/** Product measurement with declared keys and bounded dimensions. No runtime or store dependency. */
export type MetricSpec = {
    kind: "counter" | "timing";
    label: string;
    help?: string;
    unit?: string;
    perUser?: boolean;
    dimensions?: Record<string, readonly string[]>;
};
export interface Measurement {
    key: string;
    day: string;
    count: number;
    sum: number;
    user?: string | number;
    dimensions: Record<string, string>;
}
export interface MetricsSchema {
    metrics: Array<{
        key: string;
    } & MetricSpec>;
    overlaps: Array<{
        from: string;
        to: string;
    }>;
}
/**
 * Where measurements go. `declare` runs once per process before the first write and
 * carries the whole schema (kinds, labels, per-user flags, overlaps), so a store is
 * self-describing and a reader never needs the declaring code. `write` carries one sample.
 */
export interface MetricsStore {
    declare(schema: MetricsSchema): Promise<unknown>;
    write(measurement: Measurement): Promise<unknown>;
}
export interface MetricsOptions<Keys extends string = string> {
    store: MetricsStore;
    /** Unordered user overlap, not an ordered conversion funnel. */
    overlaps?: ReadonlyArray<readonly [Keys, Keys]>;
    /** Failures are visible by default, but never reject a measurement call. */
    onError?: (error: unknown, key: string) => void;
    now?: () => Date;
}
export interface SampleOptions {
    user?: string | number;
    dimensions?: Record<string, string>;
}
export interface CounterHandle {
    bump(options?: SampleOptions & {
        n?: number;
    }): Promise<void>;
}
export interface TimingHandle {
    record(value: number, options?: SampleOptions): Promise<void>;
}
export type Metrics<Spec extends Record<string, MetricSpec>> = {
    [K in keyof Spec]: Spec[K]["kind"] extends "counter" ? CounterHandle : TimingHandle;
} & {
    describe(): MetricsSchema;
    /**
     * Declare now instead of at the first sample: a server's boot, a Worker's cron. The
     * same once-per-process promise the samples await, so calling it is never a second write.
     */
    declare(): Promise<void>;
};
export declare function defineMetrics<const Spec extends Record<string, MetricSpec>>(input: Spec, opts: MetricsOptions<Extract<keyof Spec, string>>): Metrics<Spec>;
//# sourceMappingURL=index.d.ts.map