@ic-reactor/mcp 0.0.0-stage → 0.0.0

package/examples/vite-wallet/src/EnvironmentPanel.tsx

@@ -0,0 +1,103 @@
+// Scenario 1: which network the page talks to, and how it found the canisters.
+//
+// - `createClient({ network: "env" })` routes through the page's own origin;
+//   `client.network`, the network segment of every query key, is that origin.
+// - @ic-reactor/vite-plugin sets the ic_env cookie on every page load under
+//   `vite dev` and `vite preview` (the root key and a PUBLIC_CANISTER_ID per
+//   canister it asked `icp` about) and proxies /api to the local gateway.
+// - `{ name: "backend" }` is resolved from that cookie when a key or a call is
+//   built, and only on a page where it is trusted (both the page and the
+//   replica local). `client.queryKey(backend)` shows what it resolved to: the
+//   canister id, or `$unresolved:backend`, in which case every call is refused
+//   before sending (`invalid_args`, code `canister_id_unresolved`).
+//
+// This panel reads the cookie itself only to show it; the client reads it on
+// its own.
+import { useAuth, useClient } from "@ic-reactor/react"
+import { safeGetCanisterEnv } from "@icp-sdk/core/agent/canister-env"
+import { useQuery } from "@tanstack/react-query"
+import { ErrorNote } from "./ErrorNote.tsx"
+import { useCanisters } from "./use-canisters.ts"
+
+/** The cookie's entries, as `safeGetCanisterEnv` parses them. */
+type CookieEntries = Readonly<Record<string, string | Uint8Array | undefined>>
+
+export function EnvironmentPanel() {
+  const client = useClient()
+  const { backend, ledger } = useCanisters()
+  const { principal: caller } = useAuth()
+  const cookie = safeGetCanisterEnv<CookieEntries>()
+  // The fourth segment of a canister's key is the id the client resolved.
+  const resolved = (key: readonly unknown[]) => String(key[3])
+  const backendId = resolved(client.queryKey(backend))
+  const ledgerId = resolved(client.queryKey(ledger))
+  // A read that proves the id leads to a canister that answers: the
+  // caller's contacts (none for the anonymous principal).
+  const probe = useQuery(client.queryOptions(backend, "contacts"))
+
+  const names = Object.keys(cookie ?? {}).filter((name) =>
+    name.startsWith("PUBLIC_CANISTER_ID:")
+  )
+
+  return (
+    <section aria-labelledby="environment">
+      <p className="scenario">Scenario 1</p>
+      <h2 id="environment">Network and canisters</h2>
+      <dl>
+        <div className="kv">
+          <dt>
+            <code>client.network</code> (calls go to its <code>/api</code>)
+          </dt>
+          <dd data-testid="network">{client.network}</dd>
+        </div>
+        <div className="kv">
+          <dt>
+            <code>{'{ name: "backend" }'}</code> resolved to
+          </dt>
+          <dd data-testid="backend-id">{backendId}</dd>
+        </div>
+        <div className="kv">
+          <dt>
+            <code>{"{ id }"}</code> of the ICP ledger
+          </dt>
+          <dd data-testid="ledger-id">{ledgerId}</dd>
+        </div>
+        <div className="kv">
+          <dt>The backend answers</dt>
+          <dd data-testid="backend-probe">
+            {probe.isSuccess
+              ? `yes: contacts() as ${caller === "2vxsx-fae" ? "anonymous" : "you"} gave ${probe.data.length}`
+              : probe.isError
+                ? "no"
+                : "…"}
+          </dd>
+        </div>
+      </dl>
+      {probe.isError && <ErrorNote error={probe.error} />}
+      <h3>The ic_env cookie this page was served with</h3>
+      {cookie === undefined ? (
+        <p className="muted" data-testid="cookie">
+          None. Under <code>pnpm dev</code> the Vite plugin sets it once the
+          local network runs (<code>pnpm icp:start</code>).
+        </p>
+      ) : (
+        <ul className="plain" data-testid="cookie">
+          <li>
+            <code>IC_ROOT_KEY</code>: {cookie.IC_ROOT_KEY?.length ?? 0} bytes
+          </li>
+          {names.map((name) => (
+            <li key={name}>
+              <code>{name}</code>: {String(cookie[name])}
+            </li>
+          ))}
+          {typeof cookie.INTERNET_IDENTITY_PROVIDER === "string" && (
+            <li>
+              <code>INTERNET_IDENTITY_PROVIDER</code>:{" "}
+              {cookie.INTERNET_IDENTITY_PROVIDER}
+            </li>
+          )}
+        </ul>
+      )}
+    </section>
+  )
+}

