@oneshot-agent/sdk 0.38.1 → 0.42.0

package/dist/index.js

@@ -39,6 +39,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.OneShot = exports.executeSwap = exports.getSwapQuote = exports.ReadOnlyWalletProvider = exports.CdpWalletProvider = exports.EthersWalletProvider = void 0;
 const physical_mail_1 = require("./physical-mail");
 __exportStar(require("./physical-mail"), exports);
+__exportStar(require("./approvals"), exports);
 const deadline_1 = require("./deadline");
 const errors_1 = require("./errors");
 const read_only_1 = require("./providers/read-only");
@@ -55,6 +56,7 @@ 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 approvals_1 = require("./approvals");
 // Receipt verification (`canonicalizeReceipt`, `verifyReceipt`,
 // `receiptFromWire`, and their supporting types `SignableReceipt`,
 // `ReceiptSignatureFields`, `ReceiptJwk`, `ReceiptJwks`,
@@ -80,7 +82,7 @@ __exportStar(require("./errors"), exports);
 // not removing the field. Import `SignableReceipt` from the `./receipt`
 // subpath directly if you need it.
 // Keep in sync with package.json `version`. Guarded by version.test.ts.
-const SDK_VERSION = '0.38.1';
+const SDK_VERSION = '0.42.0';
 /** HTTP poll cadence while push is unconfirmed: fast first checks, settling at 2s. */
 const HTTP_POLL_BACKOFF_MS = [300, 600, 1000, 2000];
 /** HTTP poll cadence once the WebSocket has delivered for this request. */
@@ -226,6 +228,11 @@ class OneShot {
                 await this.failFromResponse('Physical mail request failed', response);
             return await response.json();
         }, input => this.executeToolRequest('/v1/tools/physical-mail/send', { ...input, wait: false }));
+        /** Ask a named human to decide, and read decisions. See ./approvals.ts. */
+        this.approvals = new approvals_1.Approvals((path, method, body, scope) => this.agentJson(path, method, body, scope));
+        /** Which paid calls run, are denied, or wait for approval. Wallet sessions write it. */
+        this.policy = new approvals_1.ActionPolicies((path, method, body, scope) => this.agentJson(path, method, body, scope));
+        this.readProofWarned = false;
         /** ETH mode: signed payments not yet observed as settled, keyed by reservation id. */
         this._usdcPending = new Map();
         this._usdcReservationSeq = 0;
@@ -392,6 +399,10 @@ class OneShot {
             // Only the send call carries the key — the quote call has no side effects.
             payload.idempotencyKey = options.idempotencyKey;
         }
+        if (options.approvalId) {
+            // Releases a send the action policy held (see ApprovalRequiredError).
+            payload.approvalId = options.approvalId;
+        }
         return this.executeToolRequest('/v1/tools/email/send', payload, quote.quote_id);
     }
     /** List the caller's domain pool with warmup and rotation metadata. */
