@paysentry/protect 1.0.0

package/dist/disputes.d.ts

@@ -0,0 +1,138 @@
+import type { DisputeCase, DisputeEvidence, DisputeId, DisputeStatus, TransactionId, AgentId, LiabilityAttribution, Logger } from '@paysentry/core';
+import type { TransactionProvenance } from './provenance.js';
+/** Options for filing a new dispute */
+export interface FileDisputeInput {
+    /** Transaction being disputed */
+    readonly transactionId: TransactionId;
+    /** Agent filing the dispute */
+    readonly agentId: AgentId;
+    /** Reason for the dispute */
+    readonly reason: string;
+    /** Amount requested for refund */
+    readonly requestedAmount: number;
+    /** Initial evidence (optional) */
+    readonly evidence?: DisputeEvidence[];
+}
+/** Filter for querying disputes */
+export interface DisputeFilter {
+    /** Filter by status */
+    readonly status?: DisputeStatus;
+    /** Filter by agent */
+    readonly agentId?: AgentId;
+    /** Filter by transaction */
+    readonly transactionId?: TransactionId;
+    /** Filter by liability */
+    readonly liability?: LiabilityAttribution;
+    /** Maximum results */
+    readonly limit?: number;
+}
+/** Callback for dispute status changes */
+export type DisputeListener = (dispute: DisputeCase, previousStatus: DisputeStatus) => void | Promise<void>;
+/**
+ * DisputeManager handles the full lifecycle of payment disputes:
+ * filing, investigation, evidence collection, liability attribution,
+ * and resolution.
+ *
+ * It integrates with TransactionProvenance to automatically pull
+ * the transaction's audit trail as evidence.
+ *
+ * @example
+ * ```ts
+ * const disputes = new DisputeManager({ provenance });
+ *
+ * // File a dispute
+ * const dispute = disputes.file({
+ *   transactionId: tx.id,
+ *   agentId: tx.agentId,
+ *   reason: 'Service not delivered after payment',
+ *   requestedAmount: tx.amount,
+ * });
+ *
+ * // Add evidence
+ * disputes.addEvidence(dispute.id, {
+ *   type: 'user_statement',
+ *   description: 'Agent completed payment but received 404 from service',
+ *   data: { httpStatus: 404, url: 'https://api.service.com/resource' },
+ *   addedAt: new Date().toISOString(),
+ * });
+ *
+ * // Resolve
+ * disputes.resolve(dispute.id, {
+ *   status: 'resolved_refunded',
+ *   liability: 'service_provider',
+ *   resolvedAmount: tx.amount,
+ * });
+ * ```
+ */
+export declare class DisputeManager {
+    /** All disputes, keyed by dispute ID */
+    private readonly disputes;
+    /** Index: transactionId -> disputeId */
+    private readonly byTransaction;
+    /** Index: agentId -> set of dispute IDs */
+    private readonly byAgent;
+    /** Status change listeners */
+    private readonly listeners;
+    private readonly provenance?;
+    private readonly logger?;
+    constructor(options?: {
+        provenance?: TransactionProvenance;
+        logger?: Logger;
+    });
+    /**
+     * File a new dispute case.
+     * Automatically pulls provenance records as initial evidence if available.
+     */
+    file(input: FileDisputeInput): DisputeCase;
+    /**
+     * Add evidence to an existing dispute.
+     */
+    addEvidence(disputeId: DisputeId, evidence: DisputeEvidence): void;
+    /**
+     * Update the status of a dispute (e.g., open -> investigating).
+     */
+    updateStatus(disputeId: DisputeId, newStatus: DisputeStatus): void;
+    /**
+     * Resolve a dispute with a final determination.
+     */
+    resolve(disputeId: DisputeId, resolution: {
+        status: 'resolved_refunded' | 'resolved_denied' | 'resolved_partial';
+        liability: LiabilityAttribution;
+        resolvedAmount?: number;
+    }): DisputeCase;
+    /**
+     * Get a dispute by ID.
+     */
+    get(disputeId: DisputeId): DisputeCase | undefined;
+    /**
+     * Get the dispute associated with a transaction.
+     */
+    getByTransaction(txId: TransactionId): DisputeCase | undefined;
+    /**
+     * Get all disputes for an agent.
+     */
+    getByAgent(agentId: AgentId): DisputeCase[];
+    /**
+     * Query disputes with filtering.
+     */
+    query(filter: DisputeFilter): DisputeCase[];
+    /**
+     * Register a listener for dispute status changes.
+     */
+    onStatusChange(listener: DisputeListener): void;
+    /**
+     * Get summary statistics for disputes.
+     */
+    getStats(): {
+        total: number;
+        open: number;
+        investigating: number;
+        resolved: number;
+        escalated: number;
+        totalRequestedAmount: number;
+        totalResolvedAmount: number;
+    };
+    private isClosed;
+    private notifyListeners;
+}
+//# sourceMappingURL=disputes.d.ts.map

package/dist/disputes.d.ts.map

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

