@ic-reactor/mcp 0.0.0-stage → 0.0.0

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

@@ -0,0 +1,244 @@
+// Scenario 5: send ICP with
+// `useMutation(client.mutationOptions(ledger, "icrc1_transfer"))`.
+//
+// - What is typed becomes an argument in transfer.ts, or is refused there:
+//   nothing half-valid is sent.
+// - The ledger's `Err` is a `canister_err` with a typed `err`
+//   (InsufficientFunds, BadFee, Duplicate, ...), worded by
+//   `describeTransferError`. Nothing was executed.
+// - `mayHaveExecuted` (a lost reply, a reject after the canister ran): the
+//   page says the outcome is unknown. It does not re-read anything itself:
+//   the client's onSettled already refetched the ledger's reads, the balance
+//   included. "Send the same transfer again" is `client.resendOf`'s offer:
+//   made only after such a failure, only while the account that sent it is
+//   still the caller, and only because the argument has a `created_at_time`
+//   (`dedupedBy`), which is what the ledger deduplicates on. Pressed, it sends
+//   the attempt's own argument, the same `memo` and `created_at_time`, through
+//   the same mutation, as that account, to the same ledger and unchanged, or
+//   not at all: the ledger answers `Duplicate` if the first one went through.
+//   From another account, or to another ledger, it would be a new transfer,
+//   paid in full. Each press of Send reads the form again into a new
+//   argument, so a new transfer gets a new memo, and is never taken for the
+//   duplicate of another one of the same amount made in the same millisecond.
+// - No `retry` is added: the client re-sends an update only when the failure
+//   proves it never arrived, and any other re-send could pay twice.
+import type { ReactorError } from "@ic-reactor/core"
+import { useAuth, useClient } from "@ic-reactor/react"
+import { useMutation } from "@tanstack/react-query"
+import { useState, type FormEvent } from "react"
+import type { TransferArg, Icrc1TransferError } from "./canisters/ledger.ts"
+import { ErrorNote } from "./ErrorNote.tsx"
+import { showAmount, useToken, type Token } from "./token.ts"
+import {
+  describeTransferError,
+  readTransferForm,
+  type TransferForm,
+} from "./transfer.ts"
+import { useCanisters } from "./use-canisters.ts"
+
+/** What the ledger deduplicates a transfer on: absent, a re-send could pay twice. */
+export const dedupedBy = (arg: TransferArg) => arg.created_at_time
+
+/** What became of the last transfer sent from a form. */
+interface Kept {
+  variables: TransferArg
+  isPending: boolean
+  data?: bigint
+  error: ReactorError<Icrc1TransferError> | null
+}
+
+/**
+ * `useMutation(client.mutationOptions(ledger, "icrc1_transfer"))`, with the
+ * outcome of the last transfer kept in the form's own state as well. The
+ * options `useClient()` builds are the caller's, and their key with them, so
+ * after an account switch the mutation is a new, idle one, while an unknown
+ * outcome must stay on screen: `client.resendOf` withdraws its offer while
+ * another account is the caller, and makes it again once the sender is back.
+ * The callbacks of the options a run was pressed with are the ones it calls,
+ * so they still reach this state after the switch.
+ */
+export function useTransfer() {
+  const client = useClient()
+  const { ledger } = useCanisters()
+  const [kept, setKept] = useState<Kept>()
+  const options = client.mutationOptions(ledger, "icrc1_transfer")
+  const transfer = useMutation({
+    ...options,
+    onSuccess: (data, variables) =>
+      setKept({ variables, isPending: true, data, error: null }),
+    onError: (error, variables) =>
+      setKept({ variables, isPending: true, error }),
+    // The client's own onSettled re-reads the ledger, the balance included;
+    // the transfer reads as pending until that ends.
+    onSettled: async (...args: Parameters<typeof options.onSettled>) => {
+      try {
+        await options.onSettled(...args)
+      } finally {
+        setKept((last) => last && { ...last, isPending: false })
+      }
+    },
+  })
+  const shown: Kept | undefined =
+    transfer.variables !== undefined
+      ? {
+          variables: transfer.variables,
+          isPending: transfer.isPending,
+          data: transfer.data,
+          error: transfer.error,
+        }
+      : kept
+  // Read on every render: `useAuth()` re-renders this on a switch of account,
+  // and the offer follows the caller.
+  const again = client.resendOf(
+    shown?.error ?? null,
+    ledger,
+    "icrc1_transfer",
+    { dedupedBy }
+  )
+  const mutate = (arg: TransferArg) => {
+    setKept({ variables: arg, isPending: true, error: null })
+    transfer.mutate(arg)
+  }
+  return { shown, again, mutate }
+}
+
+export function SendIcp() {
+  const client = useClient()
+  const { status, principal: caller } = useAuth()
+  const token = useToken()
+  const transfer = useTransfer()
+  const { again } = transfer
+  const [form, setForm] = useState<TransferForm>({ to: "", amount: "" })
+  const [refusal, setRefusal] = useState<{ field: string; reason: string }>()
+  const signedIn = status === "signed-in"
+
+  const onSubmit = (event: FormEvent) => {
+    event.preventDefault()
+    if (token === undefined) return
+    const read = readTransferForm(form, token)
+    if (!read.ok) return setRefusal(read)
+    setRefusal(undefined)
+    // The client signs with whoever is signed in when the mutation runs:
+    // `client.caller()` now, which a switch this render has not caught up
+    // with can make differ from `caller`. Send nothing then.
+    if (client.caller() !== caller) return
+    transfer.mutate(read.arg)
+  }
+
+  return (
+    <section aria-labelledby="send">
+      <p className="scenario">Scenario 5</p>
+      <h2 id="send">Send ICP</h2>
+      <form onSubmit={onSubmit}>
+        <label htmlFor="send-to">To (principal)</label>
+        <input
+          id="send-to"
+          value={form.to}
+          onChange={(e) => setForm({ ...form, to: e.target.value })}
+          spellCheck={false}
+          autoComplete="off"
+          aria-invalid={refusal?.field === "to"}
+        />
+        <label htmlFor="send-amount">
+          Amount{token ? ` (${token.symbol})` : ""}
+        </label>
+        <input
+          id="send-amount"
+          value={form.amount}
+          onChange={(e) => setForm({ ...form, amount: e.target.value })}
+          inputMode="decimal"
+          autoComplete="off"
+          aria-invalid={refusal?.field === "amount"}
+        />
+        {token && (
+          <p className="muted">
+            Fee {showAmount(token.fee, token)}, paid on top of the amount.
+          </p>
+        )}
+        <div className="row">
+          <button
+            type="submit"
+            className="primary"
+            disabled={
+              !signedIn || token === undefined || transfer.shown?.isPending
+            }
+          >
+            Send
+          </button>
+          {!signedIn && <span className="muted">Sign in to send.</span>}
+        </div>
+        {refusal && (
+          <p className="error" role="alert">
+            Not sent: {refusal.field}: {refusal.reason}
+          </p>
+        )}
+      </form>
+      {transfer.shown && token && (
+        <Outcome
+          arg={transfer.shown.variables}
+          token={token}
+          isPending={transfer.shown.isPending}
+          block={transfer.shown.data}
+          error={transfer.shown.error}
+          onSendAgain={again && (() => transfer.mutate(again.arg))}
+        />
+      )}
+    </section>
+  )
+}
+
+/** What became of the last transfer. */
+export function Outcome(props: {
+  /** The argument the last transfer sent. */
+  arg: TransferArg
+  token: Token
+  isPending: boolean
+  block: bigint | undefined
+  error: ReactorError<Icrc1TransferError> | null
+  /** Sends the same transfer again: present only while `client.resendOf` offers it. */
+  onSendAgain: (() => void) | undefined
+}) {
+  const { arg, token, error } = props
+  if (props.isPending) {
+    return (
+      <p className="muted" data-testid="outcome">
+        Sending {showAmount(arg.amount, token)}…
+      </p>
+    )
+  }
+  if (error === null) {
+    return (
+      <p className="ok" data-testid="outcome">
+        Sent {showAmount(arg.amount, token)}: block {props.block?.toString()}.
+      </p>
+    )
+  }
+  return (
+    <div data-testid="outcome">
+      <ErrorNote
+        error={error}
+        refusal={
+          error.kind === "canister_err"
+            ? describeTransferError(error.err, token)
+            : undefined
+        }
+      />
+      {/* Offered by client.resendOf: only after an unknown outcome, and only
+          to the account that sent it, since the ledger deduplicates per
+          sender and the same argument from another account would be a new
+          transfer, paid in full. */}
+      {props.onSendAgain && (
+        <p>
+          <button type="button" onClick={props.onSendAgain}>
+            Send the same transfer again
+          </button>{" "}
+          <span className="muted">
+            Same account, same <code>memo</code> and{" "}
+            <code>created_at_time</code>: if the first one went through, the
+            ledger answers Duplicate instead of paying twice.
+          </span>
+        </p>
+      )}
+    </div>
+  )
+}

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

