@paysentry/observe 1.0.0

package/dist/alerts.d.ts

@@ -0,0 +1,139 @@
+import type { AgentTransaction, AgentId, SpendAlert, AlertHandler, AlertSeverity, AlertType, Logger } from '@paysentry/core';
+import type { SpendTracker } from './tracker.js';
+/** Configuration for a single alert rule */
+export interface AlertRule {
+    /** Unique rule identifier */
+    readonly id: string;
+    /** Human-readable name */
+    readonly name: string;
+    /** Alert type */
+    readonly type: AlertType;
+    /** Alert severity */
+    readonly severity: AlertSeverity;
+    /** Whether the rule is active */
+    readonly enabled: boolean;
+    /** Rule configuration */
+    readonly config: AlertRuleConfig;
+}
+/** Configuration specific to each alert type */
+export type AlertRuleConfig = BudgetThresholdConfig | LargeTransactionConfig | RateSpikeConfig | NewRecipientConfig | AnomalyConfig;
+/** Alert when cumulative spend exceeds a threshold */
+export interface BudgetThresholdConfig {
+    readonly type: 'budget_threshold';
+    /** Agent to monitor (undefined = all agents) */
+    readonly agentId?: AgentId;
+    /** Threshold amount */
+    readonly threshold: number;
+    /** Currency */
+    readonly currency: string;
+    /** Time window in milliseconds */
+    readonly windowMs: number;
+    /** Alert at what percentage of threshold (e.g., 0.8 = 80%) */
+    readonly alertAtPercent: number;
+}
+/** Alert on any single transaction above a threshold */
+export interface LargeTransactionConfig {
+    readonly type: 'large_transaction';
+    /** Amount threshold */
+    readonly threshold: number;
+    /** Currency */
+    readonly currency: string;
+}
+/** Alert on transaction frequency spikes */
+export interface RateSpikeConfig {
+    readonly type: 'rate_spike';
+    /** Agent to monitor (undefined = all agents) */
+    readonly agentId?: AgentId;
+    /** Maximum transactions per window */
+    readonly maxTransactions: number;
+    /** Window size in milliseconds */
+    readonly windowMs: number;
+}
+/** Alert when an agent transacts with a new recipient */
+export interface NewRecipientConfig {
+    readonly type: 'new_recipient';
+    /** Agent to monitor (undefined = all agents) */
+    readonly agentId?: AgentId;
+}
+/** Alert on statistical anomalies in spending patterns */
+export interface AnomalyConfig {
+    readonly type: 'anomaly';
+    /** Agent to monitor (undefined = all agents) */
+    readonly agentId?: AgentId;
+    /** Standard deviations above mean to trigger alert */
+    readonly stdDevThreshold: number;
+    /** Minimum number of transactions before anomaly detection activates */
+    readonly minSampleSize: number;
+}
+/**
+ * SpendAlerts monitors the transaction stream and fires alerts when
+ * configured conditions are met. It supports budget thresholds, large
+ * transaction detection, rate spike detection, new recipient alerts,
+ * and statistical anomaly detection.
+ *
+ * @example
+ * ```ts
+ * const alerts = new SpendAlerts(tracker);
+ *
+ * alerts.addRule({
+ *   id: 'daily-budget',
+ *   name: 'Daily USDC Budget',
+ *   type: 'budget_threshold',
+ *   severity: 'warning',
+ *   enabled: true,
+ *   config: {
+ *     type: 'budget_threshold',
+ *     threshold: 100,
+ *     currency: 'USDC',
+ *     windowMs: 86400000, // 24 hours
+ *     alertAtPercent: 0.8,
+ *   },
+ * });
+ *
+ * alerts.onAlert((alert) => {
+ *   console.log(`[${alert.severity}] ${alert.message}`);
+ * });
+ *
+ * // Check a new transaction against all rules
+ * await alerts.evaluate(transaction);
+ * ```
+ */
+export declare class SpendAlerts {
+    private readonly tracker;
+    private readonly rules;
+    private readonly handlers;
+    private readonly knownRecipients;
+    private readonly logger?;
+    constructor(tracker: SpendTracker, options?: {
+        logger?: Logger;
+    });
+    /**
+     * Add an alert rule.
+     */
+    addRule(rule: AlertRule): void;
+    /**
+     * Remove an alert rule by ID.
+     */
+    removeRule(id: string): boolean;
+    /**
+     * Register an alert handler. Called whenever an alert fires.
+     */
+    onAlert(handler: AlertHandler): void;
+    /**
+     * Evaluate a transaction against all active alert rules.
+     * Fires alerts to all registered handlers if conditions are met.
+     */
+    evaluate(tx: AgentTransaction): Promise<SpendAlert[]>;
+    /**
+     * Get all configured rules.
+     */
+    getRules(): AlertRule[];
+    private checkRule;
+    private checkBudgetThreshold;
+    private checkLargeTransaction;
+    private checkRateSpike;
+    private checkNewRecipient;
+    private checkAnomaly;
+    private createAlert;
+}
+//# sourceMappingURL=alerts.d.ts.map

package/dist/alerts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"alerts.d.ts","sourceRoot":"","sources":["../src/alerts.ts"],"names":[],"mappings":"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"}

package/dist/alerts.js