package/dist/disputes.js

@@ -0,0 +1,282 @@
+// =============================================================================
+// DisputeManager — Open, track, and resolve payment disputes
+// Central registry for all dispute cases with lifecycle management
+// =============================================================================
+import { generateDisputeId } from '@paysentry/core';
+/**
+ * DisputeManager handles the full lifecycle of payment disputes:
+ * filing, investigation, evidence collection, liability attribution,
+ * and resolution.
+ *
+ * It integrates with TransactionProvenance to automatically pull
+ * the transaction's audit trail as evidence.
+ *
+ * @example
+ * ```ts
+ * const disputes = new DisputeManager({ provenance });
+ *
+ * // File a dispute
+ * const dispute = disputes.file({
+ *   transactionId: tx.id,
+ *   agentId: tx.agentId,
+ *   reason: 'Service not delivered after payment',
+ *   requestedAmount: tx.amount,
+ * });
+ *
+ * // Add evidence
+ * disputes.addEvidence(dispute.id, {
+ *   type: 'user_statement',
+ *   description: 'Agent completed payment but received 404 from service',
+ *   data: { httpStatus: 404, url: 'https://api.service.com/resource' },
+ *   addedAt: new Date().toISOString(),
+ * });
+ *
+ * // Resolve
+ * disputes.resolve(dispute.id, {
+ *   status: 'resolved_refunded',
+ *   liability: 'service_provider',
+ *   resolvedAmount: tx.amount,
+ * });
+ * ```
+ */
+export class DisputeManager {
+    /** All disputes, keyed by dispute ID */
+    disputes = new Map();
+    /** Index: transactionId -> disputeId */
+    byTransaction = new Map();
+    /** Index: agentId -> set of dispute IDs */
+    byAgent = new Map();
+    /** Status change listeners */
+    listeners = [];
+    provenance;
+    logger;
+    constructor(options) {
+        this.provenance = options?.provenance;
+        this.logger = options?.logger;
+    }
+    /**
+     * File a new dispute case.
+     * Automatically pulls provenance records as initial evidence if available.
+     */
+    file(input) {
+        // Check if dispute already exists for this transaction
+        const existing = this.byTransaction.get(input.transactionId);
+        if (existing) {
+            const existingCase = this.disputes.get(existing);
+            if (existingCase && !this.isClosed(existingCase.status)) {
+                throw new Error(`Active dispute ${existing} already exists for transaction ${input.transactionId}`);
+            }
+        }
+        const now = new Date().toISOString();
+        const evidence = [];
+        // Pull provenance records as evidence
+        if (this.provenance) {
+            const chain = this.provenance.getChain(input.transactionId);
+            if (chain.length > 0) {
+                evidence.push({
+                    type: 'transaction_log',
+                    description: `Transaction provenance chain (${chain.length} records)`,
+                    data: chain,
+                    addedAt: now,
+                });
+            }
+        }
+        // Add user-provided evidence
+        if (input.evidence) {
+            evidence.push(...input.evidence);
+        }
+        const dispute = {
+            id: generateDisputeId(),
+            transactionId: input.transactionId,
+            agentId: input.agentId,
+            reason: input.reason,
+            status: 'open',
+            liability: 'undetermined',
+            requestedAmount: input.requestedAmount,
+            createdAt: now,
+            updatedAt: now,
+            evidence,
+        };
+        this.disputes.set(dispute.id, dispute);
+        this.byTransaction.set(input.transactionId, dispute.id);
+        let agentSet = this.byAgent.get(input.agentId);
+        if (!agentSet) {
+            agentSet = new Set();
+            this.byAgent.set(input.agentId, agentSet);
+        }
+        agentSet.add(dispute.id);
+        // Record in provenance
+        if (this.provenance) {
+            this.provenance.recordDispute(input.transactionId, {
+                disputeId: dispute.id,
+                reason: input.reason,
+                requestedAmount: input.requestedAmount,
+            });
+        }
+        this.logger?.info(`[DisputeManager] Filed dispute ${dispute.id} for tx ${input.transactionId}`);
+        return dispute;
+    }
+    /**
+     * Add evidence to an existing dispute.
+     */
+    addEvidence(disputeId, evidence) {
+        const dispute = this.disputes.get(disputeId);
+        if (!dispute) {
+            throw new Error(`Dispute ${disputeId} not found`);
+        }
+        if (this.isClosed(dispute.status)) {
+            throw new Error(`Cannot add evidence to closed dispute ${disputeId}`);
+        }
+        dispute.evidence.push(evidence);
+        dispute.updatedAt = new Date().toISOString();
+        this.logger?.info(`[DisputeManager] Added evidence to dispute ${disputeId}`, {
+            type: evidence.type,
+        });
+    }
+    /**
+     * Update the status of a dispute (e.g., open -> investigating).
+     */
+    updateStatus(disputeId, newStatus) {
+        const dispute = this.disputes.get(disputeId);
+        if (!dispute) {
+            throw new Error(`Dispute ${disputeId} not found`);
+        }
+        const previousStatus = dispute.status;
+        dispute.status = newStatus;
+        dispute.updatedAt = new Date().toISOString();
+        this.logger?.info(`[DisputeManager] Dispute ${disputeId} status: ${previousStatus} -> ${newStatus}`);
+        // Notify listeners
+        this.notifyListeners(dispute, previousStatus);
+    }
+    /**
+     * Resolve a dispute with a final determination.
+     */
+    resolve(disputeId, resolution) {
+        const dispute = this.disputes.get(disputeId);
+        if (!dispute) {
+            throw new Error(`Dispute ${disputeId} not found`);
+        }
+        const previousStatus = dispute.status;
+        dispute.status = resolution.status;
+        dispute.liability = resolution.liability;
+        dispute.resolvedAmount = resolution.resolvedAmount;
+        dispute.resolvedAt = new Date().toISOString();
+        dispute.updatedAt = dispute.resolvedAt;
+        this.logger?.info(`[DisputeManager] Resolved dispute ${disputeId}: ${resolution.status}, liability=${resolution.liability}`);
+        this.notifyListeners(dispute, previousStatus);
+        return dispute;
+    }
+    /**
+     * Get a dispute by ID.
+     */
+    get(disputeId) {
+        return this.disputes.get(disputeId);
+    }
+    /**
+     * Get the dispute associated with a transaction.
+     */
+    getByTransaction(txId) {
+        const disputeId = this.byTransaction.get(txId);
+        return disputeId ? this.disputes.get(disputeId) : undefined;
+    }
+    /**
+     * Get all disputes for an agent.
+     */
+    getByAgent(agentId) {
+        const ids = this.byAgent.get(agentId);
+        if (!ids)
+            return [];
+        return [...ids]
+            .map((id) => this.disputes.get(id))
+            .filter((d) => d !== undefined);
+    }
+    /**
+     * Query disputes with filtering.
+     */
+    query(filter) {
+        let results = [...this.disputes.values()];
+        if (filter.status) {
+            results = results.filter((d) => d.status === filter.status);
+        }
+        if (filter.agentId) {
+            results = results.filter((d) => d.agentId === filter.agentId);
+        }
+        if (filter.transactionId) {
+            results = results.filter((d) => d.transactionId === filter.transactionId);
+        }
+        if (filter.liability) {
+            results = results.filter((d) => d.liability === filter.liability);
+        }
+        // Sort newest first
+        results.sort((a, b) => b.createdAt.localeCompare(a.createdAt));
+        if (filter.limit) {
+            results = results.slice(0, filter.limit);
+        }
+        return results;
+    }
+    /**
+     * Register a listener for dispute status changes.
+     */
+    onStatusChange(listener) {
+        this.listeners.push(listener);
+    }
+    /**
+     * Get summary statistics for disputes.
+     */
+    getStats() {
+        let open = 0;
+        let investigating = 0;
+        let resolved = 0;
+        let escalated = 0;
+        let totalRequestedAmount = 0;
+        let totalResolvedAmount = 0;
+        for (const dispute of this.disputes.values()) {
+            totalRequestedAmount += dispute.requestedAmount;
+            totalResolvedAmount += dispute.resolvedAmount ?? 0;
+            switch (dispute.status) {
+                case 'open':
+                    open++;
+                    break;
+                case 'investigating':
+                    investigating++;
+                    break;
+                case 'resolved_refunded':
+                case 'resolved_denied':
+                case 'resolved_partial':
+                    resolved++;
+                    break;
+                case 'escalated':
+                    escalated++;
+                    break;
+            }
+        }
+        return {
+            total: this.disputes.size,
+            open,
+            investigating,
+            resolved,
+            escalated,
+            totalRequestedAmount,
+            totalResolvedAmount,
+        };
+    }
+    // ---------------------------------------------------------------------------
+    // Private
+    // ---------------------------------------------------------------------------
+    isClosed(status) {
+        return (status === 'resolved_refunded' ||
+            status === 'resolved_denied' ||
+            status === 'resolved_partial');
+    }
+    notifyListeners(dispute, previousStatus) {
+        for (const listener of this.listeners) {
+            try {
+                void listener(dispute, previousStatus);
+            }
+            catch (err) {
+                this.logger?.error(`[DisputeManager] Listener error: ${err}`);
+            }
+        }
+    }
+}
+//# sourceMappingURL=disputes.js.map

