@hachej/boring-core 0.1.42 → 0.1.44

package/dist/server/index.d.ts

@@ -1,15 +1,17 @@
-import { L as LoadConfigOptions } from '../authHook-DUqyxueY.js';
-export { A as AuthHookOptions, B as BetterAuthInstance, C as CreateAuthOptions, a as authHook, b as buildRuntimeConfigPayload, c as createAuth, l as loadConfig, v as validateConfig, d as validatePasswordStrength } from '../authHook-DUqyxueY.js';
+import { L as LoadConfigOptions } from '../authHook-CzBsMwwM.js';
+export { A as AuthHookOptions, B as BetterAuthInstance, C as CreateAuthOptions, a as authHook, b as buildRuntimeConfigPayload, c as createAuth, l as loadConfig, v as validateConfig, d as validatePasswordStrength } from '../authHook-CzBsMwwM.js';
 import { z } from 'zod';
-import { C as CoreConfig, M as MemberRole, d as WorkspaceRuntimeResourceSelector, e as WorkspaceRuntimeResource, f as WorkspaceRuntimeResourceInput } from '../types-CbMOXLBf.js';
+import { C as CoreConfig, M as MemberRole, d as WorkspaceRuntimeResourceSelector, e as WorkspaceRuntimeResource, f as WorkspaceRuntimeResourceInput } from '../types-CWtJ4kgd.js';
 import * as fastify from 'fastify';
 import { FastifyInstance, FastifyPluginAsync, preHandlerHookHandler, FastifyRequest, FastifyReply } from 'fastify';
 import * as http from 'http';
 import { IncomingMessage } from 'node:http';
-import { C as CreateCoreAppOptions, D as Database, U as UserStore, W as WorkspaceStore, a as WorkspaceProvisioner } from '../connection-AL8KSENV.js';
-export { A as AuthProvider, b as CapabilitiesContributor, P as ProvisionContext, d as ProvisionResult, c as createDatabase } from '../connection-AL8KSENV.js';
+import { C as CreateCoreAppOptions, D as Database, U as UserStore, W as WorkspaceStore, a as WorkspaceProvisioner } from '../connection-C5SiqoNc.js';
+export { A as AuthProvider, b as CapabilitiesContributor, P as ProvisionContext, d as ProvisionResult, c as createDatabase } from '../connection-C5SiqoNc.js';
 import postgres from 'postgres';
-export { r as runMigrations } from '../migrate-B4dwdtGP.js';
+import { P as PostgresMeteringStore, C as CreditLedgerEntry } from '../PostgresMeteringStore-CzNv6xil.js';
+export { F as FinishReservationInput, G as GrantOnceInput, I as InsufficientCreditError, M as MeteringBalance, R as RecordUsageInput, a as RecordUsageResult, b as ReservationFinalStatus, c as ReserveInput, d as ReserveResult, r as runMigrations } from '../PostgresMeteringStore-CzNv6xil.js';
+import { AgentMeteringSink } from '@hachej/boring-agent/server';
 import 'better-auth';
 import 'drizzle-orm/postgres-js';
 
@@ -419,4 +421,589 @@ declare class WorkspaceRuntimeSandboxHandleStore {
     list(): Promise<WorkspaceSandboxHandleRecord[]>;
 }
 
