@ic-reactor/mcp 0.0.0-stage → 0.0.0

package/examples/next-ssr/src/canisters/icrc1.ts

@@ -0,0 +1,78 @@
+// Generated by Meant from a Meant Contract. Do not edit.
+import * as $ from "@meantjs/schema";
+
+export type Account = { owner: $.Principal; subaccount: Uint8Array | null };
+const $Account: $.Schema<Account> = $.c.rec(() => $.c.record({ owner: $.c.principal, subaccount: $.c.opt($.c.blob()) }));
+export { $Account as Account };
+
+export type BlockIndex = bigint;
+const $BlockIndex: $.Schema<BlockIndex> = $.c.rec(() => $.c.nat);
+export { $BlockIndex as BlockIndex };
+
+/** Number of nanoseconds between two [Timestamp]s. */
+export type Duration = bigint;
+/** Number of nanoseconds between two [Timestamp]s. */
+const $Duration: $.Schema<Duration> = $.c.rec(() => $.c.nat64);
+export { $Duration as Duration };
+
+/** The initialization parameters of the Ledger */
+export type InitArgs = { token_symbol: string; transfer_fee: bigint; metadata: Array<[string, Value]>; minting_account: Account; initial_balances: Array<[Account, bigint]>; archive_options: { num_blocks_to_archive: bigint; trigger_threshold: bigint; max_message_size_bytes: bigint | null; cycles_for_archive_creation: bigint | null; node_max_memory_size_bytes: bigint | null; controller_id: $.Principal }; token_name: string };
+/** The initialization parameters of the Ledger */
+const $InitArgs: $.Schema<InitArgs> = $.c.rec(() => $.c.record({ token_symbol: $.c.text, transfer_fee: $.c.nat64, metadata: $.c.vec($.c.tuple([$.c.text, $Value])), minting_account: $Account, initial_balances: $.c.vec($.c.tuple([$Account, $.c.nat64])), archive_options: $.c.record({ num_blocks_to_archive: $.c.nat64, trigger_threshold: $.c.nat64, max_message_size_bytes: $.c.opt($.c.nat64), cycles_for_archive_creation: $.c.opt($.c.nat64), node_max_memory_size_bytes: $.c.opt($.c.nat64), controller_id: $.c.principal }), token_name: $.c.text }));
+export { $InitArgs as InitArgs };
+
+export type LedgerArg = { tag: "Upgrade"; value: UpgradeArgs | null } | { tag: "Init"; value: InitArgs };
+const $LedgerArg: $.Schema<LedgerArg> = $.c.rec(() => $.c.variant({ Upgrade: $.c.opt($UpgradeArgs), Init: $InitArgs }));
+export { $LedgerArg as LedgerArg };
+
+export type Subaccount = Uint8Array;
+const $Subaccount: $.Schema<Subaccount> = $.c.rec(() => $.c.blob());
+export { $Subaccount as Subaccount };
+
+/** Number of nanoseconds since the UNIX epoch in UTC timezone. */
+export type Timestamp = bigint;
+/** Number of nanoseconds since the UNIX epoch in UTC timezone. */
+const $Timestamp: $.Schema<Timestamp> = $.c.rec(() => $.c.nat64);
+export { $Timestamp as Timestamp };
+
+export type Tokens = bigint;
+const $Tokens: $.Schema<Tokens> = $.c.rec(() => $.c.nat);
+export { $Tokens as Tokens };
+
+export type TransferArg = { to: Account; fee: bigint | null; memo: Uint8Array | null; from_subaccount: Uint8Array | null; created_at_time: bigint | null; amount: bigint };
+const $TransferArg: $.Schema<TransferArg> = $.c.rec(() => $.c.record({ to: $Account, fee: $.c.opt($.c.nat), memo: $.c.opt($.c.blob()), from_subaccount: $.c.opt($.c.blob()), created_at_time: $.c.opt($.c.nat64), amount: $.c.nat }));
+export { $TransferArg as TransferArg };
+
+export type TransferError = { tag: "GenericError"; value: { message: string; error_code: bigint } } | { tag: "TemporarilyUnavailable" } | { tag: "BadBurn"; value: { min_burn_amount: bigint } } | { tag: "Duplicate"; value: { duplicate_of: bigint } } | { tag: "BadFee"; value: { expected_fee: bigint } } | { tag: "CreatedInFuture"; value: { ledger_time: bigint } } | { tag: "TooOld" } | { tag: "InsufficientFunds"; value: { balance: bigint } };
+const $TransferError: $.Schema<TransferError> = $.c.rec(() => $.c.variant({ GenericError: $.c.record({ message: $.c.text, error_code: $.c.nat }), TemporarilyUnavailable: $.c.null, BadBurn: $.c.record({ min_burn_amount: $.c.nat }), Duplicate: $.c.record({ duplicate_of: $.c.nat }), BadFee: $.c.record({ expected_fee: $.c.nat }), CreatedInFuture: $.c.record({ ledger_time: $.c.nat64 }), TooOld: $.c.null, InsufficientFunds: $.c.record({ balance: $.c.nat }) }));
+export { $TransferError as TransferError };
+
+export type TransferResult = { tag: "Ok"; value: bigint } | { tag: "Err"; value: TransferError };
+const $TransferResult: $.Schema<TransferResult> = $.c.rec(() => $.c.variant({ Ok: $.c.nat, Err: $TransferError }));
+export { $TransferResult as TransferResult };
+
+export type UpgradeArgs = { token_symbol: string | null; transfer_fee: bigint | null; metadata: Array<[string, Value]> | null; token_name: string | null };
+const $UpgradeArgs: $.Schema<UpgradeArgs> = $.c.rec(() => $.c.record({ token_symbol: $.c.opt($.c.text), transfer_fee: $.c.opt($.c.nat64), metadata: $.c.opt($.c.vec($.c.tuple([$.c.text, $Value]))), token_name: $.c.opt($.c.text) }));
+export { $UpgradeArgs as UpgradeArgs };
+
+/** The value returned from the [icrc1_metadata] endpoint. */
+export type Value = { tag: "Int"; value: bigint } | { tag: "Nat"; value: bigint } | { tag: "Blob"; value: Uint8Array } | { tag: "Text"; value: string };
+/** The value returned from the [icrc1_metadata] endpoint. */
+const $Value: $.Schema<Value> = $.c.rec(() => $.c.variant({ Int: $.c.int, Nat: $.c.nat, Blob: $.c.blob(), Text: $.c.text }));
+export { $Value as Value };
+
+const $actor: $.Schema<$.Principal> = $.c.rec(() => $.c.service({ icrc1_balance_of: $.c.func([$Account], [$.c.nat], "query"), icrc1_decimals: $.c.func([], [$.c.nat8], "query"), icrc1_fee: $.c.func([], [$.c.nat], "query"), icrc1_supported_standards: $.c.func([], [$.c.vec($.c.record({ url: $.c.text, name: $.c.text }))], "query"), icrc1_metadata: $.c.func([], [$.c.vec($.c.tuple([$.c.text, $Value]))], "query"), icrc1_symbol: $.c.func([], [$.c.text], "query"), icrc1_minting_account: $.c.func([], [$.c.opt($Account)], "query"), icrc1_name: $.c.func([], [$.c.text], "query"), icrc1_total_supply: $.c.func([], [$.c.nat], "query"), icrc1_transfer: $.c.func([$TransferArg], [$TransferResult], "update") }));
+export type Actor = {
+  icrc1_balance_of: ((arg0: Account) => Promise<bigint>) & $.WithMode<"query">;
+  icrc1_decimals: (() => Promise<number>) & $.WithMode<"query">;
+  icrc1_fee: (() => Promise<bigint>) & $.WithMode<"query">;
+  icrc1_supported_standards: (() => Promise<Array<{ url: string; name: string }>>) & $.WithMode<"query">;
+  icrc1_metadata: (() => Promise<Array<[string, Value]>>) & $.WithMode<"query">;
+  icrc1_symbol: (() => Promise<string>) & $.WithMode<"query">;
+  icrc1_minting_account: (() => Promise<Account | null>) & $.WithMode<"query">;
+  icrc1_name: (() => Promise<string>) & $.WithMode<"query">;
+  icrc1_total_supply: (() => Promise<bigint>) & $.WithMode<"query">;
+  icrc1_transfer: ((arg0: TransferArg) => Promise<TransferResult>) & $.WithMode<"update">;
+};
+export { $actor as actor };
+// Note: the actor is a service class; init args are install-time metadata not exposed here (issue #104).

