@postman/sdk-config 0.1.1 → 0.2.0

package/README.md

@@ -2,10 +2,10 @@
 
 Build and validate SDK Config documents for SDK Generation API requests.
 
-SDK Config describes what to generate: SDK identity, API behavior, client behavior, package
-metadata, documentation, output, shared generation options, and one or more language targets. API
-source files, authentication, idempotency, and transport metadata belong to the SDK Generation API
-request rather than the SDK Config document.
+SDK Config describes what to generate: API source provenance, SDK identity, API behavior, client
+behavior, package metadata, documentation, output, shared generation options, and one or more
+language targets. The materialized API source bytes, authentication, idempotency, and transport
+metadata belong to the SDK Generation API request rather than the SDK Config document.
 
 ## Install
 
@@ -17,13 +17,15 @@ Node.js 24 or newer is required. Both ESM and CommonJS are supported.
 
 ## Create and validate an SDK Config
 
-Use the versioned entry point when creating an API payload. `parseSdkConfigV1` validates unknown
-input, applies defaults, and returns the normalized `SdkConfigV1` type.
+Use `validateSdkConfigV1` for a customer-authored document. Validation preserves omitted properties
+so persisted configuration is not populated with runtime defaults.
 
 ```ts
 import {
   parseSdkConfigV1,
+  validateSdkConfigV1,
   type SdkConfigV1,
+  type SdkConfigV1Document,
   type SdkConfigV1Input,
 } from '@postman/sdk-config/sdk-config/v1';
 
@@ -31,6 +33,9 @@ const input: SdkConfigV1Input = {
   schemaVersion: 'sdk-config/v1',
   sdkName: 'Example SDK',
   sdkVersion: '1.0.0',
+  source: {
+    specs: [{ id: 'example', type: 'openapi', path: './openapi.yml' }],
+  },
   api: {},
   client: { timeoutMs: 30_000 },
   package: {},
@@ -47,10 +52,12 @@ const input: SdkConfigV1Input = {
   ],
 };
 
-const sdkConfig: SdkConfigV1 = parseSdkConfigV1(input);
+const document: SdkConfigV1Document = validateSdkConfigV1(input);
+const sdkConfig: SdkConfigV1 = parseSdkConfigV1(document);
 ```
 
-For validation without throwing, use the exported schema:
+Use `parseSdkConfigV1` when entering the runtime boundary and materializing the shared domain
+defaults. For validation without throwing, use the exported schema:
 
 ```ts
 import { sdkConfigV1Schema } from '@postman/sdk-config/sdk-config/v1';
@@ -64,6 +71,11 @@ if (!result.success) {
 SDK Config objects are strict. Unknown fields, duplicate language targets, incompatible package
 publication settings, and non-exact generator versions are rejected.
 
+`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.
+
 ## Use SDK Config in an SDK Generation API request
 
 An SDK Generation API request combines three kinds of data:
@@ -115,8 +127,9 @@ const response = await fetch('https://api.example.com/sdk-generations', {
 });
 ```
 
-The endpoint URL, authentication scheme, source archive format, and response shape are defined by
-the SDK Generation API provider.
+Before submitting the request, the client resolves every SDK Config source path or URL and places
+the exact bytes in the source archive. The endpoint URL, authentication scheme, source archive
+format, and response shape are defined by the SDK Generation API provider.
 
 This request form supports downloaded archives. Its effective SDK Config output must be
 `{ "delivery": "zip" }` without publication settings, and `requestedOutput` must be
@@ -140,6 +153,9 @@ A target output replaces the root output; it is not merged with it.
 
 These SDK Config values are interpreted as file paths during generation:
 
+- `source.specs[].path`
+- `source.specs[].overlays[]`
+- `source.specs[].overrides[]`
 - `generation.customQueryPaths[]`
 - `generation.workflows[].path`
 - `generation.hooks.source.location` when `source.type` is `path`
@@ -152,8 +168,9 @@ source locations are not treated as file paths.
 ## Multiple targets
 
 An SDK Config can describe several language targets. Shared `api`, `client`, `docs`, and generation
-settings apply to every target. SDK identity, package metadata, output, and language-specific
-generation settings can be overridden per target.
+settings apply to every target. SDK identity, client settings, documentation, package metadata,
+output, common generation settings, and language-specific generation settings can be overridden per
+target.
 
 Each language can appear only once. When sending a multi-target SDK Config to an SDK Generation API,
 attach the config under each request target that should select its matching language configuration.