@ic-reactor/mcp 0.0.0-stage → 0.0.0

package/b3pay-module.json

@@ -0,0 +1,194 @@
+{
+  "$schema": "https://b3pay.net/schemas/b3pay-module.schema.json",
+  "schema": 1,
+  "id": "ic-reactor",
+  "title": "IC Reactor",
+  "description": "Typed canister calls for TypeScript and React: a client, one error type, units helpers, a test client and a React provider, over a module generated from a .did file.",
+  "group": "internet-computer",
+  "status": "maintained",
+  "links": {
+    "repository": "https://github.com/B3Pay/ic-reactor",
+    "package": "https://www.npmjs.com/package/@ic-reactor/core"
+  },
+  "editUrl": "https://github.com/B3Pay/ic-reactor/edit/main/docs/src/content/docs/{path}",
+  "source": {
+    "docs": "docs/src/content/docs",
+    "exclude": ["index.mdx", "404.mdx"],
+    "rename": {
+      "ic-reactor/index.mdx": "index.mdx"
+    },
+    "linkBase": "/v4/",
+    "static": {
+      "command": ["node", "docs/scripts/b3pay-static.mjs", "{out}"]
+    }
+  },
+  "sidebar": [
+    {
+      "label": "Get started",
+      "items": [
+        {
+          "label": "Overview",
+          "page": "index"
+        },
+        {
+          "label": "Getting started",
+          "page": "guides/getting-started"
+        },
+        {
+          "label": "Migrating from 3.x",
+          "page": "migrating-from-3"
+        },
+        {
+          "label": "Versioning and support",
+          "page": "versioning"
+        }
+      ]
+    },
+    {
+      "label": "Build",
+      "items": [
+        {
+          "label": "An ICRC-1 wallet",
+          "page": "build/icrc1-wallet"
+        },
+        {
+          "label": "A server page for one user",
+          "page": "build/ssr-per-user"
+        },
+        {
+          "label": "An agent's ledger tools",
+          "page": "build/agent-tools"
+        }
+      ]
+    },
+    {
+      "label": "Guides",
+      "items": [
+        {
+          "label": "Reads",
+          "page": "guides/reads"
+        },
+        {
+          "label": "Writes",
+          "page": "guides/writes"
+        },
+        {
+          "label": "Errors and mayHaveExecuted",
+          "page": "guides/errors"
+        },
+        {
+          "label": "Auth",
+          "page": "guides/auth"
+        },
+        {
+          "label": "SSR and hydration",
+          "page": "guides/ssr"
+        },
+        {
+          "label": "Testing",
+          "page": "guides/testing"
+        },
+        {
+          "label": "The Vite plugin",
+          "page": "guides/vite-plugin"
+        },
+        {
+          "label": "Deploy to a frontend canister",
+          "page": "guides/deploy"
+        }
+      ]
+    },
+    {
+      "label": "Concepts",
+      "items": [
+        {
+          "label": "The client",
+          "page": "guides/client"
+        },
+        {
+          "label": "Values and units",
+          "page": "guides/values"
+        }
+      ]
+    },
+    {
+      "label": "Reference",
+      "items": [
+        {
+          "label": "@ic-reactor/core",
+          "page": "packages/core"
+        },
+        {
+          "label": "@ic-reactor/react",
+          "page": "packages/react"
+        },
+        {
+          "label": "@ic-reactor/vite-plugin",
+          "page": "packages/vite-plugin"
+        },
+        {
+          "label": "@ic-reactor/mcp",
+          "page": "packages/mcp"
+        },
+        {
+          "label": "API reference",
+          "collapsed": true,
+          "items": [
+            {
+              "label": "Overview",
+              "page": "libs"
+            },
+            {
+              "label": "Functions",
+              "directory": "libs/functions",
+              "collapsed": true
+            },
+            {
+              "label": "Interfaces",
+              "directory": "libs/interfaces",
+              "collapsed": true
+            },
+            {
+              "label": "Type aliases",
+              "directory": "libs/type-aliases",
+              "collapsed": true
+            }
+          ]
+        },
+        {
+          "label": "Guide for AI tools (llms.txt)",
+          "link": "llms.txt"
+        }
+      ]
+    },
+    {
+      "label": "Examples",
+      "items": [
+        {
+          "label": "All examples",
+          "page": "examples"
+        },
+        {
+          "label": "ICRC-1 ledger",
+          "page": "examples/icrc-ledger"
+        },
+        {
+          "label": "Next.js SSR",
+          "page": "examples/next-ssr"
+        },
+        {
+          "label": "Vite wallet",
+          "page": "examples/vite-wallet"
+        },
+        {
+          "label": "Node agent tool",
+          "page": "examples/node-agent-tool"
+        },
+        {
+          "label": "Canister Studio",
+          "page": "examples/canister-studio"
+        }
+      ]
+    }
+  ]
+}

