open-agentpay 0.1.0 → 0.2.5

package/dist/state/buyer-coordinator.js

@@ -0,0 +1,363 @@
+/**
+ * Buyer State Coordinator for AgentPay.
+ *
+ * Coordinates SQLite atomic transactions between:
+ *   - Buyer Payment Intent (ap_buyer_intent)
+ *   - Budget Reservation Ledger (ap_budget_ledger)
+ *
+ * Enforces:
+ *   - Atomic two-phase reservation & commitment
+ *   - CLAUDE.md Invariant: No release once signature is dispatched
+ *   - Deterministic time injection via clock parameter
+ */
+import { randomUUID } from 'node:crypto';
+import { BudgetLedgerState, BuyerIntentRecord, PaymentIntentState, } from '../core/state.js';
+import { IllegalStateTransitionError, SignatureSentReleaseForbiddenError, } from './errors.js';
+import { validateIntentTransition, validateLedgerTransition, } from './guards.js';
+export class BuyerStateCoordinator {
+    #db;
+    #clock;
+    constructor(db, options) {
+        this.#db = db;
+        this.#clock = options?.clock ?? (() => Math.floor(Date.now() / 1000));
+    }
+    getTime() {
+        return this.#clock();
+    }
+    #rollbackQuietly() {
+        try {
+            if (this.#db.inTransaction) {
+                this.#db.exec('ROLLBACK;');
+            }
+        }
+        catch {
+            // Ignore rollback errors
+        }
+    }
+    createIntent(record) {
+        const now = this.getTime();
+        this.#db
+            .prepare(`
+        INSERT INTO ap_buyer_intent (
+          intent_id, policy_id, idempotency_key, payer_address, payee_address,
+          asset_address, network_id, amount_base_units, status, nonce,
+          valid_after, valid_before, raw_signature, created_at, updated_at
+        ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?);
+      `)
+            .run(record.intentId, record.policyId, record.idempotencyKey, record.payerAddress.toLowerCase(), record.payeeAddress.toLowerCase(), record.assetAddress.toLowerCase(), record.networkId, record.amountBaseUnits, record.status, record.nonce, record.validAfter, record.validBefore, record.rawSignature, record.createdAt || now, record.updatedAt || now);
+    }
+    reserveIntent(intentId, policyId, walletAddress, amountBaseUnits, ttlSeconds = 360) {
+        const now = this.getTime();
+        const expiresAt = now + ttlSeconds;
+        const reservationId = `res_${randomUUID().replace(/-/g, '')}`;
+        this.#db.exec('BEGIN IMMEDIATE;');
+        try {
+            const row = this.#db
+                .prepare('SELECT status FROM ap_buyer_intent WHERE intent_id = ?;')
+                .get(intentId);
+            if (!row || !row.status) {
+                this.#db.exec('ROLLBACK;');
+                throw new Error(`Buyer intent '${intentId}' not found.`);
+            }
+            const currentStatus = row.status;
+            validateIntentTransition(currentStatus, PaymentIntentState.PROCESSING, { intentId });
+            this.#db
+                .prepare(`
+          INSERT INTO ap_budget_ledger (
+            id, policy_id, wallet_address, intent_id, amount_base_units, state, created_at, expires_at, updated_at
+          ) VALUES (?, ?, ?, ?, ?, 'RESERVED', ?, ?, ?);
+        `)
+                .run(reservationId, policyId, walletAddress.toLowerCase(), intentId, typeof amountBaseUnits === 'bigint' ? amountBaseUnits : BigInt(amountBaseUnits), now, expiresAt, now);
+            this.#db
+                .prepare(`
+          UPDATE ap_buyer_intent
+          SET status = 'PROCESSING', updated_at = ?
+          WHERE intent_id = ?;
+        `)
+                .run(now, intentId);
+            this.#db.exec('COMMIT;');
+            return reservationId;
+        }
+        catch (exc) {
+            this.#rollbackQuietly();
+            throw exc;
+        }
+    }
+    recordDispatch(intentId, rawSignature = '0xdefault_sig', nonce = null) {
+        const now = this.getTime();
+        this.#db.exec('BEGIN IMMEDIATE;');
+        try {
+            const row = this.#db
+                .prepare('SELECT status FROM ap_buyer_intent WHERE intent_id = ?;')
+                .get(intentId);
+            if (!row || !row.status) {
+                this.#db.exec('ROLLBACK;');
+                throw new Error(`Buyer intent '${intentId}' not found.`);
+            }
+            const currentStatus = row.status;
+            validateIntentTransition(currentStatus, PaymentIntentState.SIGNATURE_SENT, { intentId });
+            const ledgerRow = this.#db
+                .prepare('SELECT state FROM ap_budget_ledger WHERE intent_id = ?;')
+                .get(intentId);
+            if (!ledgerRow || ledgerRow.state !== BudgetLedgerState.RESERVED) {
+                this.#db.exec('ROLLBACK;');
+                throw new IllegalStateTransitionError('BudgetLedger', ledgerRow?.state ?? 'NONE', BudgetLedgerState.RESERVED, 'Cannot dispatch request without an active RESERVED quota.');
+            }
+            this.#db
+                .prepare(`
+          UPDATE ap_buyer_intent
+          SET status = 'SIGNATURE_SENT',
+              raw_signature = COALESCE(?, raw_signature),
+              nonce = COALESCE(?, nonce),
+              updated_at = ?
+          WHERE intent_id = ?;
+        `)
+                .run(rawSignature, nonce, now, intentId);
+            this.#db.exec('COMMIT;');
+        }
+        catch (exc) {
+            this.#rollbackQuietly();
+            throw exc;
+        }
+    }
+    completeIntent(intentId) {
+        const now = this.getTime();
+        this.#db.exec('BEGIN IMMEDIATE;');
+        try {
+            const row = this.#db
+                .prepare('SELECT status FROM ap_buyer_intent WHERE intent_id = ?;')
+                .get(intentId);
+            if (!row || !row.status) {
+                this.#db.exec('ROLLBACK;');
+                throw new Error(`Buyer intent '${intentId}' not found.`);
+            }
+            const currentStatus = row.status;
+            validateIntentTransition(currentStatus, PaymentIntentState.SUCCEEDED, { intentId });
+            const ledgerRow = this.#db
+                .prepare('SELECT state FROM ap_budget_ledger WHERE intent_id = ?;')
+                .get(intentId);
+            if (!ledgerRow || !ledgerRow.state) {
+                this.#db.exec('ROLLBACK;');
+                throw new Error(`Ledger entry for intent '${intentId}' not found.`);
+            }
+            const currentLedger = ledgerRow.state;
+            validateLedgerTransition(currentLedger, BudgetLedgerState.COMMITTED);
+            this.#db
+                .prepare(`
+          UPDATE ap_budget_ledger
+          SET state = 'COMMITTED', updated_at = ?
+          WHERE intent_id = ?;
+        `)
+                .run(now, intentId);
+            this.#db
+                .prepare(`
+          UPDATE ap_buyer_intent
+          SET status = 'SUCCEEDED', updated_at = ?
+          WHERE intent_id = ?;
+        `)
+                .run(now, intentId);
+            this.#db.exec('COMMIT;');
+        }
+        catch (exc) {
+            this.#rollbackQuietly();
+            throw exc;
+        }
+    }
+    holdIntent(intentId, errorMessage) {
+        const now = this.getTime();
+        this.#db.exec('BEGIN IMMEDIATE;');
+        try {
+            const row = this.#db
+                .prepare('SELECT status FROM ap_buyer_intent WHERE intent_id = ?;')
+                .get(intentId);
+            if (!row || !row.status) {
+                this.#db.exec('ROLLBACK;');
+                throw new Error(`Buyer intent '${intentId}' not found.`);
+            }
+            const currentStatus = row.status;
+            validateIntentTransition(currentStatus, PaymentIntentState.RECOVERY_HOLD, { intentId });
+            const ledgerRow = this.#db
+                .prepare('SELECT state FROM ap_budget_ledger WHERE intent_id = ?;')
+                .get(intentId);
+            if (ledgerRow && ledgerRow.state !== BudgetLedgerState.RESERVED) {
+                this.#db.exec('ROLLBACK;');
+                throw new IllegalStateTransitionError('BudgetLedger', ledgerRow.state ?? 'NONE', BudgetLedgerState.RESERVED, 'Ledger must remain RESERVED when intent enters RECOVERY_HOLD.');
+            }
+            this.#db
+                .prepare(`
+          UPDATE ap_buyer_intent
+          SET status = 'RECOVERY_HOLD', updated_at = ?
+          WHERE intent_id = ?;
+        `)
+                .run(now, intentId);
+            this.#db.exec('COMMIT;');
+        }
+        catch (exc) {
+            this.#rollbackQuietly();
+            throw exc;
+        }
+    }
+    cancelIntent(intentId, reason = '') {
+        const now = this.getTime();
+        this.#db.exec('BEGIN IMMEDIATE;');
+        try {
+            const row = this.#db
+                .prepare('SELECT status FROM ap_buyer_intent WHERE intent_id = ?;')
+                .get(intentId);
+            if (!row || !row.status) {
+                this.#db.exec('ROLLBACK;');
+                throw new Error(`Buyer intent '${intentId}' not found.`);
+            }
+            const currentStatus = row.status;
+            // Safety Guard: Once SIGNATURE_SENT or RECOVERY_HOLD, cannot cancel!
+            if (currentStatus === PaymentIntentState.SIGNATURE_SENT ||
+                currentStatus === PaymentIntentState.RECOVERY_HOLD) {
+                this.#db.exec('ROLLBACK;');
+                throw new SignatureSentReleaseForbiddenError(intentId, currentStatus);
+            }
+            validateIntentTransition(currentStatus, PaymentIntentState.CANCELLED, { intentId });
+            const ledgerRow = this.#db
+                .prepare('SELECT state FROM ap_budget_ledger WHERE intent_id = ?;')
+                .get(intentId);
+            if (ledgerRow?.state) {
+                const currentLedger = ledgerRow.state;
+                validateLedgerTransition(currentLedger, BudgetLedgerState.RELEASED);
+                this.#db
+                    .prepare(`
+            UPDATE ap_budget_ledger
+            SET state = 'RELEASED', updated_at = ?
+            WHERE intent_id = ?;
+          `)
+                    .run(now, intentId);
+            }
+            this.#db
+                .prepare(`
+          UPDATE ap_buyer_intent
+          SET status = 'CANCELLED', updated_at = ?
+          WHERE intent_id = ?;
+        `)
+                .run(now, intentId);
+            this.#db.exec('COMMIT;');
+        }
+        catch (exc) {
+            this.#rollbackQuietly();
+            throw exc;
+        }
+    }
+    reconcileRelease(intentId, reason = '') {
+        const now = this.getTime();
+        this.#db.exec('BEGIN IMMEDIATE;');
+        try {
+            const row = this.#db
+                .prepare('SELECT status FROM ap_buyer_intent WHERE intent_id = ?;')
+                .get(intentId);
+            if (!row || !row.status) {
+                this.#db.exec('ROLLBACK;');
+                throw new Error(`Buyer intent '${intentId}' not found.`);
+            }
+            const currentStatus = row.status;
+            validateIntentTransition(currentStatus, PaymentIntentState.REJECTED, { intentId });
+            this.#db
+                .prepare(`
+          UPDATE ap_budget_ledger
+          SET state = 'RELEASED', updated_at = ?
+          WHERE intent_id = ? AND state = 'RESERVED';
+        `)
+                .run(now, intentId);
+            this.#db
+                .prepare(`
+          UPDATE ap_buyer_intent
+          SET status = 'REJECTED', updated_at = ?
+          WHERE intent_id = ?;
+        `)
+                .run(now, intentId);
+            this.#db.exec('COMMIT;');
+        }
+        catch (exc) {
+            this.#rollbackQuietly();
+            throw exc;
+        }
+    }
+    getIntent(intentId) {
+        const row = this.#db
+            .prepare(`
+        SELECT intent_id, policy_id, idempotency_key, payer_address, payee_address,
+               asset_address, network_id, amount_base_units, status, nonce,
+               valid_after, valid_before, raw_signature, created_at, updated_at
+        FROM ap_buyer_intent
+        WHERE intent_id = ?;
+      `)
+            .get(intentId);
+        if (!row) {
+            return null;
+        }
+        return new BuyerIntentRecord({
+            intentId: row.intent_id,
+            policyId: row.policy_id,
+            idempotencyKey: row.idempotency_key,
+            payerAddress: row.payer_address,
+            payeeAddress: row.payee_address,
+            assetAddress: row.asset_address,
+            networkId: row.network_id,
+            amountBaseUnits: row.amount_base_units,
+            status: row.status,
+            nonce: row.nonce,
+            validAfter: row.valid_after != null ? Number(row.valid_after) : null,
+            validBefore: row.valid_before != null ? Number(row.valid_before) : null,
+            rawSignature: row.raw_signature,
+            createdAt: Number(row.created_at),
+            updatedAt: Number(row.updated_at),
+        });
+    }
+    getLedgerState(intentId) {
+        const row = this.#db
+            .prepare('SELECT state FROM ap_budget_ledger WHERE intent_id = ?;')
+            .get(intentId);
+        return row?.state ? row.state : null;
+    }
+    listIntents(states) {
+        let rows;
+        if (states && states.length > 0) {
+            const placeholders = states.map(() => '?').join(',');
+            rows = this.#db
+                .prepare(`
+          SELECT intent_id, policy_id, idempotency_key, payer_address, payee_address,
+                 asset_address, network_id, amount_base_units, status, nonce,
+                 valid_after, valid_before, raw_signature, created_at, updated_at
+          FROM ap_buyer_intent
+          WHERE status IN (${placeholders})
+          ORDER BY created_at ASC;
+        `)
+                .all(...states);
+        }
+        else {
+            rows = this.#db
+                .prepare(`
+          SELECT intent_id, policy_id, idempotency_key, payer_address, payee_address,
+                 asset_address, network_id, amount_base_units, status, nonce,
+                 valid_after, valid_before, raw_signature, created_at, updated_at
+          FROM ap_buyer_intent
+          ORDER BY created_at ASC;
+        `)
+                .all();
+        }
+        return rows.map((row) => new BuyerIntentRecord({
+            intentId: row.intent_id,
+            policyId: row.policy_id,
+            idempotencyKey: row.idempotency_key,
+            payerAddress: row.payer_address,
+            payeeAddress: row.payee_address,
+            assetAddress: row.asset_address,
+            networkId: row.network_id,
+            amountBaseUnits: row.amount_base_units,
+            status: row.status,
+            nonce: row.nonce,
+            validAfter: row.valid_after != null ? Number(row.valid_after) : null,
+            validBefore: row.valid_before != null ? Number(row.valid_before) : null,
+            rawSignature: row.raw_signature,
+            createdAt: Number(row.created_at),
+            updatedAt: Number(row.updated_at),
+        }));
+    }
+}
+//# sourceMappingURL=buyer-coordinator.js.map