package/dist/disputes.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { TransactionProvenance } from './provenance.js';
+export { DisputeManager } from './disputes.js';
+export type { FileDisputeInput, DisputeFilter, DisputeListener } from './disputes.js';
+export { RecoveryEngine } from './recovery.js';
+export type { RecoveryAction, RecoveryStatus, RecoveryType, RefundExecutor, } from './recovery.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,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAExD,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAC/C,YAAY,EAAE,gBAAgB,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAEtF,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAC/C,YAAY,EACV,cAAc,EACd,cAAc,EACd,YAAY,EACZ,cAAc,GACf,MAAM,eAAe,CAAC"}

package/dist/index.js

@@ -0,0 +1,8 @@
+// =============================================================================
+// @paysentry/protect — Public API
+// Dispute resolution and recovery for AI agent payments
+// =============================================================================
+export { TransactionProvenance } from './provenance.js';
+export { DisputeManager } from './disputes.js';
+export { RecoveryEngine } from './recovery.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,wDAAwD;AACxD,gFAAgF;AAEhF,OAAO,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAExD,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAG/C,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC"}

package/dist/provenance.d.ts

@@ -0,0 +1,80 @@
+import type { AgentTransaction, TransactionId, ProvenanceRecord, Logger } from '@paysentry/core';
+/**
+ * TransactionProvenance maintains a complete, immutable audit trail
+ * for every transaction. Each stage of the pipeline (intent, policy check,
+ * approval, execution, settlement, dispute) creates a provenance record.
+ *
+ * This forms the evidentiary basis for dispute resolution and liability
+ * attribution.
+ *
+ * @example
+ * ```ts
+ * const provenance = new TransactionProvenance();
+ *
+ * // Record each stage
+ * provenance.recordIntent(tx, { originalPrompt: 'Buy me a coffee' });
+ * provenance.recordPolicyCheck(tx.id, 'pass', { policyId: 'default' });
+ * provenance.recordExecution(tx.id, 'pass', { txHash: '0xabc...' });
+ * provenance.recordSettlement(tx.id, 'pass', { confirmedAt: '2026-01-01' });
+ *
+ * // Query the full chain
+ * const chain = provenance.getChain(tx.id);
+ * // chain = [intent, policy_check, execution, settlement]
+ * ```
+ */
+export declare class TransactionProvenance {
+    /** Storage: transactionId -> ordered list of provenance records */
+    private readonly chains;
+    private readonly logger?;
+    constructor(options?: {
+        logger?: Logger;
+    });
+    /**
+     * Record the initial intent stage — when the agent declares what it wants to pay.
+     */
+    recordIntent(tx: AgentTransaction, details?: Record<string, unknown>): ProvenanceRecord;
+    /**
+     * Record a policy check stage — whether the policy engine approved/denied.
+     */
+    recordPolicyCheck(txId: TransactionId, outcome: 'pass' | 'fail', details?: Record<string, unknown>): ProvenanceRecord;
+    /**
+     * Record an approval stage — human or automated approval decision.
+     */
+    recordApproval(txId: TransactionId, outcome: 'pass' | 'fail', details?: Record<string, unknown>): ProvenanceRecord;
+    /**
+     * Record the execution stage — when the payment is actually submitted.
+     */
+    recordExecution(txId: TransactionId, outcome: 'pass' | 'fail', details?: Record<string, unknown>): ProvenanceRecord;
+    /**
+     * Record the settlement stage — when funds are confirmed received.
+     */
+    recordSettlement(txId: TransactionId, outcome: 'pass' | 'fail', details?: Record<string, unknown>): ProvenanceRecord;
+    /**
+     * Record a dispute stage — when a dispute is filed against this transaction.
+     */
+    recordDispute(txId: TransactionId, details?: Record<string, unknown>): ProvenanceRecord;
+    /**
+     * Get the full provenance chain for a transaction.
+     * Returns records in chronological order.
+     */
+    getChain(txId: TransactionId): readonly ProvenanceRecord[];
+    /**
+     * Check if a transaction has a complete provenance chain
+     * (intent through settlement or dispute).
+     */
+    isComplete(txId: TransactionId): boolean;
+    /**
+     * Get the last recorded stage for a transaction.
+     */
+    getLastStage(txId: TransactionId): ProvenanceRecord | undefined;
+    /**
+     * Get all transaction IDs with provenance records.
+     */
+    get transactionIds(): TransactionId[];
+    /**
+     * Get the total number of provenance records across all transactions.
+     */
+    get totalRecords(): number;
+    private addRecord;
+}
+//# sourceMappingURL=provenance.d.ts.map

