@sdk-it/typescript 0.25.0 → 0.27.0

package/dist/index.js

@@ -10,7 +10,6 @@ import {
   getFolderExports,
   writeFiles
 } from "@sdk-it/core/file-system.js";
-import { toReadme } from "@sdk-it/readme";
 import {
   augmentSpec,
   cleanFiles,
@@ -159,10 +158,10 @@ var ZodEmitter = class {
     switch (schema.format) {
       case "date-time":
       case "datetime":
-        base = "z.coerce.date()";
+        base = "z.string().datetime()";
         break;
       case "date":
-        base = "z.coerce.date() /* or z.string() if you want raw date strings */";
+        base = "z.coerce.date()";
         break;
       case "time":
         base = "z.string() /* optionally add .regex(...) for HH:MM:SS format */";
@@ -931,8 +930,8 @@ function generateCode(config) {
   const endpoints = {};
   forEachOperation(config.spec, (entry, operation) => {
     console.log(`Processing ${entry.method} ${entry.path}`);
-    groups[entry.groupName] ??= [];
-    endpoints[entry.groupName] ??= [];
+    groups[entry.tag] ??= [];
+    endpoints[entry.tag] ??= [];
     const inputs = {};
     const schemas = {};
     const shortContenTypeMap = {
@@ -1001,7 +1000,7 @@ function generateCode(config) {
       outgoingContentType = "formdata";
     }
     const endpoint = toEndpoint(
-      entry.groupName,
+      entry.tag,
       config.spec,
       operation,
       {
@@ -1014,8 +1013,8 @@ function generateCode(config) {
       },
       { makeImport: config.makeImport, style: config.style }
     );
-    endpoints[entry.groupName].push(endpoint);
-    groups[entry.groupName].push({
+    endpoints[entry.tag].push(endpoint);
+    groups[entry.tag].push({
       name: operation.operationId,
       inputs,
       outgoingContentType,
@@ -1594,16 +1593,397 @@ var offset_pagination_default = "type OffsetPaginationParams = {\n  offset: numb
 // packages/typescript/src/lib/paginations/page-pagination.txt
 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 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> = (input: Partial<PaginationParams<P, S>>) => 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\n  constructor(\n    initialParams: Partial<PaginationParams<P, S>>,\n    fetchFn: FetchFn<T, M, P, S>,\n  ) {\n    this.#fetchFn = fetchFn;\n    this.#params = { ...initialParams, page: initialParams.page };\n  }\n\n  async getNextPage() {\n    const result = await this.#fetchFn(this.#params);\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() {\n    if (!this.#currentPage) {\n      yield await this.getNextPage();\n    }\n\n    while (this.hasMore) {\n      yield await this.getNextPage();\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 { forEachOperation as forEachOperation2 } from "@sdk-it/spec";
+
+// packages/typescript/src/lib/readme/prop.emitter.ts
+import { followRef as followRef4, isRef as isRef4 } from "@sdk-it/core";
+import { coerceTypes } from "@sdk-it/spec";
+var PropEmitter = class {
+  #spec;
+  constructor(spec) {
+    this.#spec = spec;
+  }
+  /**
+   * Handle objects (properties)
+   */
+  #object(schema) {
+    const lines = [];
+    const properties = schema.properties || {};
+    if (Object.keys(properties).length > 0) {
+      lines.push(`**Properties:**`);
+      for (const [propName, propSchema] of Object.entries(properties)) {
+        const isRequired = (schema.required ?? []).includes(propName);
+        lines.push(...this.#property(propName, propSchema, isRequired));
+      }
+    }
+    if (schema.additionalProperties) {
+      lines.push(`**Additional Properties:**`);
+      if (typeof schema.additionalProperties === "boolean") {
+        lines.push(`- Allowed: ${schema.additionalProperties}`);
+      } else {
+        lines.push(
+          ...this.handle(schema.additionalProperties).map((l) => `  ${l}`)
+        );
+      }
+    }
+    return lines;
+  }
+  /**
+   * Format a property with its type and description
+   */
+  #property(name, schema, required) {
+    const docs = this.handle(schema);
+    const rawType = docs[0].replace("**Type:** ", "").replace(" (nullable)", "|null");
+    const defaultVal = !isRef4(schema) && schema.default !== void 0 ? ` default: ${JSON.stringify(schema.default)}` : "";
+    const reqMark = required ? " required" : "";
+    const summary = `- \`${name}\` ${rawType}${reqMark}${defaultVal}:`;
+    const detailLines = docs.slice(1).filter((l) => !l.startsWith("**Default:**")).map((l) => `  ${l}`);
+    return [summary, ...detailLines];
+  }
+  /**
+   * Handle array schemas
+   */
+  #array(schema) {
+    const lines = [];
+    lines.push(`**Array items:**`);
+    if (schema.items) {
+      const itemDocs = this.handle(schema.items);
+      lines.push(...itemDocs.map((line) => `  ${line}`));
+    } else {
+      lines.push(`  **Type:** \`unknown\``);
+    }
+    if (schema.minItems !== void 0)
+      lines.push(`- Minimum items: ${schema.minItems}`);
+    if (schema.maxItems !== void 0)
+      lines.push(`- Maximum items: ${schema.maxItems}`);
+    if (schema.uniqueItems) lines.push(`- Items must be unique.`);
+    return lines;
+  }
+  #ref($ref) {
+    const schemaName = $ref.split("/").pop() || "object";
+    const resolved = followRef4(this.#spec, $ref);
+    const lines = [
+      `**Type:** [\`${schemaName}\`](#${schemaName.toLowerCase()})`
+    ];
+    if (resolved.description) {
+      lines.push(resolved.description);
+    }
+    return lines;
+  }
+  #allOf(schemas) {
+    const lines = ["**All of (Intersection):**"];
+    schemas.forEach((subSchema, index) => {
+      lines.push(`- **Constraint ${index + 1}:**`);
+      const subLines = this.handle(subSchema);
+      lines.push(...subLines.map((l) => `  ${l}`));
+    });
+    return lines;
+  }
+  #anyOf(schemas) {
+    const lines = ["**Any of (Union):**"];
+    schemas.forEach((subSchema, index) => {
+      lines.push(`- **Option ${index + 1}:**`);
+      const subLines = this.handle(subSchema);
+      lines.push(...subLines.map((l) => `  ${l}`));
+    });
+    return lines;
+  }
+  #oneOf(schemas) {
+    const lines = ["**One of (Exclusive Union):**"];
+    schemas.forEach((subSchema, index) => {
+      lines.push(`- **Option ${index + 1}:**`);
+      const subLines = this.handle(subSchema);
+      lines.push(...subLines.map((l) => `  ${l}`));
+    });
+    return lines;
+  }
+  #enum(schema) {
+    const lines = [`**Type:** \`${schema.type || "unknown"}\` (enum)`];
+    if (schema.description) lines.push(schema.description);
+    lines.push("**Allowed values:**");
+    lines.push(
+      ...(schema.enum || []).map((val) => `- \`${JSON.stringify(val)}\``)
+    );
+    if (schema.default !== void 0) {
+      lines.push(`**Default:** \`${JSON.stringify(schema.default)}\``);
+    }
+    return lines;
+  }
+  #normal(type, schema, nullable) {
+    const lines = [];
+    const nullableSuffix = nullable ? " (nullable)" : "";
+    const description = schema.description ? [schema.description] : [];
+    switch (type) {
+      case "string":
+        lines.push(
+          `**Type:** \`string\`${schema.format ? ` (format: ${schema.format})` : ""}${nullableSuffix}`
+        );
+        lines.push(...description);
+        if (schema.minLength !== void 0)
+          lines.push(`- Minimum length: ${schema.minLength}`);
+        if (schema.maxLength !== void 0)
+          lines.push(`- Maximum length: ${schema.maxLength}`);
+        if (schema.pattern !== void 0)
+          lines.push(`- Pattern: \`${schema.pattern}\``);
+        break;
+      case "number":
+      case "integer":
+        lines.push(
+          `**Type:** \`${type}\`${schema.format ? ` (format: ${schema.format})` : ""}${nullableSuffix}`
+        );
+        lines.push(...description);
+        if (schema.minimum !== void 0) {
+          const exclusiveMin = typeof schema.exclusiveMinimum === "number";
+          lines.push(
+            `- Minimum: ${schema.minimum}${exclusiveMin ? " (exclusive)" : ""}`
+          );
+          if (exclusiveMin) {
+            lines.push(
+              `- Must be strictly greater than: ${schema.exclusiveMinimum}`
+            );
+          }
+        } else if (typeof schema.exclusiveMinimum === "number") {
+          lines.push(
+            `- Must be strictly greater than: ${schema.exclusiveMinimum}`
+          );
+        }
+        if (schema.maximum !== void 0) {
+          const exclusiveMax = typeof schema.exclusiveMaximum === "number";
+          lines.push(
+            `- Maximum: ${schema.maximum}${exclusiveMax ? " (exclusive)" : ""}`
+          );
+          if (exclusiveMax) {
+            lines.push(
+              `- Must be strictly less than: ${schema.exclusiveMaximum}`
+            );
+          }
+        } else if (typeof schema.exclusiveMaximum === "number") {
+          lines.push(
+            `- Must be strictly less than: ${schema.exclusiveMaximum}`
+          );
+        }
+        if (schema.multipleOf !== void 0)
+          lines.push(`- Must be a multiple of: ${schema.multipleOf}`);
+        break;
+      case "boolean":
+        lines.push(`**Type:** \`boolean\`${nullableSuffix}`);
+        lines.push(...description);
+        break;
+      case "object":
+        lines.push(`**Type:** \`object\`${nullableSuffix}`);
+        lines.push(...description);
+        lines.push(...this.#object(schema));
+        break;
+      case "array":
+        lines.push(`**Type:** \`array\`${nullableSuffix}`);
+        lines.push(...description);
+        lines.push(...this.#array(schema));
+        break;
+      case "null":
+        lines.push(`**Type:** \`null\``);
+        lines.push(...description);
+        break;
+      default:
+        lines.push(`**Type:** \`${type}\`${nullableSuffix}`);
+        lines.push(...description);
+    }
+    if (schema.default !== void 0) {
+      lines.push(`**Default:** \`${JSON.stringify(schema.default)}\``);
+    }
+    return lines.filter((l) => l);
+  }
+  /**
+   * Handle schemas by resolving references and delegating to appropriate handler
+   */
+  handle(schemaOrRef) {
+    if (isRef4(schemaOrRef)) {
+      return this.#ref(schemaOrRef.$ref);
+    }
+    const schema = schemaOrRef;
+    if (schema.allOf && Array.isArray(schema.allOf)) {
+      return this.#allOf(schema.allOf);
+    }
+    if (schema.anyOf && Array.isArray(schema.anyOf)) {
+      return this.#anyOf(schema.anyOf);
+    }
+    if (schema.oneOf && Array.isArray(schema.oneOf)) {
+      return this.#oneOf(schema.oneOf);
+    }
+    if (schema.enum && Array.isArray(schema.enum)) {
+      return this.#enum(schema);
+    }
+    let types = coerceTypes(schema);
+    let nullable = false;
+    if (types.includes("null")) {
+      nullable = true;
+      types = types.filter((t) => t !== "null");
+    }
+    if (types.length === 0) {
+      if (schema.properties || schema.additionalProperties) {
+        types = ["object"];
+      } else if (schema.items) {
+        types = ["array"];
+      }
+    }
+    if (types.length === 0) {
+      const lines2 = ["**Type:** `unknown`"];
+      if (schema.description) lines2.push(schema.description);
+      if (schema.default !== void 0)
+        lines2.push(`**Default:** \`${JSON.stringify(schema.default)}\``);
+      return lines2;
+    }
+    if (types.length === 1) {
+      return this.#normal(types[0], schema, nullable);
+    }
+    const typeString = types.join(" | ");
+    const nullableSuffix = nullable ? " (nullable)" : "";
+    const lines = [`**Type:** \`${typeString}\`${nullableSuffix}`];
+    if (schema.description) lines.push(schema.description);
+    if (schema.default !== void 0)
+      lines.push(`**Default:** \`${JSON.stringify(schema.default)}\``);
+    return lines;
+  }
+  /**
+   * Process a request body and return markdown documentation
+   */
+  requestBody(requestBody) {
+    if (!requestBody) return [];
+    const lines = [];
+    lines.push(`##### Request Body`);
+    if (requestBody.description) {
+      lines.push(requestBody.description);
+    }
+    if (requestBody.content) {
+      const contentEntries = Object.entries(requestBody.content);
+      if (contentEntries.length === 1) {
+        const [contentType, mediaType] = contentEntries[0];
+        lines.push(`**Content Type:** \`${contentType}\``);
+        if (mediaType.schema) {
+          const schemaDocs = this.handle(mediaType.schema);
+          lines.push(...schemaDocs);
+        }
+      } else {
+        for (const [contentType, mediaType] of contentEntries) {
+          lines.push(`<details>`);
+          lines.push(
+            `<summary><b>Content Type:</b> \`${contentType}\`</summary>`
+          );
+          lines.push("");
+          if (mediaType.schema) {
+            const schemaDocs = this.handle(mediaType.schema);
+            lines.push(...schemaDocs.map((l) => l));
+          }
+          lines.push("");
+          lines.push(`</details>`);
+        }
+      }
+    }
+    return lines;
+  }
+};
+
+// packages/typescript/src/lib/readme/readme.ts
+function toReadme(spec, generator) {
+  const propEmitter = new PropEmitter(spec);
+  const markdown = [];
+  markdown.push(`# ${spec.info.title} TypeScript SDK`);
+  markdown.push("");
+  markdown.push(
+    "A fully-typed TypeScript SDK with comprehensive IntelliSense support, automatic request/response validation, and modern async/await patterns. Built for seamless integration with TypeScript and JavaScript projects."
+  );
+  markdown.push("");
+  markdown.push(generator.clientSetupDocs());
+  markdown.push("");
+  const securitySchemes = spec.components?.securitySchemes || {};
+  if (Object.keys(securitySchemes).length > 0) {
+    markdown.push(generator.authenticationDocs());
+    markdown.push("");
+  }
+  const paginationDocs = generator.paginationDocs();
+  if (paginationDocs) {
+    markdown.push(paginationDocs);
+    markdown.push("");
+  }
+  markdown.push(generator.errorHandlingDocs());
+  markdown.push("");
+  markdown.push(generator.generalUsageDocs());
+  markdown.push("");
+  markdown.push("## API Reference");
+  markdown.push("");
+  forEachOperation2(spec, (entry, operation) => {
+    const { method, path } = entry;
+    markdown.push(
+      `#### ${operation["x-fn-name"]} | ${`_${method.toUpperCase()} ${path}_`}`
+    );
+    markdown.push(operation.summary || "");
+    const snippet = generator.snippet(entry, operation);
+    markdown.push(`##### Example usage`);
+    markdown.push(snippet);
+    const requestBodyContent = propEmitter.requestBody(operation.requestBody);
+    if (requestBodyContent.length > 1) {
+      markdown.push(requestBodyContent.join("\n\n"));
+    }
+    markdown.push(`##### Responses`);
+    for (const status in operation.responses) {
+      const response = operation.responses[status];
+      markdown.push(`<details>`);
+      markdown.push(
+        `<summary><b>${status}</b>  <i>${response.description}</i></summary>`
+      );
+      if (!isEmpty3(response.content)) {
+        for (const [contentType, mediaType] of Object.entries(
+          response.content
+        )) {
+          markdown.push(`
+**Content Type:** \`${contentType}\``);
+          if (mediaType.schema) {
+            const schemaDocs = propEmitter.handle(mediaType.schema);
+            markdown.push(...schemaDocs.map((l) => `
+${l}`));
+          }
+        }
+      }
+      markdown.push(`</details>`);
+    }
+  });
+  if (spec.components?.schemas) {
+    markdown.push("## Schemas");
+    markdown.push("");
+    for (const [schemaName, schema] of Object.entries(
+      spec.components.schemas
+    )) {
+      if (schemaName === "ValidationError") {
+        continue;
+      }
+      markdown.push(`<details>`);
+      markdown.push(
+        `<summary><h3 id="${schemaName.toLowerCase()}">${schemaName}</h3></summary>`
+      );
+      markdown.push("");
+      const schemaDocs = propEmitter.handle(schema);
+      markdown.push(...schemaDocs.map((line) => line.trim()));
+      markdown.push("");
+      markdown.push(`</details>`);
+      markdown.push("");
+    }
+  }
+  return markdown.join("\n\n");
+}
+
 // packages/typescript/src/lib/typescript-snippet.ts
 import { camelcase as camelcase3, spinalcase as spinalcase2 } from "stringcase";
-import { isEmpty as isEmpty3, pascalcase as pascalcase4, resolveRef as resolveRef2 } from "@sdk-it/core";
+import { isEmpty as isEmpty4, pascalcase as pascalcase4, resolveRef as resolveRef3 } from "@sdk-it/core";
+import "@sdk-it/readme";
 import {
+  forEachOperation as forEachOperation3,
   patchParameters,
   securityToOptions
 } from "@sdk-it/spec";
 
 // packages/typescript/src/lib/emitters/snippet.ts
-import { followRef as followRef4, isRef as isRef4 } from "@sdk-it/core";
+import { followRef as followRef5, isRef as isRef5, resolveRef as resolveRef2 } from "@sdk-it/core";
 var SnippetEmitter = class {
   spec;
   generatedRefs = /* @__PURE__ */ new Set();
@@ -1612,12 +1992,12 @@ var SnippetEmitter = class {
     this.spec = spec;
   }
   object(schema) {
-    const schemaObj = isRef4(schema) ? followRef4(this.spec, schema.$ref) : schema;
+    const schemaObj = resolveRef2(this.spec, schema);
     const result = {};
     const properties = schemaObj.properties || {};
     for (const [propName, propSchema] of Object.entries(properties)) {
       const isRequired = (schemaObj.required ?? []).includes(propName);
-      const resolvedProp = isRef4(propSchema) ? followRef4(this.spec, propSchema.$ref) : propSchema;
+      const resolvedProp = resolveRef2(this.spec, propSchema);
       if (isRequired || resolvedProp.example !== void 0 || resolvedProp.default !== void 0 || Math.random() > 0.5) {
         result[propName] = this.handle(propSchema);
       }
@@ -1630,7 +2010,7 @@ var SnippetEmitter = class {
     return result;
   }
   array(schema) {
-    const schemaObj = isRef4(schema) ? followRef4(this.spec, schema.$ref) : schema;
+    const schemaObj = resolveRef2(this.spec, schema);
     const itemsSchema = schemaObj.items;
     if (!itemsSchema) {
       return [];
@@ -1712,7 +2092,7 @@ var SnippetEmitter = class {
       return this.cache.get($ref);
     }
     this.cache.set($ref, { _ref: refKey });
-    const resolved = followRef4(this.spec, $ref);
+    const resolved = followRef5(this.spec, $ref);
     const result = this.handle(resolved);
     this.cache.set($ref, result);
     return result;
@@ -1739,10 +2119,10 @@ var SnippetEmitter = class {
     return Array.isArray(schema.enum) && schema.enum.length > 0 ? schema.enum[0] : void 0;
   }
   handle(schemaOrRef) {
-    if (isRef4(schemaOrRef)) {
+    if (isRef5(schemaOrRef)) {
       return this.ref(schemaOrRef.$ref);
     }
-    const schema = isRef4(schemaOrRef) ? followRef4(this.spec, schemaOrRef.$ref) : schemaOrRef;
+    const schema = resolveRef2(this.spec, schemaOrRef);
     if (schema.example !== void 0) {
       return schema.example;
     }
@@ -1807,9 +2187,9 @@ var TypeScriptGenerator = class {
   }
   succinct(entry, operation, values) {
     let payload = "{}";
-    if (!isEmpty3(operation.requestBody)) {
+    if (!isEmpty4(operation.requestBody)) {
       const contentTypes = Object.keys(operation.requestBody.content || {});
-      const schema = resolveRef2(
+      const schema = resolveRef3(
         this.#spec,
         operation.requestBody.content[contentTypes[0]].schema
       );
@@ -1869,33 +2249,33 @@ var TypeScriptGenerator = class {
         return this.#streamDownload(entry, payload);
       }
     }
-    if (!isEmpty3(operation["x-pagination"])) {
+    if (!isEmpty4(operation["x-pagination"])) {
       return this.#pagination(operation, entry, payload);
     }
     return this.#normal(entry, payload);
   }
-  #pagination(opeartion, entry, payload) {
-    const pagination = opeartion["x-pagination"];
+  #pagination(operation, entry, payload) {
+    const pagination = operation["x-pagination"];
     switch (pagination.type) {
       case "page":
         return {
-          content: `const result = ${this.#ddd(entry, payload)}`,
+          content: `const result = ${this.#toRequest(entry, payload)}`,
           footer: `for await (const page of result) {
-	console.log(page);
+		console.log(page);
 }`
         };
       case "offset":
         return {
-          content: `const result = ${this.#ddd(entry, payload)}`,
+          content: `const result = ${this.#toRequest(entry, payload)}`,
           footer: `for await (const page of result) {
-	console.log(page);
+		console.log(page);
 }`
         };
       case "cursor":
         return {
-          content: `const result = ${this.#ddd(entry, payload)}`,
+          content: `const result = ${this.#toRequest(entry, payload)}`,
           footer: `for await (const page of result) {
-	console.log(page);
+		console.log(page);
 }`
         };
     }
@@ -1903,25 +2283,25 @@ var TypeScriptGenerator = class {
   }
   #normal(entry, payload) {
     return {
-      content: `const result = ${this.#ddd(entry, payload)};`,
+      content: `const result = ${this.#toRequest(entry, payload)};`,
       footer: "console.log(result.data)"
     };
   }
   #streamDownload(entry, payload) {
     return {
-      content: `const stream = ${this.#ddd(entry, payload)}`,
+      content: `const stream = ${this.#toRequest(entry, payload)}`,
       footer: `await writeFile('./report.pdf', stream);`
     };
   }
   #httpStreaming(entry, payload) {
     return {
-      content: `const stream = ${this.#ddd(entry, payload)}`,
+      content: `const stream = ${this.#toRequest(entry, payload)}`,
       footer: `for await (const chunk of stream) {
-	console.log(chunk);
+		console.log(chunk);
 }`
     };
   }
-  #ddd(entry, payload) {
+  #toRequest(entry, payload) {
     return `await ${camelcase3(this.#clientName)}.request('${entry.method.toUpperCase()} ${entry.path}', ${payload});`;
   }
   snippet(entry, operation, config = {}) {
@@ -1934,8 +2314,7 @@ var TypeScriptGenerator = class {
       payload.footer
     ];
     if (config.frame !== false) {
-      content.unshift("```typescript");
-      content.push("```");
+      return createCodeBlock("typescript", content);
     }
     return content.join("\n");
   }
@@ -1947,26 +2326,578 @@ var TypeScriptGenerator = class {
     );
   }
   client() {
-    const inputs = [
-      `baseUrl: '${this.#spec.servers?.[0]?.url ?? "http://localhost:3000"}'`
-    ];
+    const options = {
+      baseUrl: this.#spec.servers?.[0]?.url ?? "http://localhost:3000"
+    };
     const authOptions = this.#authentication();
-    if (!isEmpty3(authOptions)) {
+    if (!isEmpty4(authOptions)) {
       const [firstAuth] = authOptions;
-      inputs.push(
-        `'${firstAuth["x-optionName"] ?? firstAuth.name}': ${firstAuth.example}`
-      );
+      const optionName = firstAuth["x-optionName"] ?? firstAuth.name;
+      options[optionName] = firstAuth.example;
     }
-    return `import { ${this.#clientName} } from '${this.#packageName}';
+    const client = this.#constructClient(options);
+    return `${client.import}
 
-const ${camelcase3(this.#clientName)} = new ${this.#clientName}({ 
-	${inputs.join(",\n	")}
-});`;
+${client.use}`;
+  }
+  #constructClient(options = {}) {
+    return {
+      import: `import { ${this.#clientName} } from '${this.#packageName}';`,
+      use: `const ${camelcase3(this.#clientName)} = new ${this.#clientName}({
+		${Object.entries(
+        options
+      ).map(([key, value]) => `${key}: ${JSON.stringify(value)}`).join(",\n		")}
+	});`
+    };
+  }
+  clientInstallDocs() {
+    const sections = [];
+    sections.push("## Installation");
+    sections.push("");
+    sections.push(
+      createCodeBlock("bash", [`npm install ${this.#packageName}`])
+    );
+    sections.push("");
+    sections.push("## Basic Usage");
+    sections.push("");
+    sections.push(createCodeBlock("typescript", [this.client()]));
+    return sections.join("\n");
+  }
+  configurationOptions() {
+    const sections = [];
+    const hasServers = Boolean(
+      this.#spec.servers && this.#spec.servers.length > 0
+    );
+    const baseUrl = this.#spec.servers?.[0]?.url || "https://api.example.com";
+    const authOptions = this.#authentication();
+    const hasApiKey = !isEmpty4(authOptions);
+    sections.push("### Configuration Options");
+    sections.push("");
+    sections.push("| Option | Type | Required | Description |");
+    sections.push("|--------|------|----------|-------------|");
+    sections.push(
+      "| `fetch` | `fetch compatible` | No | Fetch implementation to use for HTTP requests |"
+    );
+    if (hasServers) {
+      sections.push(
+        "| `baseUrl` | `string` | No | API base URL (default: `" + baseUrl + "`) |"
+      );
+    }
+    for (const authOption of authOptions) {
+      const optionName = authOption["x-optionName"] ?? authOption.name;
+      const description = authOption.in === "header" && authOption.name === "authorization" ? "Bearer token for authentication" : `API key for authentication (${authOption.in}: ${authOption.name})`;
+      sections.push(`| \`${optionName}\` | \`string\` | No | ${description} |`);
+    }
+    return { sections, hasServers, baseUrl, hasApiKey };
+  }
+  clientSetupDocs() {
+    const sections = [];
+    sections.push(this.clientInstallDocs());
+    sections.push("");
+    const config = this.configurationOptions();
+    sections.push(...config.sections);
+    sections.push("");
+    sections.push(this.configurationUpdateDocs());
+    return sections.join("\n");
+  }
+  paginationDocs() {
+    const paginationTypes = availablePaginationTypes(this.#spec);
+    if (!paginationTypes.offset && !paginationTypes.page && !paginationTypes.cursor) {
+      return "";
+    }
+    const sections = [];
+    sections.push("## Pagination");
+    sections.push("");
+    sections.push(
+      "This SDK automatically handles pagination for endpoints that return multiple items."
+    );
+    sections.push("");
+    sections.push("### How it Works");
+    sections.push("");
+    sections.push(
+      "When you call a paginated endpoint, the SDK returns a pagination object that allows you to iterate through all results:"
+    );
+    sections.push("");
+    const availableTypes = [];
+    if (paginationTypes.offset) availableTypes.push("offset");
+    if (paginationTypes.page) availableTypes.push("page");
+    if (paginationTypes.cursor) availableTypes.push("cursor");
+    const primaryPaginationType = availableTypes[0];
+    const mockPaginatedOperation = {
+      "x-pagination": { type: primaryPaginationType },
+      tags: ["Products"],
+      operationId: "listProducts",
+      parameters: [],
+      "x-fn-name": "listProducts",
+      responses: {},
+      requestBody: {}
+    };
+    const mockOperationEntry = {
+      method: "get",
+      path: "/products",
+      tag: "Products"
+    };
+    const initialRequestPayload = createObjectLiteral({ limit: 20 });
+    const paginationExample = this.#pagination(
+      mockPaginatedOperation,
+      mockOperationEntry,
+      initialRequestPayload
+    );
+    sections.push(
+      createCodeBlock("typescript", [
+        "// The SDK automatically handles pagination",
+        paginationExample.content,
+        "",
+        "// Access the current page data",
+        "const currentPage = result.getCurrentPage();",
+        "console.log(currentPage.data); // Array of product items",
+        "",
+        "// Check if more pages exist",
+        "if (result.hasMore) {",
+        "  await result.getNextPage();",
+        "}",
+        "",
+        "// Or iterate through all pages automatically",
+        paginationExample.footer
+      ])
+    );
+    sections.push("");
+    sections.push("### Iterating Through All Pages");
+    sections.push("");
+    const iterationExample = this.#pagination(
+      mockPaginatedOperation,
+      mockOperationEntry,
+      createObjectLiteral({ limit: 100 })
+    );
+    sections.push(
+      createCodeBlock("typescript", [
+        "// Using async iteration to process all pages",
+        iterationExample.content,
+        "",
+        iterationExample.footer
+      ])
+    );
+    sections.push("");
+    if (availableTypes.length > 1) {
+      sections.push("### Pagination Types");
+      sections.push("");
+      sections.push(
+        "Your API uses the following pagination strategies, automatically detected by the SDK:"
+      );
+      sections.push("");
+    } else {
+      sections.push("### Pagination Strategy");
+      sections.push("");
+      sections.push(
+        "Your API uses the following pagination strategy, automatically detected by the SDK:"
+      );
+      sections.push("");
+    }
+    for (const paginationType of availableTypes) {
+      const typeSpecificOperation = {
+        "x-pagination": { type: paginationType },
+        tags: ["Products"],
+        operationId: "listProducts",
+        parameters: [],
+        "x-fn-name": "listProducts",
+        responses: {},
+        requestBody: {}
+      };
+      const typeSpecificEntry = {
+        method: "get",
+        path: "/products",
+        tag: "Products"
+      };
+      if (paginationType === "cursor") {
+        sections.push("#### Cursor Pagination");
+        sections.push("");
+        sections.push("Uses a cursor token to fetch the next page:");
+        sections.push("");
+        const cursorPaginationExample = this.#pagination(
+          typeSpecificOperation,
+          typeSpecificEntry,
+          createObjectLiteral({ limit: 20 })
+        );
+        sections.push(
+          createCodeBlock("typescript", [
+            cursorPaginationExample.content,
+            "",
+            "// Iterate through all pages using cursor",
+            cursorPaginationExample.footer
+          ])
+        );
+        sections.push("");
+      }
+      if (paginationType === "offset") {
+        sections.push("#### Offset Pagination");
+        sections.push("");
+        sections.push("Uses offset and limit parameters:");
+        sections.push("");
+        const offsetPaginationExample = this.#pagination(
+          typeSpecificOperation,
+          typeSpecificEntry,
+          createObjectLiteral({ limit: 20, offset: 0 })
+        );
+        sections.push(
+          createCodeBlock("typescript", [
+            offsetPaginationExample.content,
+            "",
+            "// Iterate through all pages using offset",
+            offsetPaginationExample.footer
+          ])
+        );
+        sections.push("");
+      }
+      if (paginationType === "page") {
+        sections.push("#### Page Pagination");
+        sections.push("");
+        sections.push("Uses page number and page size:");
+        sections.push("");
+        const pagePaginationExample = this.#pagination(
+          typeSpecificOperation,
+          typeSpecificEntry,
+          createObjectLiteral({ page: 1, pageSize: 20 })
+        );
+        sections.push(
+          createCodeBlock("typescript", [
+            pagePaginationExample.content,
+            "",
+            "// Iterate through all pages using page numbers",
+            pagePaginationExample.footer
+          ])
+        );
+        sections.push("");
+      }
+    }
+    if (availableTypes.length > 1) {
+      sections.push(
+        "The SDK handles the differences transparently, providing a consistent interface regardless of the underlying pagination type."
+      );
+    }
+    return sections.join("\n");
+  }
+  errorHandlingDocs() {
+    const sections = [];
+    sections.push("## Error Handling");
+    sections.push("");
+    sections.push(
+      "The SDK provides structured error handling with typed HTTP error responses."
+    );
+    sections.push("");
+    sections.push("### Error Response Types");
+    sections.push("");
+    sections.push(
+      "All API errors extend from `APIError` and include the HTTP status code and response data:"
+    );
+    sections.push("");
+    sections.push(
+      createCodeBlock("typescript", [
+        `import { BadRequest, Unauthorized, NotFound, TooManyRequests, InternalServerError, ParseError } from "${this.#packageName}";`,
+        "try {",
+        "const usersList = ",
+        this.#toRequest(
+          {
+            method: "get",
+            path: "/users",
+            tag: "Users"
+          },
+          createObjectLiteral({})
+        ),
+        "  // Handle successful response",
+        "} catch (error) {",
+        "  // Handle different error types",
+        "  if (error instanceof BadRequest) {",
+        '    console.error("Bad request:", error.data);',
+        '    console.log("Status:", error.status); // 400',
+        "  } else if (error instanceof Unauthorized) {",
+        '    console.error("Authentication failed:", error.data);',
+        '    console.log("Status:", error.status); // 401',
+        "  } else if (error instanceof NotFound) {",
+        '    console.error("Resource not found:", error.data);',
+        '    console.log("Status:", error.status); // 404',
+        "  } else if (error instanceof TooManyRequests) {",
+        '    console.error("Rate limited:", error.data);',
+        "    if (error.data.retryAfter) {",
+        '      console.log("Retry after:", error.data.retryAfter);',
+        "    }",
+        "  } else if (error instanceof InternalServerError) {",
+        '    console.error("Server error:", error.data);',
+        '    console.log("Status:", error.status); // 500',
+        "  } else if (error instanceof ParseError) {",
+        '    console.error("Input validation failed:", error.data);',
+        "  }",
+        "}"
+      ])
+    );
+    sections.push("");
+    sections.push("### Available Error Classes");
+    sections.push("");
+    sections.push("#### Input Validation Errors");
+    sections.push(
+      "- `ParseError` - Request input validation failed against API schema"
+    );
+    sections.push("");
+    sections.push("#### Client Errors (4xx)");
+    sections.push("- `BadRequest` (400) - Invalid request data");
+    sections.push("- `Unauthorized` (401) - Authentication required");
+    sections.push("- `PaymentRequired` (402) - Payment required");
+    sections.push("- `Forbidden` (403) - Access denied");
+    sections.push("- `NotFound` (404) - Resource not found");
+    sections.push("- `MethodNotAllowed` (405) - HTTP method not allowed");
+    sections.push("- `NotAcceptable` (406) - Content type not acceptable");
+    sections.push("- `Conflict` (409) - Resource conflict");
+    sections.push("- `Gone` (410) - Resource no longer available");
+    sections.push("- `PreconditionFailed` (412) - Precondition failed");
+    sections.push("- `PayloadTooLarge` (413) - Request payload too large");
+    sections.push("- `UnsupportedMediaType` (415) - Unsupported content type");
+    sections.push("- `UnprocessableEntity` (422) - Validation errors");
+    sections.push("- `TooManyRequests` (429) - Rate limit exceeded");
+    sections.push("");
+    sections.push("#### Server Errors (5xx)");
+    sections.push("- `InternalServerError` (500) - Server error");
+    sections.push("- `NotImplemented` (501) - Not implemented");
+    sections.push("- `BadGateway` (502) - Bad gateway");
+    sections.push("- `ServiceUnavailable` (503) - Service unavailable");
+    sections.push("- `GatewayTimeout` (504) - Gateway timeout");
+    sections.push("");
+    sections.push("### Validation Errors");
+    sections.push("");
+    sections.push(
+      "Validation errors (422) include detailed field-level error information:"
+    );
+    sections.push("### Input Validation Errors");
+    sections.push("");
+    sections.push(
+      "When request input fails validation against the API schema, a `ParseError` is thrown:"
+    );
+    sections.push("");
+    sections.push(
+      createCodeBlock("typescript", [
+        `import { ParseError } from "${this.#packageName}";`,
+        "",
+        "try {",
+        "  // Invalid input that doesn't match the expected schema",
+        "  const newUser = ",
+        this.#toRequest(
+          {
+            method: "post",
+            path: "/users",
+            tag: "Users"
+          },
+          createObjectLiteral({
+            email: 123,
+            // should be string
+            firstName: "",
+            // empty required field
+            age: -5
+            // invalid age value
+          })
+        ),
+        "} catch (error) {",
+        "  if (error instanceof ParseError) {",
+        '    console.log("Input validation failed:");',
+        "    ",
+        "    // Field-level errors",
+        "    if (error.data.fieldErrors) {",
+        "      Object.entries(error.data.fieldErrors).forEach(([fieldName, validationIssues]) => {",
+        '        console.log(`  ${fieldName}: ${validationIssues.map(issue => issue.message).join(", ")}`);',
+        "      });",
+        "    }",
+        "    ",
+        "    // Form-level errors",
+        "    if (error.data.formErrors.length > 0) {",
+        '      console.log(`  Form errors: ${error.data.formErrors.map(issue => issue.message).join(", ")}`);',
+        "    }",
+        "  }",
+        "}"
+      ])
+    );
+    sections.push("");
+    sections.push(
+      "`ParseError` contains detailed validation information using Zod's flattened error format, providing specific field-level and form-level validation messages."
+    );
+    sections.push("");
+    sections.push("### Rate Limiting");
+    sections.push("");
+    sections.push(
+      "Rate limit responses may include a `retryAfter` field indicating when to retry:"
+    );
+    sections.push("");
+    sections.push(
+      createCodeBlock("typescript", [
+        `import { TooManyRequests } from "${this.#packageName}";`,
+        "",
+        "try {",
+        "  const apiResponse = ",
+        this.#toRequest(
+          {
+            method: "get",
+            path: "/api/data",
+            tag: "Data"
+          },
+          createObjectLiteral({})
+        ),
+        "} catch (error) {",
+        "  if (error instanceof TooManyRequests) {",
+        "    const retryAfterSeconds = error.data.retryAfter;",
+        "    if (retryAfterSeconds) {",
+        "      console.log(`Rate limited. Retry after: ${retryAfterSeconds} seconds`);",
+        "      // Implement your own retry logic",
+        "      setTimeout(() => {",
+        "        // Retry the request",
+        "      }, retryAfterSeconds * 1000);",
+        "    }",
+        "  }",
+        "}"
+      ])
+    );
+    return sections.join("\n");
+  }
+  authenticationDocs() {
+    const authOptions = this.#authentication();
+    if (isEmpty4(authOptions)) {
+      return "";
+    }
+    const sections = [];
+    sections.push("## Authentication");
+    sections.push("");
+    if (authOptions.length === 1) {
+      sections.push(
+        "The SDK requires authentication to access the API. Configure your client with the required credentials:"
+      );
+    } else {
+      sections.push("The SDK supports the following authentication methods:");
+    }
+    sections.push("");
+    for (const authOption of authOptions) {
+      const optionName = authOption["x-optionName"] ?? authOption.name;
+      const isBearer = authOption.in === "header" && authOption.name === "authorization";
+      const isApiKey = authOption.in === "header" && authOption.name !== "authorization";
+      const isQueryParam = authOption.in === "query";
+      const headingLevel = authOptions.length === 1 ? "###" : "###";
+      if (isBearer) {
+        const authenticationHeading = authOptions.length === 1 ? "Bearer Token" : "Bearer Token Authentication";
+        sections.push(`${headingLevel} ${authenticationHeading}`);
+        sections.push("");
+        sections.push(
+          'Pass your bearer token directly - the "Bearer" prefix is automatically added:'
+        );
+        sections.push("");
+        const bearerAuthClient = this.#constructClient({
+          [optionName]: "sk_live_51234567890abcdef1234567890abcdef"
+        });
+        sections.push(createCodeBlock("typescript", [bearerAuthClient.use]));
+        sections.push("");
+      } else if (isApiKey) {
+        const apiKeyHeading = authOptions.length === 1 ? "API Key (Header)" : "API Key Authentication (Header)";
+        sections.push(`${headingLevel} ${apiKeyHeading}`);
+        sections.push("");
+        const apiKeyAuthClient = this.#constructClient({
+          [optionName]: "api_key_1234567890abcdef1234567890abcdef"
+        });
+        sections.push(createCodeBlock("typescript", [apiKeyAuthClient.use]));
+        sections.push("");
+      } else if (isQueryParam) {
+        const queryParamHeading = authOptions.length === 1 ? "API Key (Query Parameter)" : "API Key Authentication (Query Parameter)";
+        sections.push(`${headingLevel} ${queryParamHeading}`);
+        sections.push("");
+        const queryParamAuthClient = this.#constructClient({
+          [optionName]: "qp_key_1234567890abcdef1234567890abcdef"
+        });
+        sections.push(
+          createCodeBlock("typescript", [queryParamAuthClient.use])
+        );
+        sections.push("");
+      } else {
+        const genericAuthHeading = authOptions.length === 1 ? authOption.name : `${authOption.name} Authentication`;
+        sections.push(`${headingLevel} ${genericAuthHeading}`);
+        sections.push("");
+        const genericAuthClient = this.#constructClient({
+          [optionName]: "auth_token_1234567890abcdef1234567890abcdef"
+        });
+        sections.push(createCodeBlock("typescript", [genericAuthClient.use]));
+        sections.push("");
+      }
+    }
+    return sections.join("\n");
+  }
+  generalUsageDocs() {
+    const sections = [];
+    return sections.join("\n");
+  }
+  configurationUpdateDocs() {
+    const sections = [];
+    const authOptions = this.#authentication();
+    sections.push("### Updating Configuration");
+    sections.push("");
+    sections.push(
+      "You can update client configuration after initialization using the `setOptions` method:"
+    );
+    sections.push("");
+    const initialClientOptions = {
+      baseUrl: "https://api.production-service.com"
+    };
+    if (!isEmpty4(authOptions)) {
+      const [primaryAuth] = authOptions;
+      const authOptionName = primaryAuth["x-optionName"] ?? primaryAuth.name;
+      initialClientOptions[authOptionName] = "prod_sk_1234567890abcdef";
+    }
+    const initialClientSetup = this.#constructClient(initialClientOptions);
+    const configurationUpdateCode = [
+      "// Initial client setup",
+      initialClientSetup.use,
+      "",
+      "// Later, update specific options",
+      "client.setOptions({",
+      "  baseUrl: 'https://api.staging-service.com',"
+    ];
+    if (!isEmpty4(authOptions)) {
+      const [primaryAuth] = authOptions;
+      const authOptionName = primaryAuth["x-optionName"] ?? primaryAuth.name;
+      configurationUpdateCode.push(
+        `  ${authOptionName}: 'staging_sk_abcdef1234567890'`
+      );
+    }
+    configurationUpdateCode.push("});");
+    sections.push(createCodeBlock("typescript", configurationUpdateCode));
+    sections.push("");
+    sections.push(
+      "The `setOptions` method validates the provided options and only updates the specified fields, leaving other configuration unchanged."
+    );
+    return sections.join("\n");
   }
 };