-export { CreateCoreAppOptions, Database, type FsProvisionerOptions, type IdempotencyEntry, type IdempotencyKeyStore, LoadConfigOptions, MailDeliveryError, type MailTransport, type PostSignupHookDeps, type RenderedEmail, type RoutesOptions, type RunCoreMigrationsFromEnvOptions, UserStore, WorkspaceProvisioner, WorkspaceRuntimeSandboxHandleStore, type WorkspaceRuntimeStoreLike, type WorkspaceSandboxHandleRecord, WorkspaceStore, coreConfigSchema, createCoreApp, createDrizzleIdempotencyStore, createFsProvisioner, createIdempotencyMiddleware, createMailTransport, createPostSignupHook, registerInviteRoutes, registerMemberRoutes, registerRoutes, registerSettingsRoutes, registerWorkspaceRoutes, renderMagicLink, renderResetPassword, renderVerifyEmail, renderWelcome, renderWorkspaceInvite, requireWorkspaceMember, runCoreMigrationsFromEnv, safeRedirect };
+/**
+ * Token → credit pricing.
+ *
+ * Direct EU providers like Infomaniak return token usage but not a per-call
+ * cost, so we price from published per-token rates and apply a margin. The
+ * result is the credit amount to charge against the balance (in credit micros).
+ *
+ * Currency-neutral: rates are expressed in a "pricing currency unit" (e.g. EUR)
+ * per million tokens; `creditMicrosPerUnit` converts that to credit micros.
+ * With 1 credit = €0.000001, `creditMicrosPerUnit = 1_000_000`.
+ */
+interface ModelTokenRate {
+    /** Pricing-currency units per 1M input tokens (cache tokens billed as input). */
+    inputPerMillion: number;
+    /** Pricing-currency units per 1M output tokens. */
+    outputPerMillion: number;
+}
+interface CreditPricingConfig {
+    /** Multiplier applied on top of raw provider cost (your margin). 1.0 = at cost. */
+    margin: number;
+    /** Credit micros per 1 pricing-currency unit. 1 credit = €0.000001 ⇒ 1_000_000. */
+    creditMicrosPerUnit: number;
+    /** Ordered [pattern, rate] table; checked BEFORE the built-in
+     * DEFAULT_MODEL_RATES (configured rate wins for a model it matches), but the
+     * defaults still apply to models you didn't list — so a selectable expensive
+     * model (e.g. Claude Opus) is never silently dropped to the cheap fallback. */
+    rates?: Array<[RegExp, ModelTokenRate]>;
+    /**
+     * Rate applied when no pattern matches and the provider reported no cost.
+     * Defaults to CONSERVATIVE_DEFAULT_RATE so an unpriced model is never billed
+     * zero (free usage) in this prepaid path — set it explicitly to tune.
+     */
+    defaultRate?: ModelTokenRate;
+    /**
+     * Trust a provider-reported cost over token pricing. Default false: for a
+     * prepaid credit balance, a provider cost in the wrong currency / stale test
+     * value / tiny non-zero number would undercharge, so we price from our own
+     * verified token rates with margin and ignore the reported cost.
+     */
+    preferProviderReportedCost?: boolean;
+}
+/** Conservative fallback rate (≈ Claude Sonnet list price). EU open models are
+ * cheaper, so this over-charges an un-configured model rather than billing zero. */
+declare const CONSERVATIVE_DEFAULT_RATE: ModelTokenRate;
+declare const DEFAULT_MODEL_RATES: Array<[RegExp, ModelTokenRate]>;
+interface CreditUsageInput {
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadTokens?: number;
+    cacheWriteTokens?: number;
+    /** Provider-reported cost in pricing-currency units, if any (0 when absent). */
+    providerReportedCost?: number;
+}
+interface CreditCost {
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadTokens: number;
+    cacheWriteTokens: number;
+    /** Raw provider cost (reported or estimated) in credit micros, before margin. */
+    providerCostMicros: number;
+    /** Amount to charge against the balance, in credit micros (with margin). */
+    billedCreditMicros: number;
+    /** True when no model rate matched and the conservative defaultRate was used —
+     * a signal to the operator to add an explicit rate for this model. */
+    pricedFromDefault: boolean;
+}
+/**
+ * The highest input/output rate this pricing config can actually charge: the max
+ * over the EFFECTIVE rate table (configured rates if set, else
+ * DEFAULT_MODEL_RATES) AND the conservative default fallback. Size a per-run
+ * reservation hold from this — never a hardcoded floor — or an expensive model
+ * in the table (e.g. Claude Opus at 15/75) can bill above a hold sized for a
+ * cheaper rate, defeating the hard stop.
+ */
+declare function maxEffectiveRate(config: CreditPricingConfig): ModelTokenRate;
+/**
+ * The priciest rate over only the SERVED models (configured rates + the
+ * conservative default), EXCLUDING the built-in DEFAULT_MODEL_RATES. Use this to
+ * size the per-run hold: the hold should reflect the models this deployment
+ * actually serves (so a small starter grant stays usable), while billing an
+ * unmatched model still fails closed at maxEffectiveRate. An unreachable
+ * expensive model would overshoot the hold — bounded; the next run is refused.
+ */
+declare function maxServedRate(config: CreditPricingConfig): ModelTokenRate;
+/** Estimate raw provider cost (pricing-currency units) from token counts. Cache
+ * tokens are billed at the input rate — a deliberate conservative over-count.
+ * Unmatched models fall back to `config.defaultRate` (never zero). */
+declare function estimateProviderCost(modelId: string, inputTokens: number, outputTokens: number, config: CreditPricingConfig): {
+    units: number;
+    usedDefault: boolean;
+};
+/**
+ * Price one usage record into the credit amount to charge. Prefers a
+ * provider-reported cost; otherwise estimates from token rates. Applies the
+ * margin and converts to credit micros (rounded up so we never undercharge).
+ */
+declare function usageToCredits(usage: CreditUsageInput, model: {
+    provider?: string;
+    id?: string;
+}, config: CreditPricingConfig): CreditCost;
+
+declare const SIGNUP_GRANT_REASON = "signup_grant";
+type CreditsLogger = (message: string, fields?: Record<string, unknown>) => void;
+interface CreditsConfig {
+    enabled: boolean;
+    /** Free starter grant on signup, in credit micros (1 credit = €0.000001). */
+    signupGrantMicros: number;
+    /** Days until the signup grant expires; null = never. */
+    signupGrantExpiresAfterDays: number | null;
+    /**
+     * Per-run hold, in credit micros. This is the per-run overdraft bound: a run
+     * is admitted against this hold, but the actual charge is posted afterward, so
+     * a single run can overshoot the hold by (actualCost − hold). Set this to
+     * cover your worst-case single run (max tokens on the priciest enabled model)
+     * so the hard stop is effectively exact.
+     */
+    runReservationMicros: number;
+    reservationTtlSeconds: number;
+    /** Floor below which a run is refused. */
+    minBalanceMicros: number;
+    pricing: CreditPricingConfig;
+}
+declare const DEFAULT_CREDITS_CONFIG: CreditsConfig;
+interface CreditBalance {
+    enabled: boolean;
+    userId: string;
+    grantedMicros: number;
+    usedMicros: number;
+    remainingMicros: number;
+    activeReservedMicros: number;
+    /** remaining minus active holds; never negative in the response. */
+    availableMicros: number;
+    /** Owed amount when the ledger went negative (e.g. after a refund of spent
+     * credits); 0 otherwise. Surfaced for audit/support so debt isn't hidden. */
+    debtMicros: number;
+    currency: 'credits';
+}
+interface CreditUsageRecord {
+    usageId: string;
+    userId: string;
+    workspaceId?: string;
+    sessionId?: string;
+    runId?: string;
+    messageId?: string;
+    reservationId?: string;
+    provider?: string;
+    model?: string;
+    usage: {
+        input: number;
+        output: number;
+        cacheRead: number;
+        cacheWrite: number;
+        cost: {
+            total: number;
+        };
+    };
+    stopReason?: string;
+}
+declare class CreditExhaustedError extends Error {
+    readonly statusCode = 402;
+    readonly code = "PAYMENT_REQUIRED";
+    readonly details: {
+        balance: CreditBalance;
+    };
+    constructor(balance: CreditBalance);
+}
+/** The subset of PostgresMeteringStore the credits policy uses; Pick keeps
+ * upstream signature changes compile-time errors and lets tests stub it. */
+type CreditsMeteringStore = Pick<PostgresMeteringStore, 'grantOnce' | 'grantPurchaseOnce' | 'revokePurchase' | 'getBalance' | 'reserve' | 'recordUsage' | 'finishReservation' | 'expireStaleReservations' | 'billedMicrosForRun' | 'billedMicrosForReservation' | 'markReservationFallbackCharge' | 'listLedger'>;
+/**
+ * Product credit policy over the generic metering store: free signup grant,
+ * purchase grants, per-run reservation hard stop, token→credit pricing, and the
+ * balance shape the UI consumes. Currency-neutral (amounts are credit micros).
+ */
+declare class CreditsService {
+    private readonly store;
+    readonly config: CreditsConfig;
+    private readonly log?;
+    /** Users whose signup grant was ensured this process; avoids an INSERT per balance poll. */
+    private readonly signupGrantedUsers;
+    constructor(store: CreditsMeteringStore, config?: CreditsConfig, log?: CreditsLogger | undefined);
+    /** Idempotently grant the free starter credits (call from the post-signup hook
+     * and lazily on first balance/reserve). The grant NEVER expires: an expiring
+     * grant would drop from grantedMicros on expiry while spent usage stayed, turning
+     * a partly-spent trial into debt. (Proper expiry must cap/allocate usage against
+     * the promo balance — a tracked follow-up; the expiry config is rejected up front.) */
+    grantSignupCredits(userId: string): Promise<void>;
+    /** Credit a completed purchase. Globally idempotent per order id (safe on
+     * webhook retry, and the same order can never be credited to two users). The
+     * optional provider identity is persisted for audit/refund reconciliation. */
+    grantPurchase(userId: string, orderId: string, amountMicros: number, identity?: {
+        storeId?: string;
+        testMode?: boolean;
+        currency?: string;
+        variantId?: string;
+    }): Promise<{
+        created: boolean;
+    }>;
+    /** Revoke a refunded/disputed purchase. `refundFraction` is the cumulative
+     * fraction of the order refunded (LS refunded_amount / total) for partial
+     * refunds; omit for a full refund. `allowTombstone` permits writing a pre-grant
+     * refund tombstone for an order not yet credited (set only when the refund
+     * validates as a credit order); an already-credited order is always revocable.
+     * Idempotent per cumulative level. */
+    revokePurchase(orderId: string, opts?: {
+        refundFraction?: number;
+        allowTombstone?: boolean;
+        expectedStoreId?: string;
+        expectedTestMode?: boolean;
+        expectedCurrency?: string;
+    }): Promise<{
+        revoked: boolean;
+    }>;
+    getBalance(userId: string): Promise<CreditBalance>;
+    /** Recent credit ledger (grants/purchases + usage/refund debits) for the account
+     * activity view, newest first, capped (clamped 1..50 in the store). Empty when
+     * credits are disabled. */
+    listLedger(userId: string, limit?: number): Promise<CreditLedgerEntry[]>;
+    /** Reserve a per-run hold. Returns the reservation id; throws
+     * CreditExhaustedError (402) below the floor. */
+    reserveRun(input: {
+        userId: string;
+        workspaceId?: string;
+        sessionId?: string;
+        runId: string;
+    }): Promise<string | undefined>;
+    /** Charge native usage, priced token→credits with margin. Returns the billed
+     * credit micros (0 when disabled or the usage priced to nothing) so the caller can
+     * decide billability from the ACTUAL charge, not raw provider fields — e.g. a
+     * cost-only row prices to 0 unless preferProviderReportedCost is set. */
+    recordUsage(input: CreditUsageRecord): Promise<{
+        billedMicros: number;
+    }>;
+    settleRun(userId: string, runId: string, reservationId?: string): Promise<void>;
+    releaseRun(userId: string, runId: string, reservationId?: string): Promise<void>;
+    /**
+     * Fail-closed billing for a completed run whose usage write failed: a run that
+     * already executed must never go free. Charge the per-run hold (worst-case)
+     * as a conservative, idempotent debit, then settle the reservation. Tagged
+     * source 'pi-chat-fallback' so it's reconcilable against the missing real
+     * usage row. Over-charges rather than risk free usage.
+     */
+    chargeFallbackUsage(input: {
+        userId: string;
+        runId: string;
+        reservationId?: string;
+        kind?: 'usage_write_failed' | 'no_billable_usage';
+    }): Promise<void>;
+}
+
+/**
+ * Adapt the credit policy to boring-agent's AgentMeteringSink. The service is
+ * resolved lazily because the sink is handed to createCoreWorkspaceAgentServer
+ * before the server (and its db) exists.
+ *
+ * reserveRun fails closed: 402 when credits are exhausted (CreditExhaustedError),
+ * 401 when an authenticated run has no user. recordUsage/settle/release are
+ * best-effort and skip silently for userless runs.
+ */
+declare function createCreditsMeteringSink(getService: () => CreditsService): AgentMeteringSink;
+
+/**
+ * Lemon Squeezy (Merchant of Record) credit purchases.
+ *
+ * Product-neutral: this module verifies the webhook, parses the order, and
+ * grants credits via a host-supplied grant function. The host owns how many
+ * credits an order is worth (pricing/bonus policy) and which user it belongs
+ * to. Grants are idempotent per order id, so webhook retries never double-credit.
+ *
+ * Lemon Squeezy signs webhooks with HMAC-SHA256 of the raw request body using
+ * the store's signing secret, in the `X-Signature` header.
+ */
+/** Verify the `X-Signature` HMAC against the raw request body. Timing-safe. */
+declare function verifyLemonSqueezySignature(rawBody: string | Buffer, signatureHeader: string | undefined, secret: string): boolean;
+/** Server-signed attribution token binding a user id to a server-created
+ * checkout. Set as `custom_data.uat`; verified on the webhook so a buyer-crafted
+ * hosted-checkout URL can't attribute a paid order to an arbitrary account. */
+declare function signUserAttribution(userId: string, secret: string): string;
+/** Verify the token against the signing secret, or ANY of several secrets (current
+ * + previous) to allow secret rotation without breaking in-flight checkout links. */
+declare function verifyUserAttribution(userId: string | undefined, token: string | undefined, secret: string | readonly string[]): boolean;
+interface LemonSqueezyOrder {
+    eventName: string;
+    orderId: string;
+    /** From checkout `custom_data.user_id` — who to credit. */
+    userId?: string;
+    /** From checkout `custom_data.uat` — server-signed HMAC binding the user_id to
+     * a server-created checkout (a crafted hosted-checkout URL can't forge it). */
+    userAttributionToken?: string;
+    userEmail?: string;
+    status?: string;
+    /** Test/live mode. `undefined` when the payload omitted it — treated as a
+     * MISMATCH by isCreditOrder (never silently assumed live). */
+    testMode?: boolean;
+    /** Lemon Squeezy store the order belongs to. */
+    storeId?: string;
+    currency?: string;
+    /** Pre-tax order amount in cents. `undefined` if the field was ABSENT (vs a real 0)
+     * so the underpayment check can fail closed on a missing required money field. */
+    subtotalCents: number | undefined;
+    /** Discount applied, pre-tax, in cents. Net paid pre-tax = subtotal − discount.
+     * `undefined` if absent (presence-preserving — a missing discount must not look
+     * like a real 0, which could over-credit a discounted order). */
+    discountTotalCents: number | undefined;
+    /** Tax-inclusive total in cents (MoR adds VAT here). `undefined` if absent. */
+    totalCents: number | undefined;
+    /** Tax amount in cents (0 when no tax). Net paid pre-tax also = total − tax, an
+     * independent cross-check against subtotal − discount. */
+    taxCents: number;
+    /** Whether the order has been (fully or partially) refunded. */
+    refunded: boolean;
+    /** Cumulative amount refunded so far, tax-inclusive, in cents. */
+    refundedAmountCents: number;
+    variantId?: string;
+    /** Units of the pack purchased (default 1). Credits scale with it. */
+    quantity: number;
+    productName?: string;
+}
+/**
+ * Parse a Lemon Squeezy webhook payload into a normalized order. Returns null
+ * for non-order or malformed payloads.
+ */
+declare function parseLemonSqueezyOrder(payload: unknown): LemonSqueezyOrder | null;
+interface LemonSqueezyWebhookOptions {
+    secret: string;
+    /** Credit amount (micros of your credit unit) to grant for this order. */
+    creditsForOrder: (order: LemonSqueezyOrder) => number;
+    /**
+     * Resolve the user to credit. Defaults to `order.userId` (custom_data).
+     * SECURITY: only trust custom_data.user_id when checkouts are created
+     * SERVER-side (see createLemonSqueezyCheckout) so the id is set by your
+     * server, not a client-editable hosted-checkout URL. Because the server sets
+     * a deterministic user per order, `purchase:<orderId>` is then effectively a
+     * per-order idempotency key (the same order never maps to two users).
+     */
+    resolveUserId?: (order: LemonSqueezyOrder) => string | undefined;
+    /** Optional: returns whether the resolved user still exists. When provided, a credit
+     * order for a non-existent (deleted) user is 200-acked WITHOUT granting, so a stale
+     * webhook can't resurrect a deleted user's purchase/grant rows (PII). */
+    userExists?: (userId: string) => Promise<boolean>;
+    /** When set, the order's `custom_data.uat` MUST be a valid attribution token
+     * for its user_id (signUserAttribution) or the order is not credited — binds
+     * attribution to a server-created checkout, not a buyer-supplied user_id. May be
+     * an array (current + previous secrets) to allow rotation: a token signed with any
+     * listed secret verifies, so in-flight checkout links survive a secret rotation. */
+    attributionSecret?: string | readonly string[];
+    /** Grant credits idempotently. `reason` is `purchase:<orderId>` (the
+     * idempotency key); `orderId` is provided so callers don't re-parse it. The
+     * full `order` is passed so the grant can persist provider identity. */
+    grant: (input: {
+        userId: string;
+        orderId: string;
+        reason: string;
+        amountMicros: number;
+    }, order: LemonSqueezyOrder) => Promise<{
+        created: boolean;
+    }>;
+    /** Which events to credit on. Defaults to `order_created`. */
+    creditableEvents?: string[];
+    /**
+     * Confirm this paid order is actually a credit-pack purchase before granting
+     * (currency, mode, and that the variant is a configured pack). REQUIRED:
+     * without it, ANY signed paid order on the store would mint credits. Returning
+     * false acks the webhook without crediting.
+     */
+    isCreditOrder: (order: LemonSqueezyOrder) => boolean;
+    /** Optional STRICT check: is this order on OUR store/mode/currency (ignoring the
+     * variant, all fields required)? Provide it ONLY for a credit-only store: then a
+     * paid order that's ours but NOT a credit order (unknown/misconfigured variant)
+     * returns a retryable 500 instead of a 200 ack — so a paid customer isn't left
+     * without credits. Omit it for a MIXED store (credits + other products), so a
+     * legitimate non-credit order is 200-ignored rather than retried/alerted forever. */
+    isOurStoreOrder?: (order: LemonSqueezyOrder) => boolean;
+    /** Optional LENIENT check for REFUNDS: a refund payload may omit store/mode/
+     * currency, so a missing field passes and only a present-and-mismatched field
+     * rejects. A refund failing this is ignored (can't revoke a credited order by
+     * order id alone). Defaults to always-true when omitted. */
+    isRefundForOurStore?: (order: LemonSqueezyOrder) => boolean;
+    /** Optional check: is this a paid order for a KNOWN credit-pack variant whose
+     * store/mode/currency identity is INCOMPLETE (a required field is missing rather
+     * than present-and-mismatched)? When true, the webhook returns a retryable 500
+     * instead of a silent 200 `not_a_credit_order` — a recognized paid pack we can't
+     * safely attribute must fail loud (parser gap / LS payload change), not drop the
+     * customer's credits. A genuinely foreign order (present field contradicts our
+     * config) is NOT this case and is still 200-ignored. */
+    isUnverifiedCreditOrder?: (order: LemonSqueezyOrder) => boolean;
+    /** Credit micros per 1 currency unit (e.g. 1_000_000 = €0.000001/credit). When
+     * set, the webhook refuses to mint a fixed pack value unless the net paid
+     * amount (subtotal − discount) covers it — so a dashboard/manual discount or LS
+     * bug can't grant full credits for an underpaid order. */
+    creditMicrosPerUnit?: number;
+    /** Events that revoke a previously-credited purchase. Default `order_refunded`. */
+    refundEvents?: string[];
+    /** Revoke a refunded/disputed order's credits (idempotent per order). REQUIRED
+     * so a refund is never silently dropped (which would leave a refunded order
+     * credited). */
+    onRefund: (order: LemonSqueezyOrder) => Promise<{
+        revoked: boolean;
+    }>;
+    log?: (message: string, fields?: Record<string, unknown>) => void;
+}
+interface LemonSqueezyWebhookResult {
+    status: number;
+    body: {
+        ok: boolean;
+        reason?: string;
+        orderId?: string;
+        created?: boolean;
+    };
+}
+/**
+ * Full webhook handler: verify signature → parse → grant. Framework-agnostic
+ * (takes the raw body + header) so the host wires it to any router with raw-body
+ * access. Returns the HTTP status + JSON body to send.
+ */
+declare function handleLemonSqueezyWebhook(rawBody: string | Buffer, signatureHeader: string | undefined, options: LemonSqueezyWebhookOptions): Promise<LemonSqueezyWebhookResult>;
+
+/**
+ * Server-side Lemon Squeezy checkout creation.
+ *
+ * The buyer's user id is set HERE (from the authenticated session), not by the
+ * browser. The purchase webhook then trusts `custom_data.user_id` because the
+ * server — not a client-editable URL — put it there. This is the money-safe
+ * alternative to client-built hosted-checkout links.
+ */
+interface CreateCheckoutInput {
+    apiKey: string;
+    storeId: string;
+    variantId: string;
+    /** Authenticated user id — written into checkout custom data server-side. */
+    userId: string;
+    /** Secret used to sign the user attribution token (custom_data.uat) so the
+     * webhook can verify the user_id came from this server-created checkout. */
+    attributionSecret?: string;
+    email?: string;
+    /** Where Lemon Squeezy redirects after a successful purchase. */
+    redirectUrl?: string;
+    /** Use test-mode checkout (mirrors the API key's mode). */
+    testMode?: boolean;
+}
+type FetchLike = (url: string, init: {
+    method: string;
+    headers: Record<string, string>;
+    body: string;
+}) => Promise<{
+    ok: boolean;
+    status: number;
+    json: () => Promise<unknown>;
+    text: () => Promise<string>;
+}>;
+/** Build the JSON:API request body for a checkout. Exported for testing. */
+declare function buildCheckoutRequestBody(input: CreateCheckoutInput): Record<string, unknown>;
+/** Create a hosted checkout and return its URL. Throws on API failure. */
+declare function createLemonSqueezyCheckout(input: CreateCheckoutInput, fetchImpl?: FetchLike): Promise<{
+    url: string;
+}>;
+
+interface LemonSqueezyCheckoutConfig {
+    apiKey: string;
+    storeId: string;
+    /** Pack variants keyed by a short pack id the client requests (e.g. "10","25"). */
+    variants: Record<string, string>;
+    /** Pack id used when the request names none. */
+    defaultPack: string;
+    redirectUrl?: string;
+    testMode?: boolean;
+}
+interface LemonSqueezyRouteOptions {
+    webhookSecret: string;
+    /**
+     * Secret used to sign/verify the checkout attribution token (`custom_data.uat`).
+     * Defaults to `webhookSecret`, but SHOULD be a dedicated, stable secret so rotating
+     * the LS webhook secret doesn't invalidate in-flight checkout links. Provide an
+     * array (current first, then previous secrets) to allow rotation: checkouts sign
+     * with the first; the webhook verifies against ANY, so in-flight links survive.
+     */
+    attributionSecret?: string | readonly string[];
+    /** Optional: resolve whether a credited user still exists. When provided, a credit
+     * order for a deleted user is 200-acked without granting (no PII resurrection via a
+     * stale webhook). */
+    userExists?: (userId: string) => Promise<boolean>;
+    /**
+     * Variant ids that are credit packs. REQUIRED and non-empty for the webhook
+     * to credit anything — only orders for these variants mint credits, so
+     * unrelated products on the same store are ignored (fail closed).
+     */
+    creditVariantIds: string[];
+    /** Expected mode of credit orders: true = test, false = live. An order whose
+     * test_mode differs is ignored (prevents test↔live cross-crediting). */
+    expectedTestMode: boolean;
+    /** Expected Lemon Squeezy store id. When set, an order from another store is
+     * ignored (defense in depth on top of the per-store webhook secret). */
+    expectedStoreId?: string;
+    /**
+     * Whether this store sells ONLY credit packs. **Defaults to true (fail-closed).**
+     * When true (a credit-only store), a paid order in our store/mode/currency whose
+     * variant isn't a configured credit pack is treated as a pack MISCONFIGURATION and
+     * returns a retryable 500 (the customer paid and would otherwise get nothing — a
+     * visible, recoverable failure rather than a silent drop). Set **false** for a MIXED
+     * store selling credits plus other products: such an order is then a different product
+     * and is 200-ignored, so its webhook isn't retried/alerted forever. A known credit
+     * variant with incomplete identity always 500s regardless (see isUnverifiedCreditOrder).
+     */
+    creditOnlyStore?: boolean;
+    /** Currency a paid order must be in to be credited (default 'EUR'). A missing
+     * or mismatched currency is rejected. */
+    requireCurrency?: string;
+    /**
+     * Fixed credit micros to grant per credit-pack variant id. REQUIRED, and the
+     * ONLY crediting basis — never order-amount math: the grant is the pack's
+     * configured value, so a multi-item order, a discount, or a tax change can't
+     * change how many credits are minted. Every entry in `creditVariantIds` must
+     * have a positive value here (enforced at registration). A non-pack host that
+     * needs a different policy must add an explicit, separately-tested route — the
+     * money webhook keeps exactly one safe path.
+     */
+    creditMicrosByVariant: Record<string, number>;
+    webhookPath?: string;
+    /** Server-side checkout creation. Required for money-safe buyer attribution
+     * (the user id is set server-side, not by the browser). */
+    checkout?: LemonSqueezyCheckoutConfig;
+    checkoutPath?: string;
+}
+interface StripeCheckoutConfig {
+    /** Stripe secret key (sk_… or rk_…). */
+    apiKey: string;
+    /** Fixed packs keyed by a short pack id the client requests (e.g. "10","25") → Stripe Price id. */
+    variants: Record<string, string>;
+    /** Pack id used when the request names none. */
+    defaultPack: string;
+    /** Stripe Price id of the custom (pay-what-you-want) pack, for creating its checkout.
+     * The custom pack's webhook policy (id, minimum) lives on StripeRouteOptions.customPack. */
+    customPriceId?: string;
+    redirectUrl?: string;
+}
+interface StripeRouteOptions {
+    /** Webhook endpoint signing secret (whsec_…). When omitted, the webhook route is NOT
+     * registered (checkout can still open, but purchases won't auto-credit). */
+    webhookSecret?: string;
+    /** Secret(s) to sign/verify the attribution token (metadata.uat). Defaults to the
+     * webhook secret. Provide [current, ...previous] so rotating the webhook secret doesn't
+     * reject in-flight checkouts: sessions sign with the first; the webhook verifies any. */
+    attributionSecret?: string | readonly string[];
+    /** true = test mode. The webhook only credits sessions whose livemode matches. */
+    expectedTestMode: boolean;
+    /** Currency a paid session must be in to be credited (default 'EUR'). */
+    requireCurrency?: string;
+    /** Whether the account sells only credit packs (default true → an unknown-pack PAID
+     * session is a misconfig that fails loud rather than a silent drop). */
+    creditOnlyStore?: boolean;
+    /** Resolve whether a credited user still exists (no PII resurrection on a stale webhook). */
+    userExists?: (userId: string) => Promise<boolean>;
+    /** Fixed pack id → credit micros (the authoritative value the webhook grants). The
+     * custom pack is credited from the amount paid, not this map. */
+    creditMicrosByPack: Record<string, number>;
+    /** Pay-what-you-want pack WEBHOOK policy — its reserved id and minimum (minor units).
+     * Top-level (not under checkout) so a paid custom session is still recognized/credited
+     * even if checkout creation is temporarily unconfigured. The price id for CREATING the
+     * checkout lives at checkout.customPriceId. */
+    customPack?: {
+        id: string;
+        minMinor: number;
+    };
+    checkout?: StripeCheckoutConfig;
+    checkoutPath?: string;
+    webhookPath?: string;
+}
+interface CreditsRoutesOptions {
+    service: CreditsService;
+    /** Resolve the authenticated user id. Default: `request.user?.id`. */
+    getUserId?: (request: FastifyRequest) => string | undefined;
+    balancePath?: string;
+    historyPath?: string;
+    /** Configure at most ONE purchase provider. */
+    lemonSqueezy?: LemonSqueezyRouteOptions;
+    stripe?: StripeRouteOptions;
+    log?: (message: string, fields?: Record<string, unknown>) => void;
+}
+/**
+ * Register the credit balance endpoint and (optionally) the Lemon Squeezy
+ * purchase webhook. The webhook route reads the RAW request body so the HMAC
+ * signature can be verified before parsing.
+ */
+declare function registerCreditsRoutes(app: FastifyInstance, options: CreditsRoutesOptions): void;
+
+export { CONSERVATIVE_DEFAULT_RATE, type CreateCheckoutInput, CreateCoreAppOptions, type CreditBalance, type CreditCost, CreditExhaustedError, type CreditPricingConfig, type CreditUsageInput, type CreditUsageRecord, type CreditsConfig, type CreditsMeteringStore, type CreditsRoutesOptions, CreditsService, DEFAULT_CREDITS_CONFIG, DEFAULT_MODEL_RATES, Database, type FsProvisionerOptions, type IdempotencyEntry, type IdempotencyKeyStore, type LemonSqueezyCheckoutConfig, type LemonSqueezyOrder, type LemonSqueezyRouteOptions, type LemonSqueezyWebhookOptions, type LemonSqueezyWebhookResult, LoadConfigOptions, MailDeliveryError, type MailTransport, type ModelTokenRate, type PostSignupHookDeps, PostgresMeteringStore, type RenderedEmail, type RoutesOptions, type RunCoreMigrationsFromEnvOptions, SIGNUP_GRANT_REASON, UserStore, WorkspaceProvisioner, WorkspaceRuntimeSandboxHandleStore, type WorkspaceRuntimeStoreLike, type WorkspaceSandboxHandleRecord, WorkspaceStore, buildCheckoutRequestBody, coreConfigSchema, createCoreApp, createCreditsMeteringSink, createDrizzleIdempotencyStore, createFsProvisioner, createIdempotencyMiddleware, createLemonSqueezyCheckout, createMailTransport, createPostSignupHook, estimateProviderCost, handleLemonSqueezyWebhook, maxEffectiveRate, maxServedRate, parseLemonSqueezyOrder, registerCreditsRoutes, registerInviteRoutes, registerMemberRoutes, registerRoutes, registerSettingsRoutes, registerWorkspaceRoutes, renderMagicLink, renderResetPassword, renderVerifyEmail, renderWelcome, renderWorkspaceInvite, requireWorkspaceMember, runCoreMigrationsFromEnv, safeRedirect, signUserAttribution, usageToCredits, verifyLemonSqueezySignature, verifyUserAttribution };