@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 initwrites 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.mdfor Claude Code. See Project setup for AI coding assistants.- The package exports
WayPointBegin,WayPointStop,WayPointBreak, andWayPointEndby name. You no longer needNonNullable<Tour["wayPoints"]>[number]. See Solution fields.
- The descriptions of the types follow the API reference.
sharedCapacitiesnow says what it really changes: how the engine treats apickupwith a negative quantity.Warningsays thatproperties.pathis 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.NewKardinal.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 thatsubmit()takes. You don’t copyid,agencyId, orversion. See Replacing a plan from your own data.
submit(),update(), andreplace()pass each kind of API warning toonWarning, with an emptyfieldslist. By default,onWarningisconsole.warn, so you see these lines with no setup. To silence them, passonWarning: () => {}. To keep the typo warnings ofupdate(), keep only the calls whosefieldslist isn’t empty. A program should keep readingplan.warnings. See Warnings on successful calls.- If your
onWarninghandler fails on an API warning, the SDK writes the failure withconsole.error. The call still returns the plan. - The skill that
kardinal initwrites points to the Integration paths page first.
solutions.wait()right afterplans.start()now waits for the new run. Before, you could restart a plan that was still optimizing, andwait()returned after 10 seconds. It returned the previous run’s solution, withfinalStateset tointerrupted.
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
workingDurationof 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 initwrites 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()andexamples.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: 0on each resource of a plan you submit. - A last-in-first-out constraint (
AdditionalConstraintRemovalStrategy) and its violation (RemovalStrategyViolation) name the unloading orderstrategy, as the API reads and returns it. Writestrategy: "lifo"instead ofremovalStrategy: "lifo", which the API ignored, and readviolation.strategyinstead ofviolation.removalStrategyType, which was alwaysundefined.
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
403error now throws a class that matches its cause. A revoked or regenerated key throwsKardinalAuthError, with.statusset to403. An archived plan that you update, stop, or restart withoutforcethrowsKardinalValidationError, with no field path in.errors. A403stays aKardinalLimitErroronly when it carries a clue of a limit: plan size, quota, or credits. Any other403throws a new public class,KardinalForbiddenError. -
Code that catches
KardinalLimitErrorto handle a revoked key or an archived plan no longer catches them. CatchKardinalAuthErrororKardinalValidationErrorinstead. This code works in 1.0.x and in 1.1.0: -
height,width, andlengthof atruckprofile are whole centimetres. A decimal value such as4.2is refused before sending.submit(),parsePlanCreate(), andparsePlan()throw aZodErrorwith the messageExpected a whole number of centimetres (4.2 m is 420). The commandskardinal routing plans submit,update, andvalidateprint the same message and exit with an error. Theplans.update()method doesn’t run these checks, so the API refuses a decimal there with a400. -
Round after converting from metres, with
Math.round(widthM * 100), because2.55 * 100is254.99999999999997in 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. -
disableGroupProximityis now required in amaximizePrecedencesobjective of thePlantype. Code that builds such an objective by hand beforeupdate()can stop compiling, so add the field. -
In a plan read from the API,
maximumof amaxCumulatedCostconstraint is typednumber, no longernumber | undefined. The generated typeGlobalConstraintMaxCumulatedCostrequires it. The SDK doesn’t checkglobalConstraintsbefore sending, so a constraint withoutmaximumstill reaches the API, which refuses it with a400, as with 1.0.1. -
SolutionObjective.nameloses its identifier pattern.
- The descriptions of the types follow the current API specification.
- The npm
homepagelink, the README, and the.kardinal/SKILL.mdfile written bykardinal initpoint to the SDK pages. The README links to this changelog.
- The options of
vehicleProfile, such aswithTrafficorgrossWeight, are no longer refused as unknown fields bysubmit,update,parsePlanCreate, andkardinal routing plans validate. Each profile is checked against the options of its owntype, so a misspelled option is still reported. - If you named these options in
allowUnknownto work around the issue in 1.0.0, you can remove them.
- Client for every endpoint of the Route Optimization API:
plans.submit,get,update,delete,list,iterAll,start,stop,getStatus, andsolutions.get,getObjectives,wait. - Types generated from the API specification, with the API’s field names and descriptions, and run-time validation of plans with
zodbefore sending. - Misspelled keys refused before sending (
UnknownFieldError), with the closest real field name;allowUnknownto 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; any403thrown asKardinalLimitError. - Automatic retries of reads,
update,delete,start, andstop;submitis never retried. - Optional
kardinalcommand-line tool (installcommanderalongside the package), with local plan validation. - ES module, for Node.js 22 or later.

