@tollbooth-dpyc/web 1.0.0 → 1.2.0

package/dist/react/useSession.js

@@ -28,6 +28,7 @@ export function useSession() {
         setState(read());
         setNotice("");
     }, []);
+    const dismissNotice = useCallback(() => setNotice(""), []);
     useEffect(() => onProofExpired(() => {
         // A tab that can sign for THIS npub lost nothing.
         if (canSignFor(currentClaim()))
@@ -35,5 +36,5 @@ export function useSession() {
         setNotice("Your session lapsed while you were away. Sign in again to carry on.");
         setState(read());
     }), []);
-    return { ...state, notice, refresh, signOut };
+    return { ...state, notice, dismissNotice, refresh, signOut };
 }

package/dist/react/useTheme.d.ts

@@ -0,0 +1,7 @@
+/**
+ * The theme pick as React state: persisted under `<prefix>:theme`, applied to
+ * <html>, followed across tabs, and — in "system" — following the OS live.
+ * Call `bootstrapTheme()` in main.tsx too, so the first frame is right.
+ */
+import { type Theme } from "../theme.ts";
+export declare function useTheme(fallback?: Theme): [Theme, (next: Theme) => void];

package/dist/react/useTheme.js

@@ -0,0 +1,44 @@
+/**
+ * The theme pick as React state: persisted under `<prefix>:theme`, applied to
+ * <html>, followed across tabs, and — in "system" — following the OS live.
+ * Call `bootstrapTheme()` in main.tsx too, so the first frame is right.
+ */
+import { useCallback, useEffect, useState } from "react";
+import { applyTheme, readTheme, themeStorageKey, writeTheme } from "../theme.js";
+export function useTheme(fallback = "dark") {
+    const [theme, setTheme] = useState(() => readTheme(fallback));
+    // Another tab changed it.
+    useEffect(() => {
+        let key;
+        try {
+            key = themeStorageKey();
+        }
+        catch {
+            return;
+        }
+        const onStorage = (e) => {
+            if (e.key !== key)
+                return;
+            const next = readTheme(fallback);
+            setTheme(next);
+            applyTheme(next);
+        };
+        window.addEventListener("storage", onStorage);
+        return () => window.removeEventListener("storage", onStorage);
+    }, [fallback]);
+    // In "system", the OS changed its mind.
+    useEffect(() => {
+        if (theme !== "system" || !window.matchMedia)
+            return;
+        const mq = window.matchMedia("(prefers-color-scheme: dark)");
+        const onChange = () => applyTheme("system");
+        mq.addEventListener("change", onChange);
+        return () => mq.removeEventListener("change", onChange);
+    }, [theme]);
+    const update = useCallback((next) => {
+        writeTheme(next);
+        applyTheme(next);
+        setTheme(next);
+    }, []);
+    return [theme, update];
+}

package/dist/react/useTopUp.d.ts

@@ -0,0 +1,30 @@
+/**
+ * A Lightning top-up as a hook: purchase_credits → an invoice → check_payment
+ * until it settles, expires or the patron gives up.
+ *
+ * The state machine is `topUpReducer` (framework-free, tested). This adds the
+ * calls and the polling: while an invoice is out and the tab is visible,
+ * check_payment runs every `pollMs` — it is free and safe to repeat — up to
+ * `maxChecks` times, after which the patron's own "check" still works.
+ */
+import { type TopUpState } from "../wallet.ts";
+export interface UseTopUpOptions {
+    /** How often to check an open invoice, in ms. 0 turns polling off. Default 5000. */
+    pollMs?: number;
+    /** Stop polling after this many checks. Default 60 (five minutes at the default rate). */
+    maxChecks?: number;
+    /** Called once when an invoice settles, with the sats credited — refresh a balance here. */
+    onSettled?: (credited: number) => void;
+}
+export interface TopUp {
+    state: TopUpState;
+    /** Ask the service for an invoice of `sats`. Ignored while one is being made or is out. */
+    create: (sats: number) => void;
+    /** Check the open invoice now. */
+    check: () => void;
+    /** Drop the open invoice (it simply expires at BTCPay). */
+    cancel: () => void;
+    /** Back to idle after a settlement or failure. */
+    reset: () => void;
+}
+export declare function useTopUp({ pollMs, maxChecks, onSettled }?: UseTopUpOptions): TopUp;

