parallel-web 0.2.2 → 0.2.4

package/src/resources/beta/beta.ts

@@ -2,6 +2,32 @@
 
 import { APIResource } from '../../core/resource';
 import * as Shared from '../shared';
+import * as FindallAPI from './findall';
+import {
+  Findall,
+  FindallCancelParams,
+  FindallCancelResponse,
+  FindallCandidateMatchStatusEvent,
+  FindallCreateParams,
+  FindallEnrichInput,
+  FindallEnrichParams,
+  FindallEventsParams,
+  FindallEventsResponse,
+  FindallExtendInput,
+  FindallExtendParams,
+  FindallIngestParams,
+  FindallResultParams,
+  FindallRetrieveParams,
+  FindallRetrieveResponse,
+  FindallRun,
+  FindallRunInput,
+  FindallRunResult,
+  FindallRunStatusEvent,
+  FindallSchema,
+  FindallSchemaParams,
+  FindallSchemaUpdatedEvent,
+  IngestInput,
+} from './findall';
 import * as TaskGroupAPI from './task-group';
 import {
   TaskGroup,
@@ -36,6 +62,7 @@ import { RequestOptions } from '../../internal/request-options';
 export class Beta extends APIResource {
   taskRun: TaskRunAPI.TaskRun = new TaskRunAPI.TaskRun(this._client);
   taskGroup: TaskGroupAPI.TaskGroup = new TaskGroupAPI.TaskGroup(this._client);
+  findall: FindallAPI.Findall = new FindallAPI.Findall(this._client);
 
   /**
    * Extracts relevant content from specific web URLs.
@@ -57,6 +84,9 @@ 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;
@@ -76,9 +106,9 @@ export class Beta extends APIResource {
  */
 export interface ExcerptSettings {
   /**
-   * Optional upper bound on the total number of characters to include across all
-   * excerpts for each url. Excerpts may contain fewer characters than this limit to
-   * maximize relevance and token efficiency.
+   * 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.
    */
   max_chars_per_result?: number | null;
 }
@@ -123,40 +153,50 @@ export interface ExtractResponse {
    * Successful extract results.
    */
   results: Array<ExtractResult>;
+
+  /**
+   * Usage metrics for the extract request.
+   */
+  usage?: Array<UsageItem> | null;
+
+  /**
+   * Warnings for the extract request, if any.
+   */
+  warnings?: Array<Shared.Warning> | null;
 }
 
 /**
  * Extract result for a single URL.
  */
 export interface ExtractResult {
+  /**
+   * URL associated with the search result.
+   */
+  url: string;
+
   /**
    * Relevant excerpted content from the URL, formatted as markdown.
    */
-  excerpts: Array<string> | null;
+  excerpts?: Array<string> | null;
 
   /**
    * Full content from the URL formatted as markdown, if requested.
    */
-  full_content: string | null;
+  full_content?: string | null;
 
   /**
-   * Publish date of the webpage, if available.
+   * Publish date of the webpage in YYYY-MM-DD format, if available.
    */
-  publish_date: string | null;
+  publish_date?: string | null;
 
   /**
    * Title of the webpage, if available.
    */
-  title: string | null;
-
-  url: string;
+  title?: string | null;
 }
 
 /**
- * Fetch policy.
- *
- * Determines when to return content from the cache (faster) vs fetching live
- * content (fresher).
+ * Policy for live fetching web results.
  */
 export interface FetchPolicy {
   /**
@@ -167,16 +207,12 @@ export interface FetchPolicy {
 
   /**
    * Maximum age of cached content in seconds to trigger a live fetch. Minimum value
-   * 600 seconds (10 minutes). If not provided, a dynamic age policy will be used
-   * based on the search objective and url.
+   * 600 seconds (10 minutes).
    */
   max_age_seconds?: number | null;
 
   /**
-   * Timeout in seconds for fetching live content if unavailable in cache. If
-   * unspecified a dynamic timeout will be used based on the url, generally 15
-   * seconds for simple pages and up to 60 seconds for complex pages requiring
-   * javascript or PDF rendering.
+   * Timeout in seconds for fetching live content if unavailable in cache.
    */
   timeout_seconds?: number | null;
 }
@@ -194,26 +230,56 @@ export interface SearchResult {
    * Search ID. Example: `search_cad0a6d2dec046bd95ae900527d880e7`
    */
   search_id: string;
+
+  /**
+   * Usage metrics for the search request.
+   */
+  usage?: Array<UsageItem> | null;
+
+  /**
+   * Warnings for the search request, if any.
+   */
+  warnings?: Array<Shared.Warning> | null;
 }
 
 /**
- * A single search result from the web search API.
+ * Usage item for a single operation.
  */
-export interface WebSearchResult {
+export interface UsageItem {
   /**
-   * Text excerpts from the search result which are relevant to the request.
+   * Count of the SKU.
    */
-  excerpts: Array<string>;
+  count: number;
 
   /**
-   * Title of the search result.
+   * Name of the SKU.
    */
-  title: string;
+  name: string;
+}
 
+/**
+ * A single search result from the web search API.
+ */
+export interface WebSearchResult {
   /**
    * URL associated with the search result.
    */
   url: string;
+
+  /**
+   * Relevant excerpted content from the URL, formatted as markdown.
+   */
+  excerpts?: Array<string> | null;
+
+  /**
+   * Publish date of the webpage in YYYY-MM-DD format, if available.
+   */
+  publish_date?: string | null;
+
+  /**
+   * Title of the webpage, if available.
+   */
+  title?: string | null;
 }
 
 export interface BetaExtractParams {
@@ -230,10 +296,7 @@ export interface BetaExtractParams {
   excerpts?: boolean | ExcerptSettings;
 
   /**
-   * Body param: Fetch policy.
-   *
-   * Determines when to return content from the cache (faster) vs fetching live
-   * content (fresher).
+   * Body param: Policy for live fetching web results.
    */
   fetch_policy?: FetchPolicy | null;
 
@@ -277,8 +340,17 @@ export namespace BetaExtractParams {
 
 export interface BetaSearchParams {
   /**
-   * Body param: Upper bound on the number of characters to include in excerpts for
-   * each search result.
+   * Body param: Optional settings for returning relevant excerpts.
+   */
+  excerpts?: ExcerptSettings;
+
+  /**
+   * Body param: Policy for live fetching web results.
+   */
+  fetch_policy?: FetchPolicy | null;
+
+  /**
+   * @deprecated Body param: DEPRECATED: Use `excerpts.max_chars_per_result` instead.
    */
   max_chars_per_result?: number | null;
 
@@ -288,6 +360,14 @@ export interface BetaSearchParams {
    */
   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;
+
   /**
    * Body param: Natural-language description of what the web search is trying to
    * find. May include guidance about preferred sources or freshness. At least one of
@@ -296,7 +376,7 @@ export interface BetaSearchParams {
   objective?: string | null;
 
   /**
-   * Body param: Search processor.
+   * @deprecated Body param: DEPRECATED: use `mode` instead.
    */
   processor?: 'base' | 'pro' | null;
 
@@ -321,6 +401,7 @@ export interface BetaSearchParams {
 }
 
 Beta.TaskRun = TaskRun;
+Beta.Findall = Findall;
 
 export declare namespace Beta {
   export {
@@ -330,6 +411,7 @@ export declare namespace Beta {
     type ExtractResult as ExtractResult,
     type FetchPolicy as FetchPolicy,
     type SearchResult as SearchResult,
+    type UsageItem as UsageItem,
     type WebSearchResult as WebSearchResult,
     type BetaExtractParams as BetaExtractParams,
     type BetaSearchParams as BetaSearchParams,
@@ -361,4 +443,30 @@ export declare namespace Beta {
     type TaskGroupEventsParams as TaskGroupEventsParams,
     type TaskGroupGetRunsParams as TaskGroupGetRunsParams,
   };
+
+  export {
+    Findall as Findall,
+    type FindallCandidateMatchStatusEvent as FindallCandidateMatchStatusEvent,
+    type FindallEnrichInput as FindallEnrichInput,
+    type FindallExtendInput as FindallExtendInput,
+    type FindallRun as FindallRun,
+    type FindallRunInput as FindallRunInput,
+    type FindallRunResult as FindallRunResult,
+    type FindallRunStatusEvent as FindallRunStatusEvent,
+    type FindallSchema as FindallSchema,
+    type FindallSchemaUpdatedEvent as FindallSchemaUpdatedEvent,
+    type IngestInput as IngestInput,
+    type FindallRetrieveResponse as FindallRetrieveResponse,
+    type FindallCancelResponse as FindallCancelResponse,
+    type FindallEventsResponse as FindallEventsResponse,
+    type FindallCreateParams as FindallCreateParams,
+    type FindallRetrieveParams as FindallRetrieveParams,
+    type FindallCancelParams as FindallCancelParams,
+    type FindallEnrichParams as FindallEnrichParams,
+    type FindallEventsParams as FindallEventsParams,
+    type FindallExtendParams as FindallExtendParams,
+    type FindallIngestParams as FindallIngestParams,
+    type FindallResultParams as FindallResultParams,
+    type FindallSchemaParams as FindallSchemaParams,
+  };
 }