package/examples/vite-wallet/src/ErrorNote.tsx

@@ -0,0 +1,70 @@
+// How the wallet words a failed call. Every rejection a client call produces
+// is a `ReactorError`: its `kind` says what happened, and `mayHaveExecuted`
+// whether a failed write may have taken effect anyway, which is the question
+// a person needs answered before trying again. Within a kind, `code` tells
+// causes apart that need different advice: an `unauthenticated` write while
+// nobody is signed in (`anonymous_write`) is not the same as a signed-in
+// session whose identity the auth could not hand over (`identity_unavailable`,
+// such as an Internet Identity session whose stored key is gone).
+import { isReactorError } from "@ic-reactor/core"
+
+/** One sentence for a failure, and whether it is a warning (it may have happened). */
+export function explain(
+  error: unknown,
+  refusal?: string
+): { text: string; unknownOutcome: boolean } {
+  if (!isReactorError(error)) {
+    return {
+      text: error instanceof Error ? error.message : String(error),
+      unknownOutcome: false,
+    }
+  }
+  if (error.kind === "canister_err") {
+    return {
+      text: `Refused by the canister: ${refusal ?? error.message}`,
+      unknownOutcome: false,
+    }
+  }
+  if (error.kind === "unauthenticated" && error.code === "anonymous_write") {
+    return {
+      text: "Not sent: nobody is signed in, and the client refuses a write before sending it (unauthenticated).",
+      unknownOutcome: false,
+    }
+  }
+  if (
+    error.kind === "unauthenticated" &&
+    error.code === "identity_unavailable"
+  ) {
+    // A read or a write: the client asks the auth for the identity of the
+    // signed-in principal before either is sent.
+    return {
+      text: "Not sent: you are signed in, but the session's key could not be loaded to sign with (unauthenticated, identity_unavailable). Sign out and sign in again.",
+      unknownOutcome: false,
+    }
+  }
+  if (error.mayHaveExecuted) {
+    return {
+      text: `Outcome unknown (${error.kind}): it may have gone through. The client re-read what it may have changed; check that before trying again.`,
+      unknownOutcome: true,
+    }
+  }
+  if (error.code === "canister_id_unresolved") {
+    return {
+      text: "Not sent: the ic_env cookie names no backend. Deploy it (pnpm icp:deploy), then reload the page.",
+      unknownOutcome: false,
+    }
+  }
+  return {
+    text: `Not done, and certainly not executed (${error.kind}${error.code ? `, ${error.code}` : ""}): ${error.message}`,
+    unknownOutcome: false,
+  }
+}
+
+export function ErrorNote(props: { error: unknown; refusal?: string }) {
+  const { text, unknownOutcome } = explain(props.error, props.refusal)
+  return (
+    <p className={unknownOutcome ? "warn" : "error"} role="alert">
+      {text}
+    </p>
+  )
+}

package/examples/vite-wallet/src/Profile.test.tsx

