@postman/sdk-config 0.10.1 → 0.12.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.
- package/README.md +6 -0
- package/dist/index.cjs +909 -41
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +3 -3
- package/dist/index.d.ts +3 -3
- package/dist/index.js +895 -42
- package/dist/index.js.map +1 -1
- package/dist/sdk-config/index.cjs +861 -41
- package/dist/sdk-config/index.cjs.map +1 -1
- package/dist/sdk-config/index.d.cts +2 -2
- package/dist/sdk-config/index.d.ts +2 -2
- package/dist/sdk-config/index.js +854 -42
- package/dist/sdk-config/index.js.map +1 -1
- package/dist/sdk-config/v1/index.cjs +861 -41
- package/dist/sdk-config/v1/index.cjs.map +1 -1
- package/dist/sdk-config/v1/index.d.cts +3345 -2632
- package/dist/sdk-config/v1/index.d.ts +3345 -2632
- package/dist/sdk-config/v1/index.js +854 -42
- package/dist/sdk-config/v1/index.js.map +1 -1
- package/dist/sdk-config-ir/index.cjs +286 -5
- package/dist/sdk-config-ir/index.cjs.map +1 -1
- package/dist/sdk-config-ir/index.d.cts +2 -2
- package/dist/sdk-config-ir/index.d.ts +2 -2
- package/dist/sdk-config-ir/index.js +280 -6
- package/dist/sdk-config-ir/index.js.map +1 -1
- package/dist/sdk-config-ir/v1/index.cjs +286 -5
- package/dist/sdk-config-ir/v1/index.cjs.map +1 -1
- package/dist/sdk-config-ir/v1/index.d.cts +3291 -2958
- package/dist/sdk-config-ir/v1/index.d.ts +3291 -2958
- package/dist/sdk-config-ir/v1/index.js +280 -6
- package/dist/sdk-config-ir/v1/index.js.map +1 -1
- package/dist/{typescript-Chge0X4f.d.cts → typescript-Byhn4MqL.d.cts} +145 -1
- package/dist/{typescript-Chge0X4f.d.ts → typescript-Byhn4MqL.d.ts} +145 -1
- package/package.json +1 -1
- package/src/sdk-config/v1/README.md +183 -1
- package/src/sdk-config-ir/v1/README.md +107 -31
|
@@ -47,6 +47,14 @@ messages. Valid IR requests route only to the IR bridge and never fall through t
|
|
|
47
47
|
- Credentials may be references to externally managed secrets or raw credential/signing values when
|
|
48
48
|
an integration must carry the material through the normalized config. Raw values are sensitive and
|
|
49
49
|
must be handled as secrets.
|
|
50
|
+
- `output.distribution` (CLI Homebrew/Scoop channels) is valid only when `target.language` is `cli`
|
|
51
|
+
and `output.delivery` is `github`. It is accepted on every delivery variant so files/zip produce an
|
|
52
|
+
actionable error. Its `*SecretName` fields hold GitHub Actions secret names that the generated
|
|
53
|
+
release workflow resolves; they are never credentials, references, or values to resolve, and
|
|
54
|
+
`credentialResolution` does not apply to them. `getSdkConfigIrV1Diagnostics` warns when
|
|
55
|
+
distribution is combined with a non-release GitHub mode. See the
|
|
56
|
+
[SDK Config v1 reference](../../sdk-config/v1/README.md#cli-distribution-and-npm-publication).
|
|
57
|
+
- npm publication is valid for `cli` targets with GitHub delivery only.
|
|
50
58
|
|
|
51
59
|
## Configuration design rules
|
|
52
60
|
|
|
@@ -92,6 +100,7 @@ Legacy aliases below intentionally converge on one normalized behavior.
|
|
|
92
100
|
| Package namespace | npm organization and generator conventions | namespace, package-prefix, and root-namespace aliases | `package.namespace` |
|
|
93
101
|
| Package identity | per-language package IDs | registry output and package-name aliases | `package.packageName`, `moduleName`, `modulePath`, `groupId`, or `artifactId` |
|
|
94
102
|
| Extra dependencies | language `hookDependencies` and package metadata | dependency and dev-dependency aliases | `package.extraDependencies`, `extraDevDependencies`, or `extraPeerDependencies` |
|
|
103
|
+
| Peer dependency metadata | npm `peerDependenciesMeta` | `extraPeerDependenciesMeta` | `package.extraPeerDependenciesMeta` |
|
|
95
104
|
| Constructor parameters | language `additionalConstructorParameters` / `additionalVariables` | generator-specific constructor options | `client.additionalConstructorParameters` |
|
|
96
105
|
| Repository delivery | `deliveryMethods`, `githubRepoName`, `githubRef`, `privateRepo` | GitHub output owner/repository settings | `output.delivery` and `output.github` |
|
|
97
106
|
| Registry publication | per-language package identity plus publishing settings | registry output settings | `package` identity plus `output.publish` mechanics |
|
|
@@ -230,6 +239,7 @@ audited on 2026-07-17. Counts guide the initial contract; they are not a permane
|
|
|
230
239
|
| `user-agent`, `includePlatformHeaders`, `allowUserAgentAppInfo` | `client.userAgent` | Not in the project snapshot; see below |
|
|
231
240
|
| `offsetSemantics` | `client.offsetSemantics` | Not in the project snapshot; see below |
|
|
232
241
|
| `enable-wire-tests`, `enableWireTests`, `generateWireTests` | `generation.wireTests` | 1-15 per language |
|
|
242
|
+
| TypeScript `wireTestsFallbackToAutoGeneratedErrorExamples` | `generation.wireTests.fallbackToGeneratedErrorExamples` | Not in the project snapshot; see below |
|
|
233
243
|
| WebSocket generation aliases | `generation.webSockets` | 3 TS, 3 Python |
|
|
234
244
|
| `streamType`, `fileResponseType` | `generation.streams` | 1 TS |
|
|
235
245
|
| client/exported/environment class aliases | `generation.naming` | 1-28 per language |
|
|
@@ -237,7 +247,7 @@ audited on 2026-07-17. Counts guide the initial contract; they are not a permane
|
|
|
237
247
|
| namespace/package-prefix aliases | `package.namespace` | 1-30 per language |
|
|
238
248
|
| output registry package names | `package.packageName` | 5-28 per registry language |
|
|
239
249
|
| TypeScript `packageJson` / PHP `composerJson` portable metadata | `package.packageName`, `description`, `authors`, and `license` | Portable subset only. |
|
|
240
|
-
| TypeScript `fetchSupport
|
|
250
|
+
| TypeScript `fetchSupport` | `generation.language.typescript.httpClient.name`: `native` is `"fetch"`, `node-fetch` is `"node-fetch"` | Native only. |
|
|
241
251
|
| Python custom `package_name` | `package.moduleName` | 18 |
|
|
242
252
|
| Python `additional_init_exports` | `generation.language.python.additionalInitExports` | 3 |
|
|
243
253
|
| Go `module.path` | `package.modulePath` | 3 |
|
|
@@ -254,6 +264,49 @@ audited on 2026-07-17. Counts guide the initial contract; they are not a permane
|
|
|
254
264
|
| Fern README config | `docs.readme` | 12 API names; 11 disabled-section configs |
|
|
255
265
|
| `customReadmeSections` | `docs.readme.customSections` | Not in the project snapshot; see below |
|
|
256
266
|
| `includeApiReference` | `docs.includeApiReference` | 10 TS |
|
|
267
|
+
| TypeScript `formDataSupport` | `generation.language.typescript.formDataSupport` | Not in the project snapshot; see below |
|
|
268
|
+
| TypeScript `allowExtraFields` | `generation.language.typescript.allowExtraFields` | Not in the project snapshot; see below |
|
|
269
|
+
| TypeScript `generateSubpackageExports` | `generation.language.typescript.generateSubpackageExports` | Not in the project snapshot; see below |
|
|
270
|
+
|
|
271
|
+
The TypeScript options below are copied by the mapper only when they have the declared type, and
|
|
272
|
+
anything else is reported in `compatibility.unsupportedFields`. Omitted options stay omitted; the
|
|
273
|
+
generator applies Fern's defaults. Each maps to the field of the same name in
|
|
274
|
+
`generation.language.typescript` unless noted. The mapper reads them for the TypeScript SDK generator
|
|
275
|
+
only. The MCP generator's converter has never read them, so an MCP config that sets one still
|
|
276
|
+
reports it in `compatibility.unsupportedFields` (`fetchSupport: node-fetch` included; `native` still
|
|
277
|
+
maps).
|
|
278
|
+
|
|
279
|
+
| Fern option | Values | Fern default | Maps to |
|
|
280
|
+
| -------------------------------------------------------------------------------------- | ------------------------------------- | ----------------------------------------------------------------- | ------------------------------------------------------- |
|
|
281
|
+
| `formDataSupport` | `Node16`, `Node18` | `Node18` | |
|
|
282
|
+
| `allowExtraFields` | boolean | `false` | |
|
|
283
|
+
| `generateSubpackageExports` | boolean | `true` | |
|
|
284
|
+
| `exportAllRequestsAtRoot`, `generateEndpointMetadata`, `outputEsm`, `neverThrowErrors` | boolean | `false` | |
|
|
285
|
+
| `includeOtherInUnionTypes`, `includeUtilsOnUnionMembers`, `omitFernHeaders` | boolean | `false` | |
|
|
286
|
+
| `linter` | `biome`, `oxlint`, `none` | `biome` | |
|
|
287
|
+
| `formatter` | `prettier`, `biome`, `oxfmt`, `none` | `biome` | |
|
|
288
|
+
| `fetchSupport` | `native`, `node-fetch` | `native` | `httpClient.name` (`fetch`, `node-fetch`) |
|
|
289
|
+
| `wireTestsFallbackToAutoGeneratedErrorExamples` | boolean | `true` | `generation.wireTests.fallbackToGeneratedErrorExamples` |
|
|
290
|
+
| `packageJson.exports` | object keyed by subpath | generated map | `exports` |
|
|
291
|
+
| `packageJson.scripts` | object of name to command | generated scripts | `scripts` (`{ name, command }` list) |
|
|
292
|
+
| `packageJson.files` | string list | generated list | `files` |
|
|
293
|
+
| `packageJson.engines` | object of name to range | generated (`node >=18.0.0`) | `engines` |
|
|
294
|
+
| `packageJson["lint-staged"]` | object of glob to commands | none | `lintStaged` |
|
|
295
|
+
| `packageJson.browser` | object of module to `false` or path | generated (`fs`, `os`, `path`, `stream`, `crypto` set to `false`) | `browser` |
|
|
296
|
+
| `packageJson.bugs` | URL string, or `{ url, email }` | none | `package.bugs` |
|
|
297
|
+
| `packageJson.repository` | URL string, or `{ type: "git", url }` | none | `package.repository` |
|
|
298
|
+
|
|
299
|
+
`generation.wireTests` requires `enabled`, and Fern generates wire tests unless told not to, so a
|
|
300
|
+
config that sets only the fallback option maps to `{ enabled: true, fallbackToGeneratedErrorExamples }`.
|
|
301
|
+
The `packageJson` keys above are the ones that have a typed home. For `engines` and `browser`, Fern merges the
|
|
302
|
+
customer's entries into the generated object key by key, so a customer `node` range replaces the generated one and a
|
|
303
|
+
customer `browser` entry is added to the generated ones. Fern merges the values you set over
|
|
304
|
+
the generated `package.json`; `files` entries come first, and `exports` subpaths replace the
|
|
305
|
+
generated ones one subpath at a time (Fern's default `shallow` merge; `packageJsonMergeStrategy` is
|
|
306
|
+
not carried). A key outside this list, a repository `directory`, or a repository `type` other than
|
|
307
|
+
`git` is still reported as unsupported.
|
|
308
|
+
`outputEsm` marks the package as an ES module while still shipping its CommonJS build; `esmOnly`
|
|
309
|
+
drops the CommonJS build.
|
|
257
310
|
|
|
258
311
|
The Rust language config was added after the initial audit. That audit compared existing Fern
|
|
259
312
|
_customer projects_, which surfaced no Rust-specific options; comparing the Fern Rust generator's
|
|
@@ -350,19 +403,38 @@ project's OpenAPI specs carry it too and are refused for it.
|
|
|
350
403
|
|
|
351
404
|
Only options that remain language-specific stay in `generation.language`.
|
|
352
405
|
|
|
353
|
-
| Language | Fern fields retained in language config
|
|
354
|
-
| ----------- |
|
|
355
|
-
| TypeScript | `packageManager` (1), `testFramework` (2), `namespaceExportName`, `allowCustomFetcher` (13), branded aliases (1), legacy exports (1), `useBigInt`, and positive `serdeLayer` from `noSerdeLayer` (8) | Namespace, validation, inline types, dependencies, wire tests, streams, WebSockets, pager/client names |
|
|
356
|
-
| Python | Python/Pydantic versions, client filenames, model switches, TypedDict requests, redirect/chunk/recursion compatibility, and package extras
|
|
357
|
-
| Java/Kotlin | Package layout (3), local dates (2), optional-nullable collapse (2), Gradle settings (7), and JVM async-client style
|
|
358
|
-
| Go | Legacy complex models, union version (3), legacy client options (1), and the fern root-client constructor name
|
|
359
|
-
| C# | Optional wrapper, simplified dictionaries (1), explicit namespaces (7), core namespace behavior (1), exception handler (5), and the experimental explicit-nullable-optional switch
|
|
360
|
-
| PHP | Property access (2) and generated client interfaces (1)
|
|
361
|
-
| Ruby | Require paths (2)
|
|
362
|
-
| Rust | Datetime representation, initialism casing, and Cargo features/default-features
|
|
363
|
-
| Swift | Module name and the nullable-as-optional collapse
|
|
364
|
-
| CLI | Pagination parameter names
|
|
365
|
-
| MCP | Server identity, availability exclusions, tool filters and named toolsets, plus the TypeScript options
|
|
406
|
+
| Language | Fern fields retained in language config | Shared mappings lifted out |
|
|
407
|
+
| ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
|
|
408
|
+
| TypeScript | `packageManager` (1), `testFramework` (2), `namespaceExportName`, `allowCustomFetcher` (13), branded aliases (1), legacy exports (1), `formDataSupport`, `allowExtraFields`, `generateSubpackageExports`, `exportAllRequestsAtRoot`, `generateEndpointMetadata`, `outputEsm`, `neverThrowErrors`, `includeOtherInUnionTypes`, `includeUtilsOnUnionMembers`, `omitFernHeaders`, `linter`, `formatter`, `useBigInt`, and positive `serdeLayer` from `noSerdeLayer` (8) | Namespace, validation, inline types, dependencies, wire tests, streams, WebSockets, pager/client names |
|
|
409
|
+
| Python | Python/Pydantic versions, client filenames, model switches, TypedDict requests, redirect/chunk/recursion compatibility, and package extras | Package/module names, enum form, extra fields, response validation, request style, dependencies, timeout, layout, wire tests, WebSockets |
|
|
410
|
+
| Java/Kotlin | Package layout (3), local dates (2), optional-nullable collapse (2), Gradle settings (7), and JVM async-client style | Maven identity, namespace, names, forward-compatible enums, inline properties, dependencies, pager, wire tests |
|
|
411
|
+
| Go | Legacy complex models, union version (3), legacy client options (1), and the fern root-client constructor name | Module/package identity, client name, environments, smart casing, inline properties, pager, wire tests |
|
|
412
|
+
| C# | Optional wrapper, simplified dictionaries (1), explicit namespaces (7), core namespace behavior (1), exception handler (5), and the experimental explicit-nullable-optional switch | NuGet identity, namespace, class/error names, pager, wire tests |
|
|
413
|
+
| PHP | Property access (2) and generated client interfaces (1) | Composer identity, namespace, client/pager names, request style, dependencies, wire tests, idempotency keys, User-Agent, offset semantics |
|
|
414
|
+
| Ruby | Require paths (2) | Gem identity, client name, dependencies, pager, wire tests |
|
|
415
|
+
| Rust | Datetime representation, initialism casing, and Cargo features/default-features | Crate identity, client name, and package metadata use shared fields. |
|
|
416
|
+
| Swift | Module name and the nullable-as-optional collapse | Client, environment and error naming use shared fields. |
|
|
417
|
+
| CLI | Pagination parameter names, the `skills` boolean, and the typed CLI settings below | Go module and package identity use `package`. |
|
|
418
|
+
| MCP | Server identity, availability exclusions, tool filters and named toolsets, plus the TypeScript options | npm package identity, client and serialization behavior |
|
|
419
|
+
|
|
420
|
+
`generation.language.cli` also accepts the typed CLI settings `binaryName`, `customCommands`,
|
|
421
|
+
`rootGroup`, `profiles`, `splitTypeCrates`, and `userAgentSuffixFlag`. Their shapes, validation,
|
|
422
|
+
and generator defaults are listed in the
|
|
423
|
+
[SDK Config v1 reference](../../sdk-config/v1/README.md#cli-generation-settings). IR leaves omitted
|
|
424
|
+
settings undefined so the CLI generator applies its own defaults.
|
|
425
|
+
|
|
426
|
+
The Fern mapper copies these six keys from a CLI generator's `config` into the target's
|
|
427
|
+
`generation` unchanged. It matches only the exact key names the CLI generator reads, so spellings
|
|
428
|
+
such as `binary-name` are still reported as unsupported. Two rules need care:
|
|
429
|
+
|
|
430
|
+
- A legacy `profiles` block without `enabled` migrates as `enabled: false`. The generator turns
|
|
431
|
+
profiles on only when `profiles.enabled === true`, so this keeps the same behavior. Profile keys
|
|
432
|
+
the generator does not read are reported as unsupported, and the known keys are still copied.
|
|
433
|
+
- A value SDK Config rejects is left out of the output and reported as
|
|
434
|
+
`FERN_CONFIG_VALUE_INVALID`. The diagnostic points at the exact legacy path and the matching
|
|
435
|
+
`targets[].generation` path. The mapper does not rewrite the value, for example by
|
|
436
|
+
kebab-casing it or dropping an invalid `profiles` entry. A rejected `profiles` block is left out
|
|
437
|
+
as a whole.
|
|
366
438
|
|
|
367
439
|
## Removed and deferred legacy configuration
|
|
368
440
|
|
|
@@ -372,18 +444,22 @@ the migration.
|
|
|
372
444
|
|
|
373
445
|
### Removed after finding no customer use and no sdk-gen-core equivalent
|
|
374
446
|
|
|
375
|
-
- Common Fern generation: the omit platform-header override (`omitFernHeaders`)
|
|
376
|
-
defaults own
|
|
377
|
-
|
|
447
|
+
- Common Fern generation: the omit platform-header override (`omitFernHeaders`) was removed from the
|
|
448
|
+
shared blocks, and Output-profile defaults own that compatibility behavior. The include side was
|
|
449
|
+
re-added as `client.userAgent.includePlatformInfo` once the Fern PHP generator documented it. The
|
|
450
|
+
TypeScript `omitFernHeaders` option is carried as its own TypeScript setting because real
|
|
451
|
+
TypeScript configs set it.
|
|
378
452
|
- Source import: optional-additional-properties defaults, environment grouping strategies,
|
|
379
453
|
discriminant removal, forward-compatible inference, default environment inference, const
|
|
380
454
|
coercion, endpoint filters, example-depth controls, alias resolution, single-schema oneOf
|
|
381
455
|
preservation, read-variant responses, binary-response import coercion, form encoding defaults,
|
|
382
456
|
additional-properties defaults, and discriminated-union inference.
|
|
383
|
-
- TypeScript:
|
|
384
|
-
type files
|
|
385
|
-
|
|
386
|
-
|
|
457
|
+
- TypeScript: the options once removed here were re-added as real configs turned up. Consolidated
|
|
458
|
+
type files is `consolidateTypeFiles` (`intercom` and `auth0_fern` set it), subpackage exports is
|
|
459
|
+
`generateSubpackageExports` (`auth0_fern`, `auth0_teams`, `corti_latest`, and `merge` set it),
|
|
460
|
+
and linter/formatter selection and endpoint metadata are `linter`, `formatter`, and
|
|
461
|
+
`generateEndpointMetadata` (`auth0_fern` and `auth0_teams` set them). None of these entries
|
|
462
|
+
applies to those options any more.
|
|
387
463
|
- Python: ORM/smart-union/coercion/wrapped-alias/positional-constructor/inheritance/validator
|
|
388
464
|
switches, flattened union bodies, lazy imports, and custom transport.
|
|
389
465
|
- Java/JVM: JSON include, required-builder checks, public/extensible constructors, unknown-as-node,
|
|
@@ -397,16 +473,16 @@ the migration.
|
|
|
397
473
|
|
|
398
474
|
### Observed but deliberately deferred as bespoke or low-use
|
|
399
475
|
|
|
400
|
-
| Legacy configuration
|
|
401
|
-
|
|
|
402
|
-
| TypeScript
|
|
403
|
-
|
|
|
404
|
-
| Python excluded `__init__` exports
|
|
405
|
-
| Python improved imports and file-upload-only TypedDict mode
|
|
406
|
-
| Java custom Gradle plugins / include-wrapper
|
|
407
|
-
| C# experimental fully qualified/version namespaces
|
|
408
|
-
| PHP arbitrary Composer autoload files
|
|
409
|
-
| Ruby flattened module structure
|
|
476
|
+
| Legacy configuration | Observed projects | Reason |
|
|
477
|
+
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------: | ------------------------------------------------------------------------------------------------------------- |
|
|
478
|
+
| TypeScript `packageJson` keys without a typed field (everything but `exports`, `scripts`, `files`, `engines`, `lint-staged`, `browser`, `bugs`, `repository` and the portable metadata) | 2 | Open-ended manifest rewriting conflicts with the typed package contract. |
|
|
479
|
+
| README `exampleStyle` | 1 | Only the Fern Java generator reads it and no Postman generator does, so a typed field would have no consumer. |
|
|
480
|
+
| Python excluded `__init__` exports | 6 | File-layout customization with significant generator coupling. |
|
|
481
|
+
| Python improved imports and file-upload-only TypedDict mode | 1-3 | Experimental or narrow compatibility behavior. |
|
|
482
|
+
| Java custom Gradle plugins / include-wrapper | 1 | Arbitrary build-file injection or one-customer behavior. |
|
|
483
|
+
| C# experimental fully qualified/version namespaces | 1 | Experimental one-customer behavior. |
|
|
484
|
+
| PHP arbitrary Composer autoload files | 2 | Open-ended manifest rewriting; typed dependencies remain supported. |
|
|
485
|
+
| Ruby flattened module structure | 1 | One-customer layout behavior. |
|
|
410
486
|
|
|
411
487
|
Adding one of these fields later is additive. Retaining every historical generator flag now would
|
|
412
488
|
make v1 expensive to implement and would turn temporary compatibility behavior into a permanent
|