@postman/sdk-config 0.8.0 → 0.9.0

package/dist/sdk-config/index.js

@@ -297,7 +297,7 @@ var retryConfigSchema = z.strictObject({
   maxDelayMs: z.number().nonnegative().default(5e3).describe("The maximum backoff delay between attempts, in milliseconds."),
   jitterMs: z.number().nonnegative().default(50).describe("The maximum random jitter added to retry delays, in milliseconds."),
   backoffFactor: z.number().positive().default(2).describe("The multiplier applied to the delay after each failed attempt."),
-  methods: z.array(nonEmptyStringSchema).default(["GET", "POST", "PUT", "DELETE", "PATCH", "HEAD", "OPTIONS"]).describe("HTTP methods that are eligible for retries."),
+  methods: z.array(nonEmptyStringSchema).default(["GET", "PUT", "DELETE", "HEAD", "OPTIONS"]).describe("HTTP methods that are eligible for retries."),
   maxRetryAfterDelayMs: z.number().nonnegative().default(6e4).describe("The longest Retry-After delay the client will honor, in milliseconds.")
 }).superRefine(validateRetryDelays);
 var constructorParameterSchema = z.strictObject({
@@ -323,6 +323,22 @@ var tokenRefreshConfigSchema = z.strictObject({
     });
   }
 });
