@arbidocs/blocks 0.4.147 → 0.4.150

package/dist/connection/billing/ProjectUsageContent.d.ts

@@ -0,0 +1,18 @@
+/**
+ * ProjectUsageContent — inline AI usage breakdown for a project.
+ *
+ * SVG line chart with composite color-coded lines.
+ * Toggle between breakdowns: User (default), Workspace, Model Tier.
+ * Resolves usr-xxx / wrk-xxx IDs to real names via workspace data.
+ * Data from LiteLLM via /v1/user/projects/{id}/usage.
+ *
+ * Rendered inline in the project card expander (no dialog).
+ */
+interface ProjectUsageContentProps {
+    projectExtId: string;
+    projectName: string;
+    /** Monthly AI usage quota in £ (quotas.ai_usage.limit) — enables the % indicator */
+    aiUsageLimit?: number;
+}
+export declare function ProjectUsageContent({ projectExtId, projectName, aiUsageLimit, }: ProjectUsageContentProps): import("react").JSX.Element;
+export {};

package/dist/connection/billing/ProjectsTable.d.ts

@@ -0,0 +1,13 @@
+/**
+ * ProjectsTable
+ *
+ * Compact list of the user's own projects. Each project is a single clickable
+ * line that opens the project's usage detail in its own tab; rename / delete /
+ * invoices / upgrade live as hover actions on the right. Plan + quota info only
+ * appears when Stripe billing is enabled (no plan concept otherwise).
+ *
+ * Projects owned by someone else aren't listed here — they're surfaced on the
+ * workspace cards the user collaborates on.
+ */
+/** The user's own projects: plan, usage, upgrade and invoices; a row opens the project. */
+export declare function ProjectsTable(): import("react").JSX.Element;

package/dist/connection/billing/ReduceAddonDialog.d.ts

@@ -0,0 +1,18 @@
+/**
+ * ReduceAddonDialog — confirm removing one AI usage / storage block (−£25 / −25 GB) from the next period.
+ *
+ * One click on "−" opens it; one click confirms. The reduction applies from the next renewal (`period_end`): this
+ * period's allowance stays until then and nothing is refunded, so an automatic top-up can be turned back down to
+ * cover only the current period. Each confirm removes one more block from what renews (today's blocks go first;
+ * legacy blocks keep their old size). Storage can't renew below what the files need (`storage_blocks_min`).
+ */
+import type { components } from '@arbidocs/client';
+import { type AddonKind } from './useAddonPurchase';
+type ProjectResponse = components['schemas']['ProjectResponse'];
+export declare function ReduceAddonDialog({ kind, project, open, onOpenChange, }: {
+    kind: AddonKind;
+    project: ProjectResponse;
+    open: boolean;
+    onOpenChange: (open: boolean) => void;
+}): import("react").JSX.Element | null;
+export {};

package/dist/connection/billing/ReferralReward.d.ts

@@ -0,0 +1,32 @@
+/**
+ * ReferralReward — binds the user's referral reward to the reward blocks.
+ *
+ * The reward is a single GLOBAL per-user Stripe account balance (mirrored read-only
+ * into `settings.extra_discount`) that auto-applies to the user's NEXT invoice. Surfaced as:
+ *   - `ReferralRewardBadge`   — standing indicator in the Projects tab header.
+ *   - `ReferralRewardSummary` — "subtotal / −reward / you pay now" where the charge is known
+ *                               exactly (new-project first invoice == the shown total).
+ *   - `ReferralRewardNote`    — a one-line note where the exact charge is a proration we
+ *                               can't compute client-side (switching an existing Pro plan).
+ *
+ * Logic + the `useReferralReward` hook live in `./referral-reward`; the presentation in
+ * `@arbidocs/blocks`.
+ */
+/** Standing pill for the Projects tab header — the global available reward. */
+export declare function ReferralRewardBadge(): import("react").JSX.Element | null;
+/**
+ * Available referral reward shown alongside a new-project purchase. When the exact charge is
+ * known (`totalCents` + `currency`), we do the math and show subtotal / −reward / you pay now;
+ * otherwise we fall back to a one-line note. Renders nothing when there's no reward.
+ */
+export declare function ReferralRewardSummary({ totalCents, currency, }: {
+    /** The known charge for this purchase, in minor units (e.g. pennies). */
+    totalCents?: number;
+    /** Currency of the charge — must match the reward's currency to apply. */
+    currency?: string;
+}): import("react").JSX.Element | null;
+/**
+ * One-line note for charges whose exact amount is a proration we don't compute client-side
+ * (switching an existing Pro subscription). Stripe applies the reward at charge time.
+ */
+export declare function ReferralRewardNote(): import("react").JSX.Element | null;

