@ic-reactor/mcp 0.0.0-stage → 0.0.0

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

@@ -0,0 +1,191 @@
+// Scenario 7: optimistic adds and removes, rolled back on a refusal or a
+// failure, with the client's own invalidation still run after each one.
+import { principal } from "@meantjs/schema"
+import {
+  cleanup,
+  fireEvent,
+  screen,
+  waitFor,
+  within,
+} from "@testing-library/react"
+import { afterEach, describe, expect, it } from "vitest"
+import { AddressBook } from "./AddressBook.tsx"
+import {
+  BOB,
+  clearEnvCookie,
+  createTestWallet,
+  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's address book holds Bob. */
+async function renderBook(): Promise<TestWallet> {
+  const made = createTestWallet()
+  made.addContact(SEED_1, { name: "Bob", owner: principal(BOB) })
+  wallet = made
+  renderWithWallet(made, <AddressBook />)
+  await screen.findByText("Bob", {}, patiently)
+  return made
+}
+
+/** The names the list shows, in order. */
+const names = () =>
+  within(screen.getByRole("list", { name: "Contacts" }))
+    .queryAllByRole("listitem")
+    .map((item) => item.querySelector("strong")?.textContent)
+
+function add(name: string, owner: string) {
+  fireEvent.change(screen.getByLabelText("Name"), { target: { value: name } })
+  fireEvent.change(screen.getByLabelText("Principal"), {
+    target: { value: owner },
+  })
+  fireEvent.click(screen.getByRole("button", { name: "Add contact" }))
+}
+
+describe("the address book", () => {
+  it("reads the list certified, as a replicated call: a contact decides where a payment goes", async () => {
+    const made = await renderBook()
+    const release = made.holdNext("add_contact")
+    add("Carol", SEED_2)
+    release()
+    await waitFor(
+      () => expect(screen.queryByText("saving…")).toBeNull(),
+      patiently
+    )
+
+    // The first read and the one after the write: never a plain query.
+    const reads = made.requests.filter((r) => r.methodName === "contacts")
+    expect(reads.length).toBeGreaterThanOrEqual(2)
+    expect(reads.map((r) => r.endpoint)).toEqual(reads.map(() => "call"))
+  })
+
+  it("shows an added contact before the backend answers, then reads the list again", async () => {
+    const made = await renderBook()
+    const release = made.holdNext("add_contact")
+    const reads = made.callsOf("contacts")
+
+    add("Carol", SEED_2)
+
+    // The backend holds the call: the list already shows Carol.
+    await waitFor(() => expect(names()).toEqual(["Bob", "Carol"]))
+    expect(screen.getByText("saving…")).toBeTruthy()
+    expect(made.contactsOf(SEED_1).map((c) => c.name)).toEqual(["Bob"])
+
+    release()
+
+    await waitFor(
+      () => expect(screen.queryByText("saving…")).toBeNull(),
+      patiently
+    )
+    expect(names()).toEqual(["Bob", "Carol"])
+    // The client's onSettled ran: it invalidated the list, which was read again.
+    expect(made.callsOf("contacts")).toBeGreaterThan(reads)
+  })
+
+  it("rolls an add back when the backend refuses it (canister_err), and says why", async () => {
+    const made = await renderBook()
+    const release = made.holdNext("add_contact")
+    const reads = made.callsOf("contacts")
+
+    add("bob", SEED_2)
+    await waitFor(() => expect(names()).toEqual(["Bob", "bob"]))
+    // The re-read the client asks for after the refusal is held, so what
+    // the list shows next comes from the rollback alone.
+    const releaseReread = made.holdNext("contacts")
+    release()
+
+    await waitFor(() => expect(names()).toEqual(["Bob"]), patiently)
+    releaseReread()
+    await screen.findByText(
+      'Refused by the canister: "bob" is in the address book already. The list is back as it was.',
+      {},
+      patiently
+    )
+    expect(names()).toEqual(["Bob"])
+    // A canister_err still invalidates: the backend may have changed state first.
+    expect(made.callsOf("contacts")).toBeGreaterThan(reads)
+  })
+
+  it("rolls an add back when the call traps, says the outcome is unknown, and reads the list again", async () => {
+    const made = await renderBook()
+    const release = made.holdNext("add_contact")
+    const reads = made.callsOf("contacts")
+    made.failNext("add_contact", "trap")
+
+    add("Carol", SEED_2)
+    await waitFor(() => expect(names()).toEqual(["Bob", "Carol"]))
+    const releaseReread = made.holdNext("contacts")
+    release()
+
+    await waitFor(() => expect(names()).toEqual(["Bob"]), patiently)
+    releaseReread()
+    await screen.findByText(/^Outcome unknown \(rejected\)/, {}, patiently)
+    expect(names()).toEqual(["Bob"])
+    expect(made.callsOf("contacts")).toBeGreaterThan(reads)
+    expect(made.contactsOf(SEED_1).map((c) => c.name)).toEqual(["Bob"])
+  })
+
+  it("removes a contact at once, and keeps it removed once the backend agrees", async () => {
+    const made = await renderBook()
+    const release = made.holdNext("remove_contact")
+
+    fireEvent.click(screen.getByRole("button", { name: "Remove Bob" }))
+
+    await screen.findByTestId("no-contacts")
+    release()
+    await waitFor(() => expect(made.contactsOf(SEED_1)).toEqual([]), patiently)
+    await waitFor(() => expect(made.callsOf("remove_contact")).toBe(1))
+    expect(screen.getByTestId("no-contacts")).toBeTruthy()
+  })
+
+  it("puts a removed contact back when the backend refuses, then shows what it really holds", async () => {
+    const made = await renderBook()
+    const release = made.holdNext("remove_contact")
+    // Removed elsewhere (another tab), so this page's remove is refused.
+    made.removeContact(SEED_1, "Bob")
+
+    fireEvent.click(screen.getByRole("button", { name: "Remove Bob" }))
+    await screen.findByTestId("no-contacts")
+    const releaseReread = made.holdNext("contacts")
+    release()
+
+    // Rolled back first: Bob is shown again while the re-read is held.
+    await screen.findByText("Bob", {}, patiently)
+    releaseReread()
+    await screen.findByText(
+      'Refused by the canister: no contact is named "Bob". The list is back as it was.',
+      {},
+      patiently
+    )
+    // Then the client's re-read shows the backend's own list.
+    await screen.findByTestId("no-contacts", {}, patiently)
+  })
+
+  it("shows the error of the last write only", async () => {
+    const made = await renderBook()
+    made.addContact(SEED_1, { name: "Carol", owner: principal(SEED_2) })
+    add("bob", SEED_2)
+    const refused =
+      'Refused by the canister: "bob" is in the address book already. The list is back as it was.'
+    await screen.findByText(refused, {}, patiently)
+
+    fireEvent.click(screen.getByRole("button", { name: "Remove Bob" }))
+
+    await waitFor(
+      () =>
+        expect(made.contactsOf(SEED_1).map((c) => c.name)).toEqual(["Carol"]),
+      patiently
+    )
+    await waitFor(() => expect(screen.queryByText(refused)).toBeNull())
+  })
+})

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

@@ -0,0 +1,147 @@
+// Scenario 7: the address book, with optimistic adds and removes.
+//
+// The list is `useQuery(client.queryOptions(certifiedBackend, "contacts"))`,
+// skipped while signed out. It is a certified read: a contact decides where a
+// payment goes, so one replica's word is not enough (use-canisters.ts).
+// Adding or removing a contact changes it at once
+// (optimistic-contacts.ts); a refusal from the backend (a duplicate or an
+// invalid name) or a failure puts it back as it was, and says why. Each row
+// can be paid (scenario 8, SendToContact.tsx).
+import { isPrincipal, principal } from "@meantjs/schema"
+import { useAuth, useClient } from "@ic-reactor/react"
+import { skipToken, useQuery } from "@tanstack/react-query"
+import { useState, type FormEvent } from "react"
+import { ErrorNote } from "./ErrorNote.tsx"
+import { useAddContact, useRemoveContact } from "./optimistic-contacts.ts"
+import { describeRefusal } from "./refusal.ts"
+import { SendToContact } from "./SendToContact.tsx"
+import { shortPrincipal } from "./token.ts"
+import { useCanisters } from "./use-canisters.ts"
+
+export function AddressBook() {
+  const client = useClient()
+  const { certifiedBackend } = useCanisters()
+  const { status } = useAuth()
+  const signedIn = status === "signed-in"
+  const contacts = useQuery(
+    client.queryOptions(
+      certifiedBackend,
+      "contacts",
+      signedIn ? undefined : skipToken
+    )
+  )
+  const add = useAddContact()
+  const remove = useRemoveContact()
+  const [name, setName] = useState("")
+  const [owner, setOwner] = useState("")
+  const [paying, setPaying] = useState<string>()
+  // Typed text is checked in render with `isPrincipal`, and turned into a
+  // `Principal` only by `principal()`, never cast.
+  const ownerIsPrincipal = isPrincipal(owner.trim())
+
+  const onAdd = (event: FormEvent) => {
+    event.preventDefault()
+    if (!ownerIsPrincipal) return
+    add.mutate({ name, owner: principal(owner.trim()) })
+  }
+
+  // The error of the write sent last: an earlier refusal is not news.
+  const failure =
+    add.submittedAt >= remove.submittedAt ? add.error : remove.error
+  const payee = contacts.data?.find((contact) => contact.name === paying)
+
+  return (
+    <section aria-labelledby="contacts">
+      <p className="scenario">Scenarios 7 and 8</p>
+      <h2 id="contacts">Address book</h2>
+      {!signedIn ? (
+        <p className="muted">Sign in to see your contacts.</p>
+      ) : contacts.isError ? (
+        <ErrorNote error={contacts.error} />
+      ) : contacts.data === undefined ? (
+        <p className="muted">…</p>
+      ) : contacts.data.length === 0 ? (
+        <p className="muted" data-testid="no-contacts">
+          No contacts yet.
+        </p>
+      ) : (
+        <ul className="contacts" aria-label="Contacts">
+          {contacts.data.map((contact, index) => (
+            // By position: an optimistic add of a name the backend will
+            // refuse as a duplicate shows two rows of that name for a moment.
+            <li key={`${index}:${contact.name}`}>
+              <span>
+                <strong>{contact.name}</strong>{" "}
+                <code title={contact.owner}>
+                  {shortPrincipal(contact.owner)}
+                </code>
+                {add.isPending && add.variables.name === contact.name && (
+                  <span className="muted"> saving…</span>
+                )}
+              </span>
+              <span className="row">
+                <button
+                  type="button"
+                  aria-pressed={paying === contact.name}
+                  onClick={() =>
+                    setPaying(
+                      paying === contact.name ? undefined : contact.name
+                    )
+                  }
+                >
+                  Pay {contact.name}
+                </button>
+                <button
+                  type="button"
+                  onClick={() => remove.mutate(contact.name)}
+                >
+                  Remove {contact.name}
+                </button>
+              </span>
+            </li>
+          ))}
+        </ul>
+      )}
+      {failure && (
+        <ErrorNote
+          error={failure}
+          refusal={
+            failure.kind === "canister_err"
+              ? `${describeRefusal(failure.err)} The list is back as it was.`
+              : undefined
+          }
+        />
+      )}
+      <form onSubmit={onAdd}>
+        <div className="pair">
+          <div>
+            <label htmlFor="contact-name">Name</label>
+            <input
+              id="contact-name"
+              value={name}
+              onChange={(e) => setName(e.target.value)}
+              autoComplete="off"
+            />
+          </div>
+          <div>
+            <label htmlFor="contact-owner">Principal</label>
+            <input
+              id="contact-owner"
+              value={owner}
+              onChange={(e) => setOwner(e.target.value)}
+              spellCheck={false}
+              autoComplete="off"
+              aria-invalid={owner !== "" && !ownerIsPrincipal}
+            />
+          </div>
+        </div>
+        <div className="row">
+          <button type="submit" disabled={!signedIn || !ownerIsPrincipal}>
+            Add contact
+          </button>
+        </div>
+      </form>
+      {payee && <SendToContact key={payee.name} contact={payee} />}
+    </section>
+  )
+}

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

@@ -0,0 +1,53 @@
+// The wallet: one client per tab, and one section per scenario.
+import { ReactorProvider, useAuth } from "@ic-reactor/react"
+import { Fragment } from "react"
+import { AddressBook } from "./AddressBook.tsx"
+import type { DevAccounts } from "./auth/dev-accounts.ts"
+import { Balance } from "./Balance.tsx"
+import { createWalletClient } from "./client.ts"
+import { EnvironmentPanel } from "./EnvironmentPanel.tsx"
+import { Profile } from "./Profile.tsx"
+import { SendIcp } from "./SendIcp.tsx"
+import { SignIn } from "./SignIn.tsx"
+
+export function App({ devAccounts }: { devAccounts?: DevAccounts }) {
+  return (
+    // The factory creates the client, so the provider owns it: built once
+    // per mounted tree (React may call the factory twice in development and
+    // keep one), disposed with its auth and cache when the tree unmounts.
+    <ReactorProvider client={() => createWalletClient(devAccounts)}>
+      <Wallet devAccounts={devAccounts} />
+    </ReactorProvider>
+  )
+}
+
+/** The page, on whichever client the provider above it holds. */
+export function Wallet({ devAccounts }: { devAccounts?: DevAccounts }) {
+  const { principal } = useAuth()
+  return (
+    <main>
+      <h1>ICP wallet on ic-reactor 4</h1>
+      <p className="lede">
+        A React and Vite app on a local icp-cli network: an ICP ledger, a
+        backend canister of its own, Internet Identity, and TanStack
+        Query&apos;s own hooks with the options the client builds.
+      </p>
+      <EnvironmentPanel />
+      <SignIn devAccounts={devAccounts} />
+      {/*
+        The account's own sections, mounted again whenever the caller
+        changes. Their reads are keyed by the caller already, but what they
+        keep in component state is not: a form, the last transfer's outcome
+        (an InsufficientFunds error carries that account's balance), a
+        mutation's error. Keyed by the principal, none of it is shown to the
+        next account, or to nobody after a sign-out.
+      */}
+      <Fragment key={principal}>
+        <Balance />
+        <SendIcp />
+        <Profile />
+        <AddressBook />
+      </Fragment>
+    </main>
+  )
+}

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

@@ -0,0 +1,57 @@
+// Scenario 4: the balance, skipped while signed out, read again on its own.
+import { act, cleanup, screen } from "@testing-library/react"
+import { afterEach, describe, expect, it } from "vitest"
+import { Balance } from "./Balance.tsx"
+import {
+  clearEnvCookie,
+  createTestWallet,
+  ICP,
+  patiently,
+  renderWithWallet,
+  SEED_1,
+  type TestWallet,
+} from "./test/test-wallet.tsx"
+
+let wallet: TestWallet | undefined
+afterEach(() => {
+  cleanup()
+  wallet?.client.dispose()
+  clearEnvCookie()
+})
+
+describe("the balance", () => {
+  it("sends no read while signed out (skipToken), and reads once signed in", async () => {
+    wallet = createTestWallet({ signedIn: false })
+    wallet.setBalance(SEED_1, 3n * ICP)
+    renderWithWallet(wallet, <Balance refreshMs={50} />)
+    // Long enough for several intervals: none of them sends a read.
+    await new Promise((resolve) => setTimeout(resolve, 200))
+    expect(screen.getByTestId("balance").textContent).toContain("skipToken")
+    expect(wallet.callsOf("icrc1_balance_of")).toBe(0)
+
+    const signedOut = wallet
+    await act(async () => {
+      await signedOut.auth.signIn(1)
+    })
+    await screen.findByText("3 ICP", {}, patiently)
+  })
+
+  it("shows a top-up by itself, with no click: refetchInterval on the client's options", async () => {
+    wallet = createTestWallet()
+    wallet.setBalance(SEED_1, 3n * ICP)
+    renderWithWallet(wallet, <Balance refreshMs={50} />)
+    await screen.findByText("3 ICP", {}, patiently)
+
+    // `pnpm faucet <principal>`, from outside the page.
+    wallet.setBalance(SEED_1, 13n * ICP)
+
+    await screen.findByText("13 ICP", {}, patiently)
+  })
+
+  it("shows the command that funds this account", async () => {
+    wallet = createTestWallet()
+    renderWithWallet(wallet, <Balance />)
+    await screen.findByText("0 ICP", {}, patiently)
+    expect(screen.getByText(`pnpm faucet ${SEED_1}`)).toBeTruthy()
+  })
+})

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

@@ -0,0 +1,58 @@
+// Scenario 4: the signed-in account's ICP balance, kept current.
+//
+// - `useQuery(client.queryOptions(ledger, "icrc1_balance_of", account))`:
+//   the key holds the caller, so each account's balance is cached apart.
+// - `skipToken` while nobody is signed in: there is no account to read yet,
+//   so nothing is sent (no placeholder account, no `owner!`).
+// - `refetchInterval` spread onto the client's options ("spread to add
+//   options"), so ICP sent from `pnpm faucet` shows up by itself.
+import { principal } from "@meantjs/schema"
+import { useAuth, useClient } from "@ic-reactor/react"
+import { skipToken, useQuery } from "@tanstack/react-query"
+import { ErrorNote } from "./ErrorNote.tsx"
+import { showAmount, useToken } from "./token.ts"
+import { useCanisters } from "./use-canisters.ts"
+
+export function Balance({ refreshMs = 3_000 }: { refreshMs?: number }) {
+  const client = useClient()
+  const { ledger } = useCanisters()
+  const { status, principal: caller } = useAuth()
+  const token = useToken()
+  const signedIn = status === "signed-in"
+  const balance = useQuery({
+    ...client.queryOptions(
+      ledger,
+      "icrc1_balance_of",
+      signedIn ? { owner: principal(caller), subaccount: null } : skipToken
+    ),
+    refetchInterval: refreshMs,
+  })
+
+  return (
+    <section aria-labelledby="balance">
+      <p className="scenario">Scenario 4</p>
+      <h2 id="balance">Balance</h2>
+      {!signedIn ? (
+        <p className="muted" data-testid="balance">
+          Sign in to see a balance: the read waits (skipToken) until there is an
+          account.
+        </p>
+      ) : balance.isError ? (
+        <ErrorNote error={balance.error} />
+      ) : (
+        <>
+          <p className="big" data-testid="balance">
+            {balance.data === undefined || token === undefined
+              ? "…"
+              : showAmount(balance.data, token)}
+          </p>
+          <p className="muted">
+            Read again every {refreshMs / 1000} s. Top it up from another
+            terminal and watch it change:
+          </p>
+          <pre>pnpm faucet {caller}</pre>
+        </>
+      )}
+    </section>
+  )
+}

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

@@ -0,0 +1,83 @@
+// Scenario 1: `network: "env"` and `{ name: "backend" }` from the ic_env
+// cookie, on jsdom's local page (http://localhost:3000).
+import { cleanup, screen, waitFor } from "@testing-library/react"
+import { afterEach, describe, expect, it } from "vitest"
+import { EnvironmentPanel } from "./EnvironmentPanel.tsx"
+import {
+  BACKEND_ID,
+  clearEnvCookie,
+  createTestWallet,
+  patiently,
+  renderWithWallet,
+  setEnvCookie,
+  type TestWallet,
+} from "./test/test-wallet.tsx"
+import { ICP_LEDGER } from "./use-canisters.ts"
+
+let wallet: TestWallet | undefined
+afterEach(() => {
+  cleanup()
+  wallet?.client.dispose()
+  clearEnvCookie()
+})
+
+describe("the environment panel", () => {
+  it("routes through the page's origin and finds the backend by its name in the cookie", async () => {
+    wallet = createTestWallet({ signedIn: false })
+    renderWithWallet(wallet, <EnvironmentPanel />)
+
+    expect(screen.getByTestId("network").textContent).toBe(
+      "http://localhost:3000"
+    )
+    expect(screen.getByTestId("backend-id").textContent).toBe(BACKEND_ID)
+    expect(screen.getByTestId("ledger-id").textContent).toBe(ICP_LEDGER)
+    await waitFor(
+      () =>
+        expect(screen.getByTestId("backend-probe").textContent).toBe(
+          "yes: contacts() as anonymous gave 0"
+        ),
+      patiently
+    )
+    // The probe went to the id the cookie named, and to no other canister.
+    const backendCalls = wallet.requests.filter(
+      (r) => r.methodName === "contacts"
+    )
+    expect(backendCalls.length).toBeGreaterThan(0)
+    expect(backendCalls.every((r) => r.canisterId === BACKEND_ID)).toBe(true)
+    expect(screen.getByTestId("cookie").textContent).toContain(
+      `PUBLIC_CANISTER_ID:backend: ${BACKEND_ID}`
+    )
+  })
+
+  it("names an undeployed backend unresolved and sends nothing to it", async () => {
+    // A cookie that names the ledger only: the backend was never deployed.
+    wallet = createTestWallet({ signedIn: false, cookie: false })
+    setEnvCookie({ ledger: ICP_LEDGER })
+    renderWithWallet(wallet, <EnvironmentPanel />)
+
+    expect(screen.getByTestId("backend-id").textContent).toBe(
+      "$unresolved:backend"
+    )
+    await screen.findByText(
+      "Not sent: the ic_env cookie names no backend. Deploy it (pnpm icp:deploy), then reload the page.",
+      {},
+      patiently
+    )
+    expect(wallet.callsOf("contacts")).toBe(0)
+  })
+
+  it("reads the cookie when a key or a call is built, so a redeploy's new id is used", () => {
+    wallet = createTestWallet({ signedIn: false })
+    const { client } = wallet
+    renderWithWallet(wallet, <EnvironmentPanel />)
+    expect(screen.getByTestId("backend-id").textContent).toBe(BACKEND_ID)
+
+    // `icp deploy` into a fresh network, and the page loaded again.
+    const redeployed = "be2us-64aaa-aaaaa-qaabq-cai"
+    setEnvCookie({ backend: redeployed, ledger: ICP_LEDGER })
+    cleanup()
+    renderWithWallet(wallet, <EnvironmentPanel />)
+    expect(screen.getByTestId("backend-id").textContent).toBe(redeployed)
+    expect(client.network).toBe("http://localhost:3000")
+  })
+})