@ic-reactor/mcp 0.0.0-stage → 0.0.0

package/examples/canister-studio/src/calls/history.ts

@@ -0,0 +1,287 @@
+import type { MethodMode } from "@meantjs/schema"
+import { useSyncExternalStore } from "react"
+import { fromHex } from "../lib/hex.ts"
+
+/** One call, as the history keeps it (localStorage, shared by the browser's tabs). */
+export interface HistoryEntry {
+  id: string
+  /** When the call settled (ms since the epoch). */
+  at: number
+  canisterId: string
+  canisterName: string
+  method: string
+  mode: MethodMode
+  /** The caller's principal text. */
+  caller: string
+  /** The encoded argument bytes as hex (never JSON). */
+  argsHex: string
+  /** "sent": a oneway call went out; it has no reply and no outcome. */
+  outcome: "ok" | "sent" | "canister_err" | "error"
+  /** The ReactorError kind, for an error. */
+  kind?: string
+  mayHaveExecuted?: boolean
+  summary: string
+}
+
+/**
+ * Where the history lives. Versioned: a later shape gets a new key rather
+ * than misreading this one.
+ */
+export const HISTORY_STORAGE_KEY = "canister-studio:history:v1"
+
+/** The newest entries kept; older ones are dropped. */
+export const HISTORY_LIMIT = 200
+
+// Storage holds text anyone with the browser can edit, so every entry read
+// back is checked field by field, and a summary is cut to a bounded length.
+const MAX_TEXT = 512
+
+const MODES: ReadonlySet<string> = new Set([
+  "query",
+  "composite_query",
+  "update",
+  "oneway",
+])
+const OUTCOMES: ReadonlySet<string> = new Set([
+  "ok",
+  "sent",
+  "canister_err",
+  "error",
+])
+
+const isText = (value: unknown, max = MAX_TEXT): value is string =>
+  typeof value === "string" && value.length <= max
+
+/** An entry read from storage, or `undefined` when it is not one. */
+export function parseHistoryEntry(value: unknown): HistoryEntry | undefined {
+  if (typeof value !== "object" || value === null) return undefined
+  const e = value as Record<string, unknown>
+  if (
+    !isText(e.id) ||
+    typeof e.at !== "number" ||
+    !Number.isFinite(e.at) ||
+    !isText(e.canisterId, 63) ||
+    !isText(e.canisterName) ||
+    !isText(e.method) ||
+    typeof e.mode !== "string" ||
+    !MODES.has(e.mode) ||
+    !isText(e.caller, 63) ||
+    typeof e.argsHex !== "string" ||
+    fromHex(e.argsHex) === undefined ||
+    typeof e.outcome !== "string" ||
+    !OUTCOMES.has(e.outcome) ||
+    !isText(e.summary) ||
+    (e.kind !== undefined && !isText(e.kind, 64)) ||
+    (e.mayHaveExecuted !== undefined && typeof e.mayHaveExecuted !== "boolean")
+  ) {
+    return undefined
+  }
+  return {
+    id: e.id,
+    at: e.at,
+    canisterId: e.canisterId,
+    canisterName: e.canisterName,
+    method: e.method,
+    mode: e.mode as MethodMode,
+    caller: e.caller,
+    argsHex: e.argsHex,
+    outcome: e.outcome as HistoryEntry["outcome"],
+    ...(e.kind === undefined ? {} : { kind: e.kind }),
+    ...(e.mayHaveExecuted === undefined
+      ? {}
+      : { mayHaveExecuted: e.mayHaveExecuted }),
+    summary: e.summary,
+  }
+}
+
+/** Every valid entry of stored text, newest first; anything unreadable is dropped. */
+export function parseHistory(raw: string | null): HistoryEntry[] {
+  if (raw === null) return []
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(raw)
+  } catch {
+    return []
+  }
+  if (!Array.isArray(parsed)) return []
+  const entries: HistoryEntry[] = []
+  for (const item of parsed) {
+    const entry = parseHistoryEntry(item)
+    if (entry !== undefined) entries.push(entry)
+    if (entries.length === HISTORY_LIMIT) break
+  }
+  return entries
+}
+
+// --- the store ------------------------------------------------------------
+//
+// One per tab, over localStorage. Storage can be missing or throw (a private
+// window, blocked site data, a full quota): then the history lives in memory
+// for the tab, and the app works the same.
+
+const EMPTY: HistoryEntry[] = []
+const listeners = new Set<() => void>()
+let snapshot: { raw: string | null; entries: HistoryEntry[] } | undefined
+let memory: HistoryEntry[] = EMPTY
+// Set once a write to storage failed: from then on the tab keeps its history
+// in memory, which already holds every stored entry it read.
+let storageFailed = false
+
+function storage(): Storage | undefined {
+  if (storageFailed) return undefined
+  try {
+    return typeof window === "undefined" ? undefined : window.localStorage
+  } catch {
+    return undefined
+  }
+}
+
+function readRaw(): string | null | undefined {
+  try {
+    return storage()?.getItem(HISTORY_STORAGE_KEY)
+  } catch {
+    return undefined
+  }
+}
+
+/** The current entries: the same array until the stored text changes. */
+function getSnapshot(): HistoryEntry[] {
+  const raw = readRaw()
+  if (raw === undefined) return memory
+  if (snapshot === undefined || snapshot.raw !== raw) {
+    snapshot = { raw, entries: parseHistory(raw) }
+  }
+  return snapshot.entries
+}
+
+const getServerSnapshot = (): HistoryEntry[] => EMPTY
+
+function notify(): void {
+  for (const listener of listeners) listener()
+}
+
+function write(entries: HistoryEntry[]): void {
+  memory = entries
+  const store = storage()
+  if (store !== undefined) {
+    try {
+      const raw = JSON.stringify(entries)
+      store.setItem(HISTORY_STORAGE_KEY, raw)
+      snapshot = { raw, entries }
+    } catch {
+      // A full quota or blocked storage.
+      storageFailed = true
+    }
+  }
+  notify()
+}
+
+// The entries this tab added since it loaded. Tabs do not lock the shared
+// store, and a tab may read a stale copy of it, so two tabs settling calls
+// at once can each write a history without the other's newest entry. Each
+// tab therefore puts its own entries back when another tab's write drops
+// them: an unknown-outcome write never vanishes from the history.
+const own = new Map<string, HistoryEntry>()
+
+/** Both lists by id, newest first, at most {@link HISTORY_LIMIT}. */
+function merged(
+  stored: readonly HistoryEntry[],
+  added: Iterable<HistoryEntry>
+): HistoryEntry[] {
+  // Added first, so an entry from the same millisecond sorts above the
+  // stored ones (the sort is stable).
+  const fresh = [...added]
+  const ids = new Set(fresh.map((e) => e.id))
+  return [...fresh, ...stored.filter((e) => !ids.has(e.id))]
+    .sort((a, b) => b.at - a.at)
+    .slice(0, HISTORY_LIMIT)
+}
+
+// Listens for as long as the tab lives once it added an entry, whether or
+// not a history view is mounted.
+let restoring = false
+
+function restoreOwn(event: StorageEvent): void {
+  if (event.key !== HISTORY_STORAGE_KEY && event.key !== null) return
+  const stored = getSnapshot()
+  if (stored.length === 0) {
+    // Cleared in another tab: this tab's entries go too.
+    own.clear()
+    return
+  }
+  const kept = new Set(stored.map((e) => e.id))
+  const oldest = stored.length < HISTORY_LIMIT ? -Infinity : stored.at(-1)!.at
+  const dropped = [...own.values()].filter(
+    (e) => !kept.has(e.id) && e.at >= oldest
+  )
+  if (dropped.length > 0) write(merged(stored, dropped))
+}
+
+function onStorage(event: StorageEvent): void {
+  // Another tab wrote the history (or cleared all site data: key null).
+  if (event.key === HISTORY_STORAGE_KEY || event.key === null) notify()
+}
+
+function subscribe(listener: () => void): () => void {
+  listeners.add(listener)
+  if (listeners.size === 1 && typeof window !== "undefined") {
+    window.addEventListener("storage", onStorage)
+  }
+  return () => {
+    listeners.delete(listener)
+    if (listeners.size === 0 && typeof window !== "undefined") {
+      window.removeEventListener("storage", onStorage)
+    }
+  }
+}
+
+/** Adds an entry (newest first), keeping at most {@link HISTORY_LIMIT}. */
+export function addHistoryEntry(entry: HistoryEntry): void {
+  own.delete(entry.id)
+  own.set(entry.id, entry)
+  // At most as many as the store keeps: older ones would be cut anyway.
+  if (own.size > HISTORY_LIMIT) own.delete(own.keys().next().value!)
+  if (!restoring && typeof window !== "undefined") {
+    restoring = true
+    window.addEventListener("storage", restoreOwn)
+  }
+  write(merged(getSnapshot(), [entry]))
+}
+
+export function clearHistory(): void {
+  own.clear()
+  write(EMPTY)
+}
+
+const historyApi = { add: addHistoryEntry, clear: clearHistory }
+
+/** The tab's call history. Browser only: empty during SSR and hydration. */
+export function useCallHistory(): {
+  entries: HistoryEntry[]
+  add(e: HistoryEntry): void
+  clear(): void
+} {
+  const entries = useSyncExternalStore(
+    subscribe,
+    getSnapshot,
+    getServerSnapshot
+  )
+  return { entries, ...historyApi }
+}
+
+let sequence = 0
+
+/** A unique id for an entry. Event handlers only (it is random). */
+export function newHistoryId(): string {
+  sequence += 1
+  try {
+    return crypto.randomUUID()
+  } catch {
+    return `${Date.now().toString(36)}-${sequence}`
+  }
+}
+
+/** Text cut to `max` characters, with an ellipsis when cut. */
+export function clip(text: string, max = 160): string {
+  return text.length <= max ? text : `${text.slice(0, max - 1)}…`
+}

