@tollbooth-dpyc/web 0.1.0

package/dist/signedIn.d.ts

@@ -0,0 +1,26 @@
+/**
+ * What "signed in" means. One definition, because there were two.
+ *
+ * An npub is public — it is on every note its owner ever wrote — so the npub
+ * alone is a claim, never a credential. A shell that read "we know an npub" as
+ * "signed in" let anyone who asked for a DM and never answered it in, as
+ * themselves, unproven. Two things can back the claim:
+ *
+ *   - a **cached DM proof**, won by answering a Nostr challenge, or
+ *   - a **session nsec** in this tab, which signs a fresh proof per call — and
+ *     only counts for the npub it actually derives to.
+ *
+ * Pure, so it is testable without a browser.
+ */
+export interface Claim {
+    /** The npub the interface is showing, proven or not. */
+    npub: string;
+    /** A cached DM proof token, if one was won and has not lapsed. */
+    proof: string;
+    /** The npub this tab's session key derives to, if it holds one. */
+    sessionNpub: string | null;
+}
+/** True only when the claimed npub is backed by something. */
+export declare function isProven({ npub, proof, sessionNpub }: Claim): boolean;
+/** True when this tab can sign a fresh proof for the npub it is claiming. */
+export declare function canSignFor({ npub, sessionNpub }: Claim): boolean;

package/dist/signedIn.js

@@ -0,0 +1,26 @@
+/**
+ * What "signed in" means. One definition, because there were two.
+ *
+ * An npub is public — it is on every note its owner ever wrote — so the npub
+ * alone is a claim, never a credential. A shell that read "we know an npub" as
+ * "signed in" let anyone who asked for a DM and never answered it in, as
+ * themselves, unproven. Two things can back the claim:
+ *
+ *   - a **cached DM proof**, won by answering a Nostr challenge, or
+ *   - a **session nsec** in this tab, which signs a fresh proof per call — and
+ *     only counts for the npub it actually derives to.
+ *
+ * Pure, so it is testable without a browser.
+ */
+/** True only when the claimed npub is backed by something. */
+export function isProven({ npub, proof, sessionNpub }) {
+    if (!npub)
+        return false;
+    if (proof)
+        return true;
+    return sessionNpub === npub;
+}
+/** True when this tab can sign a fresh proof for the npub it is claiming. */
+export function canSignFor({ npub, sessionNpub }) {
+    return Boolean(npub) && sessionNpub === npub;
+}

package/dist/standardTools.d.ts