package/docs/.remarkrc.json

@@ -0,0 +1,10 @@
+{
+  "plugins": [
+    "remark-frontmatter",
+    "remark-mdx",
+    [
+      "remark-preset-lint-recommended",
+      { "plugins": ["remark-lint-no-duplicate-headings"] }
+    ]
+  ]
+}

package/docs/README.md

@@ -0,0 +1,64 @@
+# IC Reactor Documentation
+
+Documentation for IC Reactor, following the [ICP JS Core](https://github.com/dfinity/icp-js-core) documentation pattern.
+
+## Structure
+
+This documentation setup uses TypeDoc to generate API reference documentation in Markdown format that can be integrated with the ICP Developer Portal.
+
+```
+docs/
+├── package.json          # Build scripts
+├── typedoc.json          # TypeDoc configuration
+├── scripts/
+│   └── split-index.js    # Post-processing script
+└── src/content/docs/     # Manual documentation
+    ├── _sidebar.json     # Navigation structure
+    ├── index.mdx         # Overview
+    ├── installation.mdx  # Installation guide
+    ├── quick-start.mdx   # Quick start tutorial
+    └── ...
+```
+
+## Building Documentation
+
+```bash
+# Install dependencies
+pnpm install
+
+# Build documentation (generates TypeDoc output)
+pnpm build
+```
+
+The build process:
+
+1. Cleans the `dist/` directory
+2. Runs TypeDoc to generate API reference markdown
+3. Runs `split-index.js` to process the output
+4. Copies manual docs to `dist/`
+
+## Output
+
+Documentation is output to `dist/<version>/` and can be:
+
+- Hosted on GitHub Pages
+- Integrated with the ICP Developer Portal
+- Published as a standalone documentation site
+
+## Configuration
+
+### TypeDoc (`typedoc.json`)
+
+- Entry points: `@ic-reactor/core` and `@ic-reactor/react`
+- Output: Markdown with frontmatter for static site generators
+- Plugins: `typedoc-plugin-markdown`, `typedoc-plugin-frontmatter`
+
+### Sidebar (`_sidebar.json`)
+
+Defines the navigation structure following ICP docs conventions.
+
+## Contributing
+
+1. Manual docs go in `src/content/docs/`
+2. API docs are auto-generated from TypeScript sources
+3. Follow the existing frontmatter format with `editUrl: false`

package/docs/astro.config.mjs

@@ -0,0 +1,205 @@
+import { defineConfig, passthroughImageService } from "astro/config"
+import starlight from "@astrojs/starlight"
+import starlightPageActions from "starlight-page-actions"
+
+export default defineConfig({
+  site: "https://ic-reactor.b3pay.net",
+  base: "/v4/",
+  output: "static",
+  // The only images are SVGs (the hero's mark), which need no optimizing, so
+  // the build needs no sharp.
+  image: { service: passthroughImageService() },
+  integrations: [
+    starlight({
+      title: "IC Reactor",
+      // The family mark alone: the library switcher beside it names the
+      // library, so the lockup's name would say it twice.
+      logo: {
+        light: "./src/assets/ic-reactor-mark-light.svg",
+        dark: "./src/assets/ic-reactor-mark-dark.svg",
+        alt: "IC Reactor docs home",
+        replacesTitle: true,
+      },
+      plugins: [
+        starlightPageActions({
+          baseUrl: "https://ic-reactor.b3pay.net",
+          actions: {
+            chatgpt: true,
+            claude: true,
+            markdown: true,
+          },
+        }),
+      ],
+      description:
+        "The modern, type-safe library for building Internet Computer applications",
+      social: [
+        {
+          label: "GitHub",
+          icon: "github",
+          href: "https://github.com/b3pay/ic-reactor",
+        },
+      ],
+      editLink: {
+        baseUrl: "https://github.com/b3pay/ic-reactor/edit/main/docs/",
+      },
+      head: [
+        // The B3Pay design system's type: Schibsted Grotesk and Martian Mono.
+        {
+          tag: "link",
+          attrs: { rel: "preconnect", href: "https://fonts.googleapis.com" },
+        },
+        {
+          tag: "link",
+          attrs: {
+            rel: "preconnect",
+            href: "https://fonts.gstatic.com",
+            crossorigin: true,
+          },
+        },
+        {
+          tag: "link",
+          attrs: {
+            rel: "stylesheet",
+            href: "https://fonts.googleapis.com/css2?family=Martian+Mono:wdth,wght@87.5..100,400..500&family=Schibsted+Grotesk:ital,wght@0,400;0,600;0,700;1,400&display=swap",
+          },
+        },
+        // The share image: the B3Pay design system's social card, from
+        // assets/logos/ic-reactor. Starlight already sets twitter:card to
+        // summary_large_image.
+        {
+          tag: "meta",
+          attrs: {
+            property: "og:image",
+            content:
+              "https://ic-reactor.b3pay.net/v4/ic-reactor-social-card.png",
+          },
+        },
+        { tag: "meta", attrs: { property: "og:image:width", content: "1280" } },
+        { tag: "meta", attrs: { property: "og:image:height", content: "640" } },
+        {
+          tag: "meta",
+          attrs: { property: "og:image:alt", content: "IC Reactor" },
+        },
+        {
+          tag: "meta",
+          attrs: {
+            name: "twitter:image",
+            content:
+              "https://ic-reactor.b3pay.net/v4/ic-reactor-social-card.png",
+          },
+        },
+        {
+          tag: "meta",
+          attrs: {
+            name: "description",
+            content:
+              "The modern, type-safe library for building Internet Computer applications",
+          },
+        },
+      ],
+      // One library's sidebar, in the sections every library on the site
+      // shares: Get started, Guides, Concepts, Reference and Examples. Build
+      // holds the site's step-by-step apps, which may use several libraries.
+      sidebar: [
+        {
+          label: "Get started",
+          items: [
+            { label: "Overview", slug: "ic-reactor" },
+            { label: "Getting started", slug: "guides/getting-started" },
+            { label: "Migrating from 3.x", slug: "migrating-from-3" },
+            { label: "Versioning and support", slug: "versioning" },
+          ],
+        },
+        {
+          label: "Build",
+          items: [
+            { label: "An ICRC-1 wallet", slug: "build/icrc1-wallet" },
+            { label: "A server page for one user", slug: "build/ssr-per-user" },
+            { label: "An agent's ledger tools", slug: "build/agent-tools" },
+          ],
+        },
+        {
+          label: "Guides",
+          items: [
+            { label: "Reads", slug: "guides/reads" },
+            { label: "Writes", slug: "guides/writes" },
+            { label: "Errors and mayHaveExecuted", slug: "guides/errors" },
+            { label: "Auth", slug: "guides/auth" },
+            { label: "SSR and hydration", slug: "guides/ssr" },
+            { label: "Testing", slug: "guides/testing" },
+            { label: "The Vite plugin", slug: "guides/vite-plugin" },
+            { label: "Deploy to a frontend canister", slug: "guides/deploy" },
+          ],
+        },
+        {
+          label: "Concepts",
+          items: [
+            { label: "The client", slug: "guides/client" },
+            { label: "Values and units", slug: "guides/values" },
+          ],
+        },
+        {
+          label: "Reference",
+          items: [
+            { label: "@ic-reactor/core", slug: "packages/core" },
+            { label: "@ic-reactor/react", slug: "packages/react" },
+            { label: "@ic-reactor/vite-plugin", slug: "packages/vite-plugin" },
+            { label: "@ic-reactor/mcp", slug: "packages/mcp" },
+            {
+              label: "API reference",
+              collapsed: true,
+              items: [
+                { label: "Overview", link: "/libs" },
+                {
+                  label: "Classes",
+                  collapsed: true,
+                  items: [{ autogenerate: { directory: "libs/classes" } }],
+                },
+                {
+                  label: "Functions",
+                  collapsed: true,
+                  items: [{ autogenerate: { directory: "libs/functions" } }],
+                },
+                {
+                  label: "Interfaces",
+                  collapsed: true,
+                  items: [{ autogenerate: { directory: "libs/interfaces" } }],
+                },
+                {
+                  label: "Type Aliases",
+                  collapsed: true,
+                  items: [{ autogenerate: { directory: "libs/type-aliases" } }],
+                },
+                {
+                  label: "Variables",
+                  collapsed: true,
+                  items: [{ autogenerate: { directory: "libs/variables" } }],
+                },
+              ],
+            },
+          ],
+        },
+        {
+          label: "Examples",
+          items: [
+            { label: "All examples", slug: "examples" },
+            { label: "ICRC-1 ledger", slug: "examples/icrc-ledger" },
+            { label: "Next.js SSR", slug: "examples/next-ssr" },
+            { label: "Vite wallet", slug: "examples/vite-wallet" },
+            { label: "Node agent tool", slug: "examples/node-agent-tool" },
+            { label: "Canister Studio", slug: "examples/canister-studio" },
+          ],
+        },
+      ],
+      expressiveCode: {
+        themes: ["vitesse-dark", "vitesse-light"],
+        useStarlightUiThemeColors: true,
+        styleOverrides: { borderRadius: "10px" },
+      },
+      customCss: ["./src/styles/custom.css"],
+      components: {
+        SiteTitle: "./src/components/SiteTitle.astro",
+      },
+    }),
+  ],
+})

package/docs/favicon.svg

@@ -0,0 +1,15 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 96 96" width="96" height="96">
+<title>IC Reactor</title>
+<rect id="Tile" width="96" height="96" rx="22" fill="#121110"/>
+<g id="IC Reactor mark" transform="translate(14 14) scale(.7)">
+    <g id="Ring (blocks)">
+      <rect x="35.25" y="12" width="25.5" height="12" rx="3" id="Block 1" fill="#f1ede6"/>
+      <rect x="35.25" y="12" width="25.5" height="12" rx="3" id="Block 2" fill="#f1ede6" transform="rotate(60 48 48)"/>
+      <rect x="35.25" y="12" width="25.5" height="12" rx="3" id="Block 3" fill="#f1ede6" transform="rotate(120 48 48)"/>
+      <rect x="35.25" y="12" width="25.5" height="12" rx="3" id="Block 4" fill="#f1ede6" transform="rotate(180 48 48)"/>
+      <rect x="35.25" y="12" width="25.5" height="12" rx="3" id="Block 5" fill="#f1ede6" transform="rotate(240 48 48)"/>
+      <rect x="35.25" y="12" width="25.5" height="12" rx="3" id="Block 6" fill="#f1ede6" transform="rotate(300 48 48)"/>
+    </g>
+    <circle id="Node" cx="48" cy="48" r="13" fill="#f0b35a"/>
+</g>
+</svg>

package/docs/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@ic-reactor/docs",
+  "private": true,
+  "type": "module",
+  "version": "0.0.1",
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "scripts": {
+    "dev": "astro dev",
+    "api": "typedoc --options ./typedoc.json && node scripts/split-index.js && node scripts/rewrite-typedoc-links.js",
+    "build": "pnpm run api && astro build && node scripts/fix-dist-links.js",
+    "postbuild": "mkdir -p ./dist/${DOCS_VERSION:-local}/ && cp -r ./src/content/docs/* ./dist/${DOCS_VERSION:-local}/",
+    "preview": "pnpm build && npx serve dist/local -p 3000",
+    "lint:mdx": "remark 'src/content/docs/**/*.mdx' -q --frail",
+    "check:links": "node scripts/check-links.mjs",
+    "check:examples": "node scripts/check-example-docs.mjs"
+  },
+  "devDependencies": {
+    "@astrojs/starlight": "^0.42.0",
+    "@modelcontextprotocol/client": "^2.3.1",
+    "@modelcontextprotocol/server": "^2.3.1",
+    "astro": "^7.3.2",
+    "remark-cli": "^12.0.1",
+    "remark-frontmatter": "^5.0.0",
+    "remark-lint": "^10.0.1",
+    "remark-mdx": "^3.1.1",
+    "remark-preset-lint-recommended": "^7.0.1",
+    "serve": "^14.2.6",
+    "linkinator": "^8.1.0",
+    "typedoc": "^0.28.20",
+    "typedoc-plugin-frontmatter": "^1.3.2",
+    "typedoc-plugin-markdown": "^4.13.0",
+    "zod": "^4.6.7"
+  },
+  "dependencies": {
+    "starlight-page-actions": "^0.7.1"
+  }
+}

