@geekmidas/client 0.0.1 → 0.1.1

package/README.md

@@ -31,14 +31,20 @@ pnpm add @geekmidas/client @tanstack/react-query
 // Type-safe fetcher
 import { createTypedFetcher } from '@geekmidas/client';
 
-// React Query client
+// Auth-aware fetcher with security schemes
+import { createAuthAwareFetcher } from '@geekmidas/client/auth-fetcher';
+
+// React Query hooks (endpoint-string based)
+import { createEndpointHooks } from '@geekmidas/client/endpoint-hooks';
+
+// React Query client (class-based)
 import { createTypedQueryClient } from '@geekmidas/client/react-query';
 
 // OpenAPI hooks generation
 import { generateReactQueryHooks } from '@geekmidas/client/openapi';
 
 // Type utilities
-import type { TypedFetcherOptions } from '@geekmidas/client/types';
+import type { TypedApiFunction, FilteredRequestConfig } from '@geekmidas/client/types';
 ```
 
 ## Quick Start
@@ -226,6 +232,151 @@ function InfiniteUsersList() {
 }
 ```
 
+## Generated API Client (Recommended)
+
+When using `@geekmidas/cli` to generate OpenAPI types, you get a fully configured `createApi` factory:
+
+```typescript
+// Generated by: gkm openapi --output ./src/api.ts
+import { createApi } from './api';
+
+// Create API client with authentication
+const api = createApi({
+  baseURL: 'https://api.example.com',
+  authStrategies: {
+    // Only strategies for schemes actually used in your API are required
+    jwt: {
+      type: 'bearer',
+      tokenProvider: async () => localStorage.getItem('token'),
+    },
+  },
+});
+
+// Imperative fetching - callable directly
+const user = await api('GET /users/{id}', { params: { id: '123' } });
+
+// React Query hooks - available as properties
+function UserProfile({ id }: { id: string }) {
+  // Config is required when endpoint has path params
+  const { data, isLoading } = api.useQuery('GET /users/{id}', {
+    params: { id }
+  });
+
+  if (isLoading) return <div>Loading...</div>;
+  return <div>{data.name}</div>;
+}
+
+// Mutations
+function CreateUser() {
+  const mutation = api.useMutation('POST /users');
+
+  return (
+    <button onClick={() => mutation.mutate({
+      body: { name: 'John', email: 'john@example.com' }
+    })}>
+      Create User
+    </button>
+  );
+}
+```
+
+### Type-Safe Config Requirements
+
+The generated client enforces config requirements at the type level:
+
+```typescript
+// ✅ GET /health - no params, no body → config optional
+await api('GET /health');
+
+// ❌ GET /users/{id} - has params → config required
+await api('GET /users/{id}'); // Type error!
+
+// ✅ GET /users/{id} - with required params
+await api('GET /users/{id}', { params: { id: '123' } });
+
+// ❌ POST /users - has body → config required
+await api('POST /users'); // Type error!
+
+// ✅ POST /users - with required body
+await api('POST /users', { body: { name: 'John', email: 'john@example.com' } });
+```
+
+### Authentication Strategies
+
+The `authStrategies` option maps security scheme IDs to authentication handlers:
+
+```typescript
+const api = createApi({
+  baseURL: 'https://api.example.com',
+  authStrategies: {
+    // Bearer token (JWT)
+    jwt: {
+      type: 'bearer',
+      tokenProvider: async () => getAccessToken(),
+    },
+
+    // API Key in header
+    apiKey: {
+      type: 'apiKey',
+      tokenProvider: async () => process.env.API_KEY,
+    },
+
+    // Custom authentication
+    custom: {
+      type: 'custom',
+      applyAuth: async (headers) => {
+        headers.set('X-Custom-Auth', await getCustomToken());
+      },
+    },
+  },
+});
+```
+
+## Auth-Aware Fetcher
+
+For manual setup without code generation, use `createAuthAwareFetcher`:
+
+```typescript
+import { createAuthAwareFetcher } from '@geekmidas/client/auth-fetcher';
+import { createEndpointHooks } from '@geekmidas/client/endpoint-hooks';
+import type { paths } from './openapi-types';
+
+// Define which endpoints use which auth
+const endpointAuth = {
+  'GET /users': 'jwt',
+  'POST /users': 'jwt',
+  'GET /health': null, // Public endpoint
+} as const;
+
+// Define security schemes
+const securitySchemes = {
+  jwt: { type: 'http', scheme: 'bearer', bearerFormat: 'JWT' },
+} as const;
+
+// Create auth-aware fetcher
+const fetcher = createAuthAwareFetcher<
+  paths,
+  typeof endpointAuth,
+  typeof securitySchemes
+>({
+  baseURL: 'https://api.example.com',
+  endpointAuth,
+  securitySchemes,
+  authStrategies: {
+    jwt: {
+      type: 'bearer',
+      tokenProvider: async () => localStorage.getItem('token'),
+    },
+  },
+});
+
+// Add React Query hooks
+const hooks = createEndpointHooks<paths>(fetcher);
+
+// Combine into single API object
+const api = Object.assign(fetcher, hooks);
+```
+
 ## OpenAPI Code Generation
 
 Generate React Query hooks from OpenAPI specifications:

package/dist/auth-fetcher.cjs

@@ -0,0 +1,78 @@
+const require_fetcher = require('./fetcher-KdwHgdAl.cjs');
+
+//#region src/auth-fetcher.ts
+/**
+* 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' } });
+* ```
+*/
+function createAuthAwareFetcher(options) {
+	const { endpointAuth, securitySchemes, authStrategies, onRequest: userOnRequest,...fetcherOptions } = options;
+	const baseFetcher = new require_fetcher.TypedFetcher({
+		...fetcherOptions,
+		onRequest: userOnRequest
+	});
+	const fetcher = async (endpoint, config) => {
+		const schemeName = endpointAuth[endpoint];
+		let authHeaders = {};
+		if (schemeName) {
+			const scheme = securitySchemes[schemeName];
+			const strategy = authStrategies[schemeName];
+			if (strategy) authHeaders = await resolveAuthHeaders(strategy, scheme);
+		}
+		const existingHeaders = config && "headers" in config && config.headers ? config.headers : {};
+		const mergedConfig = {
+			...config,
+			headers: {
+				...authHeaders,
+				...existingHeaders
+			}
+		};
+		return baseFetcher.request(endpoint, mergedConfig);
+	};
+	return fetcher;
+}
+/**
+* Resolves auth headers based on the strategy and scheme.
+*/
+async function resolveAuthHeaders(strategy, scheme) {
+	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 };
+			return {};
+		}
+		case "iam": return {};
+		case "none":
+		default: return {};
+	}
+}
+
+//#endregion
+exports.createAuthAwareFetcher = createAuthAwareFetcher;
+//# sourceMappingURL=auth-fetcher.cjs.map

