@geekmidas/client 0.0.1 → 0.1.0

package/src/__tests__/infer.integration.spec.ts

@@ -0,0 +1,188 @@
+import { e } from '@geekmidas/constructs/endpoints';
+import { describe, expectTypeOf, it } from 'vitest';
+import { z } from 'zod';
+import type { InferOpenApi } from '../infer';
+
+describe('InferOpenApi - TypedFetcher Integration', () => {
+  it('should generate paths structure compatible with TypedFetcher', () => {
+    // Define some endpoints
+    const getUserEndpoint = e
+      .get('/users/{id}')
+      .params(z.object({ id: z.string() }))
+      .output(z.object({ id: z.string(), name: z.string(), email: z.string() }))
+      .handle(async ({ params }) => ({
+        id: params.id,
+        name: 'John Doe',
+        email: 'john@example.com',
+      }));
+
+    const createUserEndpoint = e
+      .post('/users')
+      .body(z.object({ name: z.string(), email: z.string() }))
+      .output(z.object({ id: z.string(), name: z.string(), email: z.string() }))
+      .handle(async ({ body }) => ({
+        id: '123',
+        name: body.name,
+        email: body.email,
+      }));
+
+    const listUsersEndpoint = e
+      .get('/users')
+      .query(z.object({ page: z.coerce.number().optional() }))
+      .output(
+        z.object({
+          users: z.array(
+            z.object({ id: z.string(), name: z.string(), email: z.string() }),
+          ),
+        }),
+      )
+      .handle(async ({ query }) => ({
+        users: [],
+      }));
+
+    // Infer paths from endpoints
+    const endpoints = [
+      getUserEndpoint,
+      createUserEndpoint,
+      listUsersEndpoint,
+    ] as const;
+    type Paths = InferOpenApi<typeof endpoints>['paths'];
+
+    // Verify the structure matches TypedFetcher expectations
+    expectTypeOf<Paths>().toMatchTypeOf<{
+      '/users/{id}': {
+        get: {
+          parameters: {
+            path: { id: string };
+          };
+          responses: {
+            200: {
+              content: {
+                'application/json': {
+                  id: string;
+                  name: string;
+                  email: string;
+                };
+              };
+            };
+          };
+        };
+      };
+      '/users': {
+        get: {
+          parameters: {
+            query: { page?: number };
+          };
+          responses: {
+            200: {
+              content: {
+                'application/json': {
+                  users: Array<{ id: string; name: string; email: string }>;
+                };
+              };
+            };
+          };
+        };
+        post: {
+          requestBody: {
+            content: {
+              'application/json': {
+                name: string;
+                email: string;
+              };
+            };
+          };
+          responses: {
+            200: {
+              content: {
+                'application/json': {
+                  id: string;
+                  name: string;
+                  email: string;
+                };
+              };
+            };
+          };
+        };
+      };
+    }>();
+  });
+
+  it('should handle endpoints with multiple parameter types', () => {
+    const updateUserEndpoint = e
+      .put('/users/{id}')
+      .params(z.object({ id: z.string() }))
+      .query(z.object({ notify: z.coerce.boolean().optional() }))
+      .body(z.object({ name: z.string() }))
+      .output(z.object({ id: z.string(), name: z.string() }))
+      .handle(async ({ params, query, body }) => ({
+        id: params.id,
+        name: body.name,
+      }));
+
+    type Paths = InferOpenApi<[typeof updateUserEndpoint]>['paths'];
+
+    // Verify all parameter types are present
+    expectTypeOf<Paths>().toMatchTypeOf<{
+      '/users/{id}': {
+        parameters: {
+          path: { id: string };
+          query: { notify?: boolean };
+        };
+        put: {
+          parameters: {
+            path: { id: string };
+            query: { notify?: boolean };
+          };
+          requestBody: {
+            content: {
+              'application/json': {
+                name: string;
+              };
+            };
+          };
+          responses: {
+            200: {
+              content: {
+                'application/json': {
+                  id: string;
+                  name: string;
+                };
+              };
+            };
+          };
+        };
+      };
+    }>();
+  });
+
+  it('should handle endpoints without output schema', () => {
+    const deleteUserEndpoint = e
+      .delete('/users/{id}')
+      .params(z.object({ id: z.string() }))
+      .handle(async ({ params }) => {
+        // No return value
+      });
+
+    type Paths = InferOpenApi<[typeof deleteUserEndpoint]>['paths'];
+
+    // Verify response content is never when no output schema
+    expectTypeOf<Paths>().toMatchTypeOf<{
+      '/users/{id}': {
+        parameters: {
+          path: { id: string };
+        };
+        delete: {
+          parameters: {
+            path: { id: string };
+          };
+          responses: {
+            200: {
+              content: never;
+            };
+          };
+        };
+      };
+    }>();
+  });
+});

package/src/__tests__/infer.spec.ts