@@ -0,0 +1,266 @@
+// =============================================================================
+// SpendAlerts — Threshold alerts and anomaly detection
+// Watches the transaction stream and fires alerts when conditions are met
+// =============================================================================
+/**
+ * SpendAlerts monitors the transaction stream and fires alerts when
+ * configured conditions are met. It supports budget thresholds, large
+ * transaction detection, rate spike detection, new recipient alerts,
+ * and statistical anomaly detection.
+ *
+ * @example
+ * ```ts
+ * const alerts = new SpendAlerts(tracker);
+ *
+ * alerts.addRule({
+ *   id: 'daily-budget',
+ *   name: 'Daily USDC Budget',
+ *   type: 'budget_threshold',
+ *   severity: 'warning',
+ *   enabled: true,
+ *   config: {
+ *     type: 'budget_threshold',
+ *     threshold: 100,
+ *     currency: 'USDC',
+ *     windowMs: 86400000, // 24 hours
+ *     alertAtPercent: 0.8,
+ *   },
+ * });
+ *
+ * alerts.onAlert((alert) => {
+ *   console.log(`[${alert.severity}] ${alert.message}`);
+ * });
+ *
+ * // Check a new transaction against all rules
+ * await alerts.evaluate(transaction);
+ * ```
+ */
+export class SpendAlerts {
+    tracker;
+    rules = new Map();
+    handlers = [];
+    knownRecipients = new Map();
+    logger;
+    constructor(tracker, options) {
+        this.tracker = tracker;
+        this.logger = options?.logger;
+    }
+    /**
+     * Add an alert rule.
+     */
+    addRule(rule) {
+        this.rules.set(rule.id, rule);
+        this.logger?.info(`[SpendAlerts] Added rule: ${rule.name} (${rule.id})`);
+    }
+    /**
+     * Remove an alert rule by ID.
+     */
+    removeRule(id) {
+        const removed = this.rules.delete(id);
+        if (removed) {
+            this.logger?.info(`[SpendAlerts] Removed rule: ${id}`);
+        }
+        return removed;
+    }
+    /**
+     * Register an alert handler. Called whenever an alert fires.
+     */
+    onAlert(handler) {
+        this.handlers.push(handler);
+    }
+    /**
+     * Evaluate a transaction against all active alert rules.
+     * Fires alerts to all registered handlers if conditions are met.
+     */
+    async evaluate(tx) {
+        const alerts = [];
+        for (const rule of this.rules.values()) {
+            if (!rule.enabled)
+                continue;
+            const alert = this.checkRule(rule, tx);
+            if (alert) {
+                alerts.push(alert);
+            }
+        }
+        // Fire all alerts to handlers
+        for (const alert of alerts) {
+            this.logger?.warn(`[SpendAlerts] Alert fired: ${alert.message}`);
+            for (const handler of this.handlers) {
+                try {
+                    await handler(alert);
+                }
+                catch (err) {
+                    this.logger?.error(`[SpendAlerts] Handler error: ${err}`);
+                }
+            }
+        }
+        return alerts;
+    }
+    /**
+     * Get all configured rules.
+     */
+    getRules() {
+        return [...this.rules.values()];
+    }
+    // ---------------------------------------------------------------------------
+    // Private rule evaluation
+    // ---------------------------------------------------------------------------
+    checkRule(rule, tx) {
+        switch (rule.config.type) {
+            case 'budget_threshold':
+                return this.checkBudgetThreshold(rule, tx, rule.config);
+            case 'large_transaction':
+                return this.checkLargeTransaction(rule, tx, rule.config);
+            case 'rate_spike':
+                return this.checkRateSpike(rule, tx, rule.config);
+            case 'new_recipient':
+                return this.checkNewRecipient(rule, tx, rule.config);
+            case 'anomaly':
+                return this.checkAnomaly(rule, tx, rule.config);
+        }
+    }
+    checkBudgetThreshold(rule, tx, config) {
+        if (config.agentId && tx.agentId !== config.agentId)
+            return null;
+        if (tx.currency !== config.currency)
+            return null;
+        const windowStart = new Date(Date.now() - config.windowMs).toISOString();
+        const recentTxs = this.tracker.query({
+            agentId: config.agentId,
+            currency: config.currency,
+            status: 'completed',
+            after: windowStart,
+        });
+        const currentSpend = recentTxs.reduce((sum, t) => sum + t.amount, 0);
+        const projectedSpend = currentSpend + tx.amount;
+        const thresholdAmount = config.threshold * config.alertAtPercent;
+        if (projectedSpend >= thresholdAmount) {
+            const percent = Math.round((projectedSpend / config.threshold) * 100);
+            return this.createAlert(rule, tx, {
+                message: `Budget ${percent}% utilized: $${projectedSpend.toFixed(2)} of $${config.threshold} ${config.currency} limit`,
+                data: {
+                    currentSpend,
+                    projectedSpend,
+                    threshold: config.threshold,
+                    percentUsed: percent,
+                },
+            });
+        }
+        return null;
+    }
+    checkLargeTransaction(rule, tx, config) {
+        if (tx.currency !== config.currency)
+            return null;
+        if (tx.amount < config.threshold)
+            return null;
+        return this.createAlert(rule, tx, {
+            message: `Large transaction detected: $${tx.amount} ${tx.currency} to ${tx.recipient}`,
+            data: {
+                amount: tx.amount,
+                threshold: config.threshold,
+                recipient: tx.recipient,
+            },
+        });
+    }
+    checkRateSpike(rule, tx, config) {
+        if (config.agentId && tx.agentId !== config.agentId)
+            return null;
+        const windowStart = new Date(Date.now() - config.windowMs).toISOString();
+        const recentTxs = this.tracker.query({
+            agentId: config.agentId,
+            after: windowStart,
+        });
+        // +1 for the current transaction being evaluated
+        const txCount = recentTxs.length + 1;
+        if (txCount > config.maxTransactions) {
+            return this.createAlert(rule, tx, {
+                message: `Transaction rate spike: ${txCount} transactions in ${config.windowMs / 1000}s window (limit: ${config.maxTransactions})`,
+                data: {
+                    transactionCount: txCount,
+                    maxTransactions: config.maxTransactions,
+                    windowMs: config.windowMs,
+                },
+            });
+        }
+        return null;
+    }
+    checkNewRecipient(rule, tx, config) {
+        if (config.agentId && tx.agentId !== config.agentId)
+            return null;
+        const agentKey = config.agentId ?? '__all__';
+        let known = this.knownRecipients.get(agentKey);
+        if (!known) {
+            // Initialize from existing transactions
+            known = new Set();
+            const existingTxs = config.agentId
+                ? this.tracker.getByAgent(config.agentId)
+                : this.tracker.query({});
+            for (const existingTx of existingTxs) {
+                known.add(existingTx.recipient);
+            }
+            this.knownRecipients.set(agentKey, known);
+        }
+        if (!known.has(tx.recipient)) {
+            known.add(tx.recipient);
+            return this.createAlert(rule, tx, {
+                message: `New recipient detected: ${tx.recipient} (agent: ${tx.agentId})`,
+                data: {
+                    recipient: tx.recipient,
+                    agentId: tx.agentId,
+                    knownRecipientCount: known.size,
+                },
+            });
+        }
+        return null;
+    }
+    checkAnomaly(rule, tx, config) {
+        if (config.agentId && tx.agentId !== config.agentId)
+            return null;
+        const historicalTxs = config.agentId
+            ? this.tracker.getByAgent(config.agentId)
+            : this.tracker.query({});
+        const completedAmounts = historicalTxs
+            .filter((t) => t.status === 'completed' && t.currency === tx.currency)
+            .map((t) => t.amount);
+        if (completedAmounts.length < config.minSampleSize)
+            return null;
+        const mean = completedAmounts.reduce((s, a) => s + a, 0) / completedAmounts.length;
+        const variance = completedAmounts.reduce((s, a) => s + Math.pow(a - mean, 2), 0) / completedAmounts.length;
+        const stdDev = Math.sqrt(variance);
+        if (stdDev === 0)
+            return null;
+        const zScore = (tx.amount - mean) / stdDev;
+        if (zScore > config.stdDevThreshold) {
+            return this.createAlert(rule, tx, {
+                message: `Anomalous transaction amount: $${tx.amount} ${tx.currency} (${zScore.toFixed(1)} standard deviations above mean of $${mean.toFixed(2)})`,
+                data: {
+                    amount: tx.amount,
+                    mean: Math.round(mean * 100) / 100,
+                    stdDev: Math.round(stdDev * 100) / 100,
+                    zScore: Math.round(zScore * 100) / 100,
+                    sampleSize: completedAmounts.length,
+                },
+            });
+        }
+        return null;
+    }
+    // ---------------------------------------------------------------------------
+    // Alert factory
+    // ---------------------------------------------------------------------------
+    createAlert(rule, tx, overrides) {
+        return {
+            type: rule.type,
+            severity: rule.severity,
+            message: overrides.message,
+            timestamp: new Date().toISOString(),
+            agentId: tx.agentId,
+            transactionId: tx.id,
+            data: {
+                ...overrides.data,
+                ruleId: rule.id,
+                ruleName: rule.name,
+            },
+        };
+    }
+}
+//# sourceMappingURL=alerts.js.map