package/examples/canister-studio/src/calls/kinds.ts

@@ -0,0 +1,68 @@
+import type { MethodMode } from "@meantjs/schema"
+import type { CanisterInterface, MethodInfo } from "../interface/types.ts"
+
+/**
+ * How the studio calls a method, decided once from its mode, its results and
+ * the registry:
+ *
+ * - `read`: a `query` or `composite_query` with results, cached through
+ *   `useQuery(readQueryOptions(…))`. Only a `query` has a certified twin.
+ * - `idempotent`: an update the registry names in `idempotentUpdates` (the
+ *   ckBTC minter's `get_btc_address`), read through
+ *   `{ update: "idempotent" }`. It still goes through consensus, so it needs
+ *   a signed-in caller.
+ * - `update`: a write, confirmed first, sent once through `useMutation`.
+ * - `oneway`: a write with no reply and no outcome, confirmed first.
+ * - `call`: a query without results. `queryOptions` refuses it (a read that
+ *   resolves `undefined` caches nothing), so it is called, not cached.
+ */
+export type CallKind =
+  | { readonly kind: "read"; readonly certifiable: boolean }
+  | { readonly kind: "idempotent" }
+  | { readonly kind: "update" }
+  | { readonly kind: "oneway" }
+  | { readonly kind: "call" }
+
+export function callKindOf(
+  iface: CanisterInterface,
+  method: MethodInfo
+): CallKind {
+  switch (method.mode) {
+    case "query":
+    case "composite_query":
+      return method.results.length === 0
+        ? { kind: "call" }
+        : { kind: "read", certifiable: method.mode === "query" }
+    case "update":
+      return method.results.length > 0 &&
+        iface.registry?.idempotentUpdates?.includes(method.name) === true
+        ? { kind: "idempotent" }
+        : { kind: "update" }
+    case "oneway":
+      return { kind: "oneway" }
+  }
+}
+
+/** Whether the client refuses this kind of call from an anonymous caller. */
+export const needsSignIn = (kind: CallKind): boolean =>
+  kind.kind === "idempotent" || kind.kind === "update" || kind.kind === "oneway"
+
+/** What the run button of a method says. */
+export function submitLabelOf(kind: CallKind, mode: MethodMode): string {
+  switch (kind.kind) {
+    case "read":
+      return mode === "composite_query" ? "Run composite query" : "Run query"
+    case "idempotent":
+      return "Get (idempotent update)"
+    case "update":
+      return "Review update…"
+    case "oneway":
+      return "Review oneway call…"
+    case "call":
+      return "Call"
+  }
+}
+
+/** Why a write button is disabled while nobody is signed in. */
+export const SIGN_IN_REASON =
+  "Sign in to send writes: the client refuses them anyway (unauthenticated)."

