update-sdk

name

update-sdk

description

Update the @relewise/client SDK from the main Relewise Swagger source with a strict git and PR flow. Use when asked to regenerate SDK models/types, refresh client contracts from Swagger, or prepare an SDK-update PR. Require a Trello card URL, run clean-main preflight checks, create a timestamped chore branch, regenerate from the main Swagger URL, validate build/types/tests, and prepare a PR with Trello URL as the first line.

Update SDK

Goal

Regenerate @relewise/client models and declaration types from the main Swagger source and deliver a validated PR to main.

Required Input

Require a Trello card URL before running SDK update work.

If the prompt does not include a Trello URL, ask for it first and do not continue until provided.

Preflight Git Safety

Run commands from repository root.

1. Require a strict clean worktree:

git status --porcelain

Abort when any output exists.

2. Ensure origin exists:

git remote get-url origin

Abort on failure.

3. Fetch refs:

git fetch origin --prune

Abort on failure.

4. Switch to main:

git switch main

Abort if switch is not safe.

5. Fast-forward local main:

git pull --ff-only origin main

Abort if not fast-forward or if pull fails.

Do not continue when any preflight step fails.

Branch Creation

Use a timestamped branch (date + hour + minute):

$stamp = Get-Date -Format 'yyyyMMdd-HHmm'
$branchName = "chore/update-sdk-$stamp"

Abort if branch exists locally or remotely:

git show-ref --verify --quiet "refs/heads/$branchName"
git ls-remote --exit-code --heads origin $branchName

Create and switch:

git switch -c $branchName

SDK Regeneration (Main Swagger Source)

Run commands from repository root using package-prefixed commands:

1. Install dependencies:

npm --prefix .\packages\client ci

2. Regenerate API models/types from the main Swagger URL:

npm --prefix .\packages\client run gen-api

gen-api must use:

https://api.relewise.com/public/swagger.json

through packages/client/package.json.

Notes:

• Do not use gen-api-dev for normal SDK updates.
• gen-api also runs fix-exports.js, which patches src/models/data-contracts.ts to export UtilRequiredKeys.

Expected Changes Check

Before validation, inspect changed files and ensure updates are coherent.

Expected change locations:

• packages/client/src/models/* generated by swagger-typescript-api
• packages/client/src/models/data-contracts.ts export patch effect from fix-exports.js
• lockfile/package metadata changes only when intentionally caused by install/update work

If unrelated files changed unexpectedly, stop and investigate before proceeding.

Validation (Required)

Run validation in packages/client and treat failures as blocking unless the user explicitly accepts known failures.

1. Build:

npm --prefix .\packages\client run build

2. Build declaration types:

npm --prefix .\packages\client run build:types

3. Unit tests:

npm --prefix .\packages\client test

4. Optional integration tests (when secrets are available or explicitly requested):

npm --prefix .\packages\client run integration-test --DATASET_ID=... --API_KEY=... --SERVER_URL=https://api.relewise.com

If secrets are unavailable, report integration tests as not run.

Acceptance Criteria

Treat the SDK update as successful only when:

• npm run gen-api succeeds using the main Swagger URL
• npm --prefix .\packages\client run build succeeds
• npm --prefix .\packages\client run build:types succeeds
• npm --prefix .\packages\client test succeeds
• changed files are expected and reviewable

Commit, Push, and Pull Request

1. Commit SDK update changes on the update branch.
2. Push branch:

git push -u origin $branchName

3. Create PR to main.

Preferred automated flow with GitHub CLI:

$prBodyPath = ".\\update-sdk-pr-body.md"
$prBodyTemplate = @'
__TRELLO_CARD_URL__

## Summary
- Regenerated `@relewise/client` from main Swagger URL
- <key model/type changes>

## Validation
- `npm run gen-api`: <result>
- `npm --prefix .\packages\client run build`: <result>
- `npm --prefix .\packages\client run build:types`: <result>
- `npm --prefix .\packages\client test`: <result>
- `npm --prefix .\packages\client run integration-test`: <result or not run>

## Notes
- <known issues or limitations>
'@
$prBody = $prBodyTemplate -replace '__TRELLO_CARD_URL__', $TrelloCardUrl
Set-Content -Path $prBodyPath -Value $prBody -Encoding utf8

$prUrl = gh pr create --base main --head $branchName --title "chore(client): update sdk from swagger ($stamp)" --body-file $prBodyPath
if ($LASTEXITCODE -ne 0) { throw 'gh pr create failed.' }
Write-Host "PR URL: $prUrl"

Manual fallback:

git push -u origin $branchName
Write-Host "Create PR: https://github.com/Relewise/relewise-sdk-javascript/compare/main...$branchName?expand=1"
Write-Host "PR title: chore(client): update sdk from swagger ($stamp)"
Write-Host "PR body file: $prBodyPath"

Keep the Trello URL as the first line in PR description. Write the PR body file as UTF-8 to avoid symbol corruption in GitHub-rendered text.

Output Expectations

Provide a final summary with:

• Trello URL used
• branch name
• changed file groups
• key generated model/type updates
• results for each validation command
• pushed branch URL
• PR URL, or exact manual fallback instructions when automated PR creation is unavailable