package/dist/alerts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"alerts.js","sourceRoot":"","sources":["../src/alerts.ts"],"names":[],"mappings":"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"}

package/dist/analytics.d.ts

@@ -0,0 +1,91 @@
+import type { AgentTransaction, AgentId, TimeWindow } from '@paysentry/core';
+import type { SpendTracker } from './tracker.js';
+/** Aggregated spend summary for a single entity */
+export interface SpendSummary {
+    /** Total amount spent */
+    readonly totalAmount: number;
+    /** Number of transactions */
+    readonly transactionCount: number;
+    /** Average transaction amount */
+    readonly averageAmount: number;
+    /** Largest single transaction */
+    readonly maxAmount: number;
+    /** Smallest single transaction */
+    readonly minAmount: number;
+    /** Currency (summaries are per-currency) */
+    readonly currency: string;
+}
+/** Spend breakdown by time period */
+export interface TimeSeriesPoint {
+    /** ISO 8601 period start */
+    readonly periodStart: string;
+    /** ISO 8601 period end */
+    readonly periodEnd: string;
+    /** Total spend in this period */
+    readonly totalAmount: number;
+    /** Number of transactions */
+    readonly transactionCount: number;
+}
+/** Complete analytics snapshot for an agent */
+export interface AgentAnalytics {
+    /** Agent identifier */
+    readonly agentId: AgentId;
+    /** Spend by currency */
+    readonly spendByCurrency: ReadonlyMap<string, SpendSummary>;
+    /** Spend by service */
+    readonly spendByService: ReadonlyMap<string, SpendSummary>;
+    /** Spend by protocol */
+    readonly spendByProtocol: ReadonlyMap<string, SpendSummary>;
+    /** Top recipients by total spend */
+    readonly topRecipients: readonly {
+        recipient: string;
+        totalAmount: number;
+        count: number;
+    }[];
+    /** Time series data */
+    readonly timeSeries: readonly TimeSeriesPoint[];
+}
+/**
+ * SpendAnalytics provides computed insights from raw transaction data.
+ * It reads from a SpendTracker and produces aggregated analytics.
+ *
+ * @example
+ * ```ts
+ * const analytics = new SpendAnalytics(tracker);
+ * const agentReport = analytics.getAgentAnalytics('agent-1' as AgentId, 'daily');
+ * console.log(agentReport.spendByCurrency);
+ * ```
+ */
+export declare class SpendAnalytics {
+    private readonly tracker;
+    constructor(tracker: SpendTracker);
+    /**
+     * Compute a spend summary from a set of transactions.
+     */
+    summarize(transactions: readonly AgentTransaction[], currency: string): SpendSummary;
+    /**
+     * Get comprehensive analytics for a specific agent.
+     *
+     * @param agentId - Agent to analyze
+     * @param timeWindow - Granularity for time series data
+     * @param since - Only consider transactions after this ISO 8601 timestamp
+     */
+    getAgentAnalytics(agentId: AgentId, timeWindow?: TimeWindow, since?: string): AgentAnalytics;
+    /**
+     * Get the total spend across all agents within a time range.
+     */
+    getTotalSpend(currency: string, since?: string, until?: string): SpendSummary;
+    /**
+     * Get a leaderboard of agents by total spend.
+     */
+    getAgentLeaderboard(currency: string, limit?: number): {
+        agentId: AgentId;
+        totalAmount: number;
+        count: number;
+    }[];
+    private groupBy;
+    private buildTimeSeries;
+    private getPeriodKey;
+    private getNextPeriod;
+}
+//# sourceMappingURL=analytics.d.ts.map

