@subly_fi/pay 0.4.1 → 0.5.0

package/dist/pay.js

@@ -1083,14 +1083,18 @@ async function fetchLookupTablesForTransaction(rpc2, serializedTransaction) {
 
 // ../../src/client/vault-flows.ts
 var VaultFlowClientError = class extends Error {
-  constructor(step, message, detail = null) {
+  constructor(step, message, detail = null, code = null, errorDetails = null) {
     super(message);
     this.step = step;
     this.detail = detail;
+    this.code = code;
+    this.errorDetails = errorDetails;
     this.name = "VaultFlowClientError";
   }
   step;
   detail;
+  code;
+  errorDetails;
 };
 var VaultFlowClient = class {
   baseUrl;
@@ -1107,12 +1111,37 @@ var VaultFlowClient = class {
     this.pollTimeoutMs = config.pollTimeoutMs ?? 9e4;
     this.pollIntervalMs = config.pollIntervalMs ?? 2500;
   }
-  /** Moves USDC from the agent wallet into the vault (fee sponsored). */
+  /**
+   * Moves USDC from the agent wallet into the vault (fee sponsored). Under
+   * depositPolicy "owner_approval_required" the relayer refuses to prepare
+   * without an owner approval; when the caller passes none, an already
+   * APPROVED deposit approval for this exact amount (e.g. the mandate's
+   * initialDeposit — "one Face ID covers mandate + first deposit") is looked
+   * up and used automatically before surfacing deposit_approval_required.
+   */
   async deposit(input) {
-    const prepared = await this.postJson("prepare", "/v1/deposits/prepare", {
-      wallet: this.signer.walletAddress,
-      amountRawUsdc: input.amountRawUsdc.toString()
-    });
+    let approvalId = input.approvalId;
+    let prepared;
+    try {
+      prepared = await this.postJson("prepare", "/v1/deposits/prepare", {
+        wallet: this.signer.walletAddress,
+        amountRawUsdc: input.amountRawUsdc.toString(),
+        ...approvalId === void 0 ? {} : { approvalId }
+      });
+    } catch (error) {
+      if (!(error instanceof VaultFlowClientError) || error.code !== "deposit_approval_required" || approvalId !== void 0) {
+        throw error;
+      }
+      approvalId = await this.findApprovedDepositApproval(input.amountRawUsdc);
+      if (approvalId === void 0) {
+        throw error;
+      }
+      prepared = await this.postJson("prepare", "/v1/deposits/prepare", {
+        wallet: this.signer.walletAddress,
+        amountRawUsdc: input.amountRawUsdc.toString(),
+        approvalId
+      });
+    }
     const signed = await this.signer.signDeposit({
       intent: prepared.signingIntent,
       serializedTransaction: prepared.serializedTransaction,
@@ -1151,7 +1180,9 @@ var VaultFlowClient = class {
       {
         wallet: this.signer.walletAddress,
         amountRawUsdc: input.amountRawUsdc.toString(),
-        ...input.purpose === void 0 ? {} : { purpose: input.purpose }
+        ...input.purpose === void 0 ? {} : { purpose: input.purpose },
+        ...input.payment === void 0 ? {} : { payment: input.payment },
+        ...input.approvalId === void 0 ? {} : { approvalId: input.approvalId }
       }
     );
     const signed = await this.signer.signWithdrawal({
@@ -1230,6 +1261,70 @@ var VaultFlowClient = class {
       spendableYieldRawUsdc: body2.budget?.spendableYieldRawUsdc ?? "0"
     };
   }
+  /** Best-effort audit link: reports the x402 payment tx a realize funded. */
+  async reportPayment(input) {
+    await this.postJson("submit", "/v1/payments/report", {
+      wallet: this.signer.walletAddress,
+      withdrawalId: input.withdrawalId,
+      paymentTxSignature: input.paymentTxSignature
+    });
+  }
+  /** Wallet's approvals as the relayer sees them (optionally by status). */
+  async listApprovals(status) {
+    const body2 = await this.getJson(
+      `/v1/wallets/${this.signer.walletAddress}/approvals${status === void 0 ? "" : `?status=${encodeURIComponent(status)}`}`
+    );
+    return body2.approvals ?? [];
+  }
+  /**
+   * Creates the owner-onboarding setup link (wallet-auth pins the agreed
+   * policy + initial deposit). Paste `setupUrl` into the chat verbatim.
+   */
+  async createSetupSession(input) {
+    return await this.postJson(
+      "prepare",
+      `/v1/wallets/${this.signer.walletAddress}/setup-sessions`,
+      {
+        ...input.policy === void 0 ? {} : { policy: input.policy },
+        ...input.enforcementMode === void 0 ? {} : { enforcementMode: input.enforcementMode },
+        ...input.mandateTtlDays === void 0 ? {} : { mandateTtlDays: input.mandateTtlDays },
+        ...input.initialDepositRawUsdc === void 0 ? {} : { initialDepositRawUsdc: input.initialDepositRawUsdc }
+      }
+    );
+  }
+  /** Polls a setup session (public capability URL — no auth needed). */
+  async getSetupSession(sessionId) {
+    const url2 = `${this.baseUrl}/v1/setup-sessions/${encodeURIComponent(sessionId)}`;
+    const response = await this.fetchImpl(url2);
+    const text = await response.text();
+    if (response.status !== 200) {
+      const parsed = parseRelayerError(text);
+      throw new VaultFlowClientError(
+        "read",
+        parsed.message ?? `setup session read failed with ${response.status}`,
+        text,
+        parsed.code,
+        parsed.details
+      );
+    }
+    return JSON.parse(text);
+  }
+  /**
+   * Finds an APPROVED, unconsumed deposit approval bound to exactly this
+   * amount — the shape the mandate's initialDeposit approval has.
+   */
+  async findApprovedDepositApproval(amountRawUsdc) {
+    try {
+      const approvals = await this.listApprovals("approved");
+      const match = approvals.find((approval) => {
+        const binding = approval.binding;
+        return binding?.kind === "deposit" && binding.amountRawUsdc === amountRawUsdc.toString();
+      });
+      return match?.approvalId;
+    } catch {
+      return void 0;
+    }
+  }
   /**
    * Polls the reconciling GET endpoint until the intent leaves "submitted"
    * (each read looks the tx up on-chain) or the timeout elapses.
@@ -1279,10 +1374,13 @@ var VaultFlowClient = class {
     });
     const text = await response.text();
     if (response.status !== 200) {
+      const parsed = parseRelayerError(text);
       throw new VaultFlowClientError(
         step,
-        `${path} failed with ${response.status}: ${text}`,
-        text
+        parsed.message === null ? `${path} failed with ${response.status}: ${text}` : `${path} failed (${parsed.code ?? response.status}): ${parsed.message}`,
+        text,
+        parsed.code,
+        parsed.details
       );
     }
     try {
@@ -1295,7 +1393,49 @@ var VaultFlowClient = class {
       );
     }
   }
+  async getJson(path) {
+    const url2 = `${this.baseUrl}${path}`;
+    const response = await this.fetchImpl(url2, {
+      headers: await walletAuthHeaders({
+        signer: this.signer,
+        method: "GET",
+        url: url2
+      })
+    });
+    const text = await response.text();
+    if (response.status !== 200) {
+      const parsed = parseRelayerError(text);
+      throw new VaultFlowClientError(
+        "read",
+        parsed.message === null ? `${path} failed with ${response.status}: ${text}` : `${path} failed (${parsed.code ?? response.status}): ${parsed.message}`,
+        text,
+        parsed.code,
+        parsed.details
+      );
+    }
+    try {
+      return JSON.parse(text);
+    } catch {
+      throw new VaultFlowClientError(
+        "read",
+        `${path} returned 200 with a non-JSON body`,
+        text
+      );
+    }
+  }
 };
+function parseRelayerError(text) {
+  try {
+    const parsed = JSON.parse(text);
+    return {
+      code: typeof parsed.error?.code === "string" ? parsed.error.code : null,
+      message: typeof parsed.error?.message === "string" ? parsed.error.message : null,
+      details: parsed.error?.details ?? null
+    };
+  } catch {
+    return { code: null, message: null, details: null };
+  }
+}
 
 // ../../src/client/relayer-yield-realizer.ts
 var REALIZE_OVERHEAD_RAW_USDC = 2500n;
@@ -1329,7 +1469,11 @@ var RelayerYieldRealizer = class {
         amountRawUsdc: shortfallRawUsdc,
         // The relayer refuses to prepare this withdrawal beyond the spendable
         // yield — the principal-protection guard the client cannot bypass.
-        purpose: "yield_realize"
+        purpose: "yield_realize",
+        // Declares what is being paid so the relayer's spending-mandate layer
+        // can enforce caps/payee and keep the mandate → payment audit chain.
+        ...input.payment === void 0 ? {} : { payment: input.payment },
+        ...input.approvalId === void 0 ? {} : { approvalId: input.approvalId }
       });
     } catch (error) {
       throw this.mapWithdrawError(error);
@@ -1343,9 +1487,18 @@ var RelayerYieldRealizer = class {
     }
     return {
       realizedRawUsdc: BigInt(outcome.actualWithdrawRawUsdc ?? "0"),
-      txSignature: outcome.txSignature
+      txSignature: outcome.txSignature,
+      withdrawalId: outcome.withdrawalId
     };
   }
+  /**
+   * Best-effort report-back of the x402 payment tx this realize funded —
+   * closes the relayer's mandate → realize → payment audit chain. Callers
+   * must never let a failure here affect the payment result.
+   */
+  async reportPayment(input) {
+    await this.vaultFlows.reportPayment(input);
+  }
   /**
    * Refuses to realize more than the ledger's spendable yield (principal).
    * getBudget syncs the relayer's ledger from chain first (best-effort), so a
@@ -1380,7 +1533,14 @@ var RelayerYieldRealizer = class {
         error
       );
     }
-    const serverCode = errorCodeFrom(error.detail);
+    const serverCode = error.code ?? errorCodeFrom(error.detail);
+    if (serverCode === "approval_required") {
+      return new RelayerRealizeError(
+        "approval_required",
+        "this payment exceeds the owner-approval threshold; nothing was realized or paid. Ask the owner to approve, then retry with the approvalId",
+        error.errorDetails ?? error.detail
+      );
+    }
     if (serverCode === "insufficient_yield" || serverCode === "post_state_principal_invariant_failed") {
       return new RelayerRealizeError(
         "insufficient_yield",
@@ -1407,6 +1567,12 @@ function errorCodeFrom(detail) {
   }
 }
 
+// ../../src/lib/canonical-json.ts
+import { createHash as createHash4 } from "node:crypto";
+function sha256HexOf(data) {
+  return createHash4("sha256").update(data, "utf8").digest("hex");
+}
+
 // ../../src/x402/headers.ts
 import { z } from "zod";
 var PAYMENT_REQUIRED_HEADER = "payment-required";
@@ -1547,20 +1713,36 @@ function decodeStandardPaymentRequiredHeader(headerValue) {
 function selectPayableSolanaRequirement(requirements, options) {
   const network = options?.network ?? SOLANA_MAINNET_NETWORK;
   const usdcMint = options?.usdcMint ?? SUBLY_VAULT.usdcMint;
-  const requirement = requirements.find(
+  const matchingRequirements = requirements.filter(
     (candidate) => candidate.network === network && candidate.asset === usdcMint
-  ) ?? null;
-  if (requirement === null) {
+  );
+  if (matchingRequirements.length === 0) {
     throw new StandardX402ChallengeError(
       "no_payable_requirement",
       `The challenge has no Solana exact requirement on ${network} paying ${usdcMint}`
     );
   }
+  const requirement = matchingRequirements.find(
+    (candidate) => candidate.extra?.feePayer !== void 0
+  ) ?? null;
+  if (requirement === null) {
+    throw new StandardX402ChallengeError(
+      "missing_svm_fee_payer",
+      "The Solana exact requirement does not include extra.feePayer, which the official @x402/svm client requires for gas sponsorship"
+    );
+  }
+  const feePayer = requirement.extra?.feePayer;
+  if (feePayer === void 0) {
+    throw new StandardX402ChallengeError(
+      "missing_svm_fee_payer",
+      "The Solana exact requirement does not include extra.feePayer, which the official @x402/svm client requires for gas sponsorship"
+    );
+  }
   return {
     requirement,
     amountRawUsdc: BigInt(requirement.amount),
     payTo: requirement.payTo,
-    feePayer: requirement.extra?.feePayer ?? null
+    feePayer
   };
 }
 function standardRequirementMatchesSelected(candidate, selected) {
@@ -1683,9 +1865,23 @@ var StandardX402Payer = class {
     let realized;
     try {
       realized = await this.realizer.ensureUsdcAvailable({
-        amountRawUsdc: selected.amountRawUsdc
+        amountRawUsdc: selected.amountRawUsdc,
+        payment: {
+          payTo: selected.payTo,
+          amountRawUsdc: selected.amountRawUsdc.toString(),
+          resourceUrlHash: sha256HexOf(input.url),
+          method: method2
+        },
+        ...input.approvalId === void 0 ? {} : { approvalId: input.approvalId }
       });
     } catch (error) {
+      if (error.code === "approval_required") {
+        throw new StandardX402PayError(
+          "approval_required",
+          "this payment exceeds the owner-approval threshold; NOTHING was paid. Ask the owner to open the approveUrl, then retry the same call with the approvalId",
+          error.detail ?? null
+        );
+      }
       throw new StandardX402PayError(
         "realize_failed",
         `could not realize yield to cover ${selected.amountRawUsdc} raw USDC: ${error instanceof Error ? error.message : String(error)}`,
@@ -1741,6 +1937,19 @@ var StandardX402Payer = class {
       );
     }
     this.clearDelivered(pendingKey);
+    const paymentTxSignature = extractSettledPaymentTxSignature(response);
+    if (paymentTxSignature !== null && typeof realized.withdrawalId === "string" && this.realizer.reportPayment !== void 0) {
+      try {
+        await this.realizer.reportPayment({
+          withdrawalId: realized.withdrawalId,
+          paymentTxSignature
+        });
+      } catch (error) {
+        console.error(
+          `[subly-x402] payment report-back failed (audit only, payment ok): ${error instanceof Error ? error.message : String(error)}`
+        );
+      }
+    }
     return {
       paid: true,
       status: response.status,
@@ -1750,7 +1959,8 @@ var StandardX402Payer = class {
         payTo: selected.payTo,
         feePayer: selected.feePayer,
         realizedRawUsdc: realized.realizedRawUsdc.toString(),
-        realizeTxSignature: realized.txSignature
+        realizeTxSignature: realized.txSignature,
+        paymentTxSignature
       }
     };
   }
@@ -1864,6 +2074,26 @@ var StandardX402Payer = class {
 function pendingPaymentKey(input) {
   return `${input.method}:${input.url}:${input.requestBodyHash}`;
 }
+function extractSettledPaymentTxSignature(response) {
+  const header = response.headers.get("x-payment-response");
+  if (header === null || header.length === 0) {
+    return null;
+  }
+  try {
+    const decoded = JSON.parse(
+      Buffer.from(header, "base64").toString("utf8")
+    );
+    if (typeof decoded.transaction === "string" && decoded.transaction.length > 0) {
+      return decoded.transaction;
+    }
+    if (typeof decoded.txHash === "string" && decoded.txHash.length > 0) {
+      return decoded.txHash;
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
 
 // ../../src/client/relayer-payer.ts
 function createRelayerX402Payer(config) {

package/dist/withdraw.js

@@ -1021,14 +1021,18 @@ async function walletAuthHeaders(params) {
 
 // ../../src/client/vault-flows.ts
 var VaultFlowClientError = class extends Error {
-  constructor(step, message, detail = null) {
+  constructor(step, message, detail = null, code = null, errorDetails = null) {
     super(message);
     this.step = step;
     this.detail = detail;
+    this.code = code;
+    this.errorDetails = errorDetails;
     this.name = "VaultFlowClientError";
   }
   step;
   detail;
+  code;
+  errorDetails;
 };
 var VaultFlowClient = class {
   baseUrl;
@@ -1045,12 +1049,37 @@ var VaultFlowClient = class {
     this.pollTimeoutMs = config.pollTimeoutMs ?? 9e4;
     this.pollIntervalMs = config.pollIntervalMs ?? 2500;
   }
-  /** Moves USDC from the agent wallet into the vault (fee sponsored). */
+  /**
+   * Moves USDC from the agent wallet into the vault (fee sponsored). Under
+   * depositPolicy "owner_approval_required" the relayer refuses to prepare
+   * without an owner approval; when the caller passes none, an already
+   * APPROVED deposit approval for this exact amount (e.g. the mandate's
+   * initialDeposit — "one Face ID covers mandate + first deposit") is looked
+   * up and used automatically before surfacing deposit_approval_required.
+   */
   async deposit(input) {
-    const prepared = await this.postJson("prepare", "/v1/deposits/prepare", {
-      wallet: this.signer.walletAddress,
-      amountRawUsdc: input.amountRawUsdc.toString()
-    });
+    let approvalId = input.approvalId;
+    let prepared;
+    try {
+      prepared = await this.postJson("prepare", "/v1/deposits/prepare", {
+        wallet: this.signer.walletAddress,
+        amountRawUsdc: input.amountRawUsdc.toString(),
+        ...approvalId === void 0 ? {} : { approvalId }
+      });
+    } catch (error) {
+      if (!(error instanceof VaultFlowClientError) || error.code !== "deposit_approval_required" || approvalId !== void 0) {
+        throw error;
+      }
+      approvalId = await this.findApprovedDepositApproval(input.amountRawUsdc);
+      if (approvalId === void 0) {
+        throw error;
+      }
+      prepared = await this.postJson("prepare", "/v1/deposits/prepare", {
+        wallet: this.signer.walletAddress,
+        amountRawUsdc: input.amountRawUsdc.toString(),
+        approvalId
+      });
+    }
     const signed = await this.signer.signDeposit({
       intent: prepared.signingIntent,
       serializedTransaction: prepared.serializedTransaction,
@@ -1089,7 +1118,9 @@ var VaultFlowClient = class {
       {
         wallet: this.signer.walletAddress,
         amountRawUsdc: input.amountRawUsdc.toString(),
-        ...input.purpose === void 0 ? {} : { purpose: input.purpose }
+        ...input.purpose === void 0 ? {} : { purpose: input.purpose },
+        ...input.payment === void 0 ? {} : { payment: input.payment },
+        ...input.approvalId === void 0 ? {} : { approvalId: input.approvalId }
       }
     );
     const signed = await this.signer.signWithdrawal({
@@ -1168,6 +1199,70 @@ var VaultFlowClient = class {
       spendableYieldRawUsdc: body.budget?.spendableYieldRawUsdc ?? "0"
     };
   }
+  /** Best-effort audit link: reports the x402 payment tx a realize funded. */
+  async reportPayment(input) {
+    await this.postJson("submit", "/v1/payments/report", {
+      wallet: this.signer.walletAddress,
+      withdrawalId: input.withdrawalId,
+      paymentTxSignature: input.paymentTxSignature
+    });
+  }
+  /** Wallet's approvals as the relayer sees them (optionally by status). */
+  async listApprovals(status) {
+    const body = await this.getJson(
+      `/v1/wallets/${this.signer.walletAddress}/approvals${status === void 0 ? "" : `?status=${encodeURIComponent(status)}`}`
+    );
+    return body.approvals ?? [];
+  }
+  /**
+   * Creates the owner-onboarding setup link (wallet-auth pins the agreed
+   * policy + initial deposit). Paste `setupUrl` into the chat verbatim.
+   */
+  async createSetupSession(input) {
+    return await this.postJson(
+      "prepare",
+      `/v1/wallets/${this.signer.walletAddress}/setup-sessions`,
+      {
+        ...input.policy === void 0 ? {} : { policy: input.policy },
+        ...input.enforcementMode === void 0 ? {} : { enforcementMode: input.enforcementMode },
+        ...input.mandateTtlDays === void 0 ? {} : { mandateTtlDays: input.mandateTtlDays },
+        ...input.initialDepositRawUsdc === void 0 ? {} : { initialDepositRawUsdc: input.initialDepositRawUsdc }
+      }
+    );
+  }
+  /** Polls a setup session (public capability URL — no auth needed). */
+  async getSetupSession(sessionId) {
+    const url = `${this.baseUrl}/v1/setup-sessions/${encodeURIComponent(sessionId)}`;
+    const response = await this.fetchImpl(url);
+    const text = await response.text();
+    if (response.status !== 200) {
+      const parsed = parseRelayerError(text);
+      throw new VaultFlowClientError(
+        "read",
+        parsed.message ?? `setup session read failed with ${response.status}`,
+        text,
+        parsed.code,
+        parsed.details
+      );
+    }
+    return JSON.parse(text);
+  }
+  /**
+   * Finds an APPROVED, unconsumed deposit approval bound to exactly this
+   * amount — the shape the mandate's initialDeposit approval has.
+   */
+  async findApprovedDepositApproval(amountRawUsdc2) {
+    try {
+      const approvals = await this.listApprovals("approved");
+      const match = approvals.find((approval) => {
+        const binding = approval.binding;
+        return binding?.kind === "deposit" && binding.amountRawUsdc === amountRawUsdc2.toString();
+      });
+      return match?.approvalId;
+    } catch {
+      return void 0;
+    }
+  }
   /**
    * Polls the reconciling GET endpoint until the intent leaves "submitted"
    * (each read looks the tx up on-chain) or the timeout elapses.
@@ -1217,10 +1312,13 @@ var VaultFlowClient = class {
     });
     const text = await response.text();
     if (response.status !== 200) {
+      const parsed = parseRelayerError(text);
       throw new VaultFlowClientError(
         step,
-        `${path} failed with ${response.status}: ${text}`,
-        text
+        parsed.message === null ? `${path} failed with ${response.status}: ${text}` : `${path} failed (${parsed.code ?? response.status}): ${parsed.message}`,
+        text,
+        parsed.code,
+        parsed.details
       );
     }
     try {
@@ -1233,7 +1331,49 @@ var VaultFlowClient = class {
       );
     }
   }
+  async getJson(path) {
+    const url = `${this.baseUrl}${path}`;
+    const response = await this.fetchImpl(url, {
+      headers: await walletAuthHeaders({
+        signer: this.signer,
+        method: "GET",
+        url
+      })
+    });
+    const text = await response.text();
+    if (response.status !== 200) {
+      const parsed = parseRelayerError(text);
+      throw new VaultFlowClientError(
+        "read",
+        parsed.message === null ? `${path} failed with ${response.status}: ${text}` : `${path} failed (${parsed.code ?? response.status}): ${parsed.message}`,
+        text,
+        parsed.code,
+        parsed.details
+      );
+    }
+    try {
+      return JSON.parse(text);
+    } catch {
+      throw new VaultFlowClientError(
+        "read",
+        `${path} returned 200 with a non-JSON body`,
+        text
+      );
+    }
+  }
 };
+function parseRelayerError(text) {
+  try {
+    const parsed = JSON.parse(text);
+    return {
+      code: typeof parsed.error?.code === "string" ? parsed.error.code : null,
+      message: typeof parsed.error?.message === "string" ? parsed.error.message : null,
+      details: parsed.error?.details ?? null
+    };
+  } catch {
+    return { code: null, message: null, details: null };
+  }
+}
 
 // ../../src/solana/keys.ts
 import { readFileSync } from "node:fs";

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@subly_fi/pay",
-  "version": "0.4.1",
-  "description": "Subly client: pay for ANY standard x402 (HTTP 402) paid API from Kamino vault yield — the seller needs no Subly integration. Ships an MCP server and a one-shot pay/deposit CLI; non-custodial (signs locally with your own key).",
+  "version": "0.5.0",
+  "description": "Subly client: pay compatible standard x402 Solana USDC exact APIs from Kamino vault yield — the seller needs no Subly integration. Ships an MCP server and a one-shot pay/deposit CLI; non-custodial (signs locally with your own key).",
   "license": "MIT",
   "type": "module",
   "engines": {