@postman/sdk-config 0.5.0 → 0.6.0

package/README.md

@@ -81,11 +81,26 @@ a dedicated secret channel and remove them from generation payloads, logs, and s
 Fern migration preserves a credential only when the raw `generators.yml` value is exactly an
 environment expression; normalized, resolved, or literal values are omitted with a warning.
 
+Service-to-service consumers that must remain compatible with additive V1 fields can use
+`parseSdkConfigV1ForConsumption`. It ignores unknown object properties recursively while retaining
+all validation for known fields. Customer-authored configuration should continue to use the strict
+parser or validator so misspellings are reported.
+
 `SdkConfigV1` accepts customer-facing local source paths and HTTP(S) source URLs, but not
 server-owned signed URLs or artifact metadata. See the
 [SDK Config v1 reference](src/sdk-config/v1/README.md) for source materialization and target
 precedence rules.
 
+## Version 1 evolution policy
+
+SDK Config V1 and SDK Config IR V1 evolve additively. New properties must be optional. Existing
+properties cannot be removed, renamed, narrowed, or made required; those changes require a new
+schema version. Adding an enum or union member is also not automatically forward-compatible because
+an older consumer cannot ignore an unfamiliar value.
+
+Schema contract fingerprints make every V1 shape change visible in review. Do not update those
+fingerprints for a removal, rename, narrower type, or newly required property under V1.
+
 ## Use SDK Config in an SDK Generation API request
 
 An SDK Generation API request combines three kinds of data:

package/dist/index.cjs

