@oneshot-agent/sdk 0.18.0 → 0.19.1

package/dist/index.js

@@ -48,7 +48,8 @@ var swap_1 = require("./swap");
 Object.defineProperty(exports, "getSwapQuote", { enumerable: true, get: function () { return swap_1.getSwapQuote; } });
 Object.defineProperty(exports, "executeSwap", { enumerable: true, get: function () { return swap_1.executeSwap; } });
 __exportStar(require("./errors"), exports);
-const SDK_VERSION = '0.16.2';
+// Keep in sync with package.json `version`. Guarded by version.test.ts.
+const SDK_VERSION = '0.19.1';
 // ============================================================================
 // Environment Configuration
 // ============================================================================
@@ -159,8 +160,11 @@ class OneShot {
         return this.executeToolRequest(`/v1/tools/${toolName}`, options);
     }
     async email(options) {
-        this.validate(options.to, 'to');
-        this.validate(options.subject, 'subject');
+        // to/subject are server-derived when replying to an inbound email.
+        if (!options.reply_to_email_id) {
+            this.validate(options.to, 'to');
+            this.validate(options.subject, 'subject');
+        }
         this.validate(options.body, 'body');
         // Rotation mode: when the caller passes neither from_domain nor
         // from_mailbox, omit from_address entirely so the server picks from
@@ -174,8 +178,9 @@ class OneShot {
             : `${options.from_mailbox ?? 'agent'}@${options.from_domain ?? 'oneshotagent.com'}`;
         const quote = await this.tool('email/quote', {
             ...(fromAddress ? { from_address: fromAddress } : {}),
-            to_address: options.to,
-            subject: options.subject,
+            ...(options.to !== undefined ? { to_address: options.to } : {}),
+            ...(options.subject !== undefined ? { subject: options.subject } : {}),
+            ...(options.reply_to_email_id ? { reply_to_email_id: options.reply_to_email_id } : {}),
             body: options.body,
             // Forward maxCost so the server-side X-Max-Cost-USDC header is set on
             // the quote fetch (executeToolRequest destructures + threads it).
@@ -188,17 +193,16 @@ class OneShot {
         // (e.g. a future API revision without the header check) or skipped (cap
         // un-set so the server returned a 200 with the quote and the caller still
         // wants the local guard to apply).
-        if (options.maxCost && parseFloat(quote.total_cost) > options.maxCost) {
-            throw new errors_1.OneShotError(`Quote $${quote.total_cost} exceeds maxCost $${options.maxCost}`);
-        }
+        this.assertWithinMaxCost(quote.total_cost, options.maxCost);
         const resolvedFromAddress = fromAddress ?? quote.from_address;
         const payload = {
             // Server replays the locked address from the quote when from_address
             // is absent, but sending it anyway is harmless and forward-compatible
             // with future SDK versions that talk directly to /send without quoting.
             ...(resolvedFromAddress ? { from_address: resolvedFromAddress } : {}),
-            to_address: options.to,
-            subject: options.subject,
+            ...(options.to !== undefined ? { to_address: options.to } : {}),
+            ...(options.subject !== undefined ? { subject: options.subject } : {}),
+            ...(options.reply_to_email_id ? { reply_to_email_id: options.reply_to_email_id } : {}),
             body: options.body,
             signal: options.signal,
             onStatusUpdate: options.onStatusUpdate,
@@ -210,6 +214,10 @@ class OneShot {
         if (options.attachments?.length) {
             payload.attachments = options.attachments;
         }
+        if (options.idempotencyKey) {
+            // Only the send call carries the key — the quote call has no side effects.
+            payload.idempotencyKey = options.idempotencyKey;
+        }
         return this.executeToolRequest('/v1/tools/email/send', payload, quote.quote_id);
     }
     /** List the caller's domain pool with warmup and rotation metadata. */
@@ -302,14 +310,11 @@ class OneShot {
         return this.tool('research/interactions', { ...options });
     }
     async inboxList(options = {}) {
-        const params = new URLSearchParams();
-        if (options.since)
-            params.set('since', options.since);
-        if (options.limit)
-            params.set('limit', String(options.limit));
-        if (options.include_body)
-            params.set('include_body', 'true');
-        const qs = params.toString();
+        const qs = this.buildQuery({
+            since: options.since || undefined,
+            limit: options.limit || undefined,
+            include_body: options.include_body ? 'true' : undefined,
+        });
         const response = await fetch(`${this.baseUrl}/v1/tools/inbox${qs ? `?${qs}` : ''}`, {
             headers: this.headers()
         });
@@ -342,28 +347,17 @@ class OneShot {
             variant_id: options.variant_id
         };
         // Commerce quotes can take up to 90s due to Rye API polling
-        const quoteResp = await this.makeRequest('/v1/tools/commerce/buy', payload, undefined, undefined, options.signal, 120000, this.maxCostHeader(options.maxCost));
-        if (quoteResp.status !== 402) {
-            throw new errors_1.ToolError('Expected 402 for quote', quoteResp.status, await quoteResp.text());
-        }
-        const quoteData = await quoteResp.json();
-        this.log(`Commerce quote: $${quoteData.context.total} for "${quoteData.context.product_title}"`);
-        if (options.maxCost && parseFloat(quoteData.context.total) > options.maxCost) {
-            throw new errors_1.OneShotError(`Quote $${quoteData.context.total} exceeds maxCost $${options.maxCost}`);
-        }
-        const paymentInfo = {
-            protocol: 'x402',
-            network: `eip155:${quoteData.payment_request.chain_id}`,
-            payTo: quoteData.payment_request.recipient,
-            amount: quoteData.payment_request.amount,
-            currency: 'USD',
-            facilitator_url: this.baseUrl,
-            token: { address: quoteData.payment_request.token_address, symbol: 'USDC', decimals: 6 }
-        };
-        this.checkAbortBeforePayment(options.signal);
-        const { accepted, resource, extensions } = await this.getAcceptedRequirements(quoteResp, '/v1/tools/commerce/buy', payload, quoteData.context.quote_id, options.signal);
-        const auth = await this.signPaymentAuthorization(paymentInfo, accepted, resource, extensions);
-        const buyResp = await this.makeRequest('/v1/tools/commerce/buy', payload, auth, quoteData.context.quote_id, options.signal, 60000);
+        const { execResp: buyResp } = await this.runQuoteToPay({
+            endpoint: '/v1/tools/commerce/buy',
+            payload,
+            signal: options.signal,
+            maxCost: options.maxCost,
+            quoteTimeoutMs: 120000,
+            execTimeoutMs: 60000,
+            expectMsg: 'Expected 402 for quote',
+            totalOf: (ctx) => ctx.total,
+            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());
         }
@@ -415,9 +409,6 @@ class OneShot {
         const payload = {
             objective: options.objective,
             target_number: options.target_number,
-            signal: options.signal,
-            onStatusUpdate: options.onStatusUpdate,
-            wait: options.wait
         };
         if (options.caller_persona)
             payload.caller_persona = options.caller_persona;
@@ -425,40 +416,25 @@ class OneShot {
             payload.context = options.context;
         if (options.max_duration_minutes)
             payload.max_duration_minutes = options.max_duration_minutes;
-        // Voice uses quote-to-pay flow (402 -> payment -> 202)
-        const quoteResp = await this.makeRequest('/v1/tools/voice/call', payload, undefined, undefined, options.signal, undefined, this.maxCostHeader(options.maxCost));
-        // Handle error responses before expecting 402
-        if (quoteResp.status === 400) {
-            const errorData = await quoteResp.json();
-            if (errorData.error === 'content_blocked') {
-                throw new errors_1.ContentBlockedError(errorData.message, errorData.categories || []);
-            }
-            if (errorData.error === 'emergency_number_blocked') {
-                throw new errors_1.EmergencyNumberError(errorData.message, errorData.blocked_number || '');
-            }
-            throw new errors_1.ValidationError(errorData.message || 'Invalid request', 'request');
-        }
-        if (quoteResp.status !== 402) {
-            throw new errors_1.ToolError('Expected 402 for quote', quoteResp.status, await quoteResp.text());
-        }
-        const quoteData = await quoteResp.json();
-        this.log(`Voice quote: $${quoteData.context.total} for ${quoteData.context.estimated_duration_minutes}min call`);
-        if (options.maxCost && parseFloat(quoteData.context.total) > options.maxCost) {
-            throw new errors_1.OneShotError(`Quote $${quoteData.context.total} exceeds maxCost $${options.maxCost}`);
-        }
-        const paymentInfo = {
-            protocol: 'x402',
-            network: `eip155:${quoteData.payment_request.chain_id}`,
-            payTo: quoteData.payment_request.recipient,
-            amount: quoteData.payment_request.amount,
-            currency: 'USD',
-            facilitator_url: this.baseUrl,
-            token: { address: quoteData.payment_request.token_address, symbol: 'USDC', decimals: 6 }
-        };
-        this.checkAbortBeforePayment(options.signal);
-        const { accepted, resource, extensions } = await this.getAcceptedRequirements(quoteResp, '/v1/tools/voice/call', payload, quoteData.context.quote_id, options.signal);
-        const auth = await this.signPaymentAuthorization(paymentInfo, accepted, resource, extensions);
-        const callResp = await this.makeRequest('/v1/tools/voice/call', payload, auth, quoteData.context.quote_id, options.signal);
+        const { execResp: callResp } = await this.runQuoteToPay({
+            endpoint: '/v1/tools/voice/call',
+            payload,
+            signal: options.signal,
+            maxCost: options.maxCost,
+            expectMsg: 'Expected 402 for quote',
+            totalOf: (ctx) => ctx.total,
+            onQuote: (ctx) => this.log(`Voice quote: $${ctx.total} for ${ctx.estimated_duration_minutes}min call`),
+            on400: async (resp) => {
+                const errorData = await resp.json();
+                if (errorData.error === 'content_blocked') {
+                    throw new errors_1.ContentBlockedError(errorData.message, errorData.categories || []);
+                }
+                if (errorData.error === 'emergency_number_blocked') {
+                    throw new errors_1.EmergencyNumberError(errorData.message, errorData.blocked_number || '');
+                }
+                throw new errors_1.ValidationError(errorData.message || 'Invalid request', 'request');
+            },
+        });
         if (callResp.status !== 202) {
             throw new errors_1.ToolError('Voice call initiation failed', callResp.status, await callResp.text());
         }
@@ -501,44 +477,27 @@ class OneShot {
         const payload = {
             message: options.message,
             to_number: options.to_number,
-            signal: options.signal,
-            onStatusUpdate: options.onStatusUpdate,
-            wait: options.wait
         };
         // SMS uses quote-to-pay flow (402 -> payment -> 202)
-        const quoteResp = await this.makeRequest('/v1/tools/sms/send', payload, undefined, undefined, options.signal, undefined, this.maxCostHeader(options.maxCost));
-        // Handle error responses before expecting 402
-        if (quoteResp.status === 400) {
-            const errorData = await quoteResp.json();
-            if (errorData.error === 'content_blocked') {
-                throw new errors_1.ContentBlockedError(errorData.message, errorData.categories || []);
-            }
-            if (errorData.error === 'emergency_number_blocked') {
-                throw new errors_1.EmergencyNumberError(errorData.message, errorData.blocked_number || '');
-            }
-            throw new errors_1.ValidationError(errorData.message || 'Invalid request', 'request');
-        }
-        if (quoteResp.status !== 402) {
-            throw new errors_1.ToolError('Expected 402 for quote', quoteResp.status, await quoteResp.text());
-        }
-        const quoteData = await quoteResp.json();
-        this.log(`SMS quote: $${quoteData.context.total} for ${quoteData.context.segment_count} segment(s) to ${recipientCount} recipient(s)`);
-        if (options.maxCost && parseFloat(quoteData.context.total) > options.maxCost) {
-            throw new errors_1.OneShotError(`Quote $${quoteData.context.total} exceeds maxCost $${options.maxCost}`);
-        }
-        const paymentInfo = {
-            protocol: 'x402',
-            network: `eip155:${quoteData.payment_request.chain_id}`,
-            payTo: quoteData.payment_request.recipient,
-            amount: quoteData.payment_request.amount,
-            currency: 'USD',
-            facilitator_url: this.baseUrl,
-            token: { address: quoteData.payment_request.token_address, symbol: 'USDC', decimals: 6 }
-        };
-        this.checkAbortBeforePayment(options.signal);
-        const { accepted, resource, extensions } = await this.getAcceptedRequirements(quoteResp, '/v1/tools/sms/send', payload, quoteData.context.quote_id, options.signal);
-        const auth = await this.signPaymentAuthorization(paymentInfo, accepted, resource, extensions);
-        const sendResp = await this.makeRequest('/v1/tools/sms/send', payload, auth, quoteData.context.quote_id, options.signal);
+        const { execResp: sendResp } = await this.runQuoteToPay({
+            endpoint: '/v1/tools/sms/send',
+            payload,
+            signal: options.signal,
+            maxCost: options.maxCost,
+            expectMsg: 'Expected 402 for quote',
+            totalOf: (ctx) => ctx.total,
+            onQuote: (ctx) => this.log(`SMS quote: $${ctx.total} for ${ctx.segment_count} segment(s) to ${recipientCount} recipient(s)`),
+            on400: async (resp) => {
+                const errorData = await resp.json();
+                if (errorData.error === 'content_blocked') {
+                    throw new errors_1.ContentBlockedError(errorData.message, errorData.categories || []);
+                }
+                if (errorData.error === 'emergency_number_blocked') {
+                    throw new errors_1.EmergencyNumberError(errorData.message, errorData.blocked_number || '');
+                }
+                throw new errors_1.ValidationError(errorData.message || 'Invalid request', 'request');
+            },
+        });
         if (sendResp.status !== 202) {
             throw new errors_1.ToolError('SMS send failed', sendResp.status, await sendResp.text());
         }
@@ -575,9 +534,6 @@ class OneShot {
         const payload = {
             type: options.type ?? 'saas',
             product: options.product,
-            signal: options.signal,
-            onStatusUpdate: options.onStatusUpdate,
-            wait: options.wait
         };
         if (options.source_url)
             payload.source_url = options.source_url;
@@ -593,34 +549,24 @@ class OneShot {
             payload.domain = options.domain;
         if (options.build_id)
             payload.build_id = options.build_id;
-        // Build uses quote-to-pay flow (402 -> payment -> 202)
-        const quoteResp = await this.makeRequest('/v1/tools/build', payload, undefined, undefined, options.signal, undefined, this.maxCostHeader(options.maxCost));
-        if (quoteResp.status === 400) {
-            const errorData = await quoteResp.json();
-            throw new errors_1.ValidationError(errorData.message || 'Invalid request', 'request');
-        }
-        if (quoteResp.status !== 402) {
-            throw new errors_1.ToolError('Expected 402 for quote', quoteResp.status, await quoteResp.text());
-        }
-        const quoteData = await quoteResp.json();
-        this.log(`Build quote: $${quoteData.context.pricing.total} for "${quoteData.context.product_name}"`);
-        this.log(`Type: ${quoteData.context.analysis.inferred_type}, Sections: ${quoteData.context.analysis.estimated_sections}`);
-        if (options.maxCost && parseFloat(quoteData.context.pricing.total) > options.maxCost) {
-            throw new errors_1.OneShotError(`Quote $${quoteData.context.pricing.total} exceeds maxCost $${options.maxCost}`);
-        }
-        const paymentInfo = {
-            protocol: 'x402',
-            network: `eip155:${quoteData.payment_request.chain_id}`,
-            payTo: quoteData.payment_request.recipient,
-            amount: quoteData.payment_request.amount,
-            currency: 'USD',
-            facilitator_url: this.baseUrl,
-            token: { address: quoteData.payment_request.token_address, symbol: 'USDC', decimals: 6 }
-        };
-        this.checkAbortBeforePayment(options.signal);
-        const { accepted, resource, extensions } = await this.getAcceptedRequirements(quoteResp, '/v1/tools/build', payload, quoteData.context.quote_id, options.signal);
-        const auth = await this.signPaymentAuthorization(paymentInfo, accepted, resource, extensions);
-        const buildResp = await this.makeRequest('/v1/tools/build', payload, auth, quoteData.context.quote_id, options.signal);
+        const { execResp: buildResp } = await this.runQuoteToPay({
+            endpoint: '/v1/tools/build',
+            payload,
+            signal: options.signal,
+            maxCost: options.maxCost,
+            // Build analysis can be slow server-side; bound the quote leg client-side.
+            quoteTimeoutMs: 120000,
+            expectMsg: 'Expected 402 for quote',
+            totalOf: (ctx) => ctx.pricing.total,
+            onQuote: (ctx) => {
+                this.log(`Build quote: $${ctx.pricing.total} for "${ctx.product_name}"`);
+                this.log(`Type: ${ctx.analysis.inferred_type}, Sections: ${ctx.analysis.estimated_sections}`);
+            },
+            on400: async (resp) => {
+                const errorData = await resp.json();
+                throw new errors_1.ValidationError(errorData.message || 'Invalid request', 'request');
+            },
+        });
         if (buildResp.status !== 202) {
             throw new errors_1.ToolError('Build initiation failed', buildResp.status, await buildResp.text());
         }
@@ -653,9 +599,6 @@ class OneShot {
         }
         const payload = {
             task: options.task,
-            signal: options.signal,
-            onStatusUpdate: options.onStatusUpdate,
-            wait: options.wait
         };
         if (options.output_schema)
             payload.output_schema = options.output_schema;
@@ -671,33 +614,21 @@ class OneShot {
             payload.secrets = options.secrets;
         if (options.max_steps)
             payload.max_steps = options.max_steps;
-        // Browser uses quote-to-pay flow (402 -> payment -> 202)
-        const quoteResp = await this.makeRequest('/v1/tools/browser', payload, undefined, undefined, options.signal, undefined, this.maxCostHeader(options.maxCost));
-        if (quoteResp.status === 400) {
-            const errorData = await quoteResp.json();
-            throw new errors_1.ValidationError(errorData.message || 'Invalid request', 'request');
-        }
-        if (quoteResp.status !== 402) {
-            throw new errors_1.ToolError('Expected 402 for quote', quoteResp.status, await quoteResp.text());
-        }
-        const quoteData = await quoteResp.json();
-        this.log(`Browser quote: $${quoteData.context.estimated_cost} for ~${quoteData.context.estimated_steps} steps`);
-        if (options.maxCost && parseFloat(quoteData.context.estimated_cost) > options.maxCost) {
-            throw new errors_1.OneShotError(`Quote $${quoteData.context.estimated_cost} exceeds maxCost $${options.maxCost}`);
-        }
-        const paymentInfo = {
-            protocol: 'x402',
-            network: `eip155:${quoteData.payment_request.chain_id}`,
-            payTo: quoteData.payment_request.recipient,
-            amount: quoteData.payment_request.amount,
-            currency: 'USD',
-            facilitator_url: this.baseUrl,
-            token: { address: quoteData.payment_request.token_address, symbol: 'USDC', decimals: 6 }
-        };
-        this.checkAbortBeforePayment(options.signal);
-        const { accepted, resource, extensions } = await this.getAcceptedRequirements(quoteResp, '/v1/tools/browser', payload, quoteData.context.quote_id, options.signal);
-        const auth = await this.signPaymentAuthorization(paymentInfo, accepted, resource, extensions);
-        const execResp = await this.makeRequest('/v1/tools/browser', payload, auth, quoteData.context.quote_id, options.signal);
+        const { execResp } = await this.runQuoteToPay({
+            endpoint: '/v1/tools/browser',
+            payload,
+            signal: options.signal,
+            maxCost: options.maxCost,
+            // Browser analysis can be slow server-side; bound the quote leg client-side.
+            quoteTimeoutMs: 120000,
+            expectMsg: 'Expected 402 for quote',
+            totalOf: (ctx) => ctx.estimated_cost,
+            onQuote: (ctx) => this.log(`Browser quote: $${ctx.estimated_cost} for ~${ctx.estimated_steps} steps`),
+            on400: async (resp) => {
+                const errorData = await resp.json();
+                throw new errors_1.ValidationError(errorData.message || 'Invalid request', 'request');
+            },
+        });
         if (execResp.status !== 202) {
             throw new errors_1.ToolError('Browser task initiation failed', execResp.status, await execResp.text());
         }
@@ -721,7 +652,7 @@ class OneShot {
         this.validate(name, 'name');
         const response = await fetch(`${this.baseUrl}/v1/tools/browser/profiles`, {
             method: 'POST',
-            headers: { 'Content-Type': 'application/json', ...this.headers() },
+            headers: this.jsonHeaders(),
             body: JSON.stringify({ name }),
         });
         if (!response.ok) {
@@ -802,14 +733,11 @@ class OneShot {
      * ```
      */
     async smsInboxList(options = {}) {
-        const params = new URLSearchParams();
-        if (options.since)
-            params.set('since', options.since);
-        if (options.limit)
-            params.set('limit', String(options.limit));
-        if (options.from)
-            params.set('from', options.from);
-        const qs = params.toString();
+        const qs = this.buildQuery({
+            since: options.since || undefined,
+            limit: options.limit || undefined,
+            from: options.from || undefined,
+        });
         const response = await fetch(`${this.baseUrl}/v1/tools/sms/inbox${qs ? `?${qs}` : ''}`, {
             headers: this.headers()
         });
@@ -853,12 +781,10 @@ class OneShot {
      * ```
      */
     async notifications(options = {}) {
-        const params = new URLSearchParams();
-        if (options.unread)
-            params.set('unread', 'true');
-        if (options.limit)
-            params.set('limit', String(options.limit));
-        const qs = params.toString();
+        const qs = this.buildQuery({
+            unread: options.unread ? 'true' : undefined,
+            limit: options.limit || undefined,
+        });
         const response = await fetch(`${this.baseUrl}/v1/tools/notifications${qs ? `?${qs}` : ''}`, {
             headers: this.headers()
         });
@@ -950,36 +876,24 @@ class OneShot {
             payload.soul_service_slug = options.soul_service_slug;
         if (options.schedule)
             payload.schedule = options.schedule;
-        // First call: get quote (402)
-        const quoteResp = await this.makeRequest('/v1/compute', payload, undefined, undefined, options.signal, undefined, this.maxCostHeader(options.maxCost));
-        if (quoteResp.status === 400) {
-            const errorData = await quoteResp.json();
-            if (errorData.error === 'content_blocked') {
-                throw new errors_1.ContentBlockedError(errorData.message, []);
-            }
-            throw new errors_1.ValidationError(errorData.message || 'Invalid request', 'request');
-        }
-        if (quoteResp.status !== 402) {
-            throw new errors_1.ToolError('Expected 402 for compute quote', quoteResp.status, await quoteResp.text());
-        }
-        const quoteData = await quoteResp.json();
-        this.log(`Compute quote: $${quoteData.context.total_budget} — ${quoteData.context.objective_summary}`);
-        if (options.maxCost && parseFloat(quoteData.context.total_budget) > options.maxCost) {
-            throw new errors_1.OneShotError(`Quote $${quoteData.context.total_budget} exceeds maxCost $${options.maxCost}`);
-        }
-        const paymentInfo = {
-            protocol: 'x402',
-            network: `eip155:${quoteData.payment_request.chain_id}`,
-            payTo: quoteData.payment_request.recipient,
-            amount: quoteData.payment_request.amount,
-            currency: 'USD',
-            facilitator_url: this.baseUrl,
-            token: { address: quoteData.payment_request.token_address, symbol: 'USDC', decimals: 6 }
-        };
-        this.checkAbortBeforePayment(options.signal);
-        const { accepted, resource, extensions } = await this.getAcceptedRequirements(quoteResp, '/v1/compute', payload, quoteData.context.quote_id, options.signal);
-        const auth = await this.signPaymentAuthorization(paymentInfo, accepted, resource, extensions);
-        const createResp = await this.makeRequest('/v1/compute', payload, auth, quoteData.context.quote_id, options.signal);
+        // Compute returns the goal directly on 202 — no job polling, unlike the
+        // other paid tools.
+        const { execResp: createResp } = await this.runQuoteToPay({
+            endpoint: '/v1/compute',
+            payload,
+            signal: options.signal,
+            maxCost: options.maxCost,
+            expectMsg: 'Expected 402 for compute quote',
+            totalOf: (ctx) => ctx.total_budget,
+            onQuote: (ctx) => this.log(`Compute quote: $${ctx.total_budget} — ${ctx.objective_summary}`),
+            on400: async (resp) => {
+                const errorData = await resp.json();
+                if (errorData.error === 'content_blocked') {
+                    throw new errors_1.ContentBlockedError(errorData.message, []);
+                }
+                throw new errors_1.ValidationError(errorData.message || 'Invalid request', 'request');
+            },
+        });
         if (createResp.status !== 202) {
             throw new errors_1.ToolError('Compute goal creation failed', createResp.status, await createResp.text());
         }
@@ -1066,7 +980,7 @@ class OneShot {
         this.validate(goalId, 'goalId');
         const response = await fetch(`${this.baseUrl}/v1/compute/${goalId}/cancel`, {
             method: 'POST',
-            headers: { 'Content-Type': 'application/json', ...this.headers() },
+            headers: this.jsonHeaders(),
             body: JSON.stringify({ reason })
         });
         if (response.status === 404) {
@@ -1095,7 +1009,7 @@ class OneShot {
         this.validate(input.task_id, 'task_id');
         const response = await fetch(`${this.baseUrl}/v1/compute/${goalId}/respond`, {
             method: 'POST',
-            headers: { 'Content-Type': 'application/json', ...this.headers() },
+            headers: this.jsonHeaders(),
             body: JSON.stringify(input)
         });
         if (response.status === 404) {
@@ -1119,7 +1033,7 @@ class OneShot {
         this.validate(goalId, 'goalId');
         const response = await fetch(`${this.baseUrl}/v1/compute/${goalId}/pause`, {
             method: 'POST',
-            headers: { 'Content-Type': 'application/json', ...this.headers() },
+            headers: this.jsonHeaders(),
             body: JSON.stringify({ reason })
         });
         if (!response.ok) {
@@ -1141,7 +1055,7 @@ class OneShot {
         this.validate(goalId, 'goalId');
         const response = await fetch(`${this.baseUrl}/v1/compute/${goalId}/resume`, {
             method: 'POST',
-            headers: { 'Content-Type': 'application/json', ...this.headers() },
+            headers: this.jsonHeaders(),
             body: JSON.stringify({})
         });
         if (!response.ok) {
@@ -1210,10 +1124,7 @@ class OneShot {
      * ```
      */
     async spendBreakdown(options) {
-        const params = new URLSearchParams();
-        if (options?.period)
-            params.set('period', String(options.period));
-        const qs = params.toString();
+        const qs = this.buildQuery({ period: options?.period || undefined });
         const response = await fetch(`${this.baseUrl}/v1/analytics/spend/breakdown${qs ? `?${qs}` : ''}`, {
             headers: this.headers()
         });
@@ -1232,10 +1143,7 @@ class OneShot {
      * ```
      */
     async rocs(options) {
-        const params = new URLSearchParams();
-        if (options?.period)
-            params.set('period', String(options.period));
-        const qs = params.toString();
+        const qs = this.buildQuery({ period: options?.period || undefined });
         const response = await fetch(`${this.baseUrl}/v1/analytics/rocs${qs ? `?${qs}` : ''}`, {
             headers: this.headers()
         });
@@ -1256,14 +1164,11 @@ class OneShot {
      * ```
      */
     async receiptsList(options) {
-        const params = new URLSearchParams();
-        if (options?.period)
-            params.set('period', String(options.period));
-        if (options?.category)
-            params.set('category', options.category);
-        if (options?.limit)
-            params.set('limit', String(options.limit));
-        const qs = params.toString();
+        const qs = this.buildQuery({
+            period: options?.period || undefined,
+            category: options?.category || undefined,
+            limit: options?.limit || undefined,
+        });
         const response = await fetch(`${this.baseUrl}/v1/analytics/receipts${qs ? `?${qs}` : ''}`, {
             headers: this.headers()
         });
@@ -1315,6 +1220,26 @@ class OneShot {
             'X-OneShot-SDK-Version': SDK_VERSION
         };
     }
+    /** Auth headers plus Content-Type for JSON-body requests. */
+    jsonHeaders() {
+        return { 'Content-Type': 'application/json', ...this.headers() };
+    }
+    /** Build a query string, skipping null/undefined values. Pass falsy-but-valid
+     *  values (0, '') as undefined at the call site to match prior `if (x)` guards. */
+    buildQuery(params) {
+        const qs = new URLSearchParams();
+        for (const [k, v] of Object.entries(params)) {
+            if (v != null)
+                qs.set(k, String(v));
+        }
+        return qs.toString();
+    }
+    /** Local fast-fail guard: throw when a quote total exceeds the caller's cap. */
+    assertWithinMaxCost(total, maxCost) {
+        if (maxCost && parseFloat(total) > maxCost) {
+            throw new errors_1.OneShotError(`Quote $${total} exceeds maxCost $${maxCost}`);
+        }
+    }
     /**
      * Header that asks the API to reject the request when the computed quote
      * exceeds the caller-supplied cap (commit 8f328a7). The SDK still does its
@@ -1327,9 +1252,22 @@ class OneShot {
             return undefined;
         return { 'X-Max-Cost-USDC': maxCost.toString() };
     }
+    /**
+     * Idempotency-Key header, sent on both legs (pre-402 and paid retry) so
+     * the server can replay a cached result instead of double-charging and
+     * double-executing on a client retry.
+     */
+    idempotencyHeader(idempotencyKey) {
+        if (!idempotencyKey)
+            return undefined;
+        return { 'Idempotency-Key': idempotencyKey };
+    }
     async executeToolRequest(endpoint, options, quoteId) {
-        const { signal, onStatusUpdate, wait = true, waitForPhones, phoneTimeoutSec, maxCost, ...payload } = options;
-        const extraHeaders = this.maxCostHeader(maxCost);
+        const { signal, onStatusUpdate, wait = true, waitForPhones, phoneTimeoutSec, idempotencyKey, maxCost, ...payload } = options;
+        const extraHeaders = {
+            ...this.maxCostHeader(maxCost),
+            ...this.idempotencyHeader(idempotencyKey),
+        };
         // Validate memo
         if (payload.memo !== undefined) {
             if (typeof payload.memo !== 'string' || payload.memo.trim().length === 0) {
@@ -1394,15 +1332,55 @@ class OneShot {
         }
         return (result.data ?? result);
     }
+    /**
+     * Shared x402 quote-to-pay flow for paid tools. Fetches the 402 quote, runs
+     * any per-tool 400 handling, enforces maxCost, signs the payment auth, and
+     * POSTs the paid request. Returns the parsed quote context plus the raw paid
+     * Response — the caller owns the post-202 handling (poll a job vs. return the
+     * body directly), since that differs per tool.
+     */
+    async runQuoteToPay(cfg) {
+        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());
+        }
+        const quoteData = await quoteResp.json();
+        cfg.onQuote(quoteData.context);
+        this.assertWithinMaxCost(cfg.totalOf(quoteData.context), cfg.maxCost);
+        const paymentInfo = {
+            protocol: 'x402',
+            network: `eip155:${quoteData.payment_request.chain_id}`,
+            payTo: quoteData.payment_request.recipient,
+            amount: quoteData.payment_request.amount,
+            currency: 'USD',
+            facilitator_url: this.baseUrl,
+            token: { address: quoteData.payment_request.token_address, symbol: 'USDC', decimals: 6 }
+        };
+        this.checkAbortBeforePayment(cfg.signal);
+        const { accepted, resource, extensions } = await this.getAcceptedRequirements(quoteResp, cfg.endpoint, cfg.payload, quoteData.context.quote_id, cfg.signal);
+        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 };
+    }
     async pollJob(requestId, timeoutSec, signal, onStatusUpdate, phoneOpts) {
-        // Try WebSocket push first, fall back to HTTP polling
+        // Try WebSocket push first, fall back to HTTP polling. Both phases share a
+        // single deadline so the combined wait never exceeds the caller's timeout —
+        // previously the WS cap (≤180s) plus a fresh full HTTP timeout could total
+        // up to ~1.6× timeoutSec (e.g. ~480s for a 300s request).
+        const deadline = timeoutSec != null ? Date.now() + timeoutSec * 1000 : undefined;
         let result;
         try {
             result = await this.waitViaWebSocket(requestId, timeoutSec, signal, onStatusUpdate);
         }
         catch {
             this.log('WebSocket unavailable, falling back to HTTP polling');
-            result = await this.pollJobHttp(requestId, timeoutSec, signal, onStatusUpdate);
+            const remainingSec = deadline != null
+                ? Math.max(1, Math.ceil((deadline - Date.now()) / 1000))
+                : undefined;
+            result = await this.pollJobHttp(requestId, remainingSec, signal, onStatusUpdate);
         }
         // Optional second phase: keep polling for the async phone-reveal webhook.
         // Only kicks in when the caller explicitly opts in AND the result still
@@ -1579,7 +1557,7 @@ class OneShot {
                     else if (msg.status === 'failed') {
                         settle(() => {
                             cleanup();
-                            reject(new errors_1.JobError(`Job failed: ${msg.error ?? 'Unknown'}`, requestId, String(msg.error ?? 'Unknown')));
+                            reject(new errors_1.JobError(`Job failed: ${msg.error ?? 'Unknown'}`, requestId, String(msg.error ?? 'Unknown'), msg.error_code));
                         });
                     }
                     else {
@@ -1635,7 +1613,7 @@ class OneShot {
                     return result;
                 }
                 if (job.status === 'failed') {
-                    throw new errors_1.JobError(`Job failed: ${job.error ?? 'Unknown'}`, requestId, String(job.error ?? 'Unknown'));
+                    throw new errors_1.JobError(`Job failed: ${job.error ?? 'Unknown'}`, requestId, String(job.error ?? 'Unknown'), job.error_code);
                 }
                 onStatusUpdate?.(job.status, requestId);
                 retries = 0;