> ## Documentation Index
> Fetch the complete documentation index at: https://developers.kardinal.ai/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> If you're integrating Kardinal into an application with an SDK, start with Integration paths: https://developers.kardinal.ai/getting-started/integration-paths.md. It lists the sections to read, in order. If you follow Integration paths, you don't need llms-full.txt or openapi.yaml. Each step links the section you need.

# TypeScript SDK changelog

> Version history of the Kardinal TypeScript SDK (@kardinal-ai/sdk on npm): what each release adds or changes, and the Route Optimization API version it targets.

Releases of [`@kardinal-ai/sdk`](https://www.npmjs.com/package/@kardinal-ai/sdk). For changes to the API itself, see the [API changelog](https://developers.kardinal.ai/reference/changelog.md).

**1.3.0**

Released on 2026-11-16. kardinal init also writes the skill for OpenAI Codex and Mistral Vibe, and the waypoint types are exported by name

This release doesn't change the code you write.

**New**

* `kardinal init` writes the same skill to `.agents/skills/kardinal-typescript/SKILL.md`, where OpenAI Codex and Mistral Vibe load it. It still writes `.claude/skills/kardinal-typescript/SKILL.md` for Claude Code. See [Project setup for AI coding assistants](https://developers.kardinal.ai/sdks/cli.md#project-setup-for-ai-coding-assistants).
* The package exports `WayPointBegin`, `WayPointStop`, `WayPointBreak`, and `WayPointEnd` by name. You no longer need `NonNullable<Tour["wayPoints"]>[number]`. See [Solution fields](https://developers.kardinal.ai/sdks/typescript/reference.md#solution-fields).

**Changes**

* The descriptions of the types follow the API reference. `sharedCapacities` now says what it really changes: how the engine treats a `pickup` with a negative quantity. `Warning` says that `properties.path` is stable.

**1.2.0**

Released on 2026-11-04. whoami() and plans.replace(), API warnings passed to onWarning, and wait() right after start()

This release doesn't change the code you write. Your program now shows the API's warnings with `console.warn`: the second section says how to silence them.

**New**

* `Kardinal.whoami()` returns the host and the agency of your API key. Call it when your application starts, to check that the key belongs to the agency you expect. See [Checking the key at startup](https://developers.kardinal.ai/sdks/configuration.md#checking-the-key-at-startup).
* `plans.replace(planId, plan)` updates a plan from a new plan input, the input that `submit()` takes. You don't copy `id`, `agencyId`, or `version`. See [Replacing a plan from your own data](https://developers.kardinal.ai/sdks/plan-lifecycle.md#replacing-a-plan-from-your-own-data).

**Changes**

* `submit()`, `update()`, and `replace()` pass each kind of API warning to `onWarning`, with an empty `fields` list. By default, `onWarning` is `console.warn`, so you see these lines with no setup. To silence them, pass `onWarning: () => {}`. To keep the typo warnings of `update()`, keep only the calls whose `fields` list isn't empty. A program should keep reading `plan.warnings`. See [Warnings on successful calls](https://developers.kardinal.ai/sdks/errors-and-warnings.md#warnings-on-successful-calls).
* If your `onWarning` handler fails on an API warning, the SDK writes the failure with `console.error`. The call still returns the plan.
* The skill that `kardinal init` writes points to the [Integration paths](https://developers.kardinal.ai/getting-started/integration-paths.md) page first.

**Fixes**

* `solutions.wait()` right after `plans.start()` now waits for the new run. Before, you could restart a plan that was still optimizing, and `wait()` returned after 10 seconds. It returned the previous run's solution, with `finalState` set to `interrupted`.

**1.1.1**

Released on 2026-11-04. kardinal init writes a Claude Code skill, two case-study plans, and the LIFO order is read from strategy

This release doesn't change the code you write, except code that read a field the API never sent (see the last item). You can upgrade with `npm install @kardinal-ai/sdk@latest`.

* The descriptions of the types follow the current API specification, for example the `workingDuration` of a tour, breaks, time windows, and the rest between the days of a multi-day shift. This release targets API 1.0.2.
* The TypeScript examples of the SDK pages and the guides are compiled and run against a mocked API before each release.
* `kardinal init` writes a skill that Claude Code loads, `.claude/skills/kardinal-typescript/SKILL.md`, instead of `.kardinal/SKILL.md`. It lists the pitfalls of an integration and links to the docs. Run it again at the root of your repository, and delete the old `.kardinal/SKILL.md`.
* `examples.coldChainPlan()` and `examples.parcelExpressPlan()` return the plans of the [cold-chain](https://developers.kardinal.ai/case-studies/cold-chain-last-mile.md) and [parcel express](https://developers.kardinal.ai/case-studies/parcel-express.md) case studies, as typed objects to adapt to your data.
* You no longer need to write `priority: 0` on each resource of a plan you submit.
* A last-in-first-out constraint (`AdditionalConstraintRemovalStrategy`) and its violation (`RemovalStrategyViolation`) name the unloading order `strategy`, as the API reads and returns it. Write `strategy: "lifo"` instead of `removalStrategy: "lifo"`, which the API ignored, and read `violation.strategy` instead of `violation.removalStrategyType`, which was always `undefined`.

**1.1.0**

Released on 2026-10-23. Each 403 error gets its own class and truck dimensions are whole centimetres

This release changes behaviour in ways that can break existing code, so read the first section before you upgrade. To stay on 1.0.x until you're ready, run `npm install @kardinal-ai/sdk@~1.0.1`.

**Changes that can affect your code**

* A `403` error now throws a class that matches its cause. A revoked or regenerated key throws `KardinalAuthError`, with `.status` set to `403`. An archived plan that you update, stop, or restart without `force` throws `KardinalValidationError`, with no field path in `.errors`. A `403` stays a `KardinalLimitError` only when it carries a clue of a limit: plan size, quota, or credits. Any other `403` throws a new public class, `KardinalForbiddenError`.

* Code that catches `KardinalLimitError` to handle a revoked key or an archived plan no longer catches them. Catch `KardinalAuthError` or `KardinalValidationError` instead. This code works in 1.0.x and in 1.1.0:

  ```typescript theme={null}
  try {
    await k.routing.plans.update(plan);
  } catch (e) {
    if (e instanceof KardinalError && e.status === 403) {
      // read e.details and e.errors to tell the cases apart
    } else {
      throw e;
    }
  }
  ```

* `height`, `width`, and `length` of a `truck` profile are whole centimetres. A decimal value such as `4.2` is refused before sending. `submit()`, `parsePlanCreate()`, and `parsePlan()` throw a `ZodError` with the message `Expected a whole number of centimetres (4.2 m is 420)`. The commands `kardinal routing plans submit`, `update`, and `validate` print the same message and exit with an error. The `plans.update()` method doesn't run these checks, so the API refuses a decimal there with a `400`.

* Round after converting from metres, with `Math.round(widthM * 100)`, because `2.55 * 100` is `254.99999999999997` in JavaScript.

* If you set these dimensions with 1.0.x, check the values. A whole number in metres, such as `length: 12`, is read as 12 centimetres with no error.

* `disableGroupProximity` is now required in a `maximizePrecedences` objective of the `Plan` type. Code that builds such an objective by hand before `update()` can stop compiling, so add the field.

* In a plan read from the API, `maximum` of a `maxCumulatedCost` constraint is typed `number`, no longer `number | undefined`. The generated type `GlobalConstraintMaxCumulatedCost` requires it. The SDK doesn't check `globalConstraints` before sending, so a constraint without `maximum` still reaches the API, which refuses it with a `400`, as with 1.0.1.

* `SolutionObjective.name` loses its identifier pattern.

**Other changes**

* The descriptions of the types follow the current API specification.
* The npm `homepage` link, the README, and the `.kardinal/SKILL.md` file written by `kardinal init` point to the SDK pages. The README links to this changelog.

**1.0.1**

Released on 2026-10-12. Fix: vehicle profile options accepted

* The options of `vehicleProfile`, such as `withTraffic` or `grossWeight`, are no longer refused as unknown fields by `submit`, `update`, `parsePlanCreate`, and `kardinal routing plans validate`. Each profile is checked against the options of its own `type`, so a misspelled option is still reported.
* If you named these options in `allowUnknown` to work around the issue in 1.0.0, you can remove them.

**1.0.0**

Released on 2026-10-12. First public release, targeting API 1.0.1

* Client for every endpoint of the Route Optimization API: `plans.submit`, `get`, `update`, `delete`, `list`, `iterAll`, `start`, `stop`, `getStatus`, and `solutions.get`, `getObjectives`, `wait`.
* Types generated from the API specification, with the API's field names and descriptions, and run-time validation of plans with `zod` before sending.
* Misspelled keys refused before sending (`UnknownFieldError`), with the closest real field name; `allowUnknown` to send a field the SDK doesn't know yet.
* `solutions.wait`, which follows a plan's optimization and resolves with its solution once it's over.
* Typed errors for every API error, with `.errors`, `.details`, and `.retryable`; any `403` thrown as `KardinalLimitError`.
* Automatic retries of reads, `update`, `delete`, `start`, and `stop`; `submit` is never retried.
* Optional `kardinal` command-line tool (install `commander` alongside the package), with local plan validation.
* ES module, for Node.js 22 or later.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.