@postman/sdk-config 0.1.0 → 0.2.0

package/README.md

@@ -1,164 +1,179 @@
 # @postman/sdk-config
 
-Shared, runtime-validated public and internal configuration contracts for Postman's SDK generation
-pipeline.
+Build and validate SDK Config documents for SDK Generation API requests.
 
-This package is the source of truth for the customer-facing `SdkConfig` and internal `SdkConfigIr`.
-It is intended for sdk-gen-core, sdk-gen-api, Postman and Fern CLIs, and translators that normalize
-producer-specific configuration before generation.
+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
 
-The package is configured as a restricted package in the `@postman` npm scope.
-
 ```sh
 npm install @postman/sdk-config
 ```
 
-## Use
-
-Use `SdkConfigV1` for customer-authored, potentially multi-target generation configuration:
+Node.js 24 or newer is required. Both ESM and CommonJS are supported.
 
-```ts
-import { parseSdkConfigV1, type SdkConfigV1 } from '@postman/sdk-config/sdk-config/v1';
-
-const sdkConfig: SdkConfigV1 = parseSdkConfigV1(untrustedInput);
-```
+## Create and validate an SDK Config
 
-Use `SdkConfigIrV1` only for the normalized, single-target internal generator contract:
+Use `validateSdkConfigV1` for a customer-authored document. Validation preserves omitted properties
+so persisted configuration is not populated with runtime defaults.
 
 ```ts
-import { parseSdkConfigIrV1, type SdkConfigIrV1 } from '@postman/sdk-config/sdk-config-ir/v1';
-
-const sdkConfigIr: SdkConfigIrV1 = parseSdkConfigIrV1(untrustedInput);
-```
-
-The package also exposes `@postman/sdk-config`, `@postman/sdk-config/sdk-config`, and
-`@postman/sdk-config/sdk-config-ir` as convenient current-version entry points. Persisted payloads
-must still include the appropriate `schemaVersion`.
-
-`SdkConfigV1` does not accept source selection, server-owned fields, `SdkConfigIrV1`, or legacy
-Postman `BuildParameters`. See the [SDK Config v1 reference](src/sdk-config/v1/README.md) for the
-boundaries and target precedence rules.
-
-Both ESM `import` and CommonJS `require` consumers are supported.
-
-## Project layout
-
-```text
-src/
-  sdk-config-domain/
-    v1/                 # Portable field schemas shared by public config and internal IR
-  sdk-config/
-    v1/                 # Customer-facing multi-target schema and contract reference
-  sdk-config-ir/
-    v1/                 # Versioned schema, inferred types, and contract reference
-tests/
-  fixtures/
-    sdk-config/v1/      # Canonical public configuration payloads
-    sdk-config-ir/v1/   # Canonical portable payloads
-  sdk-config/v1/        # Public contract and export tests
-  sdk-config-ir/v1/     # Contract behavior tests
-docs/
-  migration.md          # sdk-gen-core adoption sequence
+import {
+  parseSdkConfigV1,
+  validateSdkConfigV1,
+  type SdkConfigV1,
+  type SdkConfigV1Document,
+  type SdkConfigV1Input,
+} from '@postman/sdk-config/sdk-config/v1';
+
+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: {},
+  output: { delivery: 'zip', fileName: 'example-typescript.zip' },
+  docs: { includeApiReference: true },
+  generation: { includeWatermark: true },
+  targets: [
+    {
+      language: 'typescript',
+      generatorVersion: '1.2.3',
+      package: { packageName: '@example/sdk' },
+      generation: { packageManager: 'pnpm', testFramework: 'vitest' },
+    },
+  ],
+};
+
+const document: SdkConfigV1Document = validateSdkConfigV1(input);
+const sdkConfig: SdkConfigV1 = parseSdkConfigV1(document);
 ```
 