package/dist/analytics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"analytics.d.ts","sourceRoot":"","sources":["../src/analytics.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EACV,gBAAgB,EAChB,OAAO,EAGP,UAAU,EACX,MAAM,iBAAiB,CAAC;AACzB,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAEjD,mDAAmD;AACnD,MAAM,WAAW,YAAY;IAC3B,yBAAyB;IACzB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAE7B,6BAA6B;IAC7B,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAElC,iCAAiC;IACjC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAE/B,iCAAiC;IACjC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAE3B,kCAAkC;IAClC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAE3B,4CAA4C;IAC5C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED,qCAAqC;AACrC,MAAM,WAAW,eAAe;IAC9B,4BAA4B;IAC5B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAE7B,0BAA0B;IAC1B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAE3B,iCAAiC;IACjC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAE7B,6BAA6B;IAC7B,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;CACnC;AAED,+CAA+C;AAC/C,MAAM,WAAW,cAAc;IAC7B,uBAAuB;IACvB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAE1B,wBAAwB;IACxB,QAAQ,CAAC,eAAe,EAAE,WAAW,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;IAE5D,uBAAuB;IACvB,QAAQ,CAAC,cAAc,EAAE,WAAW,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;IAE3D,wBAAwB;IACxB,QAAQ,CAAC,eAAe,EAAE,WAAW,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;IAE5D,oCAAoC;IACpC,QAAQ,CAAC,aAAa,EAAE,SAAS;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IAE7F,uBAAuB;IACvB,QAAQ,CAAC,UAAU,EAAE,SAAS,eAAe,EAAE,CAAC;CACjD;AAED;;;;;;;;;;GAUG;AACH,qBAAa,cAAc;IACb,OAAO,CAAC,QAAQ,CAAC,OAAO;gBAAP,OAAO,EAAE,YAAY;IAElD;;OAEG;IACH,SAAS,CAAC,YAAY,EAAE,SAAS,gBAAgB,EAAE,EAAE,QAAQ,EAAE,MAAM,GAAG,YAAY;IA2BpF;;;;;;OAMG;IACH,iBAAiB,CACf,OAAO,EAAE,OAAO,EAChB,UAAU,GAAE,UAAoB,EAChC,KAAK,CAAC,EAAE,MAAM,GACb,cAAc;IA6DjB;;OAEG;IACH,aAAa,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,YAAY;IAU7E;;OAEG;IACH,mBAAmB,CACjB,QAAQ,EAAE,MAAM,EAChB,KAAK,GAAE,MAAW,GACjB;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,WAAW,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,EAAE;IAuB7D,OAAO,CAAC,OAAO;IAcf,OAAO,CAAC,eAAe;IA6BvB,OAAO,CAAC,YAAY;IAqBpB,OAAO,CAAC,aAAa;CAoBtB"}

package/dist/analytics.js