@@ -0,0 +1,134 @@
+/**
+ * Typed wrappers for the tools every operator gets from
+ * `register_standard_tools` in the tollbooth-dpyc wheel.
+ */
+export interface ServiceStatus {
+    operator_npub_hash?: string;
+    lifecycle?: string;
+    message?: string;
+    version?: string;
+    tollbooth_dpyc_version?: string;
+    service?: string;
+    slug?: string;
+}
+export declare function serviceStatus(): Promise<ServiceStatus>;
+export interface NpubProofResult {
+    success?: boolean;
+    proven_npub?: string;
+    status?: string;
+    message?: string;
+    dpop_token?: string;
+    expires_in_seconds?: number;
+    expires_at?: string;
+    error?: string;
+    error_code?: string;
+}
+/**
+ * Step 1 of DM sign-in: a Secure Courier challenge DM to the npub. Free.
+ *
+ * `verifyAt` is the RFC 8628 verification venue — the place THIS app shows the
+ * session phrase. The DM names it so the human can cross-check that the code
+ * in the DM is the one on their own screen; an impostor firing the same tool
+ * from elsewhere cannot make the patron's open tab show the attacker's code.
+ */
+export declare function requestNpubProof(patronNpub: string, verifyAt?: string, reason?: string): Promise<NpubProofResult>;
+/**
+ * Step 2: drain DMs for the signed reply to step 1. Call only after the human
+ * says they replied — it is destructive, so never poll it.
+ */
+export declare function receiveNpubProof(patronNpub: string, dpopToken: string): Promise<NpubProofResult>;
+export interface ProofStatusResult {
+    success?: boolean;
+    status?: "valid" | "expired" | "unknown" | string;
+    expires_in_seconds?: number | null;
+    error?: string;
+    error_code?: string;
+}
+export declare function checkProofStatus(patronNpub: string, dpopToken: string): Promise<ProofStatusResult>;
+export interface CheckBalanceResult {
+    success?: boolean;
+    balance_api_sats?: number;
+    total_deposited_api_sats?: number;
+    total_consumed_api_sats?: number;
+    next_expiration_iso?: string;
+    expiring_within_24h_sats?: number;
+    error?: string;
+    error_code?: string;
+}
+export declare function checkBalance(): Promise<CheckBalanceResult>;
+export interface CheckPriceResult {
+    success: boolean;
+    tool_id?: string;
+    base_cost_api_sats?: number;
+    effective_cost_api_sats?: number;
+    error?: string;
+    error_code?: string;
+}
+/**
+ * The fare for one tool in api_sats, as the live pricing model resolves it,
+ * constraints included — keyed by the tool's frozen UUID. Null when unreadable:
+ * show the answer without a price rather than invent one.
+ */
+export declare function checkPrice(toolId: string): Promise<number | null>;
+export interface PurchaseCreditsResult {
+    success?: boolean;
+    invoice_id?: string;
+    checkout_link?: string;
+    lightning_invoice?: string;
+    payment_request?: string;
+    expires_at?: string;
+    amount_sats?: number;
+    error?: string;
+    error_code?: string;
+}
+export declare function purchaseCredits(sats: number): Promise<PurchaseCreditsResult>;
+export interface CheckPaymentResult {
+    success?: boolean;
+    status?: "New" | "Processing" | "Settled" | "Expired" | "Invalid" | string;
+    message?: string;
+    invoice_id?: string;
+    credits_granted?: number;
+    balance_api_sats?: number;
+    error?: string;
+    error_code?: string;
+}
+export declare function checkPayment(invoiceId: string): Promise<CheckPaymentResult>;
+export interface AccountStatementResult {
+    success?: boolean;
+    balance_api_sats?: number;
+    total_deposited_api_sats?: number;
+    total_consumed_api_sats?: number;
+    total_expired_api_sats?: number;
+    today_usage?: Record<string, {
+        calls: number;
+        api_sats: number;
+    }>;
+    error?: string;
+}
+export declare function getAccountStatement(days?: number): Promise<AccountStatementResult>;
+export interface Kind0 {
+    name?: string;
+    display_name?: string;
+    about?: string;
+    picture?: string;
+    banner?: string;
+    nip05?: string;
+    website?: string;
+    lud16?: string;
+}
+export interface GetNostrProfileResult {
+    success: boolean;
+    npub?: string;
+    profile?: Kind0;
+    error?: string;
+}
+export declare function getNostrProfile(npub: string): Promise<GetNostrProfileResult>;
+export interface PublishNostrProfileResult {
+    success: boolean;
+    ok?: number;
+    total?: number;
+    errors?: string[];
+    error?: string;
+}
+/** Relay a kind-0 the BROWSER signed. The wheel verifies it and fans it out. */
+export declare function publishNostrProfile(npub: string, signedEvent: string): Promise<PublishNostrProfileResult>;

package/dist/standardTools.js

@@ -0,0 +1,68 @@
+/**
+ * Typed wrappers for the tools every operator gets from
+ * `register_standard_tools` in the tollbooth-dpyc wheel.
+ */
+import { callTool } from "./client.js";
+export function serviceStatus() {
+    return callTool("service_status", {}, { bestEffort: true });
+}
+/**
+ * Step 1 of DM sign-in: a Secure Courier challenge DM to the npub. Free.
+ *
+ * `verifyAt` is the RFC 8628 verification venue — the place THIS app shows the
+ * session phrase. The DM names it so the human can cross-check that the code
+ * in the DM is the one on their own screen; an impostor firing the same tool
+ * from elsewhere cannot make the patron's open tab show the attacker's code.
+ */
+export function requestNpubProof(patronNpub, verifyAt, reason) {
+    return callTool("request_npub_proof", {
+        patron_npub: patronNpub,
+        ...(verifyAt ? { verify_at: verifyAt } : {}),
+        ...(reason ? { reason } : {}),
+    });
+}
+/**
+ * Step 2: drain DMs for the signed reply to step 1. Call only after the human
+ * says they replied — it is destructive, so never poll it.
+ */
+export function receiveNpubProof(patronNpub, dpopToken) {
+    return callTool("receive_npub_proof", {
+        patron_npub: patronNpub,
+        dpop_token: dpopToken,
+    });
+}
+export function checkProofStatus(patronNpub, dpopToken) {
+    return callTool("check_proof_status", { patron_npub: patronNpub, dpop_token: dpopToken }, { bestEffort: true });
+}
+export function checkBalance() {
+    return callTool("check_balance", {});
+}
+/**
+ * The fare for one tool in api_sats, as the live pricing model resolves it,
+ * constraints included — keyed by the tool's frozen UUID. Null when unreadable:
+ * show the answer without a price rather than invent one.
+ */
+export async function checkPrice(toolId) {
+    const r = await callTool("check_price", { tool_id: toolId });
+    const v = r.effective_cost_api_sats ?? r.base_cost_api_sats;
+    return typeof v === "number" ? v : null;
+}
+export function purchaseCredits(sats) {
+    return callTool("purchase_credits", { amount_sats: sats });
+}
+export function checkPayment(invoiceId) {
+    return callTool("check_payment", { invoice_id: invoiceId });
+}
+export function getAccountStatement(days = 30) {
+    return callTool("account_statement", { days });
+}
+export function getNostrProfile(npub) {
+    return callTool("get_nostr_profile", { npub });
+}
+/** Relay a kind-0 the BROWSER signed. The wheel verifies it and fans it out. */
+export function publishNostrProfile(npub, signedEvent) {
+    return callTool("publish_nostr_profile", {
+        npub,
+        signed_event: signedEvent,
+    });
+}

