@xemahq/api-client-generator 0.1.3 → 0.1.4

package/dist/lib/custom-fetch-template.d.ts

@@ -1,2 +1,2 @@
-export declare const CANONICAL_CUSTOM_FETCH = "/**\n * Configurable fetch wrapper for Orval-generated clients.\n *\n * Consumers must call `configureClient()` before using any endpoint function.\n * The baseUrl is prepended to the relative paths generated by Orval.\n */\n\nexport interface ClientConfig {\n  /** Static base URL (e.g. 'http://localhost:3140') \u2014 no trailing slash. */\n  baseUrl?: string;\n  /** Per-request base-URL resolver (service-registry-safe). */\n  baseUrlResolver?: () => string | Promise<string>;\n  /** Optional async callback to get an auth token. */\n  getAuthToken?: () => Promise<string>;\n  /** Optional callback returning headers to inject on every request. */\n  getHeaders?: () => Record<string, string> | Promise<Record<string, string>>;\n  /** Optional callback invoked on 401 before a single retry. */\n  onUnauthorized?: () => Promise<void>;\n  /** Maximum retry attempts for transient failures (default: 3). */\n  maxRetries?: number;\n}\n\nexport class ClientError extends Error {\n  constructor(\n    public readonly status: number,\n    public readonly url: string,\n    public readonly body: unknown,\n  ) {\n    super(`HTTP ${status} from ${url}`);\n    this.name = 'ClientError';\n  }\n}\n\nlet clientConfig: ClientConfig | null = null;\n\nexport function configureClient(config: ClientConfig): void {\n  clientConfig = config;\n}\n\nexport function getClientConfig(): ClientConfig {\n  if (!clientConfig) {\n    throw new Error(\n      'Client not configured. Call configureClient({ baseUrl }) before using endpoint functions.',\n    );\n  }\n  return clientConfig;\n}\n\nconst RETRYABLE_STATUSES = [429, 502, 503, 504];\n\nasync function buildHeaders(\n  config: ClientConfig,\n  callerHeaders: RequestInit['headers'],\n): Promise<Headers> {\n  const headers = new Headers(callerHeaders);\n  if (config.getHeaders) {\n    const globalHeaders = await Promise.resolve(config.getHeaders());\n    for (const [key, value] of Object.entries(globalHeaders)) {\n      if (!headers.has(key)) {\n        headers.set(key, value);\n      }\n    }\n  }\n  if (config.getAuthToken && !headers.has('Authorization')) {\n    const token = await config.getAuthToken();\n    headers.set('Authorization', `Bearer ${token}`);\n  }\n  return headers;\n}\n\nexport const customFetch = async <T>(\n  url: string,\n  options: RequestInit,\n): Promise<T> => {\n  const config = getClientConfig();\n  const base = config.baseUrlResolver\n    ? await config.baseUrlResolver()\n    : config.baseUrl;\n  if (base === undefined) {\n    throw new Error(\n      'Client not configured: set baseUrl or baseUrlResolver via configureClient().',\n    );\n  }\n  const fullUrl = `${base}${url}`;\n  const maxRetries = config.maxRetries ?? 3;\n\n  const headers = await buildHeaders(config, options.headers);\n  const requestInit: RequestInit = { ...options, headers };\n\n  let delay = 1000;\n  let lastError: Error | undefined;\n\n  for (let attempt = 0; attempt <= maxRetries; attempt++) {\n    try {\n      const response = await fetch(fullUrl, requestInit);\n\n      if (response.status === 401 && config.onUnauthorized && attempt === 0) {\n        await config.onUnauthorized();\n        const refreshedHeaders = await buildHeaders(config, options.headers);\n        const retryResponse = await fetch(fullUrl, { ...options, headers: refreshedHeaders });\n        const retryBody = await parseBody(retryResponse);\n        if (retryResponse.status >= 400) {\n          throw new ClientError(retryResponse.status, fullUrl, retryBody);\n        }\n        return retryBody as T;\n      }\n\n      if (!RETRYABLE_STATUSES.includes(response.status) || attempt >= maxRetries) {\n        const body = await parseBody(response);\n        if (response.status >= 400) {\n          throw new ClientError(response.status, fullUrl, body);\n        }\n        return body as T;\n      }\n\n      const retryAfter = parseRetryAfter(response.headers.get('Retry-After'));\n      const waitMs = retryAfter ?? addJitter(delay);\n      await sleep(waitMs);\n      delay = Math.min(delay * 2, 30_000);\n    } catch (error) {\n      if (error instanceof ClientError) throw error;\n      lastError = error instanceof Error ? error : new Error(String(error));\n      if (attempt >= maxRetries) throw lastError;\n      const waitMs = addJitter(delay);\n      await sleep(waitMs);\n      delay = Math.min(delay * 2, 30_000);\n    }\n  }\n\n  throw lastError ?? new Error(`All retries exhausted for ${fullUrl}`);\n};\n\nasync function parseBody(response: Response): Promise<unknown> {\n  const contentType = response.headers.get('content-type');\n  if (contentType?.includes('application/json')) {\n    return response.json();\n  }\n  if (response.status === 204) {\n    return undefined;\n  }\n  return response.text();\n}\n\nfunction parseRetryAfter(value: string | null): number | undefined {\n  if (!value) return undefined;\n  const seconds = Number(value);\n  if (!isNaN(seconds) && seconds >= 0) return seconds * 1000;\n  const date = new Date(value);\n  if (!isNaN(date.getTime())) return Math.max(0, date.getTime() - Date.now());\n  return undefined;\n}\n\nfunction addJitter(delay: number): number {\n  return delay + (Math.random() * 2 - 1) * delay * 0.25;\n}\n\nfunction sleep(ms: number): Promise<void> {\n  return new Promise(resolve => setTimeout(resolve, ms));\n}\n\nexport default customFetch;\n";
+export declare const CANONICAL_CUSTOM_FETCH = "/**\n * Configurable fetch wrapper for Orval-generated clients.\n *\n * Consumers must call `configureClient()` before using any endpoint function.\n * The baseUrl is prepended to the relative paths generated by Orval.\n */\n\nexport interface ClientConfig {\n  /** Static base URL (e.g. 'http://localhost:3140') \u2014 no trailing slash. */\n  baseUrl?: string;\n  /** Per-request base-URL resolver (service-registry-safe). */\n  baseUrlResolver?: () => string | Promise<string>;\n  /** Optional async callback to get an auth token. */\n  getAuthToken?: () => Promise<string>;\n  /** Optional callback returning headers to inject on every request. */\n  getHeaders?: () => Record<string, string> | Promise<Record<string, string>>;\n  /** Optional callback invoked on 401 before a single retry. */\n  onUnauthorized?: () => Promise<void>;\n  /** Maximum retry attempts for transient failures (default: 3). */\n  maxRetries?: number;\n}\n\nexport class ClientError extends Error {\n  constructor(\n    public readonly status: number,\n    public readonly url: string,\n    public readonly body: unknown,\n  ) {\n    super(`HTTP ${status} from ${url}`);\n    this.name = 'ClientError';\n  }\n}\n\nlet clientConfig: ClientConfig | null = null;\n\nexport function configureClient(config: ClientConfig): void {\n  clientConfig = config;\n}\n\nexport function getClientConfig(): ClientConfig {\n  if (!clientConfig) {\n    throw new Error(\n      'Client not configured. Call configureClient({ baseUrl }) before using endpoint functions.',\n    );\n  }\n  return clientConfig;\n}\n\nconst RETRYABLE_STATUSES = [429, 502, 503, 504];\n\nasync function buildHeaders(\n  config: ClientConfig,\n  callerHeaders: RequestInit['headers'],\n): Promise<Headers> {\n  const headers = new Headers(callerHeaders);\n  if (config.getHeaders) {\n    const globalHeaders = await Promise.resolve(config.getHeaders());\n    for (const [key, value] of Object.entries(globalHeaders)) {\n      if (!headers.has(key)) {\n        headers.set(key, value);\n      }\n    }\n  }\n  if (config.getAuthToken && !headers.has('Authorization')) {\n    const token = await config.getAuthToken();\n    headers.set('Authorization', `Bearer ${token}`);\n  }\n  return headers;\n}\n\nexport const customFetch = async <T>(\n  url: string,\n  options: RequestInit,\n): Promise<T> => {\n  const config = getClientConfig();\n  const base = config.baseUrlResolver\n    ? await config.baseUrlResolver()\n    : config.baseUrl;\n  if (base === undefined) {\n    throw new Error(\n      'Client not configured: set baseUrl or baseUrlResolver via configureClient().',\n    );\n  }\n  const fullUrl = `${base}${url}`;\n  const maxRetries = config.maxRetries ?? 3;\n\n  const headers = await buildHeaders(config, options.headers);\n  const requestInit: RequestInit = { ...options, headers };\n\n  let delay = 1000;\n  let lastError: Error | undefined;\n\n  for (let attempt = 0; attempt <= maxRetries; attempt++) {\n    try {\n      const response = await fetch(fullUrl, requestInit);\n\n      if (response.status === 401 && config.onUnauthorized && attempt === 0) {\n        await config.onUnauthorized();\n        const refreshedHeaders = await buildHeaders(config, options.headers);\n        const retryResponse = await fetch(fullUrl, { ...options, headers: refreshedHeaders });\n        const retryBody = await parseBody(retryResponse);\n        if (retryResponse.status >= 400) {\n          throw new ClientError(retryResponse.status, fullUrl, retryBody);\n        }\n        return unwrapEnvelope(retryBody) as T;\n      }\n\n      if (!RETRYABLE_STATUSES.includes(response.status) || attempt >= maxRetries) {\n        const body = await parseBody(response);\n        if (response.status >= 400) {\n          throw new ClientError(response.status, fullUrl, body);\n        }\n        return unwrapEnvelope(body) as T;\n      }\n\n      const retryAfter = parseRetryAfter(response.headers.get('Retry-After'));\n      const waitMs = retryAfter ?? addJitter(delay);\n      await sleep(waitMs);\n      delay = Math.min(delay * 2, 30_000);\n    } catch (error) {\n      if (error instanceof ClientError) throw error;\n      lastError = error instanceof Error ? error : new Error(String(error));\n      if (attempt >= maxRetries) throw lastError;\n      const waitMs = addJitter(delay);\n      await sleep(waitMs);\n      delay = Math.min(delay * 2, 30_000);\n    }\n  }\n\n  throw lastError ?? new Error(`All retries exhausted for ${fullUrl}`);\n};\n\n/**\n * Xema platform services wrap every 2xx payload in a { data: T } envelope via\n * the global ResponseEnvelopeInterceptor (platform-common). Generated types\n * describe the INNER T (controllers declare their return type as T, not\n * { data: T }), so the client must peel data to keep the static types and the\n * wire shape consistent \u2014 otherwise consumers read fields off the envelope and\n * get undefined.\n *\n * Only 2xx bodies reach this helper: non-2xx responses are surfaced as a thrown\n * ClientError before unwrap, and error envelopes are emitted by the\n * GlobalExceptionFilter, never wrapped in { data }. Paginated lists arrive as\n * { data: T[], pagination: {...} }; consumers read both fields, so that envelope\n * is kept intact (detected by the presence of pagination). Any body without a\n * top-level data field is returned as-is.\n */\nfunction unwrapEnvelope(body: unknown): unknown {\n  if (\n    body === null ||\n    typeof body !== 'object' ||\n    Array.isArray(body) ||\n    !('data' in body)\n  ) {\n    return body;\n  }\n  const envelope = body as { data: unknown; pagination?: unknown };\n  if ('pagination' in envelope) {\n    return envelope;\n  }\n  return envelope.data;\n}\n\nasync function parseBody(response: Response): Promise<unknown> {\n  const contentType = response.headers.get('content-type');\n  if (contentType?.includes('application/json')) {\n    return response.json();\n  }\n  if (response.status === 204) {\n    return undefined;\n  }\n  return response.text();\n}\n\nfunction parseRetryAfter(value: string | null): number | undefined {\n  if (!value) return undefined;\n  const seconds = Number(value);\n  if (!isNaN(seconds) && seconds >= 0) return seconds * 1000;\n  const date = new Date(value);\n  if (!isNaN(date.getTime())) return Math.max(0, date.getTime() - Date.now());\n  return undefined;\n}\n\nfunction addJitter(delay: number): number {\n  return delay + (Math.random() * 2 - 1) * delay * 0.25;\n}\n\nfunction sleep(ms: number): Promise<void> {\n  return new Promise(resolve => setTimeout(resolve, ms));\n}\n\nexport default customFetch;\n";
 //# sourceMappingURL=custom-fetch-template.d.ts.map