package/examples/next-ssr/src/components/BalanceTable.tsx

@@ -0,0 +1,43 @@
+// An account's balance on each ledger, as the /account page's sections render
+// it on the server: the amount through `formatUnits`, the exact base units,
+// and a failed ledger's `ReactorError` kind in its own row.
+import { tokens } from "@/format"
+import type { BalanceRow } from "@/server/read-balances"
+
+export function BalanceTable(props: {
+  caption: string
+  section: string
+  rows: readonly BalanceRow[]
+}) {
+  return (
+    <table className="balances" data-section={props.section}>
+      <caption>{props.caption}</caption>
+      <thead>
+        <tr>
+          <th scope="col">Ledger</th>
+          <th scope="col">Balance</th>
+          <th scope="col">Base units</th>
+        </tr>
+      </thead>
+      <tbody>
+        {props.rows.map((row) => (
+          <tr key={row.ledger.id} data-ledger={row.ledger.id}>
+            <th scope="row">{row.ledger.label}</th>
+            {row.ok ? (
+              <>
+                <td data-field="balance">
+                  {tokens(row.balance, row.decimals, row.symbol)}
+                </td>
+                <td data-field="base-units">{row.balance.toString()}</td>
+              </>
+            ) : (
+              <td colSpan={2} className="error" data-kind={row.error.kind}>
+                {row.error.kind}: {row.error.message}
+              </td>
+            )}
+          </tr>
+        ))}
+      </tbody>
+    </table>
+  )
+}

