@oneshot-agent/sdk 0.25.0 → 0.27.0

package/dist/index.js

@@ -49,7 +49,7 @@ Object.defineProperty(exports, "getSwapQuote", { enumerable: true, get: function
 Object.defineProperty(exports, "executeSwap", { enumerable: true, get: function () { return swap_1.executeSwap; } });
 __exportStar(require("./errors"), exports);
 // Keep in sync with package.json `version`. Guarded by version.test.ts.
-const SDK_VERSION = '0.25.0';
+const SDK_VERSION = '0.27.0';
 // ============================================================================
 // Environment Configuration
 // ============================================================================
@@ -76,6 +76,39 @@ __exportStar(require("./types"), exports);
  * await agent.email({ to: 'user@example.com', subject: 'Hi', body: 'Hello' });
  * ```
  */
+/**
+ * Reject a budget config the server would reject, at construction rather than
+ * on the first paid call — a typo'd cap must not become "no cap".
+ */
+function validateBudgetConfig(budgets) {
+    if (!budgets)
+        return undefined;
+    // A typo'd key (`daliy`) from an untyped caller must not silently mean "no cap".
+    for (const key of Object.keys(budgets)) {
+        if (!['daily', 'perTransaction', 'alertAt', 'pauseAt'].includes(key)) {
+            throw new errors_1.ValidationError(`budgets.${key} is not a recognized field`, `budgets.${key}`);
+        }
+    }
+    const positive = (v, field) => {
+        if (v === undefined)
+            return;
+        if (typeof v !== 'number' || !Number.isFinite(v) || v <= 0) {
+            throw new errors_1.ValidationError(`budgets.${field} must be a positive number`, `budgets.${field}`);
+        }
+    };
+    const fraction = (v, field) => {
+        if (v === undefined)
+            return;
+        if (typeof v !== 'number' || !Number.isFinite(v) || v <= 0 || v > 1) {
+            throw new errors_1.ValidationError(`budgets.${field} must be a fraction in (0, 1]`, `budgets.${field}`);
+        }
+    };
+    positive(budgets.daily, 'daily');
+    positive(budgets.perTransaction, 'perTransaction');
+    fraction(budgets.alertAt, 'alertAt');
+    fraction(budgets.pauseAt, 'pauseAt');
+    return budgets;
+}
 class OneShot {
     /**
      * Async factory — required for CDP wallets (account creation is async).
@@ -117,6 +150,8 @@ class OneShot {
         this.logger = config.logger ?? console.log;
         this._currency = config.currency ?? 'USDC';
         this._slippage = config.slippage ?? 0.01;
+        this._budgets = validateBudgetConfig(config.budgets);
+        this._alertEmail = config.alerts?.email;
         this.rpcProvider = new ethers_1.ethers.JsonRpcProvider(config.rpcUrl ?? RPC_URL);
         if (walletProvider) {
             this.provider = walletProvider;
@@ -153,6 +188,10 @@ class OneShot {
     get slippage() {
         return this._slippage;
     }
+    /** The budget config this instance was constructed with, if any. */
+    get budgetConfig() {
+        return this._budgets;
+    }
     // ---------------------------------------------------------------------------
     // Public methods
     // ---------------------------------------------------------------------------
@@ -375,7 +414,7 @@ class OneShot {
             onQuote: (ctx) => this.log(`Commerce quote: $${ctx.total} for "${ctx.product_title}"`),
         });
         if (buyResp.status !== 202) {
-            throw new errors_1.ToolError('Commerce buy failed', buyResp.status, await buyResp.text());
+            await this.failFromResponse('Commerce buy failed', buyResp);
         }
         const result = await buyResp.json();
         this.log(`Order submitted: ${result.request_id}`);
@@ -452,7 +491,7 @@ class OneShot {
             },
         });
         if (callResp.status !== 202) {
-            throw new errors_1.ToolError('Voice call initiation failed', callResp.status, await callResp.text());
+            await this.failFromResponse('Voice call initiation failed', callResp);
         }
         const result = await callResp.json();
         this.log(`Call initiated: ${result.request_id}`);
@@ -515,7 +554,7 @@ class OneShot {
             },
         });
         if (sendResp.status !== 202) {
-            throw new errors_1.ToolError('SMS send failed', sendResp.status, await sendResp.text());
+            await this.failFromResponse('SMS send failed', sendResp);
         }
         const result = await sendResp.json();
         this.log(`SMS queued: ${result.request_id}`);
@@ -584,7 +623,7 @@ class OneShot {
             },
         });
         if (buildResp.status !== 202) {
-            throw new errors_1.ToolError('Build initiation failed', buildResp.status, await buildResp.text());
+            await this.failFromResponse('Build initiation failed', buildResp);
         }
         const result = await buildResp.json();
         this.log(`Build initiated: ${result.request_id}`);
@@ -646,7 +685,7 @@ class OneShot {
             },
         });
         if (execResp.status !== 202) {
-            throw new errors_1.ToolError('Browser task initiation failed', execResp.status, await execResp.text());
+            await this.failFromResponse('Browser task initiation failed', execResp);
         }
         const result = await execResp.json();
         this.log(`Browser task initiated: ${result.request_id}`);
@@ -911,7 +950,7 @@ class OneShot {
             },
         });
         if (createResp.status !== 202) {
-            throw new errors_1.ToolError('Compute goal creation failed', createResp.status, await createResp.text());
+            await this.failFromResponse('Compute goal creation failed', createResp);
         }
         return createResp.json();
     }
@@ -1099,13 +1138,16 @@ class OneShot {
         }
         const path = `/v1/compute/${goalId}/fund`;
         const payload = { amount };
+        await this.ensureBudgetsSynced();
         // First call: get quote (402)
         const quoteResp = await this.makeRequest(path, payload);
         if (quoteResp.status !== 402) {
-            throw new errors_1.ToolError('Expected 402 for compute fund quote', quoteResp.status, await quoteResp.text());
+            // A 403 here is the budget gate on the quote leg → BudgetExceededError.
+            await this.failFromResponse('Expected 402 for compute fund quote', quoteResp);
         }
         const quoteData = await quoteResp.json();
         this.log(`Compute fund quote: $${quoteData.payment_request.amount} to top up ${goalId}`);
+        this.assertWithinBudget(quoteData.payment_request.amount);
         const paymentInfo = {
             protocol: 'x402',
             network: `eip155:${quoteData.payment_request.chain_id}`,
@@ -1116,10 +1158,11 @@ class OneShot {
             token: { address: quoteData.payment_request.token_address, symbol: 'USDC', decimals: 6 }
         };
         const { accepted, resource, extensions } = await this.getAcceptedRequirements(quoteResp, path, payload, quoteData.context.quote_id);
+        paymentInfo.amount = this.chargeAmount(accepted, quoteData.payment_request.amount);
         const auth = await this.signPaymentAuthorization(paymentInfo, accepted, resource, extensions);
         const fundResp = await this.makeRequest(path, payload, auth, quoteData.context.quote_id);
         if (!fundResp.ok) {
-            throw new errors_1.ToolError('Failed to fund compute goal', fundResp.status, await fundResp.text());
+            await this.failFromResponse('Failed to fund compute goal', fundResp);
         }
         const json = await fundResp.json();
         return json.data;
@@ -1347,6 +1390,100 @@ class OneShot {
         }
         return qs.toString();
     }
+    /**
+     * Push `config.budgets` to the server once, before the first paid call.
+     *
+     * Lazy rather than in the constructor because the PUT is signed (async) and
+     * the constructor is sync. Idempotent per instance via the cached promise,
+     * which is only kept once the sync SUCCEEDS.
+     *
+     * FAILS CLOSED. If the server can't confirm the budget — network error,
+     * 5xx, 429, or a rejected config — this throws BudgetSyncError and the paid
+     * call is not made. Proceeding would silently drop the guardrail the
+     * developer configured, which is exactly the "empty wallet at 3am" the
+     * budget exists to prevent. The marker is cleared so the next paid call
+     * retries.
+     */
+    async ensureBudgetsSynced() {
+        if (!this._budgets && !this._alertEmail)
+            return;
+        if (this._budgetSync)
+            return this._budgetSync;
+        const attempt = (async () => {
+            const body = {};
+            if (this._budgets?.daily !== undefined)
+                body.daily = this._budgets.daily;
+            if (this._budgets?.perTransaction !== undefined)
+                body.per_transaction = this._budgets.perTransaction;
+            if (this._budgets?.alertAt !== undefined)
+                body.alert_at = this._budgets.alertAt;
+            if (this._budgets?.pauseAt !== undefined)
+                body.pause_at = this._budgets.pauseAt;
+            if (this._alertEmail !== undefined)
+                body.alert_email = this._alertEmail;
+            let response;
+            try {
+                response = await fetch(`${this.baseUrl}/v1/agents/me/budgets`, {
+                    method: 'PUT',
+                    headers: { 'Content-Type': 'application/json', ...(await this.signedReadHeaders('write')) },
+                    body: JSON.stringify(body),
+                });
+            }
+            catch (err) {
+                throw new errors_1.BudgetSyncError(`Could not sync spend budget (network): ${err}`);
+            }
+            if (!response.ok) {
+                const text = await response.text();
+                throw new errors_1.BudgetSyncError(`Could not sync spend budget (${response.status}): ${text}`, response.status, text);
+            }
+            this.log('Budget synced');
+        })();
+        this._budgetSync = attempt;
+        try {
+            await attempt;
+        }
+        catch (err) {
+            // Not synced: clear the marker so the next paid call retries, then
+            // refuse this one rather than run it unguarded.
+            this._budgetSync = undefined;
+            this.log(`${err.message} — paid call refused until the budget is confirmed`);
+            throw err;
+        }
+    }
+    /**
+     * Local fast-fail on the per-transaction cap, so an oversized call fails
+     * without a network round-trip. The server enforces the same cap (and the
+     * daily one, which needs the ledger) regardless of which client calls —
+     * this is the same SDK-checks/server-enforces split as maxCost.
+     */
+    assertWithinBudget(total) {
+        const cap = this._budgets?.perTransaction;
+        if (!cap || cap <= 0)
+            return;
+        const amount = parseFloat(total);
+        if (Number.isFinite(amount) && amount > cap) {
+            throw new errors_1.BudgetExceededError(`Quote $${total} exceeds this agent's per-transaction budget of $${cap}`, 'per_transaction', cap, undefined, amount);
+        }
+    }
+    /**
+     * Current spend budget and today's utilization.
+     *
+     * @example
+     * ```typescript
+     * const b = await agent.budgets();
+     * console.log(`${b.spent_today_usdc} of ${b.daily_usdc} spent, resets ${b.resets_at}`);
+     * ```
+     */
+    async budgets() {
+        const response = await fetch(`${this.baseUrl}/v1/agents/me/budgets`, {
+            headers: await this.signedReadHeaders(),
+        });
+        if (!response.ok) {
+            throw new errors_1.ToolError('Failed to fetch budgets', response.status, await response.text());
+        }
+        const body = await response.json();
+        return (body.data ?? body);
+    }
     /** Local fast-fail guard: throw when a quote total exceeds the caller's cap. */
     assertWithinMaxCost(total, maxCost) {
         if (maxCost && parseFloat(total) > maxCost) {
@@ -1360,6 +1497,99 @@ class OneShot {
      * a server-side enforcement layer so non-SDK callers (MCP server, custom
      * integrations) can't ignore the cap.
      */
+    /**
+     * The amount to sign, in decimal USDC.
+     *
+     * A 402 advertises its price twice: the x402 v2 `PAYMENT-REQUIRED` header
+     * (`accepts[0].amount`, atomic units) and the legacy JSON body
+     * (`payment_request.amount`, decimal). The header is authoritative — it is
+     * what the server rebuilds its requirement from and what
+     * `findMatchingRequirements` compares the signature against.
+     *
+     * Preferring the body is how quote-based routes (email/send, sms, voice,
+     * build, commerce/buy, compute) silently failed: the body carried a
+     * hardcoded "0.00", so the SDK signed a zero-cost authorization against a
+     * real charge and the server answered with a bodiless 402. It stayed hidden
+     * for as long as credits covered those calls, since the credit path returns
+     * 202 without any payment handshake.
+     *
+     * Falls back to the body when the header is missing or unparseable.
+     */
+    /**
+     * Throw the most specific error a failed response supports.
+     *
+     * A 402 arriving on the PAID retry means the facilitator refused the
+     * signature — not the ordinary "here is your quote" 402. The API names the
+     * cause in that body (`payment_verification_failed` + reason + expected vs
+     * received amount); surface it as a `PaymentError` so callers can branch on
+     * `err.reason` instead of string-matching. Anything else keeps the existing
+     * `ToolError` shape.
+     */
+    async failFromResponse(message, response) {
+        const text = await response.text();
+        const rejection = response.status === 402 ? this.parsePaymentRejection(text) : undefined;
+        if (rejection)
+            throw rejection;
+        const budget = response.status === 403 ? this.parseBudgetRejection(text) : undefined;
+        if (budget)
+            throw budget;
+        throw new errors_1.ToolError(message, response.status, text);
+    }
+    /**
+     * Map a 403 `budget_exceeded` body onto a typed error, so callers can catch
+     * "my own budget stopped this" separately from an auth failure or a payment
+     * rejection. Any other 403 falls through to ToolError.
+     */
+    parseBudgetRejection(text) {
+        try {
+            const body = JSON.parse(text);
+            if (body.error !== 'budget_exceeded')
+                return undefined;
+            const b = body.budget ?? {};
+            return new errors_1.BudgetExceededError(body.message ?? 'Agent spend budget exceeded', b.reason === 'per_transaction' ? 'per_transaction' : 'daily', b.cap !== undefined ? parseFloat(b.cap) : undefined, b.spent !== undefined ? parseFloat(b.spent) : undefined, b.charge !== undefined ? parseFloat(b.charge) : undefined, b.resets_at);
+        }
+        catch {
+            return undefined;
+        }
+    }
+    parsePaymentRejection(text) {
+        let data;
+        try {
+            data = JSON.parse(text);
+        }
+        catch {
+            return undefined;
+        }
+        if (data?.error !== 'payment_verification_failed')
+            return undefined;
+        const reason = data.reason || 'unknown';
+        const expectedAmount = data.expected?.amount;
+        const receivedAmount = data.received?.amount;
+        const detail = [
+            expectedAmount ? `expected $${expectedAmount}` : null,
+            receivedAmount ? `signed $${receivedAmount}` : null,
+        ].filter(Boolean).join(', ');
+        return new errors_1.PaymentError(`payment rejected: ${reason}${detail ? ` — ${detail}` : ''}${data.message ? ` (${data.message})` : ''}`, reason, {
+            amount: expectedAmount,
+            asset: data.expected?.asset,
+            network: data.expected?.network,
+            payTo: data.expected?.pay_to,
+        }, { amount: receivedAmount }, data.quote_id);
+    }
+    chargeAmount(accepted, bodyAmount) {
+        if (accepted?.amount == null || !/^\d+$/.test(String(accepted.amount))) {
+            return bodyAmount ?? '0';
+        }
+        const fromHeader = ethers_1.ethers.formatUnits(accepted.amount, 6);
+        // When the two agree (every fixed-price route), keep the body's string
+        // verbatim — downstream consumers such as the ETH auto-swap pass this
+        // value along, and there is no reason to reformat it. Only a genuine
+        // disagreement flips to the header.
+        if (bodyAmount != null && parseFloat(bodyAmount) === parseFloat(fromHeader)) {
+            return bodyAmount;
+        }
+        return fromHeader;
+    }
     maxCostHeader(maxCost) {
         if (!maxCost || maxCost <= 0)
             return undefined;
@@ -1409,6 +1639,9 @@ class OneShot {
         if (signal?.aborted) {
             throw new errors_1.OneShotError('Operation cancelled');
         }
+        // One-time push of config.budgets before the first paid call, so the
+        // server-side gate knows about them on this very request.
+        await this.ensureBudgetsSynced();
         let response = await this.makeRequest(endpoint, payload, undefined, quoteId, signal, undefined, extraHeaders);
         // Handle 402 Payment Required
         if (response.status === 402) {
@@ -1421,18 +1654,19 @@ class OneShot {
                 protocol: 'x402',
                 network: accepted.network,
                 payTo: accepted.payTo,
-                amount: data.payment_request?.amount ?? ethers_1.ethers.formatUnits(accepted.amount, 6),
+                amount: this.chargeAmount(accepted, data.payment_request?.amount),
                 currency: 'USD',
                 facilitator_url: this.baseUrl,
                 token: { address: accepted.asset, symbol: 'USDC', decimals: 6 }
             };
             this.log(`Payment required: ${paymentInfo.amount} USDC`);
+            this.assertWithinBudget(paymentInfo.amount);
             this.checkAbortBeforePayment(signal);
             const auth = await this.signPaymentAuthorization(paymentInfo, accepted, resource, extensions);
             response = await this.makeRequest(endpoint, payload, auth, quoteId, signal, undefined, extraHeaders);
         }
         if (!response.ok) {
-            throw new errors_1.ToolError('Tool request failed', response.status, await response.text());
+            await this.failFromResponse('Tool request failed', response);
         }
         const result = await response.json();
         // Handle async jobs
@@ -1453,16 +1687,20 @@ class OneShot {
      * body directly), since that differs per tool.
      */
     async runQuoteToPay(cfg) {
+        await this.ensureBudgetsSynced();
         const quoteResp = await this.makeRequest(cfg.endpoint, cfg.payload, undefined, undefined, cfg.signal, cfg.quoteTimeoutMs, this.maxCostHeader(cfg.maxCost));
         if (quoteResp.status === 400 && cfg.on400) {
             await cfg.on400(quoteResp);
         }
         if (quoteResp.status !== 402) {
-            throw new errors_1.ToolError(cfg.expectMsg, quoteResp.status, await quoteResp.text());
+            // Routes the budget gate on the quote leg (fixed-price ones) surface a
+            // 403 here; failFromResponse maps it to BudgetExceededError.
+            await this.failFromResponse(cfg.expectMsg, quoteResp);
         }
         const quoteData = await quoteResp.json();
         cfg.onQuote(quoteData.context);
         this.assertWithinMaxCost(cfg.totalOf(quoteData.context), cfg.maxCost);
+        this.assertWithinBudget(cfg.totalOf(quoteData.context));
         const paymentInfo = {
             protocol: 'x402',
             network: `eip155:${quoteData.payment_request.chain_id}`,
@@ -1474,6 +1712,7 @@ class OneShot {
         };
         this.checkAbortBeforePayment(cfg.signal);
         const { accepted, resource, extensions } = await this.getAcceptedRequirements(quoteResp, cfg.endpoint, cfg.payload, quoteData.context.quote_id, cfg.signal);
+        paymentInfo.amount = this.chargeAmount(accepted, quoteData.payment_request.amount);
         const auth = await this.signPaymentAuthorization(paymentInfo, accepted, resource, extensions);
         const execResp = await this.makeRequest(cfg.endpoint, cfg.payload, auth, quoteData.context.quote_id, cfg.signal, cfg.execTimeoutMs);
         return { context: quoteData.context, execResp };