@postman/sdk-config 0.3.1 → 0.3.2

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 (28) hide show
  1. package/README.md +8 -4
  2. package/dist/index.cjs +111 -23
  3. package/dist/index.cjs.map +1 -1
  4. package/dist/index.js +111 -23
  5. package/dist/index.js.map +1 -1
  6. package/dist/sdk-config/index.cjs +79 -6
  7. package/dist/sdk-config/index.cjs.map +1 -1
  8. package/dist/sdk-config/index.js +79 -6
  9. package/dist/sdk-config/index.js.map +1 -1
  10. package/dist/sdk-config/v1/index.cjs +79 -6
  11. package/dist/sdk-config/v1/index.cjs.map +1 -1
  12. package/dist/sdk-config/v1/index.d.cts +4766 -0
  13. package/dist/sdk-config/v1/index.d.ts +4766 -0
  14. package/dist/sdk-config/v1/index.js +79 -6
  15. package/dist/sdk-config/v1/index.js.map +1 -1
  16. package/dist/sdk-config-ir/index.cjs +32 -17
  17. package/dist/sdk-config-ir/index.cjs.map +1 -1
  18. package/dist/sdk-config-ir/index.js +32 -17
  19. package/dist/sdk-config-ir/index.js.map +1 -1
  20. package/dist/sdk-config-ir/v1/index.cjs +32 -17
  21. package/dist/sdk-config-ir/v1/index.cjs.map +1 -1
  22. package/dist/sdk-config-ir/v1/index.d.cts +475 -160
  23. package/dist/sdk-config-ir/v1/index.d.ts +475 -160
  24. package/dist/sdk-config-ir/v1/index.js +32 -17
  25. package/dist/sdk-config-ir/v1/index.js.map +1 -1
  26. package/package.json +1 -1
  27. package/src/sdk-config/v1/README.md +14 -7
  28. package/src/sdk-config-ir/v1/README.md +92 -91
package/src/sdk-config/v1/README.md CHANGED
@@ -62,9 +62,8 @@ severity, reason, suggested manual action, and the SDK Config destination when o
62
62
  cases. Generation must not recover omitted values from legacy configuration. Differing
63
63
  target-specific values are retained as sparse target overrides when the public shape can represent
64
64
  them. Optional `api` enrichment may be supplied after Fern's definition or IR has already been
65
- lowered into the public API shape. Credentials and signing material remain outside SDK Config; the
66
- mapper reports one target-level diagnostic when a Fern output contains them without logging their
67
- values.
65
+ lowered into the public API shape. Credentials and signing material are preserved in SDK Config
66
+ output blocks when present; callers must treat these fields as sensitive secrets.
68
67
 
69
68
  ## Contract boundaries
70
69
 
@@ -86,10 +85,11 @@ bytes for the build; the server replaces the customer locator with an internal s
86
85
  SDK Config IR. Customer URLs never become generator fetch URLs. Signed URLs, S3 locations, and
87
86
  server-generated artifact metadata are not valid public locators. The public schema deliberately has
88
87
  no `compatibility`, source-origin, artifact ID, credential-resolution, or server-generated
89
- publishing control fields. Unknown fields are rejected at every object boundary. Portable API,
90
- client, documentation, package, source settings, and language field schemas come from a neutral
91
- shared domain layer to prevent drift; the public and internal envelopes and their operational
92
- extensions remain separate explicit allowlists.
88
+ publishing control fields. Publishing credentials and signing material may appear in output blocks
89
+ and must be stored, logged, and transported as secrets. Unknown fields are rejected at every object
90
+ boundary. Portable API, client, documentation, package, source settings, and language field schemas
91
+ come from a neutral shared domain layer to prevent drift; the public and internal envelopes and
92
+ their operational extensions remain separate explicit allowlists.
93
93
 
94
94
  Source `path`, `overlays`, and `overrides` values must be relative paths without parent-directory
95
95
  segments. Absolute paths and `..` traversal are rejected at validation time.
