@geekmidas/client 9.0.2 → 10.0.0-alpha.0

package/src/auth-fetcher.ts

@@ -1,288 +0,0 @@
-import { TypedFetcher } from './fetcher';
-import type {
-	ExtractEndpointResponse,
-	FetcherOptions,
-	FilteredRequestConfig,
-	TypedApiFunction,
-	TypedEndpoint,
-} from './types';
-
-export type { FetcherOptions } from './types';
-
-/**
- * Security scheme object matching OpenAPI 3.1 specification.
- */
-export interface SecuritySchemeObject {
-	type: 'apiKey' | 'http' | 'mutualTLS' | 'oauth2' | 'openIdConnect';
-	description?: string;
-	name?: string;
-	in?: 'query' | 'header' | 'cookie';
-	scheme?: string;
-	bearerFormat?: string;
-	flows?: Record<string, unknown>;
-	openIdConnectUrl?: string;
-	[key: string]: unknown;
-}
-
-/**
- * Extract all non-null security scheme IDs that are actually used in the API.
- * This gives us the union of scheme names that endpoints require.
- */
-export type UsedSecuritySchemes<
-	EndpointAuth extends Record<string, string | null>,
-> = NonNullable<EndpointAuth[keyof EndpointAuth]>;
-
-/**
- * Interface for token storage and retrieval.
- * Compatible with @geekmidas/auth TokenClient.
- */
-export interface TokenProvider {
-	/**
-	 * Get a valid access token, refreshing if necessary.
-	 */
-	getValidAccessToken(): Promise<string | null>;
-
-	/**
-	 * Create Authorization headers from the current token.
-	 */
-	createValidAuthHeaders(): Promise<Record<string, string>>;
-}
-
-/**
- * Interface for API key providers.
- */
-export interface ApiKeyProvider {
-	/**
-	 * Get the API key value.
-	 */
-	getApiKey(): Promise<string> | string;
-}
-
-/**
- * Interface for AWS SigV4 request signing.
- */
-export interface AwsSigner {
-	/**
-	 * Sign a request with AWS SigV4.
-	 * @param url - The request URL
-	 * @param init - The request init object
-	 * @returns Headers to add to the request
-	 */
-	sign(url: string, init: RequestInit): Promise<Record<string, string>>;
-}
-
-/**
- * Auth strategy configuration for a specific security scheme type.
- */
-export type AuthStrategy =
-	| { type: 'bearer'; tokenProvider: TokenProvider }
-	| { type: 'apiKey'; apiKeyProvider: ApiKeyProvider; headerName?: string }
-	| { type: 'iam'; signer: AwsSigner }
-	| { type: 'none' };
-
-/**
- * Options for creating an auth-aware fetcher.
- *
- * @template EndpointAuth - Map of endpoint strings to their auth scheme (or null for public)
- * @template SecuritySchemes - Available security scheme definitions
- */
-export interface AuthFetcherOptions<
-	EndpointAuth extends Record<string, string | null>,
-	SecuritySchemes extends Record<string, SecuritySchemeObject>,
-> extends Omit<FetcherOptions, 'onRequest'> {
-	/**
-	 * Runtime map of endpoints to their required auth scheme.
-	 * Generated by `gkm openapi --ts`.
-	 */
-	endpointAuth: EndpointAuth;
-
-	/**
-	 * Security scheme definitions.
-	 * Generated by `gkm openapi --ts`.
-	 */
-	securitySchemes: SecuritySchemes;
-
-	/**
-	 * Auth strategies for security schemes that are actually used.
-	 * Only schemes referenced in endpointAuth are required.
-	 *
-	 * @example
-	 * ```typescript
-	 * // If endpointAuth has: { 'GET /users': 'jwt', 'POST /data': 'iam', 'GET /public': null }
-	 * // Then authStrategies must include strategies for 'jwt' and 'iam'
-	 * authStrategies: {
-	 *   jwt: { type: 'bearer', tokenProvider },
-	 *   iam: { type: 'iam', signer: awsSigner },
-	 * }
-	 * ```
-	 */
-	authStrategies: Record<UsedSecuritySchemes<EndpointAuth>, AuthStrategy>;
-
-	/**
-	 * Optional request interceptor (runs after auth headers are added).
-	 */
-	onRequest?: (config: RequestInit) => RequestInit | Promise<RequestInit>;
-}
-
-/**
- * Creates an auth-aware fetcher that automatically applies the correct
- * authentication based on the endpoint being called.
- *
- * @example
- * ```typescript
- * import { endpointAuth, securitySchemes, paths } from './openapi';
- * import { TokenClient } from '@geekmidas/auth/client';
- *
- * const tokenClient = new TokenClient({ ... });
- *
- * const api = createAuthAwareFetcher<paths>({
- *   baseURL: 'https://api.example.com',
- *   endpointAuth,
- *   securitySchemes,
- *   authStrategies: {
- *     bearer: { type: 'bearer', tokenProvider: tokenClient },
- *     iam: { type: 'iam', signer: awsSigner },
- *   },
- * });
- *
- * // Bearer auth automatically applied
- * const user = await api('GET /users/{id}', { params: { id: '123' } });
- *
- * // IAM SigV4 auth automatically applied
- * const tenant = await api('POST /tenants', { body: { name: 'Acme' } });
- * ```
- */
-export function createAuthAwareFetcher<
-	Paths,
-	EndpointAuth extends Record<string, string | null> = Record<
-		string,
-		string | null
-	>,
-	SecuritySchemes extends Record<string, SecuritySchemeObject> = Record<
-		string,
-		SecuritySchemeObject
-	>,
->(
-	options: AuthFetcherOptions<EndpointAuth, SecuritySchemes> & {
-		baseURL: string;
-	},
-): TypedApiFunction<Paths> {
-	const {
-		endpointAuth,
-		securitySchemes,
-		authStrategies,
-		onRequest: userOnRequest,
-		...fetcherOptions
-	} = options;
-
-	// Create base fetcher with user's onRequest if provided
-	const baseFetcher = new TypedFetcher<Paths>({
-		...fetcherOptions,
-		onRequest: userOnRequest,
-	});
-
-	const fetcher = async <T extends TypedEndpoint<Paths>>(
-		endpoint: T,
-		config?: FilteredRequestConfig<Paths, T>,
-	): Promise<ExtractEndpointResponse<Paths, T>> => {
-		// Look up auth requirement for this endpoint
-		const schemeName = endpointAuth[endpoint as keyof EndpointAuth] as
-			| string
-			| null;
-
-		let authHeaders: Record<string, string> = {};
-
-		if (schemeName) {
-			const scheme = securitySchemes[schemeName as keyof SecuritySchemes];
-			// Since authStrategies is now required to have all used schemes,
-			// we can safely access it - TypeScript ensures the strategy exists
-			const strategy =
-				authStrategies[schemeName as UsedSecuritySchemes<EndpointAuth>];
-
-			if (strategy && scheme) {
-				authHeaders = await resolveAuthHeaders(strategy, scheme);
-			}
-		}
-
-		// Merge auth headers with config headers
-		const existingHeaders =
-			config && 'headers' in config && config.headers
-				? (config.headers as Record<string, string>)
-				: {};
-
-		const mergedConfig = {
-			...config,
-			headers: {
-				...authHeaders,
-				...existingHeaders,
-			},
-		} as unknown as FilteredRequestConfig<Paths, T>;
-
-		return baseFetcher.request(endpoint, mergedConfig);
-	};
-
-	return fetcher as TypedApiFunction<Paths>;
-}
-
-/**
- * Resolves auth headers based on the strategy and scheme.
- */
-async function resolveAuthHeaders(
-	strategy: AuthStrategy,
-	scheme: SecuritySchemeObject,
-): Promise<Record<string, string>> {
-	switch (strategy.type) {
-		case 'bearer': {
-			return strategy.tokenProvider.createValidAuthHeaders();
-		}
-
-		case 'apiKey': {
-			const apiKey = await strategy.apiKeyProvider.getApiKey();
-			const headerName = strategy.headerName || scheme.name || 'X-API-Key';
-
-			if (scheme.in === 'header' || !scheme.in) {
-				return { [headerName]: apiKey };
-			}
-			// Note: query and cookie API keys are handled differently
-			// For now, we only support header-based API keys
-			return {};
-		}
-
-		case 'iam': {
-			// IAM signing requires the full URL and request config
-			// This is a simplified version - full implementation would need
-			// access to the complete request
-			// For now, return empty - the actual signing should be done
-			// in a custom onRequest interceptor if needed
-			return {};
-		}
-		default:
-			return {};
-	}
-}
-
-/**
- * Type helper to extract the security scheme ID from an endpoint.
- */
-export type GetEndpointAuth<
-	EndpointAuth extends Record<string, string | null>,
-	Endpoint extends keyof EndpointAuth,
-> = EndpointAuth[Endpoint];
-
-/**
- * Type helper to get all authenticated endpoints.
- */
-export type AuthenticatedEndpoints<
-	EndpointAuth extends Record<string, string | null>,
-> = {
-	[K in keyof EndpointAuth]: EndpointAuth[K] extends null ? never : K;
-}[keyof EndpointAuth];
-
-/**
- * Type helper to get all public endpoints.
- */
-export type PublicEndpoints<
-	EndpointAuth extends Record<string, string | null>,
-> = {
-	[K in keyof EndpointAuth]: EndpointAuth[K] extends null ? K : never;
-}[keyof EndpointAuth];