-## Develop
+Use `parseSdkConfigV1` when entering the runtime boundary and materializing the shared domain
+defaults. For validation without throwing, use the exported schema:
 
-Requires Node.js 24 or newer. If you use nvm, run `nvm use` from the repository root.
+```ts
+import { sdkConfigV1Schema } from '@postman/sdk-config/sdk-config/v1';
 
-```sh
-npm install
-npm run check
-npm pack --dry-run
+const result = sdkConfigV1Schema.safeParse(input);
+if (!result.success) {
+  console.error(result.error.issues);
+}
 ```
 
-`npm run check` verifies formatting, linting, TypeScript, tests, and the dual-format package build.
+SDK Config objects are strict. Unknown fields, duplicate language targets, incompatible package
+publication settings, and non-exact generator versions are rejected.
 
-## Versioning and publishing
+`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.
 
-- npm access is `restricted`; do not set package.json `private: true`, because npm would refuse to
-  publish it.
-- Additive v1 fields require a package minor version and a consumer-first rollout because v1 uses
-  strict runtime objects: an older consumer rejects fields it does not know.
-- Breaking wire changes get a new schema directory and discriminator such as `sdk-config/v2` or
-  `sdk-config-ir/v2`.
-- Keep the previous version exported while consumers migrate.
+## Use SDK Config in an SDK Generation API request
 
-### Manual release process
+An SDK Generation API request combines three kinds of data:
 
-Release automation is intentionally deferred while the tagging and publishing process is reviewed
-with Postman's security team. Until that process is established, use the following manual release
-procedure. The commands use `1.1.0` as an example; replace it consistently with the version being
-released.
+1. Request metadata describing the API input and generation targets.
+2. A source archive containing the API definition files.
+3. One SDK Config JSON payload for each request target that uses `payloadKind: "sdk-config-v1"`.
 
-#### 1. Prepare a release branch from develop
+The payload filename must match its target ID: `<targetId>.json`.
 
