@ic-reactor/mcp 0.0.0-stage → 0.0.0

package/docs/src/content/docs/examples/index.mdx

@@ -0,0 +1,38 @@
+---
+title: Examples
+description: ic-reactor 4 examples
+editUrl: false
+---
+
+import { CardGrid, LinkCard } from "@astrojs/starlight/components"
+
+Examples of ic-reactor 4, each a small app in the repository's `examples/`
+directory on the `main` branch.
+
+<CardGrid>
+  <LinkCard
+    title="ICRC-1 ledger"
+    description="Mainnet ICP ledger reads, archive callbacks, and a sandbox that injects faults into transfers"
+    href="/v4/examples/icrc-ledger"
+  />
+  <LinkCard
+    title="Next.js SSR"
+    description="App Router: a client per request, server prefetch, lossless hydration, streaming, and sign-in after hydration"
+    href="/v4/examples/next-ssr"
+  />
+  <LinkCard
+    title="Vite wallet"
+    description="A React and Vite ICP wallet on a local icp-cli network: Internet Identity, a dev-account sign-in, a backend canister, optimistic updates, and the app deployed to an asset canister with security headers"
+    href="/v4/examples/vite-wallet"
+  />
+  <LinkCard
+    title="Node agent tool"
+    description="A command-line tool for ICRC-1 ledgers, for people and AI agents: direct calls, certified reads, an exit code per error kind, safe re-sends, JSON output"
+    href="/v4/examples/node-agent-tool"
+  />
+  <LinkCard
+    title="Canister Studio"
+    description="TanStack Start SSR: automatic forms and safe calls for any mainnet canister, certified interfaces read live, shared query links and a safety lab"
+    href="/v4/examples/canister-studio"
+  />
+</CardGrid>

package/docs/src/content/docs/examples/next-ssr.mdx