package/dist/provenance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provenance.d.ts","sourceRoot":"","sources":["../src/provenance.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EACV,gBAAgB,EAChB,aAAa,EACb,gBAAgB,EAChB,MAAM,EACP,MAAM,iBAAiB,CAAC;AAEzB;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,qBAAa,qBAAqB;IAChC,mEAAmE;IACnE,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAqD;IAE5E,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAS;gBAErB,OAAO,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE;IAIzC;;OAEG;IACH,YAAY,CACV,EAAE,EAAE,gBAAgB,EACpB,OAAO,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GACpC,gBAAgB;IAmBnB;;OAEG;IACH,iBAAiB,CACf,IAAI,EAAE,aAAa,EACnB,OAAO,EAAE,MAAM,GAAG,MAAM,EACxB,OAAO,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GACpC,gBAAgB;IAWnB;;OAEG;IACH,cAAc,CACZ,IAAI,EAAE,aAAa,EACnB,OAAO,EAAE,MAAM,GAAG,MAAM,EACxB,OAAO,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GACpC,gBAAgB;IAWnB;;OAEG;IACH,eAAe,CACb,IAAI,EAAE,aAAa,EACnB,OAAO,EAAE,MAAM,GAAG,MAAM,EACxB,OAAO,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GACpC,gBAAgB;IAWnB;;OAEG;IACH,gBAAgB,CACd,IAAI,EAAE,aAAa,EACnB,OAAO,EAAE,MAAM,GAAG,MAAM,EACxB,OAAO,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GACpC,gBAAgB;IAWnB;;OAEG;IACH,aAAa,CACX,IAAI,EAAE,aAAa,EACnB,OAAO,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GACpC,gBAAgB;IAWnB;;;OAGG;IACH,QAAQ,CAAC,IAAI,EAAE,aAAa,GAAG,SAAS,gBAAgB,EAAE;IAI1D;;;OAGG;IACH,UAAU,CAAC,IAAI,EAAE,aAAa,GAAG,OAAO;IAQxC;;OAEG;IACH,YAAY,CAAC,IAAI,EAAE,aAAa,GAAG,gBAAgB,GAAG,SAAS;IAM/D;;OAEG;IACH,IAAI,cAAc,IAAI,aAAa,EAAE,CAEpC;IAED;;OAEG;IACH,IAAI,YAAY,IAAI,MAAM,CAMzB;IAMD,OAAO,CAAC,SAAS;CAclB"}