package/dist/lib/custom-fetch-template.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"custom-fetch-template.d.ts","sourceRoot":"","sources":["../../src/lib/custom-fetch-template.ts"],"names":[],"mappings":"AAOA,eAAO,MAAM,sBAAsB,mvKAiKlC,CAAC"}
+{"version":3,"file":"custom-fetch-template.d.ts","sourceRoot":"","sources":["../../src/lib/custom-fetch-template.ts"],"names":[],"mappings":"AAOA,eAAO,MAAM,sBAAsB,69MAgMlC,CAAC"}

package/dist/lib/custom-fetch-template.js

@@ -105,7 +105,7 @@ export const customFetch = async <T>(
         if (retryResponse.status >= 400) {
           throw new ClientError(retryResponse.status, fullUrl, retryBody);
         }
-        return retryBody as T;
+        return unwrapEnvelope(retryBody) as T;
       }
 
       if (!RETRYABLE_STATUSES.includes(response.status) || attempt >= maxRetries) {
@@ -113,7 +113,7 @@ export const customFetch = async <T>(
         if (response.status >= 400) {
           throw new ClientError(response.status, fullUrl, body);
         }
-        return body as T;
+        return unwrapEnvelope(body) as T;
       }
 
       const retryAfter = parseRetryAfter(response.headers.get('Retry-After'));
@@ -133,6 +133,37 @@ export const customFetch = async <T>(
   throw lastError ?? new Error(\`All retries exhausted for \${fullUrl}\`);
 };
 
+/**
+ * Xema platform services wrap every 2xx payload in a { data: T } envelope via
+ * the global ResponseEnvelopeInterceptor (platform-common). Generated types
+ * describe the INNER T (controllers declare their return type as T, not
+ * { data: T }), so the client must peel data to keep the static types and the
+ * wire shape consistent — otherwise consumers read fields off the envelope and
+ * get undefined.
+ *
+ * Only 2xx bodies reach this helper: non-2xx responses are surfaced as a thrown
+ * ClientError before unwrap, and error envelopes are emitted by the
+ * GlobalExceptionFilter, never wrapped in { data }. Paginated lists arrive as
+ * { data: T[], pagination: {...} }; consumers read both fields, so that envelope
+ * is kept intact (detected by the presence of pagination). Any body without a
+ * top-level data field is returned as-is.
+ */
+function unwrapEnvelope(body: unknown): unknown {
+  if (
+    body === null ||
+    typeof body !== 'object' ||
+    Array.isArray(body) ||
+    !('data' in body)
+  ) {
+    return body;
+  }
+  const envelope = body as { data: unknown; pagination?: unknown };
+  if ('pagination' in envelope) {
+    return envelope;
+  }
+  return envelope.data;
+}
+
 async function parseBody(response: Response): Promise<unknown> {
   const contentType = response.headers.get('content-type');
   if (contentType?.includes('application/json')) {

package/dist/lib/custom-fetch-template.js.map

@@ -1 +1 @@
-{"version":3,"file":"custom-fetch-template.js","sourceRoot":"","sources":["../../src/lib/custom-fetch-template.ts"],"names":[],"mappings":";;;AAOa,QAAA,sBAAsB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAiKrC,CAAC"}
+{"version":3,"file":"custom-fetch-template.js","sourceRoot":"","sources":["../../src/lib/custom-fetch-template.ts"],"names":[],"mappings":";;;AAOa,QAAA,sBAAsB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAgMrC,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xemahq/api-client-generator",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "Layer 1 — the single, central OpenAPI + ORVAL client generator for every Xema NestJS service. Replaces the per-service orval.config.ts / scripts/extract-openapi.ts / scripts/build-client-index.js trio with two bins (xema-openapi, xema-client-generate). Extracts one OpenAPI document per ApiSurface (public/internal/operator) using the @XemaApiSurface decorator metadata, generates one ORVAL client package per non-empty surface (all sharing the owning service's version), and stamps deterministic `xema` provenance metadata into each generated client package.json. No heuristics: a route ships in a surface only if it (or its controller) is explicitly classified.",
   "keywords": [
     "xema",
@@ -54,7 +54,7 @@
     "prettier": "3.6.2",
     "reflect-metadata": "0.2.2",
     "typescript": "5.9.3",
-    "@xemahq/xema-decorators": "0.2.0"
+    "@xemahq/xema-decorators": "0.2.2"
   },
   "exports": {
     ".": {