@ps-aux/api-client-gen 0.7.0-rc.3 → 0.7.0-rc.4

package/dist/generateApiClient.cjs

@@ -722,6 +722,7 @@ const string$1 = (params) => {
     const regex = params ? `[\\s\\S]{${params?.minimum ?? 0},${params?.maximum ?? ""}}` : `[\\s\\S]*`;
     return new RegExp(`^${regex}$`);
 };
+const number = /^-?\d+(?:\.\d+)?$/;
 const boolean$1 = /^(?:true|false)$/i;
 // regex for string with no uppercase letters
 const lowercase = /^[^A-Z]*$/;
@@ -1918,6 +1919,122 @@ function handleIntersectionResults(result, left, right) {
     result.value = merged.data;
     return result;
 }
+const $ZodRecord = /*@__PURE__*/ $constructor("$ZodRecord", (inst, def) => {
+    $ZodType.init(inst, def);
+    inst._zod.parse = (payload, ctx) => {
+        const input = payload.value;
+        if (!isPlainObject(input)) {
+            payload.issues.push({
+                expected: "record",
+                code: "invalid_type",
+                input,
+                inst,
+            });
+            return payload;
+        }
+        const proms = [];
+        const values = def.keyType._zod.values;
+        if (values) {
+            payload.value = {};
+            const recordKeys = new Set();
+            for (const key of values) {
+                if (typeof key === "string" || typeof key === "number" || typeof key === "symbol") {
+                    recordKeys.add(typeof key === "number" ? key.toString() : key);
+                    const result = def.valueType._zod.run({ value: input[key], issues: [] }, ctx);
+                    if (result instanceof Promise) {
+                        proms.push(result.then((result) => {
+                            if (result.issues.length) {
+                                payload.issues.push(...prefixIssues(key, result.issues));
+                            }
+                            payload.value[key] = result.value;
+                        }));
+                    }
+                    else {
+                        if (result.issues.length) {
+                            payload.issues.push(...prefixIssues(key, result.issues));
+                        }
+                        payload.value[key] = result.value;
+                    }
+                }
+            }
+            let unrecognized;
+            for (const key in input) {
+                if (!recordKeys.has(key)) {
+                    unrecognized = unrecognized ?? [];
+                    unrecognized.push(key);
+                }
+            }
+            if (unrecognized && unrecognized.length > 0) {
+                payload.issues.push({
+                    code: "unrecognized_keys",
+                    input,
+                    inst,
+                    keys: unrecognized,
+                });
+            }
+        }
+        else {
+            payload.value = {};
+            for (const key of Reflect.ownKeys(input)) {
+                if (key === "__proto__")
+                    continue;
+                let keyResult = def.keyType._zod.run({ value: key, issues: [] }, ctx);
+                if (keyResult instanceof Promise) {
+                    throw new Error("Async schemas not supported in object keys currently");
+                }
+                // Numeric string fallback: if key is a numeric string and failed, retry with Number(key)
+                // This handles z.number(), z.literal([1, 2, 3]), and unions containing numeric literals
+                const checkNumericKey = typeof key === "string" && number.test(key) && keyResult.issues.length;
+                if (checkNumericKey) {
+                    const retryResult = def.keyType._zod.run({ value: Number(key), issues: [] }, ctx);
+                    if (retryResult instanceof Promise) {
+                        throw new Error("Async schemas not supported in object keys currently");
+                    }
+                    if (retryResult.issues.length === 0) {
+                        keyResult = retryResult;
+                    }
+                }
+                if (keyResult.issues.length) {
+                    if (def.mode === "loose") {
+                        // Pass through unchanged
+                        payload.value[key] = input[key];
+                    }
+                    else {
+                        // Default "strict" behavior: error on invalid key
+                        payload.issues.push({
+                            code: "invalid_key",
+                            origin: "record",
+                            issues: keyResult.issues.map((iss) => finalizeIssue(iss, ctx, config())),
+                            input: key,
+                            path: [key],
+                            inst,
+                        });
+                    }
+                    continue;
+                }
+                const result = def.valueType._zod.run({ value: input[key], issues: [] }, ctx);
+                if (result instanceof Promise) {
+                    proms.push(result.then((result) => {
+                        if (result.issues.length) {
+                            payload.issues.push(...prefixIssues(key, result.issues));
+                        }
+                        payload.value[keyResult.value] = result.value;
+                    }));
+                }
+                else {
+                    if (result.issues.length) {
+                        payload.issues.push(...prefixIssues(key, result.issues));
+                    }
+                    payload.value[keyResult.value] = result.value;
+                }
+            }
+        }
+        if (proms.length) {
+            return Promise.all(proms).then(() => payload);
+        }
+        return payload;
+    };
+});
 const $ZodEnum = /*@__PURE__*/ $constructor("$ZodEnum", (inst, def) => {
     $ZodType.init(inst, def);
     const values = getEnumValues(def.entries);
@@ -3314,6 +3431,49 @@ const intersectionProcessor = (schema, ctx, json, params) => {
     ];
     json.allOf = allOf;
 };
+const recordProcessor = (schema, ctx, _json, params) => {
+    const json = _json;
+    const def = schema._zod.def;
+    json.type = "object";
+    // For looseRecord with regex patterns, use patternProperties
+    // This correctly represents "only validate keys matching the pattern" semantics
+    // and composes well with allOf (intersections)
+    const keyType = def.keyType;
+    const keyBag = keyType._zod.bag;
+    const patterns = keyBag?.patterns;
+    if (def.mode === "loose" && patterns && patterns.size > 0) {
+        // Use patternProperties for looseRecord with regex patterns
+        const valueSchema = process(def.valueType, ctx, {
+            ...params,
+            path: [...params.path, "patternProperties", "*"],
+        });
+        json.patternProperties = {};
+        for (const pattern of patterns) {
+            json.patternProperties[pattern.source] = valueSchema;
+        }
+    }
+    else {
+        // Default behavior: use propertyNames + additionalProperties
+        if (ctx.target === "draft-07" || ctx.target === "draft-2020-12") {
+            json.propertyNames = process(def.keyType, ctx, {
+                ...params,
+                path: [...params.path, "propertyNames"],
+            });
+        }
+        json.additionalProperties = process(def.valueType, ctx, {
+            ...params,
+            path: [...params.path, "additionalProperties"],
+        });
+    }
+    // Add required for keys with discrete values (enum, literal, etc.)
+    const keyValues = keyType._zod.values;
+    if (keyValues) {
+        const validKeyValues = [...keyValues].filter((v) => typeof v === "string" || typeof v === "number");
+        if (validKeyValues.length > 0) {
+            json.required = validKeyValues;
+        }
+    }
+};
 const nullableProcessor = (schema, ctx, json, params) => {
     const def = schema._zod.def;
     const inner = process(def.innerType, ctx, params);
@@ -3817,6 +3977,21 @@ function intersection(left, right) {
         right: right,
     });
 }