package/dist/state/buyer-coordinator.js.map

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

package/dist/state/errors.d.ts

@@ -0,0 +1,45 @@
+/**
+ * State transition and coordination exceptions for AgentPay.
+ *
+ * Standardized error types for illegal lifecycle mutations and safety violations:
+ *   - IllegalStateTransitionError
+ *   - SignatureSentReleaseForbiddenError
+ *   - OrphanedSettlementRollbackForbiddenError
+ *   - InvalidCompositeStateError
+ *   - IdempotencyLockConflictError
+ */
+export declare class StateCoordinationError extends Error {
+    constructor(message: string);
+}
+export declare class IllegalStateTransitionError extends StateCoordinationError {
+    readonly entityType: string;
+    readonly fromState: string;
+    readonly toState: string;
+    readonly detail: string;
+    constructor(entityType: string, fromState: string, toState: string, detail?: string);
+}
+export declare class SignatureSentReleaseForbiddenError extends StateCoordinationError {
+    readonly intentId: string;
+    readonly currentState: string;
+    constructor(intentId: string, currentState: string);
+}
+export declare class OrphanedSettlementRollbackForbiddenError extends StateCoordinationError {
+    readonly settlementId: string;
+    readonly settlementState: string;
+    constructor(settlementId: string, settlementState: string);
+}
+export declare class InvalidCompositeStateError extends StateCoordinationError {
+    readonly intentState: string;
+    readonly settlementState: string;
+    readonly fulfillmentState: string;
+    readonly ledgerState: string | null;
+    readonly reason: string;
+    constructor(intentState: string, settlementState: string, fulfillmentState: string, ledgerState: string | null, reason: string);
+}
+export declare class IdempotencyLockConflictError extends StateCoordinationError {
+    readonly payerAddress: string;
+    readonly idempotencyKey: string;
+    readonly lockedUntil: number;
+    constructor(payerAddress: string, idempotencyKey: string, lockedUntil: number);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/state/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/state/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,qBAAa,sBAAuB,SAAQ,KAAK;gBACnC,OAAO,EAAE,MAAM;CAI5B;AAED,qBAAa,2BAA4B,SAAQ,sBAAsB;IACrE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;gBAEZ,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,SAAK;CAWhF;AAED,qBAAa,kCAAmC,SAAQ,sBAAsB;IAC5E,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;gBAElB,QAAQ,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM;CAUnD;AAED,qBAAa,wCAAyC,SAAQ,sBAAsB;IAClF,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;gBAErB,YAAY,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM;CAU1D;AAED,qBAAa,0BAA2B,SAAQ,sBAAsB;IACpE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IACpC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;gBAGtB,WAAW,EAAE,MAAM,EACnB,eAAe,EAAE,MAAM,EACvB,gBAAgB,EAAE,MAAM,EACxB,WAAW,EAAE,MAAM,GAAG,IAAI,EAC1B,MAAM,EAAE,MAAM;CAajB;AAED,qBAAa,4BAA6B,SAAQ,sBAAsB;IACtE,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;gBAEjB,YAAY,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM;CAU9E"}

package/dist/state/errors.js

@@ -0,0 +1,88 @@
+/**
+ * State transition and coordination exceptions for AgentPay.
+ *
+ * Standardized error types for illegal lifecycle mutations and safety violations:
+ *   - IllegalStateTransitionError
+ *   - SignatureSentReleaseForbiddenError
+ *   - OrphanedSettlementRollbackForbiddenError
+ *   - InvalidCompositeStateError
+ *   - IdempotencyLockConflictError
+ */
+export class StateCoordinationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'StateCoordinationError';
+    }
+}
+export class IllegalStateTransitionError extends StateCoordinationError {
+    entityType;
+    fromState;
+    toState;
+    detail;
+    constructor(entityType, fromState, toState, detail = '') {
+        const msg = detail
+            ? `Illegal ${entityType} state transition from '${fromState}' to '${toState}': ${detail}`
+            : `Illegal ${entityType} state transition from '${fromState}' to '${toState}'`;
+        super(msg);
+        this.name = 'IllegalStateTransitionError';
+        this.entityType = entityType;
+        this.fromState = fromState;
+        this.toState = toState;
+        this.detail = detail;
+    }
+}
+export class SignatureSentReleaseForbiddenError extends StateCoordinationError {
+    intentId;
+    currentState;
+    constructor(intentId, currentState) {
+        super(`Cannot release or cancel intent '${intentId}' in state '${currentState}': ` +
+            'Cryptographic signature has already been transmitted on the wire. ' +
+            'Quota must remain RESERVED until reconciliation or successful retry.');
+        this.name = 'SignatureSentReleaseForbiddenError';
+        this.intentId = intentId;
+        this.currentState = currentState;
+    }
+}
+export class OrphanedSettlementRollbackForbiddenError extends StateCoordinationError {
+    settlementId;
+    settlementState;
+    constructor(settlementId, settlementState) {
+        super(`Cannot void settlement '${settlementId}' in state '${settlementState}': ` +
+            'Payment verification succeeded and funds transfer is active. ' +
+            'Upstream fulfillment failures must not rollback settlement.');
+        this.name = 'OrphanedSettlementRollbackForbiddenError';
+        this.settlementId = settlementId;
+        this.settlementState = settlementState;
+    }
+}
+export class InvalidCompositeStateError extends StateCoordinationError {
+    intentState;
+    settlementState;
+    fulfillmentState;
+    ledgerState;
+    reason;
+    constructor(intentState, settlementState, fulfillmentState, ledgerState, reason) {
+        super(`Invalid composite state (Intent=${intentState}, Settlement=${settlementState}, ` +
+            `Fulfillment=${fulfillmentState}, Ledger=${ledgerState ?? 'null'}): ${reason}`);
+        this.name = 'InvalidCompositeStateError';
+        this.intentState = intentState;
+        this.settlementState = settlementState;
+        this.fulfillmentState = fulfillmentState;
+        this.ledgerState = ledgerState;
+        this.reason = reason;
+    }
+}
+export class IdempotencyLockConflictError extends StateCoordinationError {
+    payerAddress;
+    idempotencyKey;
+    lockedUntil;
+    constructor(payerAddress, idempotencyKey, lockedUntil) {
+        super(`Concurrent request in-flight for (${payerAddress}, ${idempotencyKey}). ` +
+            `Lease locked until Unix timestamp ${lockedUntil}.`);
+        this.name = 'IdempotencyLockConflictError';
+        this.payerAddress = payerAddress;
+        this.idempotencyKey = idempotencyKey;
+        this.lockedUntil = lockedUntil;
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/state/errors.js.map

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

package/dist/state/guards.d.ts

@@ -0,0 +1,24 @@
+/**
+ * State Transition Guards and Multi-Entity Validation Rules for AgentPay.
+ *
+ * Enforces:
+ *   - Transition guard matrices for Intent, Settlement, Fulfillment, and Ledger
+ *   - Strict Anti-Overspend invariant: SIGNATURE_SENT/RECOVERY_HOLD cannot release
+ *   - Strict Anti-Rollback invariant: Upstream 5xx cannot void Settlement
+ *   - Legal composite state whitelist
+ */
+import { BudgetLedgerState, FulfillmentState, PaymentIntentState, SettlementState } from '../core/state.js';
+export declare const LEGAL_INTENT_TRANSITIONS: Readonly<Record<PaymentIntentState, ReadonlySet<PaymentIntentState>>>;
+export declare const LEGAL_SETTLEMENT_TRANSITIONS: Readonly<Record<SettlementState, ReadonlySet<SettlementState>>>;
+export declare const LEGAL_FULFILLMENT_TRANSITIONS: Readonly<Record<FulfillmentState, ReadonlySet<FulfillmentState>>>;
+export declare const LEGAL_LEDGER_TRANSITIONS: Readonly<Record<BudgetLedgerState, ReadonlySet<BudgetLedgerState>>>;
+export declare function validateIntentTransition(fromState: PaymentIntentState, toState: PaymentIntentState, options?: {
+    intentId?: string;
+}): void;
+export declare function validateSettlementTransition(fromState: SettlementState, toState: SettlementState, options?: {
+    settlementId?: string;
+}): void;
+export declare function validateFulfillmentTransition(fromState: FulfillmentState, toState: FulfillmentState): void;
+export declare function validateLedgerTransition(fromState: BudgetLedgerState, toState: BudgetLedgerState): void;
+export declare function validateCompositeState(intentState: PaymentIntentState, settlementState: SettlementState, fulfillmentState: FulfillmentState, ledgerState?: BudgetLedgerState | null): void;
+//# sourceMappingURL=guards.d.ts.map

package/dist/state/guards.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"guards.d.ts","sourceRoot":"","sources":["../../src/state/guards.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EACL,iBAAiB,EACjB,gBAAgB,EAChB,kBAAkB,EAClB,eAAe,EAChB,MAAM,kBAAkB,CAAC;AAY1B,eAAO,MAAM,wBAAwB,EAAE,QAAQ,CAAC,MAAM,CAAC,kBAAkB,EAAE,WAAW,CAAC,kBAAkB,CAAC,CAAC,CAoCzG,CAAC;AAEH,eAAO,MAAM,4BAA4B,EAAE,QAAQ,CAAC,MAAM,CAAC,eAAe,EAAE,WAAW,CAAC,eAAe,CAAC,CAAC,CAuCvG,CAAC;AAEH,eAAO,MAAM,6BAA6B,EAAE,QAAQ,CAAC,MAAM,CAAC,gBAAgB,EAAE,WAAW,CAAC,gBAAgB,CAAC,CAAC,CA8B1G,CAAC;AAEH,eAAO,MAAM,wBAAwB,EAAE,QAAQ,CAAC,MAAM,CAAC,iBAAiB,EAAE,WAAW,CAAC,iBAAiB,CAAC,CAAC,CAQvG,CAAC;AAMH,wBAAgB,wBAAwB,CACtC,SAAS,EAAE,kBAAkB,EAC7B,OAAO,EAAE,kBAAkB,EAC3B,OAAO,CAAC,EAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,GAC9B,IAAI,CAsBN;AAED,wBAAgB,4BAA4B,CAC1C,SAAS,EAAE,eAAe,EAC1B,OAAO,EAAE,eAAe,EACxB,OAAO,CAAC,EAAE;IAAE,YAAY,CAAC,EAAE,MAAM,CAAA;CAAE,GAClC,IAAI,CAyBN;AAED,wBAAgB,6BAA6B,CAC3C,SAAS,EAAE,gBAAgB,EAC3B,OAAO,EAAE,gBAAgB,GACxB,IAAI,CAcN;AAED,wBAAgB,wBAAwB,CACtC,SAAS,EAAE,iBAAiB,EAC5B,OAAO,EAAE,iBAAiB,GACzB,IAAI,CAcN;AAMD,wBAAgB,sBAAsB,CACpC,WAAW,EAAE,kBAAkB,EAC/B,eAAe,EAAE,eAAe,EAChC,gBAAgB,EAAE,gBAAgB,EAClC,WAAW,CAAC,EAAE,iBAAiB,GAAG,IAAI,GACrC,IAAI,CAqDN"}