@@ -0,0 +1,216 @@
+// =============================================================================
+// SpendAnalytics — Per-agent, per-service, per-time breakdowns
+// Turns raw transaction data into actionable spending intelligence
+// =============================================================================
+/**
+ * SpendAnalytics provides computed insights from raw transaction data.
+ * It reads from a SpendTracker and produces aggregated analytics.
+ *
+ * @example
+ * ```ts
+ * const analytics = new SpendAnalytics(tracker);
+ * const agentReport = analytics.getAgentAnalytics('agent-1' as AgentId, 'daily');
+ * console.log(agentReport.spendByCurrency);
+ * ```
+ */
+export class SpendAnalytics {
+    tracker;
+    constructor(tracker) {
+        this.tracker = tracker;
+    }
+    /**
+     * Compute a spend summary from a set of transactions.
+     */
+    summarize(transactions, currency) {
+        const filtered = transactions.filter((tx) => tx.currency === currency && tx.status === 'completed');
+        if (filtered.length === 0) {
+            return {
+                totalAmount: 0,
+                transactionCount: 0,
+                averageAmount: 0,
+                maxAmount: 0,
+                minAmount: 0,
+                currency,
+            };
+        }
+        const amounts = filtered.map((tx) => tx.amount);
+        const total = amounts.reduce((sum, a) => sum + a, 0);
+        return {
+            totalAmount: Math.round(total * 1e6) / 1e6,
+            transactionCount: filtered.length,
+            averageAmount: Math.round((total / filtered.length) * 1e6) / 1e6,
+            maxAmount: Math.max(...amounts),
+            minAmount: Math.min(...amounts),
+            currency,
+        };
+    }
+    /**
+     * Get comprehensive analytics for a specific agent.
+     *
+     * @param agentId - Agent to analyze
+     * @param timeWindow - Granularity for time series data
+     * @param since - Only consider transactions after this ISO 8601 timestamp
+     */
+    getAgentAnalytics(agentId, timeWindow = 'daily', since) {
+        let transactions = this.tracker.getByAgent(agentId);
+        if (since) {
+            transactions = transactions.filter((tx) => tx.createdAt >= since);
+        }
+        // Spend by currency
+        const currencies = new Set(transactions.map((tx) => tx.currency));
+        const spendByCurrency = new Map();
+        for (const currency of currencies) {
+            spendByCurrency.set(currency, this.summarize(transactions, currency));
+        }
+        // Spend by service
+        const spendByService = new Map();
+        const serviceGroups = this.groupBy(transactions, (tx) => tx.service ?? 'unknown');
+        for (const [service, txs] of serviceGroups) {
+            const currencies2 = new Set(txs.map((tx) => tx.currency));
+            for (const currency of currencies2) {
+                const key = `${service}:${currency}`;
+                spendByService.set(key, this.summarize(txs, currency));
+            }
+        }
+        // Spend by protocol
+        const spendByProtocol = new Map();
+        const protocolGroups = this.groupBy(transactions, (tx) => tx.protocol);
+        for (const [protocol, txs] of protocolGroups) {
+            const currencies2 = new Set(txs.map((tx) => tx.currency));
+            for (const currency of currencies2) {
+                spendByProtocol.set(`${protocol}:${currency}`, this.summarize(txs, currency));
+            }
+        }
+        // Top recipients
+        const recipientMap = new Map();
+        for (const tx of transactions.filter((t) => t.status === 'completed')) {
+            const entry = recipientMap.get(tx.recipient) ?? { totalAmount: 0, count: 0 };
+            entry.totalAmount += tx.amount;
+            entry.count++;
+            recipientMap.set(tx.recipient, entry);
+        }
+        const topRecipients = [...recipientMap.entries()]
+            .map(([recipient, data]) => ({ recipient, ...data }))
+            .sort((a, b) => b.totalAmount - a.totalAmount)
+            .slice(0, 10);
+        // Time series
+        const timeSeries = this.buildTimeSeries(transactions, timeWindow);
+        return {
+            agentId,
+            spendByCurrency,
+            spendByService,
+            spendByProtocol,
+            topRecipients,
+            timeSeries,
+        };
+    }
+    /**
+     * Get the total spend across all agents within a time range.
+     */
+    getTotalSpend(currency, since, until) {
+        const all = this.tracker.query({
+            currency,
+            status: 'completed',
+            after: since,
+            before: until,
+        });
+        return this.summarize(all, currency);
+    }
+    /**
+     * Get a leaderboard of agents by total spend.
+     */
+    getAgentLeaderboard(currency, limit = 10) {
+        const agentMap = new Map();
+        for (const agentId of this.tracker.agents) {
+            const txs = this.tracker.getByAgent(agentId).filter((tx) => tx.currency === currency && tx.status === 'completed');
+            if (txs.length > 0) {
+                const total = txs.reduce((sum, tx) => sum + tx.amount, 0);
+                agentMap.set(agentId, { totalAmount: total, count: txs.length });
+            }
+        }
+        return [...agentMap.entries()]
+            .map(([agentId, data]) => ({ agentId: agentId, ...data }))
+            .sort((a, b) => b.totalAmount - a.totalAmount)
+            .slice(0, limit);
+    }
+    // ---------------------------------------------------------------------------
+    // Private helpers
+    // ---------------------------------------------------------------------------
+    groupBy(items, keyFn) {
+        const groups = new Map();
+        for (const item of items) {
+            const key = keyFn(item);
+            let group = groups.get(key);
+            if (!group) {
+                group = [];
+                groups.set(key, group);
+            }
+            group.push(item);
+        }
+        return groups;
+    }
+    buildTimeSeries(transactions, window) {
+        if (transactions.length === 0)
+            return [];
+        const completed = transactions.filter((tx) => tx.status === 'completed');
+        if (completed.length === 0)
+            return [];
+        const buckets = new Map();
+        for (const tx of completed) {
+            const key = this.getPeriodKey(tx.createdAt, window);
+            const bucket = buckets.get(key) ?? { total: 0, count: 0 };
+            bucket.total += tx.amount;
+            bucket.count++;
+            buckets.set(key, bucket);
+        }
+        return [...buckets.entries()]
+            .sort(([a], [b]) => a.localeCompare(b))
+            .map(([key, data]) => ({
+            periodStart: key,
+            periodEnd: this.getNextPeriod(key, window),
+            totalAmount: Math.round(data.total * 1e6) / 1e6,
+            transactionCount: data.count,
+        }));
+    }
+    getPeriodKey(isoDate, window) {
+        const date = new Date(isoDate);
+        switch (window) {
+            case 'per_transaction':
+                return isoDate;
+            case 'hourly':
+                return date.toISOString().slice(0, 13) + ':00:00.000Z';
+            case 'daily':
+                return date.toISOString().slice(0, 10) + 'T00:00:00.000Z';
+            case 'weekly': {
+                const day = date.getDay();
+                const mondayOffset = day === 0 ? -6 : 1 - day;
+                const monday = new Date(date);
+                monday.setDate(date.getDate() + mondayOffset);
+                return monday.toISOString().slice(0, 10) + 'T00:00:00.000Z';
+            }
+            case 'monthly':
+                return date.toISOString().slice(0, 7) + '-01T00:00:00.000Z';
+        }
+    }
+    getNextPeriod(periodStart, window) {
+        const date = new Date(periodStart);
+        switch (window) {
+            case 'per_transaction':
+                return periodStart;
+            case 'hourly':
+                date.setHours(date.getHours() + 1);
+                break;
+            case 'daily':
+                date.setDate(date.getDate() + 1);
+                break;
+            case 'weekly':
+                date.setDate(date.getDate() + 7);
+                break;
+            case 'monthly':
+                date.setMonth(date.getMonth() + 1);
+                break;
+        }
+        return date.toISOString();
+    }
+}
+//# sourceMappingURL=analytics.js.map

