@ic-reactor/mcp 0.0.0-stage → 0.0.0

package/packages/core/src/units.ts

@@ -0,0 +1,299 @@
+/**
+ * Exact conversions between a token's base units (e8s, satoshis, wei) and the
+ * decimal text a person reads and types.
+ *
+ * A ledger counts in base units as a `nat`, which a generated module returns
+ * as a `bigint`. Going through `Number` loses digits:
+ * `Math.floor(Number("0.29") * 10 ** 8)` is `28999999`, so a transfer of 0.29
+ * sends 0.28999999, and at 18 decimals `1.1` becomes `1100000000000000128`.
+ * These helpers work on the digits instead, so every amount a ledger can hold
+ * converts exactly in both directions, and what cannot be represented is
+ * refused rather than rounded: a transfer never sends something other than
+ * what was typed.
+ */
+
+import { checkBoolean, checkKeys } from "./network.js"
+
+/** The most decimals, and fraction digits, accepted: `icrc1_decimals` is a `nat8`. */
+const MAX_DIGITS = 255
+
+/** The most characters of a refused value an error message quotes. */
+const MAX_SHOWN = 40
+
+/**
+ * How a value is quoted in an error message. A form may show the message, and
+ * what was typed or pasted can be any length, so a long value is cut.
+ */
+const show = (value: unknown): string => {
+  const text =
+    typeof value === "string"
+      ? JSON.stringify(value)
+      : typeof value === "bigint"
+        ? `${value}n`
+        : String(value)
+  return text.length > MAX_SHOWN ? `${text.slice(0, MAX_SHOWN)}…` : text
+}
+
+/**
+ * `digits` without the zeros at its end. A loop rather than `/0+$/`, which
+ * retries from every zero of a long run and so takes quadratic time on text
+ * such as `"0.000…0001"`.
+ */
+const withoutTrailingZeros = (digits: string): string => {
+  let end = digits.length
+  while (end > 0 && digits.charCodeAt(end - 1) === 48) end--
+  return digits.slice(0, end)
+}
+
+/**
+ * A count from 0 to 255: `decimals` or a fraction-digit option. Not a whole
+ * number is a `TypeError` (the wrong kind of value, such as a `bigint`, text
+ * or `8.5`); a whole number outside the range is a `RangeError`.
+ */
+const toCount = (value: unknown, name: string, fn: string): number => {
+  if (typeof value !== "number" || !Number.isInteger(value)) {
+    throw new TypeError(
+      `[ic-reactor] ${fn}: ${name} must be a whole number from 0 to ${MAX_DIGITS} (a number, as icrc1_decimals returns; convert a bigint with Number()), got ${show(value)}`
+    )
+  }
+  if (value < 0 || value > MAX_DIGITS) {
+    throw new RangeError(
+      `[ic-reactor] ${fn}: ${name} must be from 0 to ${MAX_DIGITS}, got ${show(value)}`
+    )
+  }
+  return value
+}
+
+/**
+ * Refuses an options argument that is not an object, or has a key `names` does
+ * not list: `{ maximumFractionDigits }`, Intl's spelling, would otherwise be
+ * ignored and every digit shown.
+ */
+const checkOptions = (
+  options: unknown,
+  names: readonly string[],
+  fn: string
+): void => {
+  if (options === undefined) return
+  if (typeof options !== "object" || options === null) {
+    throw new TypeError(
+      `[ic-reactor] ${fn}: options is an object, got ${show(options)}`
+    )
+  }
+  checkKeys(options, names, fn)
+}
+
+/**
+ * `-`, then whole digits, then a `.` and fraction digits, either part may be
+ * empty: `"5"`, `"5."`, `".5"`, `"-1.25"`. `\d` is the ASCII digits only.
+ */
+const DECIMAL_TEXT = /^(-)?(\d*)(?:\.(\d*))?$/
+
+/**
+ * Read a decimal amount a person typed, such as `"1.5"`, as the token's base
+ * units, exactly.
+ *
+ * The text is digits with at most one `.`; whitespace around it is ignored,
+ * and `"5."` and `".5"` are accepted. Anything else is refused rather than
+ * guessed at: grouping separators (`"1,5"` means 1.5 in one locale and 15 in
+ * another), exponents (`"1e-8"`), a leading `+`, a lone `.`, whitespace
+ * inside the number, and any other character. More fraction digits than
+ * `decimals` are refused too, unless the extra ones are all zeros: 0.1 at
+ * 8 decimals is `10000000n`, but `"0.123456789"` is no amount of e8s, and
+ * rounding it would send something other than what was typed.
+ *
+ * There is no upper bound on the result. A `nat64` field in a generated
+ * module refuses 2^64 when the call is encoded, before anything is sent, and
+ * an ICRC-1 `amount` is a `nat`, which has no bound; the limit belongs to the
+ * Candid type, not to the conversion.
+ *
+ * @param text - The decimal amount, as a person types it.
+ * @param decimals - The token's decimals, a whole number from 0 to 255, as
+ * `icrc1_decimals` returns them.
+ * @param options - `signed: true` accepts a leading `-`, for an `int` amount.
+ * It defaults to `false`: a ledger's amounts are `nat`, so a negative amount
+ * is refused here instead of failing later when the call is encoded. No other
+ * key is accepted.
+ * @returns The amount in base units: `150000000n` for `"1.5"` at 8 decimals.
+ * @throws TypeError when `text` is not text or not a decimal amount (blank,
+ * letters, grouping, an exponent, a `+`, a lone `.`, inner whitespace),
+ * `decimals` is not a whole number, or `options` is not an object, has a key
+ * other than `signed`, or a `signed` that is not a boolean.
+ * @throws RangeError when `text` has more significant fraction digits than
+ * `decimals`, is negative without `signed`, or `decimals` is outside 0-255.
+ *
+ * @example
+ * ```ts
+ * import { parseUnits } from "@ic-reactor/core"
+ *
+ * parseUnits("0.29", 8) // 29000000n (Number math gives 28999999)
+ * parseUnits("1.1", 18) // 1100000000000000000n
+ * parseUnits("1.000000000", 8) // 100000000n: the extra zeros change nothing
+ * parseUnits("0.123456789", 8) // throws RangeError: 9 fraction digits
+ * parseUnits("-1", 8) // throws RangeError: negative
+ * parseUnits("-1", 8, { signed: true }) // -100000000n
+ * parseUnits("1e3", 8) // throws TypeError: no exponents
+ *
+ * // In a form: show the message and send nothing, or send the exact amount
+ * const onSubmit = () => {
+ *   let amount: bigint
+ *   try {
+ *     amount = parseUnits(input, decimals)
+ *   } catch (error) {
+ *     setAmountError((error as Error).message)
+ *     return
+ *   }
+ *   transfer({ to: { owner }, amount })
+ * }
+ * ```
+ */
+export function parseUnits(
+  text: string,
+  decimals: number,
+  options?: { signed?: boolean }
+): bigint {
+  if (typeof text !== "string") {
+    throw new TypeError(
+      `[ic-reactor] parseUnits: expected the amount as text such as "1.5", got ${show(text)}`
+    )
+  }
+  const scale = toCount(decimals, "decimals", "parseUnits")
+  checkOptions(options, ["signed"], "parseUnits")
+  const signed = options?.signed
+  checkBoolean(signed, "parseUnits: signed")
+  const match = DECIMAL_TEXT.exec(text.trim())
+  if (!match || (!match[2] && !match[3])) {
+    throw new TypeError(
+      `[ic-reactor] parseUnits: ${show(text)} is not a decimal amount; write digits with at most one "." (such as "1.5"), without grouping separators, an exponent or a "+"`
+    )
+  }
+  const [, minus, whole, fraction = ""] = match
+  if (minus && !signed) {
+    throw new RangeError(
+      `[ic-reactor] parseUnits: ${show(text)} is negative; pass { signed: true } to accept a negative amount`
+    )
+  }
+  // Zeros past the token's digits change nothing, so only the rest count.
+  const significant = withoutTrailingZeros(fraction)
+  if (significant.length > scale) {
+    throw new RangeError(
+      `[ic-reactor] parseUnits: ${show(text)} has ${significant.length} fraction ${significant.length === 1 ? "digit" : "digits"}, more than the token's ${scale} decimals`
+    )
+  }
+  const units = BigInt((whole || "0") + significant.padEnd(scale, "0"))
+  return minus ? -units : units
+}
+
+/**
+ * Show an amount of a token's base units as plain decimal text, exactly.
+ *
+ * `value` is what a ledger returns, a `bigint`; no digit passes through a
+ * JavaScript `Number`, so an 18-decimal balance of any size shows as it is.
+ * The text is only `-`, the digits 0-9 and `.`, the same on the server and in
+ * every browser, and the form {@link parseUnits} reads back. For a locale's
+ * separators or grouping, format that text yourself. `Intl.NumberFormat` reads
+ * a decimal string exactly (an engine without Intl.NumberFormat v3 turns it
+ * into a `Number` first), but it rounds to 3 fraction digits unless told
+ * otherwise, so `"0.99999999"` would show as `"1"`: the overstatement
+ * `maxFractionDigits` below prevents. Give it a `maximumFractionDigits` of at
+ * least the digits the text has (`decimals` does, up to the 100 Intl allows),
+ * and a `minimumFractionDigits` to keep zeros `minFractionDigits` padded.
+ *
+ * By default every significant fraction digit is shown and zeros at the end
+ * are dropped, so one ICP (100000000n at 8 decimals) is `"1"`.
+ * `maxFractionDigits` shortens the fraction by cutting the digits past it,
+ * toward zero and never rounding, so a balance of 0.99999999 shown to two
+ * digits is `"0.99"`: never more than is held. `minFractionDigits` pads the
+ * fraction with zeros instead of trimming them, so `2` shows one ICP as
+ * `"1.00"`. A negative amount (an `int`) is written with a leading `-`,
+ * except where the digits shown are all zero: there is no `"-0"`.
+ *
+ * `maxFractionDigits` beyond `decimals` shows the amount exactly, as the
+ * default does, so one display setting can serve tokens of different
+ * decimals. `minFractionDigits` may pad past `decimals`: `"1.2500"` at 2
+ * decimals is the same amount, and {@link parseUnits} reads it back.
+ *
+ * There is no upper bound on `value`. A `nat64` field in a generated module
+ * refuses 2^64 when the call is encoded; an ICRC-1 `nat` has no bound.
+ *
+ * @param value - The amount in base units (e8s for ICP).
+ * @param decimals - The token's decimals, a whole number from 0 to 255, as
+ * `icrc1_decimals` returns them.
+ * @param options - `maxFractionDigits` (default `decimals`, or
+ * `minFractionDigits` when that is more) and `minFractionDigits` (default
+ * `0`), each a whole number from 0 to 255 with `minFractionDigits` not more
+ * than `maxFractionDigits`. Any other key, such as Intl's
+ * `maximumFractionDigits`, is refused.
+ * @returns The amount as decimal text, `"1.5"` for 150000000n at 8 decimals.
+ * @throws TypeError when `value` is not a `bigint`, `decimals` or a digit
+ * option is not a whole number, or `options` is not an object or has another
+ * key.
+ * @throws RangeError when `decimals` or a digit option is outside 0-255, or
+ * `minFractionDigits` is more than `maxFractionDigits`.
+ *
+ * @example
+ * ```ts
+ * import { formatUnits } from "@ic-reactor/core"
+ *
+ * formatUnits(150_000_000n, 8) // "1.5"
+ * formatUnits(123_456_789n, 8, { maxFractionDigits: 2 }) // "1.23"
+ * formatUnits(99_999_999n, 8, { maxFractionDigits: 2 }) // "0.99", never "1"
+ * formatUnits(100_000_000n, 8, { minFractionDigits: 2 }) // "1.00"
+ * formatUnits(-1n, 8) // "-0.00000001"
+ *
+ * // A locale's separators are the app's to add, over the plain text.
+ * // maximumFractionDigits stops Intl rounding to its default 3 digits.
+ * // The cast is for lib ES2023 or later (es2023.intl): before it, the Intl
+ * // types accept a number or bigint only, and a number loses digits.
+ * const text = formatUnits(123_456_789_000n, 8) // "1234.56789"
+ * new Intl.NumberFormat("de-DE", { maximumFractionDigits: 8 }).format(
+ *   text as Intl.StringNumericLiteral
+ * ) // "1.234,56789"
+ * ```
+ */
+export function formatUnits(
+  value: bigint,
+  decimals: number,
+  options?: { maxFractionDigits?: number; minFractionDigits?: number }
+): string {
+  if (typeof value !== "bigint") {
+    throw new TypeError(
+      `[ic-reactor] formatUnits: expected an amount in base units as a bigint, got ${show(value)}. Read decimal text such as "1.5" with parseUnits.`
+    )
+  }
+  const scale = toCount(decimals, "decimals", "formatUnits")
+  checkOptions(
+    options,
+    ["maxFractionDigits", "minFractionDigits"],
+    "formatUnits"
+  )
+  const min =
+    options?.minFractionDigits === undefined
+      ? 0
+      : toCount(options.minFractionDigits, "minFractionDigits", "formatUnits")
+  const max =
+    options?.maxFractionDigits === undefined
+      ? Math.max(scale, min)
+      : toCount(options.maxFractionDigits, "maxFractionDigits", "formatUnits")
+  if (min > max) {
+    throw new RangeError(
+      `[ic-reactor] formatUnits: minFractionDigits (${min}) is more than maxFractionDigits (${max})`
+    )
+  }
+
+  const negative = value < 0n
+  const magnitude = negative ? -value : value
+  const unit = 10n ** BigInt(scale)
+  const whole = magnitude / unit
+  // The fraction as its `scale` digits, cut to the `max` shown: truncation, so
+  // nothing past it carries into the digits that remain.
+  const shown =
+    scale > 0
+      ? (magnitude % unit).toString().padStart(scale, "0").slice(0, max)
+      : ""
+  const significant = withoutTrailingZeros(shown)
+  const fraction = significant.padEnd(min, "0")
+  const text = fraction ? `${whole}.${fraction}` : `${whole}`
+  // Nothing shown but zeros is not negative: -0.001 to two digits is "0".
+  return negative && (whole !== 0n || significant !== "") ? `-${text}` : text
+}

