@apollo-deploy/tesseract 0.1.0

package/templates/typescript/index.hbs

@@ -0,0 +1,64 @@
+/**
+ * @generated
+ * This file was automatically generated by sdk-forge.
+ * DO NOT MODIFY THIS FILE DIRECTLY.
+ */
+
+// Client
+export { create{{meta.clientName}}Client } from './src/client.js';
+export type { {{meta.clientName}}Client, {{meta.clientName}}ClientConfig } from './src/client.js';
+
+// Error class
+export { SDKError } from './src/types/errors.js';
+
+// Transport
+export { createTransport, executeRequest } from './src/transport/axios.js';
+export type {
+  RetryConfig,
+  TransportConfig,
+  ResolvedTransportConfig,
+  SDKTransport,
+  SDKPlugin,
+  RequestOptions,
+  RequestMeta,
+  ResponseMeta,
+  ErrorMeta,
+} from './src/transport/axios.js';
+
+{{#if hasSSE}}
+// SSE (Server-Sent Events)
+export { createSSEStream, parseSSEChunk, parseSSEEventData } from './src/transport/sse.js';
+export type { SSEEvent, SSEOptions, SSEReconnectConfig } from './src/transport/sse.js';
+{{/if}}
+
+// Common types
+export type {
+  PaginationQuery,
+  PageMeta,
+  Page,
+  SuccessResponse,
+  MessageResponse,
+  ApiErrorEnvelope,
+} from './src/types/common.js';
+
+// Domain API types
+{{#each groups}}
+export type { {{interfaceName}} } from './src/domain/{{fileName}}.js';
+{{/each}}
+
+{{#if hasWebhooks}}
+// Webhooks
+export { createWebhookRegistry } from './src/webhooks/handler.js';
+export type {
+  WebhookEventMap,
+  WebhookEventName,
+  WebhookHandler,
+  WebhookMeta,
+  WebhookVerifyOptions,
+  WebhookRegistry,
+  WebhookRegistryConfig,
+} from './src/webhooks/handler.js';
+{{/if}}
+
+// Types
+export * from './src/types/index.js';

package/templates/typescript/package-json.hbs

@@ -0,0 +1,29 @@
+{
+  "name": "{{packageName}}",
+  "version": "{{version}}",
+  "type": "module",
+  "description": "{{#if description}}{{description}}{{else}}TypeScript SDK for {{title}}{{/if}}",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "tsc"
+  },
+  "dependencies": {
+    "axios": "1.14.0"{{#each externalPackages}},
+    "{{name}}": "{{version}}"{{/each}}
+  },
+  "devDependencies": {
+    "typescript": "^5.5.0"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ]
+}

package/templates/typescript/readme.hbs

@@ -0,0 +1,78 @@
+# {{title}} SDK
+
+{{#if description}}
+{{description}}
+
+{{/if}}
+> This SDK was automatically generated by [sdk-forge](https://github.com/sdk-forge).
+
+## Installation
+
+```bash
+npm install {{packageName}}
+```
+
+## Quick Start
+
+```typescript
+import { create{{clientName}}Client } from '{{packageName}}';
+
+const client = create{{clientName}}Client({
+  baseUrl: '{{baseUrl}}',
+{{#each securitySchemes}}
+  {{configKey}}: 'your-{{kebabCase name}}-credential',
+{{/each}}
+});
+const api = client.{{groups.[0].name}};
+```
+
+## Effect Runtime
+
+```typescript
+import { create{{clientName}}Client, Effect } from '{{packageName}}';
+
+const client = create{{clientName}}Client();
+
+const program = client.{{groups.[0].name}}.{{groups.[0].operations.[0].name}}Effect(/* params */);
+const result = await Effect.runPromise(program);
+```
+
+## API Reference
+
+{{#each groups}}
+### {{interfaceName}}
+
+{{#if description}}
+{{description}}
+
+{{/if}}
+| Method | HTTP | Path | Description |
+|--------|------|------|-------------|
+{{#each operations}}
+| `{{name}}` | {{httpMethod}} | `{{path}}` | {{#if description}}{{description}}{{else}}-{{/if}} |
+{{/each}}
+
+{{/each}}
+## Types
+
+{{#each schemas}}
+{{#if isEnum}}
+- `{{name}}` — enum: {{#each enumValues}}`{{this}}`{{#unless @last}}, {{/unless}}{{/each}}
+{{else}}
+- `{{name}}`{{#if description}} — {{description}}{{/if}}
+{{/if}}
+{{/each}}
+
+## Error Handling
+
+```typescript
+import { SDKError } from '{{packageName}}';
+
+try {
+  const result = await client.someApi.someMethod();
+} catch (error) {
+  if (error instanceof SDKError) {
+    console.error(`Error ${error.status}: ${error.message} (${error.code})`);
+  }
+}
+```

package/templates/typescript/transport-sse.hbs

@@ -0,0 +1,377 @@
+/**
+ * @generated
+ * This file was automatically generated by sdk-forge.
+ * DO NOT MODIFY THIS FILE DIRECTLY.
+ */
+
+/* eslint-disable @typescript-eslint/no-explicit-any */
+
+// ── SSE Types ────────────────────────────────────────
+
+/**
+ * A parsed Server-Sent Event with typed data payload.
+ */
+export interface SSEEvent<T = unknown> {
+  /** Event type (from the `event:` field, defaults to "message") */
+  type: string;
+  /** Parsed JSON data payload */
+  data: T;
+  /** Last event ID (from the `id:` field) */
+  id?: string;
+  /** Retry interval in milliseconds (from the `retry:` field) */
+  retry?: number;
+}
+
+/**
+ * Options for SSE stream subscriptions.
+ */
+export interface SSEOptions {
+  /** AbortSignal for cooperative cancellation */
+  signal?: AbortSignal;
+  /** Per-request timeout for the initial connection in milliseconds */
+  timeoutMs?: number;
+  /** Additional headers merged into the request */
+  headers?: Record<string, string>;
+  /** Custom event types to listen for (defaults to all events) */
+  eventTypes?: string[];
+  /**
+   * Called when the connection encounters a retryable error.
+   * Return `false` to stop reconnection attempts.
+   */
+  onRetry?: (attempt: number, error: unknown) => boolean | void;
+  /**
+   * Called when the SSE connection is established successfully.
+   * Useful for resetting UI state or logging.
+   */
+  onOpen?: (response: Response) => void;
+  /**
+   * Called when the SSE connection is closed (cleanly or after max retries).
+   */
+  onClose?: () => void;
+  /**
+   * Custom data parser. By default, attempts JSON.parse and falls back to raw string.
+   * Useful when the server sends non-JSON payloads or when you need custom deserialization.
+   */
+  parseData?: <R>(raw: string, eventType: string) => R;
+  /**
+   * Maximum buffer size in bytes before discarding incomplete data.
+   * Protects against memory exhaustion from malformed streams. Default: 5MB.
+   */
+  maxBufferSize?: number;
+  /**
+   * Heartbeat timeout in milliseconds. If no data is received within this period,
+   * the connection is considered dead and will be reconnected.
+   * Set to 0 to disable. Default: 0 (disabled).
+   */
+  heartbeatTimeoutMs?: number;
+  /**
+   * Whether to automatically reconnect when the stream ends cleanly (server closes connection).
+   * Default: false (only reconnects on errors).
+   */
+  reconnectOnComplete?: boolean;
+}
+
+/**
+ * Configuration for SSE reconnection behavior.
+ */
+export interface SSEReconnectConfig {
+  /** Maximum number of reconnection attempts (default: 5) */
+  maxAttempts: number;
+  /** Base delay between reconnection attempts in ms (default: 1000) */
+  baseDelayMs: number;
+  /** Maximum delay between reconnection attempts in ms (default: 30000) */
+  maxDelayMs: number;
+  /** Whether to apply jitter to reconnection delays (default: true) */
+  jitter?: boolean;
+}
+
+/**
+ * Fetch request init with headers narrowed to a plain string record.
+ * Avoids type conflicts from the broader `HeadersInit` union in `RequestInit`.
+ */
+export type SSERequestInit = Omit<RequestInit, 'headers'> & {
+  headers?: Record<string, string>;
+};
+
+// ── SSE Parser ───────────────────────────────────────
+
+/**
+ * Parse a raw SSE text chunk into individual events.
+ * Handles multi-line `data:` fields, all standard SSE fields,
+ * and both `\n` and `\r\n` line endings per the SSE specification.
+ */
+export function parseSSEChunk(chunk: string): SSEEvent<string>[] {
+  const events: SSEEvent<string>[] = [];
+  // Normalize \r\n and \r to \n for consistent parsing (SSE spec allows all three)
+  const normalized = chunk.replace(/\r\n/g, '\n').replace(/\r/g, '\n');
+  const blocks = normalized.split(/\n{2,}/);
+
+  for (const block of blocks) {
+    const trimmed = block.trim();
+    if (!trimmed) continue;
+    // Skip blocks that are entirely comments
+    if (trimmed.split('\n').every((line) => line.startsWith(':'))) continue;
+
+    let type = 'message';
+    let data = '';
+    let id: string | undefined;
+    let retry: number | undefined;
+
+    for (const line of trimmed.split('\n')) {
+      // Comment lines
+      if (line.startsWith(':')) continue;
+
+      const colonIdx = line.indexOf(':');
+      let field: string;
+      let value: string;
+
+      if (colonIdx === -1) {
+        // Field-only lines (no colon) — per spec, the value is empty string
+        field = line;
+        value = '';
+      } else {
+        field = line.slice(0, colonIdx);
+        // Per SSE spec: if there's a space after the colon, strip exactly one space
+        const rawValue = line.slice(colonIdx + 1);
+        value = rawValue.startsWith(' ') ? rawValue.slice(1) : rawValue;
+      }
+
+      switch (field) {
+        case 'event':
+          type = value;
+          break;
+        case 'data':
+          data += (data ? '\n' : '') + value;
+          break;
+        case 'id':
+          // Per spec: id field must not contain null characters
+          if (!value.includes('\0')) {
+            id = value;
+          }
+          break;
+        case 'retry': {
+          const parsed = Number.parseInt(value, 10);
+          if (Number.isFinite(parsed) && parsed >= 0) retry = parsed;
+          break;
+        }
+        // Unknown fields are ignored per spec
+      }
+    }
+
+    if (data) {
+      const event: SSEEvent<string> = { type, data };
+      if (id !== undefined) event.id = id;
+      if (retry !== undefined) event.retry = retry;
+      events.push(event);
+    }
+  }
+
+  return events;
+}
+
+/**
+ * Parse and type-cast an SSE event's data field from JSON.
+ * Falls back to the raw string value if JSON parsing fails.
+ */
+export function parseSSEEventData<T>(event: SSEEvent<string>, parseData?: <R>(raw: string, type: string) => R): SSEEvent<T> {
+  if (parseData) {
+    return { ...event, data: parseData<T>(event.data, event.type) };
+  }
+  let parsed: T;
+  try {
+    parsed = JSON.parse(event.data) as T;
+  } catch {
+    parsed = event.data as unknown as T;
+  }
+  return { ...event, data: parsed };
+}
+
+// ── SSE Stream Factory ──────────────────────────────
+
+const DEFAULT_RECONNECT: SSEReconnectConfig = {
+  maxAttempts: 5,
+  baseDelayMs: 1000,
+  maxDelayMs: 30_000,
+  jitter: true,
+};
+
+const DEFAULT_MAX_BUFFER = 5 * 1024 * 1024; // 5MB
+
+/**
+ * Create an async iterable that reads from an SSE endpoint using fetch.
+ * Automatically handles reconnection with exponential backoff.
+ *
+ * @example
+ * ```ts
+ * const stream = createSSEStream<MyEvent>(url, { method: 'GET' }, undefined, {
+ *   signal: controller.signal,
+ *   eventTypes: ['update', 'complete'],
+ *   heartbeatTimeoutMs: 30000,
+ *   onOpen: () => console.log('Connected'),
+ *   onClose: () => console.log('Disconnected'),
+ * });
+ *
+ * for await (const event of stream) {
+ *   console.log(event.type, event.data);
+ * }
+ * ```
+ */
+export async function* createSSEStream<T>(
+  url: string,
+  init: SSERequestInit,
+  reconnect?: Partial<SSEReconnectConfig>,
+  options?: SSEOptions,
+): AsyncIterable<SSEEvent<T>> {
+  const rc: SSEReconnectConfig = { ...DEFAULT_RECONNECT, ...reconnect };
+  const maxBuffer = options?.maxBufferSize ?? DEFAULT_MAX_BUFFER;
+  let lastEventId: string | undefined;
+  let attempt = 0;
+  let serverRetryMs: number | undefined;
+
+  try {
+    while (true) {
+      const headers: Record<string, string> = {
+        Accept: 'text/event-stream',
+        'Cache-Control': 'no-cache',
+        ...(init.headers ?? {}),
+        ...(options?.headers ?? {}),
+      };
+
+      if (lastEventId) {
+        headers['Last-Event-ID'] = lastEventId;
+      }
+
+      const controller = new AbortController();
+      const externalSignal = options?.signal;
+
+      if (externalSignal?.aborted) return;
+
+      // Link external signal to internal controller
+      const onAbort = () => controller.abort();
+      externalSignal?.addEventListener('abort', onAbort, { once: true });
+
+      let connectionTimeoutId: ReturnType<typeof setTimeout> | undefined;
+      if (options?.timeoutMs) {
+        connectionTimeoutId = setTimeout(() => controller.abort(), options.timeoutMs);
+      }
+
+      try {
+        const response = await fetch(url, {
+          ...init,
+          headers,
+          signal: controller.signal,
+        });
+
+        if (connectionTimeoutId) {
+          clearTimeout(connectionTimeoutId);
+          connectionTimeoutId = undefined;
+        }
+
+        if (!response.ok) {
+          throw new Error(`SSE connection failed: ${response.status} ${response.statusText}`);
+        }
+
+        if (!response.body) {
+          throw new Error('SSE response has no body');
+        }
+
+        // Connection established successfully
+        attempt = 0;
+        options?.onOpen?.(response);
+
+        const reader = response.body.getReader();
+        const decoder = new TextDecoder();
+        let buffer = '';
+        let heartbeatTimer: ReturnType<typeof setTimeout> | undefined;
+
+        const resetHeartbeat = () => {
+          if (heartbeatTimer) clearTimeout(heartbeatTimer);
+          if (options?.heartbeatTimeoutMs && options.heartbeatTimeoutMs > 0) {
+            heartbeatTimer = setTimeout(() => {
+              reader.cancel().catch(() => {});
+            }, options.heartbeatTimeoutMs);
+          }
+        };
+
+        try {
+          resetHeartbeat();
+
+          while (true) {
+            if (externalSignal?.aborted) return;
+
+            const { done, value } = await reader.read();
+            if (done) break;
+
+            resetHeartbeat();
+
+            buffer += decoder.decode(value, { stream: true });
+
+            // Guard against memory exhaustion from malformed streams
+            if (buffer.length > maxBuffer) {
+              // Discard everything before the last double newline, or the whole buffer
+              const lastBreak = buffer.lastIndexOf('\n\n');
+              if (lastBreak !== -1) {
+                buffer = buffer.slice(lastBreak + 2);
+              } else {
+                buffer = '';
+              }
+            }
+
+            // Process complete events (separated by double newlines)
+            // Handle both \n\n and \r\n\r\n
+            const lastDoubleNewline = Math.max(
+              buffer.lastIndexOf('\n\n'),
+              buffer.lastIndexOf('\r\n\r\n'),
+            );
+            if (lastDoubleNewline === -1) continue;
+
+            const breakLen = buffer[lastDoubleNewline] === '\r' ? 4 : 2;
+            const complete = buffer.slice(0, lastDoubleNewline + breakLen);
+            buffer = buffer.slice(lastDoubleNewline + breakLen);
+
+            const rawEvents = parseSSEChunk(complete);
+            for (const rawEvent of rawEvents) {
+              if (rawEvent.id !== undefined) lastEventId = rawEvent.id;
+              if (rawEvent.retry !== undefined) serverRetryMs = rawEvent.retry;
+
+              if (options?.eventTypes && !options.eventTypes.includes(rawEvent.type)) {
+                continue;
+              }
+
+              yield parseSSEEventData<T>(rawEvent, options?.parseData);
+            }
+          }
+        } finally {
+          if (heartbeatTimer) clearTimeout(heartbeatTimer);
+          reader.releaseLock();
+          externalSignal?.removeEventListener('abort', onAbort);
+        }
+
+        // Stream ended cleanly
+        if (!options?.reconnectOnComplete) return;
+        // Fall through to reconnection logic below
+      } catch (error: unknown) {
+        if (connectionTimeoutId) clearTimeout(connectionTimeoutId);
+        externalSignal?.removeEventListener('abort', onAbort);
+
+        if (externalSignal?.aborted) return;
+
+        attempt++;
+        if (attempt > rc.maxAttempts) throw error;
+
+        const shouldRetry = options?.onRetry?.(attempt, error);
+        if (shouldRetry === false) throw error;
+      }
+
+      // Reconnection delay
+      const baseDelay = serverRetryMs ?? rc.baseDelayMs * Math.pow(2, attempt - 1);
+      let delayMs = Math.min(baseDelay, rc.maxDelayMs);
+      if (rc.jitter !== false) {
+        delayMs = Math.floor(Math.random() * (delayMs + 1));
+      }
+      await new Promise((resolve) => setTimeout(resolve, delayMs));
+    }
+  } finally {
+    options?.onClose?.();
+  }
+}