package/dist/react/useTopUp.js

@@ -0,0 +1,74 @@
+/**
+ * A Lightning top-up as a hook: purchase_credits → an invoice → check_payment
+ * until it settles, expires or the patron gives up.
+ *
+ * The state machine is `topUpReducer` (framework-free, tested). This adds the
+ * calls and the polling: while an invoice is out and the tab is visible,
+ * check_payment runs every `pollMs` — it is free and safe to repeat — up to
+ * `maxChecks` times, after which the patron's own "check" still works.
+ */
+import { useCallback, useEffect, useReducer, useRef, useState } from "react";
+import { checkPayment, purchaseCredits } from "../standardTools.js";
+import { shouldPoll, TOP_UP_IDLE, topUpReducer } from "../wallet.js";
+function messageOf(e) {
+    return e instanceof Error ? e.message : String(e);
+}
+function tabHidden() {
+    return typeof document !== "undefined" && document.visibilityState === "hidden";
+}
+export function useTopUp({ pollMs = 5000, maxChecks = 60, onSettled } = {}) {
+    const [state, dispatch] = useReducer(topUpReducer, TOP_UP_IDLE);
+    const latest = useRef(state);
+    latest.current = state;
+    const settledRef = useRef(onSettled);
+    settledRef.current = onSettled;
+    // Bumped when the tab comes back, so a poll skipped while hidden is re-armed.
+    const [wake, setWake] = useState(0);
+    const create = useCallback((sats) => {
+        const s = latest.current;
+        if (s.phase === "creating" || s.phase === "awaiting")
+            return;
+        dispatch({ type: "create", sats });
+        purchaseCredits(sats).then((result) => dispatch({ type: "created", result }), (e) => dispatch({ type: "error", message: messageOf(e) }));
+    }, []);
+    const check = useCallback(() => {
+        const s = latest.current;
+        if (s.phase !== "awaiting" || s.checking)
+            return;
+        const id = s.invoice.id;
+        dispatch({ type: "check" });
+        checkPayment(id).then((result) => {
+            // A late answer for an invoice the patron has since cancelled is dropped.
+            const now = latest.current;
+            if (now.phase === "awaiting" && now.invoice.id === id)
+                dispatch({ type: "checked", result });
+        }, (e) => dispatch({ type: "error", message: messageOf(e) }));
+    }, []);
+    const cancel = useCallback(() => dispatch({ type: "cancel" }), []);
+    const reset = useCallback(() => dispatch({ type: "reset" }), []);
+    useEffect(() => {
+        if (!(pollMs > 0) || !shouldPoll(state, maxChecks))
+            return;
+        const t = setTimeout(() => {
+            if (tabHidden())
+                return; // re-armed by the visibility listener below
+            check();
+        }, pollMs);
+        return () => clearTimeout(t);
+    }, [state, pollMs, maxChecks, check, wake]);
+    useEffect(() => {
+        if (typeof document === "undefined")
+            return;
+        const onVisible = () => {
+            if (!tabHidden())
+                setWake((n) => n + 1);
+        };
+        document.addEventListener("visibilitychange", onVisible);
+        return () => document.removeEventListener("visibilitychange", onVisible);
+    }, []);
+    useEffect(() => {
+        if (state.phase === "settled")
+            settledRef.current?.(state.credited);
+    }, [state]);
+    return { state, create, check, cancel, reset };
+}

package/dist/standardTools.d.ts

@@ -2,14 +2,45 @@
  * Typed wrappers for the tools every operator gets from
  * `register_standard_tools` in the tollbooth-dpyc wheel.
  */