package/examples/canister-studio/src/calls/prepare.ts

@@ -0,0 +1,32 @@
+import { encodeArgs } from "@meantjs/schema/codec"
+import type { MethodInfo } from "../interface/types.ts"
+import { toVars } from "../lib/reactor.ts"
+
+/**
+ * A call as the form submits it, and as it is confirmed and sent: the
+ * argument values, the one `vars` value ic-reactor's builders take, and the
+ * exact Candid bytes they encode to.
+ */
+export interface PreparedCall {
+  readonly values: readonly unknown[]
+  readonly vars: unknown
+  readonly bytes: Uint8Array
+}
+
+/**
+ * The call of `values` (a shared link's, history's), or `undefined` when
+ * they do not encode as the method's arguments.
+ */
+export function prepareCall(
+  method: MethodInfo,
+  values: readonly unknown[]
+): PreparedCall | undefined {
+  const encoded = encodeArgs(method.args, values)
+  return encoded.ok
+    ? { values, vars: toVars(values), bytes: encoded.bytes }
+    : undefined
+}
+
+/** Whether two argument messages are the same bytes. */
+export const sameBytes = (a: Uint8Array, b: Uint8Array): boolean =>
+  a.length === b.length && a.every((byte, i) => byte === b[i])

package/examples/canister-studio/src/calls/query-options.ts