package/dist/connection/billing/SharedProjects.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Projects shared with you — the collaborator's view of other people's
+ * projects. You draw on their budget under a personal daily cap, and that
+ * allowance is the ONLY number that is yours to see: no plan, no billing,
+ * no project totals (the backend doesn't share them with non-owners, and
+ * pretending otherwise is what made this surface cryptic). Renders on every
+ * deployment — quotas are not a billing feature.
+ *
+ * `used_gbp` is the user's deployment-wide spend today; pairing it with
+ * each project's `daily_cap_per_user` is the sanctioned reading (see
+ * useUserUsageToday of @arbidocs/react).
+ */
+export declare function SharedProjects(): import("react").JSX.Element | null;

package/dist/connection/billing/StripeCheckoutModal.d.ts

@@ -0,0 +1,32 @@
+/**
+ * StripeCheckoutModal Component
+ *
+ * Modal with embedded Stripe checkout for a Pro subscription.
+ * Uses Stripe Elements for secure payment processing.
+ * Checkout is scoped to a specific project.
+ */
+import { type TaxQuote } from './tax-quote';
+interface StripeCheckoutModalProps {
+    projectExtId: string;
+    /** Pro billing interval: monthly or annual. */
+    interval: 'month' | 'year';
+    /** Monthly usage cap chosen at checkout (pence); null/omitted keeps the default. */
+    addonBudgetPence?: number | null;
+    /** Add-on blocks bought with the plan (+£25 of AI usage a month / +25 GB each): on the first invoice. */
+    aiBlocks?: number;
+    storageBlocks?: number;
+    promoCode?: string;
+    /** ISO-2 billing country picked before checkout; prefills the Stripe customer's address. */
+    billingCountry?: string;
+    /** ZIP / postcode, where the tax depends on it (e.g. the US). */
+    postalCode?: string;
+    /** The total quoted before checkout, repeated above Stripe's summary. */
+    quote?: TaxQuote;
+    open: boolean;
+    onOpenChange: (open: boolean) => void;
+    /** Called when Stripe reports the payment completed (before the dialog closes),
+     *  so callers can distinguish a successful checkout from a cancel/close. */
+    onCompleted?: () => void;
+}
+export declare function StripeCheckoutModal({ projectExtId, interval, addonBudgetPence, aiBlocks, storageBlocks, promoCode, billingCountry, postalCode, quote, open, onOpenChange, onCompleted, }: StripeCheckoutModalProps): import("react").JSX.Element;
+export {};

package/dist/connection/billing/SubscriptionPlans.d.ts

@@ -0,0 +1,15 @@
+/**
+ * SubscriptionPlans — upgrade a Free project to Pro (monthly or annual).
+ * Rendered inside the plan dialog. The total for the billing country (incl. tax) is quoted here,
+ * before Stripe Checkout opens.
+ */
+interface SubscriptionPlansProps {
+    projectExtId: string;
+    /** Declining the upgrade. When set, an explicit opt-out sits under Subscribe —
+     * a dialog that opens on you (the welcome modal) needs a way out that isn't the
+     * corner ✕. Omitted where the plans render inline (settings), which has no
+     * dialog to close. */
+    onDismiss?: () => void;
+}
+export declare function SubscriptionPlans({ projectExtId, onDismiss }: SubscriptionPlansProps): import("react").JSX.Element | null;
+export {};

package/dist/connection/billing/SubscriptionStatus.d.ts

@@ -0,0 +1,10 @@
+/**
+ * SubscriptionStatus: binds a project's quotas and billing state to the blocks status view
+ * (AI usage reset date, canceling notice, quota meters).
+ */
+import type { components } from '@arbidocs/client';
+interface SubscriptionStatusProps {
+    project: components['schemas']['ProjectResponse'];
+}
+export declare function SubscriptionStatus({ project }: SubscriptionStatusProps): import("react").JSX.Element;
+export {};

package/dist/connection/billing/addon-pricing.d.ts

