@apollo-deploy/tesseract 0.4.3 → 0.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@apollo-deploy/tesseract",
-  "version": "0.4.3",
+  "version": "0.5.0",
   "type": "module",
   "description": "Manifest-first SDK generator — turns sdk-manifold/v1 manifests into production-ready TypeScript SDKs",
   "bin": {
@@ -12,6 +12,30 @@
     ".": {
       "import": "./dist/index.js",
       "types": "./dist/index.d.ts"
+    },
+    "./fastify": {
+      "import": "./dist/fastify.js",
+      "types": "./dist/fastify.d.ts"
+    },
+    "./express": {
+      "import": "./dist/express.js",
+      "types": "./dist/express.d.ts"
+    },
+    "./hono": {
+      "import": "./dist/hono.js",
+      "types": "./dist/hono.d.ts"
+    },
+    "./koa": {
+      "import": "./dist/koa.js",
+      "types": "./dist/koa.d.ts"
+    },
+    "./elysia": {
+      "import": "./dist/elysia.js",
+      "types": "./dist/elysia.d.ts"
+    },
+    "./nestjs": {
+      "import": "./dist/nestjs.js",
+      "types": "./dist/nestjs.d.ts"
     }
   },
   "files": [
@@ -47,12 +71,50 @@
   "dependencies": {
     "change-case": "^5.4.4",
     "commander": "^12.1.0",
+    "fastify-plugin": "^5.1.0",
     "handlebars": "^4.7.8",
     "prettier": "^3.3.0",
     "ts-morph": "^27.0.2"
   },
+  "peerDependencies": {
+    "fastify": ">=4",
+    "express": ">=4",
+    "hono": ">=4",
+    "koa": ">=2",
+    "@koa/router": ">=12",
+    "elysia": ">=1",
+    "@nestjs/common": ">=9",
+    "@nestjs/core": ">=9"
+  },
+  "peerDependenciesMeta": {
+    "fastify": {
+      "optional": true
+    },
+    "express": {
+      "optional": true
+    },
+    "hono": {
+      "optional": true
+    },
+    "koa": {
+      "optional": true
+    },
+    "@koa/router": {
+      "optional": true
+    },
+    "elysia": {
+      "optional": true
+    },
+    "@nestjs/common": {
+      "optional": true
+    },
+    "@nestjs/core": {
+      "optional": true
+    }
+  },
   "devDependencies": {
     "@types/node": "^20.14.0",
+    "fastify": "^5.8.5",
     "typescript": "^5.5.0"
   }
 }

package/templates/typescript/client-class.hbs