@@ -0,0 +1,30 @@
+import type { Canister, Client } from "@ic-reactor/core"
+import type { MethodInfo } from "../interface/types.ts"
+import type { DynActor } from "../lib/reactor.ts"
+
+/**
+ * The query options of a read, exactly as MethodRunner (`useQuery`) and the
+ * SSR loader of a shared link (`queryClient.ensureQueryData`) both build
+ * them, so a server-rendered result hydrates under the same key.
+ *
+ * `idempotent: true` reads an update method through
+ * `{ update: "idempotent" }`: only for methods the registry names as
+ * idempotent updates. `vars` may be `skipToken` (nothing submitted yet).
+ * `can` decides certification: the certified twin's keys end in
+ * "certified", so the loader must build the same twin the runner shows.
+ *
+ * @throws TypeError, from `client.queryOptions`, for a oneway, a method
+ * without results, an update without `idempotent`, or a composite query on
+ * the certified twin: `callKindOf` keeps those away from here.
+ */
+export function readQueryOptions(
+  client: Client,
+  can: Canister<DynActor>,
+  m: MethodInfo,
+  vars: unknown,
+  opts?: { idempotent?: boolean }
+) {
+  return opts?.idempotent === true
+    ? client.queryOptions(can, m.name, vars, { update: "idempotent" })
+    : client.queryOptions(can, m.name, vars)
+}

package/examples/canister-studio/src/calls/read.ts

@@ -0,0 +1,47 @@
+import type { Canister, Client } from "@ic-reactor/core"
+import type { CanisterInterface, MethodInfo } from "../interface/types.ts"
+import type { DynActor } from "../lib/reactor.ts"
+import { addHistoryEntry, newHistoryId } from "./history.ts"
+import type { PreparedCall } from "./prepare.ts"
+import { readQueryOptions } from "./query-options.ts"
+import { historyEntryOf, type CallResult } from "./record.ts"
+
+/** Records a settled read in the history. */
+export function recordRead(
+  iface: CanisterInterface,
+  method: MethodInfo,
+  caller: string,
+  call: PreparedCall,
+  result: CallResult
+): void {
+  addHistoryEntry(
+    historyEntryOf(
+      { iface, method, caller, bytes: call.bytes, result },
+      Date.now(),
+      newHistoryId()
+    )
+  )
+}
+
+/**
+ * Reads now, never from the cache (a click asks for the canister's answer),
+ * into the very key `useQuery(readQueryOptions(…))` observes, and records
+ * the read in the history. Event handlers only: it reads the clock.
+ */
+export function readNow(
+  client: Client,
+  can: Canister<DynActor>,
+  iface: CanisterInterface,
+  method: MethodInfo,
+  call: PreparedCall,
+  opts?: { idempotent?: boolean }
+): void {
+  const caller = client.caller()
+  const options = readQueryOptions(client, can, method, call.vars, opts)
+  const record = (result: CallResult) =>
+    recordRead(iface, method, caller, call, result)
+  client.queryClient.fetchQuery({ ...options, staleTime: 0 }).then(
+    (reply) => record({ ok: true, reply }),
+    (error: unknown) => record({ ok: false, error })
+  )
+}