@@ -0,0 +1,97 @@
+/** Add-on block price helpers (VAT-inclusive pence from `project.addons`). */
+import type { components } from '@arbidocs/client';
+import type { AddonKind } from './useAddonPurchase';
+type ProjectAddons = components['schemas']['ProjectAddons'];
+/** "3 Nov 2026". */
+export declare function formatPeriodEnd(unix: number | null | undefined): string | null;
+/** What one more block of this kind costs right now, incl. UK VAT. */
+export declare function addonPricePence(kind: AddonKind, addons: ProjectAddons): number;
+/** The same price ex VAT. */
+export declare function addonPriceExVatPence(kind: AddonKind, addons: ProjectAddons): number;
+/**
+ * The PUT /addons/settings body (the monthly usage cap and the automatic add-on trigger) from the current add-on
+ * state with the given changes applied.
+ */
+export declare function addonSettingsBody(addons: ProjectAddons, change?: Partial<{
+    spend_cap_pence: number | null;
+    auto_topup_threshold_gbp: number;
+}>): {
+    spend_cap_pence: number | null;
+    auto_topup_threshold_gbp: number;
+};
+/**
+ * Of `count` blocks of a kind, how many are on an earlier catalogue's price (legacy, at their old size: £10 of AI
+ * usage or 10 GB) and how many on today's. A reduction removes today's blocks first, so the legacy ones are the
+ * last kept.
+ */
+export declare function splitBlocks(kind: AddonKind, count: number, addons: ProjectAddons): {
+    legacy: number;
+    current: number;
+};
+/**
+ * "2 × £25 of AI usage", "1 × £10 + 1 × £25 of AI usage", "1 × 10 GB + 2 × 25 GB": `count` blocks of a kind, the
+ * legacy ones (kept last on a reduction) at their old size.
+ */
+export declare function blocksLabel(kind: AddonKind, count: number, addons: ProjectAddons): string;
+/**
+ * Bounds for "Reduce from next period": keep `min`..`current` blocks. `next` is what renews
+ * now (a pending reduction, or the current count). Storage can't go below what usage needs.
+ */
+export declare function reduceBounds(kind: AddonKind, addons: ProjectAddons): {
+    min: number;
+    current: number;
+    next: number;
+};
+/** What one add-on renews at: "£25/month + VAT" or "£225/year + VAT". */
+export declare function blockRenewalShort(kind: AddonKind, addons: ProjectAddons, isAnnual: boolean): string;
+/** The extra line annual plans show beside an AI usage add-on or upgrade price. */
+export declare const ANNUAL_PREMIUM_AI_NOTE = "No markup on Premium AI on annual plans";
+/** The confirm dialog's figures: charged now (incl. / ex VAT), what it covers until, then what renews. */
+export declare function addonCharge(kind: AddonKind, addons: ProjectAddons, isAnnual: boolean, periodEnd: number | null | undefined): {
+    now: string;
+    nowExVat: string;
+    nowVat: string;
+    until: string | null;
+    then: string;
+};
+/** Why automatic top-ups stopped (one line; the price of a step is on the Add button). */
+export declare const CAP_REACHED_MESSAGE = "Usage cap reached: no more automatic top-ups this month.";
+/** The £0 usage cap: no automatic top-ups (adding by hand still works). */
+export declare const ZERO_BUDGET_MESSAGE = "Automatic top-ups are off (\u00A30 usage cap).";
+/** The usage cap's heading wherever it is edited or shown. */
+export declare const USAGE_CAP_LABEL = "Usage cap";
+/** What the usage cap means (in "More info"): £0 and "No limit" explained. */
+export declare const USAGE_CAP_HELP: string;
+/** A £0 cap turns automatic top-ups off (manual adds still work). */
+export declare function isAddonBudgetZero(addons: Pick<ProjectAddons, 'spend_cap_pence'>): boolean;
+/**
+ * How much more of a resource automatic top-ups may add this month before the usage cap stops them, in the
+ * resource's unit (£ of AI usage / GB): the whole blocks the cap left pays for at today's ex-VAT price. `null` =
+ * no limit; 0 with a £0 cap or when not even one block fits.
+ */
+export declare function autoRoom(kind: AddonKind, addons: ProjectAddons): number | null;
+/** The size of the block a one-step reduction removes from what renews (today's blocks go first). */
+export declare function nextRemovedBlockSize(kind: AddonKind, addons: ProjectAddons): number;
+/**
+ * Pounds typed into a usage cap field → pence. '' → the default (null); invalid → undefined.
+ * Equal to the default is also sent as null ("keep the default").
+ */
+export declare function parseBudgetPounds(value: string): number | null | undefined;
+/** Toast after saving the usage cap. */
+export declare function budgetSavedMessage(capPence: number | null): string;
+/** "£25 of AI usage" / "25 GB". */
+export declare function stepLabel(kind: AddonKind, size: number): string;
+/** The PUT /addons/next-period body that renews `keep` blocks of `kind` (the other kind unchanged). */
+export declare function nextPeriodBody(kind: AddonKind, keep: number): {
+    ai_blocks: number;
+    storage_blocks: null;
+} | {
+    ai_blocks: null;
+    storage_blocks: number;
+};
+/**
+ * The "+" step's price line, ex VAT: "£25/month · today £25" (annual: "£18.75/month · today £150");
+ * storage, charged for the rest of the period: "£25/month · prorated today £8.33".
+ */
+export declare function addStepCaption(kind: AddonKind, addons: ProjectAddons): string;
+export {};

