Review an API update
Carry a custom CLI workflow through an API addition, an edit conflict, and a breaking client change.
A linked repository Delivery carries API updates into the package your customers use. This walkthrough changes the fictional Parcel API, preserves a custom shipping-label command, resolves an overlapping edit, and repairs a breaking client change before accepting a Release.
You control the source changes and destination merges. A successful Generation produces files; a ready Draft has passed its required checks. Merging that checked Draft creates a Release. Publishing to a registry is a separate step.
Prepare a linked SDK
You need Node.js 22 or later, npm, Git, curl, jq, a Typeship API key, and write access to two GitHub repositories. Install the Typeship GitHub App on both. Use repositories where you can review and merge the example changes.
- Download the Parcel lifecycle Spec as
openapi.jsonin your source repository and commit it. The three-operation API is fictional; its server is not a live shipping service. - Link the repository to a Project. Select a TypeScript SDK Target and configure its repository Delivery to the destination repository's
sdkdirectory. Leave Publish after merge disabled for this walkthrough. - Generate the initial package, select Draft version
1.0.0, and merge it after release readiness and combined-package checks pass. Confirm1.0.0appears in the Target's Release history. - Require
Typeship Releaseand the Target's combined-package check in the destination's branch rules. Without required checks, GitHub can allow a failing Draft to merge.
Set the Project and Target IDs from the Console. The API key below belongs to Typeship; the workflow's local mock uses separate example credentials.
export TYPESHIP_PROJECT="prj_..."
export TYPESHIP_TARGET="tgt_..."
export TYPESHIP_TOKEN="<your-Typeship-API-key>"
typeship_api() {
local request_path="$1"
shift
curl --fail-with-body -sS \
-H "Authorization: Bearer $TYPESHIP_TOKEN" \
-H "Content-Type: application/json" \
"https://typeship.dev/api/v1$request_path" "$@"
}Use separate checkouts for the source repository and the destination Draft. Run Spec edits below in the source checkout; run package edits in the Draft's sdk directory.
Add a field and a custom command
Add an optional carrier field to Label:
node --input-type=module <<'JS'
import { readFileSync, writeFileSync } from "node:fs";
const spec = JSON.parse(readFileSync("openapi.json", "utf8"));
spec.components.schemas.Label.properties.carrier = { type: "string" };
writeFileSync("openapi.json", JSON.stringify(spec, null, 2) + "\n");
JSCommit and review the source change, then merge it. Automatic generation can deliver the update, or request it explicitly:
typeship_api "/projects/$TYPESHIP_PROJECT/generate" -X POST
TYPESHIP_DRAFT=$(typeship_api "/targets/$TYPESHIP_TARGET" | jq -r .draft_id)
typeship_api "/drafts/$TYPESHIP_DRAFT" > draft.json
jq '{status, version_next, version, compatibility, errors, head_sha, pull_request}' draft.jsonOpen the returned pull_request.url and check out that Draft. Expect the additive update to propose 1.1.0. In its sdk directory, add the four customer-authored files and executable registration from Add a custom workflow. Use the linked package already on this Draft; skip that guide's initial one-shot generation command.
Also change the comment Read the label status. in src/resources/labels.ts to Read the label status for our operations team. Leave the method implementation intact. This customization gives the later documentation update an overlap to resolve.
Build and run the workflow's twelve local-mock tests, then commit its files, package.json, and the edited resource to the Draft. Add a customer package check named parcel-label-workflow with command npm run test:workflow, preserving existing generated, customer, and repository checks.
Typeship regenerates after the check configuration changes. Retrieve the Draft again and use its latest URL and head. Check-configuration changes can replace the Draft review; customer commits remain in the branch's ancestry.
typeship_api "/drafts/$TYPESHIP_DRAFT"
typeship_api "/drafts/$TYPESHIP_DRAFT/files?filter=customized"Confirm that the package contains carrier?: string, the custom workflow files, the edited comment, and the parcel-label executable. Its checks must pass on the current head_sha. Merge the checked Draft and confirm Release 1.1.0 before continuing. The merged Draft is final, and the Target's draft_id now names the next Draft.
Resolve an overlapping edit
Change the source operation's description:
node --input-type=module <<'JS'
import { readFileSync, writeFileSync } from "node:fs";
const spec = JSON.parse(readFileSync("openapi.json", "utf8"));
spec.paths["/labels/{label_id}"].get.description = "Read the latest label state.";
writeFileSync("openapi.json", JSON.stringify(spec, null, 2) + "\n");
JSReview and merge the source edit, generate again, then inspect conflicts:
typeship_api "/projects/$TYPESHIP_PROJECT/generate" -X POST
TYPESHIP_DRAFT=$(typeship_api "/targets/$TYPESHIP_TARGET" | jq -r .draft_id)
typeship_api "/drafts/$TYPESHIP_DRAFT" > draft.json
typeship_api "/drafts/$TYPESHIP_DRAFT/files?filter=conflicted" > conflicts.json
jq '{status, conflicts, head_sha}' draft.json
jq '.data[] | {path, conflict, sides}' conflicts.jsonExpect Draft status: action_required, reason: conflict and a conflict in src/resources/labels.ts with source: generation. Both your accepted comment and the newly generated comment changed the same text. Current stays at 1.1.0; successful generation alone does not authorize a Release.
Read the base, yours, and generated sides of the file as text by their file IDs, for example typeship_api "/files/$(jq -r '.data[0].sides.generated' conflicts.json)". For this example, accept its new description and discard the older custom comment in that resource. This selects the whole generated file, so inspect all its changes first:
jq '{resolutions: [{path: "src/resources/labels.ts", keep: "generated"}],
expected_head_sha: .head_sha}' draft.json > resolution.json
typeship_api "/drafts/$TYPESHIP_DRAFT/resolve" \
-X POST --data-binary @resolution.jsonThe resolve response is the Draft with every conflict decided, and Typeship continues it while its status is working. A 409 resource_changed means the Draft changed since inspection. Retrieve the Draft and its conflicts again and review them before choosing. To combine both versions, submit the final file content through the same resolve endpoint; see conflict resolution.
The workflow files remain present and checks run again. Once readiness passes for the resolved head, expect a documentation-only 1.1.1 update. Merge it and confirm the new Release.
Repair a breaking client change
Rename the label-read operation while retaining its HTTP path:
node --input-type=module <<'JS'
import { readFileSync, writeFileSync } from "node:fs";
const spec = JSON.parse(readFileSync("openapi.json", "utf8"));
spec.paths["/labels/{label_id}"].get.operationId = "retrieveLabel";
writeFileSync("openapi.json", JSON.stringify(spec, null, 2) + "\n");
JSReview the source report before merging this intentional interface change. Generate the destination update and inspect its Draft and customized files again. The generated client now has client.labels.retrieve() in place of client.labels.get(). The preserved workflow still calls get, so its build fails and readiness stays red. Current remains 1.1.1.
Expect a major version proposal of 2.0.0. A compatible HTTP path does not make a renamed client method compatible for callers. Selecting 1.1.2 cannot waive the required major version and returns 422.
On the destination Draft, replace both client.labels.get( calls in src/label-workflow.ts with client.labels.retrieve(. Rebuild and run npm run test:workflow, then commit the fix. Regenerate if needed to refresh the Draft. All twelve workflow behaviors should pass against the unchanged local mock.
Retrieve the latest Draft before merging. Confirm its version is 2.0.0 and every required check belongs to that head_sha. Merge it only after readiness passes.
Verify the accepted package
typeship_api "/targets/$TYPESHIP_TARGET/releases" > releases.json
jq '.data[] | {id, version, generation_id, spec_revision_id,
commit_sha, checks}' releases.jsonThe completed sequence has Releases 1.0.0, 1.1.0, 1.1.1, and 2.0.0. The conflicted Draft and failed build create no intermediate Release. Match the final commit_sha to the destination merge and inspect that commit's workflow and executable registration. Release checks retain the checked Draft head; commit_sha records the accepted merge commit.
Registry publishing is separate from accepting these repository Releases. When you are ready to distribute the package, configure publishing and verify the publishing status for the accepted Release.
Follow the latest Draft URL and head after every generation, configuration update, or conflict choice. Send the Draft ETag in If-Match for version selection and head_sha as expected_head_sha for conflict choices. Branch on the Draft status for the next step. Require current package checks and inspect Release history after the authorized merge. Source preservation, successful generation, Release acceptance, and registry publishing prove different outcomes.