@@ -0,0 +1,145 @@
+// Scenario 6: the profile, read and written as the signed-in caller, and a
+// write while signed out refused by the client before it is sent.
+import { createClient, type AuthLike, type Client } from "@ic-reactor/core"
+import { ReactorProvider } from "@ic-reactor/react"
+import { SessionNotHeldError } from "@icp-sdk/auth/client"
+import {
+  cleanup,
+  fireEvent,
+  render,
+  screen,
+  waitFor,
+} from "@testing-library/react"
+import { StrictMode } from "react"
+import { afterEach, describe, expect, it } from "vitest"
+import { createWalletAuth } from "./auth/wallet-auth.ts"
+import { Profile } from "./Profile.tsx"
+import {
+  BACKEND_ID,
+  clearEnvCookie,
+  createTestWallet,
+  patiently,
+  renderWithWallet,
+  SEED_1,
+  setEnvCookie,
+  type TestWallet,
+} from "./test/test-wallet.tsx"
+
+let wallet: TestWallet | undefined
+let lostKeyClient: Client | undefined
+afterEach(() => {
+  cleanup()
+  wallet?.client.dispose()
+  lostKeyClient?.dispose()
+  lostKeyClient = undefined
+  clearEnvCookie()
+})
+
+function save(name: string) {
+  fireEvent.change(screen.getByLabelText("Name"), { target: { value: name } })
+  fireEvent.click(screen.getByRole("button", { name: "Save" }))
+}
+
+describe("the profile", () => {
+  it("refuses a write while signed out before sending it, and says so", async () => {
+    wallet = createTestWallet({ signedIn: false })
+    renderWithWallet(wallet, <Profile />)
+    expect(screen.getByTestId("profile-name").textContent).toBe(
+      "Signed out: no profile is read."
+    )
+
+    save("Ada")
+
+    await screen.findByText(
+      "Not sent: nobody is signed in, and the client refuses a write before sending it (unauthenticated).",
+      {},
+      patiently
+    )
+    // Nothing reached the replica: no write, and no read either (skipToken).
+    expect(wallet.callsOf("set_name")).toBe(0)
+    expect(wallet.callsOf("get_profile")).toBe(0)
+  })
+
+  it("saves a name as the caller, and the client's invalidation shows it", async () => {
+    wallet = createTestWallet()
+    renderWithWallet(wallet, <Profile />)
+    await screen.findByText("No name yet.", {}, patiently)
+    const reads = wallet.callsOf("get_profile")
+
+    save("Ada")
+
+    await screen.findByText("Saved as Ada.", {}, patiently)
+    // Shown by a new read of get_profile, which the client's onSettled asked for.
+    await screen.findByText("Name: Ada", {}, patiently)
+    expect(wallet.callsOf("get_profile")).toBeGreaterThan(reads)
+    expect(
+      wallet.requests.find((r) => r.methodName === "set_name")?.caller
+    ).toBe(SEED_1)
+  })
+
+  it("words the backend's typed refusal of an invalid name", async () => {
+    wallet = createTestWallet()
+    renderWithWallet(wallet, <Profile />)
+    await screen.findByText("No name yet.", {}, patiently)
+
+    save("   ")
+
+    await screen.findByText(
+      "Refused by the canister: a name is 1 to 32 characters, with no control characters.",
+      {},
+      patiently
+    )
+    expect(screen.getByTestId("profile-name").textContent).toBe("No name yet.")
+  })
+
+  it("tells a signed-in user whose key is gone to sign in again, not that nobody is signed in", async () => {
+    // An Internet Identity session whose record says signed in while the key
+    // that signs for it is gone (cleared site data, another tab's sign-out
+    // the store could not report): AuthClient's getIdentity() rejects
+    // SessionNotHeldError, and the client rejects every call of that
+    // principal, read or write, `unauthenticated` with code
+    // `identity_unavailable`. createTestClient's sign-in never loses its key,
+    // so this client is built as the app's is, over the app's own auth.
+    setEnvCookie({ backend: BACKEND_ID })
+    const lostKey: AuthLike = {
+      getPrincipal: () => ({ toText: () => SEED_1 }),
+      getStatus: () => ({ state: "signed-in" }),
+      getIdentity: () => Promise.reject(new SessionNotHeldError()),
+      subscribe: () => () => {},
+      signIn: () => Promise.resolve(),
+      signOut: () => Promise.resolve(),
+    }
+    let sent = 0
+    const client = createClient({
+      network: "env",
+      // The client asks for the identity before it builds an agent, so
+      // nothing reaches this.
+      fetch: () => {
+        sent += 1
+        return Promise.reject(new Error("nothing may be sent"))
+      },
+      auth: () => createWalletAuth({ internetIdentity: lostKey }),
+    })
+    lostKeyClient = client
+    render(
+      <StrictMode>
+        <ReactorProvider client={() => client}>
+          <Profile />
+        </ReactorProvider>
+      </StrictMode>
+    )
+    const lostKeyText =
+      "Not sent: you are signed in, but the session's key could not be loaded to sign with (unauthenticated, identity_unavailable). Sign out and sign in again."
+
+    // The read fails first, then the write, and both say the same.
+    await screen.findByText("The profile could not be read.", {}, patiently)
+    await screen.findByText(lostKeyText, {}, patiently)
+    save("Ada")
+    await waitFor(
+      () => expect(screen.getAllByText(lostKeyText)).toHaveLength(2),
+      patiently
+    )
+    expect(screen.queryByText(/nobody is signed in/)).toBeNull()
+    expect(sent).toBe(0)
+  })
+})