@@ -1246,10 +1246,16 @@ function finishOutputMapping(mapping, outputMode, sourcePath, state, index) {
   for (const path of collectLeafPaths(outputMode, sourcePath)) {
     if (path[path.length - 1] === "_visit") consume(state, path);
   }
+  const legacyGenerateFullProject = isObject(outputMode) ? outputMode.generateFullProject : void 0;
+  const generationShape = typeof legacyGenerateFullProject === "boolean" ? { generation: { ...mapping.generation, generateFullProject: legacyGenerateFullProject } } : {};
+  if (typeof legacyGenerateFullProject === "boolean") {
+    consume(state, [...sourcePath, "generateFullProject"]);
+  }
   const unsupported = collectUnsupported(outputMode, sourcePath, state);
   const hasCredentials = unsupported.some((diagnostic) => isCredentialPath(diagnostic.path));
   return {
     ...mapping,
+    ...generationShape,
     unsupportedFields: [
       ...state.credentialDiagnostics ?? [],
       ...hasCredentials ? [
@@ -1333,6 +1339,125 @@ function outputDiagnostic(path, index) {
     suggestedAction: resolvedGuidance?.suggestedAction ?? "Review this output setting and preserve it outside SDK Config when no equivalent exists."
   };
 }
+var OMIT = /* @__PURE__ */ Symbol("omit");
+function inputJsonSchema(schema) {
+  return zod.z.toJSONSchema(schema, {
+    io: "input",
+    unrepresentable: "any"
+  });
+}
+function stripUnknownProperties(value, schema) {
+  return project(value, schema, schema, false);
+}
+function omitSchemaDefaults(value, schema) {
+  const projected = project(value, schema, schema, true);
+  return projected === OMIT ? void 0 : projected;
+}
+function project(value, candidateSchema, rootSchema, omitDefaults) {
+  const resolvedCandidate = resolveSchema(candidateSchema, rootSchema);
+  if (omitDefaults && Object.hasOwn(resolvedCandidate, "default") && deepEqual(value, resolvedCandidate.default)) {
+    return OMIT;
+  }
+  const schema = selectSchema(value, resolvedCandidate, rootSchema);
+  if (omitDefaults && schema !== resolvedCandidate && Object.hasOwn(schema, "default") && deepEqual(value, schema.default)) {
+    return OMIT;
+  }
+  if (Array.isArray(value)) {
+    if (!schema.items) return value;
+    return value.map((item) => {
+      const projected = project(item, schema.items, rootSchema, omitDefaults);
+      return projected === OMIT ? item : projected;
+    });
+  }
+  if (!isRecord(value) || schema.type !== "object") return value;
+  const entries = [];
+  const properties = schema.properties ?? {};
+  const unionProperties = omitDefaults ? properties : collectAlternativeProperties(resolvedCandidate, rootSchema);
+  for (const [key, propertySchema] of Object.entries(properties)) {
+    if (!Object.hasOwn(value, key)) continue;
+    const projected = project(value[key], propertySchema, rootSchema, omitDefaults);
+    if (projected !== OMIT) entries.push([key, projected]);
+  }
+  for (const [key, fieldValue] of Object.entries(value)) {
+    if (Object.hasOwn(properties, key)) continue;
+    if (Object.hasOwn(unionProperties, key)) {
+      entries.push([key, fieldValue]);
+      continue;
+    }
+    if (schema.additionalProperties !== false) {
+      const projected = typeof schema.additionalProperties === "object" ? project(fieldValue, schema.additionalProperties, rootSchema, omitDefaults) : fieldValue;
+      if (projected !== OMIT) entries.push([key, projected]);
+    } else if (omitDefaults) {
+      throw new Error(`Cannot serialize property unknown to the wire schema: ${key}`);
+    }
+  }
+  return Object.fromEntries(entries);
+}
+function collectAlternativeProperties(schema, rootSchema) {
+  const alternatives = schema.oneOf ?? schema.anyOf;
+  if (!alternatives) return schema.properties ?? {};
+  return Object.assign(
+    {},
+    ...alternatives.map((alternative) => resolveSchema(alternative, rootSchema).properties ?? {})
+  );
+}
+function selectSchema(value, schema, rootSchema) {
+  const alternatives = schema.oneOf ?? schema.anyOf;
+  if (!alternatives || alternatives.length === 0) return schema;
+  const best = alternatives.map((alternative, index) => {
+    const resolved = resolveSchema(alternative, rootSchema);
+    return { index, schema: resolved, score: schemaMatchScore(value, resolved) };
+  }).sort((left, right) => right.score - left.score || left.index - right.index)[0];
+  return best.score === Number.NEGATIVE_INFINITY ? schema : best.schema;
+}
+function schemaMatchScore(value, schema) {
+  if (Object.hasOwn(schema, "const") && !deepEqual(value, schema.const)) {
+    return Number.NEGATIVE_INFINITY;
+  }
+  if (schema.enum && !schema.enum.some((candidate) => deepEqual(value, candidate))) {
+    return Number.NEGATIVE_INFINITY;
+  }
+  if (schema.type === "object") {
+    if (!isRecord(value)) return Number.NEGATIVE_INFINITY;
+    const properties = schema.properties ?? {};
+    for (const [key, propertySchema] of Object.entries(properties)) {
+      if (!Object.hasOwn(value, key)) continue;
+      if (Object.hasOwn(propertySchema, "const") && !deepEqual(value[key], propertySchema.const)) {
+        return Number.NEGATIVE_INFINITY;
+      }
+    }
+    return Object.keys(value).filter((key) => Object.hasOwn(properties, key)).length;
+  }
+  if (schema.type === "array") return Array.isArray(value) ? 1 : Number.NEGATIVE_INFINITY;
+  if (schema.type === "string") return typeof value === "string" ? 1 : Number.NEGATIVE_INFINITY;
+  if (schema.type === "number" || schema.type === "integer") {
+    return typeof value === "number" ? 1 : Number.NEGATIVE_INFINITY;
+  }
+  if (schema.type === "boolean") return typeof value === "boolean" ? 1 : Number.NEGATIVE_INFINITY;
+  if (schema.type === "null") return value === null ? 1 : Number.NEGATIVE_INFINITY;
+  return 0;
+}
+function resolveSchema(schema, rootSchema) {
+  if (!schema.$ref) return schema;
+  if (!schema.$ref.startsWith("#/$defs/")) return schema;
+  const name = schema.$ref.slice("#/$defs/".length).replaceAll("~1", "/").replaceAll("~0", "~");
+  return rootSchema.$defs?.[name] ?? schema;
+}
+function isRecord(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function deepEqual(left, right) {
+  if (Object.is(left, right)) return true;
+  if (Array.isArray(left) && Array.isArray(right)) {
+    return left.length === right.length && left.every((value, index) => deepEqual(value, right[index]));
+  }
+  if (isRecord(left) && isRecord(right)) {
+    const leftKeys = Object.keys(left);
+    const rightKeys = Object.keys(right);
+    return leftKeys.length === rightKeys.length && leftKeys.every((key) => Object.hasOwn(right, key) && deepEqual(left[key], right[key]));
+  }
+  return false;
+}
 var namingConfigSchema = zod.z.strictObject({
   clientName: nonEmptyStringSchema.optional(),
   exportedClientName: nonEmptyStringSchema.optional(),
@@ -1431,6 +1556,8 @@ var generationConfigOverrideShape = {
   inferServiceNames: zod.z.boolean().optional(),
   includeDeprecatedOperations: zod.z.boolean().optional(),
   multipleResponses: zod.z.boolean().optional(),
+  /** Generate the entire SDK project, including package manifests and publishable artifacts. */
+  generateFullProject: zod.z.boolean().optional(),
   devContainer: zod.z.boolean().optional(),
   allowMockClient: zod.z.boolean().optional(),
   ignoreFiles: zod.z.array(nonEmptyStringSchema).optional(),
@@ -1459,6 +1586,7 @@ var sdkConfigV1GenerationConfigSchema = zod.z.strictObject({
   inferServiceNames: zod.z.boolean().default(false),
   includeDeprecatedOperations: zod.z.boolean().default(true),
   multipleResponses: zod.z.boolean().default(false),
+  generateFullProject: zod.z.boolean().default(false),
   devContainer: zod.z.boolean().default(false),
   allowMockClient: zod.z.boolean().default(false)
 });
@@ -2008,6 +2136,10 @@ function validateSdkConfigV1(value) {
 function parseSdkConfigV1(value) {
   return sdkConfigV1Schema.parse(value);
 }
+var sdkConfigV1InputJsonSchema = inputJsonSchema(sdkConfigV1Schema);
+function parseSdkConfigV1ForConsumption(value) {
+  return parseSdkConfigV1(stripUnknownProperties(value, sdkConfigV1InputJsonSchema));
+}
 
 // src/sdk-config/v1/fern-config-mapper.ts
 var generatorLanguages = {
@@ -2063,7 +2195,14 @@ function mapFernConfigToSdkConfigV1(input) {
     api.audiences = [...input.group.audiences.audiences];
   }
   const targets = mapped.map(
-    ({ generator, invocation, language, output, package: outputPackage }, index) => {
+    ({
+      generator,
+      invocation,
+      language,
+      output,
+      package: outputPackage,
+      generation: outputGeneration
+    }, index) => {
       const target = {
         language,
         output,
@@ -2077,6 +2216,7 @@ function mapFernConfigToSdkConfigV1(input) {
       }
       const targetGeneration = {
         ...generations.targetOverrides[index],
+        ...outputGeneration,
         ...invocation.targetGeneration
       };
       if (Object.keys(targetGeneration).length > 0) {
@@ -2254,6 +2394,9 @@ function mapInvocation(generator, language, activeLanguages, index) {
   if (generator.keywords?.length) {
     generation.reservedKeywords = [...generator.keywords];
   }
+  if (generator.generateFullProject !== void 0) {
+    generation.generateFullProject = generator.generateFullProject;
+  }
   const settings = isObject(generator.settings) ? generator.settings : void 0;
   if (settings) {
     const inlinePathParameters = takeBoolean(settings, ["inlinePathParameters"], state, [
@@ -2396,6 +2539,8 @@ function mapCommonConfig(language, config, state, client, generation, packageCon
     basePath
   );
   if (webSockets !== void 0) generation.webSockets = webSockets;
+  const generateFullProject = takeBoolean(config, ["generateFullProject"], state, basePath);
+  if (generateFullProject !== void 0) generation.generateFullProject = generateFullProject;
   const inlineTypes = takeBoolean(config, ["enableInlineTypes"], state, basePath);
   const omitUndefined = takeBoolean(config, ["omitUndefined"], state, basePath);
   const forwardEnums = takeBoolean(config, ["enableForwardCompatibleEnums"], state, basePath);
@@ -3000,6 +3145,8 @@ var generationConfigSchema = zod.z.strictObject({
   inferServiceNames: zod.z.boolean().default(false),
   includeDeprecatedOperations: zod.z.boolean().default(true),
   multipleResponses: zod.z.boolean().default(false),
+  /** Generate the entire SDK project, including package manifests and publishable artifacts. */
+  generateFullProject: zod.z.boolean().default(false),
   devContainer: zod.z.boolean().default(false),
   allowMockClient: zod.z.boolean().default(false),
   ignoreFiles: zod.z.array(nonEmptyStringSchema).optional(),
@@ -3399,6 +3546,30 @@ var sdkConfigIrV1Schema = zod.z.strictObject({
 function parseSdkConfigIrV1(value) {
   return sdkConfigIrV1Schema.parse(value);
 }
+var sdkConfigIrCapabilitySchema = zod.z.enum(["generation.generateFullProject"]);
+var sdkConfigIrV1InputJsonSchema = inputJsonSchema(sdkConfigIrV1Schema);
+function serializeSdkConfigIrV1(value) {
+  const parsed = parseSdkConfigIrV1(value);
+  const wireValue = omitSchemaDefaults(parsed, sdkConfigIrV1InputJsonSchema);
+  const requiredCapabilities = [];
+  if (wireValue === void 0) {
+    throw new Error("SDK Config IR v1 root cannot be omitted from its wire payload");
+  }
+  if (parsed.generation.generateFullProject) {
+    requiredCapabilities.push("generation.generateFullProject");
+  }
+  const json = JSON.stringify(wireValue);
+  if (json === void 0) {
+    throw new Error("SDK Config IR v1 could not be serialized as JSON");
+  }
+  return {
+    body: new TextEncoder().encode(json),
+    requiredCapabilities
+  };
+}
+function parseSdkConfigIrV1ForConsumption(value) {
+  return parseSdkConfigIrV1(stripUnknownProperties(value, sdkConfigIrV1InputJsonSchema));
+}
 
 exports.FernConfigMappingError = FernConfigMappingError;
 exports.SDK_CONFIG_IR_V1_SCHEMA_VERSION = SDK_CONFIG_IR_V1_SCHEMA_VERSION;
@@ -3433,7 +3604,9 @@ exports.nonEmptyStringSchema = nonEmptyStringSchema;
 exports.outputConfigSchema = outputConfigSchema;
 exports.packageConfigSchema = packageConfigSchema;
 exports.parseSdkConfigIrV1 = parseSdkConfigIrV1;
+exports.parseSdkConfigIrV1ForConsumption = parseSdkConfigIrV1ForConsumption;
 exports.parseSdkConfigV1 = parseSdkConfigV1;
+exports.parseSdkConfigV1ForConsumption = parseSdkConfigV1ForConsumption;
 exports.phpGenerationConfigSchema = phpGenerationConfigSchema;
 exports.publishConfigSchema = publishConfigSchema;
 exports.publishRegistrySchema = publishRegistrySchema;
@@ -3444,6 +3617,7 @@ exports.relativePathSchema = relativePathSchema;
 exports.replayConfigSchema = replayConfigSchema;
 exports.rubyGenerationConfigSchema = rubyGenerationConfigSchema;
 exports.rustGenerationConfigSchema = rustGenerationConfigSchema;
+exports.sdkConfigIrCapabilitySchema = sdkConfigIrCapabilitySchema;
 exports.sdkConfigIrV1Schema = sdkConfigIrV1Schema;
 exports.sdkConfigV1ApiConfigSchema = sdkConfigV1ApiConfigSchema;
 exports.sdkConfigV1AuthConfigSchema = sdkConfigV1AuthConfigSchema;
@@ -3484,6 +3658,7 @@ exports.sdkConfigV1TargetSchema = sdkConfigV1TargetSchema;
 exports.sdkConfigV1TerraformGenerationConfigSchema = terraformGenerationConfigSchema;
 exports.sdkConfigV1TypescriptGenerationConfigSchema = typescriptGenerationConfigSchema;
 exports.sdkConfigV1WebhookSignatureSchema = sdkConfigV1WebhookSignatureSchema;
+exports.serializeSdkConfigIrV1 = serializeSdkConfigIrV1;
 exports.sourceConfigSchema = sourceConfigSchema;
 exports.sourceSpecConfigSchema = sourceSpecConfigSchema;
 exports.sourceSpecTypeSchema = sourceSpecTypeSchema;