@@ -0,0 +1,113 @@
+// Scenario 8: paying a contact refreshes the ledger's reads (both balances),
+// and leaves the backend's reads alone: the write changed no backend state.
+import { principal } from "@meantjs/schema"
+import { cleanup, fireEvent, screen, within } from "@testing-library/react"
+import { afterEach, describe, expect, it } from "vitest"
+import { AddressBook } from "./AddressBook.tsx"
+import { Balance } from "./Balance.tsx"
+import {
+  clearEnvCookie,
+  createTestWallet,
+  ICP,
+  patiently,
+  renderWithWallet,
+  SEED_1,
+  SEED_2,
+  type TestWallet,
+} from "./test/test-wallet.tsx"
+
+let wallet: TestWallet | undefined
+afterEach(() => {
+  cleanup()
+  wallet?.client.dispose()
+  clearEnvCookie()
+})
+
+/** Seed 1 holds 7 ICP and knows Grace (seed 2), who holds 2. */
+async function renderPayGrace(): Promise<TestWallet> {
+  const made = createTestWallet()
+  made.setBalance(SEED_1, 7n * ICP)
+  made.setBalance(SEED_2, 2n * ICP)
+  made.addContact(SEED_1, { name: "Grace", owner: principal(SEED_2) })
+  wallet = made
+  renderWithWallet(
+    made,
+    <>
+      <Balance refreshMs={60_000} />
+      <AddressBook />
+    </>
+  )
+  fireEvent.click(
+    await screen.findByRole("button", { name: "Pay Grace" }, patiently)
+  )
+  await screen.findByText(
+    "2 ICP",
+    { selector: "[data-testid=contact-balance]" },
+    patiently
+  )
+  await screen.findByText("7 ICP", {}, patiently)
+  return made
+}
+
+const payForm = () => within(screen.getByRole("group", { name: "Pay Grace" }))
+
+function pay(amount: string) {
+  fireEvent.change(payForm().getByLabelText("Amount (ICP)"), {
+    target: { value: amount },
+  })
+  fireEvent.click(payForm().getByRole("button", { name: "Pay" }))
+}
+
+describe("paying a contact", () => {
+  it("refreshes this account's and the contact's balances, and not the address book", async () => {
+    const made = await renderPayGrace()
+    const contactReads = made.callsOf("contacts")
+
+    pay("1")
+
+    await payForm().findByText("Sent 1 ICP: block 0.", {}, patiently)
+    // Both are reads of icrc1_balance_of, with two arguments: the default
+    // invalidation (every read of the ledger) covered both.
+    await screen.findByText(
+      "3 ICP",
+      { selector: "[data-testid=contact-balance]" },
+      patiently
+    )
+    await screen.findByText("5.9999 ICP", {}, patiently)
+    // The payment changed nothing on the backend, so it was not read again.
+    expect(made.callsOf("contacts")).toBe(contactReads)
+    expect(made.transfers[0]?.to.owner).toBe(SEED_2)
+  })
+
+  it("words the ledger's refusal the way Send does", async () => {
+    await renderPayGrace()
+    pay("100")
+    await payForm().findByText(
+      "Refused by the canister: Insufficient funds: the balance is 7 ICP, less than the amount plus the fee.",
+      {},
+      patiently
+    )
+  })
+
+  it("after a lost reply, re-sends the same payment, memo included, and is answered Duplicate", async () => {
+    const made = await renderPayGrace()
+    made.dropNextReply()
+    pay("1")
+
+    const again = await payForm().findByRole(
+      "button",
+      { name: "Send the same transfer again" },
+      patiently
+    )
+    fireEvent.click(again)
+
+    await payForm().findByText(
+      "Refused by the canister: Duplicate of block 0: this exact transfer went through already, and was not made twice.",
+      { exact: false },
+      patiently
+    )
+    // Paid once: the same argument, memo included, sent twice.
+    expect(made.transfers[1]).toEqual(made.transfers[0])
+    expect(made.balanceOf(SEED_2)).toBe(3n * ICP)
+  })
+})

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