package/dist/provenance.js

@@ -0,0 +1,180 @@
+// =============================================================================
+// TransactionProvenance — Full audit trail from intent to settlement
+// Records every step of the transaction lifecycle for accountability
+// =============================================================================
+/**
+ * TransactionProvenance maintains a complete, immutable audit trail
+ * for every transaction. Each stage of the pipeline (intent, policy check,
+ * approval, execution, settlement, dispute) creates a provenance record.
+ *
+ * This forms the evidentiary basis for dispute resolution and liability
+ * attribution.
+ *
+ * @example
+ * ```ts
+ * const provenance = new TransactionProvenance();
+ *
+ * // Record each stage
+ * provenance.recordIntent(tx, { originalPrompt: 'Buy me a coffee' });
+ * provenance.recordPolicyCheck(tx.id, 'pass', { policyId: 'default' });
+ * provenance.recordExecution(tx.id, 'pass', { txHash: '0xabc...' });
+ * provenance.recordSettlement(tx.id, 'pass', { confirmedAt: '2026-01-01' });
+ *
+ * // Query the full chain
+ * const chain = provenance.getChain(tx.id);
+ * // chain = [intent, policy_check, execution, settlement]
+ * ```
+ */
+export class TransactionProvenance {
+    /** Storage: transactionId -> ordered list of provenance records */
+    chains = new Map();
+    logger;
+    constructor(options) {
+        this.logger = options?.logger;
+    }
+    /**
+     * Record the initial intent stage — when the agent declares what it wants to pay.
+     */
+    recordIntent(tx, details = {}) {
+        return this.addRecord(tx.id, {
+            transactionId: tx.id,
+            stage: 'intent',
+            timestamp: new Date().toISOString(),
+            action: `Agent ${tx.agentId} intends to pay ${tx.amount} ${tx.currency} to ${tx.recipient}`,
+            outcome: 'pass',
+            details: {
+                agentId: tx.agentId,
+                recipient: tx.recipient,
+                amount: tx.amount,
+                currency: tx.currency,
+                purpose: tx.purpose,
+                protocol: tx.protocol,
+                ...details,
+            },
+        });
+    }
+    /**
+     * Record a policy check stage — whether the policy engine approved/denied.
+     */
+    recordPolicyCheck(txId, outcome, details = {}) {
+        return this.addRecord(txId, {
+            transactionId: txId,
+            stage: 'policy_check',
+            timestamp: new Date().toISOString(),
+            action: outcome === 'pass' ? 'Policy check passed' : 'Policy check failed',
+            outcome,
+            details,
+        });
+    }
+    /**
+     * Record an approval stage — human or automated approval decision.
+     */
+    recordApproval(txId, outcome, details = {}) {
+        return this.addRecord(txId, {
+            transactionId: txId,
+            stage: 'approval',
+            timestamp: new Date().toISOString(),
+            action: outcome === 'pass' ? 'Transaction approved' : 'Transaction rejected',
+            outcome,
+            details,
+        });
+    }
+    /**
+     * Record the execution stage — when the payment is actually submitted.
+     */
+    recordExecution(txId, outcome, details = {}) {
+        return this.addRecord(txId, {
+            transactionId: txId,
+            stage: 'execution',
+            timestamp: new Date().toISOString(),
+            action: outcome === 'pass' ? 'Payment executed successfully' : 'Payment execution failed',
+            outcome,
+            details,
+        });
+    }
+    /**
+     * Record the settlement stage — when funds are confirmed received.
+     */
+    recordSettlement(txId, outcome, details = {}) {
+        return this.addRecord(txId, {
+            transactionId: txId,
+            stage: 'settlement',
+            timestamp: new Date().toISOString(),
+            action: outcome === 'pass' ? 'Payment settled and confirmed' : 'Settlement failed',
+            outcome,
+            details,
+        });
+    }
+    /**
+     * Record a dispute stage — when a dispute is filed against this transaction.
+     */
+    recordDispute(txId, details = {}) {
+        return this.addRecord(txId, {
+            transactionId: txId,
+            stage: 'dispute',
+            timestamp: new Date().toISOString(),
+            action: 'Dispute filed against transaction',
+            outcome: 'pending',
+            details,
+        });
+    }
+    /**
+     * Get the full provenance chain for a transaction.
+     * Returns records in chronological order.
+     */
+    getChain(txId) {
+        return this.chains.get(txId) ?? [];
+    }
+    /**
+     * Check if a transaction has a complete provenance chain
+     * (intent through settlement or dispute).
+     */
+    isComplete(txId) {
+        const chain = this.chains.get(txId);
+        if (!chain || chain.length === 0)
+            return false;
+        const stages = new Set(chain.map((r) => r.stage));
+        return stages.has('intent') && (stages.has('settlement') || stages.has('dispute'));
+    }
+    /**
+     * Get the last recorded stage for a transaction.
+     */
+    getLastStage(txId) {
+        const chain = this.chains.get(txId);
+        if (!chain || chain.length === 0)
+            return undefined;
+        return chain[chain.length - 1];
+    }
+    /**
+     * Get all transaction IDs with provenance records.
+     */
+    get transactionIds() {
+        return [...this.chains.keys()];
+    }
+    /**
+     * Get the total number of provenance records across all transactions.
+     */
+    get totalRecords() {
+        let total = 0;
+        for (const chain of this.chains.values()) {
+            total += chain.length;
+        }
+        return total;
+    }
+    // ---------------------------------------------------------------------------
+    // Private
+    // ---------------------------------------------------------------------------
+    addRecord(txId, record) {
+        let chain = this.chains.get(txId);
+        if (!chain) {
+            chain = [];
+            this.chains.set(txId, chain);
+        }
+        chain.push(record);
+        this.logger?.info(`[Provenance] ${record.stage}:${record.outcome} for ${txId}`, {
+            action: record.action,
+        });
+        return record;
+    }
+}
+//# sourceMappingURL=provenance.js.map