@@ -581,6 +592,7 @@ class OneShot {
             payload,
             signal: options.signal,
             maxCost: options.maxCost,
+            approvalId: options.approvalId,
             quoteTimeoutMs: 120000,
             execTimeoutMs: 60000,
             expectMsg: 'Expected 402 for quote',
@@ -649,6 +661,7 @@ class OneShot {
             payload,
             signal: options.signal,
             maxCost: options.maxCost,
+            approvalId: options.approvalId,
             expectMsg: 'Expected 402 for quote',
             totalOf: (ctx) => ctx.total,
             onQuote: (ctx) => this.log(`Voice quote: $${ctx.total} for ${ctx.estimated_duration_minutes}min call`),
@@ -711,6 +724,7 @@ class OneShot {
             payload,
             signal: options.signal,
             maxCost: options.maxCost,
+            approvalId: options.approvalId,
             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)`),
@@ -1133,6 +1147,105 @@ class OneShot {
         }
         return response.json();
     }
+    // ---------------------------------------------------------------------------
+    // Inbound voice — the agent's number answers its own calls
+    // ---------------------------------------------------------------------------
+    /**
+     * Get this agent a voice number without placing a call. Returns the existing
+     * active number for free; otherwise buys one and charges the one-time phone
+     * registration fee from prepaid credits (see `topUpCredits`). Too little
+     * credit throws a 402 and buys nothing. Then configure it with
+     * `setInboundVoice`.
+     *
+     * @example
+     * ```typescript
+     * const number = await agent.provisionVoiceNumber();
+     * await agent.setInboundVoice(number.id, { prompt: 'You answer for Acme Dental.' });
+     * ```
+     */
+    async provisionVoiceNumber() {
+        return this.signedJson('POST', '/v1/tools/voice/numbers', {}, 'write', 'Failed to provision a phone number');
+    }
+    /**
+     * List this agent's phone numbers. A number comes from `provisionVoiceNumber`
+     * or the agent's first outbound voice call.
+     *
+     * @example
+     * ```typescript
+     * const { numbers } = await agent.voiceNumbers();
+     * ```
+     */
+    async voiceNumbers() {
+        return this.signedJson('GET', '/v1/tools/voice/numbers', undefined, 'read', 'Failed to list phone numbers');
+    }
+    /**
+     * Answer calls to one of the agent's numbers. Replaces the whole config.
+     * Inbound calls are paid from prepaid credits (see `topUpCredits`), per
+     * started minute; a call is declined when credits cannot cover the minimum
+     * fee. Keep the returned `webhook_secret` if you set `webhook_url`.
+     *
+     * @example
+     * ```typescript
+     * await agent.setInboundVoice(numberId, {
+     *   prompt: 'You answer for Acme Dental. Book cleanings; take a message for anything else.',
+     *   business_hours: { timezone: 'America/New_York', windows: [{ days: ['mon','tue','wed','thu','fri'], start: '09:00', end: '17:00' }] },
+     *   after_hours: 'take_message',
+     * });
+     * ```
+     */
+    async setInboundVoice(phoneNumberId, config) {
+        this.validate(phoneNumberId, 'phoneNumberId');
+        return this.signedJson('PUT', `/v1/tools/voice/numbers/${encodeURIComponent(phoneNumberId)}/inbound`, config, 'write', 'Failed to set inbound voice config');
+    }
+    /** Current inbound config for a number (throws 404 when none is set). */
+    async getInboundVoice(phoneNumberId) {
+        this.validate(phoneNumberId, 'phoneNumberId');
+        return this.signedJson('GET', `/v1/tools/voice/numbers/${encodeURIComponent(phoneNumberId)}/inbound`, undefined, 'read', 'Failed to get inbound voice config');
+    }
+    /** Stop answering calls to a number. The settings are kept, disabled. */
+    async disableInboundVoice(phoneNumberId) {
+        this.validate(phoneNumberId, 'phoneNumberId');
+        return this.signedJson('DELETE', `/v1/tools/voice/numbers/${encodeURIComponent(phoneNumberId)}/inbound`, undefined, 'write', 'Failed to disable inbound voice');
+    }
+    /**
+     * List inbound calls, newest first.
+     *
+     * @example
+     * ```typescript
+     * const { calls } = await agent.inboundCalls({ limit: 20 });
+     * for (const c of calls) console.log(c.from, c.summary);
+     * ```
+     */
+    async inboundCalls(options = {}) {
+        const qs = this.buildQuery({
+            limit: options.limit || undefined,
+            before: options.before || undefined,
+            phone_number_id: options.phone_number_id || undefined,
+            include_transcript: options.include_transcript ? 'true' : undefined,
+        });
+        return this.signedJson('GET', `/v1/tools/voice/inbound${qs ? `?${qs}` : ''}`, undefined, 'read', 'Failed to list inbound calls');
+    }
+    /** One inbound call, with transcript. */
+    async inboundCall(callId) {
+        this.validate(callId, 'callId');
+        return this.signedJson('GET', `/v1/tools/voice/inbound/${encodeURIComponent(callId)}`, undefined, 'read', 'Failed to get inbound call');
+    }
+    /** Signed free request returning the `data` field of `{ success, data }`. */
+    async signedJson(method, path, body, scope, failure) {
+        const response = await fetch(`${this.baseUrl}${path}`, {
+            method,
+            headers: {
+                ...(body !== undefined ? { 'Content-Type': 'application/json' } : {}),
+                ...(await this.signedReadHeaders(scope)),
+            },
+            ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
+        });
+        if (!response.ok) {
+            throw new errors_2.ToolError(failure, response.status, await response.text());
+        }
+        const json = await response.json();
+        return (json.data ?? json);
+    }
     /**
      * Get a specific inbound SMS message
      *
@@ -1192,7 +1305,7 @@ class OneShot {
         this.validate(notificationId, 'notificationId');
         const response = await fetch(`${this.baseUrl}/v1/tools/notifications/${notificationId}/read`, {
             method: 'PATCH',
-            headers: await this.signedReadHeaders()
+            headers: await this.signedReadHeaders('write')
         });
         if (response.status === 404) {
             throw new errors_2.ToolError('Notification not found', 404, 'Notification not found');
@@ -1781,7 +1894,7 @@ class OneShot {
      * read another agent's data by supplying its address. The proof binds this
      * request to the wallet the SDK controls; the server verifies the signature
      * locally. A fresh nonce per call prevents replay. Signing failure falls back
-     * to plain headers (the server runs log-only until enforcement is enabled).
+     * to plain headers, with a one-time warning.
      */
     async signedReadHeaders(scope = 'read') {
         const base = this.headers();
@@ -1806,7 +1919,16 @@ class OneShot {
             return { ...base, 'x-agent-proof': proof };
         }
         catch (err) {
-            this.log(`Failed to sign read proof (continuing without): ${err}`);
+            // Once per client, even without debug: when the API enforces proofs,
+            // these requests will be rejected, and a silent fallback would leave
+            // the caller with a 401 and no idea why.
+            if (!this.readProofWarned) {
+                this.readProofWarned = true;
+                this.logger(`[OneShot] Warning: could not sign the x-agent-proof read proof, so requests go without it and will be rejected where the API enforces proofs. Pass a signer that supports signTypedData, or use an access token. Cause: ${err}`);
+            }
+            else {
+                this.log(`Failed to sign read proof (continuing without): ${err}`);
+            }
             return base;
         }
     }
@@ -1904,6 +2026,19 @@ class OneShot {
      * console.log(`${b.spent_today_usdc} of ${b.daily_usdc} spent, resets ${b.resets_at}`);
      * ```
      */
+    /** Signed-proof JSON request to a free agent route; returns `data`. Errors map through failFromResponse. */
+    async agentJson(path, method, body, scope = 'read') {
+        const response = await fetch(`${this.baseUrl}${path}`, {
+            method,
+            headers: { 'Content-Type': 'application/json', ...(await this.signedReadHeaders(scope)) },
+            ...(body === undefined || method === 'GET' ? {} : { body: JSON.stringify(body) }),
+            signal: AbortSignal.timeout(30000),
+        });
+        if (!response.ok)
+            await this.failFromResponse(`${method} ${path.split('?')[0]} failed`, response);
+        const json = await response.json();
+        return (json && typeof json === 'object' && 'data' in json ? json.data : json);
+    }
     async budgets() {
         const response = await fetch(`${this.baseUrl}/v1/agents/me/budgets`, {
             headers: await this.signedReadHeaders(),
@@ -2018,6 +2153,9 @@ class OneShot {
         const rejection = [402, 500].includes(response.status) ? this.parsePaymentRejection(text) : undefined;
         if (rejection)
             throw rejection;
+        const policy = response.status === 403 ? this.parsePolicyRejection(text) : undefined;
+        if (policy)
+            throw policy;
         const budget = response.status === 403 ? this.parseBudgetRejection(text) : undefined;
         if (budget)
             throw budget;
@@ -2098,6 +2236,23 @@ class OneShot {
      * "my own budget stopped this" separately from an auth failure or a payment
      * rejection. Any other 403 falls through to ToolError.
      */
+    /** 403 from the action-policy gate: held for approval, or denied. */
+    parsePolicyRejection(text) {
+        let body;
+        try {
+            body = JSON.parse(text);
+        }
+        catch {
+            return undefined;
+        }
+        if (body?.error === 'approval_required' && typeof body.approval_id === 'string') {
+            return new errors_2.ApprovalRequiredError(body.message ?? 'This call needs a human approval', body.approval_id, body.approval, body.approval?.policy_rule ?? undefined);
+        }
+        if (body?.error === 'action_denied_by_policy') {
+            return new errors_2.ActionDeniedError(body.message ?? 'Denied by the action policy', body.rule);
+        }
+        return undefined;
+    }
     parseBudgetRejection(text) {
         try {
             const body = JSON.parse(text);
@@ -2163,6 +2318,12 @@ class OneShot {
             return undefined;
         return { 'Idempotency-Key': idempotencyKey };
     }
+    /** X-Approval-Id, sent on both legs; the server reads it only on the paid leg. */
+    approvalHeader(approvalId) {
+        if (!approvalId)
+            return undefined;
+        return { 'X-Approval-Id': approvalId };
+    }
     async readReliabilityJson(path, signed, allowDegraded = false) {
         const scope = (0, deadline_1.deadlineScope)(undefined, signed ? 10000 : 5000);
         try {
@@ -2216,11 +2377,13 @@ class OneShot {
         }
     }
     async executeToolRequestImpl(endpoint, options, quoteId, context = { phase: "initialization" }) {
-        const { totalTimeoutMs, onRequestCreated, onAccepted, signal, onStatusUpdate, wait = true, waitForPhones, phoneTimeoutSec, idempotencyKey, maxCost, ...payload } = options;
+        const { totalTimeoutMs, onRequestCreated, onAccepted, signal, onStatusUpdate, wait = true, waitForPhones, phoneTimeoutSec, idempotencyKey, approvalId, maxCost, ...payload } = options;
         const extraHeaders = {
             ...this.maxCostHeader(maxCost),
             ...this.idempotencyHeader(idempotencyKey),
         };
+        // Releases a call the action policy held (ToolOptions.approvalId).
+        Object.assign(extraHeaders, this.approvalHeader(approvalId));
         if (payload.memo !== undefined) {
             if (typeof payload.memo !== 'string' || payload.memo.trim().length === 0) {
                 delete payload.memo; // Drop invalid memo silently
@@ -2329,7 +2492,8 @@ class OneShot {
      */
     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));
+        const approval = this.approvalHeader(cfg.approvalId);
+        const quoteResp = await this.makeRequest(cfg.endpoint, cfg.payload, undefined, undefined, cfg.signal, cfg.quoteTimeoutMs, { ...this.maxCostHeader(cfg.maxCost), ...approval });
         if (quoteResp.status === 400 && cfg.on400) {
             await cfg.on400(quoteResp);
         }
@@ -2344,7 +2508,7 @@ class OneShot {
         this.assertWithinBudget(cfg.totalOf(quoteData.context));
         if (this._accessToken) {
             this.checkAbortBeforePayment(cfg.signal);
-            const execResp = await this.retryAsCreditsSession(quoteData, cfg.endpoint, cfg.payload, quoteData.context.quote_id, cfg.signal, cfg.execTimeoutMs);
+            const execResp = await this.retryAsCreditsSession(quoteData, cfg.endpoint, cfg.payload, quoteData.context.quote_id, cfg.signal, cfg.execTimeoutMs, approval);
             return { context: quoteData.context, execResp };
         }
         const paymentInfo = {
@@ -2357,10 +2521,10 @@ class OneShot {
             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 { accepted, resource, extensions } = await this.getAcceptedRequirements(quoteResp, cfg.endpoint, cfg.payload, quoteData.context.quote_id, cfg.signal, approval);
         paymentInfo.amount = this.chargeAmount(accepted, quoteData.payment_request.amount);
         const signed = await this.signPaymentAuthorization(paymentInfo, accepted, resource, extensions);
-        const execResp = await this.makePaidRequest(signed, cfg.endpoint, cfg.payload, quoteData.context.quote_id, cfg.signal, cfg.execTimeoutMs);
+        const execResp = await this.makePaidRequest(signed, cfg.endpoint, cfg.payload, quoteData.context.quote_id, cfg.signal, cfg.execTimeoutMs, approval);
         return { context: quoteData.context, execResp };
     }
     /**
@@ -2937,13 +3101,15 @@ class OneShot {
      * Quote-based routes don't include payment-required header on the initial 402.
      * If missing, probe with quote ID (no payment) to trigger the x402 middleware's 402.
      */
-    async getAcceptedRequirements(initialResp, endpoint, payload, quoteId, signal) {
+    async getAcceptedRequirements(initialResp, endpoint, payload, quoteId, signal, extraHeaders) {
         const header = initialResp.headers.get('payment-required');
         if (header) {
             return this.parsePaymentRequired(header);
         }
         // Probe: send quote ID without payment to get x402 middleware's 402
-        const probeResp = await this.makeRequest(endpoint, payload, undefined, quoteId, signal);
+        // Carries X-Approval-Id: a policy-held call's probe must reach the 402,
+        // not be held again.
+        const probeResp = await this.makeRequest(endpoint, payload, undefined, quoteId, signal, undefined, extraHeaders);
         return this.parsePaymentRequired(probeResp.headers.get('payment-required'));
     }
     async signPaymentAuthorization(paymentInfo, accepted, resource, extensions) {