@postman/sdk-config 0.16.0 → 0.18.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (35) hide show
  1. package/dist/index.cjs +139 -23
  2. package/dist/index.cjs.map +1 -1
  3. package/dist/index.d.cts +3 -3
  4. package/dist/index.d.ts +3 -3
  5. package/dist/index.js +133 -24
  6. package/dist/index.js.map +1 -1
  7. package/dist/sdk-config/index.cjs +127 -23
  8. package/dist/sdk-config/index.cjs.map +1 -1
  9. package/dist/sdk-config/index.d.cts +2 -2
  10. package/dist/sdk-config/index.d.ts +2 -2
  11. package/dist/sdk-config/index.js +123 -24
  12. package/dist/sdk-config/index.js.map +1 -1
  13. package/dist/sdk-config/v1/index.cjs +127 -23
  14. package/dist/sdk-config/v1/index.cjs.map +1 -1
  15. package/dist/sdk-config/v1/index.d.cts +922 -504
  16. package/dist/sdk-config/v1/index.d.ts +922 -504
  17. package/dist/sdk-config/v1/index.js +123 -24
  18. package/dist/sdk-config/v1/index.js.map +1 -1
  19. package/dist/sdk-config-ir/index.cjs +18 -1
  20. package/dist/sdk-config-ir/index.cjs.map +1 -1
  21. package/dist/sdk-config-ir/index.d.cts +2 -2
  22. package/dist/sdk-config-ir/index.d.ts +2 -2
  23. package/dist/sdk-config-ir/index.js +17 -2
  24. package/dist/sdk-config-ir/index.js.map +1 -1
  25. package/dist/sdk-config-ir/v1/index.cjs +18 -1
  26. package/dist/sdk-config-ir/v1/index.cjs.map +1 -1
  27. package/dist/sdk-config-ir/v1/index.d.cts +22 -3
  28. package/dist/sdk-config-ir/v1/index.d.ts +22 -3
  29. package/dist/sdk-config-ir/v1/index.js +17 -2
  30. package/dist/sdk-config-ir/v1/index.js.map +1 -1
  31. package/dist/{typescript-Cc50beVo.d.cts → typescript-D0YeGxxS.d.cts} +6 -1
  32. package/dist/{typescript-Cc50beVo.d.ts → typescript-D0YeGxxS.d.ts} +6 -1
  33. package/package.json +1 -1
  34. package/src/sdk-config/v1/README.md +53 -0
  35. package/src/sdk-config-ir/v1/README.md +7 -0
package/dist/index.cjs CHANGED
@@ -13,6 +13,10 @@ var relativePathSchema = nonEmptyStringSchema.refine(
13
13
  (value) => !/^(?:[\\/]|[A-Za-z]:)/.test(value) && !value.split(/[\\/]/).some((segment) => segment === ".."),
14
14
  { message: "must be a relative path without parent directory segments" }
15
15
  );
