import type * as Log from '../../internal/Log.js';
import type * as Metrics from '../../Metrics.js';
import type * as Analytics from '../Analytics.js';
/** Columns of the `request_events` table: one compact row per API request. */
export type Table = {
    /**
     * Whether the owning org's billing was active at request time (`1`/`0`), for
     * authenticated API-key callers; `null` otherwise. The request-metered
     * billing gate for sandbox: only `1` rows bill.
     */
    billing_active: number | null;
    /** Tempo chain selected for the request. */
    chain_id: number | null;
    /** Total request duration in milliseconds. */
    duration_ms: number;
    /** Deployment environment that served the request. */
    environment: string;
    /** Stable API error code, when the response was an error envelope. */
    error_code: string | null;
    /** API-key environment for authenticated API-key callers. */
    key_environment: 'production' | 'sandbox' | null;
    /** API key id for authenticated API-key callers. */
    key_id: string | null;
    /** HTTP method. */
    method: string;
    /** Organization id for authenticated API-key callers. */
    org_id: string | null;
    /** Project id for authenticated API-key callers. */
    project_id: string | null;
    /** Caller principal kind. */
    principal_type: 'api_key' | 'public' | 'session' | 'super_admin' | 'unknown';
    /** Redacted request query string, without a leading `?`. */
    query: string;
    /** Rate-limit bucket scope, when a rate limit was applied. */
    rate_limit_scope: string | null;
    /** Numeric JSON-RPC error code when every failed response shares one code. */
    rpc_error_code: number | null;
    /** Stable application error code from JSON-RPC `error.data.code`. */
    rpc_error_data_code: string | null;
    /** Number of failed JSON-RPC responses in the request. */
    rpc_error_count: number;
    /** Stable per-request id (`entry.requestId`); dedups the billing count via `uniqExact`. */
    request_id: string | null;
    /** Bounded matched route pattern. */
    route: string;
    /** Service that emitted the event. */
    service: string;
    /** HTTP response status code. */
    status: number;
    /** UTC request completion timestamp formatted for ClickHouse DateTime64. */
    timestamp: string;
    /** Longest Server-Timing operation duration per metric name. */
    timings: Record<string, number>;
};
/** One request attribution term for usage reads. */
export type Attribution = {
    /** API key ids matched by this term; absent means all keys. */
    apiKeyIds?: readonly string[] | undefined;
    /** API-key environment matched by this term; absent means all environments. */
    environment?: Environment | undefined;
    /**
     * Project scope for this term: a project id matches that project, `null`
     * matches rows without project attribution, and `undefined` matches the
     * whole organization (any project, including unattributed rows).
     */
    projectId?: string | null | undefined;
};
/** API-key environment for request usage. */
export type Environment = 'production' | 'sandbox';
/** API errors grouped by their stable error code. */
export type ErrorBreakdown = {
    /** Stable API error code, or `unknown` when none was recorded. */
    code: string;
    /** Requests returning this error. */
    requests: number;
};
/** API key usage grouped for one project. */
export type KeyBreakdown = {
    /** API key id (`key_…`). */
    apiKeyId: string;
    /** Average request duration in milliseconds. */
    averageDurationMs: number;
    /** Requests whose status was at least 400. */
    errors: number;
    /** Total requests. */
    requests: number;
};
/** Latest authenticated request timestamp for one API key. */
export type LastUsedAt = {
    /** API key id (`key_…`). */
    apiKeyId: string;
    /** Latest request completion timestamp (ISO 8601). */
    lastUsedAt: string;
};
/** Time bucket size for the usage series. */
export type Interval = 'day' | 'hour';
/** Route usage grouped for one project. */
export type RouteBreakdown = {
    /** Average request duration in milliseconds. */
    averageDurationMs: number;
    /** Requests whose status was at least 400. */
    errors: number;
    /** Total requests. */
    requests: number;
    /** Matched route pattern. */
    route: string;
};
/** One usage series point. */
export type SeriesPoint = {
    /** Requests whose status was at least 400. */
    errors: number;
    /** Total requests. */
    requests: number;
    /** Bucket start timestamp (ISO 8601). */
    time: string;
};
/** Status-code usage grouped for one project. */
export type StatusBreakdown = {
    /** Total requests. */
    requests: number;
    /** HTTP status code. */
    status: number;
};
/** Overall usage totals for one project. */
export type Totals = {
    /** Average request duration in milliseconds. */
    averageDurationMs: number;
    /** Requests whose status was at least 400. */
    errors: number;
    /** Total requests. */
    requests: number;
};
/** Usage read options for one project. */
export type ProjectUsageOptions = {
    /** Attribution terms that define which request rows count. */
    attributions: readonly Attribution[];
    /** Inclusive lower timestamp bound (ISO 8601). */
    from: string;
    /** Bucket size for the time series. */
    interval: Interval;
    /** Organization id (`org_…`). */
    orgId: string;
    /** Inclusive upper timestamp bound (ISO 8601). */
    to: string;
};
/** Project usage response body. */
export type ProjectUsage = {
    /** Usage grouped by API key. */
    byKey: readonly KeyBreakdown[];
    /** Usage grouped by route. */
    byRoute: readonly RouteBreakdown[];
    /** Usage grouped by status code. */
    byStatus: readonly StatusBreakdown[];
    /** Inclusive lower timestamp bound used for the read (ISO 8601). */
    from: string;
    /** Bucket size used for the time series. */
    interval: Interval;
    /** Usage grouped into small time buckets. */
    series: readonly SeriesPoint[];
    /** Inclusive upper timestamp bound used for the read (ISO 8601). */
    to: string;
    /** Overall usage totals. */
    totals: Totals;
};
/**
 * Builds a `Metrics.cloudflare` analytics factory that enqueues one compact
 * request row per entry onto `queue`. Pass the result directly as the
 * backend's `analytics` option; it reuses the backend's
 * `enabled`/`environment`/`service` context and self-disables when `enabled`
 * is false.
 *
 * @param queue - The analytics queue producer.
 * @returns The analytics factory.
 */