package/dist/storage.d.ts

@@ -0,0 +1,14 @@
+/**
+ * localStorage, read as the uncertainty it is.
+ *
+ * It is absent when a page is rendered off a browser, and merely touching it
+ * raises in a browser with site data blocked or in some privacy modes. An
+ * identity helper that takes the page down over a setting the visitor chose is
+ * not worth having, so a failure reads as "nothing stored" and the app carries
+ * on asking them to sign in.
+ */
+/** A key under this site's prefix, e.g. "chart:patron_npub:v1". */
+export declare function key(name: string): string;
+export declare function readStored(name: string): string;
+export declare function writeStored(name: string, value: string): void;
+export declare function removeStored(name: string): void;

package/dist/storage.js

@@ -0,0 +1,46 @@
+/**
+ * localStorage, read as the uncertainty it is.
+ *
+ * It is absent when a page is rendered off a browser, and merely touching it
+ * raises in a browser with site data blocked or in some privacy modes. An
+ * identity helper that takes the page down over a setting the visitor chose is
+ * not worth having, so a failure reads as "nothing stored" and the app carries
+ * on asking them to sign in.
+ */
+import { tollboothConfig } from "./config.js";
+function store() {
+    try {
+        return globalThis.localStorage ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+/** A key under this site's prefix, e.g. "chart:patron_npub:v1". */
+export function key(name) {
+    return `${tollboothConfig().storagePrefix}:${name}`;
+}
+export function readStored(name) {
+    try {
+        return store()?.getItem(key(name)) ?? "";
+    }
+    catch {
+        return "";
+    }
+}
+export function writeStored(name, value) {
+    try {
+        store()?.setItem(key(name), value);
+    }
+    catch {
+        /* a visitor who blocks site data simply signs in again next time */
+    }
+}
+export function removeStored(name) {
+    try {
+        store()?.removeItem(key(name));
+    }
+    catch {
+        /* nothing to remove from a store we cannot reach */
+    }
+}

package/dist/toolResult.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Turning an MCP tool result into what a page wants. Pure, so it is tested
+ * without a server.
+ */
+export interface ContentBlock {
+    type: string;
+    text?: string;
+    data?: string;
+    mimeType?: string;
+}
+export interface RawToolResult {
+    isError?: boolean;
+    content?: ContentBlock[];
+    structuredContent?: unknown;
+}
+export interface ImageBlock {
+    mimeType: string;
+    /** Base64, as the server sent it. */
+    data: string;
+}
+export interface ReadResult {
+    /** The structured answer, else the first text block parsed as JSON, else that text. */
+    payload: unknown;
+    images: ImageBlock[];
+}
+/** The text a failed call carries, or a plain fallback. */
+export declare function errorText(result: RawToolResult): string;
+export declare function readToolResult(result: RawToolResult): ReadResult;
+/**
+ * A soft proof failure: `{success: false, error_code: proof_required |
+ * proof_refresh_needed}` with no isError flag. The wheel's codes are lowercase
+ * snake_case; an earlier uppercase comparison never matched, so the bounce
+ * silently never fired. Normalised here, once.
+ */
+export declare function proofBounceMessage(payload: unknown): string | null;
+/** Whether a payload reports failure, for the debug log's colouring. */
+export declare function looksFailed(payload: unknown): boolean;

package/dist/toolResult.js

@@ -0,0 +1,60 @@
+/**
+ * Turning an MCP tool result into what a page wants. Pure, so it is tested
+ * without a server.
+ */
+/** The text a failed call carries, or a plain fallback. */
+export function errorText(result) {
+    return (result.content ?? [])
+        .filter((b) => b.type === "text" && typeof b.text === "string")
+        .map((b) => String(b.text))
+        .join("\n") || "Tool call failed";
+}
+export function readToolResult(result) {
+    const content = result.content ?? [];
+    const images = content
+        .filter((b) => b.type === "image" && typeof b.data === "string")
+        .map((b) => ({ mimeType: b.mimeType || "image/png", data: String(b.data) }));
+    let payload;
+    if (result.structuredContent !== undefined) {
+        payload = result.structuredContent;
+    }
+    else {
+        const text = content.find((b) => b.type === "text");
+        if (text) {
+            const raw = String(text.text ?? "");
+            try {
+                payload = JSON.parse(raw);
+            }
+            catch {
+                payload = raw;
+            }
+        }
+        else {
+            payload = images.length ? {} : result;
+        }
+    }
+    return { payload, images };
+}
+/**
+ * A soft proof failure: `{success: false, error_code: proof_required |
+ * proof_refresh_needed}` with no isError flag. The wheel's codes are lowercase
+ * snake_case; an earlier uppercase comparison never matched, so the bounce
+ * silently never fired. Normalised here, once.
+ */
+export function proofBounceMessage(payload) {
+    if (!payload || typeof payload !== "object")
+        return null;
+    const p = payload;
+    const code = String(p.error_code ?? "").toLowerCase();
+    if (p.success === false && (code === "proof_required" || code === "proof_refresh_needed")) {
+        return String(p.error ?? "Sign-in required.");
+    }
+    return null;
+}
+/** Whether a payload reports failure, for the debug log's colouring. */
+export function looksFailed(payload) {
+    if (!payload || typeof payload !== "object")
+        return false;
+    const p = payload;
+    return p.success === false || p.ok === false || Boolean(p.error);
+}

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@tollbooth-dpyc/web",
+  "version": "0.1.0",
+  "description": "Shared browser SDK for Tollbooth DPYC operator front ends: npub sign-in, proofs, MCP client, profile and wallet",
+  "license": "Apache-2.0",
+  "author": "Lonnie VanZandt",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lonniev/tollbooth-web.git"
+  },
+  "type": "module",
+  "sideEffects": [
+    "*.css"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./react": {
+      "types": "./dist/react/index.d.ts",
+      "default": "./dist/react/index.js"
+    },
+    "./pages-proxy": {
+      "types": "./dist/pagesProxy.d.ts",
+      "default": "./dist/pagesProxy.js"
+    },
+    "./theme.css": "./theme.css"
+  },
+  "files": [
+    "dist",
+    "theme.css",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "node --experimental-strip-types --test 'src/**/*.test.ts'",
+    "prepublishOnly": "npm test && npm run build"
+  },
+  "peerDependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "lucide-react": ">=1.0.0",
+    "nostr-tools": "^2.23.0",
+    "react": "^19.0.0"
+  },
+  "devDependencies": {
+    "@modelcontextprotocol/sdk": "^1.30.1",
+    "@types/react": "^19.2.17",
+    "lucide-react": "^1.47.0",
+    "nostr-tools": "^2.25.2",
+    "react": "^19.3.0",
+    "typescript": "^7.0.2"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  }
+}