package/examples/next-ssr/src/components/LedgerCard.test.tsx

@@ -0,0 +1,96 @@
+// @vitest-environment jsdom
+//
+// A card whose reads fail in the tab. The server's render never shows such a
+// card (a ledger whose server reads failed gets its error section, scenario
+// 8), but a card reads everything again in the tab after a sign-in, and any of
+// those reads can fail there. Each failed read's row shows the failure's
+// kind, and once every read has settled the card no longer says it is
+// reading.
+import { ReactorProvider } from "@ic-reactor/react"
+import { cleanup, render, waitFor } from "@testing-library/react"
+import { afterEach, describe, expect, it } from "vitest"
+import { actor, type Actor } from "@/canisters/icrc1"
+import { LEDGERS, NOT_A_LEDGER, type LedgerRef } from "@/ledgers"
+import { TOKEN_READS } from "@/server/prefetch-ledgers"
+import {
+  ledgerHandlers,
+  mockLedgers,
+  requestsFor,
+  SEED_1,
+  tokenOf,
+  type MockLedgers,
+} from "@/testing/mock-ledgers"
+import { LedgerCard } from "./LedgerCard"
+
+const ICP = LEDGERS[0]!
+let test: MockLedgers
+afterEach(() => {
+  cleanup()
+  test.client.dispose()
+})
+
+/** A card in a signed-in tab with an empty cache: it reads everything as seed 1. */
+function renderCard(ledger: LedgerRef) {
+  return render(
+    <ReactorProvider client={() => test.client}>
+      <LedgerCard ledger={ledger} />
+    </ReactorProvider>
+  )
+}
+
+const readText = (container: HTMLElement, method: string) =>
+  container.querySelector(`[data-read="${method}"]`)?.textContent
+const originText = (container: HTMLElement) =>
+  container.querySelector("[data-origin]")?.textContent
+
+describe("a ledger card whose reads fail in the tab", () => {
+  it("shows the kind of the failed read in its row, and the other reads", async () => {
+    test = mockLedgers({ signedIn: true })
+    const token = tokenOf(ICP)
+    test.mock<Actor>(actor, ICP.id, {
+      ...ledgerHandlers(token),
+      // A handler that throws traps the call: reject code 5.
+      icrc1_symbol: () => {
+        throw new Error("symbol trapped")
+      },
+    })
+
+    const { container } = renderCard(ICP)
+
+    await waitFor(() => {
+      expect(readText(container, "icrc1_symbol")).toBe("rejected")
+      expect(readText(container, "icrc1_decimals")).toBe(
+        `${token.decimals} number`
+      )
+      // Without a symbol, amounts are shown in base units.
+      expect(readText(container, "icrc1_fee")).toBe(
+        `${token.fee} base units bigint`
+      )
+    })
+    expect(container.querySelector('[role="alert"]')?.textContent).toMatch(
+      /^rejected: /
+    )
+    expect(originText(container)).toMatch(
+      new RegExp(`^Read again in this tab, as ${SEED_1}, at `)
+    )
+  })
+
+  it("says every read failed, not that it is reading, for a canister that answers none", async () => {
+    test = mockLedgers({ signedIn: true })
+
+    const { container } = renderCard(NOT_A_LEDGER)
+
+    await waitFor(() => {
+      for (const method of TOKEN_READS) {
+        expect(readText(container, method)).toBe("rejected")
+      }
+    })
+    expect(originText(container)).toMatch(
+      new RegExp(`^Every read failed in this tab, as ${SEED_1}\\.`)
+    )
+    // Each read was asked once: a trap is not retried.
+    for (const method of TOKEN_READS) {
+      expect(requestsFor(test, method)).toHaveLength(1)
+    }
+  })
+})

