@subly_fi/pay 0.4.0 → 0.5.0

package/README.md

@@ -5,12 +5,20 @@ Subly client for [x402](https://x402.org)-style HTTP payments funded by
 deposited USDC, and the principal is never spent. Non-custodial: it signs
 locally with your own Solana key; Subly never holds it.
 
+Current payments target standard x402 sellers that offer a Solana USDC `exact`
+rail with facilitator `extra.feePayer` support.
+
 Ships one `pay` dispatcher bin with subcommands, all runnable with `npx` (no clone):
 
 - `pay mcp` — an MCP server (Claude Code, Cursor, any MCP client) exposing
-  the full lifecycle as tools: `deposit_to_subly_vault`,
+  the full lifecycle as tools: `create_subly_setup_link` /
+  `check_subly_setup` (owner onboarding: the human approves the spending
+  mandate + first deposit with one Face ID), `deposit_to_subly_vault`,
   `get_subly_yield_budget`, `fetch_with_subly_payment`,
-  `withdraw_from_subly_vault`
+  `withdraw_from_subly_vault`. Payments above the owner's approval
+  threshold, deposits, and (when the mandate opts in) withdrawals return an
+  `approveUrl` to paste into chat; retry with the `approvalId` once the
+  human approved.
 - `pay fetch <url>` — one-shot: pay for a URL, print the receipt (used by the
   OpenClaw skill)
 - `pay deposit <amountRawUsdc>` / `pay withdraw <amountRawUsdc>` — vault
@@ -26,11 +34,11 @@ export SUBLY_DEMO_AGENT_KEYPAIR_PATH=~/.subly/agent.json
 ```
 
 Send USDC (Solana mainnet) to the printed address — no SOL needed, fees are
-sponsored — then deposit (vault minimum 1 USDC; deposit self-registers the
-wallet):
+sponsored — then deposit (vault minimum is just over 1 USDC: share rounding
+refuses exactly 1.000000; deposit self-registers the wallet):
 
 ```bash
-npx -y @subly_fi/pay deposit 1000000   # 1 USDC
+npx -y @subly_fi/pay deposit 1010000   # 1.01 USDC
 ```
 
 ## Use it

package/dist/deposit.js

@@ -993,7 +993,7 @@ var OnboardingError = class extends Error {
 };
 async function ensureWalletOnboarded(params) {
   const fetchImpl = params.fetchImpl ?? fetch;
-  const baseUrl = params.facilitatorBaseUrl.replace(/\/$/, "");
+  const baseUrl = params.relayerBaseUrl.replace(/\/$/, "");
   const post = async (step, path, body) => {
     const url = `${baseUrl}${path}`;
     const serialized = JSON.stringify(body);
@@ -1078,14 +1078,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;
@@ -1095,19 +1099,44 @@ var VaultFlowClient = class {
   pollTimeoutMs;
   pollIntervalMs;
   constructor(config) {
-    this.baseUrl = config.facilitatorBaseUrl.replace(/\/$/, "");
+    this.baseUrl = config.relayerBaseUrl.replace(/\/$/, "");
     this.signer = config.signer;
     this.fetchImpl = config.fetchImpl ?? fetch;
     this.lookupTablesFor = config.lookupTablesFor ?? ((serializedTransaction) => fetchLookupTablesForTransaction(config.rpc, serializedTransaction));
     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,
@@ -1146,7 +1175,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({
@@ -1225,6 +1256,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.
@@ -1274,10 +1369,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 {
@@ -1290,7 +1388,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";
@@ -1353,14 +1493,14 @@ var rpc = createRpc(
   process.env.SOLANA_RPC_URL ?? "https://api.mainnet-beta.solana.com"
 );
 var vaultFlows = new VaultFlowClient({
-  facilitatorBaseUrl: relayerBaseUrl,
+  relayerBaseUrl,
   signer,
   rpc
 });
 console.log(`[deposit] agent wallet: ${signer.walletAddress}`);
 console.log(`[deposit] relayer:  ${relayerBaseUrl}`);
 console.log("\n[deposit] step 0: ensure the wallet is registered (self-serve)");
-await ensureWalletOnboarded({ facilitatorBaseUrl: relayerBaseUrl, signer });
+await ensureWalletOnboarded({ relayerBaseUrl, signer });
 console.log("[deposit] wallet registered and synced");
 console.log(
   `