@oneshot-agent/sdk 0.32.1 → 0.34.0

package/dist/index.js

@@ -36,11 +36,12 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.OneShot = exports.executeSwap = exports.getSwapQuote = exports.CdpWalletProvider = exports.EthersWalletProvider = void 0;
+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);
 const deadline_1 = require("./deadline");
 const errors_1 = require("./errors");
+const read_only_1 = require("./providers/read-only");
 const ethers_1 = require("ethers");
 const ethers_2 = require("./providers/ethers");
 const errors_2 = require("./errors");
@@ -48,12 +49,14 @@ var ethers_3 = require("./providers/ethers");
 Object.defineProperty(exports, "EthersWalletProvider", { enumerable: true, get: function () { return ethers_3.EthersWalletProvider; } });
 var cdp_1 = require("./providers/cdp");
 Object.defineProperty(exports, "CdpWalletProvider", { enumerable: true, get: function () { return cdp_1.CdpWalletProvider; } });
+var read_only_2 = require("./providers/read-only");
+Object.defineProperty(exports, "ReadOnlyWalletProvider", { enumerable: true, get: function () { return read_only_2.ReadOnlyWalletProvider; } });
 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);
 // Keep in sync with package.json `version`. Guarded by version.test.ts.
-const SDK_VERSION = '0.32.1';
+const SDK_VERSION = '0.34.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. */
@@ -160,6 +163,14 @@ class OneShot {
      * ```
      */
     static async create(config) {
+        if (config.accessToken) {
+            if (config.address)
+                return new OneShot(config);
+            // The API keys job status and the WebSocket on X-Agent-ID, so the
+            // session needs its wallet address even though it never signs with it.
+            const address = await OneShot.resolveTokenAddress(config);
+            return new OneShot({ ...config, address });
+        }
         if (config.walletProvider) {
             return new OneShot(config, config.walletProvider);
         }
@@ -204,8 +215,39 @@ class OneShot {
         this._swapBufferMultiplier = validateSwapBufferMultiplier(config.swapBufferMultiplier);
         this._budgets = validateBudgetConfig(config.budgets);
         this._alertEmail = config.alerts?.email;
+        this._defaultHeaders = { ...(config.defaultHeaders ?? {}) };
+        this._stagingKey = config.stagingKey;
         this.rpcProvider = new ethers_1.ethers.JsonRpcProvider(config.rpcUrl ?? RPC_URL);
-        if (walletProvider) {
+        if (config.accessToken) {
+            // Option D: access-token session. Exclusive with every wallet option,
+            // and budgets are read-only (a delegated credential that could raise its
+            // own cap would make the cap meaningless) — set them from a wallet.
+            if (!/^oneshot_[0-9a-f]{64}$/.test(config.accessToken)) {
+                throw new errors_2.ValidationError('accessToken must be oneshot_<64 lowercase hex characters>', 'accessToken');
+            }
+            if (config.privateKey || config.cdp || config.walletProvider || walletProvider) {
+                throw new errors_2.ValidationError('accessToken cannot be combined with privateKey, cdp, or walletProvider', 'accessToken');
+            }
+            if (config.budgets || config.alerts) {
+                throw new errors_2.ValidationError('budgets and alerts are read-only for access-token sessions; set them from a wallet session or the API', 'budgets');
+            }
+            if (this._currency === 'ETH') {
+                throw new errors_2.ValidationError('ETH currency mode is not available to access-token sessions (they pay from credits)', 'currency');
+            }
+            if (!config.address) {
+                throw new errors_2.ValidationError('address is required with accessToken in the constructor; use OneShot.create() to resolve it', 'address');
+            }
+            let address;
+            try {
+                address = ethers_1.ethers.getAddress(config.address);
+            }
+            catch {
+                throw new errors_2.ValidationError('address must be a valid Ethereum address', 'address');
+            }
+            this._accessToken = config.accessToken;
+            this.provider = new read_only_1.ReadOnlyWalletProvider(address);
+        }
+        else if (walletProvider) {
             this.provider = walletProvider;
         }
         else if (config.privateKey) {
@@ -264,12 +306,19 @@ class OneShot {
         // from_mailbox, omit from_address entirely so the server picks from
         // the agent's domain pool. The chosen address comes back on the
         // quote response (`quote.from_address`) and we replay it on /send.
-        // When the caller pins either knob, we keep legacy behavior: build
-        // `${mailbox ?? 'agent'}@${domain ?? 'oneshotagent.com'}`.
+        // When the caller pins from_domain (with or without from_mailbox), we
+        // build `${mailbox ?? 'agent'}@${from_domain}`. Pinning from_mailbox
+        // alone has no domain to attach it to — `oneshotagent.com` is OneShot's
+        // own domain and no agent can send from it — so that combination is a
+        // client-side validation error rather than a guaranteed domain_not_owned
+        // rejection from the server.
+        if (options.from_mailbox && !options.from_domain) {
+            throw new errors_2.ValidationError('from_mailbox was pinned without from_domain. Pass from_domain (a domain you own) as well, or omit both to rotate across your warmed domains.', 'from_domain');
+        }
         const useRotation = !options.from_domain && !options.from_mailbox;
         const fromAddress = useRotation
             ? undefined
-            : `${options.from_mailbox ?? 'agent'}@${options.from_domain ?? 'oneshotagent.com'}`;
+            : `${options.from_mailbox ?? 'agent'}@${options.from_domain}`;
         // `mailbox_provisioning_fee` (>0) means `from_address` is a new address that
         // provisions a mailbox on first send — a one-time fee folded into `total_cost`.
         const quote = await this.tool('email/quote', {
@@ -748,8 +797,8 @@ class OneShot {
         if (options.task.length < 10) {
             throw new errors_2.ValidationError('Task must be at least 10 characters', 'task');
         }
-        if (options.max_steps !== undefined && (options.max_steps < 1 || options.max_steps > 100)) {
-            throw new errors_2.ValidationError('max_steps must be between 1 and 100', 'max_steps');
+        if (options.max_steps !== undefined && (!Number.isInteger(options.max_steps) || options.max_steps < 25 || options.max_steps > 100)) {
+            throw new errors_2.ValidationError('max_steps must be between 25 and 100', 'max_steps');
         }
         const payload = {
             task: options.task,
@@ -764,8 +813,8 @@ class OneShot {
             payload.session_id = options.session_id;
         if (options.profile_id)
             payload.profile_id = options.profile_id;
-        if (options.secrets)
-            payload.secrets = options.secrets;
+        if (options.secrets !== undefined)
+            throw new errors_2.ValidationError('secrets is unsupported; import cookies or storage_state with createBrowserProfile', 'secrets');
         if (options.max_steps)
             payload.max_steps = options.max_steps;
         const { execResp } = await this.runQuoteToPay({
@@ -802,18 +851,42 @@ class OneShot {
      * console.log(profile.id); // Use this in browser({ profile_id: ... })
      * ```
      */
-    async createBrowserProfile(name) {
+    async createBrowserProfile(name, options = {}) {
         this.validate(name, 'name');
+        if (options.cookies !== undefined && options.storage_state !== undefined)
+            throw new errors_2.ValidationError('Provide cookies or storage_state, not both', 'options');
         const response = await fetch(`${this.baseUrl}/v1/tools/browser/profiles`, {
             method: 'POST',
             headers: { 'Content-Type': 'application/json', ...(await this.signedReadHeaders()) },
-            body: JSON.stringify({ name }),
+            body: JSON.stringify({ name, ...options }),
+            signal: AbortSignal.timeout(150000),
         });
         if (!response.ok) {
             throw new errors_2.ToolError('Failed to create browser profile', response.status, await response.text());
         }
         return response.json();
     }
+    /** Open a profile login session; wait for idle before entering credentials in live_url. */
+    async startBrowserProfileSetup(profileId, startUrl) {
+        return this.browserProfileSetup(profileId, 'start', { start_url: startUrl });
+    }
+    async getBrowserProfileSetup(profileId) {
+        return this.browserProfileSetup(profileId, 'status');
+    }
+    /** Call after login and 2FA. Saves state and inspects cookies before site navigation. */
+    async finishBrowserProfileSetup(profileId) {
+        return this.browserProfileSetup(profileId, 'finish');
+    }
+    async browserProfileSetup(profileId, action, body = {}) {
+        this.validate(profileId, 'profileId');
+        const response = await fetch(`${this.baseUrl}/v1/tools/browser/profiles/${encodeURIComponent(profileId)}/setup/${action}`, {
+            method: 'POST', headers: { 'Content-Type': 'application/json', ...(await this.signedReadHeaders()) },
+            body: JSON.stringify(body), signal: AbortSignal.timeout(150000),
+        });
+        if (!response.ok)
+            throw new errors_2.ToolError('Browser profile setup failed', response.status, '');
+        return response.json();
+    }
     /**
      * List all browser profiles
      *
@@ -1246,6 +1319,13 @@ class OneShot {
         const quoteData = await quoteResp.json();
         this.log(`Compute fund quote: $${quoteData.payment_request.amount} to top up ${goalId}`);
         this.assertWithinBudget(quoteData.payment_request.amount);
+        if (this._accessToken) {
+            const fundResp = await this.retryAsCreditsSession(quoteData, path, payload, quoteData.context.quote_id);
+            if (!fundResp.ok)
+                await this.failFromResponse('Failed to fund compute goal', fundResp);
+            const json = await fundResp.json();
+            return json.data;
+        }
         const paymentInfo = {
             protocol: 'x402',
             network: `eip155:${quoteData.payment_request.chain_id}`,
@@ -1438,10 +1518,47 @@ class OneShot {
     }
     headers() {
         return {
+            ...this._defaultHeaders,
+            ...(this._stagingKey ? { 'X-Staging-Key': this._stagingKey } : {}),
             'X-Agent-ID': this.provider.address,
-            'X-OneShot-SDK-Version': SDK_VERSION
+            'X-OneShot-SDK-Version': SDK_VERSION,
+            ...(this._accessToken ? { Authorization: `Bearer ${this._accessToken}` } : {}),
         };
     }
+    /** Submit a wallet-proven application. Approval is performed by the staging operator. */
+    async applyForStaging(contact, purpose) {
+        return this.stagingOnboarding('POST', '/applications', { contact, purpose });
+    }
+    async getStagingApplication() {
+        return this.stagingOnboarding('GET', '/applications/me');
+    }
+    /** Rotates the wallet's staging key and installs it on this SDK instance. */
+    async obtainStagingKey() {
+        const result = await this.stagingOnboarding('POST', '/credential', {});
+        this._stagingKey = result.staging_key;
+        return result.staging_key;
+    }
+    async stagingOnboarding(method, path, body) {
+        if (this._accessToken)
+            throw new Error('Staging onboarding requires a wallet signer');
+        const digest = ethers_1.ethers.sha256(ethers_1.ethers.toUtf8Bytes(JSON.stringify(body ?? {}))).slice(2);
+        const headers = await this.signedReadHeaders(`staging:${method}:${path}:${digest}`);
+        if (!headers['x-agent-proof'])
+            throw new Error('Could not sign staging application');
+        const response = await fetch(`${this.baseUrl}/v1/staging${path}`, {
+            method, headers: { ...headers, 'Content-Type': 'application/json' },
+            signal: AbortSignal.timeout(10000),
+            ...(body ? { body: JSON.stringify(body) } : {}),
+        });
+        const result = await response.json();
+        if (!response.ok)
+            throw new Error(result.error ?? `Staging request failed (${response.status})`);
+        return result;
+    }
+    /** True for access-token sessions: credits-only, never signs. */
+    get isAccessTokenSession() {
+        return this._accessToken !== undefined;
+    }
     /** Auth headers plus Content-Type for JSON-body requests. */
     jsonHeaders() {
         return { 'Content-Type': 'application/json', ...this.headers() };
@@ -1457,6 +1574,10 @@ class OneShot {
      */
     async signedReadHeaders(scope = 'read') {
         const base = this.headers();
+        // The bearer token already binds the request to the agent (and is
+        // revocable); the API accepts it in place of the signed proof.
+        if (this._accessToken)
+            return base;
         try {
             const agent = this.provider.address;
             const issuedAt = Math.floor(Date.now() / 1000);
@@ -1582,6 +1703,61 @@ class OneShot {
         const body = await response.json();
         return (body.data ?? body);
     }
+    // ---------------------------------------------------------------------------
+    // Access tokens (wallet sessions only)
+    // ---------------------------------------------------------------------------
+    assertWalletSession(action) {
+        if (this._accessToken) {
+            throw new errors_2.ValidationError(`Access tokens cannot ${action}; use a wallet session`, 'accessToken');
+        }
+    }
+    /**
+     * Mint an access token for this agent: a revocable, credits-only credential
+     * for code that runs where the wallet key cannot be (hosted MCP clients,
+     * cloud runners). The plaintext is returned once and never stored.
+     *
+     * @example
+     * ```typescript
+     * const { token } = await agent.createAccessToken({ name: 'grok-bot' });
+     * // hand `token` to the hosted client; it uses OneShot.create({ accessToken: token })
+     * ```
+     */
+    async createAccessToken(opts = {}) {
+        this.assertWalletSession('mint access tokens');
+        const response = await fetch(`${this.baseUrl}/v1/agents/me/access-tokens`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json', ...(await this.signedReadHeaders('write')) },
+            body: JSON.stringify(opts.name !== undefined ? { name: opts.name } : {}),
+        });
+        if (!response.ok)
+            throw new errors_2.ToolError('Failed to create access token', response.status, await response.text());
+        const body = await response.json();
+        return body.data;
+    }
+    /** List this agent's access tokens (prefix, label, last use, spend today — never the token). */
+    async listAccessTokens(opts = {}) {
+        this.assertWalletSession('list access tokens');
+        const response = await fetch(`${this.baseUrl}/v1/agents/me/access-tokens${opts.activeOnly ? '?active=true' : ''}`, {
+            headers: await this.signedReadHeaders(),
+        });
+        if (!response.ok)
+            throw new errors_2.ToolError('Failed to list access tokens', response.status, await response.text());
+        const body = await response.json();
+        return body.data.tokens;
+    }
+    /** Revoke an access token. Sessions using it fail with 401 from the next request. */
+    async revokeAccessToken(id) {
+        this.assertWalletSession('revoke access tokens');
+        this.validate(id, 'id');
+        const response = await fetch(`${this.baseUrl}/v1/agents/me/access-tokens/${encodeURIComponent(id)}`, {
+            method: 'DELETE',
+            headers: await this.signedReadHeaders('write'),
+        });
+        if (!response.ok)
+            throw new errors_2.ToolError('Failed to revoke access token', response.status, await response.text());
+        const body = await response.json();
+        return body.data;
+    }
     /** Local fast-fail guard: throw when a quote total exceeds the caller's cap. */
     assertWithinMaxCost(total, maxCost) {
         if (maxCost && parseFloat(total) > maxCost) {
@@ -1625,6 +1801,9 @@ class OneShot {
      */
     async failFromResponse(message, response) {
         const text = await response.text();
+        const credits = response.status === 402 ? this.parseInsufficientCredits(text) : undefined;
+        if (credits)
+            throw credits;
         const rejection = response.status === 402 ? this.parsePaymentRejection(text) : undefined;
         if (rejection)
             throw rejection;
@@ -1633,6 +1812,76 @@ class OneShot {
             throw budget;
         throw new errors_2.ToolError(message, response.status, text);
     }
+    /**
+     * Map a 402 `insufficient_credits` body (access-token sessions) onto a typed
+     * error. Any other 402 falls through to the payment-rejection / quote parse.
+     */
+    parseInsufficientCredits(text) {
+        let body;
+        try {
+            body = typeof text === 'string' ? JSON.parse(text) : text;
+        }
+        catch {
+            return undefined;
+        }
+        if (!body || body.error !== 'insufficient_credits')
+            return undefined;
+        const num = (v) => (typeof v === 'string' || typeof v === 'number') && Number.isFinite(parseFloat(String(v))) ? parseFloat(String(v)) : undefined;
+        return new errors_1.InsufficientCreditsError(body.message ?? 'Credit balance does not cover this call', num(body.required_usdc), num(body.credits_balance), num(body.shortfall_usdc));
+    }
+    /**
+     * Access-token sessions never sign. When a paid call answers 402 the SDK
+     * either got the server's `insufficient_credits` verdict (throw it) or a
+     * quote (re-POST with `x-quote-id` and no payment: the server executes
+     * when the quote's credits cover it, otherwise answers `insufficient_credits`
+     * with the balance and shortfall, which failFromResponse turns into the
+     * typed error). Server-decided on purpose — the SDK holds no ledger.
+     */
+    async retryAsCreditsSession(body, endpoint, payload, quoteId, signal, timeoutMs, extraHeaders) {
+        const credits = body ? this.parseInsufficientCredits(body) : undefined;
+        if (credits)
+            throw credits;
+        const qid = quoteId ?? body?.context?.quote_id;
+        if (!qid) {
+            const amount = body?.payment_request?.amount;
+            throw new errors_1.InsufficientCreditsError(`Credits do not cover ${amount ? `$${amount}` : 'this call'}; top up credits or use a wallet session`, amount ? parseFloat(amount) : undefined);
+        }
+        this.log(`Access-token session: retrying quote ${qid} against credits`);
+        const retry = await this.makeRequest(endpoint, payload, undefined, qid, signal, timeoutMs, extraHeaders);
+        if (retry.status === 402)
+            await this.failFromResponse('Credits do not cover this call', retry);
+        return retry;
+    }
+    /** GET /v1/agents/me with the token, for OneShot.create({ accessToken }) without an address. */
+    static async resolveTokenAddress(config) {
+        const TOKEN_RESOLVE_TIMEOUT_MS = 10000;
+        const baseUrl = config.baseUrl ?? BASE_URL;
+        let response;
+        try {
+            response = await fetch(`${baseUrl}/v1/agents/me`, {
+                headers: {
+                    ...(config.defaultHeaders ?? {}),
+                    ...(config.stagingKey ? { 'X-Staging-Key': config.stagingKey } : {}),
+                    Authorization: `Bearer ${config.accessToken}`,
+                    'X-OneShot-SDK-Version': SDK_VERSION,
+                },
+                // Bounded: with no signal, Node's fetch can wait minutes on a hung
+                // connection and OneShot.create() would hang with it.
+                signal: AbortSignal.timeout(TOKEN_RESOLVE_TIMEOUT_MS),
+            });
+        }
+        catch (err) {
+            throw new errors_2.ToolError(`Could not resolve the access token's agent (network): ${err}`, 0, String(err));
+        }
+        if (!response.ok) {
+            throw new errors_2.ToolError('Could not resolve the access token\'s agent', response.status, await response.text());
+        }
+        const json = await response.json();
+        const address = json.data?.wallet_address;
+        if (!address)
+            throw new errors_2.ToolError('GET /v1/agents/me returned no wallet_address', response.status, JSON.stringify(json));
+        return address;
+    }
     /**
      * 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
@@ -1804,23 +2053,30 @@ class OneShot {
             const { accepted, resource, extensions } = this.parsePaymentRequired(paymentRequiredHeader);
             // Fallback: parse legacy body format for amount display
             const data = await response.json();
-            const paymentInfo = {
-                protocol: 'x402',
-                network: accepted.network,
-                payTo: accepted.payTo,
-                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);
-            context.phase = 'payment';
-            const signed = await this.signPaymentAuthorization(paymentInfo, accepted, resource, extensions);
-            this.checkAbortBeforePayment(signal);
-            context.phase = 'submission';
-            response = await this.makePaidRequest(signed, endpoint, payload, quoteId, signal, undefined, extraHeaders);
+            if (this._accessToken) {
+                // Credits-only session: never sign. Let the server settle it.
+                this.checkAbortBeforePayment(signal);
+                response = await this.retryAsCreditsSession(data, endpoint, payload, quoteId, signal, undefined, extraHeaders);
+            }
+            else {
+                const paymentInfo = {
+                    protocol: 'x402',
+                    network: accepted.network,
+                    payTo: accepted.payTo,
+                    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);
+                context.phase = 'payment';
+                const signed = await this.signPaymentAuthorization(paymentInfo, accepted, resource, extensions);
+                this.checkAbortBeforePayment(signal);
+                context.phase = 'submission';
+                response = await this.makePaidRequest(signed, endpoint, payload, quoteId, signal, undefined, extraHeaders);
+            }
         }
         if (!response.ok) {
             await this.failFromResponse('Tool request failed', response);
@@ -1866,6 +2122,11 @@ class OneShot {
         cfg.onQuote(quoteData.context);
         this.assertWithinMaxCost(cfg.totalOf(quoteData.context), cfg.maxCost);
         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);
+            return { context: quoteData.context, execResp };
+        }
         const paymentInfo = {
             protocol: 'x402',
             network: `eip155:${quoteData.payment_request.chain_id}`,
@@ -2096,7 +2357,7 @@ class OneShot {
                         settle(() => {
                             cleanup();
                             wait.via = 'ws';
-                            reject(new errors_2.JobError(`Job failed: ${msg.error ?? 'Unknown'}`, requestId, String(msg.error ?? 'Unknown'), msg.error_code));
+                            reject(new errors_2.JobError(`Job failed: ${msg.error ?? 'Unknown'}`, requestId, String(msg.error ?? 'Unknown'), msg.error_code, msg.result));
                         });
                     }
                     else {
@@ -2187,7 +2448,7 @@ class OneShot {
                 if (job.status === 'failed') {
                     if (wait)
                         wait.via = 'http';
-                    throw new errors_2.JobError(`Job failed: ${job.error ?? 'Unknown'}`, requestId, String(job.error ?? 'Unknown'), job.error_code);
+                    throw new errors_2.JobError(`Job failed: ${job.error ?? 'Unknown'}`, requestId, String(job.error ?? 'Unknown'), job.error_code, job.result);
                 }
                 emit?.(String(job.status));
                 retries = 0;
@@ -2487,6 +2748,11 @@ class OneShot {
                     },
                 } };
         }
+        // Belt and braces: every paid path branches to retryAsCreditsSession
+        // before reaching here in access-token mode.
+        if (this._accessToken) {
+            throw new errors_1.InsufficientCreditsError(`Credits do not cover $${paymentInfo.amount}; top up credits or use a wallet session`, parseFloat(paymentInfo.amount));
+        }
         // If paying with ETH, make sure USDC covers the charge (swapping a buffer if not) and reserve it
         const reservation = await this.ensureUsdcBalance(paymentInfo);
         const now = Math.floor(Date.now() / 1000);