package/dist/connection/billing/api-error.d.ts

@@ -0,0 +1,6 @@
+/**
+ * The `detail` of a refused billing call: the response body's `detail` (a string, or the
+ * `{code, message}` of a payment refusal), whether the error is an SDK `ArbiApiError` (body in
+ * `apiError`) or the body itself.
+ */
+export declare function apiErrorDetail(error: unknown): unknown;

package/dist/connection/billing/billing-country.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Billing country chosen before checkout (ISO 3166-1 alpha-2). Sent to the checkout API as
+ * `billing_country` so the backend can prefill the Stripe customer's address, and Stripe Tax shows
+ * the tax-inclusive total from the first frame.
+ */
+export declare const DEFAULT_BILLING_COUNTRY = "GB";
+export declare const BILLING_COUNTRY_CODES: readonly string[];
+/** The select's options: the United Kingdom first, then every other country by name. */
+export declare function billingCountryOptions(): {
+    code: string;
+    name: string;
+}[];
+/** The region of the browser's first locale that names a country ("en-US" → "US"), else GB. */
+export declare function defaultBillingCountry(languages?: readonly string[]): string;

package/dist/connection/billing/billing-focus.d.ts

@@ -0,0 +1,11 @@
+export interface ProjectBillingFocus {
+    projectExtId: string;
+    /** Open the project's upgrade dialog. */
+    openUpgrade: boolean;
+    /** Scroll to and focus this card of the project's billing. */
+    section?: 'spend-cap';
+}
+/** Ask the billing UI to focus a project (or clear the request with `null`). */
+export declare function requestProjectBillingFocus(next: ProjectBillingFocus | null): void;
+/** The pending billing focus request, if any. */
+export declare function useProjectBillingFocus(): ProjectBillingFocus | null;

package/dist/connection/billing/index.d.ts

@@ -0,0 +1,22 @@
+/**
+ * The billing kit: a host's projects (plan, usage, add-ons, invoices), the plan picker and checkout,
+ * new projects, and the projects shared with the user. Stripe stays the host's
+ * (`BillingSupportProvider`); without it projects show their limits and usage only.
+ */
+export { BillingSupportProvider, useBillingSupport, type BillingSupport, type BillingCheckoutSupport, } from './support';
+export { requestProjectBillingFocus, useProjectBillingFocus, type ProjectBillingFocus, } from './billing-focus';
+export { ProjectsTable } from './ProjectsTable';
+export { SharedProjects } from './SharedProjects';
+export { ProjectDetail, type ProjectDetailProps } from './ProjectDetail';
+export { NewProjectFlow } from './NewProjectFlow';
+export { ChangePlanDialog } from './ChangePlanDialog';
+export { AddAddonDialog } from './AddAddonDialog';
+export { InvoicesModal } from './InvoicesModal';
+export { BillingProjectEntity, type BillingProjectEntityProps } from './BillingProjectEntity';
+export { useOpenBillingPortal } from './useOpenBillingPortal';
+export { useAutoRefreshPendingProjects } from './useAutoRefreshPendingProjects';
+export { formatMoney, useRewardBalance, type RewardBalance } from './reward-balance';
+export { REFERRAL_OFFER, useReferralReward } from './referral-reward';
+export { isProProject, planBadgeView, planName } from './plan-badge';
+export { aiUsageResetTimestamp, formatResetDate, getQuotaItems } from './quota-items';
+export { CAP_REACHED_MESSAGE, ZERO_BUDGET_MESSAGE, isAddonBudgetZero } from './addon-pricing';