package/dist/auth-fetcher.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth-fetcher.cjs","names":["options: AuthFetcherOptions<EndpointAuth, SecuritySchemes> & {\n    baseURL: string;\n  }","TypedFetcher","endpoint: T","config?: FilteredRequestConfig<Paths, T>","authHeaders: Record<string, string>","strategy: AuthStrategy","scheme: SecuritySchemeObject"],"sources":["../src/auth-fetcher.ts"],"sourcesContent":["import { TypedFetcher } from './fetcher';\nimport type {\n  ExtractEndpointResponse,\n  FetcherOptions,\n  FilteredRequestConfig,\n  TypedApiFunction,\n  TypedEndpoint,\n} from './types';\n\n/**\n * Security scheme object matching OpenAPI 3.1 specification.\n */\nexport interface SecuritySchemeObject {\n  type: 'apiKey' | 'http' | 'mutualTLS' | 'oauth2' | 'openIdConnect';\n  description?: string;\n  name?: string;\n  in?: 'query' | 'header' | 'cookie';\n  scheme?: string;\n  bearerFormat?: string;\n  flows?: Record<string, unknown>;\n  openIdConnectUrl?: string;\n  [key: string]: unknown;\n}\n\n/**\n * Extract all non-null security scheme IDs that are actually used in the API.\n * This gives us the union of scheme names that endpoints require.\n */\nexport type UsedSecuritySchemes<\n  EndpointAuth extends Record<string, string | null>,\n> = NonNullable<EndpointAuth[keyof EndpointAuth]>;\n\n/**\n * Interface for token storage and retrieval.\n * Compatible with @geekmidas/auth TokenClient.\n */\nexport interface TokenProvider {\n  /**\n   * Get a valid access token, refreshing if necessary.\n   */\n  getValidAccessToken(): Promise<string | null>;\n\n  /**\n   * Create Authorization headers from the current token.\n   */\n  createValidAuthHeaders(): Promise<Record<string, string>>;\n}\n\n/**\n * Interface for API key providers.\n */\nexport interface ApiKeyProvider {\n  /**\n   * Get the API key value.\n   */\n  getApiKey(): Promise<string> | string;\n}\n\n/**\n * Interface for AWS SigV4 request signing.\n */\nexport interface AwsSigner {\n  /**\n   * Sign a request with AWS SigV4.\n   * @param url - The request URL\n   * @param init - The request init object\n   * @returns Headers to add to the request\n   */\n  sign(url: string, init: RequestInit): Promise<Record<string, string>>;\n}\n\n/**\n * Auth strategy configuration for a specific security scheme type.\n */\nexport type AuthStrategy =\n  | { type: 'bearer'; tokenProvider: TokenProvider }\n  | { type: 'apiKey'; apiKeyProvider: ApiKeyProvider; headerName?: string }\n  | { type: 'iam'; signer: AwsSigner }\n  | { type: 'none' };\n\n/**\n * Options for creating an auth-aware fetcher.\n *\n * @template EndpointAuth - Map of endpoint strings to their auth scheme (or null for public)\n * @template SecuritySchemes - Available security scheme definitions\n */\nexport interface AuthFetcherOptions<\n  EndpointAuth extends Record<string, string | null>,\n  SecuritySchemes extends Record<string, SecuritySchemeObject>,\n> extends Omit<FetcherOptions, 'onRequest'> {\n  /**\n   * Runtime map of endpoints to their required auth scheme.\n   * Generated by `gkm openapi --ts`.\n   */\n  endpointAuth: EndpointAuth;\n\n  /**\n   * Security scheme definitions.\n   * Generated by `gkm openapi --ts`.\n   */\n  securitySchemes: SecuritySchemes;\n\n  /**\n   * Auth strategies for security schemes that are actually used.\n   * Only schemes referenced in endpointAuth are required.\n   *\n   * @example\n   * ```typescript\n   * // If endpointAuth has: { 'GET /users': 'jwt', 'POST /data': 'iam', 'GET /public': null }\n   * // Then authStrategies must include strategies for 'jwt' and 'iam'\n   * authStrategies: {\n   *   jwt: { type: 'bearer', tokenProvider },\n   *   iam: { type: 'iam', signer: awsSigner },\n   * }\n   * ```\n   */\n  authStrategies: Record<UsedSecuritySchemes<EndpointAuth>, AuthStrategy>;\n\n  /**\n   * Optional request interceptor (runs after auth headers are added).\n   */\n  onRequest?: (config: RequestInit) => RequestInit | Promise<RequestInit>;\n}\n\n/**\n * Creates an auth-aware fetcher that automatically applies the correct\n * authentication based on the endpoint being called.\n *\n * @example\n * ```typescript\n * import { endpointAuth, securitySchemes, paths } from './openapi';\n * import { TokenClient } from '@geekmidas/auth/client';\n *\n * const tokenClient = new TokenClient({ ... });\n *\n * const api = createAuthAwareFetcher<paths>({\n *   baseURL: 'https://api.example.com',\n *   endpointAuth,\n *   securitySchemes,\n *   authStrategies: {\n *     bearer: { type: 'bearer', tokenProvider: tokenClient },\n *     iam: { type: 'iam', signer: awsSigner },\n *   },\n * });\n *\n * // Bearer auth automatically applied\n * const user = await api('GET /users/{id}', { params: { id: '123' } });\n *\n * // IAM SigV4 auth automatically applied\n * const tenant = await api('POST /tenants', { body: { name: 'Acme' } });\n * ```\n */\nexport function createAuthAwareFetcher<\n  Paths,\n  EndpointAuth extends Record<string, string | null> = Record<\n    string,\n    string | null\n  >,\n  SecuritySchemes extends Record<string, SecuritySchemeObject> = Record<\n    string,\n    SecuritySchemeObject\n  >,\n>(\n  options: AuthFetcherOptions<EndpointAuth, SecuritySchemes> & {\n    baseURL: string;\n  },\n): TypedApiFunction<Paths> {\n  const {\n    endpointAuth,\n    securitySchemes,\n    authStrategies,\n    onRequest: userOnRequest,\n    ...fetcherOptions\n  } = options;\n\n  // Create base fetcher with user's onRequest if provided\n  const baseFetcher = new TypedFetcher<Paths>({\n    ...fetcherOptions,\n    onRequest: userOnRequest,\n  });\n\n  const fetcher = async <T extends TypedEndpoint<Paths>>(\n    endpoint: T,\n    config?: FilteredRequestConfig<Paths, T>,\n  ): Promise<ExtractEndpointResponse<Paths, T>> => {\n    // Look up auth requirement for this endpoint\n    const schemeName = endpointAuth[endpoint as keyof EndpointAuth] as\n      | string\n      | null;\n\n    let authHeaders: Record<string, string> = {};\n\n    if (schemeName) {\n      const scheme = securitySchemes[schemeName as keyof SecuritySchemes];\n      // Since authStrategies is now required to have all used schemes,\n      // we can safely access it - TypeScript ensures the strategy exists\n      const strategy =\n        authStrategies[schemeName as UsedSecuritySchemes<EndpointAuth>];\n\n      if (strategy) {\n        authHeaders = await resolveAuthHeaders(strategy, scheme);\n      }\n    }\n\n    // Merge auth headers with config headers\n    const existingHeaders =\n      config && 'headers' in config && config.headers\n        ? (config.headers as Record<string, string>)\n        : {};\n\n    const mergedConfig = {\n      ...config,\n      headers: {\n        ...authHeaders,\n        ...existingHeaders,\n      },\n    } as unknown as FilteredRequestConfig<Paths, T>;\n\n    return baseFetcher.request(endpoint, mergedConfig);\n  };\n\n  return fetcher as TypedApiFunction<Paths>;\n}\n\n/**\n * Resolves auth headers based on the strategy and scheme.\n */\nasync function resolveAuthHeaders(\n  strategy: AuthStrategy,\n  scheme: SecuritySchemeObject,\n): Promise<Record<string, string>> {\n  switch (strategy.type) {\n    case 'bearer': {\n      return strategy.tokenProvider.createValidAuthHeaders();\n    }\n\n    case 'apiKey': {\n      const apiKey = await strategy.apiKeyProvider.getApiKey();\n      const headerName = strategy.headerName || scheme.name || 'X-API-Key';\n\n      if (scheme.in === 'header' || !scheme.in) {\n        return { [headerName]: apiKey };\n      }\n      // Note: query and cookie API keys are handled differently\n      // For now, we only support header-based API keys\n      return {};\n    }\n\n    case 'iam': {\n      // IAM signing requires the full URL and request config\n      // This is a simplified version - full implementation would need\n      // access to the complete request\n      // For now, return empty - the actual signing should be done\n      // in a custom onRequest interceptor if needed\n      return {};\n    }\n\n    case 'none':\n    default:\n      return {};\n  }\n}\n\n/**\n * Type helper to extract the security scheme ID from an endpoint.\n */\nexport type GetEndpointAuth<\n  EndpointAuth extends Record<string, string | null>,\n  Endpoint extends keyof EndpointAuth,\n> = EndpointAuth[Endpoint];\n\n/**\n * Type helper to get all authenticated endpoints.\n */\nexport type AuthenticatedEndpoints<\n  EndpointAuth extends Record<string, string | null>,\n> = {\n  [K in keyof EndpointAuth]: EndpointAuth[K] extends null ? never : K;\n}[keyof EndpointAuth];\n\n/**\n * Type helper to get all public endpoints.\n */\nexport type PublicEndpoints<\n  EndpointAuth extends Record<string, string | null>,\n> = {\n  [K in keyof EndpointAuth]: EndpointAuth[K] extends null ? K : never;\n}[keyof EndpointAuth];\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAwJA,SAAgB,uBAWdA,SAGyB;CACzB,MAAM,EACJ,cACA,iBACA,gBACA,WAAW,cACX,GAAG,gBACJ,GAAG;CAGJ,MAAM,cAAc,IAAIC,6BAAoB;EAC1C,GAAG;EACH,WAAW;CACZ;CAED,MAAM,UAAU,OACdC,UACAC,WAC+C;EAE/C,MAAM,aAAa,aAAa;EAIhC,IAAIC,cAAsC,CAAE;AAE5C,MAAI,YAAY;GACd,MAAM,SAAS,gBAAgB;GAG/B,MAAM,WACJ,eAAe;AAEjB,OAAI,SACF,eAAc,MAAM,mBAAmB,UAAU,OAAO;EAE3D;EAGD,MAAM,kBACJ,UAAU,aAAa,UAAU,OAAO,UACnC,OAAO,UACR,CAAE;EAER,MAAM,eAAe;GACnB,GAAG;GACH,SAAS;IACP,GAAG;IACH,GAAG;GACJ;EACF;AAED,SAAO,YAAY,QAAQ,UAAU,aAAa;CACnD;AAED,QAAO;AACR;;;;AAKD,eAAe,mBACbC,UACAC,QACiC;AACjC,SAAQ,SAAS,MAAjB;EACE,KAAK,SACH,QAAO,SAAS,cAAc,wBAAwB;EAGxD,KAAK,UAAU;GACb,MAAM,SAAS,MAAM,SAAS,eAAe,WAAW;GACxD,MAAM,aAAa,SAAS,cAAc,OAAO,QAAQ;AAEzD,OAAI,OAAO,OAAO,aAAa,OAAO,GACpC,QAAO,GAAG,aAAa,OAAQ;AAIjC,UAAO,CAAE;EACV;EAED,KAAK,MAMH,QAAO,CAAE;EAGX,KAAK;EACL,QACE,QAAO,CAAE;CACZ;AACF"}

package/dist/auth-fetcher.d.cts

@@ -0,0 +1,157 @@
+import { FetcherOptions, TypedApiFunction } from "./types-D4OSWveN.cjs";
+
+//#region src/auth-fetcher.d.ts
+
+/**
+ * Security scheme object matching OpenAPI 3.1 specification.
+ */
+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.
+ */
+type UsedSecuritySchemes<EndpointAuth extends Record<string, string | null>> = NonNullable<EndpointAuth[keyof EndpointAuth]>;
+/**
+ * Interface for token storage and retrieval.
+ * Compatible with @geekmidas/auth TokenClient.
+ */
+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.
+ */
+interface ApiKeyProvider {
+  /**
+   * Get the API key value.
+   */
+  getApiKey(): Promise<string> | string;
+}
+/**
+ * Interface for AWS SigV4 request signing.
+ */
+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.
+ */
+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
+ */
+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' } });
+ * ```
+ */
+declare 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>;
+/**
+ * Type helper to extract the security scheme ID from an endpoint.
+ */
+type GetEndpointAuth<EndpointAuth extends Record<string, string | null>, Endpoint extends keyof EndpointAuth> = EndpointAuth[Endpoint];
+/**
+ * Type helper to get all authenticated endpoints.
+ */
+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.
+ */
+type PublicEndpoints<EndpointAuth extends Record<string, string | null>> = { [K in keyof EndpointAuth]: EndpointAuth[K] extends null ? K : never }[keyof EndpointAuth];
+//#endregion
+export { ApiKeyProvider, AuthFetcherOptions, AuthStrategy, AuthenticatedEndpoints, AwsSigner, GetEndpointAuth, PublicEndpoints, SecuritySchemeObject, TokenProvider, UsedSecuritySchemes, createAuthAwareFetcher };
+//# sourceMappingURL=auth-fetcher.d.cts.map

package/dist/auth-fetcher.d.mts

@@ -0,0 +1,157 @@
+import { FetcherOptions, TypedApiFunction } from "./types-Cdv1XAWr.mjs";
+
+//#region src/auth-fetcher.d.ts
+
+/**
+ * Security scheme object matching OpenAPI 3.1 specification.
+ */
+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.
+ */
+type UsedSecuritySchemes<EndpointAuth extends Record<string, string | null>> = NonNullable<EndpointAuth[keyof EndpointAuth]>;
+/**
+ * Interface for token storage and retrieval.
+ * Compatible with @geekmidas/auth TokenClient.
+ */
+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.
+ */
+interface ApiKeyProvider {
+  /**
+   * Get the API key value.
+   */
+  getApiKey(): Promise<string> | string;
+}
+/**
+ * Interface for AWS SigV4 request signing.
+ */
+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.
+ */
+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
+ */
+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' } });
+ * ```
+ */
+declare 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>;
+/**
+ * Type helper to extract the security scheme ID from an endpoint.
+ */
+type GetEndpointAuth<EndpointAuth extends Record<string, string | null>, Endpoint extends keyof EndpointAuth> = EndpointAuth[Endpoint];
+/**
+ * Type helper to get all authenticated endpoints.
+ */
+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.
+ */
+type PublicEndpoints<EndpointAuth extends Record<string, string | null>> = { [K in keyof EndpointAuth]: EndpointAuth[K] extends null ? K : never }[keyof EndpointAuth];
+//#endregion
+export { ApiKeyProvider, AuthFetcherOptions, AuthStrategy, AuthenticatedEndpoints, AwsSigner, GetEndpointAuth, PublicEndpoints, SecuritySchemeObject, TokenProvider, UsedSecuritySchemes, createAuthAwareFetcher };
+//# sourceMappingURL=auth-fetcher.d.mts.map

package/dist/auth-fetcher.mjs

@@ -0,0 +1,78 @@
+import { TypedFetcher } from "./fetcher-DLDD_7Sa.mjs";
+
+//#region src/auth-fetcher.ts
+/**
+* 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' } });
+* ```
+*/
+function createAuthAwareFetcher(options) {
+	const { endpointAuth, securitySchemes, authStrategies, onRequest: userOnRequest,...fetcherOptions } = options;
+	const baseFetcher = new TypedFetcher({
+		...fetcherOptions,
+		onRequest: userOnRequest
+	});
+	const fetcher = async (endpoint, config) => {
+		const schemeName = endpointAuth[endpoint];
+		let authHeaders = {};
+		if (schemeName) {
+			const scheme = securitySchemes[schemeName];
+			const strategy = authStrategies[schemeName];
+			if (strategy) authHeaders = await resolveAuthHeaders(strategy, scheme);
+		}
+		const existingHeaders = config && "headers" in config && config.headers ? config.headers : {};
+		const mergedConfig = {
+			...config,
+			headers: {
+				...authHeaders,
+				...existingHeaders
+			}
+		};
+		return baseFetcher.request(endpoint, mergedConfig);
+	};
+	return fetcher;
+}
+/**
+* Resolves auth headers based on the strategy and scheme.
+*/
+async function resolveAuthHeaders(strategy, scheme) {
+	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 };
+			return {};
+		}
+		case "iam": return {};
+		case "none":
+		default: return {};
+	}
+}
+
+//#endregion
+export { createAuthAwareFetcher };
+//# sourceMappingURL=auth-fetcher.mjs.map