package/examples/vite-wallet/src/Profile.tsx

@@ -0,0 +1,92 @@
+// Scenario 6: the backend's profile, read and written as the signed-in caller.
+//
+// - `get_profile` is read with `skipToken` while signed out.
+// - `set_name` is a write: `useMutation(client.mutationOptions(backend,
+//   "set_name"))`. Signed out, the form still works on purpose: the client
+//   refuses the write with kind `unauthenticated` before sending anything,
+//   and the page says so. (The backend refuses the anonymous principal too,
+//   with its own `Err`, but the call never reaches it.)
+// - The backend's own refusals (a name that is empty, too long or has a
+//   control character) arrive as `canister_err` with a typed `Refusal`.
+// - After the write settles, the client invalidates the backend's reads (its
+//   default for a write), so the saved name shows without code here.
+import { useAuth, useClient } from "@ic-reactor/react"
+import { skipToken, useMutation, useQuery } from "@tanstack/react-query"
+import { useState, type FormEvent } from "react"
+import { ErrorNote } from "./ErrorNote.tsx"
+import { describeRefusal } from "./refusal.ts"
+import { useCanisters } from "./use-canisters.ts"
+
+export function Profile() {
+  const client = useClient()
+  const { backend } = useCanisters()
+  const { status } = useAuth()
+  const signedIn = status === "signed-in"
+  const profile = useQuery(
+    client.queryOptions(
+      backend,
+      "get_profile",
+      signedIn ? undefined : skipToken
+    )
+  )
+  const rename = useMutation(client.mutationOptions(backend, "set_name"))
+  const [name, setName] = useState("")
+
+  const onSubmit = (event: FormEvent) => {
+    event.preventDefault()
+    rename.mutate(name)
+  }
+
+  return (
+    <section aria-labelledby="profile">
+      <p className="scenario">Scenario 6</p>
+      <h2 id="profile">Profile</h2>
+      <p data-testid="profile-name">
+        {!signedIn
+          ? "Signed out: no profile is read."
+          : profile.isError
+            ? "The profile could not be read."
+            : profile.data === undefined
+              ? "…"
+              : profile.data === null
+                ? "No name yet."
+                : `Name: ${profile.data.name}`}
+      </p>
+      <form onSubmit={onSubmit}>
+        <label htmlFor="profile-input">Name</label>
+        <input
+          id="profile-input"
+          value={name}
+          onChange={(e) => setName(e.target.value)}
+          autoComplete="off"
+        />
+        <div className="row">
+          <button type="submit" disabled={rename.isPending}>
+            Save
+          </button>
+          {!signedIn && (
+            <span className="muted">
+              Try it signed out: the client refuses it before sending.
+            </span>
+          )}
+        </div>
+      </form>
+      {profile.isError && <ErrorNote error={profile.error} />}
+      {rename.isSuccess && (
+        <p className="ok" data-testid="profile-saved">
+          Saved as {rename.data.name}.
+        </p>
+      )}
+      {rename.error && (
+        <ErrorNote
+          error={rename.error}
+          refusal={
+            rename.error.kind === "canister_err"
+              ? describeRefusal(rename.error.err)
+              : undefined
+          }
+        />
+      )}
+    </section>
+  )
+}

