@oneshot-agent/sdk 0.33.0 → 0.35.0

package/dist/index.js

@@ -55,8 +55,32 @@ 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);
+// Receipt verification (`canonicalizeReceipt`, `verifyReceipt`,
+// `receiptFromWire`, and their supporting types `SignableReceipt`,
+// `ReceiptSignatureFields`, `ReceiptJwk`, `ReceiptJwks`,
+// `ReceiptVerificationResult`, `ReceiptVerificationFailureReason`) is
+// intentionally NOT re-exported here, values OR types. `./receipt`
+// statically imports `node:crypto`, and this file is the SDK's main entry —
+// re-exporting its values would give every consumer (including browser/edge
+// bundles, which this file otherwise avoids requiring Node builtins for;
+// see the deliberate `btoa` fallback below) a hard Node-only dependency
+// with no way to opt out. Import from the `@oneshot-agent/sdk/receipt`
+// subpath instead (see package.json `exports` and the README's
+// "Verifying Receipts" section).
+//
+// Types alone erase at compile time and carry no runtime import, so a
+// type-only re-export here would be runtime-safe — but `SignableReceipt`
+// declares `providerCost` (libs/agent-sdk/src/receipt.ts), the field whose
+// removal from the public SDK surface `tests/unit/sdk-provider-cost-removed
+// .test.ts` guards. Re-exporting it from the main entry would put it back
+// on the surface that guard exists to keep clean, just via the type system
+// instead of a runtime value. `providerCost` must stay inside
+// `SignableReceipt` itself (it's part of what the signer actually signs —
+// see `canonicalizeReceipt`), so the fix is not exposing that type here,
+// 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.33.0';
+const SDK_VERSION = '0.35.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. */
@@ -216,6 +240,7 @@ class OneShot {
         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 (config.accessToken) {
             // Option D: access-token session. Exclusive with every wallet option,
@@ -305,12 +330,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', {
@@ -789,8 +821,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,
@@ -805,8 +837,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({
@@ -843,18 +875,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
      *
@@ -894,6 +950,119 @@ class OneShot {
             throw new errors_2.ToolError('Failed to delete browser profile', response.status, await response.text());
         }
     }
+    // ── LinkedIn — messaging through a human-connected account (issue #756) ──
+    //
+    // The human connects THEIR OWN LinkedIn account through a hosted login link
+    // and grants specific actions. Connection/reads are free (signed proof);
+    // sync, reply, profile view and react are paid fixed-price tools. Every
+    // write is idempotency-keyed automatically — a message LinkedIn accepted
+    // cannot be recalled.
+    async linkedinFree(method, path, opts) {
+        const url = new URL(`${this.baseUrl}/v1/tools/linkedin${path}`);
+        for (const [k, v] of Object.entries(opts.query ?? {}))
+            if (v !== undefined)
+                url.searchParams.set(k, v);
+        const response = await fetch(url.toString(), {
+            method,
+            headers: { 'Content-Type': 'application/json', ...(await this.signedReadHeaders(opts.scope ?? 'read')) },
+            ...(opts.body !== undefined ? { body: JSON.stringify(opts.body) } : {}),
+            signal: AbortSignal.timeout(60000),
+        });
+        if (!response.ok)
+            throw new errors_2.ToolError(`LinkedIn ${opts.what} failed`, response.status, await response.text());
+        return response.json();
+    }
+    /**
+     * Create a hosted LinkedIn login link. Show `url` to the human once; it
+     * expires in 30 minutes and must be opened top-level (never in an iframe).
+     * Poll `getLinkedInConnection(intent_id)` until `completed`.
+     */
+    async linkedinConnect(options) {
+        if (!Array.isArray(options.requestedActions) || options.requestedActions.length === 0) {
+            throw new errors_2.ValidationError('requestedActions must list at least one action (read, reply, view_profile, react)', 'requestedActions');
+        }
+        return this.linkedinFree('POST', '/connect', {
+            scope: 'write', what: 'connect',
+            body: { requested_actions: options.requestedActions, success_redirect_url: options.successRedirectUrl, failure_redirect_url: options.failureRedirectUrl },
+        });
+    }
+    async getLinkedInConnection(intentId) {
+        this.validate(intentId, 'intentId');
+        return this.linkedinFree('GET', `/connect/${encodeURIComponent(intentId)}`, { what: 'connection status' });
+    }
+    async listLinkedInAccounts(options = {}) {
+        return this.linkedinFree('GET', '/accounts', { what: 'accounts', query: { include_revoked: options.includeRevoked ? 'true' : undefined } });
+    }
+    async getLinkedInAccount(accountId) {
+        this.validate(accountId, 'accountId');
+        return this.linkedinFree('GET', `/accounts/${encodeURIComponent(accountId)}`, { what: 'account' });
+    }
+    /** Reconnect an existing account (keeps ownership; may narrow, never widen, the grant). */
+    async reconnectLinkedInAccount(accountId, options = {}) {
+        this.validate(accountId, 'accountId');
+        return this.linkedinFree('POST', `/accounts/${encodeURIComponent(accountId)}/reconnect`, {
+            scope: 'write', what: 'reconnect',
+            body: { requested_actions: options.requestedActions, success_redirect_url: options.successRedirectUrl, failure_redirect_url: options.failureRedirectUrl },
+        });
+    }
+    /** End the grant, cancel queued writes, delete the upstream connection. */
+    async revokeLinkedInAccount(accountId) {
+        this.validate(accountId, 'accountId');
+        return this.linkedinFree('DELETE', `/accounts/${encodeURIComponent(accountId)}`, { scope: 'write', what: 'revoke' });
+    }
+    async getLinkedInSync(accountId) {
+        this.validate(accountId, 'accountId');
+        return this.linkedinFree('GET', `/accounts/${encodeURIComponent(accountId)}/sync`, { what: 'sync status' });
+    }
+    async linkedinConversations(options) {
+        this.validate(options.accountId, 'accountId');
+        return this.linkedinFree('GET', `/accounts/${encodeURIComponent(options.accountId)}/conversations`, {
+            what: 'conversations',
+            query: { cursor: options.cursor, limit: options.limit?.toString(), since: options.since, unread: options.unread ? 'true' : undefined, archived: options.archived ? 'true' : undefined },
+        });
+    }
+    async linkedinMessages(options) {
+        this.validate(options.accountId, 'accountId');
+        return this.linkedinFree('GET', `/accounts/${encodeURIComponent(options.accountId)}/messages`, {
+            what: 'messages',
+            query: {
+                conversation_id: options.conversationId, direction: options.direction, since: options.since, changed_since: options.changedSince,
+                cursor: options.cursor, limit: options.limit?.toString(), include_deleted: options.includeDeleted ? 'true' : undefined,
+            },
+        });
+    }
+    /**
+     * One bounded, paid history-sync run (up to maxPages × 250 messages). A
+     * run that hits the bound is paused with a cursor; the next `continue`
+     * call resumes it. Check `coverage.complete` before buying another run.
+     */
+    async linkedinSync(options) {
+        this.validate(options.accountId, 'accountId');
+        const { accountId, mode, maxPages, ...rest } = options;
+        return this.tool('linkedin/sync', { ...rest, account_id: accountId, ...(mode ? { mode } : {}), ...(maxPages ? { max_pages: maxPages } : {}), timeout: options.timeout ?? 600 });
+    }
+    /** Send a reply in an existing conversation through the connected account. Paced; per-account daily cap. */
+    async linkedinReply(options) {
+        this.validate(options.accountId, 'accountId');
+        this.validate(options.conversationId, 'conversationId');
+        this.validate(options.text, 'text');
+        const { accountId, conversationId, text, ...rest } = options;
+        return this.tool('linkedin/reply', { ...rest, account_id: accountId, conversation_id: conversationId, text, timeout: options.timeout ?? 180 });
+    }
+    /** View a profile through the connected account. `notify: true` is visible to the target and cannot be undone. */
+    async linkedinViewProfile(options) {
+        this.validate(options.accountId, 'accountId');
+        this.validate(options.identifier, 'identifier');
+        const { accountId, identifier, notify, ...rest } = options;
+        return this.tool('linkedin/profile-view', { ...rest, account_id: accountId, identifier, notify: !!notify, timeout: options.timeout ?? 180 });
+    }
+    /** React to a post through the connected account. */
+    async linkedinReact(options) {
+        this.validate(options.accountId, 'accountId');
+        this.validate(options.postId, 'postId');
+        const { accountId, postId, reactionType, ...rest } = options;
+        return this.tool('linkedin/react', { ...rest, account_id: accountId, post_id: postId, reaction_type: reactionType ?? 'like', timeout: options.timeout ?? 180 });
+    }
     /**
      * Update an existing website build
      *
@@ -1487,11 +1656,42 @@ 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,
             ...(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;
@@ -1798,6 +1998,7 @@ class OneShot {
             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,
                 },
@@ -1913,7 +2114,8 @@ class OneShot {
         return this.readReliabilityJson('/v1/status', false, true);
     }
     async executeToolRequest(endpoint, options, quoteId) {
-        const reliable = /(?:^|\/)(enrich\/(profile|email)|verify\/email)$/.test(endpoint);
+        // LinkedIn writes act through a human's account and cannot be recalled: always keyed.
+        const reliable = /(?:^|\/)(enrich\/(profile|email)|verify\/email|linkedin\/(reply|profile-view|react))$/.test(endpoint);
         const key = options.idempotencyKey ?? (reliable ? ethers_1.ethers.hexlify(ethers_1.ethers.randomBytes(16)) : undefined);
         if (options.totalTimeoutMs !== undefined && (!Number.isFinite(options.totalTimeoutMs) || options.totalTimeoutMs <= 0)) {
             throw new errors_2.ValidationError('totalTimeoutMs must be positive', 'totalTimeoutMs');
@@ -2293,7 +2495,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 {
@@ -2384,7 +2586,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;
@@ -2605,7 +2807,8 @@ class OneShot {
             resp = await this.makeRequest(endpoint, data, signed.auth, quoteId, signal, timeoutMs, extraHeaders);
         }
         catch (err) {
-            if (!/(enrich\/(profile|email)|verify\/email|physical-mail\/send)$/.test(endpoint))
+            // Keyed writes may already be queued server-side after a transport failure: keep the reservation.
+            if (!/(enrich\/(profile|email)|verify\/email|physical-mail\/send|linkedin\/(reply|profile-view|react))$/.test(endpoint))
                 this.releaseUsdcReservation(signed.reservation);
             throw err;
         }