@hachej/boring-core 0.1.41 → 0.1.43

package/dist/app/front/index.d.ts

@@ -10,16 +10,28 @@ interface ChatFirstPublicShellOptions {
         eyebrow?: string;
         title?: string;
         description?: string;
+        footer?: ReactNode;
     };
     suggestions?: ChatSuggestion[];
+    /**
+     * Hand-drawn "Your agent" / "Your remote computer" annotations point at the
+     * composer and the workspace surface to teach the empty public shell. Apps
+     * that open a center panel on load (e.g. a landing page) should disable them,
+     * otherwise the fixed-position arrows overlay the open panel. Defaults to on.
+     */
+    showTeachingArrows?: boolean;
 }
 
 type ChatEntryMode = 'auth-first' | 'chat-first';
-interface CoreWorkspaceAgentFrontProps<TSession extends WorkspaceAgentSession = WorkspaceAgentSession> extends Omit<WorkspaceAgentFrontProps<TSession>, 'workspaceId' | 'frontPluginHotReload' | 'hotReloadEnabled'> {
+type RoutedWorkspaceAgentProps<TSession extends WorkspaceAgentSession = WorkspaceAgentSession> = Omit<WorkspaceAgentFrontProps<TSession>, 'workspaceId' | 'frontPluginHotReload' | 'hotReloadEnabled'>;
+interface CoreWorkspaceAgentFrontProps<TSession extends WorkspaceAgentSession = WorkspaceAgentSession> extends RoutedWorkspaceAgentProps<TSession> {
     /** Core consumes plugins statically for now; app-level hot reload is explicitly unsupported. */
     hotReload?: false;
     chatEntryMode?: ChatEntryMode;
     chatFirstPublicShell?: ChatFirstPublicShellOptions;
+    /** Extra workspace props used only by the unauthenticated chat-first public shell. */
+    chatFirstPublicWorkspaceProps?: Partial<RoutedWorkspaceAgentProps<TSession>>;
+    publicPaths?: string[];
     authPages?: CoreFrontAuthPagesOverride;
     cspNonce?: string;
     children?: ReactNode;
@@ -29,6 +41,203 @@ interface CoreWorkspaceAgentFrontProps<TSession extends WorkspaceAgentSession =
     loadingFallback?: ReactNode;
     bootPreloadPaths?: string[];
 }
-declare function CoreWorkspaceAgentFront<TSession extends WorkspaceAgentSession = WorkspaceAgentSession>({ authPages, cspNonce, children, workspaceRoute, workspaceIdParam, workspaceHref, loadingFallback, bootPreloadPaths, topBarLeft, topBarRight, appTitle, bridgeEndpoint, hotReload, chatEntryMode, chatFirstPublicShell, ...workspaceProps }: CoreWorkspaceAgentFrontProps<TSession>): react_jsx_runtime.JSX.Element;
+/** Default top-bar right content. Exported so apps can compose extra widgets
+ * (e.g. a credit balance badge) alongside the user menu. */
+declare function DefaultTopBarRight(): react_jsx_runtime.JSX.Element;
+declare function CoreWorkspaceAgentFront<TSession extends WorkspaceAgentSession = WorkspaceAgentSession>({ authPages, cspNonce, children, workspaceRoute, workspaceIdParam, workspaceHref, loadingFallback, bootPreloadPaths, topBarLeft, topBarRight, appTitle, bridgeEndpoint, hotReload, chatEntryMode, chatFirstPublicShell, chatFirstPublicWorkspaceProps, publicPaths, ...workspaceProps }: CoreWorkspaceAgentFrontProps<TSession>): react_jsx_runtime.JSX.Element;
 
-export { type ChatFirstPublicShellOptions, CoreWorkspaceAgentFront, type CoreWorkspaceAgentFrontProps };
+interface CreditBalanceBadgeProps {
+    /** Base URL for the credits API (default: same origin). */
+    apiBaseUrl?: string;
+    /** Fallback enable for the add-credits action. The server's `checkoutEnabled`
+     * (from /api/credits/balance) takes precedence when present. */
+    buyEnabled?: boolean;
+    /** Poll interval for the balance, ms (default 30s). */
+    pollMs?: number;
+    locale?: string;
+}
+/**
+ * Top-bar credit balance: a DISCRETE remaining-balance figure plus a small "+" button.
+ * Clicking "+" opens a popover of fixed top-up amounts (Anthropic-style); picking one starts
+ * the server-created checkout and opens it. Polls `/api/credits/balance`; hides itself when
+ * credits are disabled or the user is unauthenticated.
+ */
+declare function CreditBalanceBadge({ apiBaseUrl, buyEnabled, pollMs, locale, }: CreditBalanceBadgeProps): react_jsx_runtime.JSX.Element | null;
+
+interface CreditsSettingsPanelProps {
+    /** Base URL for the credits API (default: same origin). */
+    apiBaseUrl?: string;
+    locale?: string;
+}
+/**
+ * Account-settings "Billing & credits" panel: current balance (+ debt/low notices,
+ * staleness), a pack picker → checkout, and a lazy-loaded recent-activity list.
+ * Renders nothing when credits are disabled or the user is unauthenticated.
+ */
+declare function CreditsSettingsPanel({ apiBaseUrl, locale }: CreditsSettingsPanelProps): react_jsx_runtime.JSX.Element | null;
+
+/** Front-end helpers for the credit balance badge + buy-credits flow. */
+/** Display-ready credit pack (server-authored). The client never infers price from
+ * the id and never sees the provider's price/variant id. */
+interface CreditPack {
+    id: string;
+    creditMicros: number;
+    /** Price in the currency's minor unit (e.g. cents). For a custom pack, the MINIMUM. */
+    priceMinor: number;
+    currency: string;
+    label: string;
+    isDefault: boolean;
+    /** Pay-what-you-want pack: the buyer enters the amount on the hosted checkout, so
+     * `creditMicros` is 0 here and `priceMinor` is the minimum. The picker shows an
+     * "enter amount" option instead of a fixed price. */
+    custom?: boolean;
+}
+interface CreditBalanceResponse {
+    enabled: boolean;
+    userId: string;
+    grantedMicros: number;
+    usedMicros: number;
+    remainingMicros: number;
+    activeReservedMicros: number;
+    availableMicros: number;
+    /** Amount owed when the ledger went negative (e.g. refund of spent credits). */
+    debtMicros: number;
+    /** Server truth: whether the Buy-credits checkout is wired (avoids client drift). */
+    checkoutEnabled?: boolean;
+    /** Display-ready packs (present only when checkout is wired). */
+    packs?: CreditPack[];
+    currency: 'credits';
+}
+type CreditLedgerKind = 'grant' | 'purchase' | 'usage' | 'refund' | 'fallback';
+/** One credit-activity row (mirrors the server `CreditLedgerEntry`). `amountMicros`
+ * is signed: positive = added, negative = consumed/removed. */
+interface CreditLedgerEntry {
+    id: string;
+    kind: CreditLedgerKind;
+    amountMicros: number;
+    createdAt: string;
+    description: string;
+}
+/** Format SIGNED credit micros as a euro string with an explicit +/− sign. */
+declare function formatSignedCreditMicros(micros: number, locale?: string): string;
+/** Format a minor-unit price (e.g. cents) in its currency for pack labels/buttons. */
+declare function formatMinorPrice(priceMinor: number, currency: string, locale?: string): string;
+/** Format credit micros as a euro string. 1 credit = €0.000001 ⇒ µ/1e6 euros. */
+declare function formatCreditMicros(micros: number, locale?: string): string;
+/** True when the remaining balance is at or below the low-balance threshold. */
+declare function isLowBalance(micros: number, thresholdMicros?: number): boolean;
+/** Stable server error code for an out-of-credits rejection (mirrors the agent's
+ * ErrorCode enum). Kept here so the credits feature owns the credit↔code mapping
+ * and the agent stays billing-agnostic. */
+declare const PAYMENT_REQUIRED_ERROR_CODE = "PAYMENT_REQUIRED";
+/** True when a run-rejected notice was an out-of-credits rejection. Hosts use this
+ * in renderNoticeAction to decide whether to show the Buy-credits CTA. */
+declare function isPaymentRequiredNotice(notice: {
+    errorCode?: string;
+}): boolean;
+
+/** Window event other code can dispatch to force an immediate balance refetch —
+ * e.g. the chat dispatching `window.dispatchEvent(new Event(CREDITS_REFRESH_EVENT))`
+ * when a run finishes, so the balance updates without waiting for the poll. */
+declare const CREDITS_REFRESH_EVENT = "credits:refresh";
+interface UseCreditBalanceOptions {
+    /** Base URL for the credits API (default: same origin). */
+    apiBaseUrl?: string;
+    /** Poll interval for the balance, ms (default 30s). */
+    pollMs?: number;
+    /** Credit pack id to purchase (server maps it to a Lemon Squeezy variant). */
+    pack?: string;
+}
+interface UseCreditBalanceResult {
+    /** Latest balance, or null before the first successful load. */
+    balance: CreditBalanceResponse | null;
+    /** True when credits are disabled or the user is unauthenticated (UI should hide). */
+    hidden: boolean;
+    /** Set when a balance fetch failed (network/server) before a successful load; null
+     * otherwise. Lets a consumer show an error state rather than an endless spinner. */
+    error: string | null;
+    /** Refetch the balance now. */
+    refresh: () => Promise<void>;
+    /** Refetch now, then a short backoff burst (~15s) — credit writes settle
+     * asynchronously after a run/purchase, so a single refetch can read a stale value.
+     * Concurrent bursts are deduped (a new call restarts the window). */
+    refreshWithRetry: () => void;
+    /** Start a Lemon Squeezy checkout (server creates it, sets the buyer id from the
+     * session) and open it in a new tab. Resolves to an error message on failure.
+     * Pass a pack id to buy a specific pack. */
+    buy: (pack?: string) => Promise<string | null>;
+    /** True while a checkout request is in flight. */
+    buying: boolean;
+    /** Epoch ms of the last successful balance read (null before first load). */
+    lastUpdatedAt: number | null;
+    /** True while a refresh (incl. a retry burst) is in flight. */
+    updating: boolean;
+}
+/**
+ * Shared credit-balance state for the top-bar badge and the settings panel:
+ * polls `/api/credits/balance`, refetches on window focus and on the
+ * `credits:refresh` event, and exposes a server-side checkout action. The buyer
+ * id is set SERVER-side (POST /api/credits/checkout) so the client never supplies it.
+ */
+declare function useCreditBalance({ apiBaseUrl, pollMs, pack, }?: UseCreditBalanceOptions): UseCreditBalanceResult;
+
+interface UseCreditHistoryResult {
+    entries: CreditLedgerEntry[] | null;
+    loading: boolean;
+    error: boolean;
+    /** Fetch (or refetch) the activity. Call lazily, e.g. when the section expands. */
+    load: () => Promise<void>;
+}
+/**
+ * Lazy loader for the account credit-activity list (`GET /api/credits/history`).
+ * Does NOT fetch on mount — call `load()` when the section is opened. `entries` is
+ * null until the first load; `[]` means "no activity yet".
+ */
+declare function useCreditHistory(apiBaseUrl?: string, limit?: number): UseCreditHistoryResult;
+
+type CheckoutReturnStatus = 'idle' | 'checking' | 'confirmed' | 'processing' | 'cancelled';
+interface UseCheckoutReturnHandlerOptions {
+    apiBaseUrl?: string;
+    /** Query param name the LS redirect uses (default 'checkout'). */
+    param?: string;
+}
+interface UseCheckoutReturnHandlerResult {
+    status: CheckoutReturnStatus;
+    dismiss: () => void;
+}
+/**
+ * Handle the return from a Lemon Squeezy hosted checkout. The URL marker (`?checkout=
+ * return|success|cancelled`) is NOT treated as proof of payment — on a return we poll
+ * the AUTHENTICATED balance and only show success once it actually increases (credits
+ * settle asynchronously via the webhook). The marker is stripped immediately so a reload
+ * can't replay it, and a `credits:refresh` event + BroadcastChannel signal refresh any
+ * other open app tab. Returns the status for a small banner to render.
+ */
+declare function useCheckoutReturnHandler({ apiBaseUrl, param }?: UseCheckoutReturnHandlerOptions): UseCheckoutReturnHandlerResult;
+
+interface CheckoutReturnBannerProps {
+    apiBaseUrl?: string;
+    /** Query param the LS redirect uses (default 'checkout'). */
+    param?: string;
+}
+/**
+ * Renders the post-checkout return state (see useCheckoutReturnHandler). Mount it once
+ * near the app root. It NEVER claims success from the URL — only after the server
+ * balance actually increases. ARIA-live so the status is announced. Self-hides when idle.
+ */
+declare function CheckoutReturnBanner({ apiBaseUrl, param }: CheckoutReturnBannerProps): react_jsx_runtime.JSX.Element | null;
+
+interface BuyCreditsNoticeActionProps {
+    /** Base URL for the credits API (default: same origin). */
+    apiBaseUrl?: string;
+    label?: string;
+}
+/**
+ * Inline "Buy credits" action for a PAYMENT_REQUIRED run-rejected notice. Self-contained:
+ * starts a server-created checkout (the buyer id is set server-side) on click. Renders
+ * nothing once the server reports checkout is disabled, so it can't dangle a dead button.
+ * Mount it from a host's renderNoticeAction (see isPaymentRequiredNotice).
+ */
+declare function BuyCreditsNoticeAction({ apiBaseUrl, label }: BuyCreditsNoticeActionProps): react_jsx_runtime.JSX.Element | null;
+
+export { BuyCreditsNoticeAction, type BuyCreditsNoticeActionProps, CREDITS_REFRESH_EVENT, type ChatFirstPublicShellOptions, CheckoutReturnBanner, type CheckoutReturnBannerProps, type CheckoutReturnStatus, CoreWorkspaceAgentFront, type CoreWorkspaceAgentFrontProps, CreditBalanceBadge, type CreditBalanceBadgeProps, type CreditBalanceResponse, type CreditLedgerEntry, type CreditLedgerKind, type CreditPack, CreditsSettingsPanel, type CreditsSettingsPanelProps, DefaultTopBarRight, PAYMENT_REQUIRED_ERROR_CODE, type UseCheckoutReturnHandlerResult, type UseCreditBalanceOptions, type UseCreditBalanceResult, type UseCreditHistoryResult, formatCreditMicros, formatMinorPrice, formatSignedCreditMicros, isLowBalance, isPaymentRequiredNotice, useCheckoutReturnHandler, useCreditBalance, useCreditHistory };