import type { Selectable } from 'kysely';
import type * as Db from '../Db.js';
import type * as db_Schema from '../Schema.js';
/** Columns of the `sponsored_transactions` table, derived from `Schema.SponsoredTransaction`. */
export type Table = db_Schema.SponsoredTransaction;
/** A stored sponsored-transaction row. */
export type Record = Selectable<Table>;
/** How long failed fill intents remain eligible for on-chain reconciliation. */
export declare const failedIntentRecoveryTtlMs = 86400000;
/**
 * Records one sponsorship commitment as `pending`, keyed by its fee-payer
 * sign payload. Written after fee-payer signing and before any broadcast, so
 * no sponsored transaction goes unrecorded; a later recording site for the
 * same envelope (raw submission after a fill intent) upgrades the row with
 * its transaction hash, reopening failed rows for finalization.
 *
 * @param db - The database.
 * @param input - Attribution and envelope facts captured at signing time.
 * @returns The stored record.
 */
export declare function upsert(db: Db.Db, input: upsert.Input): Promise<Record>;
export declare namespace upsert {
    /** Attribution and envelope facts recorded at sponsorship time. */
    type Input = {
        /** API key id (`key_…`) that requested sponsorship. */
        apiKeyId: string;
        /** Whether the sponsorship accrues billable spend; false for sandbox. */
        billable: boolean;
        /** Chain the sponsored transaction targets. */
        chainId: number;
        /** Lowercase fee currency snapshot (`usd`), when resolved. */
        currency?: string | undefined;
        /** Key environment the sponsorship was requested under. */
        environment: Table['environment'];
        /** Signed fee cap (`gas × maxFeePerGas`) in base units, when known. */
        feeMax?: string | undefined;
        /** Fee token the sponsorship resolved, when known. */
        feeToken?: string | undefined;
        /** Organization id (`org_…`) the spend attributes to. */
        orgId: string;
        /** Project id (`prj_…`) the spend attributes to; omit for organization-level spend. */
        projectId?: string | undefined;
        /** Fee-payer sign payload — a stable identity for the sponsored envelope. */
        signPayload: string;
        /** Serialized sponsored transaction, kept for observability beyond log retention. */
        transaction: string;
        /** Transaction hash; omit for fill intents, whose senders have not signed yet. */
        transactionHash?: string | undefined;
    };
}
/**
 * Reads one sponsorship row by id.
 *
 * @param db - The database.
 * @param id - The sponsored-transaction id (`stx_…`).
 * @returns The record, or `undefined` when absent.
 */
export declare function get(db: Db.Db, id: string): Promise<Record | undefined>;
/**
 * Lists pending sponsorships, oldest first, for the finalization job.
 *
 * @param db - The database.
 * @param options - Paging options.
 * @returns The pending records.
 */
export declare function listPending(db: Db.Db, options?: listPending.Options): Promise<Record[]>;
export declare namespace listPending {
    /** Options for {@link listPending}. */
    type Options = {
        /** Maximum rows to return. */
        limit?: number | undefined;
    };
}
/**
 * Lists hash-less fill intents, oldest first, for the reconciliation pass.
 * Failed intents are included only when the caller supplies a recovery floor.
 *
 * @param db - The database.
 * @param options - Paging options.
 * @returns The pending intents.
 */
export declare function listIntents(db: Db.Db, options?: listIntents.Options): Promise<Record[]>;
export declare namespace listIntents {
    /** Options for {@link listIntents}. */
    type Options = listPending.Options & {
        /** Include failed intents whose terminal timestamp is at or after this ISO timestamp. */
        failedSince?: string | undefined;
    };
}
/**
 * Fills a reconciled intent's transaction hash and reopens failed intents.
 * A no-op once another pass already assigned the hash.
 *
 * @param db - The database.
 * @param id - The sponsored-transaction id (`stx_…`).
 * @param transactionHash - The matched on-chain transaction hash.
 * @param limit - The active period spend limit, when enforced.
 */
export declare function assignTransactionHash(db: Db.Db, id: string, transactionHash: string, limit?: reserve.Limit): Promise<void>;
/**
 * Transitions a pending sponsorship to `finalized` with the receipt's actual
 * fee. A no-op when the row is no longer pending (idempotent re-runs).
 *
 * @param db - The database.
 * @param id - The sponsored-transaction id (`stx_…`).
 * @param input - The finalized fee facts.
 */
export declare function finalize(db: Db.Db, id: string, input: finalize.Input): Promise<void>;
export declare namespace finalize {
    /** Fee facts resolved from the transaction receipt. */
    type Input = {
        /** Actual fee paid in fee-token base units. */
        feeAmount: string;
        /** When the sponsorship finalized (ISO 8601). */
        finalizedAt: string;
    };
}
/**
 * Transitions a pending sponsorship to `failed` (never landed within the
 * pending TTL). A no-op when the row is no longer pending.
 *
 * @param db - The database.
 * @param id - The sponsored-transaction id (`stx_…`).
 * @param finalizedAt - When the sponsorship was marked failed (ISO 8601).
 */
export declare function fail(db: Db.Db, id: string, finalizedAt: string): Promise<void>;
/**
 * Records a sponsorship and enforces the period spend limit atomically. A
 * per-org advisory lock serializes concurrent sponsorships so each one's
 * signed cap is counted before the limit check; without it a burst reads
 * pre-burst spend and overshoots. Throws {@link PeriodSpendLimitError} (rolling
 * back the row) when the limit would be exceeded.
 *
 * @param db - The database (primary; never a cached replica).
 * @param input - The sponsorship to record.
 * @param limit - The period spend limit to enforce.
 * @returns The stored record.
 */
