@aifinpay/agent 2.3.0 → 2.5.0

package/dist/spendLedger.d.ts

@@ -1,54 +1,95 @@
+/** Exact trusted purchase context; a quote cannot select the ledger or cap. */
+export interface SpendLedgerBinding {
+    apiBaseUrl: string;
+    paymentIssuer: string;
+    payer: string;
+    merchantId: string;
+    scope: string;
+    resource: string;
+    networkMode: string;
+    chain: string;
+    asset: string;
+    token: string;
+    grossAmount: string;
+    quoteId: string;
+    /** Trusted factory identity shared by EVM/Solana payer keys. */
+    walletIdentity?: string;
+    /** Independently sourced pre-sign rate/cap, bound only for Solana accounting. */
+    solanaAdmissionRateUsd?: string;
+    solanaMaxFeeLamports?: string;
+    solanaTransactionFeeLamports?: string;
+    /** Makes older parsers refuse the durable pre-quote phase. */
+    quoteAdmissionVersion?: "1";
+}
+export interface QuoteAdmission {
+    id: string;
+    ownerContext: string;
+    requestBody: string;
+    statement: string;
+    quoteJson?: string;
+    phase: "pending" | "monetary" | "terminal";
+    terminal?: "not-admitted" | "expired-unbroadcast";
+    wasReserved?: true;
+    originalBinding: SpendLedgerBinding;
+}
 export interface SpendLedger {
-    /**
-     * Claim `usd` of the cap, atomically, or refuse.
-     *
-     * The cap is checked here rather than by the caller because a caller that
-     * checks and then reserves has reintroduced the race this exists to close.
-     * Returns a reservation id, or null when the window total would exceed `cap`.
-     */
-    reserve(usd: number, cap: number, windowMs: number): Promise<string | null>;
-    /** The payment happened. `actualUsd` corrects the estimate when known. */
+    reserve(usd: number, cap: number, windowMs: number, binding?: SpendLedgerBinding, admissionId?: string): Promise<string | null>;
+    beginQuoteAdmission?(binding: SpendLedgerBinding, ownerContext: string, create: () => Promise<{
+        requestBody: string;
+        statement: string;
+    }>): Promise<QuoteAdmission>;
+    adoptQuoteAdmission?(id: string, binding: SpendLedgerBinding, ownerContext: string, quoteJson: string): Promise<void>;
+    closeQuoteAdmission?(id: string, binding: SpendLedgerBinding, ownerContext: string, terminal: "not-admitted" | "expired-unbroadcast", quoteJson?: string): Promise<void>;
     commit(id: string, actualUsd?: number): Promise<void>;
-    /** The payment did not happen. Give the budget back now, not at expiry. */
+    /** Caller must prove settlement never broadcast or reverted. */
     release(id: string): Promise<void>;
-    /** Settled plus outstanding, over the window. */
     total(windowMs: number): Promise<number>;
+    /** Required by capped v1.4 callers; old custom adapters fail before broadcast. */
+    prepare?(id: string, txRef: string, binding: SpendLedgerBinding): Promise<void>;
+    assertRecovery?(id: string, txRef: string, binding: SpendLedgerBinding): Promise<void>;
+    complete?(id: string, txRef: string, binding: SpendLedgerBinding): Promise<void>;
+    /** Exact canonical finalized failure only; retains an immutable fee-only ID. */
+    finalizeFailure?(id: string, txRef: string, binding: SpendLedgerBinding, feeUsd: number): Promise<void>;
 }
-/**
- * In-process ledger. Correct for one process, forgotten on restart.
- *
- * Kept because it is the right answer when no daily cap is set — there is
- * nothing to remember — and because a test should not need a filesystem.
- */
+/** One-process implementation; use one shared instance or the local file ledger. */
 export declare class MemorySpendLedger implements SpendLedger {
     private entries;
-    reserve(usd: number, cap: number, windowMs: number): Promise<string | null>;
+    private tail;
+    private serial;
+    reserve(usd: number, cap: number, windowMs: number, binding?: SpendLedgerBinding, admissionId?: string): Promise<string | null>;
     commit(id: string, actualUsd?: number): Promise<void>;
     release(id: string): Promise<void>;
     total(windowMs: number): Promise<number>;
+    prepare(id: string, txRef: string, binding: SpendLedgerBinding): Promise<void>;
+    assertRecovery(id: string, txRef: string, binding: SpendLedgerBinding): Promise<void>;
+    complete(id: string, txRef: string, binding: SpendLedgerBinding): Promise<void>;
+    finalizeFailure(id: string, txRef: string, binding: SpendLedgerBinding, feeUsd: number): Promise<void>;
+    beginQuoteAdmission(binding: SpendLedgerBinding, context: string, create: () => Promise<{
+        requestBody: string;
+        statement: string;
+    }>): Promise<QuoteAdmission>;
+    adoptQuoteAdmission(id: string, binding: SpendLedgerBinding, context: string, quoteJson: string): Promise<void>;
+    closeQuoteAdmission(id: string, binding: SpendLedgerBinding, context: string, terminal: "not-admitted" | "expired-unbroadcast", quoteJson?: string): Promise<void>;
 }