package/theme.css

@@ -0,0 +1,47 @@
+/*
+ * Theme tokens for @tollbooth-dpyc/web components.
+ *
+ * Components use only these variables for colour, so a site re-skins them by
+ * redefining the variables after importing this file. Tailwind must also scan
+ * the package for class names:
+ *
+ *   @import "tailwindcss";
+ *   @import "@tollbooth-dpyc/web/theme.css";
+ *   @source "../node_modules/@tollbooth-dpyc/web/dist";
+ */
+
+:root {
+  --tb-accent: #2f6fde;
+  --tb-on-accent: #ffffff;
+  --tb-surface: #ffffff;
+  --tb-surface-2: #f3f5f8;
+  --tb-ink: #14181f;
+  --tb-muted: #5b6573;
+  --tb-line: #d7dce3;
+  --tb-ok: #1f7a4a;
+  --tb-warn-bg: #fff7e6;
+  --tb-warn-line: #f0d08a;
+  --tb-warn-ink: #7a5200;
+  --tb-err-bg: #fdecec;
+  --tb-err-line: #f2b8b8;
+  --tb-err-ink: #9b1c1c;
+}
+
+@media (prefers-color-scheme: dark) {
+  :root:not([data-theme="light"]) {
+    --tb-accent: #7aa7ff;
+    --tb-on-accent: #0b1220;
+    --tb-surface: #151a21;
+    --tb-surface-2: #1d232c;
+    --tb-ink: #e6ebf2;
+    --tb-muted: #9aa5b4;
+    --tb-line: #2b333e;
+    --tb-ok: #5fd39a;
+    --tb-warn-bg: #2a2110;
+    --tb-warn-line: #5c4717;
+    --tb-warn-ink: #f2cf7a;
+    --tb-err-bg: #2c1515;
+    --tb-err-line: #5e2525;
+    --tb-err-ink: #f4a3a3;
+  }
+}