package/examples/next-ssr/src/components/LedgerCard.tsx

@@ -0,0 +1,230 @@
+"use client"
+
+// Scenarios 2 and 3: a client component that renders what the server read.
+//
+// Rules:
+// - Reads are `useQuery(client.queryOptions(ledger, method))`, built in
+//   render: the same options the server prefetched with
+//   (src/server/prefetch-ledgers.ts), so the same keys, and the
+//   `<HydrationBoundary>` around this card has already put their data in the
+//   cache. The server render of this component and the browser's hydrating
+//   render both show it, signed in or not (scenario 10); nothing is fetched
+//   on load (`SERVER_DATA` keeps it fresh for a minute).
+// - The values are exactly what the generated module types: `bigint` for the
+//   fee and the supply, principal text for the minting account, `Uint8Array`
+//   for a subaccount or a `Blob` metadata value, after the trip through JSON
+//   (scenario 3). Each value shows its type at run time.
+// - When the caller changes (a sign-in, scenario 9), `useClient()` renders
+//   the card again and these options are built with the new caller in their
+//   keys: the card reads everything again as the new caller, and never shows
+//   the anonymous answers under them. `useAuth()` is here only to name the
+//   caller in the card's footer.
+// - A reload in a tab that is still signed in (scenario 10) renders these
+//   options for the anonymous caller while the page hydrates, as the server
+//   did, so the card shows the server's data with nothing fetched, then reads
+//   again as the user right after.
+// - Any of those reads can fail in the tab. A read without data is `loading`
+//   only while it is pending: once it failed, its row shows the kind.
+import { isReactorError } from "@ic-reactor/core"
+import { useAuth, useClient } from "@ic-reactor/react"
+import { useQuery } from "@tanstack/react-query"
+import type { ReactNode } from "react"
+import { actor, type Actor } from "@/canisters/icrc1"
+import {
+  metadataText,
+  principalType,
+  runtimeType,
+  toHex,
+  tokens,
+} from "@/format"
+import type { LedgerRef } from "@/ledgers"
+import { SERVER_DATA } from "./server-data"
+
+export function LedgerCard({ ledger: ref }: { ledger: LedgerRef }) {
+  const client = useClient()
+  const { principal: caller } = useAuth()
+  // `client.canister()` returns the same object for the same id: made in render.
+  const ledger = client.canister<Actor>(actor, { id: ref.id })
+  const name = useQuery({
+    ...client.queryOptions(ledger, "icrc1_name"),
+    ...SERVER_DATA,
+  })
+  const symbol = useQuery({
+    ...client.queryOptions(ledger, "icrc1_symbol"),
+    ...SERVER_DATA,
+  })
+  const decimals = useQuery({
+    ...client.queryOptions(ledger, "icrc1_decimals"),
+    ...SERVER_DATA,
+  })
+  const fee = useQuery({
+    ...client.queryOptions(ledger, "icrc1_fee"),
+    ...SERVER_DATA,
+  })
+  const supply = useQuery({
+    ...client.queryOptions(ledger, "icrc1_total_supply"),
+    ...SERVER_DATA,
+  })
+  const minter = useQuery({
+    ...client.queryOptions(ledger, "icrc1_minting_account"),
+    ...SERVER_DATA,
+  })
+  const metadata = useQuery({
+    ...client.queryOptions(ledger, "icrc1_metadata"),
+    ...SERVER_DATA,
+  })
+  const reads = [name, symbol, decimals, fee, supply, minter, metadata]
+
+  const amount = (units: bigint) =>
+    decimals.data === undefined || symbol.data === undefined
+      ? `${units} base units`
+      : tokens(units, decimals.data, symbol.data)
+
+  // Every read came from the server's render until one is fetched here.
+  const fetchedHere = reads.some((r) => r.isFetchedAfterMount)
+  // Pending: neither data nor an error yet. A read that failed has settled.
+  const loading = reads.some((r) => r.isPending)
+  // At 0 (the epoch) when no read has data: every one of them failed.
+  const readAt = new Date(Math.max(...reads.map((r) => r.dataUpdatedAt)))
+  const failure = reads.find((r) => r.error !== null)?.error
+
+  return (
+    <section className="ledger" data-ledger={ref.id}>
+      <h2>
+        {ref.label} <code>{ref.id}</code>
+      </h2>
+      <dl>
+        <Row label="Name" method="icrc1_name" read={name}>
+          {name.data}
+        </Row>
+        <Row label="Symbol" method="icrc1_symbol" read={symbol}>
+          {symbol.data}
+        </Row>
+        <Row label="Decimals" method="icrc1_decimals" read={decimals}>
+          {decimals.data}
+        </Row>
+        <Row label="Fee" method="icrc1_fee" read={fee}>
+          {fee.data !== undefined && amount(fee.data)}
+        </Row>
+        <Row label="Total supply" method="icrc1_total_supply" read={supply}>
+          {supply.data !== undefined && amount(supply.data)}
+        </Row>
+        <Row
+          label="Minting account"
+          method="icrc1_minting_account"
+          read={minter}
+        >
+          {minter.data === null
+            ? "none"
+            : minter.data && (
+                <>
+                  <code>{minter.data.owner}</code>{" "}
+                  <small className="type">
+                    {principalType(minter.data.owner)}
+                  </small>
+                  <br />
+                  subaccount{" "}
+                  {minter.data.subaccount === null ? (
+                    "none"
+                  ) : (
+                    <>
+                      <code>{toHex(minter.data.subaccount)}</code>{" "}
+                      <Type of={minter.data.subaccount} />
+                    </>
+                  )}
+                </>
+              )}
+        </Row>
+        <Row label="Metadata" method="icrc1_metadata" read={metadata}>
+          <ul className="metadata">
+            {metadata.data?.map(([key, value]) => (
+              <li key={key}>
+                <code>{key}</code> {metadataText(value)}{" "}
+                <Type of={value.value} />
+              </li>
+            ))}
+          </ul>
+        </Row>
+      </dl>
+      {failure && (
+        <p className="error" role="alert">
+          {isReactorError(failure) ? failure.kind : "error"}: {failure.message}
+        </p>
+      )}
+      <p className="origin" data-origin={fetchedHere ? "browser" : "server"}>
+        {loading ? (
+          "Reading in this tab, as the current caller."
+        ) : readAt.getTime() === 0 ? (
+          `Every read failed in this tab, as ${caller}.`
+        ) : (
+          <>
+            {fetchedHere
+              ? `Read again in this tab, as ${caller}, at `
+              : "From the server's render: read on the server at "}
+            <time dateTime={readAt.toISOString()}>{readAt.toISOString()}</time>.
+          </>
+        )}{" "}
+        <button
+          type="button"
+          disabled={reads.some((r) => r.isFetching)}
+          onClick={() =>
+            void client.queryClient.invalidateQueries({
+              queryKey: client.queryKey(ledger),
+            })
+          }
+        >
+          Read again in this tab
+        </button>
+      </p>
+    </section>
+  )
+}
+
+/**
+ * A read of the card: its value once there is one, else the kind of its
+ * failure if it failed, else `loading`.
+ */
+function Row(props: {
+  label: string
+  method: string
+  read: { data: unknown; error: Error | null }
+  children: ReactNode
+}) {
+  const { label, method, read, children } = props
+  const value = read.data
+  const scalar =
+    typeof value === "bigint" ||
+    typeof value === "number" ||
+    typeof value === "string"
+  return (
+    <div className="kv">
+      <dt>
+        {label} <code>{method}</code>
+      </dt>
+      <dd data-read={method}>
+        {value === undefined && read.error !== null ? (
+          <span className="error">
+            {isReactorError(read.error) ? read.error.kind : "error"}
+          </span>
+        ) : value === undefined ? (
+          <span className="muted">loading</span>
+        ) : (
+          <>
+            {children}
+            {scalar && (
+              <>
+                {" "}
+                <Type of={value} />
+              </>
+            )}
+          </>
+        )}
+      </dd>
+    </div>
+  )
+}
+
+/** The run-time type of a value, shown after it. */
+const Type = ({ of }: { of: unknown }) => (
+  <small className="type">{runtimeType(of)}</small>
+)

