Skip to main content
Releases of @kardinal-ai/sdk. For changes to the API itself, see the API changelog.
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.
  • The package exports WayPointBegin, WayPointStop, WayPointBreak, and WayPointEnd by name. You no longer need NonNullable<Tour["wayPoints"]>[number]. See 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.
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.
  • 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.
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.
  • 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 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.
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 and parcel express 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.
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:
  • 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.
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.
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.