@tollbooth-dpyc/web 1.0.0 → 1.1.0

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

@@ -45,13 +45,36 @@ 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;
+    }>;
     error?: string;
     error_code?: string;
 }
@@ -93,19 +116,99 @@ export interface CheckPaymentResult {
     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;

package/dist/standardTools.js

@@ -56,6 +56,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 });
 }

package/dist/table.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Paging, sorting and filtering arithmetic for a table, without a framework.
+ *
+ * Pages are zero-based. A table may be paged by the server (it sends one page
+ * and a total) or in the browser (`pageRows` over the whole list); the
+ * arithmetic is the same either way.
+ */
+export type SortDir = "asc" | "desc";
+/** The last page's index for `total` rows. Zero when there are none. */
+export declare function lastPage(total: number, pageSize: number): number;
+/** A page index that exists: whole, and between 0 and the last page. */
+export declare function clampPage(page: number, total: number, pageSize: number): number;
+export declare function pageCount(total: number, pageSize: number): number;
+/** One page of an in-memory list. */
+export declare function pageRows<T>(rows: readonly T[], page: number, pageSize: number): T[];
+/**
+ * The sort after a header is tapped: the active column flips direction; a new
+ * column starts at `initial` (descending by default — newest, largest first).
+ */
+export declare function nextSort(col: string, activeCol: string, dir: SortDir, initial?: SortDir): {
+    col: string;
+    dir: SortDir;
+};
+/**
+ * A case-insensitive test for `pattern`. It is read as a regular expression
+ * when it is one, and as plain text when it is not, so a stray "(" in a search
+ * box finds the bracket rather than throwing. An empty pattern matches all.
+ */
+export declare function searchMatcher(pattern: string): (text: string) => boolean;
+/** The calendar day ("YYYY-MM-DD") of an ISO stamp or date, or null. */
+export declare function dayOf(value: string | null | undefined): string | null;
+/**
+ * Whether `value` falls in the inclusive range [from, to], compared by day.
+ * An empty bound is open. A row with no date is outside any range that has
+ * a bound, and inside one that has none.
+ */
+export declare function inDateRange(value: string | null | undefined, from: string, to: string): boolean;
+export interface RowFilter {
+    search: string;
+    dateFrom: string;
+    dateTo: string;
+}
+export declare const NO_FILTER: RowFilter;
+export declare function filterActive(f: Partial<RowFilter>, summary?: string): boolean;
+/**
+ * Filter rows in the browser, for a table the server does not filter.
+ * `text` gives what the search reads; `date` the stamp the range reads.
+ */
+export declare function filterRows<T>(rows: readonly T[], f: Partial<RowFilter>, by: {
+    text: (row: T) => string;
+    date?: (row: T) => string | null | undefined;
+}): T[];

package/dist/table.js

@@ -0,0 +1,95 @@
+/**
+ * Paging, sorting and filtering arithmetic for a table, without a framework.
+ *
+ * Pages are zero-based. A table may be paged by the server (it sends one page
+ * and a total) or in the browser (`pageRows` over the whole list); the
+ * arithmetic is the same either way.
+ */
+/** The last page's index for `total` rows. Zero when there are none. */
+export function lastPage(total, pageSize) {
+    if (!(pageSize > 0) || !(total > 0))
+        return 0;
+    return Math.max(0, Math.ceil(total / pageSize) - 1);
+}
+/** A page index that exists: whole, and between 0 and the last page. */
+export function clampPage(page, total, pageSize) {
+    const p = Number.isFinite(page) ? Math.trunc(page) : 0;
+    return Math.min(Math.max(0, p), lastPage(total, pageSize));
+}
+export function pageCount(total, pageSize) {
+    return lastPage(total, pageSize) + 1;
+}
+/** One page of an in-memory list. */
+export function pageRows(rows, page, pageSize) {
+    if (!(pageSize > 0))
+        return [...rows];
+    const p = clampPage(page, rows.length, pageSize);
+    return rows.slice(p * pageSize, (p + 1) * pageSize);
+}
+/**
+ * The sort after a header is tapped: the active column flips direction; a new
+ * column starts at `initial` (descending by default — newest, largest first).
+ */
+export function nextSort(col, activeCol, dir, initial = "desc") {
+    if (col === activeCol)
+        return { col, dir: dir === "desc" ? "asc" : "desc" };
+    return { col, dir: initial };
+}
+// ── Filtering ──────────────────────────────────────────────────────────────
+/**
+ * A case-insensitive test for `pattern`. It is read as a regular expression
+ * when it is one, and as plain text when it is not, so a stray "(" in a search
+ * box finds the bracket rather than throwing. An empty pattern matches all.
+ */
+export function searchMatcher(pattern) {
+    const p = pattern.trim();
+    if (!p)
+        return () => true;
+    try {
+        const re = new RegExp(p, "i");
+        return (text) => re.test(text);
+    }
+    catch {
+        const needle = p.toLowerCase();
+        return (text) => text.toLowerCase().includes(needle);
+    }
+}
+/** The calendar day ("YYYY-MM-DD") of an ISO stamp or date, or null. */
+export function dayOf(value) {
+    if (!value)
+        return null;
+    const m = /^(\d{4}-\d{2}-\d{2})/.exec(value);
+    return m ? m[1] : null;
+}
+/**
+ * Whether `value` falls in the inclusive range [from, to], compared by day.
+ * An empty bound is open. A row with no date is outside any range that has
+ * a bound, and inside one that has none.
+ */
+export function inDateRange(value, from, to) {
+    if (!from && !to)
+        return true;
+    const day = dayOf(value);
+    if (!day)
+        return false;
+    if (from && day < from)
+        return false;
+    if (to && day > to)
+        return false;
+    return true;
+}
+export const NO_FILTER = { search: "", dateFrom: "", dateTo: "" };
+export function filterActive(f, summary = "") {
+    return !!(f.search?.trim() || f.dateFrom || f.dateTo || summary);
+}
+/**
+ * Filter rows in the browser, for a table the server does not filter.
+ * `text` gives what the search reads; `date` the stamp the range reads.
+ */
+export function filterRows(rows, f, by) {
+    const match = searchMatcher(f.search ?? "");
+    const from = f.dateFrom ?? "";
+    const to = f.dateTo ?? "";
+    const ranged = !!(from || to) && !!by.date;
+    return rows.filter((r) => match(by.text(r)) && (!ranged || inDateRange(by.date(r), from, to)));
+}

