@postman/sdk-config 0.0.4 → 0.1.1

package/README.md

@@ -1,139 +1,162 @@
 # @postman/sdk-config
 
-Shared, runtime-validated 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 `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: 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.
 
 ## Install
 
-The package is configured as a restricted package in the `@postman` npm scope.
-
 ```sh
 npm install @postman/sdk-config
 ```
 
-## Use
-
-Prefer the versioned entry point at transport and persistence boundaries:
-
-```ts
-import { parseSdkConfigIrV1, type SdkConfigIrV1 } from '@postman/sdk-config/sdk-config-ir/v1';
-
-const sdkConfigIr: SdkConfigIrV1 = parseSdkConfigIrV1(untrustedInput);
-```
+Node.js 24 or newer is required. Both ESM and CommonJS are supported.
 
-The package also exposes `@postman/sdk-config` and `@postman/sdk-config/sdk-config-ir` as convenient
-current-version entry points. Persisted payloads must still include `schemaVersion`.
+## Create and validate an SDK Config
 
-Both ESM `import` and CommonJS `require` consumers are supported.
+Use the versioned entry point when creating an API payload. `parseSdkConfigV1` validates unknown
+input, applies defaults, and returns the normalized `SdkConfigV1` type.
 
-## Project layout
-
-```text
-src/
-  sdk-config-ir/
-    v1/                 # Versioned schema, inferred types, and contract reference
-tests/
-  fixtures/
-    sdk-config-ir/v1/   # Canonical portable payloads
-  sdk-config-ir/v1/     # Contract behavior tests
-docs/
-  migration.md          # sdk-gen-core adoption sequence
+```ts
+import {
+  parseSdkConfigV1,
+  type SdkConfigV1,
+  type SdkConfigV1Input,
+} from '@postman/sdk-config/sdk-config/v1';
+
+const input: SdkConfigV1Input = {
+  schemaVersion: 'sdk-config/v1',
+  sdkName: 'Example SDK',
+  sdkVersion: '1.0.0',
+  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 sdkConfig: SdkConfigV1 = parseSdkConfigV1(input);
 ```
 
-## Develop
+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.
-
-## Versioning and publishing
+SDK Config objects are strict. Unknown fields, duplicate language targets, incompatible package
+publication settings, and non-exact generator versions are rejected.
 
-- 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-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`.
+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 a signed, annotated tag on the checked-out `main` commit, verify it locally, and push it:
+- `generation.customQueryPaths[]`
+- `generation.workflows[].path`
+- `generation.hooks.source.location` when `source.type` is `path`
+- `generation.customCode.source.location` when `source.type` is `path`
 
-```sh
-git tag -s v1.1.0 -m "Release v1.1.0"
-git tag -v v1.1.0
-git push origin 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
 
-Pushing a tag matching `v*.*.*` automatically triggers the **Package Release** workflow defined in
-`.github/workflows/npm-publish.yml`. In GitHub, open **Actions** → **Package Release** and confirm
-the tag-triggered run succeeds.
+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.
 
-If publishing fails after the tag has been created, do not delete, move, or recreate the tag. After
-the underlying problem is fixed, open **Actions** → **Package Release** → **Run workflow** and enter
-the existing tag, such as `v1.1.0`, to retry it.
+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`.