@oneshot-agent/sdk 0.50.0 → 0.52.0

package/dist/index.js

@@ -65,7 +65,7 @@ const approvals_1 = require("./approvals");
 // stay off this public surface (see tests/unit/sdk-provider-cost-removed.test.ts).
 // Import from the `@oneshot-agent/sdk/receipt` subpath instead.
 // Keep in sync with package.json `version`. Guarded by version.test.ts.
-const SDK_VERSION = '0.50.0';
+const SDK_VERSION = '0.52.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. */
@@ -145,6 +145,8 @@ function validateBudgetConfig(budgets) {
     fraction(budgets.pauseAt, 'pauseAt');
     return budgets;
 }
+/** The keys executeToolRequestImpl takes out of a request as SDK options, so they never reach the API body. */
+const PAID_ROUTE_OPTION_KEYS = ['timeout', 'totalTimeoutMs', 'onRequestCreated', 'onAccepted', 'signal', 'onStatusUpdate', 'wait', 'waitForPhones', 'phoneTimeoutSec', 'idempotencyKey', 'approvalId', 'maxCost'];
 class OneShot {
     /**
      * Async factory — required for CDP wallets (account creation is async).
@@ -455,48 +457,48 @@ class OneShot {
         this.validate(options.topic, 'topic');
         return this.tool('research', { ...options });
     }
-    async peopleSearch(options) {
-        return this.tool('research/people', { ...options, limit: options.limit ?? 100 });
+    async personFind(options) {
+        return this.tool('find/person', { ...options, limit: options.limit ?? 100 });
     }
-    async enrichProfile(options) {
+    async personProfile(options) {
         if (!options.linkedin_url && !options.email && !options.name) {
             throw new errors_2.ValidationError('At least one of linkedin_url, email, or name is required', 'identifier');
         }
-        return this.tool('enrich/profile', { ...options });
+        return this.tool('lookup/person-profile', { ...options });
     }
-    async companySearch(options = {}) {
-        return this.tool('research/company', { ...options, limit: options.limit ?? 10 });
+    async companyFind(options = {}) {
+        return this.tool('find/company', { ...options, limit: options.limit ?? 10 });
     }
-    async enrichCompany(options) {
+    async companyProfile(options) {
         if (!options.domain && !options.name && !options.linkedin_url && !options.ticker) {
             throw new errors_2.ValidationError('At least one of domain, name, linkedin_url, or ticker is required', 'identifier');
         }
-        return this.tool('enrich/company', { ...options });
+        return this.tool('lookup/company-profile', { ...options });
     }
     /**
      * Discover local businesses (restaurants, contractors, practices) by
      * category/keywords × location. Flat price per search, not per row.
      */
-    async localSearch(options) {
+    async businessFind(options) {
         if (!options.location || options.location.length === 0) {
             throw new errors_2.ValidationError('location is required (e.g. ["Austin, TX"])', 'location');
         }
         if (!(options.category && options.category.length) && !(options.keywords && options.keywords.length)) {
             throw new errors_2.ValidationError('At least one of category or keywords is required', 'category');
         }
-        return this.tool('local/search', { ...options, limit: options.limit ?? 100 });
+        return this.tool('find/business', { ...options, limit: options.limit ?? 100 });
     }
     /**
      * Resolve a business name + one locating field to its domain, phone,
      * category and operating status. A miss resolves with `found: false`
      * (a completed job), never a rejection.
      */
-    async localResolve(options) {
+    async businessResolve(options) {
         this.validate(options.name, 'name');
         if (!options.address && !options.city && !options.postal_code && !options.phone) {
             throw new errors_2.ValidationError('name plus at least one of address, city, postal_code, or phone is required', 'address');
         }
-        return this.tool('local/resolve', { ...options });
+        return this.tool('resolve/business', { ...options });
     }
     /**
      * Federal contract opportunities (SAM.gov) by NAICS code — Sources Sought
@@ -505,7 +507,7 @@ class OneShot {
      * `data_as_of` on the result is the snapshot behind the rows (SAM.gov's
      * daily extract publish time, or "now" when the live API served).
      */
-    async govSolicitations(options) {
+    async recordSolicitationsFind(options) {
         if (!options.naics || options.naics.length === 0) {
             throw new errors_2.ValidationError('naics is required (one or more 6-digit codes, e.g. ["541511"])', 'naics');
         }
@@ -513,53 +515,53 @@ class OneShot {
         if (bad !== undefined) {
             throw new errors_2.ValidationError(`NAICS codes are 6 digits (got ${JSON.stringify(bad)})`, 'naics');
         }
-        return this.tool('gov/solicitations', {
+        return this.tool('find/record-solicitations', {
             ...options,
             notice_types: options.notice_types ?? ['r', 'p'],
             limit: options.limit ?? 100,
         });
     }
-    async findEmail(options) {
+    async personEmail(options) {
         this.validate(options.company_domain, 'company_domain');
         if (!options.full_name && !(options.first_name && options.last_name)) {
             throw new errors_2.ValidationError('Either full_name or both first_name and last_name required', 'name');
         }
-        return this.tool('enrich/email', { ...options });
+        return this.tool('lookup/person-email', { ...options });
     }
-    async verifyEmail(options) {
+    async personEmailStatus(options) {
         this.validate(options.email, 'email');
-        return this.tool('verify/email', { ...options });
+        return this.tool('lookup/person-email-status', { ...options });
     }
-    async deepResearchPerson(options) {
+    async personDossier(options) {
         if (!options.email && !options.social_media_url && !options.name) {
             throw new errors_2.ValidationError('At least one of email, social_media_url, or name is required', 'identifier');
         }
-        return this.tool('research/person', { ...options });
+        return this.tool('lookup/person-dossier', { ...options });
     }
-    async socialProfiles(options) {
+    async personSocialAccounts(options) {
         if (!options.email && !options.social_media_url) {
             throw new errors_2.ValidationError('At least one of email or social_media_url is required', 'identifier');
         }
-        return this.tool('research/social', { ...options });
+        return this.tool('lookup/person-social-accounts', { ...options });
     }
-    async articleSearch(options) {
+    async personArticles(options) {
         this.validate(options.name, 'name');
         this.validate(options.company, 'company');
-        return this.tool('research/articles', { ...options });
+        return this.tool('lookup/person-articles', { ...options });
     }
-    async personNewsfeed(options) {
+    async personPosts(options) {
         this.validate(options.social_media_url, 'social_media_url');
-        return this.tool('research/newsfeed', { ...options });
+        return this.tool('lookup/person-posts', { ...options });
     }
     async personInterests(options) {
         if (!options.email && !options.phone && !options.social_media_url) {
             throw new errors_2.ValidationError('At least one of email, phone, or social_media_url is required', 'identifier');
         }
-        return this.tool('research/interests', { ...options });
+        return this.tool('lookup/person-interests', { ...options });
     }
-    async personInteractions(options) {
+    async personFollowers(options) {
         this.validate(options.social_media_url, 'social_media_url');
-        return this.tool('research/interactions', { ...options });
+        return this.tool('lookup/person-followers', { ...options });
     }
     async inboxList(options = {}) {
         const qs = this.buildQuery({
@@ -1295,6 +1297,95 @@ class OneShot {
         this.validate(callId, 'callId');
         return this.signedJson('GET', `/v1/tools/voice/inbound/${encodeURIComponent(callId)}`, undefined, 'read', 'Failed to get inbound call');
     }
+    /**
+     * Call a declared route of the API by method and path (#1580), the one generic call for a route that has no
+     * typed method. Follows the Python client's `call_free_get/post/patch/put/delete`:
+     *
+     * - `path` is the route, with `{name}` (or `:name`) for a path parameter, filled from `params` and URL-encoded
+     *   (`/v1/compute/{goal_id}/budget`). It must start with `/v1/` and hold no `..` or `?`.
+     * - `query` is the query string (null/undefined left out; booleans `true`/`false`; objects and arrays as JSON).
+     * - `body` is the JSON body of a `POST`, `PUT` or `PATCH` (an object field is sent as it is); a `GET` or
+     *   `DELETE` sends none.
+     * - A free route is authorised like the other free calls: a signed proof (read scope for `GET`, write scope for
+     *   any other method) or, in an access-token session, the bearer token. Returns the `data` field of
+     *   `{ success, data }`, or the whole body when there is none; an empty answer is `{ success: true }`.
+     * - `paid: true` sends the route through the quote-to-pay flow of {@link OneShot.tool} (a `POST` only), with the
+     *   {@link ToolOptions} (`maxCost`, `idempotencyKey`, `wait`, `signal`, ...) given in `options`.
+     *
+     * @example
+     * ```typescript
+     * const budget = await agent.route('GET', '/v1/compute/{goal_id}/budget', { params: { goal_id: 'goal_01HX' } });
+     * const changes = await agent.route('POST', '/v1/tools/changes', { paid: true, body: { attribute: 'vehicle_identification', key: '1HGCM82633A004352', since: '2026-01-01' } });
+     * ```
+     */
+    async route(method, path, options = {}) {
+        const { params = {}, query = {}, body, paid = false, ...toolOptions } = options;
+        if (!['GET', 'POST', 'PUT', 'PATCH', 'DELETE'].includes(method))
+            throw new errors_2.ValidationError(`Not an HTTP method of the API: ${method}`, 'method');
+        if (!path.startsWith('/v1/') || path.includes('..') || path.includes('?') || path.includes('#')) {
+            throw new errors_2.ValidationError(`Not a route of the API: ${path}`, 'path');
+        }
+        const filled = path.replace(/\{([A-Za-z0-9_]+)\}|:([A-Za-z0-9_]+)/g, (_match, braced, colon) => {
+            const name = braced ?? colon;
+            const value = params[name];
+            if ((typeof value !== 'string' && typeof value !== 'number') || String(value) === '') {
+                throw new errors_2.ValidationError(`${name} is required to call ${method} ${path}`, name);
+            }
+            return encodeURIComponent(String(value));
+        });
+        const qs = new URLSearchParams();
+        for (const [key, value] of Object.entries(query)) {
+            if (value === undefined || value === null)
+                continue;
+            qs.set(key, typeof value === 'boolean' ? (value ? 'true' : 'false') : typeof value === 'object' ? JSON.stringify(value) : String(value));
+        }
+        const target = qs.size ? `${filled}?${qs.toString()}` : filled;
+        if (paid) {
+            if (method !== 'POST')
+                throw new errors_2.ValidationError(`A paid route is called with POST, not ${method}`, 'method');
+            // executeToolRequestImpl strips these keys out of the payload as SDK options, so a body field of the same
+            // name would be dropped silently: refuse it, and tell the caller to send it as an option or rename it.
+            for (const name of PAID_ROUTE_OPTION_KEYS) {
+                if (body && name in body)
+                    throw new errors_2.ValidationError(`The body field "${name}" of ${path} is an option of the SDK call and would not reach the API`, name);
+            }
+            return this.executeToolRequest(target, { ...(body ?? {}), ...toolOptions });
+        }
+        const sendsBody = method !== 'GET' && method !== 'DELETE';
+        const scope = (0, deadline_1.deadlineScope)(toolOptions.signal, filled.startsWith('/v1/tools/browser/profiles') ? 150000 : 30000);
+        try {
+            const request = (async () => {
+                const response = await fetch(`${this.baseUrl}${target}`, {
+                    method,
+                    headers: { ...(sendsBody ? { 'Content-Type': 'application/json' } : {}), ...(await this.signedReadHeaders(method === 'GET' ? 'read' : 'write')) },
+                    ...(sendsBody ? { body: JSON.stringify(body ?? {}) } : {}),
+                    signal: scope.signal,
+                });
+                if (!response.ok) {
+                    if (response.status === 409 && filled.startsWith('/v1/tools/linkedin/')) {
+                        const text = await response.clone().text();
+                        let code;
+                        try {
+                            code = JSON.parse(text)?.error;
+                        }
+                        catch { /* Not JSON. */ }
+                        if (code === 'connect_required')
+                            throw new errors_1.LinkedInConnectRequiredError(text);
+                    }
+                    await this.failFromResponse(`${method} ${filled} failed`, response);
+                }
+                const text = await response.text();
+                if (response.status === 204 || !text)
+                    return { success: true };
+                const json = JSON.parse(text);
+                return (json && typeof json === 'object' && 'data' in json ? json.data : json);
+            })();
+            return await (0, deadline_1.abortable)(request, scope.signal);
+        }
+        finally {
+            scope.close();
+        }
+    }
     /** Signed free request returning the `data` field of `{ success, data }`. */
     async signedJson(method, path, body, scope, failure) {
         const response = await fetch(`${this.baseUrl}${path}`, {
@@ -1701,11 +1792,17 @@ class OneShot {
         return json.data;
     }
     /**
-     * Top up budget for a recurring compute goal.
+     * Top up budget for a recurring compute goal, or for a goal (one-off or recurring) that
+     * ended because it ran out of budget (`end_reason: 'budget_exhausted'`).
      *
      * Uses the quote-then-pay flow: the first call gets a 402 with the top-up price,
      * the second call (with payment) credits the budget. The amount IS the price.
      *
+     * Funding a goal that ran out of budget sets it back to `active` and wakes it; it keeps its
+     * id, tasks, workspace, outputs, done-check and deadline. A goal that ended any other way, or
+     * whose deadline has passed, is refused (`invalid_state` / `deadline_passed`). While the first
+     * ending's refund is still settling the call fails with a retryable `refund_pending` (409).
+     *
      * @example
      * ```typescript
      * const result = await agent.fundComputeGoal('goal_01HX...', 10.00);
@@ -1900,7 +1997,7 @@ class OneShot {
      * await agent.tagReceiptValue('rcpt_01HX...', { type: 'revenue', amount: 5.00, label: 'Sale from lead' });
      *
      * // By the request_id you already kept from the call:
-     * const r = await agent.verifyEmail({ email: 'x@y.com' });
+     * const r = await agent.personEmailStatus({ email: 'x@y.com' });
      * await agent.tagReceiptValue({ requestId: r.request_id }, { type: 'lead', amount: 1 });
      *
      * // By cadence correlation key — one call attributes a closed deal to the whole sequence:
@@ -2484,7 +2581,7 @@ class OneShot {
     }
     async executeToolRequest(endpoint, options, quoteId) {
         // LinkedIn writes act through a human's account and cannot be recalled: always keyed.
-        const reliable = /(?:^|\/)(enrich\/(profile|email)|verify\/email|linkedin\/(reply|message|profile-view|react|invite(?:\/withdraw)?))$/.test(endpoint);
+        const reliable = /(?:^|\/)(lookup\/person-(profile|email|email-status)|lookup\/place-permits|linkedin\/(reply|message|profile-view|react|invite(?:\/withdraw)?))$/.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');
@@ -2511,7 +2608,7 @@ class OneShot {
         }
     }
     async executeToolRequestImpl(endpoint, options, quoteId, context = { phase: "initialization" }) {
-        const { totalTimeoutMs, onRequestCreated, onAccepted, signal, onStatusUpdate, wait = true, waitForPhones, phoneTimeoutSec, idempotencyKey, approvalId, maxCost, ...payload } = options;
+        const { timeout, totalTimeoutMs, onRequestCreated, onAccepted, signal, onStatusUpdate, wait = true, waitForPhones, phoneTimeoutSec, idempotencyKey, approvalId, maxCost, ...payload } = options;
         const extraHeaders = {
             ...this.maxCostHeader(maxCost),
             ...this.idempotencyHeader(idempotencyKey),
@@ -2562,6 +2659,7 @@ class OneShot {
             const { accepted, resource, extensions } = this.parsePaymentRequired(paymentRequiredHeader);
             // Fallback: parse legacy body format for amount display
             const data = await response.json();
+            quoteId ?? (quoteId = data.context?.quote_id);
             if (this._accessToken) {
                 // Credits-only session: never sign. Let the server settle it.
                 this.checkAbortBeforePayment(signal);
@@ -2609,7 +2707,7 @@ class OneShot {
             if (!wait) {
                 return { ...result, idempotencyKey };
             }
-            const completed = await this.pollJob(result.request_id, options.timeout, signal, onStatusUpdate, waitForPhones ? { waitForPhones, phoneTimeoutSec } : undefined);
+            const completed = await this.pollJob(result.request_id, timeout, signal, onStatusUpdate, waitForPhones ? { waitForPhones, phoneTimeoutSec } : undefined);
             if (completed && typeof completed === 'object' && !Array.isArray(completed)) {
                 return { ...completed, request_id: context.requestId, receipt_id: completed.receipt_id ?? context.receiptId, idempotencyKey };
             }
@@ -2738,8 +2836,7 @@ class OneShot {
      * has a pending async webhook and the webhook URL is configured; the webhook
      * handler flips it to false (or removes it) once phones arrive.
      *
-     * Tolerates two shapes: the unwrapped result `{phones_pending}` and the
-     * deep_research_person wrapper `{result: {phones_pending}}`.
+     * Accepts legacy flat results and person_dossier's result.profile.data.
      */
     _isPhonesPending(result) {
         if (!result || typeof result !== 'object')
@@ -2750,6 +2847,9 @@ class OneShot {
         const inner = r.result;
         if (inner && typeof inner === 'object' && inner.phones_pending === true)
             return true;
+        const profile = inner?.profile;
+        if (profile?.data?.phones_pending === true)
+            return true;
         return false;
     }
     /**
@@ -3075,7 +3175,7 @@ class OneShot {
         // alone (401 proof_required).
         const unsignedStub = payment?.payload?.signature === '0x';
         const askedForProof = !!extraHeaders?.['x-agent-proof'];
-        const proofScope = /(enrich\/(profile|email)|verify\/email|physical-mail\/send)$/.test(endpoint)
+        const proofScope = /(lookup\/person-(profile|email|email-status)|lookup\/place-permits|physical-mail\/send)$/.test(endpoint)
             ? 'submit'
             : askedForProof ? 'read' : 'write';
         const headers = {
@@ -3260,7 +3360,7 @@ class OneShot {
         }
         catch (err) {
             // 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|message|profile-view|react|invite(?:\/withdraw)?))$/.test(endpoint))
+            if (!/(lookup\/person-(profile|email|email-status)|lookup\/place-permits|physical-mail\/send|linkedin\/(reply|message|profile-view|react|invite(?:\/withdraw)?))$/.test(endpoint))
                 this.releaseUsdcReservation(signed.reservation);
             throw err;
         }