package/dist/connection/billing/plan-badge.d.ts

@@ -0,0 +1,15 @@
+import type { PlanBadgeProps } from '../../settings';
+import type { components } from '@arbidocs/client';
+type ProjectBillingFields = Pick<components['schemas']['ProjectResponse'], 'subscription' | 'plan_interval'> & Partial<Pick<components['schemas']['ProjectResponse'], 'packs' | 'addons'>>;
+/** A project is on Pro when it has a billing interval (null = Free or checkout pending). */
+export declare function isProProject(project: Pick<ProjectBillingFields, 'plan_interval'>): boolean;
+/** "Pro", or a legacy multi-pack plan's name ("Pro ×N") — the API's name when it sends one (owner view). */
+export declare function proTierName(project: ProjectBillingFields): string;
+/** "Free", "Pro monthly", "Pro annual", "Pro ×3 monthly" (legacy) or "Dev" — the full plan name. */
+export declare function planName(project: ProjectBillingFields): string;
+/**
+ * Maps a project's billing state to the `PlanBadge` block's label + tone.
+ * Pro reads as accent, Free/dev as neutral, payment trouble or cancelling as pending.
+ */
+export declare function planBadgeView(project: ProjectBillingFields): Pick<PlanBadgeProps, 'label' | 'tone'>;
+export {};

package/dist/connection/billing/plan-change-outcome.d.ts

@@ -0,0 +1,15 @@
+/**
+ * What change-plan did, from `ProjectResponse.plan_change`, as one notification:
+ *  - upgraded        → "Upgraded to Pro · £48.00 charged"
+ *  - scheduled       → "Scheduled for 16 Nov 2026"
+ *  - requires_action → "Confirm with your bank. Nothing is charged until you do." + Confirm
+ *  - unchanged / no outcome → the caller's own message.
+ */
+import type { components } from '@arbidocs/client';
+type ProjectResponse = components['schemas']['ProjectResponse'];
+export declare const BANK_CONFIRM_PLAN_CHANGE = "Confirm with your bank. Nothing is charged until you do.";
+/** Returns the outcome's result, so callers can tell a finished upgrade from one still waiting. */
+export declare function notifyPlanChange(data: ProjectResponse | undefined, fallback: string, 
+/** The plan an upgrade went to, when the caller knows it. */
+planName?: string): 'upgraded' | 'scheduled' | 'unchanged' | 'requires_action' | null;
+export {};

package/dist/connection/billing/plan-constants.d.ts

@@ -0,0 +1,29 @@
+/** Pro's allowance per month (one licence) — must match the backend. Legacy multi-pack plans get it per pack.
+ *  The live numbers for an existing project come from `project.addons`; these are only for
+ *  describing the plan before a project exists (new-project dialog, upgrade picker). */
+export declare const PRO_AI_GBP = 10;
+export declare const PRO_STORAGE_GB = 5;
+/**
+ * Add-on block sizes (£25 of AI usage or 25 GB), the same on every plan. Their prices come from the
+ * products API (`addon_prices`) before a project exists, and from `project.addons` after.
+ */
+export declare const ADDON_BLOCK_AI_GBP = 25;
+export declare const STORAGE_BLOCK_GB = 25;
+/** Default monthly usage cap for a new Pro project (pence); it limits automatic top-ups only. 0 = no automatic
+ *  top-ups, null = no limit. */
+export declare const DEFAULT_SPEND_CAP_PENCE = 10000;
+/** The automatic add-on triggers when less than this much AI usage (£) remains; the backend minimum. */
+export declare const MIN_AUTO_TOPUP_THRESHOLD_GBP = 1;
+/** Free-tier quotas — must match backend FREE_* constants in src/constants.py
+ *  (FREE_AI_GBP=1, FREE_STORAGE_GB=0.05 → 50 MB, FREE_COLLABORATORS=0). */
+export declare const FREE_AI_GBP = 1;
+export declare const FREE_STORAGE_MB = 50;
+export declare const FREE_COLLABORATORS = 0;
+/** Collaborator limits at or above this are "unlimited" (the backend reports 999 for Pro/dev). */
+export declare const UNLIMITED_COLLABORATORS = 999;
+/**
+ * Suggested initial daily per-user AI usage cap (£), pre-filled when creating
+ * a new project. The user can clear it to create a project with no cap.
+ * Backend treats null as "no enforcement" — there is no server-side default.
+ */
+export declare const SUGGESTED_DAILY_CAP_PER_USER = 10;