@@ -0,0 +1,102 @@
+// Scenario 8: pay a contact, and refresh what the payment changed.
+//
+// The contact comes from the backend (the address book); the payment is a
+// write to the ledger. Which reads does it change? Only the ledger's: this
+// account's balance, the contact's balance (shown below, a read of the same
+// method with another argument), and the total supply the fee is burned from.
+// So the mutation keeps the client's default, every read of the ledger it
+// writes to, for every caller and every argument, and names no other canister.
+//
+// Listing the backend (`{ invalidates: [ledger, [backend, "contacts"]] }`)
+// would be wrong here: no backend state changes when ICP moves, so it would
+// only read the address book again for nothing. `invalidates` names another
+// canister's reads when a write changes that canister: a backend method that
+// paid out through the ledger itself, for one, would list
+// `{ invalidates: [backend, [ledger, "icrc1_balance_of"]] }`.
+import { useAuth, useClient } from "@ic-reactor/react"
+import { useQuery } from "@tanstack/react-query"
+import { useState, type FormEvent } from "react"
+import type { Contact } from "./canisters/backend.ts"
+import { Outcome, useTransfer } from "./SendIcp.tsx"
+import { showAmount, useToken } from "./token.ts"
+import { readTransferForm } from "./transfer.ts"
+import { useCanisters } from "./use-canisters.ts"
+
+export function SendToContact({ contact }: { contact: Contact }) {
+  const client = useClient()
+  const { ledger } = useCanisters()
+  const { principal: caller } = useAuth()
+  const token = useToken()
+  const theirs = useQuery(
+    client.queryOptions(ledger, "icrc1_balance_of", {
+      owner: contact.owner,
+      subaccount: null,
+    })
+  )
+  // The outcome stays on screen across a switch of account: see `useTransfer`.
+  const pay = useTransfer()
+  const { again } = pay
+  const [amount, setAmount] = useState("")
+  const [refusal, setRefusal] = useState<string>()
+
+  const onPay = (event: FormEvent) => {
+    event.preventDefault()
+    if (token === undefined) return
+    const read = readTransferForm({ to: contact.owner, amount }, token)
+    if (!read.ok) return setRefusal(read.reason)
+    setRefusal(undefined)
+    if (client.caller() !== caller) return
+    pay.mutate(read.arg)
+  }
+
+  return (
+    <div className="pay" aria-label={`Pay ${contact.name}`} role="group">
+      <h3>Pay {contact.name}</h3>
+      <p>
+        {contact.name}&apos;s balance:{" "}
+        <strong data-testid="contact-balance">
+          {theirs.data === undefined || token === undefined
+            ? "…"
+            : showAmount(theirs.data, token)}
+        </strong>
+      </p>
+      <form onSubmit={onPay}>
+        <label htmlFor="pay-amount">
+          Amount{token ? ` (${token.symbol})` : ""}
+        </label>
+        <input
+          id="pay-amount"
+          value={amount}
+          onChange={(e) => setAmount(e.target.value)}
+          inputMode="decimal"
+          autoComplete="off"
+          aria-invalid={refusal !== undefined}
+        />
+        <div className="row">
+          <button
+            type="submit"
+            className="primary"
+            disabled={token === undefined || pay.shown?.isPending}
+          >
+            Pay
+          </button>
+        </div>
+        {refusal && (
+          <p className="error" role="alert">
+            Not sent: {refusal}
+          </p>
+        )}
+      </form>
+      {pay.shown && token && (
+        <Outcome
+          arg={pay.shown.variables}
+          token={token}
+          isPending={pay.shown.isPending}
+          block={pay.shown.data}
+          error={pay.shown.error}
+          onSendAgain={again && (() => pay.mutate(again.arg))}
+        />
+      )}
+    </div>
+  )
+}

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