package/src/endpoint-hooks.ts

@@ -1,346 +0,0 @@
-import type {
-	QueryClient,
-	QueryFunctionContext,
-	UseInfiniteQueryOptions,
-	UseInfiniteQueryResult,
-	UseMutationOptions,
-	UseMutationResult,
-	UseQueryOptions,
-	UseQueryResult,
-} from '@tanstack/react-query';
-import { useInfiniteQuery, useMutation, useQuery } from '@tanstack/react-query';
-import { useMemo } from 'react';
-import type {
-	ExtractEndpointResponse,
-	FilteredRequestConfig,
-	IsConfigRequired,
-	MutationEndpoint,
-	QueryEndpoint,
-	TypedApiFunction,
-} from './types';
-
-/**
- * Build query key from endpoint and config
- */
-function buildQueryKey<Paths, T extends QueryEndpoint<Paths>>(
-	endpoint: T,
-	config?: FilteredRequestConfig<Paths, T>,
-): unknown[] {
-	const key: unknown[] = [endpoint];
-
-	if (config && 'params' in config && config.params) {
-		key.push({ params: config.params });
-	}
-
-	if (config && 'query' in config && config.query) {
-		key.push({ query: config.query });
-	}
-
-	return key;
-}
-
-/**
- * Options for creating endpoint-based hooks
- */
-export interface CreateEndpointHooksOptions {
-	queryClient?: QueryClient;
-}
-
-/**
- * Hook options type that conditionally requires config
- */
-type UseQueryArgs<Paths, T extends QueryEndpoint<Paths>> = IsConfigRequired<
-	Paths,
-	T
-> extends true
-	? [
-			config: FilteredRequestConfig<Paths, T>,
-			options?: Omit<
-				UseQueryOptions<ExtractEndpointResponse<Paths, T>, Error>,
-				'queryKey' | 'queryFn'
-			>,
-		]
-	: [
-			config?: FilteredRequestConfig<Paths, T>,
-			options?: Omit<
-				UseQueryOptions<ExtractEndpointResponse<Paths, T>, Error>,
-				'queryKey' | 'queryFn'
-			>,
-		];
-
-/**
- * Endpoint-based React Query hooks
- */
-export interface EndpointHooks<Paths> {
-	/**
-	 * Use query hook for GET endpoints.
-	 * Config is required when endpoint has path params.
-	 */
-	useQuery: <T extends QueryEndpoint<Paths>>(
-		endpoint: T,
-		...args: UseQueryArgs<Paths, T>
-	) => UseQueryResult<ExtractEndpointResponse<Paths, T>, Error>;
-
-	/**
-	 * Use mutation hook for POST, PUT, PATCH, DELETE endpoints.
-	 * Config with params/body is passed to mutate().
-	 */
-	useMutation: <T extends MutationEndpoint<Paths>>(
-		endpoint: T,
-		options?: Omit<
-			UseMutationOptions<
-				ExtractEndpointResponse<Paths, T>,
-				Error,
-				FilteredRequestConfig<Paths, T>
-			>,
-			'mutationFn'
-		>,
-	) => UseMutationResult<
-		ExtractEndpointResponse<Paths, T>,
-		Error,
-		FilteredRequestConfig<Paths, T>
-	>;
-
-	/**
-	 * Use infinite query hook for paginated GET endpoints.
-	 */
-	useInfiniteQuery: <
-		T extends QueryEndpoint<Paths>,
-		TPageData = ExtractEndpointResponse<Paths, T>,
-		TPageParam = unknown,
-	>(
-		endpoint: T,
-		options: Omit<
-			UseInfiniteQueryOptions<
-				TPageData,
-				Error,
-				{ pages: TPageData[]; pageParams: TPageParam[] },
-				unknown[],
-				TPageParam
-			>,
-			'queryKey' | 'queryFn' | 'getNextPageParam' | 'initialPageParam'
-		> & {
-			getNextPageParam: (
-				lastPage: TPageData,
-				allPages: TPageData[],
-				lastPageParam: TPageParam,
-				allPageParams: TPageParam[],
-			) => TPageParam | undefined;
-			initialPageParam: TPageParam;
-		},
-		config?: FilteredRequestConfig<Paths, T>,
-	) => UseInfiniteQueryResult<
-		{ pages: TPageData[]; pageParams: TPageParam[] },
-		Error
-	>;
-
-	/**
-	 * Invalidate queries for a specific endpoint.
-	 */
-	invalidateQueries: <T extends QueryEndpoint<Paths>>(
-		endpoint: T,
-		config?: FilteredRequestConfig<Paths, T>,
-	) => Promise<void>;
-
-	/**
-	 * Invalidate all queries in the cache.
-	 */
-	invalidateAllQueries: () => Promise<void>;
-
-	/**
-	 * Build a query key for manual cache operations
-	 */
-	buildQueryKey: <T extends QueryEndpoint<Paths>>(
-		endpoint: T,
-		config?: FilteredRequestConfig<Paths, T>,
-	) => unknown[];
-}
-
-/**
- * Create endpoint-based React Query hooks from a typed fetcher.
- *
- * @example
- * ```typescript
- * const fetcher = createAuthAwareFetcher<paths>({ ... });
- * const hooks = createEndpointHooks<paths>(fetcher);
- *
- * // In a component
- * const { data } = hooks.useQuery('GET /users/{id}', { params: { id: '123' } });
- *
- * const mutation = hooks.useMutation('POST /users');
- * await mutation.mutateAsync({ body: { name: 'John' } });
- * ```
- */
-export function createEndpointHooks<Paths>(
-	fetcher: TypedApiFunction<Paths>,
-	options: CreateEndpointHooksOptions = {},
-): EndpointHooks<Paths> {
-	return {
-		useQuery: <T extends QueryEndpoint<Paths>>(
-			endpoint: T,
-			...args: UseQueryArgs<Paths, T>
-		) => {
-			// Parse args - config is first, options is second
-			const [config, queryOptions] = args as [
-				FilteredRequestConfig<Paths, T> | undefined,
-				(
-					| Omit<
-							UseQueryOptions<ExtractEndpointResponse<Paths, T>, Error>,
-							'queryKey' | 'queryFn'
-					  >
-					| undefined
-				),
-			];
-
-			const queryKey = buildQueryKey(endpoint, config);
-
-			const memoizedOptions = useMemo(
-				() => ({
-					queryKey,
-					queryFn: () =>
-						// Type assertion needed due to complex conditional types
-						(
-							fetcher as (
-								endpoint: T,
-								config?: unknown,
-							) => Promise<ExtractEndpointResponse<Paths, T>>
-						)(endpoint, config),
-					...queryOptions,
-				}),
-				[endpoint, config, fetcher, queryKey, queryOptions],
-			);
-
-			return useQuery<ExtractEndpointResponse<Paths, T>, Error>(
-				memoizedOptions,
-			);
-		},
-
-		useMutation: <T extends MutationEndpoint<Paths>>(
-			endpoint: T,
-			mutationOptions?: Omit<
-				UseMutationOptions<
-					ExtractEndpointResponse<Paths, T>,
-					Error,
-					FilteredRequestConfig<Paths, T>
-				>,
-				'mutationFn'
-			>,
-		) => {
-			const memoizedOptions = useMemo(
-				() => ({
-					mutationFn: (config: FilteredRequestConfig<Paths, T>) =>
-						// Type assertion needed due to complex conditional types
-						(
-							fetcher as (
-								endpoint: T,
-								config?: unknown,
-							) => Promise<ExtractEndpointResponse<Paths, T>>
-						)(endpoint, config),
-					...mutationOptions,
-				}),
-				[endpoint, fetcher, mutationOptions],
-			);
-
-			return useMutation<
-				ExtractEndpointResponse<Paths, T>,
-				Error,
-				FilteredRequestConfig<Paths, T>
-			>(memoizedOptions);
-		},
-
-		useInfiniteQuery: <
-			T extends QueryEndpoint<Paths>,
-			TPageData = ExtractEndpointResponse<Paths, T>,
-			TPageParam = unknown,
-		>(
-			endpoint: T,
-			options: Omit<
-				UseInfiniteQueryOptions<
-					TPageData,
-					Error,
-					{ pages: TPageData[]; pageParams: TPageParam[] },
-					unknown[],
-					TPageParam
-				>,
-				'queryKey' | 'queryFn' | 'getNextPageParam' | 'initialPageParam'
-			> & {
-				getNextPageParam: (
-					lastPage: TPageData,
-					allPages: TPageData[],
-					lastPageParam: TPageParam,
-					allPageParams: TPageParam[],
-				) => TPageParam | undefined;
-				initialPageParam: TPageParam;
-			},
-			config?: FilteredRequestConfig<Paths, T>,
-		) => {
-			const queryKey = buildQueryKey(endpoint, config);
-
-			const memoizedOptions = useMemo(
-				() => ({
-					queryKey,
-					queryFn: ({
-						pageParam,
-					}: QueryFunctionContext<unknown[], TPageParam>) => {
-						let mergedConfig = config;
-						if (pageParam !== undefined && config) {
-							const pageQuery =
-								typeof pageParam === 'object' ? pageParam : { page: pageParam };
-							mergedConfig = {
-								...config,
-								query: { ...(config as any).query, ...pageQuery },
-							} as any;
-						} else if (pageParam !== undefined && !config) {
-							const pageQuery =
-								typeof pageParam === 'object' ? pageParam : { page: pageParam };
-							mergedConfig = { query: pageQuery } as any;
-						}
-						return (
-							fetcher as (
-								endpoint: T,
-								config?: unknown,
-							) => Promise<ExtractEndpointResponse<Paths, T>>
-						)(endpoint, mergedConfig) as Promise<TPageData>;
-					},
-					...options,
-				}),
-				[endpoint, config, fetcher, queryKey, options],
-			);
-
-			return useInfiniteQuery<
-				TPageData,
-				Error,
-				{ pages: TPageData[]; pageParams: TPageParam[] },
-				unknown[],
-				TPageParam
-			>(memoizedOptions);
-		},
-
-		invalidateQueries: <T extends QueryEndpoint<Paths>>(
-			endpoint: T,
-			config?: FilteredRequestConfig<Paths, T>,
-		) => {
-			if (!options.queryClient) {
-				throw new Error(
-					'queryClient is required for invalidateQueries. Pass it to createEndpointHooks options.',
-				);
-			}
-			const queryKey = buildQueryKey(endpoint, config);
-			return options.queryClient.invalidateQueries({
-				queryKey,
-				exact: !!config,
-			});
-		},
-
-		invalidateAllQueries: () => {
-			if (!options.queryClient) {
-				throw new Error(
-					'queryClient is required for invalidateAllQueries. Pass it to createEndpointHooks options.',
-				);
-			}
-			return options.queryClient.invalidateQueries();
-		},
-
-		buildQueryKey,
-	};
-}