package/dist/analytics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"analytics.js","sourceRoot":"","sources":["../src/analytics.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export { SpendTracker } from './tracker.js';
+export type { TransactionFilter } from './tracker.js';
+export { SpendAnalytics } from './analytics.js';
+export type { SpendSummary, TimeSeriesPoint, AgentAnalytics } from './analytics.js';
+export { SpendAlerts } from './alerts.js';
+export type { AlertRule, AlertRuleConfig, BudgetThresholdConfig, LargeTransactionConfig, RateSpikeConfig, NewRecipientConfig, AnomalyConfig, } from './alerts.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAC5C,YAAY,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAEtD,OAAO,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAChD,YAAY,EAAE,YAAY,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAEpF,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,YAAY,EACV,SAAS,EACT,eAAe,EACf,qBAAqB,EACrB,sBAAsB,EACtB,eAAe,EACf,kBAAkB,EAClB,aAAa,GACd,MAAM,aAAa,CAAC"}

package/dist/index.js

@@ -0,0 +1,8 @@
+// =============================================================================
+// @paysentry/observe — Public API
+// Payment observability for AI agents
+// =============================================================================
+export { SpendTracker } from './tracker.js';
+export { SpendAnalytics } from './analytics.js';
+export { SpendAlerts } from './alerts.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,gFAAgF;AAChF,kCAAkC;AAClC,sCAAsC;AACtC,gFAAgF;AAEhF,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAG5C,OAAO,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAGhD,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC"}

package/dist/tracker.d.ts

@@ -0,0 +1,97 @@
+import type { AgentTransaction, AgentId, TransactionId, TransactionStatus, ServiceId, PaymentProtocol, Logger } from '@paysentry/core';
+/** Filter criteria for querying transactions */
+export interface TransactionFilter {
+    /** Filter by agent ID */
+    readonly agentId?: AgentId;
+    /** Filter by recipient (exact match) */
+    readonly recipient?: string;
+    /** Filter by service */
+    readonly service?: ServiceId;
+    /** Filter by protocol */
+    readonly protocol?: PaymentProtocol;
+    /** Filter by status */
+    readonly status?: TransactionStatus;
+    /** Filter by currency */
+    readonly currency?: string;
+    /** Minimum amount (inclusive) */
+    readonly minAmount?: number;
+    /** Maximum amount (inclusive) */
+    readonly maxAmount?: number;
+    /** ISO 8601 — transactions created after this time */
+    readonly after?: string;
+    /** ISO 8601 — transactions created before this time */
+    readonly before?: string;
+    /** Maximum number of results */
+    readonly limit?: number;
+}
+/**
+ * SpendTracker records, stores, and queries agent transactions.
+ * It maintains in-memory indices for fast lookups by agent, service,
+ * and time range.
+ *
+ * @example
+ * ```ts
+ * const tracker = new SpendTracker();
+ * tracker.record(transaction);
+ *
+ * const agentTxs = tracker.getByAgent('agent-1' as AgentId);
+ * const recentTxs = tracker.query({ after: '2026-01-01T00:00:00Z', limit: 50 });
+ * ```
+ */
+export declare class SpendTracker {
+    /** Primary storage: id -> transaction */
+    private readonly transactions;
+    /** Index: agentId -> set of transaction IDs */
+    private readonly byAgent;
+    /** Index: service -> set of transaction IDs */
+    private readonly byService;
+    /** Index: recipient -> set of transaction IDs */
+    private readonly byRecipient;
+    /** Chronologically ordered transaction IDs */
+    private readonly chronological;
+    private readonly logger?;
+    constructor(options?: {
+        logger?: Logger;
+    });
+    /**
+     * Record a transaction. If a transaction with the same ID already exists,
+     * it will be updated (useful for status changes).
+     */
+    record(tx: AgentTransaction): void;
+    /**
+     * Get a single transaction by ID.
+     */
+    get(id: TransactionId): AgentTransaction | undefined;
+    /**
+     * Get all transactions for a specific agent, newest first.
+     */
+    getByAgent(agentId: AgentId): AgentTransaction[];
+    /**
+     * Get all transactions for a specific service, newest first.
+     */
+    getByService(serviceId: ServiceId): AgentTransaction[];
+    /**
+     * Get all transactions for a specific recipient, newest first.
+     */
+    getByRecipient(recipient: string): AgentTransaction[];
+    /**
+     * Query transactions with flexible filtering.
+     * Results are returned newest first.
+     */
+    query(filter: TransactionFilter): AgentTransaction[];
+    /**
+     * Get the total number of recorded transactions.
+     */
+    get size(): number;
+    /**
+     * Get all unique agent IDs that have transactions.
+     */
+    get agents(): AgentId[];
+    /**
+     * Get all unique recipients that have received payments.
+     */
+    get recipients(): string[];
+    private addToIndex;
+    private resolveIds;
+}
+//# sourceMappingURL=tracker.d.ts.map

package/dist/tracker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tracker.d.ts","sourceRoot":"","sources":["../src/tracker.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EACV,gBAAgB,EAChB,OAAO,EACP,aAAa,EACb,iBAAiB,EACjB,SAAS,EACT,eAAe,EACf,MAAM,EACP,MAAM,iBAAiB,CAAC;AAEzB,gDAAgD;AAChD,MAAM,WAAW,iBAAiB;IAChC,yBAAyB;IACzB,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAE3B,wCAAwC;IACxC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAE5B,wBAAwB;IACxB,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,CAAC;IAE7B,yBAAyB;IACzB,QAAQ,CAAC,QAAQ,CAAC,EAAE,eAAe,CAAC;IAEpC,uBAAuB;IACvB,QAAQ,CAAC,MAAM,CAAC,EAAE,iBAAiB,CAAC;IAEpC,yBAAyB;IACzB,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAE3B,iCAAiC;IACjC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAE5B,iCAAiC;IACjC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAE5B,sDAAsD;IACtD,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAExB,uDAAuD;IACvD,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IAEzB,gCAAgC;IAChC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;;;;;;;;GAaG;AACH,qBAAa,YAAY;IACvB,yCAAyC;IACzC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAmD;IAEhF,+CAA+C;IAC/C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA8C;IAEtE,+CAA+C;IAC/C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA8C;IAExE,iDAAiD;IACjD,OAAO,CAAC,QAAQ,CAAC,WAAW,CAA8C;IAE1E,8CAA8C;IAC9C,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAuB;IAErD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAS;gBAErB,OAAO,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE;IAIzC;;;OAGG;IACH,MAAM,CAAC,EAAE,EAAE,gBAAgB,GAAG,IAAI;IAyBlC;;OAEG;IACH,GAAG,CAAC,EAAE,EAAE,aAAa,GAAG,gBAAgB,GAAG,SAAS;IAIpD;;OAEG;IACH,UAAU,CAAC,OAAO,EAAE,OAAO,GAAG,gBAAgB,EAAE;IAMhD;;OAEG;IACH,YAAY,CAAC,SAAS,EAAE,SAAS,GAAG,gBAAgB,EAAE;IAMtD;;OAEG;IACH,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,gBAAgB,EAAE;IAMrD;;;OAGG;IACH,KAAK,CAAC,MAAM,EAAE,iBAAiB,GAAG,gBAAgB,EAAE;IAwCpD;;OAEG;IACH,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED;;OAEG;IACH,IAAI,MAAM,IAAI,OAAO,EAAE,CAEtB;IAED;;OAEG;IACH,IAAI,UAAU,IAAI,MAAM,EAAE,CAEzB;IAMD,OAAO,CAAC,UAAU;IASlB,OAAO,CAAC,UAAU;CAQnB"}

package/dist/tracker.js

@@ -0,0 +1,185 @@
+// =============================================================================
+// SpendTracker — Records and indexes all agent transactions
+// The foundation of the Observe pillar. Every transaction goes through here.
+// =============================================================================
+/**
+ * SpendTracker records, stores, and queries agent transactions.
+ * It maintains in-memory indices for fast lookups by agent, service,
+ * and time range.
+ *
+ * @example
+ * ```ts
+ * const tracker = new SpendTracker();
+ * tracker.record(transaction);
+ *
+ * const agentTxs = tracker.getByAgent('agent-1' as AgentId);
+ * const recentTxs = tracker.query({ after: '2026-01-01T00:00:00Z', limit: 50 });
+ * ```
+ */
+export class SpendTracker {
+    /** Primary storage: id -> transaction */
+    transactions = new Map();
+    /** Index: agentId -> set of transaction IDs */
+    byAgent = new Map();
+    /** Index: service -> set of transaction IDs */
+    byService = new Map();
+    /** Index: recipient -> set of transaction IDs */
+    byRecipient = new Map();
+    /** Chronologically ordered transaction IDs */
+    chronological = [];
+    logger;
+    constructor(options) {
+        this.logger = options?.logger;
+    }
+    /**
+     * Record a transaction. If a transaction with the same ID already exists,
+     * it will be updated (useful for status changes).
+     */
+    record(tx) {
+        const isUpdate = this.transactions.has(tx.id);
+        this.transactions.set(tx.id, tx);
+        if (!isUpdate) {
+            // Index on first insert only
+            this.addToIndex(this.byAgent, tx.agentId, tx.id);
+            this.addToIndex(this.byRecipient, tx.recipient, tx.id);
+            if (tx.service) {
+                this.addToIndex(this.byService, tx.service, tx.id);
+            }
+            this.chronological.push(tx.id);
+            this.logger?.info(`[SpendTracker] Recorded transaction ${tx.id}`, {
+                agent: tx.agentId,
+                amount: tx.amount,
+                currency: tx.currency,
+            });
+        }
+        else {
+            this.logger?.info(`[SpendTracker] Updated transaction ${tx.id}`, {
+                status: tx.status,
+            });
+        }
+    }
+    /**
+     * Get a single transaction by ID.
+     */
+    get(id) {
+        return this.transactions.get(id);
+    }
+    /**
+     * Get all transactions for a specific agent, newest first.
+     */
+    getByAgent(agentId) {
+        const ids = this.byAgent.get(agentId);
+        if (!ids)
+            return [];
+        return this.resolveIds(ids).reverse();
+    }
+    /**
+     * Get all transactions for a specific service, newest first.
+     */
+    getByService(serviceId) {
+        const ids = this.byService.get(serviceId);
+        if (!ids)
+            return [];
+        return this.resolveIds(ids).reverse();
+    }
+    /**
+     * Get all transactions for a specific recipient, newest first.
+     */
+    getByRecipient(recipient) {
+        const ids = this.byRecipient.get(recipient);
+        if (!ids)
+            return [];
+        return this.resolveIds(ids).reverse();
+    }
+    /**
+     * Query transactions with flexible filtering.
+     * Results are returned newest first.
+     */
+    query(filter) {
+        let results;
+        // Start with the most selective index
+        if (filter.agentId) {
+            results = this.getByAgent(filter.agentId);
+        }
+        else if (filter.service) {
+            results = this.getByService(filter.service);
+        }
+        else if (filter.recipient) {
+            results = this.getByRecipient(filter.recipient);
+        }
+        else {
+            // Full scan in reverse chronological order
+            results = [...this.chronological]
+                .reverse()
+                .map((id) => this.transactions.get(id))
+                .filter((tx) => tx !== undefined);
+        }
+        // Apply additional filters
+        results = results.filter((tx) => {
+            if (filter.agentId && tx.agentId !== filter.agentId)
+                return false;
+            if (filter.recipient && tx.recipient !== filter.recipient)
+                return false;
+            if (filter.service && tx.service !== filter.service)
+                return false;
+            if (filter.protocol && tx.protocol !== filter.protocol)
+                return false;
+            if (filter.status && tx.status !== filter.status)
+                return false;
+            if (filter.currency && tx.currency !== filter.currency)
+                return false;
+            if (filter.minAmount !== undefined && tx.amount < filter.minAmount)
+                return false;
+            if (filter.maxAmount !== undefined && tx.amount > filter.maxAmount)
+                return false;
+            if (filter.after && tx.createdAt < filter.after)
+                return false;
+            if (filter.before && tx.createdAt > filter.before)
+                return false;
+            return true;
+        });
+        if (filter.limit && results.length > filter.limit) {
+            results = results.slice(0, filter.limit);
+        }
+        return results;
+    }
+    /**
+     * Get the total number of recorded transactions.
+     */
+    get size() {
+        return this.transactions.size;
+    }
+    /**
+     * Get all unique agent IDs that have transactions.
+     */
+    get agents() {
+        return [...this.byAgent.keys()];
+    }
+    /**
+     * Get all unique recipients that have received payments.
+     */
+    get recipients() {
+        return [...this.byRecipient.keys()];
+    }
+    // ---------------------------------------------------------------------------
+    // Private helpers
+    // ---------------------------------------------------------------------------
+    addToIndex(index, key, txId) {
+        let set = index.get(key);
+        if (!set) {
+            set = new Set();
+            index.set(key, set);
+        }
+        set.add(txId);
+    }
+    resolveIds(ids) {
+        const results = [];
+        for (const id of ids) {
+            const tx = this.transactions.get(id);
+            if (tx)
+                results.push(tx);
+        }
+        return results;
+    }
+}
+//# sourceMappingURL=tracker.js.map

package/dist/tracker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tracker.js","sourceRoot":"","sources":["../src/tracker.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@paysentry/observe",
+  "version": "1.0.0",
+  "description": "Payment observability for AI agents — track what agents spend, where, and why",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "clean": "tsc --build --clean"
+  },
+  "dependencies": {
+    "@paysentry/core": "1.0.0"
+  },
+  "license": "MIT",
+  "files": ["dist"],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/paysentry/paysentry",
+    "directory": "packages/observe"
+  }
+}