/**
 * `billing` namespace — organizations and Stripe checkouts.
 *
 * Organizations are addressed by their canonical `org_id` (UUID). A
 * wallet or email is resolved to that id through the
 * `GET /orgs/v1/lookup?wallet=|?email=` lookup; `getOrganization` / `history`
 * accept any of the three identifier forms and resolve internally. Organization
 * reads require SIWX from a wallet linked to the organization (or matching the
 * looked-up `?wallet`), or an admin key; email lookups are admin-only.
 * Mutations such as link-wallet, checkout creation, and auto-recharge require
 * an org credential (or admin).
 */
import type { Client } from "../kernel.js";
import type { ProjectTier } from "./projects.types.js";
export interface OrganizationDetail {
    /** Canonical organization id (UUID). */
    org_id: string;
    available_usd_micros: number;
    /** Held/reserved portion of the balance; absent on gateways that predate the field. */
    held_usd_micros?: number;
    email_credits_remaining: number;
    tier: ProjectTier | null;
    lease_expires_at: string | null;
    auto_recharge_enabled: boolean;
    auto_recharge_threshold: number;
}
export interface BillingHistoryEntry {
    id: string;
    direction: "credit" | "debit";
    kind: string;
    amount_usd_micros: number;
    balance_after_available: number;
    balance_after_held: number;
    reference_type: string | null;
    reference_id: string | null;
    metadata: Record<string, unknown>;
    created_at: string;
}
export interface BillingHistoryResult {
    /** Canonical organization id (UUID) the entries belong to. */
    org_id: string;
    entries: BillingHistoryEntry[];
    has_more: boolean;
    next_cursor: string | null;
}
/** Options for {@link Billing.history} / {@link Billing.getHistory}. */
export interface BillingHistoryOptions {
    /** Page size; gateway default applies when omitted. */
    limit?: number;
    /** Opaque keyset cursor — page forward from a prior page's `next_cursor`. */
    after?: string;
}
export interface CreateCheckoutResult {
    org_id: string;
    product: CheckoutProduct;
    checkout_url: string;
    topup_id: string;
}
/**
 * A Lightning cash top-up (lightning-cash-topup). `amount_usd_micros` is a
 * QUOTE fixed at mint (`usd_value_is_quote: true`) and is what settlement
 * credits. Never carries the provider's credential.
 */
export interface LightningTopup {
    org_id: string;
    product: "balance_topup";
    rail: "lightning";
    topup_id: string;
    /** The payable invoice, verbatim. */
    bolt11: string | null;
    payment_hash: string | null;
    amount_sats: number | null;
    amount_usd_micros: number;
    usd_value_is_quote: true;
    quoted_rate: {
        usd_per_btc: number;
        source: string;
        observed_at: string;
        amount_sats: number;
    } | null;
    invoice_expires_at: string | null;
    status: "pending" | "paid" | "paid_late" | "expired";
    paid_at: string | null;
    credited_ledger_id: string | null;
    created_at: string | null;
    next_actions: Array<{
        type: string;
        method: string;
        path: string;
        why: string;
    }>;
}
export interface CreateLightningTopupOptions {
    /** Whole satoshis, 100–1,000,000. */
    amountSats: number;
    /** Replay-safe create: the same key returns the same top-up. */
    idempotencyKey?: string;
}
export interface WaitForTopupOptions {
    pollMs?: number;
    timeoutMs?: number;
    onPoll?: (state: LightningTopup) => void;
}
export interface EmailOrganization {
    id: string;
    email: string;
    email_credits_remaining: number;
    verification_sent: boolean;
}
/**
 * Pool impact of a wallet-link operation (v1.46+). Returned in the
 * `link-wallet` response so the caller knows the freshly-shared pool's
 * tier, current usage, and configured limits at the moment of linking.
 */