+var idempotencyKeyGenerationSchema = z.strictObject({
+  enabled: z.boolean().describe("Whether the client generates an idempotency key when the caller supplies none."),
+  headerName: nonEmptyStringSchema.optional().describe("The header that carries the generated key. Generators default to Idempotency-Key."),
+  methods: z.array(nonEmptyStringSchema).optional().describe("HTTP methods that receive a generated key. Generators default to POST and PUT.")
+});
+var userAgentConfigSchema = z.strictObject({
+  template: nonEmptyStringSchema.optional().describe(
+    "The User-Agent product token, resolved at generation time. Supports the {packageName}, {version}, {language}, {generatorVersion}, {organization}, and {apiName} placeholders."
+  ),
+  includePlatformInfo: z.boolean().optional().describe(
+    "Whether the User-Agent carries operating system, architecture, and runtime details, as `{product} ({os}; {arch}) {runtime}/{runtimeVersion}`."
+  ),
+  allowAppInfo: z.boolean().optional().describe(
+    "Whether callers can pass application info that is appended to the User-Agent as a `{name}/{version} ({comment})` product token."
+  )
+});
 var clientOverrideShape = {
   retry: clientRetryOverrideSchema.optional().describe("Retry behavior for generated API requests."),
   responseHeaders: z.boolean().optional().describe("Whether generated operations expose HTTP response headers."),
@@ -335,7 +351,12 @@ var clientOverrideShape = {
   filePropertyStyle: parameterStyleSchema.optional().describe("Whether generated file properties are wrapped or passed inline."),
   useDefaultRequestParameterValues: z.boolean().optional().describe("Whether schema defaults are applied to omitted request parameters."),
   respectOptionalRequestBody: z.boolean().optional().describe("Whether an optional request body remains optional in generated methods."),
-  tokenRefresh: tokenRefreshConfigSchema.optional().describe("Refresh-token behavior for the generated client.")
+  tokenRefresh: tokenRefreshConfigSchema.optional().describe("Refresh-token behavior for the generated client."),
+  idempotencyKeyGeneration: idempotencyKeyGenerationSchema.optional().describe("Automatic idempotency keys on eligible requests."),
+  userAgent: userAgentConfigSchema.optional().describe("The User-Agent header the generated client sends."),
+  offsetSemantics: z.enum(["item-index", "page-index"]).optional().describe(
+    "How an offset-paginated endpoint advances: by the number of items returned, or by one page."
+  )
 };
 var clientConfigOverrideSchema = z.strictObject(clientOverrideShape);
 var clientConfigSchema = z.strictObject({
@@ -2405,6 +2426,14 @@ function mapInvocation(generator, language, activeLanguages, index) {
     ...prefix,
     "config"
   ]);
+  const apiWideIdempotency = idempotencyKeyGenerationFrom(
+    generator.idempotencyKeyGenerationConfig,
+    [...prefix, "idempotencyKeyGenerationConfig"],
+    state
+  );
+  if (apiWideIdempotency && client.idempotencyKeyGeneration === void 0) {
+    client.idempotencyKeyGeneration = apiWideIdempotency;
+  }
   const rawGenerator = isObject(generator.raw) ? generator.raw : void 0;
   const smartCasing = typeof rawGenerator?.["smart-casing"] === "boolean" ? rawGenerator["smart-casing"] : generator.smartCasing === false ? false : void 0;
   const smartCasingDigitWordBoundary = typeof rawGenerator?.["smart-casing-digit-word-boundary"] === "boolean" ? rawGenerator["smart-casing-digit-word-boundary"] : generator.smartCasingDigitWordBoundary === true ? true : void 0;
@@ -2438,16 +2467,19 @@ function mapInvocation(generator, language, activeLanguages, index) {
     ...collectUnsupported(config, [...prefix, "config"], state),
     ...settings ? collectUnsupported(settings, [...prefix, "settings"], state) : [],
     ...isObject(generator.readme) ? collectUnsupported(generator.readme, [...prefix, "readme"], state) : [],
-    ...unsupportedResolvedFields(generator, index)
+    ...unsupportedResolvedFields(generator, index, apiWideIdempotency !== void 0)
   ];
   return { client, docs, generation, package: packageConfig, targetGeneration, unsupportedFields };
 }
-function unsupportedResolvedFields(generator, index) {
+function unsupportedResolvedFields(generator, index, idempotencyMapped) {
   const values = [
     ["automation", isDefaultAutomation(generator.automation) ? void 0 : generator.automation],
     ["containerImage", generator.containerImage],
     ["irVersionOverride", generator.irVersionOverride],
-    ["idempotencyKeyGenerationConfig", generator.idempotencyKeyGenerationConfig],
+    [
+      "idempotencyKeyGenerationConfig",
+      idempotencyMapped ? void 0 : generator.idempotencyKeyGenerationConfig
+    ],
     ["absolutePathToLocalSnippets", generator.absolutePathToLocalSnippets],
     [
       "disableExamples",
@@ -2480,7 +2512,8 @@ function resolvedFieldGuidance(field) {
   }
   if (field === "idempotencyKeyGenerationConfig") {
     return {
-      suggestedAction: "Preserve this orchestration setting outside SDK Config; public v1 has no idempotency-generation field."
+      sdkConfigPath: ["client", "idempotencyKeyGeneration"],
+      suggestedAction: "Use true, false, or an object with header-name and methods, or set client.idempotencyKeyGeneration manually."
     };
   }
   if (field === "generateFullProject") {
@@ -2495,6 +2528,20 @@ function resolvedFieldGuidance(field) {
 function isDefaultAutomation(value) {
   return isObject(value) && value.generate === true && value.upgrade === true && value.preview === true && value.verify === true;
 }
+var HTTP_METHODS = ["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"];
+function idempotencyKeyGenerationFrom(value, path, state) {
+  if (typeof value === "boolean") {
+    consume(state, path);
+    return { enabled: value };
+  }
+  if (!isObject(value)) return void 0;
+  const probe = { consumedPaths: /* @__PURE__ */ new Set() };
+  const headerName = takeString(value, ["headerName"], probe, path);
+  const methods = takeEnumArray(value, ["methods"], HTTP_METHODS, probe, path);
+  if (probe.consumedPaths.size !== Object.keys(value).length) return void 0;
+  consume(state, path);
+  return { enabled: true, ...optional("headerName", headerName), ...optional("methods", methods) };
+}
 function mapCommonConfig(language, config, state, client, generation, packageConfig, basePath) {
   const inlinePath = takeBoolean(config, ["inlinePathParameters"], state, basePath);
   const inlineFile = takeBoolean(config, ["inlineFileProperties"], state, basePath);
@@ -2519,6 +2566,23 @@ function mapCommonConfig(language, config, state, client, generation, packageCon
   if (useDefaults !== void 0) client.useDefaultRequestParameterValues = useDefaults;
   const respectOptionalBody = takeBoolean(config, ["respectOptionalRequestBody"], state, basePath);
   if (respectOptionalBody !== void 0) client.respectOptionalRequestBody = respectOptionalBody;
+  const idempotency = locate(config, ["autoGenerateIdempotencyKey"], basePath);
+  const idempotencyKeyGeneration = idempotency && idempotencyKeyGenerationFrom(idempotency.value, idempotency.path, state);
+  if (idempotencyKeyGeneration) client.idempotencyKeyGeneration = idempotencyKeyGeneration;
+  const userAgent = compact({
+    template: takeString(config, ["userAgent"], state, basePath),
+    includePlatformInfo: takeBoolean(config, ["includePlatformHeaders"], state, basePath),
+    allowAppInfo: takeBoolean(config, ["allowUserAgentAppInfo"], state, basePath)
+  });
+  if (Object.keys(userAgent).length) client.userAgent = userAgent;
+  const offsetSemantics = takeEnum(
+    config,
+    ["offsetSemantics"],
+    ["item-index", "page-index"],
+    state,
+    basePath
+  );
+  if (offsetSemantics !== void 0) client.offsetSemantics = offsetSemantics;
   const maxRetries = takeNumber(config, ["maxRetries"], state, basePath);
   const statusCodeProfile = takeEnum(
     config,
@@ -2536,7 +2600,10 @@ function mapCommonConfig(language, config, state, client, generation, packageCon
   const pythonClient = language === "python" ? takeObject(config, ["client"], state, basePath) : void 0;
   const typescriptNaming = language === "typescript" || language === "mcp" ? takeObject(config, ["naming"], state, basePath) : void 0;
   const directClientName = takeString(config, ["clientName", "clientClassName"], state, basePath);
-  const nestedClientName = pythonClient ? takeString(pythonClient.value, ["className"], state, pythonClient.path) : typescriptNaming ? takeString(typescriptNaming.value, ["client"], state, typescriptNaming.path) : void 0;
+  const nestedClientName = pythonClient ? takeString(pythonClient.value, ["className"], state, pythonClient.path) : typescriptNaming ? takeString(typescriptNaming.value, ["client"], state, typescriptNaming.path) : language === "ruby" ? (
+    // Fern's Ruby generator renames the root client class (`Auth0::Management`) with it.
+    takeString(config, ["clientModuleName"], state, basePath)
+  ) : void 0;
   const directExportedClientName = takeString(
     config,
     ["exportedClientName", "exportedClientClassName"],
@@ -2807,6 +2874,8 @@ function mapComposerRequirements(manifest, state, packageConfig) {
 function mapRuby(config, state, packageConfig, basePath) {
   const moduleName = takeString(config, ["moduleName"], state, basePath);
   if (moduleName !== void 0) packageConfig.moduleName = moduleName;
+  const packageName = takeString(config, ["package-name"], state, basePath);
+  if (packageName !== void 0) packageConfig.packageName = packageName;
   return compact({ requirePaths: takeStringArray(config, ["requirePaths"], state, basePath) });
 }
 function mapRust(config, state, packageConfig, basePath) {