@@ -0,0 +1,106 @@
+// Scenarios 2 and 3 as a person uses them: the sign-in panel over the app's
+// own auth (wallet-auth.ts), with Internet Identity stood in for by the
+// sign-in of `createTestClient()` (an AuthClient's surface, borrowed from a
+// test client that is never used).
+import { createClient, type Client } from "@ic-reactor/core"
+import { createTestClient } from "@ic-reactor/core/testing"
+import { ReactorProvider } from "@ic-reactor/react"
+import { cleanup, fireEvent, render, screen } from "@testing-library/react"
+import { StrictMode } from "react"
+import { afterEach, describe, expect, it } from "vitest"
+import {
+  createDevAccounts,
+  type AccountStorage,
+  type DevAccounts,
+} from "./auth/dev-accounts.ts"
+import { createWalletAuth } from "./auth/wallet-auth.ts"
+import { SignIn } from "./SignIn.tsx"
+import { SEED_1 } from "./test/test-wallet.tsx"
+
+const memoryStorage = (): AccountStorage => {
+  const map = new Map<string, string>()
+  return {
+    getItem: (key) => map.get(key) ?? null,
+    setItem: (key, value) => void map.set(key, value),
+  }
+}
+
+let client: Client | undefined
+afterEach(() => {
+  cleanup()
+  client?.dispose()
+})
+
+function renderSignIn(devAccounts: DevAccounts | undefined) {
+  const unused = createTestClient({ signedIn: false })
+  unused.client.dispose()
+  const internetIdentity = unused.auth
+  client = createClient({
+    network: "env",
+    auth: () => createWalletAuth({ internetIdentity, devAccounts }),
+    fetch: async () => {
+      throw new Error("the sign-in panel makes no call")
+    },
+  })
+  const made = client
+  render(
+    <StrictMode>
+      <ReactorProvider client={() => made}>
+        <SignIn devAccounts={devAccounts} />
+      </ReactorProvider>
+    </StrictMode>
+  )
+}
+
+const who = () => screen.getByTestId("who").textContent
+const principal = () => screen.getByTestId("principal").textContent
+const click = (name: string | RegExp) =>
+  fireEvent.click(screen.getByRole("button", { name }))
+
+describe("the sign-in panel", () => {
+  it("signs in with a dev account, makes a second one, and switches between them", async () => {
+    const devAccounts = createDevAccounts(memoryStorage())
+    renderSignIn(devAccounts)
+    expect(who()).toBe("nobody")
+    expect(principal()).toBe("2vxsx-fae")
+
+    click("Sign in with a dev account")
+    await screen.findByText("Dev account 1", { selector: "[data-testid=who]" })
+    const first = principal()
+
+    click("New dev account")
+    await screen.findByText("Dev account 2", { selector: "[data-testid=who]" })
+    const second = principal()
+    expect(second).not.toBe(first)
+
+    click("Dev account 1")
+    await screen.findByText("Dev account 1", { selector: "[data-testid=who]" })
+    expect(principal()).toBe(first)
+  })
+
+  it("signs in with Internet Identity, which replaces the dev account, and signs out", async () => {
+    const devAccounts = createDevAccounts(memoryStorage())
+    renderSignIn(devAccounts)
+    click("Sign in with a dev account")
+    await screen.findByText("Dev account 1", { selector: "[data-testid=who]" })
+
+    click("Sign in with Internet Identity")
+    await screen.findByText("Internet Identity", {
+      selector: "[data-testid=who]",
+    })
+    expect(principal()).toBe(SEED_1)
+    expect(devAccounts.getStatus().state).toBe("signed-out")
+
+    click("Sign out")
+    await screen.findByText("nobody", { selector: "[data-testid=who]" })
+    expect(principal()).toBe("2vxsx-fae")
+  })
+
+  it("offers no dev account on a page that is not local", () => {
+    renderSignIn(undefined)
+    expect(screen.queryByText("Dev account (local only)")).toBeNull()
+    expect(
+      screen.getByRole("button", { name: "Sign in with Internet Identity" })
+    ).toBeTruthy()
+  })
+})

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