export interface LinkWalletPoolImplications {
    tier: ProjectTier | null;
    projects_in_pool_count: number;
    organization_api_calls_current: number;
    organization_storage_bytes_current: number;
    tier_limits: {
        api_calls: number;
        storage_bytes: number;
    };
    over_limit: boolean;
}
export interface LinkWalletResult {
    status: string;
    org_id: string;
    wallet: string;
    /** Present on v1.46+ gateways; undefined when the gateway predates the field. */
    pool_implications?: LinkWalletPoolImplications;
}
export type OrganizationIdentifier = string;
export type CheckoutProduct = "balance_topup" | "tier" | "email_pack";
export type CreateCheckoutOptions = {
    product: "balance_topup";
    amountUsdMicros: number;
    successUrl?: string;
    cancelUrl?: string;
} | {
    /** lightning-cash-topup: a bolt11 invoice instead of a Stripe session. */
    product?: "balance_topup";
    rail: "lightning";
    amountSats: number;
} | {
    product: "tier";
    tier: ProjectTier;
    successUrl?: string;
    cancelUrl?: string;
} | {
    product: "email_pack";
    successUrl?: string;
    cancelUrl?: string;
};
export interface AutoRechargeOptions {
    organizationId: string;
    enabled: boolean;
    threshold?: number;
}
export declare class Billing {
    private readonly client;
    readonly balance: (identifier: OrganizationIdentifier) => Promise<OrganizationDetail>;
    readonly createEmail: (email: string) => Promise<EmailOrganization>;
    readonly autoRecharge: (opts: AutoRechargeOptions) => Promise<void>;
    constructor(client: Client);
    /** Check a organization by organization id (UUID), wallet, or email. */
    checkBalance(identifier: OrganizationIdentifier): Promise<OrganizationDetail>;
    /**
     * Read a organization's financial detail by organization id (UUID), wallet,
     * or email. An organization id reads `GET /orgs/v1/:org_id/billing`
     * directly; a wallet/email is resolved through the
     * `GET /orgs/v1/lookup?wallet=|?email=` lookup. Requires SIWX from a
     * wallet linked to the organization (or matching the looked-up `?wallet`), or an
     * admin key; email lookups are admin-only.
     */
    getOrganization(identifier: OrganizationIdentifier): Promise<OrganizationDetail>;
    /**
     * Resolve a wallet or email to its organization detail — including the
     * canonical `org_id` — via `GET /orgs/v1/lookup?wallet=|?email=`.
     * An org-id (UUID) argument is read directly instead. SIWX must match the
     * `?wallet`; email lookups are admin-only.
     */
    lookupOrganization(identifier: OrganizationIdentifier): Promise<OrganizationDetail>;
    /**
     * Fetch billing history by organization id (UUID), wallet, or email. Pass
     * `{ limit, after }` to page; `after` is the opaque keyset cursor
     * (`next_cursor` from a prior page).
     */
    history(identifier: OrganizationIdentifier, opts?: BillingHistoryOptions): Promise<BillingHistoryResult>;
    /**
     * Fetch ledger history for a organization. History is keyed by organization id
     * (UUID): a wallet/email identifier is first resolved to its organization via the
     * lookup, then `GET /orgs/v1/:org_id/billing/history` is read.
     * Requires SIWX from a wallet linked to the organization, or an admin key.
     * Pass `{ limit, after }` to page; `after` is the opaque keyset cursor
     * (`next_cursor` from a prior page). Returns `{ org_id, entries, has_more,
     * next_cursor }`.
     */
    getHistory(identifier: OrganizationIdentifier, opts?: BillingHistoryOptions): Promise<BillingHistoryResult>;
    /** Create a Stripe checkout URL for an organization. */
    createCheckout(organizationId: string, checkout: CreateCheckoutOptions): Promise<CreateCheckoutResult>;
    /**
     * lightning-cash-topup: mint a bolt11 invoice that tops up the org's cash
     * balance when paid. No funds move at creation; any active org member or a
     * delegate for one of the org's projects may call it.
     */
    createLightningTopup(organizationId: string, options: CreateLightningTopupOptions): Promise<LightningTopup>;
    /** Read one top-up (the waiting client's poll). */
    getTopup(organizationId: string, topupId: string): Promise<LightningTopup>;
    /**
     * Poll a top-up until it is paid, paid late, or expired (or the timeout
     * elapses, in which case the last observed state is returned).
     */
    waitForTopup(organizationId: string, topupId: string, options?: WaitForTopupOptions): Promise<LightningTopup>;
    /** Create an email-only (no-wallet) organization. Sends a verification email. */
    createEmailOrganization(email: string): Promise<EmailOrganization>;
    /**
     * Link a wallet to an existing email organization to enable hybrid
     * Stripe + x402 payments. `organizationId` is the canonical
     * `org_id` (UUID) returned by `createEmailOrganization` /
     * `lookupOrganization`; the gateway addresses the route as
     * `POST /orgs/v1/:org_id/wallets`. Returns the gateway
     * response; v1.46+ gateways include a {@link LinkWalletPoolImplications}
     * block describing the freshly-shared pool's tier, current usage, and limits
     * so callers can warn before the merge pushes usage `over_limit`.
     */
    linkWallet(organizationId: string, wallet: string): Promise<LinkWalletResult>;
    /** Enable/disable email-pack auto-recharge. */
    setAutoRecharge(opts: AutoRechargeOptions): Promise<void>;
}
//# sourceMappingURL=billing.d.ts.map