export declare function reserve(db: Db.Db, input: upsert.Input, limit: reserve.Limit): Promise<Record>;
export declare namespace reserve {
    /** The period spend limit enforced by {@link reserve}. */
    type Limit = {
        /** Billing snapshot whose rows consume this limit; omit for customer-billable spend. */
        billable?: boolean | undefined;
        /** Chains whose spend counts (mainnet chain ids). */
        chainIds: readonly number[];
        /** Limit in fee-token base units. */
        max: bigint;
        /** Project scope for independent limits; omit for the organization-wide budget. */
        projectId?: string | undefined;
        /** Window start (ISO 8601). */
        since: string;
    };
}
/**
 * Applies the current promotion policy and records the sponsorship atomically.
 * Exhausted promotions retain their window and fall back to customer billing.
 */
export declare function reservePromotion(db: Db.Db, input: upsert.Input, options: reservePromotion.Options): Promise<reservePromotion.Result>;
export declare namespace reservePromotion {
    /** Project promotion window and cap. */
    type Options = {
        /** Timestamp of the recorded sponsorship that may activate the window. */
        at: string;
        /** Customer billing limit used when the project promotion is exhausted. */
        billingLimit?: reserve.Limit | undefined;
        /** Mainnet chains whose promotional spend counts. */
        chainIds: readonly number[];
        /** Project receiving the independent promotion. */
        projectId: string;
    };
    /** Promotion reservation outcome. */
    type Result = {
        /** Stored sponsorship. */
        record: Record;
        /** Whether Tempo or the customer pays for the stored sponsorship. */
        status: 'billed' | 'subsidized';
    } | {
        /** The current organization or project policy does not grant a promotion. */
        status: 'ineligible';
    };
}
/**
 * Billable spend committed since a cutoff, in fee-token base units: finalized
 * rows at their actual fee plus pending rows at their signed fee cap, so
 * in-flight sponsorships consume limit budget until receipts land.
 *
 * @param db - The database.
 * @param options - Aggregation scope.
 * @returns The committed spend in base units.
 */
export declare function spend(db: Db.Db, options: spend.Options): Promise<bigint>;
export declare namespace spend {
    /** Options for {@link spend}. */
    type Options = {
        /** Billing snapshot to count; omit for the existing production-billable behavior. */
        billable?: boolean | undefined;
        /** Chains whose spend counts (mainnet chain ids). */
        chainIds: readonly number[];
        /** Environment whose spend counts; production mirrors the billing gate, sandbox is display-only. Defaults to `production`. */
        environment?: Table['environment'] | undefined;
        /** Organization id (`org_…`) the spend attributes to. */
        orgId: string;
        /** Project whose spend counts; omit for organization-wide spend. */
        projectId?: string | undefined;
        /** Window start (ISO 8601); rows created earlier are out of scope. */
        since: string;
    };
}
/**
 * Sponsorship usage bucketed by time for one organization: row counts and
 * committed fees per bucket. Fee semantics mirror {@link spend}: finalized
 * rows at their actual fee, pending rows at their signed cap, failed rows at
 * zero. Buckets with no rows are omitted.
 *
 * @param db - The database.
 * @param options - Aggregation scope.
 * @returns Time-ordered usage buckets.
 */
export declare function usage(db: Db.Db, options: usage.Options): Promise<usage.Bucket[]>;
export declare namespace usage {
    /** One time bucket of sponsorship usage. */
    type Bucket = {
        /** Sponsored transactions recorded in the bucket, any status. */
        count: number;
        /** Sponsored transactions in the bucket whose status is `failed`. */
        failed: number;
        /** Committed fees in fee-token base units: finalized fees plus pending caps. */
        feeTotal: bigint;
        /** Bucket start (ISO 8601), aligned to UTC calendar boundaries. */
        timestamp: string;
    };
    /** Options for {@link usage}. */
    type Options = {
        /** Key environment to restrict to; omit for all. */
        environment?: Table['environment'] | undefined;
        /** Window start (ISO 8601), inclusive. */
        from: string;
        /** Bucket width, aligned to UTC calendar boundaries. */
        interval: 'day' | 'hour' | 'month' | 'week';
        /** Organization id (`org_…`) the usage attributes to. */
        orgId: string;
        /** Project id (`prj_…`) to restrict to; omit for all. */
        projectId?: string | undefined;
        /** Window end (ISO 8601), exclusive. */
        to: string;
    };
}
/**
 * Lists finalized billable rows not yet reported to the billing meter, oldest
 * first, for the metering job.
 *
 * @param db - The database.
 * @param options - Reporting scope.
 * @returns The unreported records.
 */
export declare function listUnreported(db: Db.Db, options: listUnreported.Options): Promise<Record[]>;
export declare namespace listUnreported {
    /** Options for {@link listUnreported}. */
    type Options = {
        /** Chains whose spend is metered (mainnet chain ids). */
        chainIds: readonly number[];
        /** Maximum rows to return. */
        limit?: number | undefined;
    };
}
/**
 * Marks a row as reported to the billing meter. A no-op once marked — the
 * durable exactly-once guard for the metering job.
 *
 * @param db - The database.
 * @param id - The sponsored-transaction id (`stx_…`).
 * @param at - When the report was acknowledged (ISO 8601).
 */
export declare function markReported(db: Db.Db, id: string, at: string): Promise<void>;
/** Thrown by {@link reserve} when recording would exceed the org's period spend limit. */
export declare class PeriodSpendLimitError extends Error {
    name: string;
}
/** Thrown when a promotional window cannot be activated consistently. */
export declare class PromotionActivationError extends Error {
    name: string;
}
/** Thrown when one signed envelope is presented with conflicting project attribution. */
export declare class AttributionConflictError extends Error {
    name: string;
}
//# sourceMappingURL=sponsoredTransactions.d.ts.map