package/examples/canister-studio/src/calls/readback.ts

@@ -0,0 +1,100 @@
+import { principal, type Principal } from "@meantjs/schema"
+import type { CanisterInterface, MethodInfo } from "../interface/types.ts"
+import { prepareCall, type PreparedCall } from "./prepare.ts"
+
+/**
+ * A read that shows whether a write with an unknown outcome happened: for a
+ * ledger, the sending account's balance.
+ */
+export interface ReadBack {
+  readonly method: MethodInfo
+  readonly call: PreparedCall
+  /** What to look for in the answer. */
+  readonly label: string
+}
+
+const isObject = (value: unknown): value is Record<string, unknown> =>
+  typeof value === "object" && value !== null
+
+const subaccountOf = (arg: Record<string, unknown>): unknown =>
+  Object.hasOwn(arg, "from_subaccount") ? (arg.from_subaccount ?? null) : null
+
+function asPrincipal(text: string): Principal | undefined {
+  try {
+    return principal(text)
+  } catch {
+    return undefined
+  }
+}
+
+/** The query `name` of the interface, if it has one taking one argument. */
+function query(iface: CanisterInterface, name: string): MethodInfo | undefined {
+  const method = iface.method(name)
+  return method !== undefined &&
+    (method.mode === "query" || method.mode === "composite_query") &&
+    method.args.length === 1 &&
+    method.results.length > 0
+    ? method
+    : undefined
+}
+
+function readBack(
+  method: MethodInfo | undefined,
+  arg: unknown,
+  label: string
+): ReadBack | undefined {
+  if (method === undefined) return undefined
+  const call = prepareCall(method, [arg])
+  return call === undefined ? undefined : { method, call, label }
+}
+
+/**
+ * The read that tells whether `method` ran with `values` as `caller`, or
+ * `undefined` when the studio knows none: then the reader picks a query.
+ *
+ * - An ICRC-1 transfer or the ICP ledger's `transfer`: `icrc1_balance_of` of
+ *   the sending account (the caller, and `from_subaccount`).
+ * - An ICRC-2 `transfer_from`: the balance of its `from` account.
+ * - An ICRC-2 `approve`: `icrc2_allowance` of the caller's account for the
+ *   spender.
+ */
+export function suggestReadBack(
+  iface: CanisterInterface,
+  method: MethodInfo,
+  values: readonly unknown[],
+  caller: string
+): ReadBack | undefined {
+  const [arg] = values
+  if (!isObject(arg)) return undefined
+  const owner = asPrincipal(caller)
+  switch (method.name) {
+    case "icrc1_transfer":
+    case "transfer": {
+      if (owner === undefined) return undefined
+      return readBack(
+        query(iface, "icrc1_balance_of"),
+        { owner, subaccount: subaccountOf(arg) },
+        "The sending account's balance: lower by the amount and the fee if it ran."
+      )
+    }
+    case "icrc2_transfer_from":
+      return readBack(
+        query(iface, "icrc1_balance_of"),
+        arg.from,
+        "The source account's balance: lower by the amount and the fee if it ran."
+      )
+    case "icrc2_approve": {
+      if (owner === undefined) return undefined
+      return readBack(
+        query(iface, "icrc2_allowance"),
+        {
+          account: { owner, subaccount: subaccountOf(arg) },
+          spender: arg.spender,
+        },
+        "The spender's allowance: the approved amount if it ran."
+      )
+    }
+    default:
+      return undefined
+  }
+}

package/examples/canister-studio/src/calls/record.ts

