@apollo-deploy/tesseract 1.9.0 → 2.1.0

package/templates/rust/types.hbs

@@ -1,142 +1,65 @@
 use serde::{Deserialize, Serialize};
 
 {{#each schemas}}
-{{#if (and (not ownership) (not isEnum) (not isTypeAlias) (not isUnionType) (not isIntersectionType))}}
-{{#if (or externalImport (eq ownership.kind "external"))}}
-// {{name}} is imported from an external schema package.
-{{else}}
-{{#if description}}
-/// {{description}}
-{{/if}}
-#[derive(Debug, Clone, Serialize, Deserialize)]
-{{#if additionalPropertiesType}}
-{{! Additional properties means we need to use a flattened map }}
-#[serde(rename_all = "camelCase")]
-pub struct {{name}} {
-    {{#each properties}}
-    {{#if description}}
-    /// {{description}}
-    {{/if}}
-    {{#if deprecated}}
-    #[deprecated]
-    {{/if}}
-    {{#if (and nullable (not required))}}
-    #[serde(skip_serializing_if = "Option::is_none")]
-    pub {{snakeCase name}}: Option<{{{rustType type}}}>,
-    {{else if nullable}}
-    #[serde(skip_serializing_if = "Option::is_none")]
-    pub {{snakeCase name}}: Option<{{{rustType type}}}>,
-    {{else if required}}
-    pub {{snakeCase name}}: {{{rustType type}}},
-    {{else}}
-    #[serde(skip_serializing_if = "Option::is_none")]
-    pub {{snakeCase name}}: Option<{{{rustType type}}}>,
-    {{/if}}
-    {{/each}}
-}
-{{else}}
-#[serde(rename_all = "camelCase")]
-pub struct {{name}} {
-    {{#each properties}}
-    {{#if description}}
-    /// {{description}}
-    {{/if}}
-    {{#if deprecated}}
-    #[deprecated]
-    {{/if}}
-    {{#if (and nullable (not required))}}
-    #[serde(skip_serializing_if = "Option::is_none")]
-    pub {{snakeCase name}}: Option<{{{rustType type}}}>,
-    {{else if nullable}}
-    #[serde(skip_serializing_if = "Option::is_none")]
-    pub {{snakeCase name}}: Option<{{{rustType type}}}>,
-    {{else if required}}
-    pub {{snakeCase name}}: {{{rustType type}}},
-    {{else}}
-    #[serde(skip_serializing_if = "Option::is_none")]
-    pub {{snakeCase name}}: Option<{{{rustType type}}}>,
-    {{/if}}
-    {{/each}}
-}
-{{/if}}
-{{/if}}
-{{/if}}
+{{#if external}}
+/// External schema placeholder. Configure a language-specific package mapping to replace it.
+pub type {{name}} = serde_json::Value;
 
-{{#if isEnum}}
+{{else if isEnum}}
+{{#if stringEnum}}
 {{#if description}}
 /// {{description}}
 {{/if}}
 #[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
-{{#if enumValues}}
-#[serde(rename_all = "camelCase")]
-{{/if}}
 pub enum {{name}} {
-    {{#each enumValues}}
-    #[serde(rename = "{{this}}")]
-    {{pascalCase this}},
-    {{/each}}
+{{#each enumValues}}
+    #[serde(rename = "{{value}}")] {{name}},
+{{/each}}
 }
+{{else}}
+pub type {{name}} = f64;
 {{/if}}
 
-{{#if isTypeAlias}}
+{{else if isUnionType}}
 {{#if description}}
 /// {{description}}
 {{/if}}
-{{#if properties.length}}
-{{! Type alias with shape — emit as struct }}
 #[derive(Debug, Clone, Serialize, Deserialize)]
-#[serde(rename_all = "camelCase")]
-pub struct {{name}} {
-    {{#each properties}}
-    {{#if description}}
-    /// {{description}}
-    {{/if}}
-    {{#if required}}
-    pub {{snakeCase name}}: {{{rustType type}}},
-    {{else}}
-    #[serde(skip_serializing_if = "Option::is_none")]
-    pub {{snakeCase name}}: Option<{{{rustType type}}}>,
-    {{/if}}
-    {{/each}}
-}
-{{else}}
-{{! Simple type alias — skip, referenced by name }}
-// {{name}} is a type alias — referenced inline.
-{{/if}}
-{{/if}}
+#[serde(transparent)]
+pub struct {{name}}(pub serde_json::Value);
 
-{{#if isUnionType}}
+{{else if isIntersectionType}}
 {{#if description}}
 /// {{description}}
 {{/if}}
-{{#if unionMembers.length}}
-{{! Union type with named members — emit as enum }}
-#[derive(Debug, Clone, Serialize, Deserialize)]
-#[serde(untagged)]
-pub enum {{name}} {
-    {{#each unionMembers}}
-    {{pascalCase this}}({{{rustType this}}}),
-    {{/each}}
-}
-{{/if}}
+#[derive(Debug, Clone, Serialize, Deserialize, Default)]
+#[serde(transparent)]
+pub struct {{name}}(pub std::collections::HashMap<String, serde_json::Value>);
+
+{{else if isTypeAlias}}
+{{#if description}}
+/// {{description}}
 {{/if}}
+pub type {{name}} = {{{aliasType}}};
 
-{{#if isIntersectionType}}
+{{else}}
 {{#if description}}
 /// {{description}}
 {{/if}}
-{{#if intersectionMembers.length}}
-{{! Intersection type — flatten into a struct combining all members }}
 #[derive(Debug, Clone, Serialize, Deserialize)]
-#[serde(rename_all = "camelCase")]
 pub struct {{name}} {
-    {{#each intersectionMembers}}
-    // Fields from {{this}} are expected to be inlined by the code generator.
-    {{/each}}
-    // Intersection types require manual field specification.
-    // TODO: inline fields from {{join intersectionMembers ", "}}
-}
+{{#each properties}}
+{{#if description}}
+    /// {{description}}
+{{/if}}
+    #[serde(rename = "{{name}}"{{#if optional}}, skip_serializing_if = "Option::is_none"{{/if}})]
+    pub {{fieldName}}: {{targetType}},
+{{/each}}
+{{#if additionalType}}
+    #[serde(flatten)]
+    pub additional_properties: std::collections::HashMap<String, {{additionalType}}>,
 {{/if}}
+}
 {{/if}}
 
 {{/each}}

package/templates/typescript/domain-class.hbs

@@ -70,10 +70,12 @@ export class {{interfaceName}} {
       }
     }
 {{/if}}
-{{#if (or (hasRequestBody this) (needsRequestHeaders this))}}
+{{#if (or (hasRequestBody this) (needsRequestHeaders this) (sendsEmptyBody this))}}
     const sseHeaders: Record<string, string> = {};
 {{#if (hasRequestBody this)}}
     sseHeaders['Content-Type'] = '{{requestBody.contentType}}';
+{{else if (sendsEmptyBody this)}}
+    sseHeaders['Content-Type'] = 'application/json';
 {{/if}}
 {{#if (and headerParams.length headerType)}}
     if (headerOptions) {
@@ -98,14 +100,16 @@ export class {{interfaceName}} {
     }
 {{/if}}
 {{/if}}
-    return createSSEStream<{{#if sseReturnType}}{{sseReturnType}}{{else}}{{{sseEventType this}}}{{/if}}>(
+    return createSSEStream<{{#if sseReturnType}}{{sseReturnType}}{{else}}SSEEvent<{{{sseEventType this}}}>{{/if}}>(
       sseUrl.toString(),
       {
         method: '{{httpMethod}}',
 {{#if (hasRequestBody this)}}
         body: JSON.stringify(input),
+{{else if (sendsEmptyBody this)}}
+        body: '{}',
 {{/if}}
-{{#if (or (hasRequestBody this) (needsRequestHeaders this))}}
+{{#if (or (hasRequestBody this) (needsRequestHeaders this) (sendsEmptyBody this))}}
         headers: Object.keys(sseHeaders).length > 0 ? sseHeaders : undefined,
 {{/if}}
       },
@@ -133,9 +137,11 @@ export class {{interfaceName}} {
 {{else if queryType}}
     const params = query;
 {{/if}}
-{{#if (needsRequestHeaders this)}}
+{{#if (or (needsRequestHeaders this) (sendsEmptyBody this))}}
     const requestHeaders: Record<string, string> = {};
-{{#if (and (hasRequestBody this) (and (neq requestBody.contentType "application/json") (neq requestBody.contentType "multipart/form-data")))}}
+{{#if (sendsEmptyBody this)}}
+    requestHeaders['Content-Type'] = 'application/json';
+{{else 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)}}
@@ -167,11 +173,13 @@ export class {{interfaceName}} {
         url: `{{path}}`,
 {{#if (hasRequestBody this)}}
         data: input,
+{{else if (sendsEmptyBody this)}}
+        data: {},
 {{/if}}
 {{#if (or (hasQueryParams this) queryType)}}
         params,
 {{/if}}
-{{#if (needsRequestHeaders this)}}
+{{#if (or (needsRequestHeaders this) (sendsEmptyBody this))}}
         headers: Object.keys(requestHeaders).length > 0 ? requestHeaders : undefined,
 {{/if}}
       },

package/templates/typescript/domain.hbs

@@ -84,10 +84,12 @@ export function {{factoryName}}(transport: SDKTransport): {{interfaceName}} {
         }
       }
 {{/if}}
-{{#if (or (hasRequestBody this) (needsRequestHeaders this))}}
+{{#if (or (hasRequestBody this) (needsRequestHeaders this) (sendsEmptyBody this))}}
       const sseHeaders: Record<string, string> = {};
 {{#if (hasRequestBody this)}}
       sseHeaders['Content-Type'] = '{{requestBody.contentType}}';
+{{else if (sendsEmptyBody this)}}
+      sseHeaders['Content-Type'] = 'application/json';
 {{/if}}
 {{#if (and headerParams.length headerType)}}
       if (headerOptions) {
@@ -118,8 +120,10 @@ export function {{factoryName}}(transport: SDKTransport): {{interfaceName}} {
           method: '{{httpMethod}}',
 {{#if (hasRequestBody this)}}
           body: JSON.stringify(input),
+{{else if (sendsEmptyBody this)}}
+          body: '{}',
 {{/if}}
-{{#if (or (hasRequestBody this) (needsRequestHeaders this))}}
+{{#if (or (hasRequestBody this) (needsRequestHeaders this) (sendsEmptyBody this))}}
           headers: Object.keys(sseHeaders).length > 0 ? sseHeaders : undefined,
 {{/if}}
         },
@@ -142,9 +146,11 @@ export function {{factoryName}}(transport: SDKTransport): {{interfaceName}} {
 {{else if queryType}}
       const params = query;
 {{/if}}
-{{#if (needsRequestHeaders this)}}
+{{#if (or (needsRequestHeaders this) (sendsEmptyBody this))}}
       const requestHeaders: Record<string, string> = {};
-{{#if (and (hasRequestBody this) (and (neq requestBody.contentType "application/json") (neq requestBody.contentType "multipart/form-data")))}}
+{{#if (sendsEmptyBody this)}}
+      requestHeaders['Content-Type'] = 'application/json';
+{{else 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)}}
@@ -176,11 +182,13 @@ export function {{factoryName}}(transport: SDKTransport): {{interfaceName}} {
           url: `{{path}}`,
 {{#if (hasRequestBody this)}}
           data: input,
+{{else if (sendsEmptyBody this)}}
+          data: {},
 {{/if}}
 {{#if (or (hasQueryParams this) queryType)}}
           params,
 {{/if}}
-{{#if (needsRequestHeaders this)}}
+{{#if (or (needsRequestHeaders this) (sendsEmptyBody this))}}
           headers: Object.keys(requestHeaders).length > 0 ? requestHeaders : undefined,
 {{/if}}
         },

package/templates/typescript/package-json.hbs

@@ -24,6 +24,8 @@
   },
   "files": [
     "dist",
-    "README.md"
+    "docs",
+    "README.md",
+    "LICENSE"
   ]
 }

package/templates/typescript/readme.hbs

@@ -1,10 +1,8 @@
 # {{title}} SDK
 
-{{#if description}}
-{{description}}
+{{#if description}}{{description}}{{else}}TypeScript client for the {{title}} API.{{/if}}
 
-{{/if}}
-> This SDK was automatically generated by [Tesseract](https://www.npmjs.com/package/@apollo-deploy/tesseract).
+> Generated by [Tesseract](https://www.npmjs.com/package/@apollo-deploy/tesseract). Generated source files should not be edited manually.
 
 ## Installation
 
@@ -12,7 +10,7 @@
 npm install {{packageName}}
 ```
 
-## Quick Start
+## Quick start
 
 ```typescript
 import { create{{clientName}}Client } from '{{packageName}}';
@@ -20,66 +18,68 @@ import { create{{clientName}}Client } from '{{packageName}}';
 const client = create{{clientName}}Client({
   baseUrl: '{{baseUrl}}',
 {{#each securitySchemes}}
-  {{configKey}}: 'your-{{kebabCase name}}-credential',
+  {{configKey}}: process.env.{{upperCase (snakeCase configKey)}},
 {{/each}}
+  timeoutMs: 15_000,
 });
+
+{{#if groups.length}}
+// Domain clients are available directly on the client.
 const api = client.{{groups.[0].name}};
+{{/if}}
 ```
 
-## Request Options
+## Configuration and reliability
 
-```typescript
-import { create{{clientName}}Client } from '{{packageName}}';
+The generated transport supports:
 
-const client = create{{clientName}}Client();
+- Bounded request timeouts and `AbortSignal` cancellation
+- Exponential-backoff retries for transient failures
+- `Retry-After` handling for rate limits
+- Per-request headers, timeout, and retry overrides
+- Structured `SDKError` values with HTTP status, error code, and request ID
+- Request/response hooks and transport plugins for logging or telemetry
 
-const result = await client.{{groups.[0].name}}.{{groups.[0].operations.[0].name}}(
-  /* params */,
-  {
-    timeoutMs: 30_000,
-    headers: {
-      'X-Trace-Id': 'trace_123',
-    },
+```typescript
+const client = create{{clientName}}Client({
+  timeoutMs: 30_000,
+  defaultHeaders: { 'X-Application': 'my-service' },
+  retries: {
+    attempts: 3,
+    backoffMs: 400,
+    jitter: true,
   },
-);
+});
 ```
 
-## API Reference
-
-{{#each groups}}
-### {{interfaceName}}
+Mutating requests are retried only when the request is considered idempotent, carries an idempotency key, or the retry policy explicitly allows it.
 
-{{#if description}}
-{{description}}
+## Documentation
 
-{{/if}}
-| Method | HTTP | Path | Description |
-|--------|------|------|-------------|
-{{#each operations}}
-| `{{name}}` | {{httpMethod}} | `{{path}}` | {{#if description}}{{description}}{{else}}-{{/if}} |
-{{/each}}
-
-{{/each}}
-## Types
+- [Documentation index](./docs/README.md)
+- [Generated types](./docs/types.md)
 
-{{#each schemas}}
-{{#if isEnum}}
-- `{{name}}` — enum: {{#each enumValues}}`{{this}}`{{#unless @last}}, {{/unless}}{{/each}}
-{{else}}
-- `{{name}}`{{#if description}} — {{description}}{{/if}}
-{{/if}}
+| Domain | Description |
+|---|---|
+{{#each groups}}
+| [{{interfaceName}}](./docs/domains/{{fileName}}.md) | {{#if description}}{{description}}{{else}}{{name}} operations{{/if}} |
 {{/each}}
 
-## Error Handling
+## Error handling
 
 ```typescript
 import { SDKError } from '{{packageName}}';
 
 try {
-  const result = await client.someApi.someMethod();
+  // await client.someDomain.someOperation();
 } catch (error) {
   if (error instanceof SDKError) {
-    console.error(`Error ${error.status}: ${error.message} (${error.code})`);
+    console.error(error.status, error.code, error.requestId);
   }
+  throw error;
 }
 ```
+
+## License
+
+MIT

package/templates/typescript/transport.hbs

@@ -59,8 +59,12 @@ function calculateBackoff(attempt: number, baseMs: number, useJitter: boolean, m
 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) {
+  const header = error.response?.headers?.['retry-after'];
+  const rawRetryAfter = Array.isArray(header) ? header[0] : header;
+  if (
+    (typeof rawRetryAfter !== 'string' && typeof rawRetryAfter !== 'number') ||
+    String(rawRetryAfter).length === 0
+  ) {
     return undefined;
   }
 
@@ -71,7 +75,7 @@ function parseRetryAfterMs(error: unknown): number | undefined {
   }
 
   // Try HTTP-date format
-  const absoluteTime = Date.parse(rawRetryAfter);
+  const absoluteTime = Date.parse(String(rawRetryAfter));
   if (!Number.isNaN(absoluteTime)) {
     return Math.max(absoluteTime - Date.now(), 0);
   }
@@ -213,6 +217,11 @@ export interface TransportConfig {
    * Default: ['POST', 'PUT', 'PATCH', 'DELETE']
    */
   idempotentMethods?: string[];
+  /**
+   * HTTP methods eligible for automatic retries without an idempotency key.
+   * Default: ['GET', 'HEAD', 'OPTIONS', 'PUT', 'DELETE']
+   */
+  retryMethods?: string[];
 }
 
 // ── Telemetry Meta Types ────────────────────────────
@@ -244,6 +253,7 @@ export interface ResolvedTransportConfig extends TransportConfig {
   retries: RetryConfig;
   plugins: SDKPlugin[];
   idempotentMethods: string[];
+  retryMethods: string[];
 }
 
 /**
@@ -365,14 +375,16 @@ export function createTransport(config: TransportConfig): SDKTransport {
     },
     plugins: config.plugins ?? [],
     idempotentMethods: config.idempotentMethods ?? ['POST', 'PUT', 'PATCH', 'DELETE'],
+    retryMethods: config.retryMethods ?? ['GET', 'HEAD', 'OPTIONS', 'PUT', 'DELETE'],
   };
 
   const instance = axios.create({
     baseURL: resolvedConfig.baseUrl,
     timeout: resolvedConfig.timeoutMs,
     withCredentials: resolvedConfig.withCredentials ?? false,
+    // Content-Type is set per-request when a body is present (see domain methods).
+    // Avoid advertising application/json on GET/HEAD with no body.
     headers: {
-      'Content-Type': 'application/json',
       ...(resolvedConfig.defaultHeaders ?? {}),
     },
     ...resolvedConfig.axiosConfig,
@@ -483,6 +495,17 @@ export function createTransport(config: TransportConfig): SDKTransport {
 
 // ── Request Execution ───────────────────────────────
 
+function hasIdempotencyKey(headers: AxiosRequestConfig['headers']): boolean {
+  if (!headers) return false;
+  return Object.entries(headers as Record<string, unknown>).some(
+    ([name, value]) =>
+      name.toLowerCase() === 'x-idempotency-key' &&
+      value !== undefined &&
+      value !== null &&
+      String(value).length > 0,
+  );
+}
+
 /**
  * Execute an HTTP request with automatic retries and error mapping.
  */
@@ -545,9 +568,13 @@ export async function executeRequest<T>(
       const duration = startTime === undefined ? 0 : Date.now() - startTime;
 
       // Determine if we should retry
+      const method = (effectiveConfig.method ?? 'GET').toUpperCase();
+      const methodCanRetry =
+        transport.config.retryMethods.includes(method) ||
+        hasIdempotencyKey(effectiveConfig.headers);
       const shouldRetry = retries.shouldRetry
         ? retries.shouldRetry(sdkError, attempt)
-        : sdkError.isRetryable();
+        : methodCanRetry && sdkError.isRetryable();
 
       const willRetry = attempt < maxAttempts && shouldRetry;
 
@@ -578,7 +605,7 @@ export async function executeRequest<T>(
       let delayMs: number;
 
       if (sdkError.status === 429 && retryAfterMs !== undefined) {
-        delayMs = retryAfterMs;
+        delayMs = Math.min(retryAfterMs, maxBackoff);
       } else {
         delayMs = calculateBackoff(attempt, retries.backoffMs, retries.jitter, maxBackoff);
       }
@@ -648,15 +675,26 @@ function mapAxiosError(error: unknown): SDKError {
 
   const status = error.response.status;
   const data = error.response.data as any;
+  const headerRequestId =
+    error.response.headers?.['x-request-id'] ??
+    error.response.headers?.['request-id'];
+  const requestId = Array.isArray(headerRequestId)
+    ? headerRequestId[0]
+    : typeof headerRequestId === 'string'
+      ? headerRequestId
+      : undefined;
 
   if (data && typeof data === 'object' && typeof data.error === 'string' && typeof data.message === 'string') {
-    return new SDKError(data as ApiErrorEnvelope, status);
+    return new SDKError(
+      { ...data, request_id: data.request_id ?? requestId } as ApiErrorEnvelope,
+      status,
+    );
   }
 
   return new SDKError(
     data?.message || error.message || resolveMessage(status),
     status,
     data?.error || resolveErrorCode(status),
-    data?.request_id,
+    data?.request_id ?? requestId,
   );
 }

package/templates/typescript/types-errors.hbs

@@ -167,7 +167,7 @@ export class SDKError extends Error {
 
   /** Check if this error is retryable */
   isRetryable(): boolean {
-    return this.code === 'network_error' || this.code === 'gateway_timeout' || this.status === 429 || this.status >= 500;
+    return this.code === 'network_error' || this.code === 'gateway_timeout' || this.status === 408 || this.status === 425 || this.status === 429 || this.status >= 500;
   }
 
   /** Convert to a plain object for logging/serialization */

package/dist/adapters/typescript/model-emitter.d.ts

@@ -1,13 +0,0 @@
-/**
- * TypeScript model emitter (ts-morph based).
- *
- * Emits schema definitions as TypeScript interfaces, type aliases,
- * and enums using ts-morph AST construction.
- */
-import type { EnrichedSDKIR } from '../../types/ir.js';
-import type { EmittedFile } from '../../pipeline/write.js';
-export declare function emitTypeScriptModels(enriched: EnrichedSDKIR, outputDir: string): {
-    files: EmittedFile[];
-    domainTypeFiles: string[];
-};
-//# sourceMappingURL=model-emitter.d.ts.map

package/dist/adapters/typescript/model-emitter.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"model-emitter.d.ts","sourceRoot":"","sources":["../../../src/adapters/typescript/model-emitter.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AASH,OAAO,KAAK,EAAE,aAAa,EAAoC,MAAM,mBAAmB,CAAC;AACzF,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAE3D,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,aAAa,EACvB,SAAS,EAAE,MAAM,GAChB;IAAE,KAAK,EAAE,WAAW,EAAE,CAAC;IAAC,eAAe,EAAE,MAAM,EAAE,CAAA;CAAE,CAmErD"}