+/** What a patron must supply beyond the npub proof, per the wheel's `patron_auth_block`. */
+export interface PatronAuth {
+    mode: "oauth" | "secure_courier" | "none";
+    patron_credentials_required: boolean;
+    /** mode "oauth": the provider's credential service. */
+    oauth_service?: string;
+    /** mode "secure_courier": the service a patron delivers secrets to. */
+    credential_service?: string;
+}
+/** The wheel's `service_status`: health and build facts, free and unauthenticated. */
 export interface ServiceStatus {
+    success?: boolean;
+    service?: string;
+    slug?: string;
+    version?: string;
+    tollbooth_dpyc_version?: string;
+    vault_configured?: boolean;
+    courier_has_vault?: boolean;
     operator_npub_hash?: string;
+    process_id?: number;
+    /** Deploy metadata from the environment (commit, build time, …), lower-cased keys. */
+    build_info?: Record<string, string> | null;
+    patron_auth?: PatronAuth;
+    /** Only on a server that runs background jobs. */
+    async_jobs?: {
+        docket_url_set: boolean;
+        backend: string;
+        durable_across_recycles: boolean;
+    };
+    durable_jobs?: {
+        modal_app: string | null;
+        detached_executor_active: boolean;
+        detached_executor_resolved: boolean;
+        detached_executor_error: string | null;
+        last_dispatch_error: string | null;
+        dispatching: boolean;
+    };
     lifecycle?: string;
     message?: string;
-    version?: string;
-    tollbooth_dpyc_version?: string;
-    service?: string;
-    slug?: string;
 }
 export declare function serviceStatus(): Promise<ServiceStatus>;
 export interface NpubProofResult {
@@ -45,31 +76,79 @@ export interface ProofStatusResult {
     error_code?: string;
 }
 export declare function checkProofStatus(patronNpub: string, dpopToken: string): Promise<ProofStatusResult>;
+/** One credit tranche: a purchase (or grant) and what is left of it. */
+export interface CreditTranche {
+    id: string;
+    amount_sats: number;
+    remaining_sats: number;
+    expires_at: string | null;
+    created_at: string | null;
+}
 export interface CheckBalanceResult {
     success?: boolean;
     balance_api_sats?: number;
     total_deposited_api_sats?: number;
     total_consumed_api_sats?: number;
+    total_expired_api_sats?: number;
+    pending_invoices?: number;
+    pending_invoice_ids?: string[];
+    last_deposit_at?: string | null;
     next_expiration_iso?: string;
     expiring_within_24h_sats?: number;
+    active_tranches?: number;
+    tranches?: CreditTranche[];
+    expired_tranches?: CreditTranche[];
+    seed_balance_granted?: boolean;
+    /** The ledger could not be read: the figures may be stale or zero. */
+    vault_unavailable?: boolean;
+    warning?: string;
+    today_usage?: Record<string, {
+        calls: number;
+        api_sats: number;
+    }>;
+    invoice_summary?: {
+        total_invoices: number;
+        settled_count: number;
+        pending_count: number;
+        total_real_sats: number;
+        total_api_sats_credited: number;
+    };
     error?: string;
     error_code?: string;
 }
 export declare function checkBalance(): Promise<CheckBalanceResult>;
+export interface ConstraintEffect {
+    type: string;
+    message?: string;
+    [key: string]: unknown;
+}
+/** The wheel's `check_price` preview. */
 export interface CheckPriceResult {
     success: boolean;
     tool_id?: string;
-    base_cost_api_sats?: number;
-    effective_cost_api_sats?: number;
+    tool_name?: string;
+    /** "flat" | "flat+multipliers" | "percent" */
+    pricing_type?: string;
+    base_cost_api_sats?: number | null;
+    effective_cost_api_sats?: number | null;
+    rate_percent?: number;
+    rate_param?: string;
+    min_cost_sats?: number;
+    multipliers?: Record<string, unknown>;
+    constraints_enabled?: boolean;
+    constraint_effects?: ConstraintEffect[];
+    hint?: string;
     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.
+ * constraints included — keyed by the tool's frozen UUID (or its capability
+ * name). `toolKwargs` are the call's own parameters, for a tool priced by
+ * them (ad valorem, or a multiplier on a categorical argument). Null when
+ * unreadable: show the answer without a price rather than invent one.
  */
-export declare function checkPrice(toolId: string): Promise<number | null>;
+export declare function checkPrice(toolId: string, toolKwargs?: Record<string, unknown>): Promise<number | null>;
 export interface PurchaseCreditsResult {
     success?: boolean;
     invoice_id?: string;
@@ -89,23 +168,107 @@ export interface CheckPaymentResult {
     invoice_id?: string;
     credits_granted?: number;
     balance_api_sats?: number;
+    amount_sats?: number;
+    /** false: the credit could not be written; nothing was granted. */
+    persisted?: boolean;
+    source?: string;
     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, {
+export interface StatementInvoice {
+    invoice_id: string;
+    status: string;
+    amount_sats: number;
+    api_sats_credited: number;
+    multiplier?: number;
+    created_at: string | null;
+    settled_at?: string;
+}
+export interface StatementTranche {
+    granted_at: string | null;
+    original_sats: number;
+    remaining_sats: number;
+    invoice_id: string | null;
+    expires_at?: string;
+}
+export interface StatementToolUsage {
+    tool: string;
+    calls: number;
+    api_sats: number;
+}
+export interface StatementDay {
+    date: string;
+    total_calls: number;
+    total_api_sats: number;
+    tools: Record<string, {
         calls: number;
         api_sats: number;
     }>;
+}
+/** The wheel's `account_statement`: history, tranches and usage, newest first. */
+export interface AccountStatementResult {
+    success?: boolean;
+    generated_at?: string;
+    statement_period_days?: number;
+    account_summary?: {
+        balance_api_sats: number;
+        total_deposited_api_sats: number;
+        total_consumed_api_sats: number;
+        total_expired_api_sats: number;
+    };
+    purchase_history?: StatementInvoice[];
+    active_tranches?: StatementTranche[];
+    tool_usage_all_time?: StatementToolUsage[];
+    daily_usage?: StatementDay[];
     error?: string;
+    error_code?: string;
 }
 export declare function getAccountStatement(days?: number): Promise<AccountStatementResult>;
+export interface PatronCoupon {
+    coupon_id: string;
+    name: string;
+    discount_percent: number;
+    valid_from: string;
+    valid_until: string;
+    uses_per_patron: number | null;
+    use_count: number;
+    uses_remaining: number | null;
+    total_uses: number | null;
+    total_remaining: number | null;
+    /** active | window_closed | window_not_started | patron_limit | total_limit */
+    status: string;
+}
+export interface ListMyCouponsResult {
+    success?: boolean;
+    count?: number;
+    coupons?: PatronCoupon[];
+    error?: string;
+    error_code?: string;
+}
+export interface RedeemCouponResult {
+    success?: boolean;
+    coupon_id?: string;
+    name?: string;
+    discount_percent?: number;
+    valid_until?: string;
+    uses_remaining?: number | null;
+    uses_per_patron?: number | null;
+    error?: string;
+    error_code?: string;
+}
+export interface ForgetCouponResult {
+    success?: boolean;
+    coupon_id?: string;
+    error?: string;
+    error_code?: string;
+}
+/** The coupons this patron has redeemed here. Free. */
+export declare function listMyCoupons(): Promise<ListMyCouponsResult>;
+/** Redeem an operator's code once; the discount then applies on its own. Free. */
+export declare function redeemCoupon(code: string): Promise<RedeemCouponResult>;
+/** Take a coupon off the patron's list. The code stays re-redeemable while its window allows. */
+export declare function forgetCoupon(couponId: string): Promise<ForgetCouponResult>;
 export interface Kind0 {
     name?: string;
     display_name?: string;
@@ -132,3 +295,149 @@ export interface PublishNostrProfileResult {
 }
 /** 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>;
+/** Every lifecycle `session_status` reports. */
+export type SessionLifecycle = "ready" | "warming_up" | "misconfigured" | "quota_exceeded" | "not_registered" | "no_identity";
+/** The patron's stored upstream OAuth token, when the operator has a provider. */
+export interface UpstreamOAuth {
+    service: string;
+    has_access_token: boolean;
+    has_refresh_token: boolean;
+    refresh_enabled: boolean;
+    access_token_expires_at?: number;
+    access_token_expires_in_seconds?: number;
+}
+export interface SessionStatusResult {
+    success?: boolean;
+    lifecycle?: SessionLifecycle;
+    message?: string;
+    operator_npub?: string;
+    /** Why it is not ready, from the failing layer. */
+    detail?: string;
+    operator_credential_service?: string;
+    patron_credential_service?: string;
+    upstream_oauth?: UpstreamOAuth;
+    /** The vault could not answer — not the same as "never authorized". */
+    upstream_oauth_unreadable?: string;
+    error?: string;
+    error_code?: string;
+}
+/**
+ * Is the operator ready to serve? Free, no proof. With `patronNpub`, also the
+ * patron's upstream OAuth token expiry, so a page can refresh ahead of time.
+ */
+export declare function sessionStatus(patronNpub?: string): Promise<SessionStatusResult>;
+export interface OnboardingItem {
+    field: string;
+    /** "identity" | "authority" | "secret" */
+    category: string;
+    /** "configured" | "missing" | "unknown" */
+    status: string;
+    how?: string;
+    lifecycle?: string;
+    delivered_at?: string | null;
+}
+/** The wheel's `get_operator_onboarding_status`: what the operator still has to set up. */
+export interface OperatorOnboardingStatus {
+    ready?: boolean;
+    configured?: OnboardingItem[];
+    missing?: OnboardingItem[];
+    optional_missing?: OnboardingItem[];
+    summary?: string;
+    bootstrap_error?: string;
+    vault_ok?: boolean;
+    /** Set when the credential vault could not be read: nothing is known either way. */
+    vault_situation?: string;
+    credential_greeting?: string | null;
+    credential_service?: string | null;
+    operator_name?: string;
+    error?: string;
+    error_code?: string;
+}
+export declare function getOperatorOnboardingStatus(): Promise<OperatorOnboardingStatus>;
+/**
+ * The operator's own balance at its Authority — what certifies patron top-ups.
+ * The Authority's ledger, in the same shape as a patron's `check_balance`.
+ */
+export declare function checkAuthorityBalance(): Promise<CheckBalanceResult>;
+export interface PricingStep {
+    id: string;
+    type: string;
+    params?: Record<string, unknown>;
+    patron_npubs?: string[];
+}
+export interface ToolPrice {
+    tool_id: string;
+    tool_name: string;
+    price_sats: number;
+    category: string;
+    intent: string;
+    priced: boolean;
+    price_type?: string;
+    price_formula?: unknown;
+    min_cost?: number;
+    max_cost?: number;
+    multipliers?: Record<string, unknown>;
+    chain?: PricingStep[];
+}
+/** The wheel's `get_pricing_model`. `status` is "ok" or "error". */
+export interface PricingModelResult {
+    status?: string;
+    model_id?: string | null;
+    name?: string | null;
+    is_active?: boolean | null;
+    tools?: ToolPrice[] | null;
+    tranche_lifetime?: {
+        target_usage_pct: number;
+        ttl_days?: number;
+        min_days?: number;
+        max_days?: number;
+    };
+    error?: string;
+}
+/** The operator's active pricing model. Free, no proof. */
+export declare function getPricingModel(): Promise<PricingModelResult>;
+export interface CanonicalIdentity {
+    tool_id: string;
+    mcp_name: string;
+    category: string;
+    intent: string;
+    capability: string;
+    registered: boolean;
+    reason?: string;
+}
+/** The wheel's `list_canonical_identities`: every tool's frozen UUID and wire name. */
+export interface CanonicalIdentitiesResult {
+    success?: boolean;
+    operator_npub?: string;
+    count?: number;
+    unregistered_count?: number;
+    tools?: CanonicalIdentity[];
+    unregistered?: Array<{
+        mcp_name: string;
+        reason: string;
+        [key: string]: unknown;
+    }>;
+    error?: string;
+}
+export declare function listCanonicalIdentities(): Promise<CanonicalIdentitiesResult>;
+export interface PatronCredentialFieldsResult {
+    success?: boolean;
+    fields?: string[];
+    /** Per field, when it was delivered; null for secrets vaulted before stamps. */
+    delivered_at?: Record<string, string | null>;
+    count?: number;
+    error?: string;
+    error_code?: string;
+}
+export interface PatronCredentialWriteResult {
+    success?: boolean;
+    message?: string;
+    error?: string;
+    error_code?: string;
+}
+/** The names of the patron's stored credential fields — never their values. */
+export declare function getPatronCredentialFields(): Promise<PatronCredentialFieldsResult>;
+/** Set one credential field, leaving the others as they are. */
+export declare function updatePatronCredential(field: string, value: string): Promise<PatronCredentialWriteResult>;
+/** Remove one credential field, leaving the others as they are. */
+export declare function deletePatronCredential(field: string): Promise<PatronCredentialWriteResult>;

package/dist/standardTools.js

@@ -39,11 +39,16 @@ export function checkBalance() {
 }
 /**
  * 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.
+ * constraints included — keyed by the tool's frozen UUID (or its capability
+ * name). `toolKwargs` are the call's own parameters, for a tool priced by
+ * them (ad valorem, or a multiplier on a categorical argument). 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 });
+export async function checkPrice(toolId, toolKwargs) {
+    const r = await callTool("check_price", {
+        tool_id: toolId,
+        ...(toolKwargs ? { tool_kwargs: JSON.stringify(toolKwargs) } : {}),
+    });
     const v = r.effective_cost_api_sats ?? r.base_cost_api_sats;
     return typeof v === "number" ? v : null;
 }
@@ -56,6 +61,18 @@ export function checkPayment(invoiceId) {
 export function getAccountStatement(days = 30) {
     return callTool("account_statement", { days });
 }
+/** The coupons this patron has redeemed here. Free. */
+export function listMyCoupons() {
+    return callTool("list_my_coupons", {});
+}
+/** Redeem an operator's code once; the discount then applies on its own. Free. */
+export function redeemCoupon(code) {
+    return callTool("redeem_coupon", { code });
+}
+/** Take a coupon off the patron's list. The code stays re-redeemable while its window allows. */
+export function forgetCoupon(couponId) {
+    return callTool("forget_coupon", { coupon_id: couponId });
+}
 export function getNostrProfile(npub) {
     return callTool("get_nostr_profile", { npub });
 }
@@ -66,3 +83,40 @@ export function publishNostrProfile(npub, signedEvent) {
         signed_event: signedEvent,
     });
 }
+/**
+ * Is the operator ready to serve? Free, no proof. With `patronNpub`, also the
+ * patron's upstream OAuth token expiry, so a page can refresh ahead of time.
+ */
+export function sessionStatus(patronNpub) {
+    return callTool("session_status", patronNpub ? { patron_npub: patronNpub } : {}, { bestEffort: true });
+}
+export function getOperatorOnboardingStatus() {
+    return callTool("get_operator_onboarding_status", {}, { bestEffort: true });
+}
+/**
+ * The operator's own balance at its Authority — what certifies patron top-ups.
+ * The Authority's ledger, in the same shape as a patron's `check_balance`.
+ */
+export function checkAuthorityBalance() {
+    return callTool("check_authority_balance", {}, { bestEffort: true });
+}
+/** The operator's active pricing model. Free, no proof. */
+export function getPricingModel() {
+    return callTool("get_pricing_model", {});
+}
+export function listCanonicalIdentities() {
+    return callTool("list_canonical_identities", {});
+}
+/** The names of the patron's stored credential fields — never their values. */
+export function getPatronCredentialFields() {
+    return callTool("get_patron_credential_fields", {});
+}
+/** Set one credential field, leaving the others as they are. */
+export function updatePatronCredential(field, value) {
+    // `field` first: the log's scrubber keys on it to hide `value`.
+    return callTool("update_patron_credential", { field, value });
+}
+/** Remove one credential field, leaving the others as they are. */
+export function deletePatronCredential(field) {
+    return callTool("delete_patron_credential", { field });
+}