-function generateSnippet(spec, settings, entry, operation, config = {}) {
-  const generator = new TypeScriptGenerator(spec, settings);
-  return generator.snippet(entry, operation, config);
+function createCodeBlock(language, content) {
+  return ["```" + language, ...content, "```"].join("\n");
+}
+function createObjectLiteral(obj, indent = "	") {
+  return "{\n" + Object.entries(obj).map(([key, value]) => `${indent}${key}: ${JSON.stringify(value)}`).join(",\n") + `
+${indent.slice(0, -1)}}`;
+}
+function availablePaginationTypes(spec) {
+  let offset = false;
+  let page = false;
+  let cursor = false;
+  forEachOperation3(spec, (entry, operation) => {
+    if (operation["x-pagination"]) {
+      switch (operation["x-pagination"].type) {
+        case "offset":
+          offset = true;
+          break;
+        case "page":
+          page = true;
+          break;
+        case "cursor":
+          cursor = true;
+          break;
+      }
+    }
+  });
+  return {
+    offset,
+    page,
+    cursor
+  };
 }
 
 // packages/typescript/src/lib/generate.ts
@@ -2203,13 +3134,13 @@ ${template2(dispatcher_default, {})({ throwError: !style.errorAsValue, outputTyp
         )
       }
     };
-    if (settings.readme) {
-      configFiles["README.md"] = toReadme(spec, {
-        generateSnippet: (...args) => generator.snippet(...args)
-      });
-    }
     await settings.writer(settings.output, configFiles);
   }
+  if (settings.readme) {
+    await settings.writer(settings.mode === "full" ? settings.output : output, {
+      "README.md": toReadme(spec, generator)
+    });
+  }
   await settings.formatCode?.({
     output,
     env: npmRunPathEnv()
@@ -2300,7 +3231,6 @@ function toInputs(operationsSet, commonZod, makeImport) {
 export {
   TypeScriptGenerator,
   generate,
-  generateSnippet,
   toInputs
 };
 //# sourceMappingURL=index.js.map