-/**
- * A ledger on disk, so a restart does not hand the agent its allowance again.
- *
- * Read-modify-write is guarded by an exclusive lock file, which is atomic on a
- * local filesystem: `open(..., "wx")` either creates the file or fails, with no
- * window in between. That covers several processes on one host, which is what
- * a restart, a cron and a worker pool actually are.
- *
- * It does NOT cover several hosts — a lock file on a network filesystem is not
- * a lock. An agent fleet spanning machines should pass its own SpendLedger
- * backed by something that can answer for all of them; that is why this is an
- * interface rather than a class the SDK insists on.
- */
+/** Shared cap for processes on one local filesystem; never a cross-host lock. */
 export declare class FileSpendLedger implements SpendLedger {
     private readonly path;
     constructor(path: string);
-    /** Default location, one file per agent address. */
     static forAgent(address: string): FileSpendLedger;
     private withLock;
-    reserve(usd: number, cap: number, windowMs: number): Promise<string | null>;
+    reserve(usd: number, cap: number, windowMs: number, binding?: SpendLedgerBinding, admissionId?: string): Promise<string | null>;
     commit(id: string, actualUsd?: number): Promise<void>;
     release(id: string): Promise<void>;
     total(windowMs: number): Promise<number>;
+    prepare(id: string, txRef: string, binding: SpendLedgerBinding): Promise<void>;
+    assertRecovery(id: string, txRef: string, binding: SpendLedgerBinding): Promise<void>;
+    complete(id: string, txRef: string, binding: SpendLedgerBinding): Promise<void>;
+    finalizeFailure(id: string, txRef: string, binding: SpendLedgerBinding, feeUsd: number): Promise<void>;
+    beginQuoteAdmission(binding: SpendLedgerBinding, context: string, create: () => Promise<{
+        requestBody: string;
+        statement: string;
+    }>): Promise<QuoteAdmission>;
+    adoptQuoteAdmission(id: string, binding: SpendLedgerBinding, context: string, quoteJson: string): Promise<void>;
+    closeQuoteAdmission(id: string, binding: SpendLedgerBinding, context: string, terminal: "not-admitted" | "expired-unbroadcast", quoteJson?: string): Promise<void>;
 }
 //# sourceMappingURL=spendLedger.d.ts.map

package/dist/spendLedger.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"spendLedger.d.ts","sourceRoot":"","sources":["../src/spendLedger.ts"],"names":[],"mappings":"AAsCA,MAAM,WAAW,WAAW;IAC1B;;;;;;OAMG;IACH,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAC5E,0EAA0E;IAC1E,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACtD,2EAA2E;IAC3E,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACnC,iDAAiD;IACjD,KAAK,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CAC1C;AAgBD;;;;;GAKG;AACH,qBAAa,iBAAkB,YAAW,WAAW;IACnD,OAAO,CAAC,OAAO,CAAe;IAExB,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAS3E,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAOrD,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIlC,KAAK,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;CAG/C;AAED;;;;;;;;;;;;GAYG;AACH,qBAAa,eAAgB,YAAW,WAAW;IACrC,OAAO,CAAC,QAAQ,CAAC,IAAI;gBAAJ,IAAI,EAAE,MAAM;IAEzC,oDAAoD;IACpD,MAAM,CAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,eAAe;YAKnC,QAAQ;IAiDhB,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAa3E,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAYrD,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAOlC,KAAK,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;CAO/C"}
+{"version":3,"file":"spendLedger.d.ts","sourceRoot":"","sources":["../src/spendLedger.ts"],"names":[],"mappings":"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"}