parallel-web 0.3.1 → 0.3.2

package/src/client.ts

@@ -11,6 +11,7 @@ import type { APIResponseProps } from './internal/parse';
 import { getPlatformHeaders } from './internal/detect-platform';
 import * as Shims from './internal/shims';
 import * as Opts from './internal/request-options';
+import { stringifyQuery } from './internal/utils/query';
 import { VERSION } from './version';
 import * as Errors from './core/error';
 import * as Uploads from './core/uploads';
@@ -228,21 +229,8 @@ export class Parallel {
   /**
    * Basic re-implementation of `qs.stringify` for primitive types.
    */
-  protected stringifyQuery(query: Record<string, unknown>): string {
-    return Object.entries(query)
-      .filter(([_, value]) => typeof value !== 'undefined')
-      .map(([key, value]) => {
-        if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean') {
-          return `${encodeURIComponent(key)}=${encodeURIComponent(value)}`;
-        }
-        if (value === null) {
-          return `${encodeURIComponent(key)}=`;
-        }
-        throw new Errors.ParallelError(
-          `Cannot stringify type ${typeof value}; Expected string, number, boolean, or null. If you need to pass nested query parameters, you can manually encode them, e.g. { query: { 'foo[key1]': value1, 'foo[key2]': value2 } }, and please open a GitHub issue requesting better support for your use case.`,
-        );
-      })
-      .join('&');
+  protected stringifyQuery(query: object | Record<string, unknown>): string {
+    return stringifyQuery(query);
   }
 
   private getUserAgent(): string {
@@ -274,12 +262,13 @@ export class Parallel {
       : new URL(baseURL + (baseURL.endsWith('/') && path.startsWith('/') ? path.slice(1) : path));
 
     const defaultQuery = this.defaultQuery();
-    if (!isEmptyObj(defaultQuery)) {
-      query = { ...defaultQuery, ...query };
+    const pathQuery = Object.fromEntries(url.searchParams);
+    if (!isEmptyObj(defaultQuery) || !isEmptyObj(pathQuery)) {
+      query = { ...pathQuery, ...defaultQuery, ...query };
     }
 
     if (typeof query === 'object' && query && !Array.isArray(query)) {
-      url.search = this.stringifyQuery(query as Record<string, unknown>);
+      url.search = this.stringifyQuery(query);
     }
 
     return url.toString();
@@ -463,7 +452,7 @@ export class Parallel {
       loggerFor(this).info(`${responseInfo} - ${retryMessage}`);
 
       const errText = await response.text().catch((err: any) => castToError(err).message);
-      const errJSON = safeJSON(errText);
+      const errJSON = safeJSON(errText) as any;
       const errMessage = errJSON ? undefined : errText;
 
       loggerFor(this).debug(
@@ -504,9 +493,10 @@ export class Parallel {
     controller: AbortController,
   ): Promise<Response> {
     const { signal, method, ...options } = init || {};
-    if (signal) signal.addEventListener('abort', () => controller.abort());
+    const abort = this._makeAbort(controller);
+    if (signal) signal.addEventListener('abort', abort, { once: true });
 
-    const timeout = setTimeout(() => controller.abort(), ms);
+    const timeout = setTimeout(abort, ms);
 
     const isReadableBody =
       ((globalThis as any).ReadableStream && options.body instanceof (globalThis as any).ReadableStream) ||
@@ -583,9 +573,9 @@ export class Parallel {
       }
     }
 
-    // If the API asks us to wait a certain amount of time (and it's a reasonable amount),
-    // just do what it says, but otherwise calculate a default
-    if (!(timeoutMillis && 0 <= timeoutMillis && timeoutMillis < 60 * 1000)) {
+    // If the API asks us to wait a certain amount of time, just do what it
+    // says, but otherwise calculate a default
+    if (timeoutMillis === undefined) {
       const maxRetries = options.maxRetries ?? this.maxRetries;
       timeoutMillis = this.calculateDefaultRetryTimeoutMillis(retriesRemaining, maxRetries);
     }
@@ -673,6 +663,12 @@ export class Parallel {
     return headers.values;
   }
 
+  private _makeAbort(controller: AbortController) {
+    // note: we can't just inline this method inside `fetchWithTimeout()` because then the closure
+    //       would capture all request options, and cause a memory leak.
+    return () => controller.abort();
+  }
+
   private buildBody({ options: { body, headers: rawHeaders } }: { options: FinalRequestOptions }): {
     bodyHeaders: HeadersLike;
     body: BodyInit | undefined;
@@ -705,6 +701,14 @@ export class Parallel {
         (Symbol.iterator in body && 'next' in body && typeof body.next === 'function'))
     ) {
       return { bodyHeaders: undefined, body: Shims.ReadableStreamFrom(body as AsyncIterable<Uint8Array>) };
+    } else if (
+      typeof body === 'object' &&
+      headers.values.get('content-type') === 'application/x-www-form-urlencoded'
+    ) {
+      return {
+        bodyHeaders: { 'content-type': 'application/x-www-form-urlencoded' },
+        body: this.stringifyQuery(body),
+      };
     } else {
       return this.#encoder({ body, headers });
     }
@@ -729,6 +733,10 @@ export class Parallel {
 
   static toFile = Uploads.toFile;
 
+  /**
+   * The Task API executes web research and extraction tasks. Clients submit a natural-language objective with an optional input schema; the service plans retrieval, fetches relevant URLs, and returns outputs that conform to a provided or inferred JSON schema. Supports deep research style queries and can return rich structured JSON outputs. Processors trade-off between cost, latency, and quality. Each processor supports calibrated confidences.
+   * - Output metadata: citations, excerpts, reasoning, and confidence per field
+   */
   taskRun: API.TaskRun = new API.TaskRun(this);
   beta: API.Beta = new API.Beta(this);
 }

package/src/core/streaming.ts

@@ -46,7 +46,7 @@ export class Stream<Item> implements AsyncIterable<Item> {
       try {
         for await (const sse of _iterSSEMessages(response, controller)) {
           try {
-            yield JSON.parse(sse.data);
+            yield JSON.parse(sse.data) as Item;
           } catch (e) {
             logger.error(`Could not parse message into JSON:`, sse.data);
             logger.error(`From chunk:`, sse.raw);
@@ -102,7 +102,7 @@ export class Stream<Item> implements AsyncIterable<Item> {
       try {
         for await (const line of iterLines()) {
           if (done) continue;
-          if (line) yield JSON.parse(line);
+          if (line) yield JSON.parse(line) as Item;
         }
         done = true;
       } catch (e) {

package/src/internal/parse.ts

@@ -43,6 +43,12 @@ export async function defaultParseResponse<T>(client: Parallel, props: APIRespon
     const mediaType = contentType?.split(';')[0]?.trim();
     const isJSON = mediaType?.includes('application/json') || mediaType?.endsWith('+json');
     if (isJSON) {
+      const contentLength = response.headers.get('content-length');
+      if (contentLength === '0') {
+        // if there is no content we can't do anything
+        return undefined as T;
+      }
+
       const json = await response.json();
       return json as T;
     }

package/src/internal/utils/query.ts

@@ -0,0 +1,23 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { ParallelError } from '../../core/error';
+
+/**
+ * Basic re-implementation of `qs.stringify` for primitive types.
+ */
+export function stringifyQuery(query: object | Record<string, unknown>) {
+  return Object.entries(query)
+    .filter(([_, value]) => typeof value !== 'undefined')
+    .map(([key, value]) => {
+      if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean') {
+        return `${encodeURIComponent(key)}=${encodeURIComponent(value)}`;
+      }
+      if (value === null) {
+        return `${encodeURIComponent(key)}=`;
+      }
+      throw new ParallelError(
+        `Cannot stringify type ${typeof value}; Expected string, number, boolean, or null. If you need to pass nested query parameters, you can manually encode them, e.g. { query: { 'foo[key1]': value1, 'foo[key2]': value2 } }, and please open a GitHub issue requesting better support for your use case.`,
+      );
+    })
+    .join('&');
+}

package/src/internal/utils.ts

@@ -6,3 +6,4 @@ export * from './utils/env';
 export * from './utils/log';
 export * from './utils/uuid';
 export * from './utils/sleep';
+export * from './utils/query';

package/src/resources/beta/api.md

@@ -0,0 +1,84 @@
+# Beta
+
+Types:
+
+- <code><a href="./src/resources/beta/beta.ts">ExcerptSettings</a></code>
+- <code><a href="./src/resources/beta/beta.ts">ExtractError</a></code>
+- <code><a href="./src/resources/beta/beta.ts">ExtractResponse</a></code>
+- <code><a href="./src/resources/beta/beta.ts">ExtractResult</a></code>
+- <code><a href="./src/resources/beta/beta.ts">FetchPolicy</a></code>
+- <code><a href="./src/resources/beta/beta.ts">SearchResult</a></code>
+- <code><a href="./src/resources/beta/beta.ts">UsageItem</a></code>
+- <code><a href="./src/resources/beta/beta.ts">WebSearchResult</a></code>
+
+Methods:
+
+- <code title="post /v1beta/extract">client.beta.<a href="./src/resources/beta/beta.ts">extract</a>({ ...params }) -> ExtractResponse</code>
+- <code title="post /v1beta/search">client.beta.<a href="./src/resources/beta/beta.ts">search</a>({ ...params }) -> SearchResult</code>
+
+## TaskRun
+
+Types:
+
+- <code><a href="./src/resources/beta/task-run.ts">BetaRunInput</a></code>
+- <code><a href="./src/resources/beta/task-run.ts">BetaTaskRunResult</a></code>
+- <code><a href="./src/resources/beta/task-run.ts">ErrorEvent</a></code>
+- <code><a href="./src/resources/beta/task-run.ts">McpServer</a></code>
+- <code><a href="./src/resources/beta/task-run.ts">McpToolCall</a></code>
+- <code><a href="./src/resources/beta/task-run.ts">ParallelBeta</a></code>
+- <code><a href="./src/resources/beta/task-run.ts">TaskRunEvent</a></code>
+- <code><a href="./src/resources/beta/task-run.ts">Webhook</a></code>
+- <code><a href="./src/resources/beta/task-run.ts">TaskRunEventsResponse</a></code>
+
+Methods:
+
+- <code title="post /v1/tasks/runs?beta=true">client.beta.taskRun.<a href="./src/resources/beta/task-run.ts">create</a>({ ...params }) -> TaskRun</code>
+- <code title="get /v1beta/tasks/runs/{run_id}/events">client.beta.taskRun.<a href="./src/resources/beta/task-run.ts">events</a>(runID) -> TaskRunEventsResponse</code>
+- <code title="get /v1/tasks/runs/{run_id}/result?beta=true">client.beta.taskRun.<a href="./src/resources/beta/task-run.ts">result</a>(runID, { ...params }) -> BetaTaskRunResult</code>
+
+## TaskGroup
+
+Types:
+
+- <code><a href="./src/resources/beta/task-group.ts">TaskGroup</a></code>
+- <code><a href="./src/resources/beta/task-group.ts">TaskGroupRunResponse</a></code>
+- <code><a href="./src/resources/beta/task-group.ts">TaskGroupStatus</a></code>
+- <code><a href="./src/resources/beta/task-group.ts">TaskGroupEventsResponse</a></code>
+- <code><a href="./src/resources/beta/task-group.ts">TaskGroupGetRunsResponse</a></code>
+
+Methods:
+
+- <code title="post /v1beta/tasks/groups">client.beta.taskGroup.<a href="./src/resources/beta/task-group.ts">create</a>({ ...params }) -> TaskGroup</code>
+- <code title="get /v1beta/tasks/groups/{taskgroup_id}">client.beta.taskGroup.<a href="./src/resources/beta/task-group.ts">retrieve</a>(taskGroupID) -> TaskGroup</code>
+- <code title="post /v1beta/tasks/groups/{taskgroup_id}/runs">client.beta.taskGroup.<a href="./src/resources/beta/task-group.ts">addRuns</a>(taskGroupID, { ...params }) -> TaskGroupRunResponse</code>
+- <code title="get /v1beta/tasks/groups/{taskgroup_id}/events">client.beta.taskGroup.<a href="./src/resources/beta/task-group.ts">events</a>(taskGroupID, { ...params }) -> TaskGroupEventsResponse</code>
+- <code title="get /v1beta/tasks/groups/{taskgroup_id}/runs">client.beta.taskGroup.<a href="./src/resources/beta/task-group.ts">getRuns</a>(taskGroupID, { ...params }) -> TaskGroupGetRunsResponse</code>
+
+## FindAll
+
+Types:
+
+- <code><a href="./src/resources/beta/findall.ts">FindAllCandidateMatchStatusEvent</a></code>
+- <code><a href="./src/resources/beta/findall.ts">FindAllEnrichInput</a></code>
+- <code><a href="./src/resources/beta/findall.ts">FindAllExtendInput</a></code>
+- <code><a href="./src/resources/beta/findall.ts">FindAllRun</a></code>
+- <code><a href="./src/resources/beta/findall.ts">FindAllRunInput</a></code>
+- <code><a href="./src/resources/beta/findall.ts">FindAllRunResult</a></code>
+- <code><a href="./src/resources/beta/findall.ts">FindAllRunStatusEvent</a></code>
+- <code><a href="./src/resources/beta/findall.ts">FindAllSchema</a></code>
+- <code><a href="./src/resources/beta/findall.ts">FindAllSchemaUpdatedEvent</a></code>
+- <code><a href="./src/resources/beta/findall.ts">IngestInput</a></code>
+- <code><a href="./src/resources/beta/findall.ts">FindAllCancelResponse</a></code>
+- <code><a href="./src/resources/beta/findall.ts">FindAllEventsResponse</a></code>
+
+Methods:
+
+- <code title="post /v1beta/findall/runs">client.beta.findall.<a href="./src/resources/beta/findall.ts">create</a>({ ...params }) -> FindAllRun</code>
+- <code title="get /v1beta/findall/runs/{findall_id}">client.beta.findall.<a href="./src/resources/beta/findall.ts">retrieve</a>(findallID, { ...params }) -> FindAllRun</code>
+- <code title="post /v1beta/findall/runs/{findall_id}/cancel">client.beta.findall.<a href="./src/resources/beta/findall.ts">cancel</a>(findallID, { ...params }) -> unknown</code>
+- <code title="post /v1beta/findall/runs/{findall_id}/enrich">client.beta.findall.<a href="./src/resources/beta/findall.ts">enrich</a>(findallID, { ...params }) -> FindAllSchema</code>
+- <code title="get /v1beta/findall/runs/{findall_id}/events">client.beta.findall.<a href="./src/resources/beta/findall.ts">events</a>(findallID, { ...params }) -> FindAllEventsResponse</code>
+- <code title="post /v1beta/findall/runs/{findall_id}/extend">client.beta.findall.<a href="./src/resources/beta/findall.ts">extend</a>(findallID, { ...params }) -> FindAllSchema</code>
+- <code title="post /v1beta/findall/ingest">client.beta.findall.<a href="./src/resources/beta/findall.ts">ingest</a>({ ...params }) -> FindAllSchema</code>
+- <code title="get /v1beta/findall/runs/{findall_id}/result">client.beta.findall.<a href="./src/resources/beta/findall.ts">result</a>(findallID, { ...params }) -> FindAllRunResult</code>
+- <code title="get /v1beta/findall/runs/{findall_id}/schema">client.beta.findall.<a href="./src/resources/beta/findall.ts">schema</a>(findallID, { ...params }) -> FindAllSchema</code>

package/src/resources/beta/beta.ts

@@ -83,9 +83,6 @@ export class Beta extends APIResource {
 
   /**
    * Searches the web.
-   *
-   * To access this endpoint, pass the `parallel-beta` header with the value
-   * `search-extract-2025-10-10`.
    */
   search(params: BetaSearchParams, options?: RequestOptions): APIPromise<SearchResult> {
     const { betas, ...body } = params;
@@ -107,15 +104,15 @@ export interface ExcerptSettings {
   /**
    * Optional upper bound on the total number of characters to include per url.
    * Excerpts may contain fewer characters than this limit to maximize relevance and
-   * token efficiency, but will never contain fewer than 1000 characters per result.
+   * token efficiency. Values below 1000 will be automatically set to 1000.
    */
   max_chars_per_result?: number | null;
 
   /**
    * Optional upper bound on the total number of characters to include across all
    * urls. Results may contain fewer characters than this limit to maximize relevance
-   * and token efficiency, but will never contain fewer than 1000 characters per
-   * result.This overall limit applies in addition to max_chars_per_result.
+   * and token efficiency. Values below 1000 will be automatically set to 1000. This
+   * overall limit applies in addition to max_chars_per_result.
    */
   max_chars_total?: number | null;
 }
@@ -362,18 +359,22 @@ export interface BetaSearchParams {
   max_chars_per_result?: number | null;
 
   /**
-   * Body param: Upper bound on the number of results to return. May be limited by
-   * the processor. Defaults to 10 if not provided.
+   * Body param: Upper bound on the number of results to return. Defaults to 10 if
+   * not provided.
    */
   max_results?: number | null;
 
   /**
    * Body param: Presets default values for parameters for different use cases.
-   * `one-shot` returns more comprehensive results and longer excerpts to answer
-   * questions from a single response, while `agentic` returns more concise,
-   * token-efficient results for use in an agentic loop.
-   */
-  mode?: 'one-shot' | 'agentic' | null;
+   *
+   * - `one-shot` returns more comprehensive results and longer excerpts to answer
+   *   questions from a single response
+   * - `agentic` returns more concise, token-efficient results for use in an agentic
+   *   loop
+   * - `fast` trades some quality for lower latency, with best results when used with
+   *   concise and high-quality objective and keyword queries
+   */
+  mode?: 'one-shot' | 'agentic' | 'fast' | null;
 
   /**
    * Body param: Natural-language description of what the web search is trying to

package/src/resources/beta/findall.ts

@@ -9,6 +9,9 @@ import { buildHeaders } from '../../internal/headers';
 import { RequestOptions } from '../../internal/request-options';
 import { path } from '../../internal/utils/path';
 
+/**
+ * The FindAll API discovers and evaluates entities that match complex criteria from natural language objectives. Submit a high-level goal and the service automatically generates structured match conditions, discovers relevant candidates, and evaluates each against the criteria. Returns comprehensive results with detailed reasoning, citations, and confidence scores for each match decision. Streaming events and webhooks are supported.
+ */
 export class FindAll extends APIResource {
   /**
    * Starts a FindAll run.
@@ -367,6 +370,7 @@ export namespace FindAllRun {
       | 'user_cancelled'
       | 'error_occurred'
       | 'timeout'
+      | 'insufficient_funds'
       | null;
   }
 

package/src/resources/beta/task-group.ts

@@ -10,6 +10,15 @@ import { buildHeaders } from '../../internal/headers';
 import { RequestOptions } from '../../internal/request-options';
 import { path } from '../../internal/utils/path';
 
+/**
+ * The Task Group API is currently in beta and enables batch execution of many independent Task runs with group-level monitoring and failure handling.
+ *  - Submit hundreds or thousands of Tasks as a single group
+ * - Observe group progress and receive results as they complete
+ * - Real-time updates via Server-Sent Events (SSE)
+ * - Add tasks to an existing group while it is running
+ * - Group-level retry and error aggregation
+ * Status: beta and subject to change.
+ */
 export class TaskGroup extends APIResource {
   /**
    * Initiates a TaskGroup to group and track multiple runs.
@@ -233,7 +242,9 @@ export interface TaskGroupCreateParams {
 
 export interface TaskGroupAddRunsParams {
   /**
-   * Body param: List of task runs to execute.
+   * Body param: List of task runs to execute. Up to 1,000 runs can be specified per
+   * request. If you'd like to add more runs, split them across multiple TaskGroup
+   * POST requests.
    */
   inputs: Array<BetaTaskRunAPI.BetaRunInput>;
 

package/src/resources/beta/task-run.ts

@@ -10,6 +10,10 @@ import { buildHeaders } from '../../internal/headers';
 import { RequestOptions } from '../../internal/request-options';
 import { path } from '../../internal/utils/path';
 
+/**
+ * The Task API executes web research and extraction tasks. Clients submit a natural-language objective with an optional input schema; the service plans retrieval, fetches relevant URLs, and returns outputs that conform to a provided or inferred JSON schema. Supports deep research style queries and can return rich structured JSON outputs. Processors trade-off between cost, latency, and quality. Each processor supports calibrated confidences.
+ * - Output metadata: citations, excerpts, reasoning, and confidence per field
+ */
 export class TaskRun extends APIResource {
   /**
    * Initiates a task run.
@@ -109,6 +113,11 @@ export interface BetaRunInput {
    */
   metadata?: { [key: string]: string | number | boolean } | null;
 
+  /**
+   * Interaction ID to use as context for this request.
+   */
+  previous_interaction_id?: string | null;
+
   /**
    * Source policy for web search results.
    *
@@ -476,6 +485,11 @@ export interface TaskRunCreateParams {
    */
   metadata?: { [key: string]: string | number | boolean } | null;
 
+  /**
+   * Body param: Interaction ID to use as context for this request.
+   */
+  previous_interaction_id?: string | null;
+
   /**
    * Body param: Source policy for web search results.
    *

package/src/resources/task-run.ts

@@ -6,6 +6,10 @@ import { APIPromise } from '../core/api-promise';
 import { RequestOptions } from '../internal/request-options';
 import { path } from '../internal/utils/path';
 
+/**
+ * The Task API executes web research and extraction tasks. Clients submit a natural-language objective with an optional input schema; the service plans retrieval, fetches relevant URLs, and returns outputs that conform to a provided or inferred JSON schema. Supports deep research style queries and can return rich structured JSON outputs. Processors trade-off between cost, latency, and quality. Each processor supports calibrated confidences.
+ * - Output metadata: citations, excerpts, reasoning, and confidence per field
+ */
 export class TaskRun extends APIResource {
   /**
    * Initiates a task run.
@@ -131,6 +135,11 @@ export interface RunInput {
    */
   metadata?: { [key: string]: string | number | boolean } | null;
 
+  /**
+   * Interaction ID to use as context for this request.
+   */
+  previous_interaction_id?: string | null;
+
   /**
    * Source policy for web search results.
    *
@@ -158,6 +167,12 @@ export interface TaskRun {
    */
   created_at: string | null;
 
+  /**
+   * Identifier for this interaction. Pass this value as `previous_interaction_id` to
+   * reuse context for a future request.
+   */
+  interaction_id: string;
+
   /**
    * Whether the run is currently active, i.e. status is one of {'cancelling',
    * 'queued', 'running'}.
@@ -355,6 +370,11 @@ export interface TaskRunCreateParams {
    */
   metadata?: { [key: string]: string | number | boolean } | null;
 
+  /**
+   * Interaction ID to use as context for this request.
+   */
+  previous_interaction_id?: string | null;
+
   /**
    * Source policy for web search results.
    *

package/src/version.ts

@@ -1 +1 @@
-export const VERSION = '0.3.1'; // x-release-please-version
+export const VERSION = '0.3.2'; // x-release-please-version

package/version.d.mts

@@ -1,2 +1,2 @@
-export declare const VERSION = "0.3.1";
+export declare const VERSION = "0.3.2";
 //# sourceMappingURL=version.d.mts.map

package/version.d.ts

@@ -1,2 +1,2 @@
-export declare const VERSION = "0.3.1";
+export declare const VERSION = "0.3.2";
 //# sourceMappingURL=version.d.ts.map

package/version.js

@@ -1,5 +1,5 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.VERSION = void 0;
-exports.VERSION = '0.3.1'; // x-release-please-version
+exports.VERSION = '0.3.2'; // x-release-please-version
 //# sourceMappingURL=version.js.map

package/version.mjs

@@ -1,2 +1,2 @@
-export const VERSION = '0.3.1'; // x-release-please-version
+export const VERSION = '0.3.2'; // x-release-please-version
 //# sourceMappingURL=version.mjs.map