Migration guide

Halyard SDK v3 → v4

3.8.2 → 4.1.0

Three breaking changes, one codemod, about twenty minutes. No coordinated deploy: v3 and v4 clients can talk to the API at the same time.

Deadline

v3 stops receiving security fixes on 1 December 2026 — 88 days away.

Applies to
JS / TS SDK
Effort
~20 min
Breaking
3 changes
Rollback
Safe, any time

What breaks, and what to write instead

1 · The client takes an options object

A bare API-key string is no longer accepted, and the export is now named.

Before · v3

import Halyard from "halyard";
const hal = new Halyard(
  process.env.HALYARD_API_KEY
);

After · v4

import { Halyard } from "halyard";
const hal = new Halyard({
  token: process.env.HALYARD_TOKEN,
});

2 · List calls return a page, not an array

Every list* method returns { data, cursor }. Iterate the client when you want all of it — it pages for you.

Before · v3

const runs = await hal.listRuns();
runs.map(r => r.id);
// silently capped at 100

After · v4

const page = await hal.listRuns();
page.data.map(r => r.id);
for await (const r of hal.runs) {}

3 · Three renames, no other behaviour change

The codemod does all three; they are listed so you can grep for them yourself.

− v3  /  + v4

  • err.code === 429err.type === "rate_limited"
  • hal.close()await hal.dispose()
  • HALYARD_API_KEYHALYARD_TOKEN

Do it in three steps

  1. Upgrade the dependency

    $ npm install halyard@^4.1.0

  2. Run the codemod

    It rewrites constructors, renames and err.code comparisons. Where it is not sure it leaves a TODO(halyard) — grep -rn "TODO(halyard)" src/ to find them. Pagination is the one only you can decide.

    $ npx halyard-codemod v3-to-v4 src/ 42 files scanned 17 files changed 3 need a human · see TODO(halyard)

  3. Verify before you deploy

    Strict mode turns every remaining v3 shape into a thrown error instead of a warning, so the test run tells you the truth.

    $ HALYARD_STRICT=1 npm test ✓ 184 passing ✓ 0 deprecation warnings

If it goes wrong

Two errors account for almost every report. Rolling back is reinstalling halyard@3.8.2 and reverting the codemod commit.

TypeError: runs.map is not a function

A list call you did not update. Use page.data, or iterate hal.runs if you actually wanted every row.

HalyardError: missing_token

The process still exports HALYARD_API_KEY. Rename it in your deployment config — v4 does not read the old name, on purpose.

The dates that matter