@@ -0,0 +1,189 @@
+import { e } from '@geekmidas/constructs/endpoints';
+import { describe, expectTypeOf, it } from 'vitest';
+import { z } from 'zod';
+import type { InferOpenApi, InferOpenApiFromEndpoint } from '../infer';
+
+describe('InferOpenApi', () => {
+  describe('single endpoint', () => {
+    it('should infer OpenAPI structure for GET endpoint', () => {
+      const endpoint = e
+        .get('/users/{id}')
+        .params(z.object({ id: z.string() }))
+        .output(z.object({ id: z.string(), name: z.string() }))
+        .handle(async ({ params }) => ({
+          id: params.id,
+          name: 'John',
+        }));
+
+      type API = InferOpenApiFromEndpoint<typeof endpoint>;
+
+      expectTypeOf<API>().toMatchTypeOf<{
+        paths: {
+          '/users/{id}': {
+            get: {
+              responses: {
+                '200': {
+                  description: string;
+                };
+              };
+            };
+          };
+        };
+      }>();
+    });
+
+    it('should infer OpenAPI structure for POST endpoint with body', () => {
+      const endpoint = e
+        .post('/users')
+        .body(z.object({ name: z.string(), email: z.string() }))
+        .output(z.object({ id: z.string(), name: z.string() }))
+        .handle(async ({ body }) => ({
+          id: '123',
+          name: body.name,
+        }));
+
+      type API = InferOpenApiFromEndpoint<typeof endpoint>;
+
+      expectTypeOf<API>().toMatchTypeOf<{
+        paths: {
+          '/users': {
+            post: {
+              responses: {
+                '200': {
+                  description: string;
+                };
+              };
+            };
+          };
+        };
+      }>();
+    });
+  });
+
+  describe('multiple endpoints', () => {
+    it('should merge OpenAPI specs from multiple endpoints', () => {
+      const getUserEndpoint = e
+        .get('/users/{id}')
+        .params(z.object({ id: z.string() }))
+        .output(z.object({ id: z.string(), name: z.string() }))
+        .handle(async ({ params }) => ({
+          id: params.id,
+          name: 'John',
+        }));
+
+      const createUserEndpoint = e
+        .post('/users')
+        .body(z.object({ name: z.string() }))
+        .output(z.object({ id: z.string(), name: z.string() }))
+        .handle(async ({ body }) => ({
+          id: '123',
+          name: body.name,
+        }));
+
+      const endpoints = [getUserEndpoint, createUserEndpoint] as const;
+
+      type API = InferOpenApi<typeof endpoints>;
+
+      // Should have both paths
+      expectTypeOf<API>().toMatchTypeOf<{
+        paths: {
+          '/users/{id}': {
+            get: unknown;
+          };
+          '/users': {
+            post: unknown;
+          };
+        };
+      }>();
+    });
+
+    it('should handle endpoints with different HTTP methods on same path', () => {
+      const getUserEndpoint = e
+        .get('/users')
+        .output(z.object({ users: z.array(z.object({ id: z.string() })) }))
+        .handle(async () => ({
+          users: [],
+        }));
+
+      const createUserEndpoint = e
+        .post('/users')
+        .body(z.object({ name: z.string() }))
+        .output(z.object({ id: z.string() }))
+        .handle(async ({ body }) => ({
+          id: '123',
+        }));
+
+      const endpoints = [getUserEndpoint, createUserEndpoint] as const;
+
+      type API = InferOpenApi<typeof endpoints>;
+
+      // Should have both methods on same path
+      expectTypeOf<API>().toMatchTypeOf<{
+        paths: {
+          '/users': {
+            get: unknown;
+            post: unknown;
+          };
+        };
+      }>();
+    });
+  });
+
+  describe('complex schemas', () => {
+    it('should handle endpoints with query parameters', () => {
+      const endpoint = e
+        .get('/users')
+        .query(
+          z.object({
+            page: z.coerce.number().optional(),
+            limit: z.coerce.number().optional(),
+          }),
+        )
+        .output(z.object({ users: z.array(z.object({ id: z.string() })) }))
+        .handle(async ({ query }) => ({
+          users: [],
+        }));
+
+      type API = InferOpenApiFromEndpoint<typeof endpoint>;
+
+      expectTypeOf<API>().toMatchTypeOf<{
+        paths: {
+          '/users': {
+            get: {
+              responses: {
+                '200': unknown;
+              };
+            };
+          };
+        };
+      }>();
+    });
+
+    it('should handle endpoints with body, params, and query', () => {
+      const endpoint = e
+        .put('/users/{id}')
+        .params(z.object({ id: z.string() }))
+        .query(z.object({ notify: z.coerce.boolean().optional() }))
+        .body(z.object({ name: z.string() }))
+        .output(z.object({ id: z.string(), name: z.string() }))
+        .handle(async ({ params, body }) => ({
+          id: params.id,
+          name: body.name,
+        }));
+
+      type API = InferOpenApiFromEndpoint<typeof endpoint>;
+
+      expectTypeOf<API>().toMatchTypeOf<{
+        paths: {
+          '/users/{id}': {
+            put: {
+              responses: {
+                '200': unknown;
+              };
+            };
+          };
+        };
+      }>();
+    });
+  });
+});

package/src/auth-fetcher.ts

@@ -0,0 +1,288 @@
+import { TypedFetcher } from './fetcher';
+import type {
+  ExtractEndpointResponse,
+  FetcherOptions,
+  FilteredRequestConfig,
+  TypedApiFunction,
+  TypedEndpoint,
+} 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) {
+        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 {};
+    }
+
+    case 'none':
+    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];