package/packages/core/src/version.ts

@@ -0,0 +1,4 @@
+/**
+ * Library version - automatically synced from package.json.
+ */
+export const VERSION = "4.1.1"

package/packages/core/tests/canister-helpers.ts

@@ -0,0 +1,187 @@
+/**
+ * Fixtures for the canister tests: fake canisters written in domain values
+ * (encoded and decoded with the service schema, as a real canister's Candid
+ * would be), an ICRC-1 ledger that keeps balances, and clients on a fake
+ * replica.
+ *
+ * Every test runs the real client against `createFakeReplica`, which signs
+ * and verifies like a replica; nothing global is stubbed but the page a
+ * browser test runs in.
+ */
+import { serviceMethods, type Principal, type Schema } from "@meantjs/schema"
+import { decodeArgs, encodeArgs } from "@meantjs/schema/codec"
+import type { Identity } from "@icp-sdk/core/agent"
+import { vi } from "vitest"
+import { createClient, type AuthLike, type Client } from "../src/client.js"
+import type { ArgsOf, ReplyOf } from "../src/types.js"
+import {
+  createFakeReplica,
+  type FakeCallContext,
+  type FakeCanister,
+  type FakeReplica,
+  type FakeReplicaRequest,
+} from "../src/testing/fake-replica.js"
+import * as icrc1 from "./fixtures/icrc1.js"
+
+export { ANONYMOUS, deferred, networkOf, onPage } from "./client-helpers.js"
+
+/** The canister ids the tests run their fakes at. */
+export const LEDGER = "ryjl3-tyaaa-aaaaa-aaaba-cai"
+export const SHAPES = "rrkah-fqaaa-aaaaa-aaaaq-cai"
+export const ARCHIVE = "qoctq-giaaa-aaaaa-aaaea-cai"
+export const MANAGEMENT = "aaaaa-aa"
+
+/** What a fake method is told about its call. */
+export interface CallContext {
+  /** The caller the replica checked, as text. */
+  readonly caller: string
+}
+
+/**
+ * `A` as an `Actor` written by hand: the same call signatures, without the
+ * mode `meant gen` marks each method with (`$.WithMode<mode>`).
+ * Its methods' modes are unknown to the types, so `queryOptions` compiles for
+ * an update or a oneway method of it, and the run-time check is what refuses
+ * them: a test of that check reads through this.
+ */
+export type HandWritten<A> = {
+  [K in keyof A]: A[K] extends (...args: infer P) => Promise<infer R>
+    ? (...args: P) => Promise<R>
+    : never
+}
+
+/** A fake method: the decoded arguments in, the reply (before any unwrapping) out. */
+export type Handlers<A> = {
+  readonly [K in keyof A]?: (
+    args: ArgsOf<A[K]>,
+    context: CallContext
+  ) => ReplyOf<A[K]> | Promise<ReplyOf<A[K]>>
+}
+
+/**
+ * A fake canister for `service` that runs `handlers` with decoded arguments
+ * and encodes what they return with the method's result schemas: the value
+ * for one result, the tuple for several, nothing for none. It answers both
+ * queries and calls, so a test can send a query method as a replicated call.
+ */
+export function serve<A>(
+  service: Schema<Principal>,
+  handlers: Handlers<A>
+): FakeCanister {
+  const methods = serviceMethods(service)
+  const run = async (
+    name: string,
+    arg: Uint8Array,
+    { caller }: FakeCallContext
+  ): Promise<Uint8Array> => {
+    const method = methods.get(name)
+    const handler = (
+      handlers as Record<
+        string,
+        ((args: unknown[], context: CallContext) => unknown) | undefined
+      >
+    )[name]
+    if (method === undefined || handler === undefined) {
+      throw new Error(`the test canister has no handler for ${name}`)
+    }
+    const decoded = decodeArgs(method.args, arg)
+    if (!decoded.ok) {
+      throw new Error(
+        `the test canister could not decode the arguments of ${name}: ${JSON.stringify(decoded.issues)}`
+      )
+    }
+    const reply = await handler([...decoded.values], {
+      caller: caller.toText(),
+    })
+    const values =
+      method.results.length === 0
+        ? []
+        : method.results.length === 1
+          ? [reply]
+          : (reply as unknown[])
+    const encoded = encodeArgs(method.results, values)
+    if (!encoded.ok) {
+      throw new Error(
+        `the test canister could not encode the reply of ${name}: ${JSON.stringify(encoded.issues)}`
+      )
+    }
+    return encoded.bytes
+  }
+  return { query: run, update: run }
+}
+
+/** The ledger's transfer fee. */
+export const FEE = 10_000n
+
+/** A fake ICRC-1 ledger: balances by owner, transfers debit the caller. */
+export function ledgerCanister(balances: Map<string, bigint>) {
+  const balanceOf = (owner: string) => balances.get(owner) ?? 0n
+  return serve<icrc1.Actor>(icrc1.actor, {
+    icrc1_balance_of: ([account]) => balanceOf(account.owner),
+    icrc1_fee: () => FEE,
+    icrc1_decimals: () => 8,
+    icrc1_symbol: () => "ICP",
+    icrc1_minting_account: () => null,
+    icrc1_transfer: ([arg], { caller }) => {
+      const debit = arg.amount + FEE
+      const balance = balanceOf(caller)
+      if (balance < debit) {
+        return {
+          tag: "Err",
+          value: { tag: "InsufficientFunds", value: { balance } },
+        }
+      }
+      balances.set(caller, balance - debit)
+      balances.set(arg.to.owner, balanceOf(arg.to.owner) + arg.amount)
+      return { tag: "Ok", value: 7n }
+    },
+  })
+}
+
+/** The canister requests (`query` and `call`) the replica saw, in order. */
+export const canisterRequests = (replica: FakeReplica): FakeReplicaRequest[] =>
+  replica.requests.filter(
+    (request) => request.endpoint === "query" || request.endpoint === "call"
+  )
+
+/** The canister requests for `method`. */
+export const requestsFor = (replica: FakeReplica, method: string) =>
+  canisterRequests(replica).filter((request) => request.methodName === method)
+
+/** A client on `replica` that calls as `identity`. Runs where the test runs (Node: a server). */
+export const clientAs = (
+  replica: FakeReplica,
+  identity: Identity | "anonymous",
+  options: { maxDepth?: number } = {}
+): Client =>
+  createClient({
+    network: { host: replica.host, rootKey: replica.rootKey },
+    fetch: replica.fetch,
+    identity,
+    ...options,
+  })
+
+/** A client on `replica` in a browser page, signed in through `auth`. */
+export const clientWithAuth = (
+  replica: FakeReplica,
+  auth: AuthLike
+): Client => {
+  vi.stubGlobal("window", {
+    location: {
+      origin: "https://app.example.com",
+      protocol: "https:",
+    },
+  })
+  return createClient({
+    network: { host: replica.host, rootKey: replica.rootKey },
+    fetch: replica.fetch,
+    auth: () => auth,
+  })
+}
+
+/** A fake replica running `canisters`. */
+export const replicaWith = (canisters: Record<string, FakeCanister>) =>
+  createFakeReplica({ canisters })
+
+export const sleep = (ms: number) =>
+  new Promise<void>((resolve) => setTimeout(resolve, ms))