package/dist/connection/billing/plan-pricing.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Pro plan price helpers. Prices come from Stripe via GET /v1/user/products (source of truth).
+ * One plan is sold: Pro, one licence (£10 of AI usage + 5 GB a month). Each price lists
+ * `pack_prices` for that one licence — `amount` incl. UK VAT and `amount_ex_vat` — and
+ * `addon_prices` (one add-on block on that interval). Display them as-is.
+ * Legacy subscriptions with several packs keep working; their name and price come from the project.
+ */
+import type { components } from '@arbidocs/client';
+type PlanChangePreview = components['schemas']['PlanChangePreview'];
+type ProductPrice = components['schemas']['ProductPrice'];
+type ProductResponse = components['schemas']['ProductResponse'];
+type PackPrice = components['schemas']['PackPrice'];
+type AddonPrice = components['schemas']['AddonPrice'];
+export type PlanInterval = 'month' | 'year';
+/** The headline price: "£40 + VAT". */
+export declare function plusVat(exVatPence: number, currency?: string): string;
+/** The one licence Pro sells. Other pack counts exist only on legacy subscriptions (displayed, not sold). */
+export declare const PRO_PACKS = 1;
+/** A plan the pickers offer. */
+export type PlanChoice = 'free' | 'pro';
+/** Packs per plan choice (0 = Free). */
+export declare const PLAN_CHOICE_PACKS: Record<PlanChoice, number>;
+/** "Free" (0), "Pro" (1), otherwise "Pro ×N" (a legacy multi-pack plan; the API's own name wins). */
+export declare function planNameForPacks(packs: number | null | undefined): string;
+/** The plan-change panel's fixed lines, each with a test id. */
+export interface PlanChangeLine {
+    id: 'pay-today' | 'from' | 'current-until' | 'no-change' | 'awaiting-bank';
+    text: string;
+}
+/**
+ * What a plan change costs, from the backend's Stripe invoice preview (taxed for the customer's
+ * address), as fixed lines:
+ *  - "Pay today £42.00 incl. VAT (£35.00 + £7.00 VAT 20%)" ("Pay today £0" for a change that waits)
+ *  - "From 16 Nov 2026: £210.00 incl. VAT (£175.00 + £35.00 VAT 20%) a month"
+ *  - "Current plan until 16 Nov 2026" for a change that waits for the period end.
+ * "No change" when the selection is what the project already has; "Waiting for your bank" while
+ * an earlier upgrade payment awaits 3-D Secure.
+ */
+export declare function planPreviewLines(preview: PlanChangePreview): PlanChangeLine[];
+/** Stand-in for "Pay today" when the preview failed for an upgrade. */
+export declare const PAY_TODAY_UNPRICED = "Pay today: the difference for the rest of this period";
+/** One add-on block's price on this interval's plan price (`addon_prices`), if listed. */
+export declare function addonPrice(price: ProductPrice | undefined, kind?: 'ai_usage' | 'storage'): AddonPrice | undefined;
+/** Per add-on block of `kind` per month, ex VAT (annual plans: the monthly equivalent). */
+export declare function addonMonthlyExVat(price: ProductPrice | undefined, kind?: 'ai_usage' | 'storage'): number | undefined;
+/**
+ * The add-on offer on this interval's price, each block with its own price:
+ * "£25 of AI usage for £25/month + VAT or 25 GB for £25/month + VAT". Null when unlisted.
+ */
+export declare function addonOfferText(price: ProductPrice | undefined): string | null;
+/** What a checkout buys: "Pro", "Pro + 2 × £25 of AI usage + 1 × 25 GB". */
+export declare function checkoutItemsLabel(aiBlocks: number, storageBlocks: number): string;
+/** The price of `packs` packs on this interval's price, if Stripe lists it (only one licence is listed). */
+export declare function packPrice(price: ProductPrice | undefined, packs?: number): PackPrice | undefined;
+export interface ProPrices {
+    monthly?: ProductPrice;
+    annual?: ProductPrice;
+}
+/** The Pro product's monthly and annual prices (default price per interval wins). */
+export declare function findProPrices(products: ProductResponse[] | undefined): ProPrices;
+/** Annual savings vs 12 × monthly, as a whole percent (e.g. £360 vs £480 → 25). */
+export declare function calcSavingsPercent(monthlyPrice: ProductPrice | undefined, annualPrice: ProductPrice | undefined): number | null;
+/** Most add-on blocks of each kind a checkout may include (the backend's limit). */
+export declare const MAX_CHECKOUT_BLOCKS = 100;
+/** "£25/month + VAT each", annual: "£225/year + VAT each": one block on the chosen interval. */
+export declare function checkoutBlockPriceText(price: ProductPrice | undefined, kind: 'ai_usage' | 'storage'): string | null;
+export {};

