feat(stac-api): accept callable options resolved at call time

[alukach]

What I'm changing

The PR enables dynamic options to accompany requests to a STAC API. My current use case is to pass in a callable options parameter that fetches the latest authorization header (developmentseed/stac-manager#71), which allows us to maintain the same STAC API instance while the underlying auth token is refreshed within my application.

How I did it

StacApiProvider/useStacApi/StacApi now accept options as either the existing static GenericObject (backward compatible) or a function of type OptionsGetter invoked per request. The function form lets consumers rotate values (auth headers, custom headers, signal, etc.) without rebuilding the StacApi instance and re-firing the landing-page probe.

Internally, useStacApi ref-stabilizes whatever options form was passed and excludes it from the react-query queryKey, so identity changes across renders no longer cause client rebuilds. Static options no longer need to be memoized.

Note

It wasn't really clear to me why options were ever part of the queryKey. It's worth considering if they need to be there for any reason that I'm not seeing.

The constructor signature stays positional (baseUrl, searchMode, options?) — the only change to the existing API surface is widening the options type to GenericObject | OptionsGetter.

[alukach]

/cc @pantierra

[danielfdsilva]

I think I'm not fully grasping the goal here. Passing a callable options that gets executed every time seem excessive.
I agree that the options shouldn't be part of the query key (unless anything there may affect the response, but I don't think it is the case).

IMO it would make more sense for the query to return the search mode and url and the stac api be constructed outside. Then if the options change the stac api is updated and there's no need of a new request. Am I missing something really big here?

Something like:

function useStacApi(url: string, options?: GenericObject): StacApiHook {
  const { data, isSuccess, isLoading, isError } = useQuery({
    queryKey: generateStacApiQueryKey(url),
    queryFn: async () => {
      const response = await fetch(url, {
        headers: {
          ...options?.headers,
        },
      });
      const stacData = await handleStacResponse<{ links?: Link[] }>(response);

      const doesPost = stacData.links?.find(
        ({ rel, method }: Link) => rel === 'search' && method === 'POST'
      );

      return {
        mode: doesPost ? SearchMode.POST : SearchMode.GET,
        url: response.url
      }
    },
    staleTime: Infinity,
  });


  return useMemo(() => {
    if (isSuccess) {
      return {
        stacApi: new StacApi(data.url, data.mode, options),
        isLoading,
        isError
      }
    }
    
    return {
      stacApi: undefined,
      isLoading,
      isError
    }

  }, [data, isSuccess, isLoading, isError, options])
}

If the headers change the query won't run again. We need to make sure that's ok.

[alukach]

@danielfdsilva Good suggestion. Closing in favor of #57