@postman/sdk-config 0.1.0 → 0.1.1

package/README.md

@@ -1,164 +1,162 @@
 # @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: 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
-
-Use `SdkConfigV1` for customer-authored, potentially multi-target generation configuration:
-
-```ts
-import { parseSdkConfigV1, type SdkConfigV1 } from '@postman/sdk-config/sdk-config/v1';
+Node.js 24 or newer is required. Both ESM and CommonJS are supported.
 
-const sdkConfig: SdkConfigV1 = parseSdkConfigV1(untrustedInput);
-```
+## Create and validate an SDK Config
 
-Use `SdkConfigIrV1` only for the normalized, single-target internal generator contract:
+Use the versioned entry point when creating an API payload. `parseSdkConfigV1` validates unknown
+input, applies defaults, and returns the normalized `SdkConfigV1` type.
 
 ```ts
-import { parseSdkConfigIrV1, type SdkConfigIrV1 } from '@postman/sdk-config/sdk-config-ir/v1';
-
-const sdkConfigIr: SdkConfigIrV1 = parseSdkConfigIrV1(untrustedInput);
+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);
 ```
 
-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
-```
-
-## 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/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`.
+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:
+- `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, 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, 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`.

package/dist/index.cjs

@@ -9,6 +9,10 @@ var semver__default = /*#__PURE__*/_interopDefault(semver);
 
 // src/sdk-config-domain/v1/api.ts
 var nonEmptyStringSchema = zod.z.string().min(1);
+var relativePathSchema = nonEmptyStringSchema.refine(
+  (value) => !/^(?:[\\/]|[A-Za-z]:)/.test(value) && !value.split(/[\\/]/).some((segment) => segment === ".."),
+  { message: "must be a relative path without parent directory segments" }
+);
 var exactSemverSchema = zod.z.string().refine(
   (value) => {
     if (value.trim() !== value || !/^\d/.test(value)) {
@@ -253,7 +257,7 @@ var clientConfigSchema = zod.z.strictObject({
 
 // src/sdk-config/v1/client.ts
 var sdkConfigV1ClientConfigSchema = clientConfigSchema;
-var goModulePathSchema = nonEmptyStringSchema.regex(
+var goModulePathSchema = relativePathSchema.regex(
   /^(?!.*(?:^|\/)\.{1,2}(?:\/|$))[A-Za-z0-9._~-]+(?:\/[A-Za-z0-9._~-]+)+$/,
   "Go module path must be a slash-delimited path using letters, numbers, dots, dashes, underscores, or tildes"
 );
@@ -934,7 +938,7 @@ function outputDiagnostic(path, index) {
   };
 }
 var customerGenerationAssetSchema = zod.z.discriminatedUnion("type", [
-  zod.z.strictObject({ type: zod.z.literal("path"), location: nonEmptyStringSchema }),
+  zod.z.strictObject({ type: zod.z.literal("path"), location: relativePathSchema }),
   zod.z.strictObject({ type: zod.z.literal("url"), location: nonEmptyStringSchema })
 ]);
 var hookDependencySchema = zod.z.strictObject({
@@ -955,7 +959,7 @@ var customCodeConfigSchema = zod.z.strictObject({
   protectedFiles: zod.z.array(nonEmptyStringSchema).optional()
 });
 var workflowConfigSchema = zod.z.strictObject({
-  path: nonEmptyStringSchema,
+  path: relativePathSchema,
   outputName: nonEmptyStringSchema.optional()
 });
 var analyticsHeaderSchema = zod.z.union([
@@ -1032,7 +1036,7 @@ var sdkConfigV1GenerationConfigSchema = zod.z.strictObject({
   hooks: hooksConfigSchema.optional(),
   customCode: customCodeConfigSchema.optional(),
   workflows: zod.z.array(workflowConfigSchema).optional(),
-  customQueryPaths: zod.z.array(nonEmptyStringSchema).optional(),
+  customQueryPaths: zod.z.array(relativePathSchema).optional(),
   analytics: analyticsConfigSchema.optional(),
   wireTests: wireTestsSchema.optional(),
   unitTests: unitTestsSchema.optional(),
@@ -2219,10 +2223,11 @@ var compatibilityConfigSchema = zod.z.strictObject({
   legacyInput: legacyInputSchema.optional(),
   unsupportedFields: zod.z.array(unsupportedFieldSchema).optional()
 });
-var generationAssetSchema = zod.z.strictObject({
-  type: zod.z.enum(["path", "url", "artifact"]),
-  location: nonEmptyStringSchema
-});
+var generationAssetSchema = zod.z.discriminatedUnion("type", [
+  zod.z.strictObject({ type: zod.z.literal("path"), location: relativePathSchema }),
+  zod.z.strictObject({ type: zod.z.literal("url"), location: nonEmptyStringSchema }),
+  zod.z.strictObject({ type: zod.z.literal("artifact"), location: nonEmptyStringSchema })
+]);
 var hookDependencySchema2 = zod.z.strictObject({
   name: nonEmptyStringSchema,
   version: nonEmptyStringSchema,
@@ -2242,7 +2247,7 @@ var customCodeConfigSchema2 = zod.z.strictObject({
   protectedFiles: zod.z.array(nonEmptyStringSchema).optional()
 });
 var workflowConfigSchema2 = zod.z.strictObject({
-  path: nonEmptyStringSchema,
+  path: relativePathSchema,
   outputName: nonEmptyStringSchema.optional()
 });
 var analyticsHeaderSchema2 = zod.z.union([
@@ -2348,7 +2353,7 @@ var generationConfigSchema = zod.z.strictObject({
   hooks: hooksConfigSchema2.optional(),
   customCode: customCodeConfigSchema2.optional(),
   workflows: zod.z.array(workflowConfigSchema2).optional(),
-  customQueryPaths: zod.z.array(nonEmptyStringSchema).optional(),
+  customQueryPaths: zod.z.array(relativePathSchema).optional(),
   analytics: analyticsConfigSchema2.optional(),
   wireTests: wireTestsSchema2.optional(),
   unitTests: unitTestsSchema2.optional(),
@@ -2708,6 +2713,7 @@ exports.publishRegistrySchema = publishRegistrySchema;
 exports.pythonGenerationConfigSchema = pythonGenerationConfigSchema;
 exports.readmeCustomSectionSchema = readmeCustomSectionSchema;
 exports.readmeEndpointSchema = readmeEndpointSchema;
+exports.relativePathSchema = relativePathSchema;
 exports.rubyGenerationConfigSchema = rubyGenerationConfigSchema;
 exports.rustGenerationConfigSchema = rustGenerationConfigSchema;
 exports.sdkConfigIrV1Schema = sdkConfigIrV1Schema;
@@ -2736,6 +2742,7 @@ exports.sdkConfigV1PublishRegistrySchema = sdkConfigV1PublishRegistrySchema;
 exports.sdkConfigV1PythonGenerationConfigSchema = pythonGenerationConfigSchema;
 exports.sdkConfigV1ReadmeCustomSectionSchema = sdkConfigV1ReadmeCustomSectionSchema;
 exports.sdkConfigV1ReadmeEndpointSchema = sdkConfigV1ReadmeEndpointSchema;
+exports.sdkConfigV1RelativePathSchema = relativePathSchema;
 exports.sdkConfigV1RubyGenerationConfigSchema = rubyGenerationConfigSchema;
 exports.sdkConfigV1RustGenerationConfigSchema = rustGenerationConfigSchema;
 exports.sdkConfigV1Schema = sdkConfigV1Schema;