@@ -0,0 +1,120 @@
+// Scenarios 2 and 3: who is signed in, and how to change it.
+//
+// `useAuth()` follows the client: `status` and `principal` re-render this
+// component once per change, and `signIn`/`signOut` go through the client to
+// its one auth (wallet-auth.ts), which picks the source from the options:
+//
+// - Internet Identity (scenario 2): `signIn({ with: "internet-identity" })`
+//   opens the local Internet Identity in a new window.
+// - Dev account, local only (scenario 3): `signIn({ with: "dev-account",
+//   account })`. Signed in as one dev account, picking another is a switch.
+//
+// `principal` is the anonymous principal (2vxsx-fae) unless `status` is
+// "signed-in", so it can be shown as is.
+import { useAuth } from "@ic-reactor/react"
+import { useState } from "react"
+import type { DevAccounts } from "./auth/dev-accounts.ts"
+import type { SignInChoice } from "./auth/wallet-auth.ts"
+
+export function SignIn({ devAccounts }: { devAccounts?: DevAccounts }) {
+  const { status, principal, signIn, signOut } = useAuth()
+  const [failure, setFailure] = useState<string>()
+  const signedIn = status === "signed-in"
+  const devNumber = signedIn ? devAccounts?.numberOf(principal) : undefined
+  const accounts = devAccounts?.list() ?? []
+
+  const run = (action: () => Promise<void>) => {
+    setFailure(undefined)
+    action().catch((error: unknown) =>
+      setFailure(error instanceof Error ? error.message : String(error))
+    )
+  }
+  const signInWith = (choice: SignInChoice) => run(() => signIn(choice))
+
+  return (
+    <section aria-labelledby="sign-in">
+      <p className="scenario">Scenarios 2 and 3</p>
+      <h2 id="sign-in">Who is signed in</h2>
+      <p>
+        <span className="pill" data-status={status}>
+          {status}
+        </span>{" "}
+        <span data-testid="who">
+          {!signedIn
+            ? "nobody"
+            : devNumber !== undefined
+              ? `Dev account ${devNumber}`
+              : "Internet Identity"}
+        </span>
+      </p>
+      <p>
+        <code data-testid="principal">{principal}</code>
+      </p>
+      {status === "expired" && (
+        <p className="warn">The session expired: sign in again.</p>
+      )}
+      <div className="row">
+        <button
+          type="button"
+          onClick={() => signInWith({ with: "internet-identity" })}
+        >
+          Sign in with Internet Identity
+        </button>
+        <button
+          type="button"
+          disabled={!signedIn}
+          onClick={() => run(() => signOut())}
+        >
+          Sign out
+        </button>
+      </div>
+      {devAccounts && (
+        <>
+          <h3>Dev account (local only)</h3>
+          <p className="muted">
+            An Ed25519 key this tab keeps in sessionStorage: no passkey, for
+            local demos. Fund one with{" "}
+            <code>pnpm faucet &lt;principal&gt;</code>.
+          </p>
+          <div className="row">
+            {accounts.map(({ number }) => (
+              <button
+                key={number}
+                type="button"
+                aria-pressed={devNumber === number}
+                onClick={() =>
+                  signInWith({ with: "dev-account", account: number })
+                }
+              >
+                Dev account {number}
+              </button>
+            ))}
+            <button
+              type="button"
+              onClick={() =>
+                signInWith({
+                  with: "dev-account",
+                  account: accounts.length + 1,
+                })
+              }
+            >
+              {accounts.length === 0
+                ? "Sign in with a dev account"
+                : "New dev account"}
+            </button>
+          </div>
+        </>
+      )}
+      {failure && (
+        <p className="error" role="alert">
+          Sign-in failed: {failure}
+        </p>
+      )}
+      <p className="muted">
+        Every read is cached under its caller&apos;s principal, so a switch
+        starts the next account from an empty cache: one account&apos;s balance,
+        profile or contacts are never shown to another.
+      </p>
+    </section>
+  )
+}