@sdk-it/typescript 0.45.0 → 0.46.1

package/README.md

@@ -1,103 +1,121 @@
 # @sdk-it/typescript
 
-<p align="center">A type-safe SDK generator that converts OpenAPI specifications into TypeScript client.</p>
+Generate a fully typed TypeScript client from an OpenAPI document. Generated
+clients work in Node.js, browsers, and other JavaScript runtimes with `fetch`.
 
-## Description
-
-This package transforms OpenAPI specifications into
-
-- a fully-typed TypeScript client
-- that works in Node.js, browsers, and any JavaScript runtime
-- with the ability to control the structure, style, and formatting of generated code
-
-## Installation
+## Install
 
 ```bash
-npm install @sdk-it/typescript
+npm install --save-dev @sdk-it/typescript
+npm install zod fast-content-type-parse
 ```
 
-## Usage
+`zod` and `fast-content-type-parse` are runtime dependencies of clients
+generated in `minimal` mode.
 
-### Basic SDK Generation
+## Generate from an OpenAPI document
 
 ```typescript
 import { generate } from '@sdk-it/typescript';
 
-import spec from './openapi.json';
+const spec = await fetch('https://api.openstatus.dev/v1/openapi').then(
+  (response) => response.json(),
+);
 
 await generate(spec, {
-  output: './client',
-  name: 'MyAPI',
+  output: './src/generated/openstatus',
+  mode: 'minimal',
+  name: 'OpenStatus',
 });
 ```
 
-### Remote Spec Example
+`name` controls the generated client class name. `minimal` mode writes client
+source files directly to `output`.
+
+## Use the generated client
 
 ```typescript
-import { generate } from '@sdk-it/typescript';
+import { OpenStatus } from './src/generated/openstatus/index.ts';
 
-// Fetch remote OpenAPI specification
-const spec = await fetch('https://api.openstatus.dev/v1/openapi').then((res) =>
-  res.json(),
-);
+const client = new OpenStatus({
+  baseUrl: 'https://api.openstatus.dev/v1',
+  'x-openstatus-key': process.env.OPENSTATUS_API_KEY,
+});
 
-// Generate client SDK
-await generate(spec, {
-  output: './client',
-  name: 'OpenStatus',
+const reports = await client.request('GET /status_report', {});
+console.log(reports);
+```
+
+`request` returns unwrapped response data. It throws `ParseError` when input
+validation fails and an `APIError` subclass when the server returns a
+non-successful response:
+
+```typescript
+import {
+  APIError,
+  OpenStatus,
+  ParseError,
+} from './src/generated/openstatus/index.ts';
+
+const client = new OpenStatus({
+  baseUrl: 'https://api.openstatus.dev/v1',
+  'x-openstatus-key': process.env.OPENSTATUS_API_KEY,
 });
+
+try {
+  const report = await client.request('GET /status_report/{id}', { id: '42' });
+  console.log(report);
+} catch (error) {
+  if (error instanceof ParseError) {
+    console.error(error.data);
+  } else if (error instanceof APIError) {
+    console.error(error.status, error.data);
+  } else {
+    throw error;
+  }
+}
 ```
 
-### Format Generated Code
+## Format generated code
 
-You can format the generated code using the `formatCode` option. Useful when committing generated code to source control.
+`formatCode` runs after generation and receives the actual source directory plus
+an environment with local package executables on `PATH`:
 
 ```typescript
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+
 import { generate } from '@sdk-it/typescript';
 
+const execFileAsync = promisify(execFile);
 const spec = await fetch('https://petstore.swagger.io/v2/swagger.json').then(
-  (res) => res.json(),
+  (response) => response.json(),
 );
 
-// Format generated code using Prettier
 await generate(spec, {
-  output: join(process.cwd(), 'node_modules/.sdk-it/client'),
-  formatCode: ({ output, env }) => {
-    execFile('prettier', [output, '--write'], { env: env });
+  output: './src/generated/petstore',
+  name: 'PetStore',
+  formatCode: async ({ output, env }) => {
+    await execFileAsync('prettier', [output, '--write'], { env });
   },
 });
 ```
 
-### Run the script
+## Generate a standalone project
 