package/examples/vite-wallet/src/SendIcp.test.tsx

@@ -0,0 +1,231 @@
+// Scenario 5: sending ICP, as a person does it, with the ledger mocked on the
+// in-memory replica and faults put in its way.
+import {
+  act,
+  cleanup,
+  fireEvent,
+  screen,
+  waitFor,
+} from "@testing-library/react"
+import { afterEach, describe, expect, it } from "vitest"
+import { Balance } from "./Balance.tsx"
+import { SendIcp } from "./SendIcp.tsx"
+import {
+  BOB,
+  clearEnvCookie,
+  createTestWallet,
+  FEE,
+  ICP,
+  patiently,
+  renderWithWallet,
+  SEED_1,
+  type TestWallet,
+} from "./test/test-wallet.tsx"
+
+let wallet: TestWallet | undefined
+afterEach(() => {
+  cleanup()
+  wallet?.client.dispose()
+  clearEnvCookie()
+})
+
+async function renderSend(start = 7n * ICP): Promise<TestWallet> {
+  const made = createTestWallet()
+  made.setBalance(SEED_1, start)
+  wallet = made
+  renderWithWallet(
+    made,
+    <>
+      <Balance refreshMs={60_000} />
+      <SendIcp />
+    </>
+  )
+  await screen.findByText(
+    "Fee 0.0001 ICP, paid on top of the amount.",
+    {},
+    patiently
+  )
+  await screen.findByText("7 ICP", {}, patiently)
+  return made
+}
+
+function send(to: string, amount: string) {
+  fireEvent.change(screen.getByLabelText("To (principal)"), {
+    target: { value: to },
+  })
+  fireEvent.change(screen.getByLabelText("Amount (ICP)"), {
+    target: { value: amount },
+  })
+  fireEvent.click(screen.getByRole("button", { name: "Send" }))
+}
+
+const outcome = () => screen.getByTestId("outcome").textContent
+
+describe("sending ICP", () => {
+  it("sends the amount with the fee shown, a memo and a created_at_time, and the balance follows", async () => {
+    const made = await renderSend()
+    send(BOB, "1.5")
+
+    await screen.findByText("Sent 1.5 ICP: block 0.", {}, patiently)
+    // The client's onSettled read the ledger again: 7 - 1.5 - 0.0001.
+    await screen.findByText("5.4999 ICP", {}, patiently)
+    expect(made.transfers).toHaveLength(1)
+    expect(made.transfers[0]?.fee).toBe(FEE)
+    expect(made.transfers[0]?.memo).toHaveLength(16)
+    expect(made.transfers[0]?.created_at_time).not.toBeNull()
+  })
+
+  it("refuses text parseUnits refuses, and sends nothing", async () => {
+    const made = await renderSend()
+    send(BOB, "1e3")
+    await screen.findByText(
+      'Not sent: amount: Write plain digits with at most one "." (no exponent, grouping or sign).'
+    )
+    send("bob", "1")
+    await screen.findByText("Not sent: to: Not a principal.")
+    expect(made.callsOf("icrc1_transfer")).toBe(0)
+  })
+
+  it("words the ledger's Err: insufficient funds", async () => {
+    await renderSend()
+    send(BOB, "7")
+    await waitFor(
+      () =>
+        expect(outcome()).toBe(
+          "Refused by the canister: Insufficient funds: the balance is 7 ICP, less than the amount plus the fee."
+        ),
+      patiently
+    )
+  })
+
+  it("words the ledger's Err: a fee that changed since it was shown", async () => {
+    const made = await renderSend()
+    made.setFee(2n * FEE)
+    send(BOB, "1")
+    await waitFor(
+      () =>
+        expect(outcome()).toBe(
+          "Refused by the canister: Bad fee: the ledger now charges 0.0002 ICP. Nothing moved; send again to pay that fee."
+        ),
+      patiently
+    )
+    // A canister_err invalidates the ledger's reads too: the fee shown is the new one.
+    await screen.findByText(
+      "Fee 0.0002 ICP, paid on top of the amount.",
+      {},
+      patiently
+    )
+  })
+
+  it("after a lost reply, says the outcome is unknown, re-reads, and lets the same account send it again, deduplicated", async () => {
+    const made = await renderSend()
+    const balanceReads = made.callsOf("icrc1_balance_of")
+    made.dropNextReply()
+    send(BOB, "1")
+
+    await screen.findByRole(
+      "button",
+      { name: "Send the same transfer again" },
+      patiently
+    )
+    expect(outcome()).toContain(
+      "Outcome unknown (outcome_unknown): it may have gone through."
+    )
+    // The page did not re-read: the client did, after a failure that may have executed.
+    expect(made.callsOf("icrc1_balance_of")).toBeGreaterThan(balanceReads)
+    await screen.findByText("5.9999 ICP", {}, patiently)
+
+    fireEvent.click(
+      screen.getByRole("button", { name: "Send the same transfer again" })
+    )
+    await waitFor(
+      () =>
+        expect(outcome()).toBe(
+          "Refused by the canister: Duplicate of block 0: this exact transfer went through already, and was not made twice."
+        ),
+      patiently
+    )
+    // Paid once: the same argument, memo included, sent twice by the same account.
+    expect(made.balanceOf(BOB)).toBe(1n * ICP)
+    expect(made.transfers[1]).toEqual(made.transfers[0])
+  })
+
+  it("does not offer the transfer again to another account", async () => {
+    const made = await renderSend()
+    made.dropNextReply()
+    send(BOB, "1")
+    await screen.findByRole(
+      "button",
+      { name: "Send the same transfer again" },
+      patiently
+    )
+
+    act(() => {
+      made.auth.switchTo(2)
+    })
+
+    // Once the page has the token again, as seed 2: the outcome is shown,
+    // and the button is not.
+    await screen.findByText(
+      "Fee 0.0001 ICP, paid on top of the amount.",
+      {},
+      patiently
+    )
+    expect(outcome()).toContain("Outcome unknown (outcome_unknown)")
+    expect(
+      screen.queryByRole("button", { name: "Send the same transfer again" })
+    ).toBeNull()
+  })
+
+  it("withdraws the offer on a sign-out, and makes it again once the same account signs back in", async () => {
+    const made = await renderSend()
+    made.dropNextReply()
+    send(BOB, "1")
+    const again = { name: "Send the same transfer again" }
+    await screen.findByRole("button", again, patiently)
+
+    await act(async () => {
+      await made.auth.signOut()
+    })
+    await screen.findByText("Sign in to send.", {}, patiently)
+    expect(screen.queryByRole("button", again)).toBeNull()
+
+    await act(async () => {
+      await made.auth.signIn()
+    })
+    fireEvent.click(await screen.findByRole("button", again, patiently))
+    await waitFor(
+      () =>
+        expect(outcome()).toBe(
+          "Refused by the canister: Duplicate of block 0: this exact transfer went through already, and was not made twice."
+        ),
+      patiently
+    )
+    expect(made.balanceOf(BOB)).toBe(1n * ICP)
+  })
+
+  it("after a reject from the canister, says it may have executed, and the re-read shows nothing moved", async () => {
+    const made = await renderSend()
+    made.failNext("icrc1_transfer", "reject-4")
+    send(BOB, "1")
+    await screen.findByRole(
+      "button",
+      { name: "Send the same transfer again" },
+      patiently
+    )
+    expect(outcome()).toContain("Outcome unknown (rejected)")
+    expect(screen.getByText("7 ICP")).toBeTruthy()
+    expect(made.balanceOf(SEED_1)).toBe(7n * ICP)
+  })
+
+  it("cannot send while signed out", async () => {
+    const made = createTestWallet({ signedIn: false })
+    wallet = made
+    renderWithWallet(made, <SendIcp />)
+    await screen.findByText("Sign in to send.", {}, patiently)
+    expect(
+      (screen.getByRole("button", { name: "Send" }) as HTMLButtonElement)
+        .disabled
+    ).toBe(true)
+  })
+})