-Normal feature pull requests target `develop`. Start the release from an up-to-date `develop`
-branch, update the version without creating a tag, and run the complete check suite:
-
-```sh
-git switch develop
-git pull --ff-only origin develop
-git switch -c release/v1.1.0
-npm version 1.1.0 --no-git-tag-version
-npm run check
-git add package.json package-lock.json
-git commit -m "release: v1.1.0"
-git push -u origin release/v1.1.0
+```ts
+const targetId = 'typescript-sdk';
+const request = {
+  protocolVersion: 2,
+  apiName: 'Example API',
+  idempotencyKey: crypto.randomUUID(),
+  apiInputs: [{ id: 'default', specIndexes: 'all' }],
+  targets: [
+    {
+      targetId,
+      apiInputId: 'default',
+      language: 'typescript',
+      sdk: {
+        name: sdkConfig.sdkName,
+        version: sdkConfig.sdkVersion,
+        ...(sdkConfig.apiVersion === undefined ? {} : { apiVersion: sdkConfig.apiVersion }),
+      },
+      fernGenerator: { id: 'typescript-generator', version: '1.2.3' },
+      payloadKind: 'sdk-config-v1',
+      package: sdkConfig.targets[0]?.package,
+      requestedOutput: { type: 'download' },
+    },
+  ],
+};
+
+const form = new FormData();
+form.append('request', JSON.stringify(request));
+form.append('sources', sourceArchive, 'sources.tar.gz');
+form.append(
+  'payloads',
+  new Blob([JSON.stringify(sdkConfig)], { type: 'application/json' }),
+  `${targetId}.json`,
+);
+
+const response = await fetch('https://api.example.com/sdk-generations', {
+  method: 'POST',
+  headers: { Authorization: `Bearer ${accessToken}` },
+  body: form,
+});
 ```
 
-Open a pull request from `release/v1.1.0` into `main`. Review the version change, wait for required
-checks and approvals, and merge it. The release branch isolates the version bump and preserves the
-exact `develop` snapshot being reviewed, while work can continue independently on `develop`.
+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.
 
-#### 2. Merge main back into develop
+This request form supports downloaded archives. Its effective SDK Config output must be
+`{ "delivery": "zip" }` without publication settings, and `requestedOutput` must be
+`{ "type": "download" }`.
 
-The publishing workflow requires the tagged commit to be in the history of the repository's default
-branch, `develop`. After the release pull request is merged, create a synchronization branch from
-the latest `develop` and merge the released `main` into it:
+### Keep request targets consistent
 
-```sh
-git fetch origin
-git switch -c chore/merge-main-after-v1.1.0 origin/develop
-git merge --no-ff origin/main -m "Merge main back to develop after v1.1.0"
-git push -u origin chore/merge-main-after-v1.1.0
-```
+For each request target, the API request and matching SDK Config target must agree on:
 
-Open a pull request from `chore/merge-main-after-v1.1.0` into `develop`, wait for its checks, and use
-**Create a merge commit** to merge it. Do not squash or rebase this pull request: the original
-`main` commit must remain in `develop`'s ancestry for the publishing workflow's validation. The
-temporary branch can then be deleted safely.
+- `language`
+- effective SDK name and version
+- API version, when present
+- generator version, when `generatorVersion` is present in SDK Config
+- every package property included in the API request; the request may omit package properties
+- ZIP output without publication settings, paired with a download request
 
-#### 3. Create the release tag from main
+Root package properties are inherited by each target and overridden by target package properties.
+A target output replaces the root output; it is not merged with it.
 
-After the synchronization pull request is merged, update your local `main` and verify that
-`package.json` contains the version you are about to tag:
+## Generation file paths
 
-```sh
-git switch main
-git pull --ff-only origin main
-node -p "require('./package.json').version"
-```
+These SDK Config values are interpreted as file paths during generation:
 
-Create the signed tag and dispatch the **Package Release** workflow with the tag as its explicit
-input:
+- `source.specs[].path`
+- `source.specs[].overlays[]`
+- `source.specs[].overrides[]`
+- `generation.customQueryPaths[]`
+- `generation.workflows[].path`
+- `generation.hooks.source.location` when `source.type` is `path`
+- `generation.customCode.source.location` when `source.type` is `path`
 
-```sh
-npm run release -- v1.1.0
-```
+Each value must be a relative path and cannot contain a `..` path segment. Absolute POSIX paths,
+Windows drive paths, UNC paths, and parent-directory traversal are rejected during validation. URL
+source locations are not treated as file paths.
+
+## Multiple targets
 
-The release script requires a clean, up-to-date `main`, verifies that the package version matches
-the tag and that the commit is already contained in `main` and `develop`, creates and verifies a
-signed, annotated tag, pushes it, and dispatches `.github/workflows/npm-publish.yml` with
-`tag=v1.1.0`. The workflow independently rechecks `main` ancestry before calling the shared
-publisher, which verifies `develop` ancestry and the tag signature. Explicit dispatch avoids
-duplicate publish runs and keeps retries tied to the immutable tag. In GitHub, open **Actions** →
-**Package Release** and confirm the dispatched run succeeds.
+An SDK Config can describe several language targets. Shared `api`, `client`, `docs`, and generation
+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.
 
-If publishing fails after the tag has been created, do not delete, move, or recreate the tag. After
-the underlying problem is fixed, run the same command again. The script verifies and reuses the
-existing tag before dispatching another run. You can also use **Actions** → **Package Release** →
-**Run workflow** and enter the existing tag, such as `v1.1.0`.
+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.
 
-See the [SDK Config IR v1 reference](src/sdk-config-ir/v1/README.md) for the complete contract.
+Supported target languages are `typescript`, `python`, `java`, `kotlin`, `go`, `csharp`, `php`,
+`ruby`, `rust`, `swift`, `cli`, `mcp`, and `terraform`.