@@ -114,6 +114,13 @@ segments. Absolute paths and `..` traversal are rejected at validation time.
114
114
  {
115
115
  "language": "typescript",
116
116
  "package": { "packageName": "@acme/sdk" },
117
+ "output": {
118
+ "delivery": "zip",
119
+ "publish": {
120
+ "registry": "npm",
121
+ "credentials": { "token": "npm-token" }
122
+ }
123
+ },
117
124
  "generation": {
118
125
  "packageManager": "pnpm",
119
126
  "namespaceExportName": "AcmeSDK"
package/src/sdk-config-ir/v1/README.md CHANGED
@@ -44,8 +44,9 @@ messages. Valid IR requests route only to the IR bridge and never fall through t
44
44
  - `compatibility.outputProfile` preserves converged, Postman-legacy, or Fern-legacy output defaults
45
45
  without introducing a permanent target flavor.
46
46
  - `target.sourceOrigin` identifies where a request originated; it does not select output behavior.
47
- - Credentials are references to externally managed secrets. Tokens and passwords do not belong in
48
- normalized output or publication configuration.
47
+ - Credentials may be references to externally managed secrets or raw credential/signing values when
48
+ an integration must carry the material through the normalized config. Raw values are sensitive and
49
+ must be handled as secrets.
49
50
 
50
51
  ## Configuration design rules
51
52
 
@@ -112,52 +113,52 @@ Translators are responsible for alias resolution, unit conversion, and inverted
112
113
 
113
114
  ## Postman `BuildParameters` migration map
114
115
 
115
- | Legacy field | SDK Config IR v1 | Notes |
116
- | ---------------------------------------------- | ----------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
117
- | `specUrl` | `source.specs[].specUrl` | A legacy request creates a one-element array. |
118
- | `languages[]` | `target.language` | Translators emit one IR request per target. |
119
- | `sdkName` | `target.sdkName` | Public SDK identity, not package registry identity. |
120
- | `sdkVersion` / language `sdkVersion` | `target.sdkVersion` | Language override is resolved before emitting IR. |
121
- | `apiVersion` | `target.apiVersion` | API version metadata. |
122
- | `org` | `target.organization` | Source organization metadata. |
123
- | `baseUrl` | `api.baseUrl` | Default API URL. |
124
- | `environments` | `api.environments` | Every environment has a non-empty `urls` array; a single URL becomes one entry. |
125
- | `environmentVariables` | `api.environmentVariables` | Declarations; auth/header fields reference them by name. |
126
- | `auth` + `authentication` | `api.auth` | Legacy flags and settings become typed schemes and requirements. |
127
- | `refreshToken` | `client.tokenRefresh` | Response keys map to `accessTokenField` and `refreshTokenField`. |
128
- | `retry` | `client.retry` | Millisecond units are explicit in normalized names. |
129
- | `responseHeaders` | `client.responseHeaders` | Shared across languages. |
130
- | `multiTenant` | `client.multiTenant` | Shared client behavior. |
131
- | TypeScript `httpClient` | `generation.language.typescript.httpClient` | Only `fetch` and `axios` are selectable; other languages use their generator transport. |
132
- | `additionalConstructorParameters` | `client.additionalConstructorParameters` | Merged from language options. |
133
- | `deliveryMethods` | `output.delivery` | Normalized to `files`, `zip`, or `github`; multiple deliveries produce separate IR requests. |
134
- | `fileOutput` | `output.path` or `output.fileName` | Depends on delivery type. |
135
- | `githubRef` | `output.github.branch` | Only meaningful for GitHub delivery. |
136
- | `privateRepo` | `output.github.privateRepository` | Only meaningful for GitHub delivery. |
137
- | `publishing.githubOrg` | `output.github.repository` | Translator combines the organization and repository name. |
138
- | package names and IDs | `package` | Includes npm/PyPI/NuGet/RubyGems/Crates/Composer names and Maven IDs. |
139
- | `goModuleName` | `package.modulePath` | Go publication and import identity. |
140
- | `license`, `authors`, `developers`, `homepage` | `package` | Manifest metadata. |
141
- | TypeScript package privacy / JSR publication | `output.publish.isPackagePrivate` / `output.publish.publishToJsr` | NPM-specific publication options. |
142
- | registry workflow and env-var settings | `output.publish` | Per-registry workflow toggles, credential env vars, and trusted publishing flags. |
143
- | `documentation.url` | `docs.referenceBaseUrl` | Base URL for generated reference-file links. |
144
- | `documentation.snippets` | `docs.snippets` | `enabled` is explicit when the object is present. |
145
- | `docs[]` | `docs` | Legacy API/snippet selections are lowered to typed documentation settings. |
146
- | `includeWatermark` | `generation.includeWatermark` | Simple on/off behavior. |
147
- | `includeOptionalSnippetParameters` | `generation.includeOptionalSnippetParameters` | Simple on/off behavior. |
148
- | `inferServiceNames` | `generation.inferServiceNames` | Simple on/off behavior. |
149
- | `buildAllModels` | `generation.buildAllModels` | Simple on/off behavior. |
150
- | `deprecatedOperations.include` | `generation.includeDeprecatedOperations` | Simplified to a boolean. |
151
- | `multipleResponses.enabled` | `generation.multipleResponses` | Simplified to a boolean. |
152
- | `devContainer` | `generation.devContainer` | Simple on/off behavior. |
153
- | `ignoreFiles` / language `ignore` | `generation.ignoreFiles` | Language aliases are resolved by the translator. |
154
- | `reservedKeywords` | `generation.reservedKeywords` | Shared generator input. |
155
- | `hooks`, `hookDependencies`, `hooksLocation` | `generation.hooks` | Location and dependencies are one configurable feature. |
156
- | `customCode*`, previous artifact location | `generation.customCode` | Locations become typed generation assets. |
157
- | `workflow` | `generation.workflows[]` | The normalized shape supports more than one workflow. |
158
- | `customQueries` | `generation.customQueryPaths` | Query definitions are represented as paths. |
159
- | `analytics` | `generation.analytics` | `enabled` is explicit; timing fields use milliseconds. |
160
- | language options | `generation.language.<target>` or shared fields | Package, naming, validation, and dependency aliases are lifted out first. |
116
+ | Legacy field | SDK Config IR v1 | Notes |
117
+ | --------------------------------------------------- | ----------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
118
+ | `specUrl` | `source.specs[].specUrl` | A legacy request creates a one-element array. |
119
+ | `languages[]` | `target.language` | Translators emit one IR request per target. |
120
+ | `sdkName` | `target.sdkName` | Public SDK identity, not package registry identity. |
121
+ | `sdkVersion` / language `sdkVersion` | `target.sdkVersion` | Language override is resolved before emitting IR. |
122
+ | `apiVersion` | `target.apiVersion` | API version metadata. |
123
+ | `org` | `target.organization` | Source organization metadata. |
124
+ | `baseUrl` | `api.baseUrl` | Default API URL. |
125
+ | `environments` | `api.environments` | Every environment has a non-empty `urls` array; a single URL becomes one entry. |
126
+ | `environmentVariables` | `api.environmentVariables` | Declarations; auth/header fields reference them by name. |
127
+ | `auth` + `authentication` | `api.auth` | Legacy flags and settings become typed schemes and requirements. |
128
+ | `refreshToken` | `client.tokenRefresh` | Response keys map to `accessTokenField` and `refreshTokenField`. |
129
+ | `retry` | `client.retry` | Millisecond units are explicit in normalized names. |
130
+ | `responseHeaders` | `client.responseHeaders` | Shared across languages. |
131
+ | `multiTenant` | `client.multiTenant` | Shared client behavior. |
132
+ | TypeScript `httpClient` | `generation.language.typescript.httpClient` | Only `fetch` and `axios` are selectable; other languages use their generator transport. |
133
+ | `additionalConstructorParameters` | `client.additionalConstructorParameters` | Merged from language options. |
134
+ | `deliveryMethods` | `output.delivery` | Normalized to `files`, `zip`, or `github`; multiple deliveries produce separate IR requests. |
135
+ | `fileOutput` | `output.path` or `output.fileName` | Depends on delivery type. |
136
+ | `githubRef` | `output.github.branch` | Only meaningful for GitHub delivery. |
137
+ | `privateRepo` | `output.github.privateRepository` | Only meaningful for GitHub delivery. |
138
+ | `publishing.githubOrg` | `output.github.repository` | Translator combines the organization and repository name. |
139
+ | package names and IDs | `package` | Includes npm/PyPI/NuGet/RubyGems/Crates/Composer names and Maven IDs. |
140
+ | `goModuleName` | `package.modulePath` | Go publication and import identity. |
141
+ | `license`, `authors`, `developers`, `homepage` | `package` and `output.github.license` | Manifest metadata and GitHub-specific repository license settings. |
142
+ | TypeScript package privacy / JSR publication | `output.publish.isPackagePrivate` / `output.publish.publishToJsr` | NPM-specific publication options. |
143
+ | registry workflow, credential, and env-var settings | `output.publish` | Per-registry workflow toggles, credential values/refs/env vars, and trusted publishing flags. |
144
+ | `documentation.url` | `docs.referenceBaseUrl` | Base URL for generated reference-file links. |
145
+ | `documentation.snippets` | `docs.snippets` | `enabled` is explicit when the object is present. |
146
+ | `docs[]` | `docs` | Legacy API/snippet selections are lowered to typed documentation settings. |
147
+ | `includeWatermark` | `generation.includeWatermark` | Simple on/off behavior. |
148
+ | `includeOptionalSnippetParameters` | `generation.includeOptionalSnippetParameters` | Simple on/off behavior. |
149
+ | `inferServiceNames` | `generation.inferServiceNames` | Simple on/off behavior. |
150
+ | `buildAllModels` | `generation.buildAllModels` | Simple on/off behavior. |
151
+ | `deprecatedOperations.include` | `generation.includeDeprecatedOperations` | Simplified to a boolean. |
152
+ | `multipleResponses.enabled` | `generation.multipleResponses` | Simplified to a boolean. |
153
+ | `devContainer` | `generation.devContainer` | Simple on/off behavior. |
154
+ | `ignoreFiles` / language `ignore` | `generation.ignoreFiles` | Language aliases are resolved by the translator. |
155
+ | `reservedKeywords` | `generation.reservedKeywords` | Shared generator input. |
156
+ | `hooks`, `hookDependencies`, `hooksLocation` | `generation.hooks` | Location and dependencies are one configurable feature. |
157
+ | `customCode*`, previous artifact location | `generation.customCode` | Locations become typed generation assets. |
158
+ | `workflow` | `generation.workflows[]` | The normalized shape supports more than one workflow. |
159
+ | `customQueries` | `generation.customQueryPaths` | Query definitions are represented as paths. |
160
+ | `analytics` | `generation.analytics` | `enabled` is explicit; timing fields use milliseconds. |
161
+ | language options | `generation.language.<target>` or shared fields | Package, naming, validation, and dependency aliases are lifted out first. |
161
162
 
162
163
  ### Postman language-option migration map
163
164
 
@@ -195,49 +196,49 @@ inputs were not restored as part of the normalized contract.
195
196
  Customer-use counts below are distinct projects observed in the 61-project configuration snapshot
196
197
  audited on 2026-07-17. Counts guide the initial contract; they are not a permanent support policy.
197
198
 
198
- | Fern field or aliases | SDK Config IR v1 | Observed projects |
199
- | --------------------------------------------------------------------------- | ---------------------------------------------------------------------------- | -----------------------------------------: |
200
- | `api.specs[]` | `source.specs[]` | 53 OpenAPI, 3 AsyncAPI |
201
- | `api.specs[].namespace` | `source.specs[].namespace` | 1 |
202
- | `api.specs[].overlays` | `source.specs[].overlays` | 2 |
203
- | `api.specs[].overrides` | `source.specs[].overrides` | 39 |
204
- | `api.default-url` | `api.baseUrl` | 21 |
205
- | `api.default-environment` | `api.defaultEnvironment` | 22 |
206
- | `api.environments` | `api.environments` | 20+ |
207
- | `api.auth`, `api.auth-schemes` | `api.auth` | 27 |
208
- | `api.headers` | `api.headers` | 11+ |
209
- | generator-group `audiences` | `api.audiences` | Absent selects all audiences. |
210
- | generator `inlinePathParameters`, `inline-path-parameters`, and API setting | `client.pathParameterStyle` | 12 API; 1-3 per language |
211
- | generator `inlineFileProperties`, `inline-file-properties` | `client.filePropertyStyle` | 1-3 per language |
212
- | `inline_request_params` | `client.requestParameterStyle` | 6 Python |
213
- | `customPagerName`, `custom-pager-name`, `custom_pager_name` | `generation.naming.pagerName` | 2-5 per language |
214
- | `smart-casing`, `smart-casing-digit-word-boundary` | `generation.naming` | Preserved only when explicitly set. |
215
- | timeout aliases in seconds or milliseconds | `client.timeoutMs` | Translator converts units. |
216
- | `skipResponseValidation`, Python `skip_validation` | `client.responseValidation` | Inverted; 12 TS, 8 Python |
217
- | `useDefaultRequestParameterValues` aliases | `client.useDefaultRequestParameterValues` | 1 |
218
- | `respectOptionalRequestBody`, `respect-optional-request-body` | `client.respectOptionalRequestBody` | Not in the project snapshot; see below |
219
- | `enable-wire-tests`, `enableWireTests`, `generateWireTests` | `generation.wireTests` | 1-15 per language |
220
- | WebSocket generation aliases | `generation.webSockets` | 3 TS, 3 Python |
221
- | `streamType`, `fileResponseType` | `generation.streams` | 1 TS |
222
- | client/exported/environment class aliases | `generation.naming` | 1-28 per language |
223
- | base API/general exception class aliases | `generation.naming.apiErrorName` / `generation.naming.baseErrorName` | 3-6 Java/C# |
224
- | namespace/package-prefix aliases | `package.namespace` | 1-30 per language |
225
- | output registry package names | `package.packageName` | 5-28 per registry language |
226
- | Python custom `package_name` | `package.moduleName` | 18 |
227
- | Go `module.path` | `package.modulePath` | 3 |
228
- | Maven `group` / `artifact` | `package.groupId` / `package.artifactId` | 7 |
229
- | custom/extra dependencies | `package.extraDependencies` and related lists | Multiple languages |
230
- | local output | `output.delivery: "files"` | 49+ |
231
- | registry output | `output.publish` plus `package` identity | 5-28 per registry language |
232
- | GitHub output | `output.delivery: "github"` and `output.github` | Translator resolves Fern owner/repo forms. |
233
- | npm package privacy and JSR publication | `output.publish.isPackagePrivate` / `output.publish.publishToJsr` | NPM-only booleans |
234
- | registry version and workflow gate | `output.publish.version` / `output.publish.shouldGeneratePublishWorkflow` | Per-registry controls |
235
- | registry credential environment variables | `output.publish.*EnvironmentVariable` | Registry-specific env-var names |
236
- | trusted publishing / OIDC markers | `output.publish.trustedPublishing` | npm, PyPI, and NuGet |
237
- | Maven coordinate and signing env vars | `output.publish.coordinate` / `output.publish.signatureEnvironmentVariables` | Maven-specific |
238
- | Fern README config | `docs.readme` | 12 API names; 11 disabled-section configs |
239
- | `customReadmeSections` | `docs.readme.customSections` | Not in the project snapshot; see below |
240
- | `includeApiReference` | `docs.includeApiReference` | 10 TS |
199
+ | Fern field or aliases | SDK Config IR v1 | Observed projects |
200
+ | --------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- | -----------------------------------------: |
201
+ | `api.specs[]` | `source.specs[]` | 53 OpenAPI, 3 AsyncAPI |
202
+ | `api.specs[].namespace` | `source.specs[].namespace` | 1 |
203
+ | `api.specs[].overlays` | `source.specs[].overlays` | 2 |
204
+ | `api.specs[].overrides` | `source.specs[].overrides` | 39 |
205
+ | `api.default-url` | `api.baseUrl` | 21 |
206
+ | `api.default-environment` | `api.defaultEnvironment` | 22 |
207
+ | `api.environments` | `api.environments` | 20+ |
208
+ | `api.auth`, `api.auth-schemes` | `api.auth` | 27 |
209
+ | `api.headers` | `api.headers` | 11+ |
210
+ | generator-group `audiences` | `api.audiences` | Absent selects all audiences. |
211
+ | generator `inlinePathParameters`, `inline-path-parameters`, and API setting | `client.pathParameterStyle` | 12 API; 1-3 per language |
212
+ | generator `inlineFileProperties`, `inline-file-properties` | `client.filePropertyStyle` | 1-3 per language |
213
+ | `inline_request_params` | `client.requestParameterStyle` | 6 Python |
214
+ | `customPagerName`, `custom-pager-name`, `custom_pager_name` | `generation.naming.pagerName` | 2-5 per language |
215
+ | `smart-casing`, `smart-casing-digit-word-boundary` | `generation.naming` | Preserved only when explicitly set. |
216
+ | timeout aliases in seconds or milliseconds | `client.timeoutMs` | Translator converts units. |
217
+ | `skipResponseValidation`, Python `skip_validation` | `client.responseValidation` | Inverted; 12 TS, 8 Python |
218
+ | `useDefaultRequestParameterValues` aliases | `client.useDefaultRequestParameterValues` | 1 |
219
+ | `respectOptionalRequestBody`, `respect-optional-request-body` | `client.respectOptionalRequestBody` | Not in the project snapshot; see below |
220
+ | `enable-wire-tests`, `enableWireTests`, `generateWireTests` | `generation.wireTests` | 1-15 per language |
221
+ | WebSocket generation aliases | `generation.webSockets` | 3 TS, 3 Python |
222
+ | `streamType`, `fileResponseType` | `generation.streams` | 1 TS |
223
+ | client/exported/environment class aliases | `generation.naming` | 1-28 per language |
224
+ | base API/general exception class aliases | `generation.naming.apiErrorName` / `generation.naming.baseErrorName` | 3-6 Java/C# |
225
+ | namespace/package-prefix aliases | `package.namespace` | 1-30 per language |
226
+ | output registry package names | `package.packageName` | 5-28 per registry language |
227
+ | Python custom `package_name` | `package.moduleName` | 18 |
228
+ | Go `module.path` | `package.modulePath` | 3 |
229
+ | Maven `group` / `artifact` | `package.groupId` / `package.artifactId` | 7 |
230
+ | custom/extra dependencies | `package.extraDependencies` and related lists | Multiple languages |
231
+ | local output | `output.delivery: "files"` | 49+ |
232
+ | registry output | `output.publish` plus `package` identity | 5-28 per registry language |
233
+ | GitHub output | `output.delivery: "github"` and `output.github` | Translator resolves Fern owner/repo forms. |
234
+ | npm package privacy and JSR publication | `output.publish.isPackagePrivate` / `output.publish.publishToJsr` | NPM-only booleans |
235
+ | registry version and workflow gate | `output.publish.version` / `output.publish.shouldGeneratePublishWorkflow` | Per-registry controls |
236
+ | registry credentials and environment variables | `output.publish.credentials` / `output.publish.*EnvironmentVariable` | Registry-specific secret values/names |
237
+ | trusted publishing / OIDC markers | `output.publish.trustedPublishing` | npm, PyPI, and NuGet |
238
+ | Maven coordinate and signing material/env vars | `output.publish.coordinate` / `output.publish.signature` / `output.publish.signatureEnvironmentVariables` | Maven-specific |
239
+ | Fern README config | `docs.readme` | 12 API names; 11 disabled-section configs |
240
+ | `customReadmeSections` | `docs.readme.customSections` | Not in the project snapshot; see below |
241
+ | `includeApiReference` | `docs.includeApiReference` | 10 TS |
241
242
 
242
243
  The Rust language config was added after the initial audit. That audit compared existing Fern
243
244
  _customer projects_, which surfaced no Rust-specific options; comparing the Fern Rust generator's