+const ZodRecord = /*@__PURE__*/ $constructor("ZodRecord", (inst, def) => {
+    $ZodRecord.init(inst, def);
+    ZodType.init(inst, def);
+    inst._zod.processJSONSchema = (ctx, json, params) => recordProcessor(inst, ctx, json, params);
+    inst.keyType = def.keyType;
+    inst.valueType = def.valueType;
+});
+function record(keyType, valueType, params) {
+    return new ZodRecord({
+        type: "record",
+        keyType,
+        valueType: valueType,
+        ...normalizeParams(params),
+    });
+}
 const ZodEnum = /*@__PURE__*/ $constructor("ZodEnum", (inst, def) => {
     $ZodEnum.init(inst, def);
     ZodType.init(inst, def);
@@ -4049,8 +4224,19 @@ const vNextOasGeneratorSchema = strictObject({
     unwrap: boolean().default(true),
     withRequestParams: boolean().default(false),
     pathParamsStyle: _enum(["object", "positional"]).default("positional"),
-    enumStyle: _enum(["enum", "union"]).default("enum")
-  }),
+    enumStyle: _enum(["enum", "union"]).default("enum"),
+    comments: strictObject({
+      enabled: boolean().default(true),
+      operation: strictObject({
+        tags: boolean().default(true),
+        summary: boolean().default(true),
+        description: boolean().default(true)
+      }).prefault({}),
+      schema: strictObject({
+        metadata: boolean().default(true)
+      }).prefault({})
+    }).prefault({})
+  }).prefault({}),
   compat: strictObject({
     uppercaseEnumKeys: boolean(),
     swaggerTsApiRequiredBooleans: boolean()
@@ -4061,7 +4247,7 @@ const legacyOasGeneratorSchema = strictObject({
     ignoreOperationsWithTags: array(string()).optional()
   })
 });