package/dist/theme.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Light, dark or the system's choice — kept under `<prefix>:theme` so a
+ * returning patron keeps their pick, and applied to <html> before first paint.
+ *
+ * Mechanics only; the colours are the site's. Applying a theme sets all three
+ * hooks a stylesheet might key on, so every fleet site's CSS keeps working:
+ *   - the `dark` class (Tailwind `darkMode: "class"`, `@custom-variant dark`),
+ *   - `data-theme="light" | "dark"` (the package's theme.css and token sheets),
+ *   - `color-scheme` (native form controls and scrollbars).
+ * "system" resolves to the OS preference and follows it live.
+ */
+export type Theme = "dark" | "light" | "system";
+export type EffectiveTheme = "dark" | "light";
+export declare const THEMES: readonly Theme[];
+export declare function isTheme(v: unknown): v is Theme;
+/** The stored pick, or `fallback` when nothing (or nonsense) is stored. */
+export declare function parseTheme(raw: string | null | undefined, fallback?: Theme): Theme;
+export declare function themeStorageKey(): string;
+export declare function readTheme(fallback?: Theme): Theme;
+export declare function writeTheme(theme: Theme): void;
+export declare function systemPrefersDark(): boolean;
+export declare function resolveTheme(theme: Theme, prefersDark?: boolean): EffectiveTheme;
+/** The part of <html> a theme touches — narrow, so it is testable without a DOM. */
+export interface ThemeTarget {
+    classList: {
+        toggle(token: string, force?: boolean): unknown;
+    };
+    setAttribute(name: string, value: string): void;
+    style: {
+        colorScheme: string;
+    };
+}
+export declare function applyTheme(theme: Theme, target?: ThemeTarget, prefersDark?: boolean): EffectiveTheme;
+/**
+ * Apply the stored theme. Call once in main.tsx, after `configureTollbooth`
+ * and before rendering, so the first frame has the right palette.
+ */
+export declare function bootstrapTheme(fallback?: Theme): Theme;
+/** The pick after `current`, for a single chip that cycles. */
+export declare function nextTheme(current: Theme, order?: readonly Theme[]): Theme;

package/dist/theme.js

@@ -0,0 +1,76 @@
+/**
+ * Light, dark or the system's choice — kept under `<prefix>:theme` so a
+ * returning patron keeps their pick, and applied to <html> before first paint.
+ *
+ * Mechanics only; the colours are the site's. Applying a theme sets all three
+ * hooks a stylesheet might key on, so every fleet site's CSS keeps working:
+ *   - the `dark` class (Tailwind `darkMode: "class"`, `@custom-variant dark`),
+ *   - `data-theme="light" | "dark"` (the package's theme.css and token sheets),
+ *   - `color-scheme` (native form controls and scrollbars).
+ * "system" resolves to the OS preference and follows it live.
+ */
+import { tollboothConfig } from "./config.js";
+export const THEMES = ["dark", "light", "system"];
+export function isTheme(v) {
+    return v === "dark" || v === "light" || v === "system";
+}
+/** The stored pick, or `fallback` when nothing (or nonsense) is stored. */
+export function parseTheme(raw, fallback = "dark") {
+    return isTheme(raw) ? raw : fallback;
+}
+export function themeStorageKey() {
+    return `${tollboothConfig().storagePrefix}:theme`;
+}
+export function readTheme(fallback = "dark") {
+    try {
+        return parseTheme(globalThis.localStorage?.getItem(themeStorageKey()), fallback);
+    }
+    catch {
+        return fallback; // blocked site data, or not configured yet
+    }
+}
+export function writeTheme(theme) {
+    try {
+        globalThis.localStorage?.setItem(themeStorageKey(), theme);
+    }
+    catch {
+        /* the choice still applies for this page */
+    }
+}
+export function systemPrefersDark() {
+    try {
+        return !!globalThis.matchMedia?.("(prefers-color-scheme: dark)").matches;
+    }
+    catch {
+        return false;
+    }
+}
+export function resolveTheme(theme, prefersDark = systemPrefersDark()) {
+    if (theme === "system")
+        return prefersDark ? "dark" : "light";
+    return theme;
+}
+export function applyTheme(theme, target, prefersDark) {
+    const effective = resolveTheme(theme, prefersDark);
+    const el = target ?? globalThis.document?.documentElement;
+    if (el) {
+        el.classList.toggle("dark", effective === "dark");
+        el.setAttribute("data-theme", effective);
+        el.style.colorScheme = effective;
+    }
+    return effective;
+}
+/**
+ * Apply the stored theme. Call once in main.tsx, after `configureTollbooth`
+ * and before rendering, so the first frame has the right palette.
+ */
+export function bootstrapTheme(fallback = "dark") {
+    const theme = readTheme(fallback);
+    applyTheme(theme);
+    return theme;
+}
+/** The pick after `current`, for a single chip that cycles. */
+export function nextTheme(current, order = THEMES) {
+    const i = order.indexOf(current);
+    return order[(i + 1) % order.length] ?? order[0];
+}

package/dist/wallet.d.ts

@@ -0,0 +1,85 @@
+/**
+ * The wallet's logic without a framework: the top-up state machine, the reading
+ * of a check_payment answer, and the words a coupon row needs. Pure, so it is
+ * tested without React or a server.
+ *
+ * A top-up goes idle → creating → awaiting (an invoice is out) → settled, or
+ * back to idle on cancel, or to failed when the invoice expires, is invalid or
+ * the service refuses. While awaiting, check_payment may be polled: it is free,
+ * idempotent and safe to repeat, unlike receive_npub_proof.
+ */
+import type { CheckPaymentResult, PatronCoupon, PurchaseCreditsResult } from "./standardTools.ts";
+/** One invoice the patron has been handed. */
+export interface Invoice {
+    id: string;
+    /** BTCPay's checkout page, when the service gave one. */
+    checkoutLink: string | null;
+    /** The BOLT11 string, for a wallet that takes a paste. */
+    bolt11: string | null;
+    sats: number;
+}
+export type TopUpState = {
+    phase: "idle";
+    message: string | null;
+} | {
+    phase: "creating";
+    sats: number;
+} | {
+    phase: "awaiting";
+    invoice: Invoice;
+    checking: boolean;
+    status: string | null;
+    checks: number;
+} | {
+    phase: "settled";
+    invoice: Invoice;
+    credited: number;
+} | {
+    phase: "failed";
+    invoice: Invoice | null;
+    message: string;
+};
+export type TopUpEvent = {
+    type: "create";
+    sats: number;
+} | {
+    type: "created";
+    result: PurchaseCreditsResult;
+} | {
+    type: "check";
+} | {
+    type: "checked";
+    result: CheckPaymentResult;
+} | {
+    type: "error";
+    message: string;
+} | {
+    type: "cancel";
+} | {
+    type: "reset";
+};
+export declare const TOP_UP_IDLE: TopUpState;
+/** Where an invoice stands, from BTCPay's status word. */
+export type PaymentPhase = "waiting" | "settled" | "expired" | "invalid";
+export declare function paymentPhase(status: string | undefined | null): PaymentPhase;
+/** The invoice in a purchase_credits answer, or null when there is none to pay. */
+export declare function invoiceFrom(result: PurchaseCreditsResult, asked: number): Invoice | null;
+/** A whole number of sats worth invoicing, from what the patron typed; else null. */
+export declare function parseSats(input: string | number): number | null;
+export declare function topUpReducer(state: TopUpState, event: TopUpEvent): TopUpState;
+/** Whether a poll should run now: an invoice is out, nothing is in flight, and the budget is not spent. */
+export declare function shouldPoll(state: TopUpState, maxChecks: number): boolean;
+/** Sats as the fleet writes them. Null is unknown, and unknown is a dash, never 0. */
+export declare function formatSats(n: number | null | undefined): string;
+/** The wheel's coupon status, in words a patron reads. */
+export declare function couponStatusLabel(status: string): string;
+export declare function couponUsesText(c: Pick<PatronCoupon, "uses_per_patron" | "uses_remaining">): string;
+/** Whole days until the window closes, never below zero; null when the date is unreadable. */
+export declare function couponDaysLeft(validUntil: string, now?: number): number | null;
+export declare function couponExpiryText(validUntil: string, now?: number): string | null;
+/** What a successful redeem_coupon says back. */
+export declare function redeemedText(r: {
+    name?: string;
+    discount_percent?: number;
+    uses_remaining?: number | null;
+}): string;