import * as RequestEvents from './tables/requestEvents.js';
export { createQueueSink } from './tables/requestEvents.js';
/** One org's deduped billable request count for a UTC hour; the reporter's source row. */
export type BillableCount = RequestEvents.BillableCount;
/** Options for {@link readBillableRequestCounts}. */
export type BillableCountsOptions = RequestEvents.BillableCountsOptions;
/** One organization's request usage and error breakdown. */
export type ProjectUsage = RequestEvents.ProjectUsage;
/** Options for reading one organization's request usage. */
export type ProjectUsageOptions = RequestEvents.ProjectUsageOptions;
/** API errors grouped by their stable error code. */
export type ErrorBreakdown = RequestEvents.ErrorBreakdown;
/** Reads stable API error-code counts for one organization attribution window. */
export declare function readErrorBreakdown(source: Source, options: ProjectUsageOptions): Promise<ErrorBreakdown[]>;
/** Reads request usage for an organization and optional attribution terms. */
export declare function readProjectUsage(source: Source, options: ProjectUsageOptions): Promise<ProjectUsage>;
/**
 * Reads deduped billable request counts grouped by `(org, UTC hour)` from
 * `request_events` — the request-metered billing source. Resolves the source
 * at the leaf so a Workers factory builds a fresh connection.
 *
 * @param source - The analytics store or factory.
 * @param options - The read options.
 * @returns One deduped count per `(org, hour)`.
 */
export declare function readBillableRequestCounts(source: Source, options: BillableCountsOptions): Promise<BillableCount[]>;
/**
 * ClickHouse schema; table repository modules (`tables/*`) type their rows
 * through it.
 */
export type Database = {
    request_events: RequestEvents.Table;
};
/**
 * A ClickHouse-backed analytics store: row inserts, JSON reads, and schema
 * migrations. Table repository modules (`tables/*`) query through it.
 */
export type Analytics = {
    /** Inserts rows into a table. */
    insert<name extends keyof Database>(table: name, rows: readonly Database[name][]): Promise<void>;
    /** Applies any pending schema migrations; safe to re-run. */
    migrate(): Promise<void>;
    /** Runs a read query, returning JSON rows. */
    query<row>(sql: string): Promise<row[]>;
};
/**
 * An {@link Analytics}, or a factory for per-request construction. Resolve at
 * the leaf with {@link get}.
 */
export type Source = Analytics | (() => Analytics);
/** One stored request row (`request_events`); hosts use it in their queue-body union. */
export type Event = RequestEvents.Table;
/** Queue name {@link handleQueue} consumes; the host's queue producer/consumer bindings must reference it. */
export declare const queueName = "api-request-analytics";
/**
 * Resolves a {@link Source} to an {@link Analytics}. Call at the request leaf
 * so factories create per-request instances; singletons resolve to themselves.
 *
 * @param source - The analytics store or factory.
 * @returns The resolved {@link Analytics}.
 */
export declare function get(source: Source): Analytics;
/** One schema migration: a single idempotent DDL statement, safe to re-apply. */
type Migration = {
    /** Unique, ordered migration name (e.g. `0001_request_events`). */
    name: string;
    /** Idempotent DDL applied by {@link Analytics.migrate}. */
    sql: string;
    /**
     * Optional `SELECT` run before {@link Migration.sql}; a nonzero first value
     * skips the migration. Lets a scoped user without an `ALTER` grant (preview)
     * skip an `ALTER` whose columns already exist from the baseline `CREATE`.
     */
    guard?: string;
};
/**
 * Ordered migrations for {@link Analytics.migrate}. ClickHouse lacks
 * transactional DDL and advisory locks, so each statement is idempotent
 * (`IF NOT EXISTS`) and re-applied on every run; no applied-migrations ledger.
 */
export declare const migrations: readonly Migration[];
/**
 * Creates a ClickHouse-backed {@link Analytics} over the HTTP interface.
 * Requests scope to `database` (the `?database=` parameter); table names are
 * code-owned by the `tables/*` modules, not configuration.
 *
 * @param options - ClickHouse connection options.
 * @returns The analytics store.
 */
export declare function clickhouse(options: clickhouse.Options): Analytics;
export declare namespace clickhouse {
    /** ClickHouse connection options. */
    type Options = {
        /** Database the connection scopes to (e.g. `tempo_api`). */
        database: string;
        /** Password for `user`. */
        password: string;
        /** ClickHouse HTTPS endpoint. */
        url: string;
        /** ClickHouse user; ingest and read deployments differ only here. */
        user: string;
    };
}
/**
 * Consumes one queue batch when it is the analytics queue ({@link queueName}):
 * batch-inserts the queued rows, acking on success and retrying on failure.
 * Returns whether the batch was handled, so a multi-queue worker can chain:
 *
 * ```ts
 * async queue(batch) {
 *   if (await Analytics.handleQueue(analytics, batch)) return
 *   // … other queues …
 * }
 * ```
 *
 * @param source - The analytics store or factory.
 * @param batch - The queue batch.
 * @param options - Options.
 * @returns Whether the batch belonged to the analytics queue.
 */
export declare function handleQueue(source: Source, batch: handleQueue.Batch, options?: handleQueue.Options): Promise<boolean>;
export declare namespace handleQueue {
    /** Options for {@link handleQueue}. */
    type Options = {
        /** Receives the final insert disposition for metrics and error reporting. */
        onResult?: RequestEvents.insertMessages.Options['onResult'];
        /** Queue name to match instead of {@link queueName} (e.g. a per-preview queue). */
        queue?: string | undefined;
    };
    /** Minimal queue batch shape; Cloudflare's `MessageBatch` satisfies it. */
    type Batch = {
        /** Queued messages; bodies are {@link Event} rows when `queue` matches. */
        messages: readonly Message[];
        /** Originating queue name. */
        queue: string;
    };
    /** One queued message. */
    type Message = {
        /** Acknowledges the message. */
        ack(): void;
        /** Queued body; an {@link Event} when the batch is the analytics queue. */
        body: unknown;
        /** Marks the message for redelivery. */
        retry(): void;
    };
}
/** Rejected ClickHouse identifier. */
export declare class ConfigError extends Error {
    constructor(value: string);
}
/** Failed ClickHouse insert (non-2xx HTTP response). */
export declare class InsertError extends Error {
    /** HTTP response status returned by ClickHouse. */
    status: number;
    constructor(status: number, body: string);
}
/** Failed ClickHouse schema migration (non-2xx HTTP response). */
export declare class MigrateError extends Error {
    constructor(name: string, status: number, body: string);
}
/** Failed ClickHouse read query (non-2xx HTTP response). */
export declare class QueryError extends Error {
    constructor(status: number, body: string);
}
//# sourceMappingURL=Analytics.d.ts.map