import type { AmountLike, CommitReceipt } from './Session.js';
import { SessionFetchClient, type SessionFetchOpenState } from './SessionFetch.js';
/**
 * Priced cumulative amount for the current metered operation.
 */
export interface SessionUsagePrice {
    /** Absolute cumulative amount to record, in base units. */
    readonly cumulativeAmount: AmountLike;
    /** Delta reported in the watermark event. Defaults to target − current. */
    readonly deltaAmount?: AmountLike | undefined;
}
/**
 * Context passed to a usage pricing function.
 */
export interface SessionUsagePricingContext {
    /** Session cumulative when the first usage sample of this operation arrived, in base units. */
    readonly baselineCumulativeAmount: string;
    /** Cumulative the session has accepted so far, in base units. */
    readonly currentCumulativeAmount: string;
    /** Open-session state from the fetch client. */
    readonly open: SessionFetchOpenState;
    /** Highest locally recorded watermark, in base units. */
    readonly targetCumulativeAmount?: string | undefined;
}
/**
 * Converts provider-specific usage into the absolute cumulative amount that
 * should be committed for the active session.
 */
export type SessionUsagePricer<Usage> = (usage: Usage, context: SessionUsagePricingContext) => SessionUsagePrice | null | undefined;
/**
 * High-level helper for SDK streams that expose provider-specific usage.
 *
 * The meter captures the session's cumulative watermark when the first usage
 * sample arrives, converts later usage samples into absolute cumulative amounts,
 * and delegates all voucher reservation/commit work to `SessionFetchClient`.
 *
 * @example
 * ```ts
 * const meter = createSessionUsageMeter({
 *     client,
 *     priceUsage: (usage, context) => ({
 *         cumulativeAmount: BigInt(context.baselineCumulativeAmount) + BigInt(usage.outputTokens),
 *     }),
 * });
 *
 * await meter.withPatchedFetch(async () => {
 *     const stream = await sdk.generateContentStream(request);
 *     for await (const chunk of stream) {
 *         meter.recordUsage(chunk.usage);
 *     }
 * });
 * await meter.flush();
 * ```
 */
export declare class SessionUsageMeter<Usage> {
    #private;
    constructor(parameters: SessionUsageMeter.Parameters<Usage>);
    /** Session fetch client used by this meter. */
    get client(): SessionFetchClient;
    /** First cumulative watermark observed for the current metered operation. */
    get baselineCumulativeAmount(): string | undefined;
    /**
     * Clears the per-operation baseline. Call this before reusing one meter for
     * another upstream stream on the same open session.
     */
    resetBaseline(): void;
    /**
     * Records a usage snapshot. Returns true when it accepted a new cumulative
     * watermark and queued session commit handling.
     */
    recordUsage(usage: Usage, options?: SessionUsageMeter.RecordOptions): boolean;
    /**
     * Forces pricing for the latest usage sample, then waits for any queued
     * voucher commits to settle.
     */
    flush(usage?: Usage): Promise<CommitReceipt | null>;
    /**
     * Runs an SDK call while global `fetch` is temporarily replaced with the
     * session-aware fetch client.
     */
    withPatchedFetch<Value>(operation: () => Promise<Value>): Promise<Value>;
}
export declare namespace SessionUsageMeter {
    interface Parameters<Usage> {
        /** Session fetch client that owns the open session and voucher commits. */
        readonly client: SessionFetchClient;
        /** Converts provider usage samples into absolute cumulative amounts. */
        readonly priceUsage: SessionUsagePricer<Usage>;
    }
    interface RecordOptions {
        /** Commit immediately instead of waiting for the live-commit interval. */
        readonly force?: boolean | undefined;
    }
}
/**
 * Creates a usage meter for an existing `SessionFetchClient`.
 */
export declare function createSessionUsageMeter<Usage>(parameters: SessionUsageMeter.Parameters<Usage>): SessionUsageMeter<Usage>;
//# sourceMappingURL=SessionUsageMeter.d.ts.map