@apollo-deploy/tesseract 0.1.0

package/templates/typescript/transport.hbs

@@ -0,0 +1,662 @@
+/**
+ * @generated
+ * This file was automatically generated by sdk-forge.
+ * DO NOT MODIFY THIS FILE DIRECTLY.
+ */
+
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import axios, {
+  type AxiosError,
+  type AxiosInstance,
+  type AxiosRequestConfig,
+  type AxiosResponse,
+  type InternalAxiosRequestConfig,
+} from 'axios';
+import { SDKError } from '../types/errors.js';
+import type { ApiErrorEnvelope } from '../types/common.js';
+
+// Re-export for backward compatibility
+export { SDKError } from '../types/errors.js';
+
+// ── Retry Utilities ─────────────────────────────────
+
+export interface RetryConfig {
+  /** Maximum number of retry attempts (default: 3) */
+  attempts: number;
+  /** Base backoff delay in milliseconds (default: 400) */
+  backoffMs: number;
+  /** Whether to apply jitter to the backoff delay (default: true) */
+  jitter: boolean;
+  /** Maximum backoff delay in milliseconds (default: 30000) */
+  maxBackoffMs?: number;
+  /**
+   * Custom predicate to determine if a failed request should be retried.
+   * Receives the error and the current attempt number (0-indexed).
+   * Return `true` to retry, `false` to fail immediately.
+   * When not provided, retries on network errors, timeouts, 429, and 5xx.
+   */
+  shouldRetry?: (error: SDKError, attempt: number) => boolean;
+  /**
+   * Custom function to compute the retry delay in milliseconds.
+   * Receives the error, current attempt number, and the computed default delay.
+   * When not provided, uses exponential backoff with optional jitter.
+   */
+  delay?: (error: SDKError, attempt: number, computedDelayMs: number) => number;
+  /**
+   * Called before each retry attempt. Useful for logging or metrics.
+   * Return `false` to abort retrying.
+   */
+  onRetry?: (error: SDKError, attempt: number, delayMs: number) => void | false | Promise<void | false>;
+}
+
+function calculateBackoff(attempt: number, baseMs: number, useJitter: boolean, maxMs: number): number {
+  const exponential = Math.min(baseMs * Math.pow(2, attempt), maxMs);
+  if (!useJitter) return exponential;
+  // Full jitter: uniform random between 0 and exponential cap
+  return Math.floor(Math.random() * (exponential + 1));
+}
+
+function parseRetryAfterMs(error: unknown): number | undefined {
+  if (!isAxiosError(error)) return undefined;
+
+  const rawRetryAfter = error.response?.headers?.['retry-after'];
+  if (typeof rawRetryAfter !== 'string' || rawRetryAfter.length === 0) {
+    return undefined;
+  }
+
+  // Try integer seconds first
+  const seconds = Number(rawRetryAfter);
+  if (Number.isFinite(seconds) && seconds >= 0) {
+    return Math.ceil(seconds) * 1000;
+  }
+
+  // Try HTTP-date format
+  const absoluteTime = Date.parse(rawRetryAfter);
+  if (!Number.isNaN(absoluteTime)) {
+    return Math.max(absoluteTime - Date.now(), 0);
+  }
+
+  return undefined;
+}
+
+function delay(ms: number, signal?: AbortSignal): Promise<void> {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) {
+      reject(signal.reason ?? new DOMException('Aborted', 'AbortError'));
+      return;
+    }
+    const timer = setTimeout(resolve, ms);
+    signal?.addEventListener('abort', () => {
+      clearTimeout(timer);
+      reject(signal.reason ?? new DOMException('Aborted', 'AbortError'));
+    }, { once: true });
+  });
+}
+
+// ── Plugin API ───────────────────────────────────────
+
+/**
+ * Extensibility hooks for transforming or observing every request and response.
+ * Register plugins via `TransportConfig.plugins`; they are applied in array order.
+ *
+ * @example
+ * ```ts
+ * const loggingPlugin: SDKPlugin = {
+ *   name: 'logger',
+ *   beforeRequest(config) { console.log('→', config.method, config.url); },
+ *   afterResponse(response) { console.log('←', response.status); },
+ * };
+ * const transport = createTransport({ baseUrl: '...', plugins: [loggingPlugin] });
+ * ```
+ */
+export interface SDKPlugin {
+  /** Optional plugin name for debugging and identification */
+  name?: string;
+
+  /**
+   * Called before each request is dispatched to the network.
+   * Return a modified `InternalAxiosRequestConfig` to replace it, or `void` to leave it unchanged.
+   */
+  beforeRequest?: (
+    config: InternalAxiosRequestConfig,
+  ) => InternalAxiosRequestConfig | Promise<InternalAxiosRequestConfig> | void | Promise<void>;
+
+  /**
+   * Called after a successful response is received, before data reaches the caller.
+   * Return a modified `AxiosResponse` to replace it, or `void` to leave it unchanged.
+   */
+  afterResponse?: (
+    response: AxiosResponse,
+  ) => AxiosResponse | Promise<AxiosResponse> | void | Promise<void>;
+
+  /**
+   * Called when a request fails (after retries are exhausted).
+   * Can transform the error or perform side effects like logging.
+   * Return a modified `SDKError` to replace it, or `void` to leave it unchanged.
+   */
+  onError?: (
+    error: SDKError,
+    config: AxiosRequestConfig,
+  ) => SDKError | Promise<SDKError> | void | Promise<void>;
+}
+
+// ── Transport Config ────────────────────────────────
+
+export interface TransportConfig {
+  baseUrl: string;
+{{#each securitySchemes}}
+  {{#if (eq type "apiKey")}}
+  /** API key value for the {{name}} security scheme */
+  {{configKey}}?: string;
+  {{/if}}
+  {{#if (and (eq type "http") (eq scheme "bearer"))}}
+  /** Bearer token for the {{name}} security scheme */
+  {{configKey}}?: string;
+  {{/if}}
+  {{#if (eq type "oauth2")}}
+  /** OAuth2 access token for the {{name}} security scheme */
+  {{configKey}}?: string;
+  {{/if}}
+  {{#if (eq type "openIdConnect")}}
+  /** OpenID Connect access token for the {{name}} security scheme */
+  {{configKey}}?: string;
+  {{/if}}
+{{/each}}
+  /** Request timeout in milliseconds (default: 15000) */
+  timeoutMs?: number;
+  /** Retry configuration */
+  retries?: RetryConfig;
+  /** Custom idempotency key generator for mutating requests */
+  getIdempotencyKey?: () => string;
+  /** Called before each request is dispatched */
+  onRequest?: (meta: RequestMeta) => void;
+  /** Called after a successful response is received */
+  onResponse?: (meta: ResponseMeta) => void;
+  /** Called when a request fails */
+  onError?: (meta: ErrorMeta) => void;
+  /**
+   * Send credentials (cookies, HTTP auth) on cross-origin requests.
+   * Maps directly to Axios's `withCredentials` option — effective in browser environments.
+   * In Node.js use `cookies` or `cookieJar` instead.
+   */
+  withCredentials?: boolean;
+  /** Static cookie key/value pairs sent with every request */
+  cookies?: Record<string, string>;
+  /**
+   * Ordered list of plugins applied to every request and response.
+   * See {@link SDKPlugin} for the available hooks.
+   */
+  plugins?: SDKPlugin[];
+  /**
+   * Default headers sent with every request.
+   * Merged beneath per-request headers (per-request wins on conflict).
+   */
+  defaultHeaders?: Record<string, string>;
+  /**
+   * Custom Axios instance configuration merged into the transport instance.
+   * Useful for setting proxy, httpsAgent, or other Axios-specific options.
+   */
+  axiosConfig?: Omit<AxiosRequestConfig, 'baseURL' | 'timeout' | 'withCredentials' | 'headers'>;
+  /**
+   * Custom function to map raw errors to SDKError.
+   * When provided, this replaces the built-in error mapper entirely.
+   */
+  mapError?: (error: unknown) => SDKError;
+  /**
+   * Custom function to extract response data from the Axios response.
+   * Useful when the API wraps responses in an envelope.
+   * When not provided, returns `response.data` directly.
+   */
+  responseTransform?: <T>(response: AxiosResponse) => T;
+  /**
+   * HTTP methods that should receive an idempotency key.
+   * Default: ['POST', 'PUT', 'PATCH', 'DELETE']
+   */
+  idempotentMethods?: string[];
+}
+
+// ── Telemetry Meta Types ────────────────────────────
+
+export interface RequestMeta {
+  method: string;
+  url: string;
+  timestamp: number;
+}
+
+export interface ResponseMeta {
+  method: string;
+  url: string;
+  status: number;
+  duration: number;
+}
+
+export interface ErrorMeta {
+  method: string;
+  url: string;
+  error: Record<string, unknown>;
+  duration: number;
+  attempt: number;
+  willRetry: boolean;
+}
+
+export interface ResolvedTransportConfig extends TransportConfig {
+  timeoutMs: number;
+  retries: RetryConfig;
+  plugins: SDKPlugin[];
+  idempotentMethods: string[];
+}
+
+/**
+ * Per-request options that override transport-level defaults.
+ */
+export interface RequestOptions {
+  /** AbortSignal for cooperative cancellation of this specific request */
+  signal?: AbortSignal;
+  /** Per-request timeout override in milliseconds (overrides TransportConfig.timeoutMs) */
+  timeoutMs?: number;
+  /** Additional headers merged into this request only */
+  headers?: Record<string, string>;
+  /** Per-request retry override. Set `{ attempts: 0 }` to disable retries for this request. */
+  retries?: Partial<RetryConfig>;
+}
+
+export interface SDKTransport {
+  readonly axios: AxiosInstance;
+  readonly config: ResolvedTransportConfig;
+  executeRequest<T>(config: AxiosRequestConfig, options?: RequestOptions): Promise<T>;
+}
+
+// ── Error Resolution ────────────────────────────────
+
+function resolveErrorCode(status: number): string {
+  switch (status) {
+    case 400: return 'bad_request';
+    case 401: return 'unauthorized';
+    case 403: return 'forbidden';
+    case 404: return 'not_found';
+    case 405: return 'method_not_allowed';
+    case 408: return 'request_timeout';
+    case 409: return 'conflict';
+    case 413: return 'payload_too_large';
+    case 422: return 'unprocessable_entity';
+    case 429: return 'rate_limit_exceeded';
+    case 502: return 'bad_gateway';
+    case 503: return 'service_unavailable';
+    case 504: return 'gateway_timeout';
+    default: return status >= 500 ? 'internal_server_error' : 'http_error';
+  }
+}
+
+function resolveMessage(status: number): string {
+  switch (status) {
+    case 400: return 'Bad request';
+    case 401: return 'Unauthorized';
+    case 403: return 'Forbidden';
+    case 404: return 'Not found';
+    case 405: return 'Method not allowed';
+    case 408: return 'Request timeout';
+    case 409: return 'Conflict';
+    case 413: return 'Payload too large';
+    case 422: return 'Unprocessable entity';
+    case 429: return 'Rate limit exceeded';
+    case 502: return 'Bad gateway';
+    case 503: return 'Service unavailable';
+    case 504: return 'Gateway timeout';
+    default: return status >= 500 ? 'Internal server error' : 'HTTP error';
+  }
+}
+
+function isAxiosError(error: unknown): error is AxiosError {
+  return !!error && typeof error === 'object' && (error as { isAxiosError?: unknown }).isAxiosError === true;
+}
+
+function readStartTime(config: AxiosRequestConfig | undefined): number | undefined {
+  const startTime = (config as { _startTime?: unknown } | undefined)?._startTime;
+  return typeof startTime === 'number' ? startTime : undefined;
+}
+
+function appendQueryParam(
+  reqConfig: InternalAxiosRequestConfig,
+  key: string,
+  value: string,
+): void {
+  if (reqConfig.params instanceof URLSearchParams) {
+    reqConfig.params.set(key, value);
+    return;
+  }
+
+  const params = reqConfig.params && typeof reqConfig.params === 'object'
+    ? (reqConfig.params as Record<string, unknown>)
+    : {};
+
+  params[key] = value;
+  reqConfig.params = params;
+}
+
+function appendCookie(
+  reqConfig: InternalAxiosRequestConfig,
+  key: string,
+  value: string,
+): void {
+  const serialized = `${encodeURIComponent(key)}=${encodeURIComponent(value)}`;
+  const existing = reqConfig.headers.Cookie;
+  if (typeof existing === 'string' && existing.length > 0) {
+    reqConfig.headers.Cookie = `${existing}; ${serialized}`;
+    return;
+  }
+  reqConfig.headers.Cookie = serialized;
+}
+
+// ── Transport Factory ───────────────────────────────
+
+/**
+ * Create a configured Axios-backed transport with automatic retries.
+ */
+export function createTransport(config: TransportConfig): SDKTransport {
+  const resolvedConfig: ResolvedTransportConfig = {
+    ...config,
+    timeoutMs: config.timeoutMs ?? 15000,
+    retries: {
+      attempts: 3,
+      backoffMs: 400,
+      jitter: true,
+      maxBackoffMs: 30_000,
+      ...config.retries,
+    },
+    plugins: config.plugins ?? [],
+    idempotentMethods: config.idempotentMethods ?? ['POST', 'PUT', 'PATCH', 'DELETE'],
+  };
+
+  const instance = axios.create({
+    baseURL: resolvedConfig.baseUrl,
+    timeout: resolvedConfig.timeoutMs,
+    withCredentials: resolvedConfig.withCredentials ?? false,
+    headers: {
+      'Content-Type': 'application/json',
+      ...(resolvedConfig.defaultHeaders ?? {}),
+    },
+    ...resolvedConfig.axiosConfig,
+  });
+
+  instance.interceptors.request.use(
+    async (reqConfig: InternalAxiosRequestConfig): Promise<InternalAxiosRequestConfig> => {
+      (reqConfig as { _startTime?: number })._startTime = Date.now();
+
+{{#each securitySchemes}}
+      {{#if (eq type "apiKey")}}
+      if (resolvedConfig.{{configKey}}) {
+        {{#if (eq in "header")}}
+        reqConfig.headers['{{paramName}}'] = resolvedConfig.{{configKey}};
+        {{/if}}
+        {{#if (eq in "query")}}
+        appendQueryParam(reqConfig, '{{paramName}}', resolvedConfig.{{configKey}});
+        {{/if}}
+        {{#if (eq in "cookie")}}
+        appendCookie(reqConfig, '{{paramName}}', resolvedConfig.{{configKey}});
+        {{/if}}
+      }
+      {{/if}}
+      {{#if (and (eq type "http") (eq scheme "bearer"))}}
+      if (resolvedConfig.{{configKey}}) {
+        reqConfig.headers.Authorization = `Bearer ${ resolvedConfig.{{configKey}} }`;
+      }
+      {{/if}}
+      {{#if (eq type "oauth2")}}
+      if (resolvedConfig.{{configKey}}) {
+        reqConfig.headers.Authorization = `Bearer ${ resolvedConfig.{{configKey}} }`;
+      }
+      {{/if}}
+      {{#if (eq type "openIdConnect")}}
+      if (resolvedConfig.{{configKey}}) {
+        reqConfig.headers.Authorization = `Bearer ${ resolvedConfig.{{configKey}} }`;
+      }
+      {{/if}}
+{{/each}}
+
+      // ── Static Cookies ─────────────────────────────────
+      if (resolvedConfig.cookies) {
+        for (const [name, value] of Object.entries(resolvedConfig.cookies)) {
+          appendCookie(reqConfig, name, value);
+        }
+      }
+
+      const method = reqConfig.method?.toUpperCase();
+      if (
+        method &&
+        resolvedConfig.idempotentMethods.includes(method) &&
+        resolvedConfig.getIdempotencyKey &&
+        !reqConfig.headers['X-Idempotency-Key']
+      ) {
+        reqConfig.headers['X-Idempotency-Key'] = resolvedConfig.getIdempotencyKey();
+      }
+
+      resolvedConfig.onRequest?.({
+        method: reqConfig.method || 'GET',
+        url: reqConfig.url || '',
+        timestamp: (reqConfig as { _startTime?: number })._startTime ?? Date.now(),
+      });
+
+      // ── Plugin: beforeRequest ───────────────────────────
+      let result: InternalAxiosRequestConfig = reqConfig;
+      for (const plugin of resolvedConfig.plugins) {
+        if (plugin.beforeRequest) {
+          const returned = await plugin.beforeRequest(result);
+          if (returned !== undefined) result = returned;
+        }
+      }
+      return result;
+    },
+    (error) => Promise.reject(error),
+  );
+
+  instance.interceptors.response.use(async (response) => {
+    const startTime = readStartTime(response.config);
+    const duration = startTime === undefined ? 0 : Date.now() - startTime;
+
+    resolvedConfig.onResponse?.({
+      method: response.config.method || 'GET',
+      url: response.config.url || '',
+      status: response.status,
+      duration,
+    });
+
+    // ── Plugin: afterResponse ───────────────────────────
+    let result: AxiosResponse = response;
+    for (const plugin of resolvedConfig.plugins) {
+      if (plugin.afterResponse) {
+        const returned = await plugin.afterResponse(result);
+        if (returned !== undefined) result = returned;
+      }
+    }
+    return result;
+  });
+
+  const transport: SDKTransport = {
+    axios: instance,
+    config: resolvedConfig,
+    executeRequest: <T>(requestConfig: AxiosRequestConfig, options?: RequestOptions) =>
+      executeRequest<T>(transport, requestConfig, options),
+  };
+
+  return transport;
+}
+
+// ── Request Execution ───────────────────────────────
+
+/**
+ * Execute an HTTP request with automatic retries and error mapping.
+ */
+export async function executeRequest<T>(
+  transport: SDKTransport,
+  requestConfig: AxiosRequestConfig,
+  options?: RequestOptions,
+): Promise<T> {
+  const retries: RetryConfig = {
+    ...transport.config.retries,
+    ...options?.retries,
+  };
+  const maxAttempts = retries.attempts;
+  const maxBackoff = retries.maxBackoffMs ?? 30_000;
+  const mapError = transport.config.mapError ?? mapAxiosError;
+
+  const mergedConfig: AxiosRequestConfig = {
+    ...requestConfig,
+    ...(options?.signal !== undefined ? { signal: options.signal } : {}),
+    ...(options?.timeoutMs !== undefined ? { timeout: options.timeoutMs } : {}),
+    ...(options?.headers
+      ? { headers: { ...requestConfig.headers, ...options.headers } }
+      : {}),
+  };
+
+  let lastError: SDKError | undefined;
+
+  for (let attempt = 0; attempt <= maxAttempts; attempt++) {
+    // Check for cancellation before each attempt
+    if (options?.signal?.aborted) {
+      throw lastError ?? new SDKError('Request aborted', 0, 'aborted');
+    }
+
+    try {
+      const response = await transport.axios.request<T>(mergedConfig);
+
+      // Handle no-content responses
+      if (response.status === 204 || response.status === 205) {
+        return undefined as T;
+      }
+
+      // Apply custom response transform if provided
+      if (transport.config.responseTransform) {
+        return transport.config.responseTransform<T>(response);
+      }
+
+      return response.data;
+    } catch (error) {
+      // Don't retry if the request was cancelled
+      if (options?.signal?.aborted) {
+        throw mapError(error);
+      }
+
+      const sdkError = mapError(error);
+      lastError = sdkError;
+
+      const axiosConfig = isAxiosError(error) ? error.config : undefined;
+      const effectiveConfig = axiosConfig ?? mergedConfig;
+      const startTime = readStartTime(effectiveConfig);
+      const duration = startTime === undefined ? 0 : Date.now() - startTime;
+
+      // Determine if we should retry
+      const shouldRetry = retries.shouldRetry
+        ? retries.shouldRetry(sdkError, attempt)
+        : sdkError.isRetryable();
+
+      const willRetry = attempt < maxAttempts && shouldRetry;
+
+      // Notify error hook
+      transport.config.onError?.({
+        method: effectiveConfig.method || 'GET',
+        url: effectiveConfig.url || '',
+        error: sdkError.toJSON(),
+        duration,
+        attempt,
+        willRetry,
+      });
+
+      if (!willRetry) {
+        // Run plugin onError hooks before throwing
+        let finalError = sdkError;
+        for (const plugin of transport.config.plugins) {
+          if (plugin.onError) {
+            const transformed = await plugin.onError(finalError, mergedConfig);
+            if (transformed instanceof SDKError) finalError = transformed;
+          }
+        }
+        throw finalError;
+      }
+
+      // Calculate delay
+      const retryAfterMs = parseRetryAfterMs(error);
+      let delayMs: number;
+
+      if (sdkError.status === 429 && retryAfterMs !== undefined) {
+        delayMs = retryAfterMs;
+      } else {
+        delayMs = calculateBackoff(attempt, retries.backoffMs, retries.jitter, maxBackoff);
+      }
+
+      // Allow custom delay override
+      if (retries.delay) {
+        delayMs = retries.delay(sdkError, attempt, delayMs);
+      }
+
+      // Notify retry hook (can abort)
+      if (retries.onRetry) {
+        const result = await retries.onRetry(sdkError, attempt, delayMs);
+        if (result === false) {
+          throw sdkError;
+        }
+      }
+
+      await delay(delayMs, options?.signal);
+    }
+  }
+
+  // Should never reach here, but TypeScript needs it
+  throw lastError ?? new SDKError('Request failed after retries', 0, 'retry_exhausted');
+}
+
+/**
+ * Map an Axios error to a structured SDKError.
+ */
+function mapAxiosError(error: unknown): SDKError {
+  if (error instanceof SDKError) {
+    return error;
+  }
+
+  if (!isAxiosError(error)) {
+    if (error instanceof DOMException && error.name === 'AbortError') {
+      return new SDKError('Request aborted', 0, 'aborted');
+    }
+    return new SDKError(
+      error instanceof Error ? error.message : 'Unexpected error',
+      0,
+      'unexpected_error',
+    );
+  }
+
+  if (error.code === 'ERR_CANCELED' || error.code === 'ECONNABORTED') {
+    if (error.message?.includes('timeout')) {
+      return new SDKError('Request timed out', 504, 'gateway_timeout');
+    }
+    return new SDKError('Request aborted', 0, 'aborted');
+  }
+
+  if (error.code === 'ECONNREFUSED') {
+    return new SDKError('Connection refused', 0, 'connection_refused');
+  }
+
+  if (error.code === 'ENOTFOUND') {
+    return new SDKError('DNS lookup failed', 0, 'dns_error');
+  }
+
+  if (!error.response) {
+    return new SDKError(
+      error.message || 'Unable to connect to the server',
+      0,
+      'network_error',
+    );
+  }
+
+  const status = error.response.status;
+  const data = error.response.data as any;
+
+  if (data && typeof data === 'object' && typeof data.error === 'string' && typeof data.message === 'string') {
+    return new SDKError(data as ApiErrorEnvelope, status);
+  }
+
+  return new SDKError(
+    data?.message || error.message || resolveMessage(status),
+    status,
+    data?.error || resolveErrorCode(status),
+    data?.request_id,
+  );
+}

package/templates/typescript/tsconfig.hbs

@@ -0,0 +1,18 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "Node16",
+    "moduleResolution": "Node16",
+    "outDir": "./dist",
+    "rootDir": ".",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true
+  },
+  "include": ["index.ts", "src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}