package/dist/connection/billing/quota-items.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Quota display — single source of truth.
+ *
+ * Builds the icon / label / formatted used-of-limit strings for a project's
+ * quotas (AI usage in £, storage, collaborators). Shared by QuotaBadges and the
+ * project tooltip so the numbers and units can never disagree (storage in GB on
+ * plans of 1 GB or more, MB below).
+ */
+import type { QuotaMeterItem } from '../../settings';
+import type { components } from '@arbidocs/client';
+type Quotas = components['schemas']['ProjectResponse']['quotas'];
+/** "May 31, 2025" — the one format every AI-usage-reset mention uses. */
+export declare function formatResetDate(unixTimestamp: number | null | undefined): string | null;
+/**
+ * When the project's AI usage allowance next resets, as a unix timestamp.
+ * Pro projects report it directly (`addons.ai_usage_reset_at` — monthly, even on an
+ * annual plan); monthly subscriptions otherwise reset with the billing period
+ * (`current_period_end`); free projects reset on the backend-stamped signup
+ * anniversary (`quotas.budget_reset_at`). Only a FUTURE date is returned — a stale
+ * past stamp would read as a bug, not a promise.
+ */
+export declare function aiUsageResetTimestamp(project: {
+    quotas?: {
+        budget_reset_at?: number | null;
+    } | null;
+    current_period_end?: number | null;
+    plan_interval?: string | null;
+    addons?: {
+        ai_usage_reset_at?: number | null;
+    } | null;
+}): number | null;
+export declare function getQuotaItems(quotas: Quotas): QuotaMeterItem[];
+export {};

package/dist/connection/billing/referral-reward.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Referral-reward logic (hook + pure helpers) shared across the pricing UI.
+ *
+ * The reward is a single GLOBAL per-user number — a Stripe account balance mirrored
+ * read-only into `settings.extra_discount`. It auto-applies to the user's NEXT invoice.
+ * `applyReferralReward` mirrors Stripe's customer-balance logic: applied to the charge,
+ * clamped at zero, remainder rolls forward. Components live in `./ReferralReward`.
+ */
+export { formatMoney } from './reward-balance';
+export interface ReferralReward {
+    amount: number;
+    currency: string;
+}
+/** The standing referral offer — what one successful invite earns. One constant
+ *  so the welcome modal and the rewards modal can never quote different money. */
+export declare const REFERRAL_OFFER: ReferralReward;
+/** The user's available referral reward, or null if none. */
+export declare function useReferralReward(): ReferralReward | null;
+/**
+ * Apply the reward to a charge, mirroring Stripe's customer-balance behaviour.
+ * Returns null when there's no usable reward or the currency doesn't match the price.
+ */
+export declare function applyReferralReward(totalCents: number, reward: ReferralReward | null, priceCurrency: string): {
+    bonus: number;
+    youPay: number;
+    remaining: number;
+    currency: string;
+} | null;

package/dist/connection/billing/refusal-copy.d.ts

@@ -0,0 +1,5 @@
+/**
+ * One template for every refusal where money is involved (declined card, failed or timed-out
+ * upgrade): "<What happened>. Nothing was charged. <Next step>."
+ */
+export declare function refusal(what: string, next: string): string;

