import { type ColumnType } from 'kysely';
import type * as Db from '../Db.js';
import type * as db_Schema from '../Schema.js';
/** A `bigint` count column: read as a string from pg, written as a number. */
type Count = ColumnType<string, number, number>;
/** Environment a request-usage row attributes to. */
export type Environment = db_Schema.RequestUsageBucket['environment'];
/** Exactly-once state of a meter event. */
export type State = db_Schema.RequestUsageMeterEvent['state'];
/** Columns of the `request_usage_buckets` table (pg representation). */
export type BucketTable = {
    bucketStart: string;
    environment: Environment;
    orgId: string;
    reportedCount: Count;
    updatedAt: string;
};
/** Columns of the `request_usage_meter_events` table (pg representation). */
export type MeterEventTable = {
    bucketStart: string;
    deltaCount: Count;
    environment: Environment;
    error: string | null;
    firstAttemptedAt: string;
    identifier: string;
    orgId: string;
    reason: string | null;
    reportedAt: string | null;
    sequence: Count;
    state: State;
    stripeCustomerId: string;
};
/** A stored per-hour request-count watermark. */
export type Bucket = db_Schema.RequestUsageBucket;
/** A stored request-count meter event. */
export type MeterEvent = db_Schema.RequestUsageMeterEvent;
/** Aggregate state for pending meter events in one billing environment. */
export type PendingStatus = {
    count: number;
    oldestAttemptedAt: string | undefined;
};
/** Identifies one hourly bucket for an org in an environment. */
export type BucketKey = {
    /** UTC hour start (ISO 8601). */
    bucketStart: string;
    /** Environment the requests were served under. */
    environment: Environment;
    /** Organization id (`org_…`). */
    orgId: string;
};
/**
 * Reads a bucket watermark.
 *
 * @param db - The database.
 * @param key - The bucket key.
 * @returns The watermark, or `undefined` when none has been reported yet.
 */
export declare function getBucket(db: Db.Db, key: BucketKey): Promise<Bucket | undefined>;
/**
 * Lists the meter events still awaiting a Stripe acknowledgement in an
 * environment, oldest first — the reporter's crash-recovery drive.
 *
 * @param db - The database.
 * @param environment - The environment to scan.
 * @returns The pending meter events.
 */
export declare function listPending(db: Db.Db, environment: Environment): Promise<MeterEvent[]>;
/**
 * Reads the number and age anchor of meter events still awaiting Stripe.
 *
 * @param db - The database.
 * @param environment - The billing environment to inspect.
 * @returns The pending-event count and oldest first attempt.
 */
export declare function getPendingStatus(db: Db.Db, environment: Environment): Promise<PendingStatus>;
/**
 * Inserts a frozen `pending` meter event, claiming a delta. Idempotent on the
 * deterministic `identifier`: a re-seal after a crash resolves to the existing
 * row rather than duplicating the delta.
 *
 * @param db - The database.
 * @param input - The event to insert.
 * @returns Whether this call inserted the row.
 */
export declare function insertPending(db: Db.Db, input: insertPending.Input): Promise<boolean>;
export declare namespace insertPending {
    /** Fields accepted when sealing a pending meter event. */
    type Input = {
        /** UTC hour start the delta bills for (ISO 8601). */
        bucketStart: string;
        /** Frozen request count this event bills (positive). */
        deltaCount: number;
        /** Environment the requests were served under. */
        environment: Environment;
        /** Deterministic id; also the Stripe identifier and idempotency key. */
        identifier: string;
        /** Organization id (`org_…`). */
        orgId: string;
        /** Reported-count watermark observed when this delta was claimed. */
        sequence: number;
        /** Stripe customer id the event bills against. */
        stripeCustomerId: string;
    };
}
/**
 * Marks a pending event reported and advances its bucket watermark by the
 * event's frozen delta, atomically. A no-op once reported, so a retry after a
 * crash between the Stripe ack and this write never double-advances.
 *
 * @param db - The database.
 * @param identifier - The event identifier.
 * @param at - When Stripe acknowledged the event (ISO 8601).
 * @returns Whether this call settled the event (false when already reported).
 */
export declare function settle(db: Db.Db, identifier: string, at: string): Promise<boolean>;
/**
 * Records a transient failure on a pending event; it stays pending for retry.
 *
 * @param db - The database.
 * @param identifier - The event identifier.
 * @param error - The failure detail.
 */
export declare function markError(db: Db.Db, identifier: string, error: string): Promise<void>;
export {};
//# sourceMappingURL=requestUsage.d.ts.map