-```bash
-# using recent versions of node
-node ./openapi.ts
-
-# using node < 22
-npx tsx ./openapi.ts
-
-# using bun
-bun ./openapi.ts
-```
-
-- Use the generated SDK
+`full` mode adds `package.json` and `tsconfig.json`, places generated source
+under `<output>/src`, and records the generated client's runtime dependencies:
 
 ```typescript
-import { OpenStatus } from './client';
-
-const client = new OpenStatus({
-  baseUrl: 'https://api.openstatus.dev/v1/',
+await generate(spec, {
+  output: './generated/petstore',
+  mode: 'full',
+  name: 'PetStore',
+  packageName: '@acme/petstore',
 });
-
-const [result, error] = await client.request('GET /status_report', {});
 ```
 
-## Using with Your Favorite Frameworks
-
-The SDK works on its own, but you might want native integration with your frameworks:
+## Framework integrations
 
 - [React Query](../../docs/react-query.md)
 - [Angular](../../docs/angular.md)
-
-Let us know what you're using, and we'll help you integrate it.

package/dist/index.js

@@ -66,7 +66,7 @@ function createTool(entry, operation) {
       inputSchema: schemas.${schemaName},
 			execute: async (input, options) => {
 				console.log('Executing ${operation.operationId} tool with input:', input);
-        const context = coerceContext(options.experimental_context);
+        const context = coerceContext(options.context);
         const response = await context.client.request(
           '${entry.method.toUpperCase()} ${entry.path}' ,
           input,
@@ -117,13 +117,13 @@ function createTool2(entry, operation) {
 }
 
 // packages/typescript/src/lib/agent/utils.txt
-var utils_default = "function coerceContext(context?: any) {\n  if (!context) {\n    throw new Error('Context is required');\n  }\n  return context as {\n    client: any\n  };\n}\n/**\n * Takes a Zod object schema and makes all optional properties nullable as well.\n * This is useful for APIs where optional fields can be explicitly set to null.\n *\n * @param schema - The Zod object schema to transform\n * @returns A new Zod schema with optional properties made nullable\n */\nfunction makeOptionalPropsNullable<T extends z.ZodRawShape>(\n  schema: z.ZodObject<T>,\n) {\n  const shape = schema.shape;\n  const newShape = {} as Record<string, z.ZodType>;\n\n  for (const [key, value] of Object.entries(shape)) {\n    if (value instanceof z.ZodOptional) {\n      // Make optional properties also nullable\n      newShape[key] = value.unwrap().nullable().optional();\n    } else {\n      // Keep non-optional properties as they are\n      newShape[key] = value;\n    }\n  }\n\n  return z.object(newShape);\n}";
+var utils_default = "function coerceContext(context?: any) {\n  if (!context) {\n    throw new Error('Context is required');\n  }\n  return context as {\n    client: any\n  };\n}\n/**\n * Takes a Zod object schema and makes all optional properties nullable as well.\n * This is useful for APIs where optional fields can be explicitly set to null.\n *\n * @param schema - The Zod object schema to transform\n * @returns A new Zod schema with optional properties made nullable\n */\nfunction makeOptionalPropsNullable<T extends z.ZodRawShape>(\n  schema: z.ZodObject<T>,\n) {\n  const shape = schema.shape;\n  const newShape = {} as Record<string, z.ZodType>;\n\n  for (const [key, value] of Object.entries(shape) as [string, z.ZodType][]) {\n    if (value instanceof z.ZodOptional) {\n      // Make optional properties also nullable\n      newShape[key] = value.nullable();\n    } else {\n      // Keep non-optional properties as they are\n      newShape[key] = value;\n    }\n  }\n\n  return z.object(newShape);\n}\n";
 
 // packages/typescript/src/lib/client.ts
 import { toLitObject } from "@sdk-it/core";
 
 // packages/typescript/src/lib/emitters/zod.ts
-import { followRef, isRef, parseRef, pascalcase } from "@sdk-it/core";
+import { followRef, isEmpty, isRef, parseRef, pascalcase } from "@sdk-it/core";
 import { isPrimitiveSchema, sanitizeTag } from "@sdk-it/spec";
 var ZodEmitter = class {
   #generatedRefs = /* @__PURE__ */ new Set();
@@ -344,6 +344,9 @@ var ZodEmitter = class {
     if (isRef(schema)) {
       return `${this.#ref(schema.$ref, true)}${appendOptional(required)}`;
     }
+    if (schema.not && isEmpty(schema.not)) {
+      return `z.never()${appendOptional(required)}`;
+    }
     if (schema.allOf && Array.isArray(schema.allOf)) {
       return this.allOf(schema.allOf ?? [], required);
     }
@@ -619,7 +622,14 @@ export async function prepare<const E extends keyof typeof schemas>(
 };
 
 // packages/typescript/src/lib/emitters/interface.ts
-import { followRef as followRef2, isRef as isRef2, parseRef as parseRef2, pascalcase as pascalcase2, resolveRef } from "@sdk-it/core";
+import {
+  followRef as followRef2,
+  isEmpty as isEmpty2,
+  isRef as isRef2,
+  parseRef as parseRef2,
+  pascalcase as pascalcase2,
+  resolveRef
+} from "@sdk-it/core";
 import { isPrimitiveSchema as isPrimitiveSchema2, sanitizeTag as sanitizeTag2 } from "@sdk-it/spec";
 var TypeScriptEmitter = class {
   #spec;
@@ -629,7 +639,7 @@ var TypeScriptEmitter = class {
   #stringifyKey = (value) => {
     return `'${value}'`;
   };
-  object(schema, required = false) {
+  object(schema, _required = false) {
     const properties = schema.properties || {};
     const propEntries = Object.entries(properties).map(([key, propSchema]) => {
       const isRequired = (schema.required ?? []).includes(key);
@@ -649,7 +659,7 @@ var TypeScriptEmitter = class {
   /**
    * Handle arrays (items could be a single schema or a tuple)
    */
-  #array(schema, required = false) {
+  #array(schema, _required = false) {
     const { items } = schema;
     if (!items) {
       return "any[]";
@@ -759,6 +769,9 @@ var TypeScriptEmitter = class {
     if (isRef2(schema)) {
       return this.#ref(schema.$ref, required);
     }
+    if (schema.not && isEmpty2(schema.not)) {
+      return appendOptional2("never", required);
+    }
     if (schema.allOf && Array.isArray(schema.allOf)) {
       return this.allOf(schema.allOf);
     }
@@ -801,14 +814,14 @@ function appendOptional2(type, isRequired) {
 import { merge, template } from "lodash-es";
 import { join } from "node:path";
 import { camelcase as camelcase4, spinalcase as spinalcase2 } from "stringcase";
-import { followRef as followRef3, isEmpty as isEmpty2, isRef as isRef3, resolveRef as resolveRef2, sortArray } from "@sdk-it/core";
+import { followRef as followRef3, isEmpty as isEmpty4, isRef as isRef3, resolveRef as resolveRef2, sortArray } from "@sdk-it/core";
 import {
   forEachOperation as forEachOperation3
 } from "@sdk-it/spec";
 
 // packages/typescript/src/lib/sdk.ts
 import { camelcase as camelcase3 } from "stringcase";
-import { isEmpty, pascalcase as pascalcase3 } from "@sdk-it/core";
+import { isEmpty as isEmpty3, pascalcase as pascalcase3 } from "@sdk-it/core";
 import {
   isBinaryContentType,
   isSseContentType,
@@ -855,9 +868,7 @@ function describe(p) {
         nextPageMapping: `${p.pageNumberParamName}: nextPageParams.page, ${p.pageSizeParamName}: nextPageParams.pageSize`
       };
   }
-  throw new Error(
-    `Unknown pagination type: ${p.type}`
-  );
+  throw new Error(`Unknown pagination type: ${p.type}`);
 }
 function paginationOperation(pagination) {
   const shape = describe(pagination);
@@ -963,7 +974,7 @@ function normalOperation() {
 function toHttpOutput(spec, operationName, status, response, withGenerics = true) {
   const typeScriptDeserialzer = new TypeScriptEmitter(spec);
   const interfaceName = pascalcase3(sanitizeTag3(response["x-response-name"]));
-  if (!isEmpty(response.content)) {
+  if (!isEmpty3(response.content)) {
     const contentTypeResult = fromContentType(typeScriptDeserialzer, response);
     if (!contentTypeResult) {
       throw new Error(
@@ -1086,7 +1097,7 @@ function coearceRequestInput(spec, operation, type) {
   if (type === "application/empty") {
     objectSchema = {
       type: "object",
-      additionalProperties: isEmpty2(xProperties)
+      additionalProperties: isEmpty4(xProperties)
     };
   } else {
     if (objectSchema.type !== "object") {
@@ -1356,7 +1367,7 @@ var offset_pagination_default = "type OffsetPaginationParams = {\n  offset: numb
 var page_pagination_default = "type InferPage<T> = T extends Page<infer U> ? U : never;\ntype PaginationParams<P extends number | bigint, S extends number | bigint> = {\n  page?: P;\n  pageSize?: S;\n};\n\ninterface Metadata {\n  hasMore?: boolean;\n}\n\ntype PaginationRequestOptions = {\n  signal?: AbortSignal;\n};\n\ntype PaginationResult<T, M extends Metadata> = {\n  data: T[];\n  meta: M;\n};\n\ntype FetchFn<\n  T,\n  M extends Metadata,\n  P extends number | bigint,\n  S extends number | bigint,\n> = (\n  input: Partial<PaginationParams<P, S>>,\n  requestOptions?: PaginationRequestOptions,\n) => Promise<PaginationResult<T, M>>;\n\n/**\n * @experimental\n */\nexport class Pagination<\n  T,\n  M extends Metadata,\n  P extends number | bigint,\n  S extends number | bigint,\n> {\n  #meta: PaginationResult<T, M>['meta'] | null = null;\n  #params: PaginationParams<P, S>;\n  #currentPage: Page<T> | null = null;\n  readonly #fetchFn: FetchFn<T, M, P, S>;\n  readonly #requestOptions: PaginationRequestOptions;\n\n  constructor(\n    initialParams: Partial<PaginationParams<P, S>>,\n    fetchFn: FetchFn<T, M, P, S>,\n    requestOptions: PaginationRequestOptions = {},\n  ) {\n    this.#fetchFn = fetchFn;\n    this.#requestOptions = requestOptions;\n    this.#params = { ...initialParams, page: initialParams.page };\n  }\n\n  async getNextPage(requestOptions?: PaginationRequestOptions) {\n    const result = await this.#fetchFn(this.#params, {\n      ...this.#requestOptions,\n      ...requestOptions,\n    });\n    this.#currentPage = new Page(result.data);\n    this.#meta = result.meta;\n    this.#params = {\n      ...this.#params,\n      page: (((this.#params.page as number) || 0) + 1) as never,\n    };\n    return this;\n  }\n\n  getCurrentPage() {\n    if (!this.#currentPage) {\n      throw new Error(\n        'No page data available. Please call getNextPage() first.',\n      );\n    }\n    return this.#currentPage;\n  }\n\n  get hasMore() {\n    if (!this.#meta) {\n      throw new Error(\n        'No meta data available. Please call getNextPage() first.',\n      );\n    }\n    return this.#meta.hasMore;\n  }\n\n  async *[Symbol.asyncIterator]() {\n    for await (const page of this.iter()) {\n      yield page.getCurrentPage();\n    }\n  }\n\n  async *iter(requestOptions?: PaginationRequestOptions) {\n    if (!this.#currentPage) {\n      yield await this.getNextPage(requestOptions);\n    }\n\n    while (this.hasMore) {\n      yield await this.getNextPage(requestOptions);\n    }\n  }\n\n  get metadata() {\n    if (!this.#meta) {\n      throw new Error(\n        'No meta data available. Please call getNextPage() first.',\n      );\n    }\n    return this.#meta;\n  }\n}\n\nclass Page<T> {\n  data: T[];\n  constructor(data: T[]) {\n    this.data = data;\n  }\n}\n";
 
 // packages/typescript/src/lib/readme/readme.ts
-import { isEmpty as isEmpty3 } from "@sdk-it/core";
+import { isEmpty as isEmpty5 } from "@sdk-it/core";
 import { forEachOperation as forEachOperation4 } from "@sdk-it/spec";
 
 // packages/typescript/src/lib/readme/prop.emitter.ts
@@ -1684,7 +1695,7 @@ function toReadme(spec, generator) {
     markdown.push(`#### Output`);
     for (const status in operation.responses) {
       const response = operation.responses[status];
-      if (!isEmpty3(response.content)) {
+      if (!isEmpty5(response.content)) {
         const contentEntries = Object.entries(response.content);
         if (contentEntries.length === 1) {
           const [contentType, mediaType] = contentEntries[0];
@@ -1768,7 +1779,7 @@ function expandServerUrls(servers) {
 
 // packages/typescript/src/lib/typescript-snippet.ts
 import { camelcase as camelcase5, spinalcase as spinalcase3 } from "stringcase";
-import { isEmpty as isEmpty4, pascalcase as pascalcase4, resolveRef as resolveRef4 } from "@sdk-it/core";
+import { isEmpty as isEmpty6, pascalcase as pascalcase4, resolveRef as resolveRef4 } from "@sdk-it/core";
 import "@sdk-it/readme";
 import {
   forEachOperation as forEachOperation5,
@@ -1979,7 +1990,7 @@ var TypeScriptSnippet = class {
   }
   succinct(entry, operation, values) {
     let payload = "{}";
-    if (!isEmpty4(operation.requestBody)) {
+    if (!isEmpty6(operation.requestBody)) {
       const contentTypes = Object.keys(operation.requestBody.content || {});
       const schema = resolveRef4(
         this.#spec,
@@ -2041,7 +2052,7 @@ var TypeScriptSnippet = class {
         return this.#streamDownload(entry, payload);
       }
     }
-    if (!isEmpty4(operation["x-pagination"])) {
+    if (!isEmpty6(operation["x-pagination"])) {
       return this.#pagination(operation, entry, payload);
     }
     return this.#normal(entry, payload);
@@ -2125,7 +2136,7 @@ const result = await ${camelcase5(this.#clientName)}.request('${entry.method.toU
       baseUrl: expandServerUrls(this.#spec.servers ?? [])[0] ?? "http://localhost:3000"
     };
     const authOptions = this.#authentication();
-    if (!isEmpty4(authOptions)) {
+    if (!isEmpty6(authOptions)) {
       const [firstAuth] = authOptions;
       const optionName = firstAuth["x-optionName"] ?? firstAuth.name;
       options[optionName] = firstAuth.example;
@@ -2165,7 +2176,7 @@ ${client.use}`;
     );
     const baseUrl = expandServerUrls(this.#spec.servers ?? [])[0] || "https://api.example.com";
     const authOptions = this.#authentication();
-    const hasApiKey = !isEmpty4(authOptions);
+    const hasApiKey = !isEmpty6(authOptions);
     sections.push("### Configuration Options");
     sections.push("");
     sections.push("| Option | Type | Required | Description |");
@@ -2550,7 +2561,7 @@ ${client.use}`;
   }
   authenticationDocs() {
     const authOptions = this.#authentication();
-    if (isEmpty4(authOptions)) {
+    if (isEmpty6(authOptions)) {
       return "";
     }
     const sections = [];
@@ -2632,7 +2643,7 @@ ${client.use}`;
     const initialClientOptions = {
       baseUrl: "https://api.production-service.com"
     };
-    if (!isEmpty4(authOptions)) {
+    if (!isEmpty6(authOptions)) {
       const [primaryAuth] = authOptions;
       const authOptionName = primaryAuth["x-optionName"] ?? primaryAuth.name;
       initialClientOptions[authOptionName] = "YOUR_PRODUCTION_TOKEN";
@@ -2646,7 +2657,7 @@ ${client.use}`;
       "client.setOptions({",
       "  baseUrl: 'https://api.staging-service.com',"
     ];
-    if (!isEmpty4(authOptions)) {
+    if (!isEmpty6(authOptions)) {
       const [primaryAuth] = authOptions;
       const authOptionName = primaryAuth["x-optionName"] ?? primaryAuth.name;
       configurationUpdateCode.push(`  ${authOptionName}: 'YOUR_STAGING_TOKEN'`);
@@ -2695,7 +2706,7 @@ function availablePaginationTypes(spec) {
 
 // packages/typescript/src/lib/generate.ts
 async function generate(openapi, settings) {
-  const spec = toIR(
+  const spec = await toIR(
     {
       spec: openapi,
       responses: { flattenErrorResponses: true },
@@ -2860,6 +2871,7 @@ ${utils_default}`
             name: packageName,
             version: "0.0.1",
             type: "module",
+            ...settings.agentTools === "ai-sdk" ? { engines: { node: ">=22" } } : {},
             main: "./src/index.ts",
             module: "./src/index.ts",
             types: "./src/index.ts",
@@ -2876,7 +2888,9 @@ ${utils_default}`
             },
             dependencies: {
               "fast-content-type-parse": "^3.0.0",
-              zod: "^4.3.0"
+              zod: "^4.3.0",
+              ...settings.agentTools === "ai-sdk" ? { ai: "^7.0.29" } : {},
+              ...settings.agentTools === "openai-agents" ? { "@openai/agents": "^0.13.4" } : {}
             }
           },
           null,