package/dist/provenance.js.map

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

package/dist/recovery.d.ts

@@ -0,0 +1,127 @@
+import type { DisputeId, TransactionId, AgentId, Logger } from '@paysentry/core';
+import type { DisputeManager } from './disputes.js';
+/** Status of a recovery attempt */
+export type RecoveryStatus = 'pending' | 'processing' | 'completed' | 'failed' | 'cancelled';
+/** Type of recovery action */
+export type RecoveryType = 'full_refund' | 'partial_refund' | 'chargeback' | 'credit';
+/** A single recovery action */
+export interface RecoveryAction {
+    /** Unique recovery ID */
+    readonly id: string;
+    /** Associated dispute */
+    readonly disputeId: DisputeId;
+    /** Original transaction */
+    readonly transactionId: TransactionId;
+    /** Agent receiving the recovery */
+    readonly agentId: AgentId;
+    /** Type of recovery */
+    readonly type: RecoveryType;
+    /** Amount to recover */
+    readonly amount: number;
+    /** Currency */
+    readonly currency: string;
+    /** Current status */
+    status: RecoveryStatus;
+    /** ISO 8601 timestamp of creation */
+    readonly createdAt: string;
+    /** ISO 8601 timestamp of last update */
+    updatedAt: string;
+    /** ISO 8601 timestamp of completion */
+    completedAt?: string;
+    /** Protocol-specific refund transaction ID */
+    refundTxId?: string;
+    /** Error message if failed */
+    error?: string;
+}
+/** Handler that executes the actual refund on the protocol level */
+export type RefundExecutor = (action: RecoveryAction) => Promise<{
+    success: boolean;
+    refundTxId?: string;
+    error?: string;
+}>;
+/**
+ * RecoveryEngine automates the process of recovering funds after
+ * a dispute has been resolved in favor of the agent. It manages
+ * refund queues, retry logic, and settlement confirmation.
+ *
+ * @example
+ * ```ts
+ * const recovery = new RecoveryEngine({
+ *   disputes: disputeManager,
+ *   executor: async (action) => {
+ *     // Execute the actual refund via the payment protocol
+ *     const result = await protocolRefund(action.transactionId, action.amount);
+ *     return { success: result.ok, refundTxId: result.txId };
+ *   },
+ * });
+ *
+ * // Initiate recovery for a resolved dispute
+ * const action = recovery.initiate(dispute.id);
+ *
+ * // Process the recovery queue
+ * await recovery.processQueue();
+ * ```
+ */
+export declare class RecoveryEngine {
+    /** All recovery actions */
+    private readonly actions;
+    /** Index: disputeId -> recoveryId */
+    private readonly byDispute;
+    /** Processing queue (FIFO) */
+    private readonly queue;
+    /** Maximum retry attempts */
+    private readonly maxRetries;
+    /** Retry delay in milliseconds */
+    private readonly retryDelayMs;
+    private readonly disputes;
+    private readonly executor;
+    private readonly logger?;
+    constructor(options: {
+        disputes: DisputeManager;
+        executor: RefundExecutor;
+        maxRetries?: number;
+        retryDelayMs?: number;
+        logger?: Logger;
+    });
+    /**
+     * Initiate a recovery action for a resolved dispute.
+     * The dispute must be in a resolved state that warrants a refund.
+     */
+    initiate(disputeId: DisputeId): RecoveryAction;
+    /**
+     * Process all pending recovery actions in the queue.
+     * Each action is attempted with retry logic.
+     */
+    processQueue(): Promise<RecoveryAction[]>;
+    /**
+     * Cancel a pending recovery action.
+     */
+    cancel(recoveryId: string): RecoveryAction;
+    /**
+     * Get a recovery action by ID.
+     */
+    get(recoveryId: string): RecoveryAction | undefined;
+    /**
+     * Get the recovery action for a specific dispute.
+     */
+    getByDispute(disputeId: DisputeId): RecoveryAction | undefined;
+    /**
+     * Get all recovery actions, optionally filtered by status.
+     */
+    getAll(status?: RecoveryStatus): RecoveryAction[];
+    /**
+     * Get recovery statistics.
+     */
+    getStats(): {
+        total: number;
+        pending: number;
+        processing: number;
+        completed: number;
+        failed: number;
+        cancelled: number;
+        totalRecovered: number;
+    };
+    private executeWithRetry;
+    private sleep;
+}
+//# sourceMappingURL=recovery.d.ts.map

