Review Spec Update

Step 3 — Check for parameter-order regressions

pnpm <pkg> generate
pnpm <pkg> run apply-patches

Then for every function where positional parameters reordered:

1. Check if a patch already exists:

   ls packages/<pkg>/patches/

2. Patch exists → leave it alone unless pnpm <pkg> run apply-patches reported that patch file as failing. If it failed, the context lines around the reorder changed (e.g. new parameters added nearby). Update the patch context to match the new generated output (see §Updating a patch below). Do NOT delete a parameter-order patch just because the working tree already looks correct.
3. No patch exists → create one (see §Creating a patch below).
4. Patch is truly obsolete → delete it only if the function no longer has both headerParameters and queryParameters (i.e., one was removed from the spec), making the ordering moot.

Detecting parameter-order changes

The generated functions follow this shape:

functionName: (
  param1: Type1,
  param2: Type2,
  ...
) => new OpenApiRequestBuilder(...)

<!-- vale SAP.Sentences = NO -->

If the spec reordered headerParameters vs queryParameters, the generator will flip their positions.

<!-- vale SAP.Sentences = YES -->

Creating a patch

# 1. Manually edit the generated file to restore the old parameter order
#    (swap back to the order consumers expect)
# 2. Stage only that file
git add packages/<pkg>/src/client/api/<api-file>.ts
# 3. Generate the patch against HEAD (which has the newly-generated code)
git diff --cached > packages/<pkg>/patches/backward-compat-<function-name>-order.patch
# 4. Unstage (the patch is the artifact, not the edit)
git restore --staged packages/<pkg>/src/client/api/<api-file>.ts
git restore packages/<pkg>/src/client/api/<api-file>.ts

Patch file naming: backward-compat-<camelFunctionName>-order.patch

Updating a patch

If the patch context no longer matches (function body changed around the reorder):

# Inspect what changed
git diff main...HEAD -- packages/<pkg>/src/client/api/<api-file>.ts
# Open the patch file, update the context lines (the unchanged lines around the @@)
# to match the new generated code, keeping the - / + lines intact
# Then verify:
pnpm <pkg> generate
pnpm <pkg> run apply-patches

Step 4 — Maintain apply-patches support

If you deleted a patch in Step 3 because it was truly obsolete, remove the patches directory if now empty and remove the apply-patches script from package.json.

Check whether the package has an apply-patches script:

cat packages/<pkg>/package.json | grep apply-patches

If missing, add it. Add this to package.json scripts:

"apply-patches": "tsx ../../scripts/apply-patches.ts ."

Also verify the root package.json runs apply-patches across the repository:

grep apply-patches package.json
# Should have: "apply-patches": "pnpm -r run --if-present apply-patches"

Step 5 — Write [compat] changesets

For each breaking change, run pnpm changeset --empty once, then edit the generated file.

Format

---
'@sap-ai-sdk/<package-name>': minor
---

[compat] <TypeName(s)>: <what changed and what consumers need to do>.

Use minor for all [compat] entries (breaking changes in this project always bump minor).

Examples from this repository

Type narrowed:

[compat] `DocumentKeyValueListPair`, `RetrievalDocumentKeyValueListPair`, `VectorDocumentKeyValueListPair`: the `matchMode` property type was narrowed from an open union (`'ANY' | 'ALL' | any`) to the strict `FilterMatchModeEnum` (`'ANY' | 'ALL'`).

Field removed from response:

[compat] `CollectionPendingResponse`: fields `Location` and `status` were removed.
A new `monitorURL` property was added instead.

Required field added to request type:

[compat] `TextOnlyBaseChunk`: new required field `id: string` added and `metadata` is now optional.

Field type changed:

[compat] `BaseDocument` / `DocumentInput`: `chunks` type changed from `TextOnlyBaseChunk[]` to `TextOnlyBaseChunkCreate[]`.
The `metadata` property is now optional.

Optional became required:

[compat] `PromptTemplateSubstitutionRequest` now requires the `inputParams` property.

What does not need a [compat] changeset

• New optional fields on response types
• New enum members added
• Type widened (e.g., 'a'|'b' → 'a'|'b'|'c')
• New optional parameters on functions
• Fields on response types becoming optional

These get rolled into the [feat] changeset that should already exist for the spec update.

If no [feat] changeset exists yet for this spec update, create one with pnpm changeset --empty. Label it [feat] <package-name>: updated generated client to latest spec before rolling in non-breaking changes.

Step 6 — Verify

# Recreate raw generated output, then verify the shared patch runner succeeds
pnpm <pkg> generate
pnpm <pkg> run apply-patches

# TypeScript compiles
pnpm <pkg> compile

# Tests pass
pnpm <pkg> test

# List changesets created
ls .changeset/

If pnpm <pkg> run apply-patches fails, return to Step 3 §Updating a patch for each failing patch file. Do not proceed to compile or test until all patches apply cleanly. List each failing patch file by name in your output.

If compilation fails, inspect the error output to determine whether the failure is caused by a breaking change not yet covered by a [compat] changeset or patch. If so, return to Step 2 or Step 3. If the failure is unrelated to this spec update, note it as a pre-existing issue and do not block the review. If tests fail, apply the same triage: attribute failures to this spec update or flag them as pre-existing.

Quick checklist

• Diffed src/client/ against main
• Every breaking request-side change has a [compat] changeset
• Every breaking response-side removal/rename/narrowing has a [compat] changeset
• additionalProperties: false added to any request object → [compat] changeset created
• Schema splits checked: exported old names → [compat]; unexported without structural change → no action needed
• Every deprecated type or field has a [compat] changeset with migration target
• Under-specified response changes ({} bodies) confirmed as non-breaking and omitted from [compat]
• Parameter-order regressions have patches (new or updated)
• All patches apply cleanly (pnpm <pkg> apply-patches from fresh generated output)
• Package has apply-patches script (added if missing)
• TypeScript compiles, tests pass