16
+ var parentRelativePathSchema = nonEmptyStringSchema.refine(
17
+ (value) => !/^(?:[\\/]|[A-Za-z]:)/.test(value),
18
+ { message: "must be a relative path" }
19
+ );
16
20
  var exactSemverSchema = zod.z.string().refine(
17
21
  (value) => {
18
22
  if (value.trim() !== value || !/^\d/.test(value)) {
@@ -1118,6 +1122,27 @@ function mapOutput(generator, language, index) {
1118
1122
  language
1119
1123
  );
1120
1124
  }
1125
+ if (language === "mcp" && rawOutput?.location === "fern-hosted") {
1126
+ const slug = rawOutput.slug;
1127
+ if (typeof slug !== "string" || slug === "") {
1128
+ fail(
1129
+ "FERN_HOSTED_SLUG_REQUIRED",
1130
+ ["group", "generators", index, "output", "slug"],
1131
+ `Fern generator ${generator.name} uses output.location "fern-hosted" without a slug`,
1132
+ 'Set output.slug on the generator, or set target.output manually with delivery "hosted" and a slug.',
1133
+ ["targets", index, "output", "slug"]
1134
+ );
1135
+ }
1136
+ if (isObject(generator.outputMode)) consume(state, [...outputPath, "type"]);
1137
+ return finishOutputMapping(
1138
+ { output: { delivery: "hosted", slug } },
1139
+ generator.outputMode,
1140
+ outputPath,
1141
+ state,
1142
+ index,
1143
+ language
1144
+ );
1145
+ }
1121
1146
  if (!isObject(generator.outputMode) || typeof generator.outputMode.type !== "string") {
1122
1147
  fail(
1123
1148
  "FERN_OUTPUT_REQUIRED",
@@ -2447,6 +2472,17 @@ var sdkConfigV1OutputConfigSchema = zod.z.discriminatedUnion(
2447
2472
  [filesOutputSchema, zipOutputSchema, githubDeliverySchema],
2448
2473
  { error: 'output.delivery must be one of "files", "zip", or "github"' }
2449
2474
  );
2475
+ var hostedOutputSchema = zod.z.strictObject({
2476
+ delivery: zod.z.literal("hosted").describe("Deploys the generated MCP server to Fern-hosted infrastructure."),
2477
+ slug: nonEmptyStringSchema.describe(
2478
+ "The server slug. The hosted URL is https://{organization}.fernmcp.dev/{slug}. May be an environment expression that resolves to the slug."
2479
+ )
2480
+ });
2481
+ var sdkConfigV1McpOutputConfigSchema = zod.z.discriminatedUnion(
2482
+ "delivery",
2483
+ [filesOutputSchema, zipOutputSchema, githubDeliverySchema, hostedOutputSchema],
2484
+ { error: 'output.delivery must be one of "files", "zip", "github", or "hosted"' }
2485
+ );
2450
2486
  var cliDistributionShape = {
2451
2487
  distribution: cliDistributionConfigSchema.optional().describe(
2452
2488
  "CLI release channels and build attestation settings for the generated release workflow; credentials are GitHub Actions secret names."
@@ -2500,7 +2536,8 @@ var apiImportSettingsSchema = zod.z.strictObject({
2500
2536
  ),
2501
2537
  resolveSchemaCollisions: zod.z.boolean().optional().describe("Whether colliding imported schema names are resolved automatically."),
2502
2538
  asyncApiMessageNaming: zod.z.enum(["v1", "v2"]).optional().describe("The naming strategy used for messages imported from AsyncAPI."),
2503
- defaultIntegerFormat: zod.z.enum(["int32", "int64", "uint32", "uint64"]).optional().describe("The integer format used when a schema does not declare one.")
2539
+ defaultIntegerFormat: zod.z.enum(["int32", "int64", "uint32", "uint64"]).optional().describe("The integer format used when a schema does not declare one."),
2540
+ respectByteFormat: zod.z.boolean().optional().describe("Whether string schemas with format byte are imported as base64-encoded bytes.")
2504
2541
  });
2505
2542
  var sourceSpecTypeSchema = zod.z.enum([
2506
2543
  "openapi",
@@ -2511,28 +2548,66 @@ var sourceSpecTypeSchema = zod.z.enum([
2511
2548
  ]);
2512
2549
 
2513
2550
  // src/sdk-config/v1/source.ts
2514
- var sourceSpecShape = {
2551
+ var commonSourceSpecShape = {
2515
2552
  id: nonEmptyStringSchema.describe("A unique identifier for this API source."),
2516
- type: sourceSpecTypeSchema.describe("The API description format of this source."),
2517
2553
  name: nonEmptyStringSchema.optional().describe("A human-readable name for this API source."),
2518
2554
  namespace: nonEmptyStringSchema.optional().describe("A namespace used to isolate this source in a multi-source SDK."),
2519
- apiImportSettings: apiImportSettingsSchema.optional().describe("Import behavior that overrides the source-level defaults for this spec."),
2555
+ apiImportSettings: apiImportSettingsSchema.optional().describe("Import behavior that overrides the source-level defaults for this spec.")
2556
+ };
2557
+ var sourceSpecShape = {
2558
+ ...commonSourceSpecShape,
2559
+ type: sourceSpecTypeSchema.describe("The API description format of this source."),
2520
2560
  overlays: zod.z.array(relativePathSchema).optional().describe("Relative paths to overlays applied to this source in order."),
2521
2561
  overrides: zod.z.array(relativePathSchema).optional().describe("Relative paths to source override files applied in order.")
2522
2562
  };
2523
- var sdkConfigV1SourceSpecSchema = zod.z.union(
2524
- [
2525
- zod.z.strictObject({
2526
- ...sourceSpecShape,
2527
- path: relativePathSchema.describe("The relative path to the API source file.")
2528
- }),
2529
- zod.z.strictObject({
2530
- ...sourceSpecShape,
2531
- url: zod.z.url({ protocol: /^https?$/ }).describe("The HTTP or HTTPS URL of the API source file.")
2532
- })
2533
- ],
2534
- { error: "source spec must contain exactly one locator: path or HTTP(S) url" }
2535
- );
2563
+ var sdkConfigV1GitRemoteSchema = zod.z.strictObject({
2564
+ repo: nonEmptyStringSchema.describe("The git repository URL."),
2565
+ ref: nonEmptyStringSchema.optional().describe("The branch, tag, or commit SHA. Defaults to the repository's default branch."),
2566
+ path: relativePathSchema.describe("The path to the directory within the repository.")
2567
+ });
2568
+ var sdkConfigV1ProtobufRootSchema = zod.z.union([
2569
+ parentRelativePathSchema.describe("The relative path to the .proto directory root."),
2570
+ zod.z.strictObject({
2571
+ git: sdkConfigV1GitRemoteSchema.describe("The git remote holding the .proto files.")
2572
+ }).describe("A .proto directory root in a remote git repository.")
2573
+ ]);
2574
+ var sdkConfigV1ProtobufSourceSchema = zod.z.strictObject({
2575
+ root: sdkConfigV1ProtobufRootSchema.describe(
2576
+ "The .proto directory root, as a relative path or a git remote."
2577
+ ),
2578
+ target: parentRelativePathSchema.optional().describe("The relative path to the single .proto file that defines the API."),
2579
+ overrides: zod.z.array(parentRelativePathSchema).optional().describe("Relative paths to override files applied to the converted API in order."),
2580
+ dependencies: zod.z.array(nonEmptyStringSchema).optional().describe("Buf Schema Registry modules the .proto files depend on."),
2581
+ localGeneration: zod.z.boolean().optional().describe("Whether the .proto files are compiled locally instead of remotely."),
2582
+ fromOpenApi: zod.z.boolean().default(false).describe("Whether SDKs are generated from the OpenAPI converted from the .proto files.")
2583
+ });
2584
+ var sourceSpecOptions = [
2585
+ zod.z.strictObject({
2586
+ ...sourceSpecShape,
2587
+ path: relativePathSchema.describe("The relative path to the API source file.")
2588
+ }),
2589
+ zod.z.strictObject({
2590
+ ...sourceSpecShape,
2591
+ url: zod.z.url({ protocol: /^https?$/ }).describe("The HTTP or HTTPS URL of the API source file.")
2592
+ }),
2593
+ zod.z.strictObject({
2594
+ ...commonSourceSpecShape,
2595
+ proto: sdkConfigV1ProtobufSourceSchema.describe("The protobuf definitions of this source.")
2596
+ })
2597
+ ];
2598
+ var protobufSourceSpecOptionIndex = 2;
2599
+ function hasProtoLocator(input) {
2600
+ return typeof input === "object" && input !== null && "proto" in input;
2601
+ }
2602
+ var sdkConfigV1SourceSpecSchema = zod.z.union(sourceSpecOptions, {
2603
+ error: (issue) => {
2604
+ if (issue.code !== "invalid_union" || !hasProtoLocator(issue.input)) {
2605
+ return "source spec must contain exactly one locator: path, HTTP(S) url, or proto";
2606
+ }
2607
+ const details = (issue.errors[protobufSourceSpecOptionIndex] ?? []).map(({ path, message }) => path.length ? `${path.join(".")}: ${message}` : message).join("; ");
2608
+ return `protobuf source spec is invalid: ${details}`;
2609
+ }
2610
+ });
2536
2611
  var sdkConfigV1SourceConfigSchema = zod.z.strictObject({
2537
2612
  specs: zod.z.array(sdkConfigV1SourceSpecSchema).min(1, "source.specs must contain at least one source spec").describe("API source files in authoritative processing order."),
2538
2613
  apiImportSettings: apiImportSettingsSchema.optional().describe("Default import behavior shared by every source spec.")
@@ -2845,7 +2920,10 @@ var sdkConfigV1TargetSchema = zod.z.discriminatedUnion("language", [
2845
2920
  zod.z.strictObject({
2846
2921
  language: zod.z.literal("mcp").describe("Generates an MCP server."),
2847
2922
  generation: sdkConfigV1GenerationConfigOverrideSchema.extend(mcpGenerationConfigSchema.shape).optional().describe("Common and MCP-specific generation settings for this target."),
2848
- ...targetOverrideShape
2923
+ ...targetOverrideShape,
2924
+ output: sdkConfigV1McpOutputConfigSchema.optional().describe(
2925
+ "Output configuration, including Fern-hosted deployment, that replaces the root output for this target."
2926
+ )
2849
2927
  }),
2850
2928
  zod.z.strictObject({
2851
2929
  language: zod.z.literal("terraform").describe("Generates a Terraform provider."),
@@ -2922,7 +3000,7 @@ function validateTargetPublishing(target, targetIndex, globalPackage, globalOutp
2922
3000
  });
2923
3001
  return;
2924
3002
  }
2925
- if (!output.publish) {
3003
+ if (output.delivery === "hosted" || !output.publish) {
2926
3004
  return;
2927
3005
  }
2928
3006
  const registry = output.publish.registry;
@@ -3040,6 +3118,22 @@ function mapFernConfigToSdkConfigV1(input) {
3040
3118
  const docs = partitionSharedBlock(mapped.map(({ docs: docs2 }) => docs2));
3041
3119
  const generations = partitionSharedBlock(mapped.map(({ invocation }) => invocation.generation));
3042
3120
  const api = { ...input.api ?? {} };
3121
+ const mcpBaseUrlIndex = mapped.findIndex(({ invocation }) => invocation.apiBaseUrl !== void 0);
3122
+ const mcpBaseUrl = mapped[mcpBaseUrlIndex]?.invocation.apiBaseUrl;
3123
+ const apiDiagnostics = [];
3124
+ if (mcpBaseUrl !== void 0) {
3125
+ if (api.baseUrl !== void 0 && api.baseUrl !== "" && api.baseUrl !== mcpBaseUrl) {
3126
+ apiDiagnostics.push({
3127
+ code: "FERN_MCP_BASE_URL_REPLACES_API_BASE_URL",
3128
+ severity: "warning",
3129
+ path: ["group", "generators", mcpBaseUrlIndex, "config", "baseUrl"],
3130
+ reason: `The MCP generator baseUrl "${mcpBaseUrl}" replaced the API base URL "${api.baseUrl}"`,
3131
+ sdkConfigPath: ["api", "baseUrl"],
3132
+ suggestedAction: "Check api.baseUrl in the migrated SDK Config. Remove the MCP baseUrl to keep the API base URL."
3133
+ });
3134
+ }
3135
+ api.baseUrl = mcpBaseUrl;
3136
+ }
3043
3137
  delete api.audiences;
3044
3138
  if (input.group.audiences.type === "select") {
3045
3139
  api.audiences = [...input.group.audiences.audiences];
@@ -3140,10 +3234,13 @@ function mapFernConfigToSdkConfigV1(input) {
3140
3234
  const validatedSdkConfig = sdkConfig;
3141
3235
  return {
3142
3236
  sdkConfig: validatedSdkConfig,
3143
- unsupportedFields: mapped.flatMap(({ invocation, unsupportedFields }) => [
3144
- ...invocation.unsupportedFields,
3145
- ...unsupportedFields
3146
- ])
3237
+ unsupportedFields: [
3238
+ ...apiDiagnostics,
3239
+ ...mapped.flatMap(({ invocation, unsupportedFields }) => [
3240
+ ...invocation.unsupportedFields,
3241
+ ...unsupportedFields
3242
+ ])
3243
+ ]
3147
3244
  };
3148
3245
  }
3149
3246
  function withRustCratesPublishDefaults(packageConfig, { language, output, generator }) {
@@ -3276,6 +3373,7 @@ function mapInvocation(generator, language, activeLanguages, index) {
3276
3373
  ...optional("smartCasingDigitWordBoundary", smartCasingDigitWordBoundary)
3277
3374
  };
3278
3375
  }
3376
+ const apiBaseUrl = language === "mcp" && activeLanguages.size === 1 ? takeString(config, ["baseUrl"], state, [...prefix, "config"]) : void 0;
3279
3377
  const targetGeneration = mapLanguageConfig(
3280
3378
  language,
3281
3379
  config,
@@ -3320,6 +3418,7 @@ function mapInvocation(generator, language, activeLanguages, index) {
3320
3418
  package: packageConfig,
3321
3419
  packageFallbacks: state.packageFallbacks ?? [],
3322
3420
  ...optional("cliDistribution", state.cliDistribution),
3421
+ ...optional("apiBaseUrl", apiBaseUrl),
3323
3422
  targetGeneration,
3324
3423
  unsupportedFields
3325
3424
  };
@@ -4624,6 +4723,7 @@ var outputConfigSchema = zod.z.discriminatedUnion(
4624
4723
  var replayConfigSchema = zod.z.strictObject({
4625
4724
  enabled: zod.z.boolean().describe("Whether regeneration reapplies customer-authored repository changes.")
4626
4725
  });
4726
+ var sourceSpecOriginSchema = zod.z.enum(["protobuf"]);
4627
4727
  var sourceSpecConfigSchema = zod.z.strictObject({
4628
4728
  id: nonEmptyStringSchema.optional().describe("A unique identifier for this API source."),
4629
4729
  name: nonEmptyStringSchema.optional().describe("A human-readable name for this API source."),
@@ -4632,9 +4732,18 @@ var sourceSpecConfigSchema = zod.z.strictObject({
4632
4732
  "The materialized URL from which the generator retrieves the API source."
4633
4733
  ),
4634
4734
  specType: sourceSpecTypeSchema.describe("The API description format of this source."),
4735
+ origin: sourceSpecOriginSchema.optional().describe("The format this source was authored in before it was converted to specType."),
4635
4736
  apiImportSettings: apiImportSettingsSchema.optional().describe("Import behavior that overrides the source-level defaults for this spec."),
4636
4737
  overlays: zod.z.array(nonEmptyStringSchema).optional().describe("Materialized overlays applied to this source in order."),
4637
4738
  overrides: zod.z.array(nonEmptyStringSchema).optional().describe("Materialized source overrides applied in order.")
4739
+ }).superRefine(({ specType, origin }, context) => {
4740
+ if (origin === "protobuf" && specType !== "openapi") {
4741
+ context.addIssue({
4742
+ code: "custom",
4743
+ message: 'origin "protobuf" is only allowed on openapi specs',
4744
+ path: ["origin"]
4745
+ });
4746
+ }
4638
4747
  });
4639
4748
  var sourceConfigSchema = zod.z.strictObject({
4640
4749
  specs: zod.z.array(sourceSpecConfigSchema).min(1, "source.specs must contain at least one source spec").describe("Materialized API sources in authoritative processing order."),
@@ -4915,6 +5024,7 @@ exports.mcpGenerationConfigSchema = mcpGenerationConfigSchema;
4915
5024
  exports.nonEmptyStringSchema = nonEmptyStringSchema;
4916
5025
  exports.outputConfigSchema = outputConfigSchema;
4917
5026
  exports.packageConfigSchema = packageConfigSchema;
5027
+ exports.parentRelativePathSchema = parentRelativePathSchema;
4918
5028
  exports.parseSdkConfigIrV1 = parseSdkConfigIrV1;
4919
5029
  exports.parseSdkConfigIrV1ForConsumption = parseSdkConfigIrV1ForConsumption;
4920
5030
  exports.parseSdkConfigV1 = parseSdkConfigV1;
@@ -4949,16 +5059,21 @@ exports.sdkConfigV1DocsConfigSchema = sdkConfigV1DocsConfigSchema;
4949
5059
  exports.sdkConfigV1ExactSemverSchema = exactSemverSchema;
4950
5060
  exports.sdkConfigV1GenerationConfigOverrideSchema = sdkConfigV1GenerationConfigOverrideSchema;
4951
5061
  exports.sdkConfigV1GenerationConfigSchema = sdkConfigV1GenerationConfigSchema;
5062
+ exports.sdkConfigV1GitRemoteSchema = sdkConfigV1GitRemoteSchema;
4952
5063
  exports.sdkConfigV1GithubActionsSecretNameSchema = githubActionsSecretNameSchema;
4953
5064
  exports.sdkConfigV1GoGenerationConfigSchema = goGenerationConfigSchema;
4954
5065
  exports.sdkConfigV1GoModulePathSchema = goModulePathSchema;
4955
5066
  exports.sdkConfigV1JavaGenerationConfigSchema = javaGenerationConfigSchema;
4956
5067
  exports.sdkConfigV1KotlinGenerationConfigSchema = kotlinGenerationConfigSchema;
4957
5068
  exports.sdkConfigV1McpGenerationConfigSchema = mcpGenerationConfigSchema;
5069
+ exports.sdkConfigV1McpOutputConfigSchema = sdkConfigV1McpOutputConfigSchema;
4958
5070
  exports.sdkConfigV1NonEmptyStringSchema = nonEmptyStringSchema;
4959
5071
  exports.sdkConfigV1OutputConfigSchema = sdkConfigV1OutputConfigSchema;
4960
5072
  exports.sdkConfigV1PackageConfigSchema = sdkConfigV1PackageConfigSchema;
5073
+ exports.sdkConfigV1ParentRelativePathSchema = parentRelativePathSchema;
4961
5074
  exports.sdkConfigV1PhpGenerationConfigSchema = phpGenerationConfigSchema;
5075
+ exports.sdkConfigV1ProtobufRootSchema = sdkConfigV1ProtobufRootSchema;
5076
+ exports.sdkConfigV1ProtobufSourceSchema = sdkConfigV1ProtobufSourceSchema;
4962
5077
  exports.sdkConfigV1PublishConfigSchema = sdkConfigV1PublishConfigSchema;
4963
5078
  exports.sdkConfigV1PublishRegistrySchema = sdkConfigV1PublishRegistrySchema;
4964
5079
  exports.sdkConfigV1PythonGenerationConfigSchema = pythonGenerationConfigSchema;
@@ -4979,6 +5094,7 @@ exports.sdkConfigV1WebhookSignatureSchema = sdkConfigV1WebhookSignatureSchema;
4979
5094
  exports.serializeSdkConfigIrV1 = serializeSdkConfigIrV1;
4980
5095
  exports.sourceConfigSchema = sourceConfigSchema;
4981
5096
  exports.sourceSpecConfigSchema = sourceSpecConfigSchema;
5097
+ exports.sourceSpecOriginSchema = sourceSpecOriginSchema;
4982
5098
  exports.sourceSpecTypeSchema = sourceSpecTypeSchema;
4983
5099
  exports.splitSdkConfigV1TargetGeneration = splitSdkConfigV1TargetGeneration;
4984
5100
  exports.swiftGenerationConfigSchema = swiftGenerationConfigSchema;