package/dist/connection/billing/reward-balance.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Reward-balance logic (hook + money formatter).
+ *
+ * A user's reward balance is their available account balance — a single GLOBAL per-user
+ * number, the Stripe customer account balance mirrored read-only into
+ * `settings.extra_discount`. It auto-applies to the user's NEXT invoice.
+ *
+ * "Rewards" is the broad concept: the balance can be fed by several sources (referral
+ * reward is just one). The referral pricing surfaces of the billing kit
+ * speak to the referral source specifically; this module owns the balance itself.
+ */
+export interface RewardBalance {
+    amount: number;
+    currency: string;
+}
+/** The user's available reward balance (all sources), or null if none. */
+export declare function useRewardBalance(): RewardBalance | null;
+/** Format minor units as a localized money string, e.g. `£20` (whole) or `£29.99`. */
+export declare function formatMoney(cents: number, currency?: string): string;

package/dist/connection/billing/support.d.ts

@@ -0,0 +1,35 @@
+/**
+ * What a host adds to the billing kit. Selling plans needs Stripe, which stays the host's: whether
+ * this deployment sells plans (a publishable key is configured), and its embedded checkout. Without
+ * a `BillingSupportProvider` nothing is for sale: projects show their limits and usage only.
+ */
+import { type ReactNode } from 'react';
+export interface BillingCheckoutSupport {
+    /** Load the host's Stripe (lazily, when a checkout opens); `null` when it cannot. */
+    load(): Promise<unknown> | null;
+    /** Stripe's embedded checkout for a session, on the loaded Stripe. */
+    render(stripe: unknown, session: {
+        clientSecret: string;
+        onComplete: () => void;
+    }): ReactNode;
+}
+export interface BillingSupport {
+    /** This deployment sells plans (Stripe is configured). */
+    stripeEnabled: boolean;
+    checkout?: BillingCheckoutSupport;
+    /**
+     * Add-on blocks the user just bought here, so the host does not announce them later as having
+     * arrived on their own.
+     */
+    onAddonBlocksBought?: (projectExtId: string, blocks: {
+        ai: number;
+        storage: number;
+    }) => void;
+}
+export declare function BillingSupportProvider({ value, children, }: {
+    value: BillingSupport;
+    children: ReactNode;
+}): import("react").JSX.Element;
+export declare function useBillingSupport(): BillingSupport;
+/** The signed-in user's id (`usr-…`), to tell the projects they own from the others. */
+export declare function useSelfExtId(): string | undefined;

package/dist/connection/billing/tax-quote.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Tax-inclusive totals from the backend's Stripe Tax quotes (`TaxQuoteResponse`, plan-change
+ * previews, add-on quotes): "£48.00 incl. VAT (£40.00 + £8.00 VAT 20%)", "£40.00 · no VAT
+ * (reverse charge)", "£40.00 · no tax".
+ */
+import type { components } from '@arbidocs/client';
+export type TaxQuote = components['schemas']['TaxQuoteResponse'];
+/** Countries whose tax depends on the postcode: the field is shown up front. */
+export declare const POSTCODE_COUNTRIES: readonly string[];
+/** The quote error that asks for a ZIP / postal code. */
+export declare const TAX_LOCATION_INVALID = "TAX_LOCATION_INVALID";
+/** "£42.00" — always pence, so the parts of a total add up on screen. */
+export declare function money2(pence: number, currency?: string): string;
+export interface TaxParts {
+    subtotal: number;
+    tax: number;
+    total: number;
+    /** "VAT 20%"; null when no tax is due. */
+    label?: string | null;
+    reverseCharge?: boolean;
+}
+/** What follows the total: "incl. VAT (£40.00 + £8.00 VAT 20%)", "· no VAT (reverse charge)", "· no tax". */
+export declare function taxDetail({ subtotal, tax, label, reverseCharge }: TaxParts): string;
+/** "£48.00 incl. VAT (£40.00 + £8.00 VAT 20%)", "£40.00 · no VAT (reverse charge)", "£40.00 · no tax". */
+export declare function taxSummary(parts: TaxParts): string;
+/** "£21.00 incl. VAT" / "£17.50" — a total with only the word for its tax. */
+export declare function totalWithTaxWord({ total, tax, label }: TaxParts): string;
+/** The parts of a quote response. */
+export declare function quoteParts(quote: TaxQuote): TaxParts;
+/** "Total today £48.00 incl. VAT (£40.00 + £8.00 VAT 20%)". */
+export declare function quoteTotalLine(quote: TaxQuote): string;
+/** The API error code (`detail.code`) and message, if any. */
+export declare function quoteError(error: unknown): {
+    code?: string;
+    message?: string;
+};