@@ -0,0 +1,123 @@
+import { isReactorError } from "@ic-reactor/core"
+import type { CanisterInterface, MethodInfo } from "../interface/types.ts"
+import { toHex } from "../lib/hex.ts"
+import { errorSummary } from "./error-info.ts"
+import { clip, type HistoryEntry } from "./history.ts"
+
+/**
+ * Arguments larger than this are not kept: the entry records the call, but
+ * cannot replay it. Storage is a few megabytes for the whole site.
+ */
+export const HISTORY_ARGS_MAX_BYTES = 16 * 1024
+
+/** How a call ended, as the runner saw it. */
+export type CallResult =
+  | { readonly ok: true; readonly reply: unknown }
+  | { readonly ok: false; readonly error: unknown }
+
+export interface SettledCall {
+  readonly iface: CanisterInterface
+  readonly method: MethodInfo
+  /** The principal the call went out as. */
+  readonly caller: string
+  /** The exact argument bytes sent. */
+  readonly bytes: Uint8Array
+  readonly result: CallResult
+  /** A prefix for the summary, such as "re-send". */
+  readonly note?: string
+}
+
+/**
+ * A value as short, plain text for a history line: bigints as digits, bytes
+ * as their length, at most `max` characters. Not a format to read back:
+ * the entry's `argsHex` is what replays a call.
+ */
+export function shortValue(value: unknown, max = 160): string {
+  if (value === undefined) return "no reply value"
+  let out = ""
+  const seen = new Set<object>()
+  const walk = (v: unknown, depth: number): void => {
+    if (out.length > max) return
+    if (v === null || v === undefined) out += String(v)
+    else if (typeof v === "bigint") out += v.toString()
+    else if (typeof v === "string") out += JSON.stringify(v)
+    else if (typeof v !== "object") out += String(v)
+    else if (v instanceof Uint8Array) out += `<${v.length} bytes>`
+    else if (depth > 8 || seen.has(v)) out += "…"
+    else {
+      seen.add(v)
+      const array = Array.isArray(v)
+      const keys = array ? undefined : Object.keys(v)
+      const count = keys === undefined ? (v as unknown[]).length : keys.length
+      out += array ? "[" : "{"
+      // Stops at the budget: a reply can hold a million items.
+      for (let i = 0; i < count && out.length <= max; i++) {
+        if (i > 0) out += ", "
+        const key = keys?.[i]
+        if (key !== undefined) out += `${key}: `
+        walk(
+          key === undefined
+            ? (v as unknown[])[i]
+            : (v as Record<string, unknown>)[key],
+          depth + 1
+        )
+      }
+      out += array ? "]" : "}"
+    }
+  }
+  walk(value, 0)
+  return clip(out, max)
+}
+
+function summaryOf(result: CallResult, oneway: boolean): string {
+  if (result.ok && oneway) return "sent: a oneway call has no reply or outcome"
+  if (result.ok) return `ok: ${shortValue(result.reply)}`
+  const { error } = result
+  if (isReactorError(error) && error.kind === "canister_err") {
+    return `Err: ${shortValue(error.err)}`
+  }
+  return errorSummary(error)
+}
+
+/**
+ * The history entry of a settled call. `at` and `id` come from the caller
+ * (an event handler: the clock and randomness never run in render).
+ */
+export function historyEntryOf(
+  call: SettledCall,
+  at: number,
+  id: string
+): HistoryEntry {
+  const { iface, method, result } = call
+  const keepArgs = call.bytes.length <= HISTORY_ARGS_MAX_BYTES
+  const summary = [
+    call.note,
+    summaryOf(result, method.mode === "oneway"),
+    keepArgs ? undefined : "(arguments too large to keep)",
+  ]
+    .filter((part): part is string => part !== undefined)
+    .join(" ")
+  const error = result.ok ? undefined : result.error
+  const failure = isReactorError(error) ? error : undefined
+  return {
+    id,
+    at,
+    canisterId: iface.canisterId,
+    canisterName: clip(iface.name, 120),
+    method: method.name,
+    mode: method.mode,
+    caller: call.caller,
+    argsHex: keepArgs ? toHex(call.bytes) : "",
+    outcome: result.ok
+      ? method.mode === "oneway"
+        ? "sent"
+        : "ok"
+      : failure?.kind === "canister_err"
+        ? "canister_err"
+        : "error",
+    ...(failure === undefined
+      ? {}
+      : { kind: failure.kind, mayHaveExecuted: failure.mayHaveExecuted }),
+    summary: clip(summary),
+  }
+}