export declare function createQueueSink(queue: createQueueSink.Queue): createQueueSink.Factory;
export declare namespace createQueueSink {
    /** Analytics factory accepted by `Metrics.cloudflare`'s `analytics` option. */
    type Factory = (context: Metrics.cloudflare.Context) => Log.Emit;
    /** Minimal Cloudflare Queue producer shape the sink sends rows to. */
    type Queue = {
        /** Enqueues one row; the result is awaited and discarded. */
        send(message: Table): Promise<unknown>;
    };
}
/**
 * Inserts a batch of queued request rows, acking each message on success and
 * retrying the batch on failure.
 *
 * @param analytics - The analytics store.
 * @param messages - The queued messages.
 */
export declare function insertMessages(analytics: Analytics.Analytics, messages: readonly insertMessages.Message[], options?: insertMessages.Options): Promise<void>;
export declare namespace insertMessages {
    /** Minimal Cloudflare Queue message shape carrying one row. */
    type Message = {
        /** Acknowledges the message. */
        ack(): void;
        /** Queued row. */
        body: Table;
        /** Marks the message for redelivery. */
        retry(): void;
    };
    /** Queue insert observability options. */
    type Options = {
        /** Receives one bounded batch result after messages are acknowledged or retried. */
        onResult?: ((result: Result) => void) | undefined;
    };
    /** Outcome of one analytics insert batch. */
    type Result = {
        /** Number of messages acknowledged. */
        messages: number;
        /** Successful queue disposition. */
        outcome: 'acked';
    } | {
        /** Original insert failure. */
        cause: unknown;
        /** Number of messages marked for retry. */
        messages: number;
        /** Failed queue disposition. */
        outcome: 'retried';
    };
}
/**
 * Reads the latest authenticated request timestamp for each requested API key.
 * Keys with no request events are omitted.
 */
export declare function readLastUsedAt(analytics: Analytics.Analytics, apiKeyIds: readonly string[]): Promise<LastUsedAt[]>;
/**
 * Reads request usage for one project from the `request_events` table.
 *
 * @param analytics - The analytics store.
 * @param options - The usage read options.
 * @returns The project usage.
 */
export declare function readProjectUsage(analytics: Analytics.Analytics, options: ProjectUsageOptions): Promise<ProjectUsage>;
/** Reads stable API error-code counts for one organization attribution window. */
export declare function readErrorBreakdown(analytics: Analytics.Analytics, options: ProjectUsageOptions): Promise<ErrorBreakdown[]>;
/** One org's deduped billable request count for a single UTC hour. */
export type BillableCount = {
    /** UTC hour start (ISO 8601). */
    bucketStart: string;
    /** Deduped billable request count (`uniqExact(request_id)`). */
    count: number;
    /** Organization id (`org_…`). */
    orgId: string;
};
/** Options for {@link readBillableCounts}. */
export type BillableCountsOptions = {
    /** API-key environment to bill; `sandbox` rows require request-time billing. */
    environment: Environment;
    /** Inclusive lower timestamp bound (ISO 8601). */
    from: string;
    /** Exclusive upper timestamp bound (ISO 8601); the seal cutoff. */
    to: string;
};
/**
 * Reads deduped billable request counts grouped by `(org, UTC hour)` for the
 * request-metered billing reporter. Counts dedupe on `request_id` via
 * `uniqExact` (the queue → ClickHouse path can duplicate rows); production rows
 * always bill, sandbox rows only when `billing_active = 1` at request time.
 *
 * @param analytics - The analytics store.
 * @param options - The read options.
 * @returns One deduped count per `(org, hour)`.
 */
export declare function readBillableCounts(analytics: Analytics.Analytics, options: BillableCountsOptions): Promise<BillableCount[]>;
//# sourceMappingURL=requestEvents.d.ts.map