package/docs/public/favicon.svg

@@ -0,0 +1,15 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 96 96" width="96" height="96">
+<title>IC Reactor</title>
+<rect id="Tile" width="96" height="96" rx="22" fill="#121110"/>
+<g id="IC Reactor mark" transform="translate(14 14) scale(.7)">
+    <g id="Ring (blocks)">
+      <rect x="35.25" y="12" width="25.5" height="12" rx="3" id="Block 1" fill="#f1ede6"/>
+      <rect x="35.25" y="12" width="25.5" height="12" rx="3" id="Block 2" fill="#f1ede6" transform="rotate(60 48 48)"/>
+      <rect x="35.25" y="12" width="25.5" height="12" rx="3" id="Block 3" fill="#f1ede6" transform="rotate(120 48 48)"/>
+      <rect x="35.25" y="12" width="25.5" height="12" rx="3" id="Block 4" fill="#f1ede6" transform="rotate(180 48 48)"/>
+      <rect x="35.25" y="12" width="25.5" height="12" rx="3" id="Block 5" fill="#f1ede6" transform="rotate(240 48 48)"/>
+      <rect x="35.25" y="12" width="25.5" height="12" rx="3" id="Block 6" fill="#f1ede6" transform="rotate(300 48 48)"/>
+    </g>
+    <circle id="Node" cx="48" cy="48" r="13" fill="#f0b35a"/>
+</g>
+</svg>

package/docs/scripts/b3pay-static.mjs

@@ -0,0 +1,22 @@
+#!/usr/bin/env node
+/**
+ * Writes the static files of IC Reactor's module on b3pay.net
+ * (b3pay-module.json): the consumer guide, packages/core/llms.txt, which
+ * b3pay.net serves at /docs/ic-reactor/llms.txt as this site serves it at
+ * /llms.txt.
+ *
+ *   node docs/scripts/b3pay-static.mjs <out folder>
+ */
+import { copyFileSync, mkdirSync } from "node:fs"
+import { join, resolve } from "node:path"
+
+const out = process.argv[2]
+if (!out) {
+  console.error("usage: node docs/scripts/b3pay-static.mjs <out folder>")
+  process.exit(1)
+}
+mkdirSync(out, { recursive: true })
+copyFileSync(
+  resolve(import.meta.dirname, "../../packages/core/llms.txt"),
+  join(out, "llms.txt")
+)