@@ -0,0 +1,73 @@
+---
+title: "Next.js SSR"
+description: Mainnet ICRC-1 ledgers read on the server, hydrated losslessly, and read again as the signed-in user, on ic-reactor 4 and the Next.js App Router
+editUrl: false
+---
+
+import { CardGrid, LinkCard } from "@astrojs/starlight/components"
+
+A Next.js App Router app built on `@ic-reactor/core` and `@ic-reactor/react`
+with TanStack Query's own hooks. It reads the ICP, ckBTC and ckETH ledgers on
+mainnet through one module generated from `icrc1.did` by `meant gen`,
+and shows the server-rendering story end to end:
+
+- **One client per request.** A Server Component builds
+  `createClient({ network: "ic", identity: "anonymous" })` inside the request
+  (React's `cache()`), prefetches every ledger's name, symbol, decimals, fee,
+  total supply, minting account and metadata with `{ id }` targets, and hands
+  `dehydrate(client.queryClient)` to a `<HydrationBoundary>`.
+- **The provider factory in a `'use client'` module.**
+  `<ReactorProvider client={() => createClient({ network: "ic", auth: (network) => new AuthClient(network) })}>`
+  builds a client per mounted tree. The server render and the browser's
+  hydrating render build keys for the anonymous principal, so every visitor
+  gets the server's keys, a tab still signed in from an earlier visit
+  included, and the cards hydrate from them with nothing fetched on load.
+- **Lossless hydration.** `bigint` amounts, principals and `Uint8Array`
+  values arrive exact; the page prints each value's run-time type.
+- **No JavaScript needed** to read the pages: the values are in the server's
+  HTML, which a smoke script checks against a running `next start`.
+- **Streaming.** On the account page, certified balances (replicated calls)
+  stream in after the rest of the page, from an async Server Component inside
+  `<Suspense>`.
+- **Progressive enhancement.** The account lookup is a GET form validated on
+  the server with `isPrincipal` and `principal()`.
+- **A Route Handler** with its own client per request answers JSON, with
+  amounts as decimal text and base units, and maps a `ReactorError` to an
+  HTTP status by its `kind`, reading `httpStatus` where the kind is not enough:
+  a canister that does not exist is a 502, not a 503 that invites a retry.
+- **Errors on the server.** A canister that is not a ledger renders its own
+  section with the error's `kind`; the rest of the page renders as usual.
+- **Sign-in after hydration.** Signing in with Internet Identity moves every
+  read to keys that hold the user's principal; nothing read anonymously is
+  reused for them. A tab that reloads signed in hydrates without a mismatch,
+  then reads its own keys the same way.
+
+The tests run the real client on `createTestClient()` from
+`@ic-reactor/core/testing`, with the ledgers mocked over in-memory replicas,
+and never reach mainnet.
+
+The [SSR and hydration guide](/v4/guides/ssr/) explains each rule, and
+[Auth](/v4/guides/auth/) covers sign-in and the caller.
+[Render a server page for one user](/v4/build/ssr-per-user/) builds one
+account's page step by step, in a new Next.js app with Cache Components.
+
+StackBlitz installs the example from npm and runs the tests (`npm test`):
+you can read and change the code there and run them again. It cannot serve
+the app. Next 16 keeps each request's state in Node's `AsyncLocalStorage`,
+which StackBlitz does not implement, so `next dev` fails there on every page
+with Next's own "Invariant: Expected workStore to be initialized", and a
+production build renders through the same storage. Clone the repository to
+run the app.
+
+<CardGrid>
+  <LinkCard
+    title="Open in StackBlitz"
+    description="Read the code and run the tests in your browser (not the app)"
+    href="https://stackblitz.com/github/b3pay/ic-reactor/tree/main/examples/next-ssr?file=src/app/page.tsx"
+  />
+  <LinkCard
+    title="View on GitHub"
+    description="Browse the source code"
+    href="https://github.com/b3pay/ic-reactor/tree/main/examples/next-ssr"
+  />
+</CardGrid>

package/docs/src/content/docs/examples/node-agent-tool.mdx

@@ -0,0 +1,80 @@
+---
+title: "Node agent tool"
+description: A command-line tool for ICRC-1 ledgers, for people and AI agents, on @ic-reactor/core outside React
+editUrl: false
+---
+
+import { CardGrid, LinkCard } from "@astrojs/starlight/components"
+
+A command-line tool for ICRC-1 ledgers that a person or an AI agent runs with
+Node 22.18 or newer (`node src/cli.ts <command>`, no build step). It is
+`@ic-reactor/core` with no React at all, one scenario per file:
+
+- **Identity:** a fixed `Identity` from a PEM file (Ed25519 or secp256k1, as
+  `icp identity export` prints it) or a hex seed, else
+  `identity: "anonymous"`, whose writes the client refuses before sending.
+  Give it an identity of its own that holds little and controls nothing
+  (`icp identity new agent-tool --output-seed <file>`, which writes the seed
+  phrase to a file instead of printing it, or `pnpm exec icp` inside the
+  example),
+  never one that controls a canister, and export its key outside the
+  project, readable by you alone. An agent that runs the tool can read its
+  environment, the seed variable included, and so can sign whatever the tool
+  can.
+- **Networks:** `--network ic|local|<url>` onto `createClient`'s `network`. A
+  root key is fetched only from a replica on this machine; any other URL needs
+  the key given.
+- **Many ledgers, one interface:** ICP, ckBTC, ckETH or any ledger id, each
+  `client.canister<Actor>(actor, { id })` over one generated module.
+- **Direct calls:** `info` and `balance` call the ledger's methods directly,
+  in parallel; `--certified` reads through `{ id, certified: true }`.
+- **Writes:** `transfer` reads the amount with `parseUnits`, pays the ledger's
+  fee and sets `created_at_time`. Every failure goes through `isReactorError`
+  and a `kind` switch, with an exit code per kind. After a failure that may
+  have executed, it reads the balance back and prints the command that
+  re-sends the same argument, which the ledger answers `Duplicate` if the
+  first went through.
+- **JSON for agents:** `--json` on every command, one document per line,
+  bigints as decimal strings, failures as
+  `{ ok: false, kind, mayHaveExecuted, message }`.
+- **The cache outside React:** `watch` polls a balance through
+  `client.queryClient.fetchQuery(client.queryOptions(...))`, prints only
+  changes, and disposes the client on Ctrl-C.
+- **Every failure, narrated:** `pnpm demo` runs the same commands on
+  `createTestClient()` from `@ic-reactor/core/testing`, with a mocked ledger:
+  a lost reply and its deduplicated re-send, an HTTP 429 the client re-sends
+  by itself, a canister reject, a signed-out write, and input refused before
+  sending. No network, no funds.
+
+Read [The client](/v4/guides/client/) and
+[Errors and mayHaveExecuted](/v4/guides/errors/) for the rules it follows, and
+[Testing](/v4/guides/testing/) for `createTestClient()`.
+[Give an agent a canister's tools](/v4/build/agent-tools/) builds the same
+ledger as MCP tools, step by step.
+
+```sh
+pnpm --filter node-agent-tool demo
+cd examples/node-agent-tool
+node src/cli.ts info --ledger ckbtc
+node src/cli.ts balance rkp4c-7iaaa-aaaaa-aaaca-cai --certified --json
+pnpm test
+```
+
+StackBlitz installs the example from npm and runs the demo (`npm run demo`)
+in its terminal, where `npm test` runs the tests. The demo and the CLI run
+their `.ts` files with Node's type stripping, so they need Node 22.18 or later,
+there as on your machine. The commands that call a ledger on mainnet or on a
+local network, and a PEM identity from your disk, are for your own machine.
+
+<CardGrid>
+  <LinkCard
+    title="Open in StackBlitz"
+    description="Run the demo and the tests in your browser"
+    href="https://stackblitz.com/github/b3pay/ic-reactor/tree/main/examples/node-agent-tool?file=src/commands/transfer.ts"
+  />
+  <LinkCard
+    title="View on GitHub"
+    description="Browse the source code"
+    href="https://github.com/b3pay/ic-reactor/tree/main/examples/node-agent-tool"
+  />
+</CardGrid>

package/docs/src/content/docs/examples/vite-wallet.mdx

@@ -0,0 +1,71 @@
+---
+title: "Vite wallet"
+description: A React and Vite ICP wallet on a local icp-cli network, with Internet Identity, a backend canister and optimistic updates on ic-reactor 4
+editUrl: false
+---
+
+import { CardGrid, LinkCard } from "@astrojs/starlight/components"
+
+An ICP wallet built with React and Vite on `@ic-reactor/core`,
+`@ic-reactor/react` and `@ic-reactor/vite-plugin`, against a local icp-cli
+network that runs the NNS ICP ledger, Internet Identity and a small Rust
+backend canister of the example's own.
+
+- **The page's network:** one client per tab,
+  `createClient({ network: "env", auth })`. The Vite plugin sets the `ic_env`
+  cookie and proxies `/api` to the local network, so the backend is called as
+  `{ name: "backend" }` and the ledger by its `{ id }`. A panel shows the id
+  the client resolved and the cookie it came from.
+- **Two ways to sign in, one client:** Internet Identity through
+  `@icp-sdk/auth`'s `AuthClient`, built with
+  `(network) => new AuthClient(network)` from the network the client hands it
+  (the local II on a local page), and a "dev account" of the app's own, an
+  `AuthLike` holding an Ed25519 key, offered only on a local page. Switching
+  accounts shows the next account nothing of the last.
+- **Reads and writes:** the balance with `skipToken` while signed out and a
+  `refetchInterval`, so a top-up from the example's faucet shows by itself;
+  ICP transfers with `parseUnits`, the fee, deduplication by `created_at_time`
+  and a `memo` per transfer, typed ledger errors and the
+  unknown-outcome path, where `client.resendOf` offers the same transfer
+  again to its sender only; a profile write refused before sending while
+  signed out.
+- **Optimistic updates:** an address book whose adds and removes show at once
+  and roll back on a refusal or a failure, while the client's own
+  invalidation still runs; paying a contact refreshes both balances and not
+  the address book. The address book is a certified read, because a contact
+  decides where a payment goes.
+- **Deployed with security headers:** `pnpm icp:deploy` also serves the
+  production build from an asset canister, with the Content-Security-Policy,
+  `Cross-Origin-Opener-Policy` and raw-domain redirect of
+  [Deploy to a frontend canister](/v4/guides/deploy/).
+
+The guides behind it: [Auth](/v4/guides/auth/) for the two sign-in sources,
+[Writes](/v4/guides/writes/) for transfers and optimistic updates,
+[Reads](/v4/guides/reads/#what-to-certify) for what to certify, and
+[the Vite plugin](/v4/guides/vite-plugin/) for the cookie and the `/api` proxy.
+[Build an ICRC-1 wallet](/v4/build/icrc1-wallet/) builds its sign-in, balance
+and transfer step by step, against mainnet.
+
+Every scenario has tests on `createTestClient()` that run without a replica
+(`pnpm test`). To run the wallet itself you need icp-cli's local network,
+which the example installs (`pnpm icp:start`, `pnpm icp:deploy`,
+`pnpm dev`), and the Rust toolchain for the backend; see its README.
+
+StackBlitz installs the example from npm and runs those tests (`npm test`):
+you can read and change the code there and run them again. It cannot run the
+wallet itself. icp-cli's local network is a native binary, which StackBlitz
+does not run, and the backend needs the Rust toolchain, so the page it would
+serve has no network to call. Clone the repository to run the wallet.
+
+<CardGrid>
+  <LinkCard
+    title="Open in StackBlitz"
+    description="Read the code and run the tests in your browser (not the wallet)"
+    href="https://stackblitz.com/github/b3pay/ic-reactor/tree/main/examples/vite-wallet?file=src/App.tsx"
+  />
+  <LinkCard
+    title="View on GitHub"
+    description="Browse the source code"
+    href="https://github.com/b3pay/ic-reactor/tree/main/examples/vite-wallet"
+  />
+</CardGrid>