package/dist/recovery.d.ts.map

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

package/dist/recovery.js

@@ -0,0 +1,222 @@
+// =============================================================================
+// RecoveryEngine — Automated refund and chargeback flows
+// Handles the mechanical process of recovering funds after dispute resolution
+// =============================================================================
+import { generateId } from '@paysentry/core';
+/**
+ * RecoveryEngine automates the process of recovering funds after
+ * a dispute has been resolved in favor of the agent. It manages
+ * refund queues, retry logic, and settlement confirmation.
+ *
+ * @example
+ * ```ts
+ * const recovery = new RecoveryEngine({
+ *   disputes: disputeManager,
+ *   executor: async (action) => {
+ *     // Execute the actual refund via the payment protocol
+ *     const result = await protocolRefund(action.transactionId, action.amount);
+ *     return { success: result.ok, refundTxId: result.txId };
+ *   },
+ * });
+ *
+ * // Initiate recovery for a resolved dispute
+ * const action = recovery.initiate(dispute.id);
+ *
+ * // Process the recovery queue
+ * await recovery.processQueue();
+ * ```
+ */
+export class RecoveryEngine {
+    /** All recovery actions */
+    actions = new Map();
+    /** Index: disputeId -> recoveryId */
+    byDispute = new Map();
+    /** Processing queue (FIFO) */
+    queue = [];
+    /** Maximum retry attempts */
+    maxRetries;
+    /** Retry delay in milliseconds */
+    retryDelayMs;
+    disputes;
+    executor;
+    logger;
+    constructor(options) {
+        this.disputes = options.disputes;
+        this.executor = options.executor;
+        this.maxRetries = options.maxRetries ?? 3;
+        this.retryDelayMs = options.retryDelayMs ?? 5000;
+        this.logger = options.logger;
+    }
+    /**
+     * Initiate a recovery action for a resolved dispute.
+     * The dispute must be in a resolved state that warrants a refund.
+     */
+    initiate(disputeId) {
+        const dispute = this.disputes.get(disputeId);
+        if (!dispute) {
+            throw new Error(`Dispute ${disputeId} not found`);
+        }
+        if (dispute.status !== 'resolved_refunded' && dispute.status !== 'resolved_partial') {
+            throw new Error(`Cannot initiate recovery for dispute ${disputeId} with status "${dispute.status}". ` +
+                `Dispute must be resolved with refund or partial refund.`);
+        }
+        // Check for existing recovery
+        const existingId = this.byDispute.get(disputeId);
+        if (existingId) {
+            const existing = this.actions.get(existingId);
+            if (existing && existing.status !== 'failed' && existing.status !== 'cancelled') {
+                throw new Error(`Active recovery ${existingId} already exists for dispute ${disputeId}`);
+            }
+        }
+        const amount = dispute.resolvedAmount ?? dispute.requestedAmount;
+        const recoveryType = dispute.status === 'resolved_partial' ? 'partial_refund' : 'full_refund';
+        const now = new Date().toISOString();
+        const action = {
+            id: generateId('rcv'),
+            disputeId,
+            transactionId: dispute.transactionId,
+            agentId: dispute.agentId,
+            type: recoveryType,
+            amount,
+            currency: 'USDC', // Default; could be pulled from transaction
+            status: 'pending',
+            createdAt: now,
+            updatedAt: now,
+        };
+        this.actions.set(action.id, action);
+        this.byDispute.set(disputeId, action.id);
+        this.queue.push(action.id);
+        this.logger?.info(`[RecoveryEngine] Initiated ${recoveryType} of $${amount} for dispute ${disputeId}`);
+        return action;
+    }
+    /**
+     * Process all pending recovery actions in the queue.
+     * Each action is attempted with retry logic.
+     */
+    async processQueue() {
+        const processed = [];
+        while (this.queue.length > 0) {
+            const actionId = this.queue.shift();
+            const action = this.actions.get(actionId);
+            if (!action || action.status === 'cancelled')
+                continue;
+            const result = await this.executeWithRetry(action);
+            processed.push(result);
+        }
+        return processed;
+    }
+    /**
+     * Cancel a pending recovery action.
+     */
+    cancel(recoveryId) {
+        const action = this.actions.get(recoveryId);
+        if (!action) {
+            throw new Error(`Recovery action ${recoveryId} not found`);
+        }
+        if (action.status !== 'pending') {
+            throw new Error(`Cannot cancel recovery ${recoveryId} with status "${action.status}"`);
+        }
+        action.status = 'cancelled';
+        action.updatedAt = new Date().toISOString();
+        this.logger?.info(`[RecoveryEngine] Cancelled recovery ${recoveryId}`);
+        return action;
+    }
+    /**
+     * Get a recovery action by ID.
+     */
+    get(recoveryId) {
+        return this.actions.get(recoveryId);
+    }
+    /**
+     * Get the recovery action for a specific dispute.
+     */
+    getByDispute(disputeId) {
+        const recoveryId = this.byDispute.get(disputeId);
+        return recoveryId ? this.actions.get(recoveryId) : undefined;
+    }
+    /**
+     * Get all recovery actions, optionally filtered by status.
+     */
+    getAll(status) {
+        const all = [...this.actions.values()];
+        return status ? all.filter((a) => a.status === status) : all;
+    }
+    /**
+     * Get recovery statistics.
+     */
+    getStats() {
+        let pending = 0;
+        let processing = 0;
+        let completed = 0;
+        let failed = 0;
+        let cancelled = 0;
+        let totalRecovered = 0;
+        for (const action of this.actions.values()) {
+            switch (action.status) {
+                case 'pending':
+                    pending++;
+                    break;
+                case 'processing':
+                    processing++;
+                    break;
+                case 'completed':
+                    completed++;
+                    totalRecovered += action.amount;
+                    break;
+                case 'failed':
+                    failed++;
+                    break;
+                case 'cancelled':
+                    cancelled++;
+                    break;
+            }
+        }
+        return {
+            total: this.actions.size,
+            pending,
+            processing,
+            completed,
+            failed,
+            cancelled,
+            totalRecovered,
+        };
+    }
+    // ---------------------------------------------------------------------------
+    // Private
+    // ---------------------------------------------------------------------------
+    async executeWithRetry(action) {
+        action.status = 'processing';
+        action.updatedAt = new Date().toISOString();
+        for (let attempt = 1; attempt <= this.maxRetries; attempt++) {
+            this.logger?.info(`[RecoveryEngine] Executing recovery ${action.id}, attempt ${attempt}/${this.maxRetries}`);
+            try {
+                const result = await this.executor(action);
+                if (result.success) {
+                    action.status = 'completed';
+                    action.refundTxId = result.refundTxId;
+                    action.completedAt = new Date().toISOString();
+                    action.updatedAt = action.completedAt;
+                    this.logger?.info(`[RecoveryEngine] Recovery ${action.id} completed: refundTxId=${result.refundTxId}`);
+                    return action;
+                }
+                action.error = result.error ?? 'Refund execution returned failure';
+            }
+            catch (err) {
+                action.error = err instanceof Error ? err.message : String(err);
+            }
+            // Wait before retrying (skip wait on last attempt)
+            if (attempt < this.maxRetries) {
+                await this.sleep(this.retryDelayMs * attempt);
+            }
+        }
+        // All retries exhausted
+        action.status = 'failed';
+        action.updatedAt = new Date().toISOString();
+        this.logger?.error(`[RecoveryEngine] Recovery ${action.id} failed after ${this.maxRetries} attempts: ${action.error}`);
+        return action;
+    }
+    sleep(ms) {
+        return new Promise((resolve) => setTimeout(resolve, ms));
+    }
+}
+//# sourceMappingURL=recovery.js.map

package/dist/recovery.js.map

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

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@paysentry/protect",
+  "version": "1.0.0",
+  "description": "Dispute resolution and recovery for AI agent payments",
+  "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/protect"
+  }
+}