@@ -0,0 +1,136 @@
+/**
+ * @generated
+ * This file was automatically generated by Tesseract.
+ * DO NOT MODIFY THIS FILE DIRECTLY.
+ */
+
+{{#if (eq clientType "public")}}
+import { createTransport, type SDKTransport } from './transport/axios.js';
+{{else}}
+import { createTransport, type SDKTransport, type SDKPlugin, type RequestMeta, type ResponseMeta, type ErrorMeta } from './transport/axios.js';
+{{/if}}
+{{#each groups}}
+import { {{interfaceName}} } from './domain/{{fileName}}.js';
+{{/each}}
+{{#if hasWebhooks}}
+import { createWebhookRegistry, type WebhookRegistry } from './webhooks/handler.js';
+{{/if}}
+
+{{#if (eq clientType "internal")}}
+/**
+ * Configuration options for {{meta.title}}.
+ * Pass as the last argument to the constructor for advanced settings.
+ */
+export interface {{meta.clientName}}Options {
+  /** Base URL for the API (default: '{{meta.baseUrl}}') */
+  baseUrl?: string;
+  /** Request timeout in milliseconds (default: 15000) */
+  timeoutMs?: number;
+  /** Retry configuration */
+  retries?: { attempts: number; backoffMs: number; jitter: boolean; maxBackoffMs?: number };
+  /** Custom idempotency key generator */
+  getIdempotencyKey?: () => string;
+  /** Request telemetry hook */
+  onRequest?: (meta: RequestMeta) => void;
+  /** Response telemetry hook */
+  onResponse?: (meta: ResponseMeta) => void;
+  /** Error telemetry hook */
+  onError?: (meta: ErrorMeta) => void;
+  /** Default headers sent with every request */
+  defaultHeaders?: Record<string, string>;
+  /** Ordered list of plugins applied to every request and response */
+  plugins?: SDKPlugin[];
+}
+
+{{/if}}
+/**
+ * {{meta.title}} SDK client.
+ *
+ * @example
+ * ```ts
+ * import { {{meta.clientName}} } from '{{meta.packageName}}';
+ *
+{{#if securitySchemes.length}}
+{{#each securitySchemes}}
+{{#if (eq type "apiKey")}}
+ * const client = new {{../meta.clientName}}('YOUR_{{upperCase configKey}}');
+{{/if}}
+{{#if (and (eq type "http") (eq scheme "bearer"))}}
+ * const client = new {{../meta.clientName}}('YOUR_BEARER_TOKEN');
+{{/if}}
+{{/each}}
+{{else}}
+ * const client = new {{meta.clientName}}();
+{{/if}}
+ * ```
+ */
+export class {{meta.clientName}} {
+{{#if (eq clientType "public")}}
+  private readonly _transport: SDKTransport;
+{{else}}
+  /** @internal — exposed for advanced use and testing */
+  readonly _transport: SDKTransport;
+{{/if}}
+
+{{#each groups}}
+  /** {{#if description}}{{description}}{{else}}{{interfaceName}} operations{{/if}} */
+  readonly {{name}}: {{interfaceName}};
+{{/each}}
+{{#if hasWebhooks}}
+  /** Typed webhook event handler registry */
+  readonly webhooks: WebhookRegistry;
+{{/if}}
+
+  constructor(
+{{#if securitySchemes.length}}
+{{#each securitySchemes}}
+{{#if (eq type "apiKey")}}
+    readonly {{configKey}}: string,
+{{/if}}
+{{#if (and (eq type "http") (eq scheme "bearer"))}}
+    readonly {{configKey}}: string,
+{{/if}}
+{{#if (eq type "oauth2")}}
+    readonly {{configKey}}: string,
+{{/if}}
+{{#if (eq type "openIdConnect")}}
+    readonly {{configKey}}: string,
+{{/if}}
+{{/each}}
+{{/if}}
+{{#if (eq clientType "internal")}}
+    options?: {{meta.clientName}}Options,
+{{/if}}
+  ) {
+    this._transport = createTransport({
+{{#if (eq clientType "public")}}
+      baseUrl: '{{meta.baseUrl}}',
+{{else}}
+      baseUrl: options?.baseUrl ?? '{{meta.baseUrl}}',
+{{/if}}
+{{#each securitySchemes}}
+      {{configKey}}: this.{{configKey}},
+{{/each}}
+{{#if (eq clientType "public")}}
+      timeoutMs: 15000,
+      retries: { attempts: 3, backoffMs: 400, jitter: true },
+{{else}}
+      timeoutMs: options?.timeoutMs ?? 15000,
+      retries: options?.retries ?? { attempts: 3, backoffMs: 400, jitter: true },
+      getIdempotencyKey: options?.getIdempotencyKey,
+      onRequest: options?.onRequest,
+      onResponse: options?.onResponse,
+      onError: options?.onError,
+      defaultHeaders: options?.defaultHeaders,
+      plugins: options?.plugins,
+{{/if}}
+    });
+
+{{#each groups}}
+    this.{{name}} = new {{interfaceName}}(this._transport);
+{{/each}}
+{{#if hasWebhooks}}
+    this.webhooks = createWebhookRegistry();
+{{/if}}
+  }
+}

package/templates/typescript/domain-class.hbs

@@ -0,0 +1,188 @@
+/**
+ * @generated
+ * This file was automatically generated by Tesseract.
+ * DO NOT MODIFY THIS FILE DIRECTLY.
+ */
+
+import type { SDKTransport, RequestOptions } from '../transport/axios.js';
+{{#if hasSSE}}
+import { createSSEStream, type SSEEvent, type SSEOptions, type SSEClientConfig } from '../transport/sse.js';
+{{/if}}
+{{#if imports.length}}
+import type {
+{{#each imports}}
+  {{this}},
+{{/each}}
+} from '../types/index.js';
+{{/if}}
+
+export class {{interfaceName}} {
+  constructor(private readonly _transport: SDKTransport) {}
+
+{{#if hasSSE}}
+  private _buildSSEClientConfig(): SSEClientConfig {
+    const headers: Record<string, string> = {
+      ...(this._transport.config.defaultHeaders ?? {}),
+    };
+{{#each securitySchemes}}
+  {{#if (eq type "apiKey")}}
+    {{#if (eq in "header")}}
+    if (this._transport.config.{{configKey}}) headers['{{paramName}}'] = this._transport.config.{{configKey}}!;
+    {{/if}}
+  {{/if}}
+  {{#if (and (eq type "http") (eq scheme "bearer"))}}
+    if (this._transport.config.{{configKey}}) headers['Authorization'] = `Bearer ${ this._transport.config.{{configKey}} }`;
+  {{/if}}
+  {{#if (eq type "oauth2")}}
+    if (this._transport.config.{{configKey}}) headers['Authorization'] = `Bearer ${ this._transport.config.{{configKey}} }`;
+  {{/if}}
+  {{#if (eq type "openIdConnect")}}
+    if (this._transport.config.{{configKey}}) headers['Authorization'] = `Bearer ${ this._transport.config.{{configKey}} }`;
+  {{/if}}
+{{/each}}
+    return {
+      headers: Object.keys(headers).length > 0 ? headers : undefined,
+      cookies: this._transport.config.cookies,
+      withCredentials: this._transport.config.withCredentials,
+    };
+  }
+
+{{/if}}
+{{#each operations}}
+{{#if (isEventStream this)}}
+  {{#if (or summary description)}}
+  /** {{#if summary}}{{summary}}{{#if description}} — {{description}}{{/if}}{{else}}{{description}}{{/if}} (SSE stream) */
+  {{/if}}
+  {{name}}{{{sseMethodSignature this}}} {
+    const sseUrl = new URL(`{{path}}`, this._transport.config.baseUrl);
+{{#if (hasQueryParams this)}}
+    if (query) {
+{{#each queryParams}}
+      if (query.{{name}} !== undefined && query.{{name}} !== null) {
+        sseUrl.searchParams.set('{{originalName}}', String(query.{{name}}));
+      }
+{{/each}}
+    }
+{{else if queryType}}
+    if (query) {
+      for (const [k, v] of Object.entries(query)) {
+        if (v !== undefined && v !== null) sseUrl.searchParams.set(k, String(v));
+      }
+    }
+{{/if}}
+{{#if (or (hasRequestBody this) (needsRequestHeaders this))}}
+    const sseHeaders: Record<string, string> = {};
+{{#if (hasRequestBody this)}}
+    sseHeaders['Content-Type'] = '{{requestBody.contentType}}';
+{{/if}}
+{{#if (and headerParams.length headerType)}}
+    if (headerOptions) {
+{{#each headerParams}}
+      if (headerOptions.{{name}} !== undefined && headerOptions.{{name}} !== null) {
+        sseHeaders['{{originalName}}'] = String(headerOptions.{{name}});
+      }
+{{/each}}
+    }
+{{/if}}
+{{#if cookieParams}}
+    if (cookies) {
+      const cookiePairs: string[] = [];
+{{#each cookieParams}}
+      if (cookies.{{name}} !== undefined && cookies.{{name}} !== null) {
+        cookiePairs.push(`{{originalName}}=${encodeURIComponent(String(cookies.{{name}}))}`);
+      }
+{{/each}}
+      if (cookiePairs.length > 0) {
+        sseHeaders.Cookie = cookiePairs.join('; ');
+      }
+    }
+{{/if}}
+{{/if}}
+    return createSSEStream<{{#if sseReturnType}}{{sseReturnType}}{{else}}{{{sseEventType this}}}{{/if}}>(
+      sseUrl.toString(),
+      {
+        method: '{{httpMethod}}',
+{{#if (hasRequestBody this)}}
+        body: JSON.stringify(input),
+{{/if}}
+{{#if (or (hasRequestBody this) (needsRequestHeaders this))}}
+        headers: Object.keys(sseHeaders).length > 0 ? sseHeaders : undefined,
+{{/if}}
+      },
+      undefined,
+      this._buildSSEClientConfig(),
+      options,
+    );
+  }
+
+{{else}}
+  {{#if deprecated}}
+  /** @deprecated {{#if deprecationMessage}}{{deprecationMessage}}{{else if summary}}{{summary}}{{#if description}} — {{description}}{{/if}}{{else if description}}{{description}}{{/if}} */
+  {{else if (or summary description)}}
+  /** {{#if summary}}{{summary}}{{#if description}} — {{description}}{{/if}}{{else}}{{description}}{{/if}} */
+  {{/if}}
+  {{name}}{{{methodParams this}}}: Promise<{{responseType}}> {
+{{#if (hasQueryParams this)}}
+    const params = query
+      ? {
+{{#each queryParams}}
+          '{{originalName}}': query.{{name}},
+{{/each}}
+        }
+      : undefined;
+{{else if queryType}}
+    const params = query;
+{{/if}}
+{{#if (needsRequestHeaders this)}}
+    const requestHeaders: Record<string, string> = {};
+{{#if (and (hasRequestBody this) (and (neq requestBody.contentType "application/json") (neq requestBody.contentType "multipart/form-data")))}}
+    requestHeaders['Content-Type'] = '{{requestBody.contentType}}';
+{{/if}}
+{{#if (and headerParams.length headerType)}}
+    if (headerOptions) {
+{{#each headerParams}}
+      if (headerOptions.{{name}} !== undefined && headerOptions.{{name}} !== null) {
+        requestHeaders['{{originalName}}'] = String(headerOptions.{{name}});
+      }
+{{/each}}
+    }
+{{/if}}
+{{#if cookieParams}}
+    if (cookies) {
+      const cookiePairs: string[] = [];
+{{#each cookieParams}}
+      if (cookies.{{name}} !== undefined && cookies.{{name}} !== null) {
+        cookiePairs.push(`{{originalName}}=${encodeURIComponent(String(cookies.{{name}}))}`);
+      }
+{{/each}}
+      if (cookiePairs.length > 0) {
+        requestHeaders.Cookie = cookiePairs.join('; ');
+      }
+    }
+{{/if}}
+{{/if}}
+    return this._transport.executeRequest<{{responseType}}>(
+      {
+        method: '{{httpMethod}}',
+        url: `{{path}}`,
+{{#if (hasRequestBody this)}}
+        data: input,
+{{/if}}
+{{#if (or (hasQueryParams this) queryType)}}
+        params,
+{{/if}}
+{{#if (needsRequestHeaders this)}}
+        headers: Object.keys(requestHeaders).length > 0 ? requestHeaders : undefined,
+{{/if}}
+      },
+{{#if timeout}}
+      { timeoutMs: {{timeout}}, ...options },
+{{else}}
+      options,
+{{/if}}
+    );
+  }
+
+{{/if}}
+{{/each}}
+}

package/templates/typescript/domain.hbs

@@ -25,7 +25,7 @@ export interface {{interfaceName}} {
   {{name}}{{{sseMethodSignature this}}};
 {{else}}
   {{#if deprecated}}
-  /** @deprecated {{#if summary}}{{summary}}{{#if description}} — {{description}}{{/if}}{{else if description}}{{description}}{{/if}} */
+  /** @deprecated {{#if deprecationMessage}}{{deprecationMessage}}{{else if summary}}{{summary}}{{#if description}} — {{description}}{{/if}}{{else if description}}{{description}}{{/if}} */
   {{else if (or summary description)}}
   /** {{#if summary}}{{summary}}{{#if description}} — {{description}}{{/if}}{{else}}{{description}}{{/if}} */
   {{/if}}
@@ -48,13 +48,13 @@ export function {{factoryName}}(transport: SDKTransport): {{interfaceName}} {
     {{/if}}
   {{/if}}
   {{#if (and (eq type "http") (eq scheme "bearer"))}}
-    if (transport.config.{{configKey}}) headers['Authorization'] = `Bearer ${transport.config.{{configKey}}}`;
+    if (transport.config.{{configKey}}) headers['Authorization'] = `Bearer ${ transport.config.{{configKey}} }`;
   {{/if}}
   {{#if (eq type "oauth2")}}
-    if (transport.config.{{configKey}}) headers['Authorization'] = `Bearer ${transport.config.{{configKey}}}`;
+    if (transport.config.{{configKey}}) headers['Authorization'] = `Bearer ${ transport.config.{{configKey}} }`;
   {{/if}}
   {{#if (eq type "openIdConnect")}}
-    if (transport.config.{{configKey}}) headers['Authorization'] = `Bearer ${transport.config.{{configKey}}}`;
+    if (transport.config.{{configKey}}) headers['Authorization'] = `Bearer ${ transport.config.{{configKey}} }`;
   {{/if}}
 {{/each}}
     return {
@@ -67,7 +67,7 @@ export function {{factoryName}}(transport: SDKTransport): {{interfaceName}} {
   return {
 {{#each operations}}
 {{#if (isEventStream this)}}
-    {{name}}{{{sseMethodParams this}}}: AsyncIterable<SSEEvent<{{{sseEventType this}}}>> {
+    {{name}}{{{sseMethodParams this}}}: {{#if sseReturnType}}AsyncIterable<{{sseReturnType}}>{{else}}AsyncIterable<SSEEvent<{{{sseEventType this}}}>>{{/if}} {
       const sseUrl = new URL(`{{path}}`, transport.config.baseUrl);
 {{#if (hasQueryParams this)}}
       if (query) {
@@ -112,7 +112,7 @@ export function {{factoryName}}(transport: SDKTransport): {{interfaceName}} {
       }
 {{/if}}
 {{/if}}
-      return createSSEStream<{{{sseEventType this}}}>(
+      return createSSEStream<{{#if sseReturnType}}{{sseReturnType}}{{else}}{{{sseEventType this}}}{{/if}}>(
         sseUrl.toString(),
         {
           method: '{{httpMethod}}',
@@ -184,7 +184,11 @@ export function {{factoryName}}(transport: SDKTransport): {{interfaceName}} {
           headers: Object.keys(requestHeaders).length > 0 ? requestHeaders : undefined,
 {{/if}}
         },
+{{#if timeout}}
+        { timeoutMs: {{timeout}}, ...options },
+{{else}}
         options,
+{{/if}}
       );
     },
 

package/templates/typescript/index-class.hbs

@@ -0,0 +1,68 @@
+/**
+ * @generated
+ * This file was automatically generated by Tesseract.
+ * DO NOT MODIFY THIS FILE DIRECTLY.
+ */
+
+// Client class — primary entry point
+{{#if (eq clientType "internal")}}
+export { {{meta.clientName}}, type {{meta.clientName}}Options } from './src/client.js';
+{{else}}
+export { {{meta.clientName}} } from './src/client.js';
+{{/if}}
+
+// Domain classes
+{{#each groups}}
+export { {{interfaceName}} } from './src/domain/{{fileName}}.js';
+{{/each}}
+
+// Error class
+export { SDKError } from './src/types/errors.js';
+
+{{#if (eq clientType "internal")}}
+// 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}}
+{{/if}}
+
+// Common types
+export type {
+  PaginationQuery,
+  PageMeta,
+  Page,
+  SuccessResponse,
+  MessageResponse,
+  ApiErrorEnvelope,
+} from './src/types/common.js';
+
+{{#if hasWebhooks}}
+// Webhooks
+{{#if (eq clientType "internal")}}
+export { createWebhookRegistry } from './src/webhooks/handler.js';
+{{/if}}
+export type {
+  WebhookEventMap,
+  WebhookEventName,
+  WebhookHandler,
+  WebhookMeta,
+  WebhookVerifyOptions,
+  WebhookRegistry,
+  WebhookRegistryConfig,
+} from './src/webhooks/handler.js';
+{{/if}}

package/templates/typescript/transport-sse.hbs

@@ -235,13 +235,13 @@ const DEFAULT_MAX_BUFFER = 5 * 1024 * 1024; // 5MB
  * }
  * ```
  */
-export async function* createSSEStream<T>(
+export async function* createSSEStream<TEvent extends SSEEvent<unknown> = SSEEvent<Record<string, unknown>>>(
   url: string,
   init: SSERequestInit,
   reconnect?: Partial<SSEReconnectConfig>,
   clientConfig?: SSEClientConfig,
   options?: SSEOptions,
-): AsyncIterable<SSEEvent<T>> {
+): AsyncIterable<TEvent> {
   const rc: SSEReconnectConfig = { ...DEFAULT_RECONNECT, ...reconnect };
   const maxBuffer = options?.maxBufferSize ?? DEFAULT_MAX_BUFFER;
   let lastEventId: string | undefined;
@@ -374,7 +374,7 @@ export async function* createSSEStream<T>(
                 continue;
               }
 
-              yield parseSSEEventData<T>(rawEvent, options?.parseData);
+              yield parseSSEEventData<TEvent>(rawEvent, options?.parseData) as TEvent;
             }
           }
         } finally {