@coinbase/cdp-sdk/_types/x402/guardrails/spend-tracker.d.ts

SDK for interacting with the Coinbase Developer Platform Wallet API

import type { Address, Asset, SpendLedgerEntry, SpendStore } from "./types.js";
import type { Network } from "@x402/core/types";
/**
 * Default maximum number of ledger entries kept in memory.
 */
export declare const DEFAULT_MAX_LEDGER_ENTRIES = 10000;
/**
 * Constructor options for {@link SpendTracker}.
 */
export interface SpendTrackerOptions {
    /**
     * Maximum number of entries to hold. Defaults to {@link DEFAULT_MAX_LEDGER_ENTRIES}.
     */
    maxLedgerEntries?: number;
    /**
     * Storage backend. Defaults to an in-memory array-backed store.
     */
    store?: SpendStore;
}
/**
 * Argument shape for {@link SpendTracker.record}.
 */
export interface RecordSpendInput {
    /** - Payment amount in base units. */
    atomicAmount: bigint;
    /** - Asset identifier. */
    asset: Asset;
    /** - Network the payment was made on. */
    network: Network;
    /** - Payee address. */
    payTo: Address;
}
/**
 * Argument shape for {@link SpendTracker.total}.
 */
export interface TotalSpendQuery {
    /** - Asset to sum. */
    asset: Asset;
    /** - Inclusive lower bound (ms since epoch). Entries strictly older are excluded. */
    since?: number;
}
/**
 * Tracks spend per asset in an append-only ledger.
 */
export declare class SpendTracker {
    private readonly store;
    private readonly maxLedgerEntries;
    private warnedOnRemove;
    /**
     * Creates a new SpendTracker.
     *
     * @param options - Optional configuration for the tracker.
     */
    constructor(options?: SpendTrackerOptions);
    /**
     * Adds a spend entry to the ledger and returns it.
     *
     * @param input - The spend record to add.
     * @returns The recorded ledger entry.
     */
    record(input: RecordSpendInput): Promise<SpendLedgerEntry>;
    /**
     * Sum atomic amounts for the given asset, optionally restricted to entries
     * recorded at or after `since`.
     *
     * @param query - Query parameters specifying asset and optional time window.
     * @returns The total atomic amount spent.
     */
    total(query: TotalSpendQuery): Promise<bigint>;
    /**
     * Drop entries older than `now - windowMs`.
     *
     * @param now - Current timestamp in milliseconds.
     * @param windowMs - Optional rolling window size in milliseconds.
     */
    prune(now: number, windowMs?: number): Promise<void>;
    /**
     * Removes a previously recorded entry, undoing its contribution to the cumulative total.
     *
     * @param entry - The ledger entry to remove.
     */
    removeEntry(entry: SpendLedgerEntry): Promise<void>;
    /**
     * Returns all current ledger entries as a read-only snapshot.
     *
     * @returns All current entries.
     */
    entries(): Promise<readonly SpendLedgerEntry[]>;
}
//# sourceMappingURL=spend-tracker.d.ts.map