-const configSchema = strictObject({
+const profileConfigSchema = strictObject({
   srcSpec: string().trim().min(1),
   dstDir: string().trim().min(1),
   apiName: string().trim().min(1),
@@ -4079,6 +4265,8 @@ const configSchema = strictObject({
     localDateTimes: boolean().optional()
   }).optional()
 });
+const configSchema = record(string(), profileConfigSchema);
+const defineConfig = (config) => config;
 const parseConfig = (userConfig, filePath) => {
   const parsed = configSchema.safeParse(userConfig);
   if (parsed.success) return parsed.data;
@@ -4086,6 +4274,13 @@ const parseConfig = (userConfig, filePath) => {
     cause: parsed.error
   });
 };
+const parseProfileConfig = (userConfig, filePath) => {
+  const parsed = profileConfigSchema.safeParse(userConfig);
+  if (parsed.success) return parsed.data;
+  throw new Error(`Invalid config at ${filePath}: ${parsed.error.message}`, {
+    cause: parsed.error
+  });
+};
 
 const downloadSpec = async (path, url) => {
   let response;
@@ -4240,9 +4435,9 @@ const resolveLocalRef = (root, ref) => {
   return current;
 };
 
-var __defProp$9 = Object.defineProperty;
-var __defNormalProp$9 = (obj, key, value) => key in obj ? __defProp$9(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
-var __publicField$9 = (obj, key, value) => __defNormalProp$9(obj, key + "" , value);
+var __defProp$a = Object.defineProperty;
+var __defNormalProp$a = (obj, key, value) => key in obj ? __defProp$a(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
+var __publicField$a = (obj, key, value) => __defNormalProp$a(obj, key + "" , value);
 const PARAMETER_LOCATIONS = [
   "path",
   "query",
@@ -4268,7 +4463,7 @@ const mergeParameters = (base, override) => {
 class OpenApiNormalizer {
   constructor(doc) {
     this.doc = doc;
-    __publicField$9(this, "problems", []);
+    __publicField$a(this, "problems", []);
   }
   load() {
     const info = readRecord(this.doc, "info");
@@ -4611,23 +4806,24 @@ const syntheticOperationId = (method, path) => {
   return `_${compact}`;
 };
 
-var __defProp$8 = Object.defineProperty;
-var __defNormalProp$8 = (obj, key, value) => key in obj ? __defProp$8(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
-var __publicField$8 = (obj, key, value) => __defNormalProp$8(obj, typeof key !== "symbol" ? key + "" : key, value);
+var __defProp$9 = Object.defineProperty;
+var __defNormalProp$9 = (obj, key, value) => key in obj ? __defProp$9(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
+var __publicField$9 = (obj, key, value) => __defNormalProp$9(obj, typeof key !== "symbol" ? key + "" : key, value);
 class TsCodegen {
-  constructor(typeExprCodegen) {
+  constructor(typeExprCodegen, docRenderer) {
     this.typeExprCodegen = typeExprCodegen;
-    __publicField$8(this, "usedTypeRefs", []);
-    __publicField$8(this, "usedTypeRefKeys", /* @__PURE__ */ new Set());
-    __publicField$8(this, "typeExpr", (typeExpr) => {
+    __publicField$9(this, "usedTypeRefs", []);
+    __publicField$9(this, "usedTypeRefKeys", /* @__PURE__ */ new Set());
+    __publicField$9(this, "docRenderer");
+    __publicField$9(this, "typeExpr", (typeExpr) => {
       this.collectTypeRefsFromExpr(typeExpr);
       return this.typeExprCodegen.toCode(typeExpr).code;
     });
-    __publicField$8(this, "declaration", (name, declaration) => {
+    __publicField$9(this, "declaration", (name, declaration, options = {}) => {
       this.collectTypeRefsFromDeclaration(declaration);
-      return this.toDeclarationCode(name, declaration);
+      return this.toDeclarationCode(name, declaration, options);
     });
-    __publicField$8(this, "toChunk", (name, code, exports$1) => {
+    __publicField$9(this, "toChunk", (name, code, exports$1) => {
       const exportedSymbols = new Set(exports$1);
       const refs = this.getTypeRefs().filter((ref) => {
         return ref.kind !== "internal" || !exportedSymbols.has(ref.name);
@@ -4639,17 +4835,25 @@ class TsCodegen {
         refs
       };
     });
-    __publicField$8(this, "getTypeRefs", () => {
+    __publicField$9(this, "getTypeRefs", () => {
       return this.usedTypeRefs.map((ref) => ({ ...ref }));
     });
-    __publicField$8(this, "toDeclarationCode", (name, declaration) => {
+    __publicField$9(this, "toDeclarationCode", (name, d, o) => {
+      let code = this.toDeclarationBodyCode(name, d);
+      if (o.exported) {
+        code = `export ${code}`;
+      }
+      return this.addDoc(code, d.doc);
+    });
+    __publicField$9(this, "toDeclarationBodyCode", (name, declaration) => {
       switch (declaration.kind) {
         case "typeAlias":
           return `type ${name} = ${this.typeExprCodegen.toCode(declaration.typeExpr).code}`;
         case "enum": {
-          const members = declaration.members.map(
-            (member) => `    ${member.name} = ${JSON.stringify(member.value)}`
-          ).join(",\n");
+          const members = declaration.members.map((member) => {
+            const code = `${member.name} = ${JSON.stringify(member.value)}`;
+            return this.addDoc(code, member.doc);
+          }).join(",\n");
           return `enum ${name} {
 ${members}
 }`;
@@ -4662,6 +4866,13 @@ ${members}
         }
       }
     });
+    __publicField$9(this, "addDoc", (code, doc) => {
+      if (!doc) return code;
+      const rendered = this.docRenderer.render(doc);
+      return rendered ? `${rendered}
+${code}` : code;
+    });
+    this.docRenderer = docRenderer;
   }
   collectTypeRef(typeRef) {
     if (typeRef.kind === "builtin") return;
@@ -4787,12 +4998,13 @@ const toTsPropertyKey = (value) => {
   return isTsIdentifier(value) ? value : JSON.stringify(value);
 };
 
-var __defProp$7 = Object.defineProperty;
-var __defNormalProp$7 = (obj, key, value) => key in obj ? __defProp$7(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
-var __publicField$7 = (obj, key, value) => __defNormalProp$7(obj, typeof key !== "symbol" ? key + "" : key, value);
+var __defProp$8 = Object.defineProperty;
+var __defNormalProp$8 = (obj, key, value) => key in obj ? __defProp$8(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
+var __publicField$8 = (obj, key, value) => __defNormalProp$8(obj, typeof key !== "symbol" ? key + "" : key, value);
 class TypeExprCodegen {
-  constructor() {
-    __publicField$7(this, "toCode", (typeExpr) => {
+  constructor(docRenderer) {
+    __publicField$8(this, "docRenderer");
+    __publicField$8(this, "toCode", (typeExpr) => {
       switch (typeExpr.kind) {
         case "reference":
           return this.toReferenceCode(typeExpr);
@@ -4808,7 +5020,7 @@ class TypeExprCodegen {
         }
       }
     });
-    __publicField$7(this, "toReferenceCode", (typeExpr) => {
+    __publicField$8(this, "toReferenceCode", (typeExpr) => {
       if (!typeExpr.typeArgs?.length) {
         return {
           code: typeExpr.ref.name,
@@ -4821,7 +5033,7 @@ class TypeExprCodegen {
         ref: typeExpr.ref
       };
     });
-    __publicField$7(this, "toInlineCode", (expr) => {
+    __publicField$8(this, "toInlineCode", (expr) => {
       switch (expr.node) {
         case "scalar":
           return expr.name === "integer" ? "number" : expr.name;
@@ -4846,55 +5058,66 @@ class TypeExprCodegen {
         }
       }
     });
-    __publicField$7(this, "toIntersectionMemberCode", (typeExpr) => {
+    __publicField$8(this, "toIntersectionMemberCode", (typeExpr) => {
       const rendered = this.toCode(typeExpr).code;
       return this.isUnion(typeExpr) ? `(${rendered})` : rendered;
     });
-    __publicField$7(this, "toArrayElementCode", (typeExpr) => {
+    __publicField$8(this, "toArrayElementCode", (typeExpr) => {
       const rendered = this.toCode(typeExpr).code;
       return this.needsGroupingForArrayElement(typeExpr) ? `(${rendered})` : rendered;
     });
-    __publicField$7(this, "isUnion", (typeExpr) => {
+    __publicField$8(this, "isUnion", (typeExpr) => {
       return typeExpr.kind === "inline" && typeExpr.expr.node === "union";
     });
-    __publicField$7(this, "needsGroupingForArrayElement", (typeExpr) => {
+    __publicField$8(this, "needsGroupingForArrayElement", (typeExpr) => {
       return typeExpr.kind === "inline" && (typeExpr.expr.node === "union" || typeExpr.expr.node === "intersection");
     });
-    __publicField$7(this, "toLiteralCode", (value) => {
+    __publicField$8(this, "toLiteralCode", (value) => {
       if (value === null) return "null";
       return JSON.stringify(value);
     });
-    __publicField$7(this, "toObjectCode", (properties, additionalProperties) => {
+    __publicField$8(this, "toObjectCode", (properties, additionalProperties) => {
       const members = properties.map(
         (property) => this.toPropertyCode(property)
       );
       if (additionalProperties === true) {
-        members.push("[key: string]: unknown");
+        members.push("[key: string]: unknown;");
       } else if (additionalProperties !== void 0 && additionalProperties !== false) {
         members.push(
-          `[key: string]: ${this.toCode(additionalProperties).code}`
+          `[key: string]: ${this.toCode(additionalProperties).code};`
         );
       }
-      if (!members.length) return "{}";
-      return `{ ${members.join("; ")} }`;
+      return `{
+${members.join("\n")}
+}`;
     });
-    __publicField$7(this, "toPropertyCode", (property) => {
+    __publicField$8(this, "toPropertyCode", (property) => {
       const name = toTsPropertyKey(property.name);
       const optional = property.required ? "" : "?";
-      return `${name}${optional}: ${this.toCode(property.typeExpr).code}`;
-    });
+      const propertyCode = `${name}${optional}: ${this.toCode(property.typeExpr).code}`;
+      const docCode = property.doc ? this.docRenderer.render(property.doc, {
+        compactText: true
+      }) : "";
+      const renderedProperty = `${propertyCode};`;
+      return docCode ? `${docCode}
+${renderedProperty}` : renderedProperty;
+    });
+    this.docRenderer = docRenderer;
   }
 }
 
-var __defProp$6 = Object.defineProperty;
-var __defNormalProp$6 = (obj, key, value) => key in obj ? __defProp$6(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
-var __publicField$6 = (obj, key, value) => __defNormalProp$6(obj, typeof key !== "symbol" ? key + "" : key, value);
+var __defProp$7 = Object.defineProperty;
+var __defNormalProp$7 = (obj, key, value) => key in obj ? __defProp$7(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
+var __publicField$7 = (obj, key, value) => __defNormalProp$7(obj, typeof key !== "symbol" ? key + "" : key, value);
 class TsCodegenFactory {
-  constructor() {
-    __publicField$6(this, "typeExprCodegen", new TypeExprCodegen());
-    __publicField$6(this, "forNewChunk", () => {
-      return new TsCodegen(this.typeExprCodegen);
-    });
+  constructor(docRenderer) {
+    __publicField$7(this, "typeExprCodegen");
+    __publicField$7(this, "docRenderer");
+    __publicField$7(this, "forNewChunk", () => {
+      return new TsCodegen(this.typeExprCodegen, this.docRenderer);
+    });
+    this.docRenderer = docRenderer;
+    this.typeExprCodegen = new TypeExprCodegen(this.docRenderer);
   }
 }
 
@@ -4943,13 +5166,13 @@ const isReservedWord = (value) => {
   return RESERVED_WORDS.has(value);
 };
 
-var __defProp$5 = Object.defineProperty;
-var __defNormalProp$5 = (obj, key, value) => key in obj ? __defProp$5(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
-var __publicField$5 = (obj, key, value) => __defNormalProp$5(obj, typeof key !== "symbol" ? key + "" : key, value);
+var __defProp$6 = Object.defineProperty;
+var __defNormalProp$6 = (obj, key, value) => key in obj ? __defProp$6(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
+var __publicField$6 = (obj, key, value) => __defNormalProp$6(obj, typeof key !== "symbol" ? key + "" : key, value);
 class ParamsConstructor {
   constructor(options) {
     this.options = options;
-    __publicField$5(this, "process", (params, httpPath) => {
+    __publicField$6(this, "process", (params, httpPath) => {
       const pathParamSpec = validatePathParams(params, httpPath);
       const pathParamBindings = pathParamSpec?.bindings;
       const funParams = params.flatMap(
@@ -4969,7 +5192,7 @@ class ParamsConstructor {
         hasQuery
       };
     });
-    __publicField$5(this, "renderOperationParams", (param, pathParamSpec) => {
+    __publicField$6(this, "renderOperationParams", (param, pathParamSpec) => {
       if (param.kind !== "path" || !pathParamSpec) {
         return [
           {
@@ -4993,7 +5216,7 @@ class ParamsConstructor {
         }
       ];
     });
-    __publicField$5(this, "renderPathTemplateLiteral", (path, pathParamVarName, pathParamBindings) => {
+    __publicField$6(this, "renderPathTemplateLiteral", (path, pathParamVarName, pathParamBindings) => {
       const escapedPath = path.replace(/\\/g, "\\\\").replace(/`/g, "\\`").replace(/\$\{/g, "\\${");
       const pathWithParams = escapedPath.replace(
         /\{([^}]+)\}/g,
@@ -5007,7 +5230,7 @@ class ParamsConstructor {
       );
       return `\`${pathWithParams}\``;
     });
-    __publicField$5(this, "renderPathParamDestructuring", (pathParamBindings) => {
+    __publicField$6(this, "renderPathParamDestructuring", (pathParamBindings) => {
       const members = Object.entries(pathParamBindings).map(
         ([paramName, binding]) => {
           const key = toTsPropertyKey(paramName);
@@ -5016,7 +5239,7 @@ class ParamsConstructor {
       );
       return `{ ${members.join(", ")} }`;
     });
-    __publicField$5(this, "paramName", (p) => {
+    __publicField$6(this, "paramName", (p) => {
       switch (p.kind) {
         case "body":
           return this.options.paramNames.body;
@@ -5128,19 +5351,27 @@ const validatePathParams = (params, httpPath) => {
   };
 };
 
+const indentBlock = (value, indent) => {
+  if (!value || !indent) {
+    return value;
+  }
+  return value.split("\n").map((line) => `${indent}${line}`).join("\n");
+};
+
 const EMPTY_LINE_MARKER = "/*__EMPTY_LINE_MARKER__*/";
 
-var __defProp$4 = Object.defineProperty;
-var __defNormalProp$4 = (obj, key, value) => key in obj ? __defProp$4(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
-var __publicField$4 = (obj, key, value) => __defNormalProp$4(obj, typeof key !== "symbol" ? key + "" : key, value);
+var __defProp$5 = Object.defineProperty;
+var __defNormalProp$5 = (obj, key, value) => key in obj ? __defProp$5(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
+var __publicField$5 = (obj, key, value) => __defNormalProp$5(obj, typeof key !== "symbol" ? key + "" : key, value);
 const REQUEST_PARAMS_TYPE = "RequestParams";
 const REQUEST_PARAMS_DEFAULT = "never";
 const REQUEST_PARAMS_ARG = "params";
 class ApiClientCodegen {
-  constructor(opts, tsCodegenFactory) {
+  constructor(opts, tsCodegenFactory, docRenderer) {
     this.opts = opts;
     this.tsCodegenFactory = tsCodegenFactory;
-    __publicField$4(this, "generate", (apiName, operations) => {
+    this.docRenderer = docRenderer;
+    __publicField$5(this, "generate", (apiName, operations, doc) => {
       const tsCodegen = this.tsCodegenFactory.forNewChunk();
       const httpClientType = tsCodegen.typeExpr(this.opts.httpClient.typeName);
       let clientType = httpClientType;
@@ -5150,16 +5381,18 @@ class ApiClientCodegen {
         classTypeParams = `<${REQUEST_PARAMS_TYPE} = ${REQUEST_PARAMS_DEFAULT}>`;
       }
       const methodsCode = Array.isArray(operations) ? this.opsCode(tsCodegen, operations) : this.groupsOpsCode(tsCodegen, operations);
+      const classDocCode = this.renderApiClientDoc(doc, "");
       const code = `
-            export class ${apiName}${classTypeParams} {
-                constructor(private readonly client: ${clientType}) {}
+            ${classDocCode ? `${classDocCode}
+` : ""}export class ${apiName}${classTypeParams} {
+                constructor(private readonly http: ${clientType}) {}
 
                 ${methodsCode}
             }
         `;
       return tsCodegen.toChunk("api", code, [apiName]);
     });
-    __publicField$4(this, "groupsOpsCode", (codegen, groupedOps) => Object.entries(groupedOps).map(([groupName, ops]) => {
+    __publicField$5(this, "groupsOpsCode", (codegen, groupedOps) => Object.entries(groupedOps).map(([groupName, ops]) => {
       const methodsCode = this.opsCode(codegen, ops, "object");
       return `
                     ${toTsPropertyKey(groupName)} = {
@@ -5167,14 +5400,14 @@ class ApiClientCodegen {
                     }
                 `;
     }).join("\n\n"));
-    __publicField$4(this, "opsCode", (codegen, operations, target = "class") => {
+    __publicField$5(this, "opsCode", (codegen, operations, target = "class") => {
       const separator = target === "object" ? `,
 ${EMPTY_LINE_MARKER}
 ` : "\n\n";
       const methodsCode = operations.map((op) => this.renderOp(op, codegen, target)).join(separator);
       return methodsCode;
     });
-    __publicField$4(this, "renderOp", (op, tsCodegen, target) => {
+    __publicField$5(this, "renderOp", (op, tsCodegen, target) => {
       const { signature: sig, http } = op;
       const invocationVars = this.opts.httpClient.invocation.vars;
       const paramNames = {
@@ -5200,6 +5433,7 @@ ${EMPTY_LINE_MARKER}
       const responseType = tsCodegen.typeExpr(sig.returnType);
       const returnType = this.wrapInResponseWrapper(sig.returnType, tsCodegen);
       return this.renderFunctionCode({
+        doc: sig.doc,
         funName: sig.name,
         responseType,
         returnType,
@@ -5215,13 +5449,14 @@ ${EMPTY_LINE_MARKER}
         target
       });
     });
-    __publicField$4(this, "wrapInResponseWrapper", (typeExpr, tsCodegen) => {
+    __publicField$5(this, "wrapInResponseWrapper", (typeExpr, tsCodegen) => {
       return tsCodegen.typeExpr({
         ...this.opts.httpClient.responseWrapper,
         typeArgs: [typeExpr]
       });
     });
-    __publicField$4(this, "renderFunctionCode", ({
+    __publicField$5(this, "renderFunctionCode", ({
+      doc,
       funName,
       responseType,
       returnType,
@@ -5253,9 +5488,74 @@ ${EMPTY_LINE_MARKER}
       invocation = invocation.replaceAll("\n", "");
       const operator = target === "object" ? ":" : "=";
       const returnTypeCode = this.opts.httpClient.inferMethodReturnType ? "" : `:${returnType}`;
-      return `${funName} ${operator} (${params})${returnTypeCode} => 
-             this.client${invocation}
+      const functionCode = `${funName} ${operator} (${params})${returnTypeCode} => 
+             this.http${invocation}
         `;
+      const docCode = this.renderOperationDoc(
+        doc,
+        this.opts.comments,
+        target === "object" ? "        " : "    "
+      );
+      return docCode ? `${docCode}
+${functionCode}` : functionCode;
+    });
+    __publicField$5(this, "renderOperationDoc", (doc, comments, indent = "") => {
+      if (!doc) return null;
+      return indentBlock(this.docRenderer.render(this.toTsDoc(doc)), indent);
+    });
+    __publicField$5(this, "renderApiClientDoc", (doc, indent = "") => {
+      if (!doc) return "";
+      return indentBlock(
+        this.docRenderer.render({
+          nodes: [
+            {
+              key: "title",
+              value: doc.title
+            },
+            {
+              key: "version",
+              value: doc.version
+            },
+            ...doc.description ? [doc.description] : []
+          ]
+        }),
+        indent
+      );
+    });
+    __publicField$5(this, "toTsDoc", (doc) => {
+      const nodes = [
+        {
+          key: "id",
+          value: doc.id
+        }
+      ];
+      const comms = this.opts.comments;
+      if ((comms.summary ?? true) && doc.summary) {
+        nodes.push({
+          key: "summary",
+          value: doc.summary
+        });
+      }
+      if ((comms.description ?? true) && doc.description) {
+        nodes.push({
+          key: "description",
+          value: doc.description
+        });
+      }
+      nodes.push({
+        key: "request",
+        value: doc.request
+      });
+      if ((comms.tags ?? true) && doc.tags.length) {
+        nodes.push({
+          key: "tags",
+          value: doc.tags.join(", ")
+        });
+      }
+      return {
+        deprecated: doc.deprecated,
+        nodes
+      };
     });
   }
 }
@@ -5424,21 +5724,102 @@ const provideHttpClientCode = (gen, opts) => gen.toChunk(
   ["HttpRequest", "HttpResponse", "HttpClient"]
 );
 
+var __defProp$4 = Object.defineProperty;
+var __defNormalProp$4 = (obj, key, value) => key in obj ? __defProp$4(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
+var __publicField$4 = (obj, key, value) => __defNormalProp$4(obj, typeof key !== "symbol" ? key + "" : key, value);
+class TsDocRenderer {
+  constructor(options) {
+    this.options = options;
+    __publicField$4(this, "render", (doc, options = {}) => {
+      if (!this.options.enabled) return "";
+      const lines = [];
+      this.appendNodes(lines, doc.nodes, options);
+      if (doc.deprecated) {
+        this.appendDeprecated(lines, { separate: lines.length > 0 });
+      }
+      return this.renderComment(lines);
+    });
+    __publicField$4(this, "renderComment", (lines) => {
+      if (!this.options.enabled) return "";
+      if (!lines.length) return "";
+      if (lines.length === 1) {
+        return `/** ${lines[0]} */`;
+      }
+      const body = lines.map((line) => line ? ` * ${line}` : " *").join("\n");
+      return `/**
+${body}
+ */`;
+    });
+    __publicField$4(this, "appendDocText", (lines, value) => {
+      const normalized = this.normalizeLines(value);
+      if (!normalized.length) return;
+      if (lines.length > 0) {
+        lines.push("");
+      }
+      lines.push(...normalized);
+    });
+    __publicField$4(this, "appendField", (lines, key, value) => {
+      const normalized = this.normalizeLines(value);
+      if (!normalized.length) return;
+      lines.push(`@${key} ${normalized[0]}`.trimEnd());
+      lines.push(...normalized.slice(1));
+    });
+    __publicField$4(this, "appendDeprecated", (lines, options) => {
+      if (options.separate) {
+        lines.push("");
+      }
+      lines.push("@deprecated");
+    });
+    __publicField$4(this, "appendNodes", (lines, nodes = [], options = {}) => {
+      nodes.forEach((node) => {
+        if (typeof node === "string") {
+          if (options.compactText) {
+            lines.push(...this.normalizeNonEmptyLines(node));
+            return;
+          }
+          this.appendDocText(lines, node);
+          return;
+        }
+        this.appendField(lines, node.key, node.value);
+      });
+    });
+    __publicField$4(this, "normalizeLines", (value) => {
+      const trimmed = value?.trim();
+      if (!trimmed) return [];
+      return trimmed.split(/\r?\n/u).map((line) => line.trimEnd().replaceAll("*/", "*\\/"));
+    });
+    __publicField$4(this, "normalizeNonEmptyLines", (value) => this.normalizeLines(value).filter((line) => line.length > 0));
+  }
+}
+
 const generateTsCode = (clientName, projectResult, opts) => {
-  const tsCodegenFac = new TsCodegenFactory();
+  const docRenderer = new TsDocRenderer({
+    enabled: opts.comments.enabled
+  });
+  const tsCodegenFac = new TsCodegenFactory(docRenderer);
   const { schemaDefinitions } = projectResult;
   const types = [...schemaDefinitions].sort((a, b) => a.name.localeCompare(b.name)).map((def) => {
     const cg = tsCodegenFac.forNewChunk();
-    const code = `export ${cg.declaration(def.name, def.declaration)}`;
+    const code = cg.declaration(def.name, def.declaration, {
+      exported: true
+    });
     return cg.toChunk(def.name, code, [def.name]);
   });
   const clientCodegen = new ApiClientCodegen(
-    { httpClient: promiseHttpClientCodegenSpec(), ...opts },
-    tsCodegenFac
+    {
+      httpClient: promiseHttpClientCodegenSpec(),
+      comments: opts.comments.operation,
+      unwrap: opts.unwrap,
+      pathParamsStyle: opts.pathParamsStyle,
+      withRequestParams: opts.withRequestParams
+    },
+    tsCodegenFac,
+    docRenderer
   );
   const generated = clientCodegen.generate(
     clientName,
-    groupsOpsByTag(projectResult.operations)
+    groupsOpsByTag(projectResult.operations),
+    projectResult.api
   );
   const clientChunk = {
     ...generated,
@@ -5648,6 +6029,7 @@ class ToTypeExprConverter {
       }
       return {
         kind: "typeAlias",
+        doc: this.getSchemaDoc(schema),
         typeExpr: this.fromTypeExpr(schema)
       };
     });
@@ -5661,6 +6043,7 @@ class ToTypeExprConverter {
       }
       return {
         kind: "enum",
+        doc: this.getSchemaDoc(schema),
         valueType,
         members: this.toEnumMembers(schema.enum)
       };
@@ -5776,6 +6159,7 @@ class ToTypeExprConverter {
             );
           }
           return {
+            doc: this.getSchemaDoc(propertySchema),
             name,
             required: this.isRequiredProperty(
               name,
@@ -5836,6 +6220,71 @@ class ToTypeExprConverter {
     __publicField$3(this, "isBinaryFileSchema", (schema) => {
       return schema.type === "string" && schema.format === "binary";
     });
+    __publicField$3(this, "getSchemaDoc", (schema) => {
+      const summary = typeof schema.summary === "string" ? schema.summary : void 0;
+      const description = typeof schema.description === "string" ? schema.description : void 0;
+      const deprecated = typeof schema.deprecated === "boolean" ? schema.deprecated : void 0;
+      const annotations = this.getSchemaAnnotations(schema);
+      if (!summary && !description && !deprecated && !annotations.length) {
+        return void 0;
+      }
+      const nodes = [];
+      if (summary) {
+        nodes.push(summary);
+      }
+      if (description) {
+        nodes.push(description);
+      }
+      nodes.push(...annotations);
+      return {
+        deprecated,
+        nodes
+      };
+    });
+    __publicField$3(this, "getSchemaAnnotations", (schema) => {
+      if (this.options.comments?.metadata === false) return [];
+      return [
+        this.annotationNode("format", schema.format),
+        this.annotationNode("min", schema.minimum),
+        this.annotationNode("multipleOf", schema.multipleOf),
+        this.annotationNode("exclusiveMin", schema.exclusiveMinimum),
+        this.annotationNode("max", schema.maximum),
+        this.annotationNode("minLength", schema.minLength),
+        this.annotationNode("maxLength", schema.maxLength),
+        this.annotationNode("exclusiveMax", schema.exclusiveMaximum),
+        this.annotationNode("maxItems", schema.maxItems),
+        this.annotationNode("minItems", schema.minItems),
+        this.annotationNode("uniqueItems", schema.uniqueItems),
+        this.annotationNode(
+          "default",
+          this.stringifyAnnotationValue(schema.default)
+        ),
+        this.annotationNode("pattern", schema.pattern),
+        this.annotationNode(
+          "example",
+          this.stringifyAnnotationValue(schema.example)
+        )
+      ].filter(
+        (value) => value !== void 0
+      );
+    });
+    __publicField$3(this, "annotationNode", (name, value) => {
+      if (value === void 0) return void 0;
+      return {
+        key: name,
+        value: String(value)
+      };
+    });
+    __publicField$3(this, "stringifyAnnotationValue", (value) => {
+      if (value === void 0) return void 0;
+      if (value && typeof value === "object") {
+        return JSON.stringify(value);
+      }
+      if (typeof value === "string") {
+        return JSON.stringify(value);
+      }
+      return String(value);
+    });
     __publicField$3(this, "fromSchemaCore", (schema) => {
       if (this.isUnconstrainedSchema(schema)) {
         return this.scalar("unknown");
@@ -6022,6 +6471,11 @@ class OperationProjector {
         return this.projectOne(operationName, operation);
       });
       return {
+        api: {
+          title: openApi.info.title,
+          version: openApi.info.version,
+          description: openApi.info.description
+        },
         operations,
         schemaDefinitions: this.typeExprConverter.getSchemaDefinitions()
       };
@@ -6038,6 +6492,7 @@ class OperationProjector {
       return {
         op: {
           signature: {
+            doc: this.toOperationDoc(operationName, operation),
             name: operationName,
             parameters,
             returnType: this.projectReturnType(operation)
@@ -6086,6 +6541,7 @@ class OperationProjector {
     });
     __publicField$2(this, "projectParameterGroupTypeExpr", (params) => {
       const properties = Object.entries(params).map(([name, parameter]) => ({
+        doc: this.toParameterDoc(parameter),
         name,
         required: parameter.required,
         typeExpr: this.typeExprConverter.fromTypeExpr(
@@ -6158,6 +6614,25 @@ class OperationProjector {
     __publicField$2(this, "selectResponseSchema", (response) => {
       return getPreferredMediaTypeEntry(response.content).media?.schema;
     });
+    __publicField$2(this, "toParameterDoc", (parameter) => {
+      if (!parameter.description && !parameter.deprecated) {
+        return void 0;
+      }
+      return {
+        deprecated: parameter.deprecated,
+        nodes: parameter.description ? [parameter.description] : []
+      };
+    });
+    __publicField$2(this, "toOperationDoc", (operationName, operation) => {
+      return {
+        id: operationName,
+        request: `${toHttpMethodUpper(operation.method)}:${operation.path}`,
+        summary: operation.summary,
+        description: operation.description,
+        deprecated: operation.deprecated,
+        tags: operation.tags.map((tag) => tag.trim()).filter(Boolean)
+      };
+    });
   }
 }
 
@@ -6283,6 +6758,7 @@ class VNextOasClientGenerator {
     const projectResult = new OperationProjector({
       includeAllSchema: this.options.selection?.allSchemas === true,
       typeExtraction: {
+        comments: this.options.codegen.comments.schema,
         enumStyle: this.options.codegen.enumStyle,
         uppercaseEnumKeys: this.options.compat?.uppercaseEnumKeys,
         swaggerTsApiRequiredBooleans: this.options.compat?.swaggerTsApiRequiredBooleans
@@ -6505,7 +6981,10 @@ const getModuleImportPath = (inputFile, outputFile) => {
 };
 
 const generateApiClient = async (params, configFilePath, log = console.log) => {
-  const config = parseConfig(params, configFilePath);
+  const config = parseProfileConfig(params, configFilePath);
+  return generateApiClientFromConfig(config, log);
+};
+const generateApiClientFromConfig = async (config, log = console.log) => {
   const { dstDir, apiName, srcSpec, zodSchemas } = config;
   const dir = Path.resolve(dstDir, apiName);
   if (!fs__namespace.existsSync(dir)) {
@@ -6552,4 +7031,7 @@ const getSpecPath = async (urlOrPath, dir, log) => {
   return specPath;
 };
 
+exports.defineConfig = defineConfig;
 exports.generateApiClient = generateApiClient;
+exports.generateApiClientFromConfig = generateApiClientFromConfig;
+exports.parseConfig = parseConfig;