@postman/sdk-config 0.8.0 → 0.10.1

package/dist/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({
@@ -650,8 +671,19 @@ function mapOutput(generator, language, index) {
   const outputPath = ["group", "generators", index, "outputMode"];
   const state = { consumedPaths: /* @__PURE__ */ new Set(), credentialDiagnostics: [] };
   if (generator.output) {
+    const downloadSnippets = mapDownloadSnippets(
+      generator.outputMode,
+      outputPath,
+      state,
+      language,
+      index
+    );
     return {
       output: sanitizeNormalizedOutput(generator.output, rawOutput, state, index),
+      ...optional(
+        "docs",
+        downloadSnippets === void 0 ? void 0 : { snippets: { enabled: downloadSnippets } }
+      ),
       unsupportedFields: state.credentialDiagnostics ?? []
     };
   }
@@ -667,7 +699,8 @@ function mapOutput(generator, language, index) {
       generator.outputMode,
       outputPath,
       state,
-      index
+      index,
+      language
     );
   }
   if (!isObject(generator.outputMode) || typeof generator.outputMode.type !== "string") {
@@ -683,14 +716,22 @@ function mapOutput(generator, language, index) {
   consume(state, [...outputPath, "type"]);
   switch (output.type) {
     case "downloadFiles":
-      return finishOutputMapping({ output: { delivery: "zip" } }, output, outputPath, state, index);
+      return finishOutputMapping(
+        { output: { delivery: "zip" } },
+        output,
+        outputPath,
+        state,
+        index,
+        language
+      );
     case "github":
       return finishOutputMapping(
         githubOutput(output, output.publishInfo, rawOutput, language, outputPath, state, index),
         output,
         outputPath,
         state,
-        index
+        index,
+        language
       );
     case "githubV2": {
       if (!isObject(output.githubV2))
@@ -715,7 +756,8 @@ function mapOutput(generator, language, index) {
         output,
         outputPath,
         state,
-        index
+        index,
+        language
       );
     }
     case "publishV2": {
@@ -735,7 +777,8 @@ function mapOutput(generator, language, index) {
         output,
         outputPath,
         state,
-        index
+        index,
+        language
       );
     }
     case "publish": {
@@ -755,7 +798,8 @@ function mapOutput(generator, language, index) {
         output,
         outputPath,
         state,
-        index
+        index,
+        language
       );
     }
     default:
@@ -1262,7 +1306,8 @@ function mapAuthors(value, sourcePath, state) {
   });
   return authors;
 }
-function finishOutputMapping(mapping, outputMode, sourcePath, state, index) {
+function finishOutputMapping(mapping, outputMode, sourcePath, state, index, language) {
+  const downloadSnippets = mapDownloadSnippets(outputMode, sourcePath, state, language, index);
   for (const path of collectLeafPaths(outputMode, sourcePath)) {
     if (path[path.length - 1] === "_visit") consume(state, path);
   }
@@ -1270,6 +1315,10 @@ function finishOutputMapping(mapping, outputMode, sourcePath, state, index) {
   const hasCredentials = unsupported.some((diagnostic) => isCredentialPath(diagnostic.path));
   return {
     ...mapping,
+    ...optional(
+      "docs",
+      downloadSnippets === void 0 ? void 0 : { snippets: { enabled: downloadSnippets } }
+    ),
     unsupportedFields: [
       ...state.credentialDiagnostics ?? [],
       ...hasCredentials ? [
@@ -1289,6 +1338,45 @@ function finishOutputMapping(mapping, outputMode, sourcePath, state, index) {
     ]
   };
 }
+function mapDownloadSnippets(value, sourcePath, state, language, index) {
+  if (!isObject(value)) return void 0;
+  const candidates = [];
+  switch (value.type) {
+    case "downloadFiles":
+    case "github":
+      candidates.push({ value, path: sourcePath });
+      break;
+    case "githubV2":
+      if (isObject(value.githubV2)) {
+        candidates.push({ value: value.githubV2, path: [...sourcePath, "githubV2"] });
+      }
+      break;
+    case "publishV2":
+      if (isObject(value.publishV2)) {
+        candidates.push({ value: value.publishV2, path: [...sourcePath, "publishV2"] });
+      }
+      break;
+    case "publish":
+      if (isObject(value.registryOverrides)) {
+        const registry = defaultRegistry(language, [...sourcePath, "registryOverrides"], index);
+        const override = value.registryOverrides[registry];
+        if (isObject(override)) {
+          candidates.push({
+            value: override,
+            path: [...sourcePath, "registryOverrides", registry]
+          });
+        }
+      }
+      break;
+  }
+  let enabled;
+  for (const candidate of candidates) {
+    if (typeof candidate.value.downloadSnippets !== "boolean") continue;
+    consume(state, [...candidate.path, "downloadSnippets"]);
+    enabled = enabled === true || candidate.value.downloadSnippets;
+  }
+  return enabled;
+}
 function isCredentialPath(path) {
   const fields = path.filter((part) => typeof part === "string");
   const field = fields[fields.length - 1];
@@ -2224,11 +2312,12 @@ function mapFernConfigToSdkConfigV1(input) {
       generator,
       language,
       invocation,
-      ...outputMapping
+      ...outputMapping,
+      docs: { ...invocation.docs, ...outputMapping.docs }
     };
   });
   const clients = partitionSharedBlock(mapped.map(({ invocation }) => invocation.client));
-  const docs = partitionSharedBlock(mapped.map(({ invocation }) => invocation.docs));
+  const docs = partitionSharedBlock(mapped.map(({ docs: docs2 }) => docs2));
   const generations = partitionSharedBlock(mapped.map(({ invocation }) => invocation.generation));
   const api = { ...input.api ?? {} };
   delete api.audiences;
@@ -2417,6 +2506,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;
@@ -2450,16 +2547,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",
@@ -2492,7 +2592,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") {
@@ -2507,6 +2608,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);
@@ -2531,6 +2646,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,
@@ -2548,7 +2680,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"],
@@ -2717,7 +2852,8 @@ function mapPython(config, state, packageConfig, basePath) {
   });
 }
 function mapJvm(language, config, state, packageConfig, basePath) {
-  const namespace = takeString(config, ["packageName", "packagePrefix"], state, basePath);
+  const namespaceAliases = language === "java" ? ["packagePrefix"] : ["packageName", "packagePrefix"];
+  const namespace = takeString(config, namespaceAliases, state, basePath);
   const groupId = takeString(config, ["group", "groupId"], state, basePath);
   const artifactId = takeString(config, ["artifact", "artifactId"], state, basePath);
   if (namespace !== void 0) packageConfig.namespace = namespace;
@@ -2819,6 +2955,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) {