package/examples/next-ssr/src/components/LedgerError.tsx

@@ -0,0 +1,32 @@
+// Scenario 8 (with src/server/error-summary.ts): a section that failed on the
+// server, rendered on the server.
+//
+// The page renders this in place of a ledger's card when the server's reads
+// of it failed. It is a plain component (no hooks, no 'use client'), so its
+// HTML is complete without JavaScript, and the failure of one canister costs
+// one section: the other ledgers render as usual. The kind comes from
+// `isReactorError(error)` on the server, where the error still has it.
+import type { LedgerRef } from "@/ledgers"
+import type { ErrorSummary } from "@/server/error-summary"
+
+export function LedgerError(props: { ledger: LedgerRef; error: ErrorSummary }) {
+  const { ledger, error } = props
+  return (
+    <section className="ledger failed" data-ledger={ledger.id}>
+      <h2>
+        {ledger.label} <code>{ledger.id}</code>
+      </h2>
+      <div className="error" role="alert">
+        <p className="plain">
+          The server&apos;s reads of this canister failed:{" "}
+          <strong data-kind={error.kind}>{error.kind}</strong>
+          {error.rejectCode !== undefined &&
+            `, reject code ${error.rejectCode}`}
+          {error.httpStatus !== undefined && `, HTTP ${error.httpStatus}`}. The
+          rest of the page rendered as usual.
+        </p>
+        <p>{error.message}</p>
+      </div>
+    </section>
+  )
+}

package/examples/next-ssr/src/components/LedgerSections.tsx

@@ -0,0 +1,22 @@
+// The ledgers of the home page, one section each: the card (a client
+// component reading the hydrated cache) for a ledger the server read, and the
+// server-rendered error for one whose reads failed. A plain component, so the
+// page renders it and the tests render it the same way.
+import type { LedgerRef } from "@/ledgers"
+import type { ErrorSummary } from "@/server/error-summary"
+import { LedgerCard } from "./LedgerCard"
+import { LedgerError } from "./LedgerError"
+
+export function LedgerSections(props: {
+  ledgers: readonly LedgerRef[]
+  failures: Readonly<Record<string, ErrorSummary>>
+}) {
+  return props.ledgers.map((ledger) => {
+    const error = props.failures[ledger.id]
+    return error === undefined ? (
+      <LedgerCard key={ledger.id} ledger={ledger} />
+    ) : (
+      <LedgerError key={ledger.id} ledger={ledger} error={error} />
+    )
+  })
+}