package/packages/core/tests/canister-id.test.ts

@@ -0,0 +1,158 @@
+/**
+ * `client.canisterId(target)`: what a target resolves to now, from the same
+ * resolver a call uses, without a call. Its reasons are the resolver's own;
+ * these tests check that the client hands them out as a call would meet them.
+ */
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"
+import { createClient, type Client } from "../src/index.js"
+import {
+  COOKIE_CANISTER_ID,
+  icEnvCookie,
+  stubNoWindow,
+  stubPage,
+  stubProcessEnv,
+} from "./network-helpers.js"
+import * as shapes from "./fixtures/shapes.js"
+
+const LOCAL_PAGE = "http://localhost:5173"
+const CUSTOM_PAGE = "https://app.example.com"
+const OTHER_ID = "rrkah-fqaaa-aaaaa-aaaaq-cai"
+
+beforeEach(() => {
+  stubProcessEnv()
+})
+
+afterEach(() => {
+  vi.unstubAllGlobals()
+  vi.unstubAllEnvs()
+})
+
+const localClient = (): Client =>
+  createClient({ network: "local", identity: "anonymous" })
+
+/** The message a call on `{ name }` rejects with on `client`. */
+const callRefusal = async (client: Client, name: string): Promise<unknown> =>
+  client
+    .canister<shapes.Actor>(shapes.actor, { name })
+    .who()
+    .catch((error: unknown) => error)
+
+describe("a client's canisterId", () => {
+  it("gives an { id } as it is, on any page and with no cookie", () => {
+    stubPage(CUSTOM_PAGE, { cookie: "" })
+    const client = createClient({ network: "ic", identity: "anonymous" })
+
+    expect(client.canisterId({ id: OTHER_ID })).toStrictEqual({
+      ok: true,
+      id: OTHER_ID,
+    })
+    expect(client.canisterId({ id: OTHER_ID, certified: true })).toStrictEqual({
+      ok: true,
+      id: OTHER_ID,
+    })
+  })
+
+  it("gives the cookie's id for a { name } on a trusted page, the id a call is sent to", () => {
+    stubPage(LOCAL_PAGE)
+    const client = localClient()
+    const backend = client.canister<shapes.Actor>(shapes.actor, {
+      name: "backend",
+    })
+
+    expect(client.canisterId({ name: "backend" })).toStrictEqual({
+      ok: true,
+      id: COOKIE_CANISTER_ID,
+    })
+    // The canister's keys carry the id its calls go to.
+    expect(client.queryKey(backend)).toContain(COOKIE_CANISTER_ID)
+  })
+
+  it.each([
+    [
+      "absent",
+      () => {
+        stubPage(LOCAL_PAGE)
+        return localClient()
+      },
+      "missing",
+    ],
+    [
+      "untrusted_host",
+      () => {
+        stubPage(CUSTOM_PAGE)
+        return createClient({ network: "ic", identity: "anonymous" })
+      },
+      "backend",
+    ],
+    [
+      "no_browser",
+      () => {
+        stubNoWindow()
+        return createClient({ network: "local", identity: "anonymous" })
+      },
+      "backend",
+    ],
+  ] as const)(
+    "says %s, with the message a call on the same target rejects with",
+    async (reason, setup, name) => {
+      const send = vi.fn()
+      vi.stubGlobal("fetch", send)
+      const client = setup()
+
+      const answer = client.canisterId({ name })
+      expect(answer).toMatchObject({ ok: false, reason })
+      const refusal = await callRefusal(client, name)
+      expect(refusal).toMatchObject({ code: "canister_id_unresolved" })
+      expect((refusal as Error).message).toContain(
+        (answer as { message: string }).message
+      )
+      expect(send).not.toHaveBeenCalled()
+    }
+  )
+
+  it("reads the cookie again on each call, so a new id is seen at once", () => {
+    let cookie = icEnvCookie({ "PUBLIC_CANISTER_ID:backend": OTHER_ID })
+    vi.stubGlobal("window", {
+      location: { origin: LOCAL_PAGE, protocol: "http:" },
+    })
+    vi.stubGlobal("document", {
+      get cookie() {
+        return cookie
+      },
+    })
+    const client = localClient()
+
+    expect(client.canisterId({ name: "backend" })).toStrictEqual({
+      ok: true,
+      id: OTHER_ID,
+    })
+    cookie = icEnvCookie()
+    expect(client.canisterId({ name: "backend" })).toStrictEqual({
+      ok: true,
+      id: COOKIE_CANISTER_ID,
+    })
+    cookie = ""
+    expect(client.canisterId({ name: "backend" })).toMatchObject({
+      ok: false,
+      reason: "absent",
+    })
+  })
+
+  it.each([
+    ["an id that is not principal text", { id: "not-a-principal" }],
+    ["both id and name", { id: OTHER_ID, name: "backend" }],
+    ["neither", {}],
+    ["an unknown option", { canisterId: OTHER_ID }],
+    ["a value that is not an object", "backend"],
+  ])("throws a TypeError for %s", (_label, target) => {
+    const client = localClient()
+    expect(() => client.canisterId(target as never)).toThrow(TypeError)
+  })
+
+  it("names itself in the TypeError for a target of the wrong shape", () => {
+    const client = localClient()
+    expect(() => client.canisterId({} as never)).toThrow(
+      /client\.canisterId\(\) takes \{ id \} or \{ name \}/
+    )
+  })
+})