exa-js 1.7.2 → 1.7.4

package/README.md

@@ -190,7 +190,7 @@ Each chunk contains:
 - `content`: A string containing the next piece of generated text
 - `citations`: An array of citation objects containing source information
 
-### `exa.research.createTask(input: object, options?: { schema?: object }): Promise<ResearchTaskResponse>`
+### `exa.research.createTask(input: object, options?: { schema?: object }): Promise<{id: string}>`
 
 Exa's research agent can autonomously gather information and return a structured JSON object that conforms to a schema you provide.
 
@@ -207,12 +207,13 @@ const schema = {
   },
 };
 
-const response = await exa.research.createTask(
+const { id: taskId } = await exa.research.createTask(
   {
     instructions: "In ≤3 sentences, explain quantum computing.",
   },
   { schema }
 );
+const result = await exa.research.pollTask(taskId);
 ```
 
 Use the `status` field to poll long-running tasks if needed (a future `getTask` helper will be added when the async API is released).

package/dist/index.d.mts

@@ -79,6 +79,25 @@ interface components {
                 label: string;
             }[];
         };
+        CreateStreamParameters: {
+            /** @description Behavior to perform when stream runs */
+            behavior: components["schemas"]["StreamBehaviorSearch"] | components["schemas"]["StreamBehaviorRefresh"];
+            /** @description How often the stream will run */
+            cadence: {
+                /** @description Cron expression for stream cadence (must be a valid Unix cron with 5 fields). The schedule must trigger at most once per day. */
+                cron: string;
+                /**
+                 * @description IANA timezone (e.g., "America/New_York")
+                 * @default Etc/UTC
+                 */
+                timezone: string;
+            };
+            metadata?: {
+                [key: string]: string;
+            };
+            /** @description The id of the Webset */
+            websetId: string;
+        };
         CreateWebhookParameters: {
             /** @description The events to trigger the webhook */
             events: components["schemas"]["EventType"][];
@@ -130,14 +149,13 @@ interface components {
         };
         CreateWebsetSearchParameters: {
             /**
-             * WebsetSearchBehaviour
-             * @description The behaviour of the Search when it is added to a Webset.
+             * @description The behavior of the Search when it is added to a Webset.
              *
-             *     - `override`: the search will reuse the existing Items found in the Webset and evaluate them against the new criteria. Any Items that don't match the new criteria will be discarded.
+             *     - `override`: the search will replace the existing Items found in the Webset and evaluate them against the new criteria. Any Items that don't match the new criteria will be discarded.
+             *     - `append`: the search will add the new Items found to the existing Webset. Any Items that don't match the new criteria will be discarded.
              * @default override
-             * @enum {string}
              */
-            behaviour: CreateWebsetSearchParametersBehaviour;
+            behavior: WebsetSearchBehavior;
             /** @description Number of Items the Search will attempt to find.
              *
              *     The actual number of Items found may be less than this number depending on the query complexity. */
@@ -162,7 +180,7 @@ interface components {
         EnrichmentResult: {
             /** @description The id of the Enrichment that generated the result */
             enrichmentId: string;
-            format: components["schemas"]["WebsetEnrichmentFormat"];
+            format: WebsetEnrichmentFormat;
             /**
              * @default enrichment_result
              * @constant
@@ -388,6 +406,22 @@ interface components {
             /** @description The cursor to paginate through the next set of results */
             nextCursor: string | null;
         };
+        ListStreamRunsResponse: {
+            /** @description The list of stream runs */
+            data: components["schemas"]["StreamRun"][];
+            /** @description Whether there are more results to paginate through */
+            hasMore: boolean;
+            /** @description The cursor to paginate through the next set of results */
+            nextCursor: string | null;
+        };
+        ListStreamsResponse: {
+            /** @description The list of streams */
+            data: components["schemas"]["Stream"][];
+            /** @description Whether there are more results to paginate through */
+            hasMore: boolean;
+            /** @description The cursor to paginate through the next set of results */
+            nextCursor: string | null;
+        };
         ListWebhookAttemptsResponse: {
             /** @description The list of webhook attempts */
             data: components["schemas"]["WebhookAttempt"][];
@@ -420,6 +454,172 @@ interface components {
             /** @description The cursor to paginate through the next set of results */
             nextCursor: string | null;
         };
+        Stream: {
+            /** @description Behavior to perform when stream runs */
+            behavior: components["schemas"]["StreamBehaviorSearch"] | components["schemas"]["StreamBehaviorRefresh"];
+            /** @description How often the stream will run */
+            cadence: {
+                /** @description Cron expression for stream cadence (must be a valid Unix cron with 5 fields). The schedule must trigger at most once per day. */
+                cron: string;
+                /**
+                 * @description IANA timezone (e.g., "America/New_York")
+                 * @default Etc/UTC
+                 */
+                timezone: string;
+            };
+            /**
+             * Format: date-time
+             * @description When the stream was created
+             */
+            createdAt: string;
+            /** @description The unique identifier for the Stream */
+            id: string;
+            /**
+             * StreamRun
+             * @description The last run of the stream
+             */
+            lastRun: components["schemas"]["StreamRun"];
+            /** @description Set of key-value pairs you want to associate with this object. */
+            metadata: {
+                [key: string]: string;
+            };
+            /**
+             * Format: date-time
+             * @description When the next run will occur
+             */
+            nextRunAt: string | null;
+            /**
+             * @description The type of object
+             * @enum {string}
+             */
+            object: StreamObject;
+            /**
+             * @description The status of the Stream
+             * @enum {string}
+             */
+            status: StreamStatus;
+            /**
+             * Format: date-time
+             * @description When the stream was last updated
+             */
+            updatedAt: string;
+            /** @description The id of the Webset the Stream belongs to */
+            websetId: string;
+        };
+        StreamBehaviorRefresh: {
+            /** @description Specify the target of the refresh */
+            config: components["schemas"]["StreamRefreshBehaviorEnrichmentsConfig"] | components["schemas"]["StreamRefreshBehaviorContentsConfig"];
+            /**
+             * @default refresh
+             * @constant
+             */
+            type: "refresh";
+        };
+        StreamBehaviorSearch: {
+            config: {
+                /**
+                 * @description The behaviour of the Search when it is added to a Webset.
+                 * @default append
+                 */
+                behavior?: WebsetSearchBehavior;
+                /** @description The maximum number of results to find */
+                count: number;
+                criteria: {
+                    description: string;
+                }[];
+                /** WebsetEntity */
+                entity: components["schemas"]["WebsetEntity"];
+                query: string;
+            };
+            /**
+             * @default search
+             * @constant
+             */
+            type: "search";
+        };
+        StreamCadence: {
+            /** @description Cron expression for stream cadence (must be a valid Unix cron with 5 fields). The schedule must trigger at most once per day. */
+            cron: string;
+            /**
+             * @description IANA timezone (e.g., "America/New_York")
+             * @default Etc/UTC
+             */
+            timezone: string;
+        };
+        StreamRefreshBehaviorContentsConfig: {
+            /**
+             * @default contents
+             * @constant
+             */
+            target: "contents";
+        };
+        StreamRefreshBehaviorEnrichmentsConfig: {
+            /** @description Only refresh specific enrichments */
+            enrichments?: {
+                ids?: string[];
+            };
+            /**
+             * @default enrichments
+             * @constant
+             */
+            target: "enrichments";
+        };
+        StreamRun: {
+            /**
+             * Format: date-time
+             * @description When the run was canceled
+             */
+            canceledAt: string | null;
+            /**
+             * Format: date-time
+             * @description When the run completed
+             */
+            completedAt: string | null;
+            /**
+             * Format: date-time
+             * @description When the run was created
+             */
+            createdAt: string;
+            /**
+             * Format: date-time
+             * @description When the run failed
+             */
+            failedAt: string | null;
+            /** @description The unique identifier for the Stream Run */
+            id: string;
+            /**
+             * @description The type of object
+             * @enum {string}
+             */
+            object: StreamRunObject;
+            /**
+             * @description The status of the Stream Run
+             * @enum {string}
+             */
+            status: StreamRunStatus;
+            /** @description The stream that the run is associated with */
+            streamId: string;
+            /**
+             * @description The type of the Stream Run
+             * @enum {string}
+             */
+            type: StreamRunType;
+            /**
+             * Format: date-time
+             * @description When the run was last updated
+             */
+            updatedAt: string;
+        };
+        UpdateStream: {
+            metadata?: {
+                [key: string]: string;
+            };
+            /**
+             * @description The status of the stream.
+             * @enum {string}
+             */
+            status?: UpdateStreamStatus;
+        };
         UpdateWebhookParameters: {
             /** @description The events to trigger the webhook */
             events?: components["schemas"]["EventType"][];
@@ -549,6 +749,8 @@ interface components {
              * @enum {string}
              */
             status: WebsetStatus;
+            /** @description The Streams for the Webset. */
+            streams: components["schemas"]["Stream"][];
             /**
              * Format: date-time
              * @description The date and time the webset was updated
@@ -589,7 +791,7 @@ interface components {
             /** @description The description of the enrichment task provided during the creation of the enrichment. */
             description: string;
             /** @description The format of the enrichment response. */
-            format: components["schemas"]["WebsetEnrichmentFormat"];
+            format: WebsetEnrichmentFormat;
             /** @description The unique identifier for the enrichment */
             id: string;
             /** @description The instructions for the enrichment Agent.
@@ -635,7 +837,6 @@ interface components {
             websetId: string;
         };
         /** @enum {string} */
-        WebsetEnrichmentFormat: WebsetEnrichmentFormat;
         WebsetEntity: components["schemas"]["WebsetCompanyEntity"] | components["schemas"]["WebsetPersonEntity"] | components["schemas"]["WebsetArticleEntity"] | components["schemas"]["WebsetResearchPaperEntity"] | components["schemas"]["WebsetCustomEntity"];
         WebsetItem: {
             /**
@@ -840,16 +1041,21 @@ interface components {
             type: "research_paper";
         };
         WebsetSearch: {
+            /**
+             * @description The behavior of the search when it is added to a Webset.
+             *
+             *     - `override`: the search will replace the existing Items found in the Webset and evaluate them against the new criteria. Any Items that don't match the new criteria will be discarded.
+             *     - `append`: the search will add the new Items found to the existing Webset. Any Items that don't match the new criteria will be discarded.
+             * @default override
+             */
+            behavior: WebsetSearchBehavior;
             /**
              * Format: date-time
              * @description The date and time the search was canceled
              */
             canceledAt: string | null;
-            /**
-             * @description The reason the search was canceled
-             * @enum {string|null}
-             */
-            canceledReason: WebsetSearchCanceledReason;
+            /** @description The reason the search was canceled */
+            canceledReason: WebsetSearchCanceledReason | null;
             /** @description The number of results the search will attempt to find. The actual number of results may be less than this number depending on the search complexity. */
             count: number;
             /**
@@ -911,6 +1117,7 @@ interface components {
     pathItems: never;
 }
 type CreateEnrichmentParameters = components["schemas"]["CreateEnrichmentParameters"];
+type CreateStreamParameters = components["schemas"]["CreateStreamParameters"];
 type CreateWebhookParameters = components["schemas"]["CreateWebhookParameters"];
 type CreateWebsetParameters = components["schemas"]["CreateWebsetParameters"];
 type CreateWebsetSearchParameters = components["schemas"]["CreateWebsetSearchParameters"];
@@ -918,10 +1125,15 @@ type EnrichmentResult = components["schemas"]["EnrichmentResult"];
 type Event = components["schemas"]["Event"];
 type GetWebsetResponse = components["schemas"]["GetWebsetResponse"];
 type ListEventsResponse = components["schemas"]["ListEventsResponse"];
+type ListStreamRunsResponse = components["schemas"]["ListStreamRunsResponse"];
+type ListStreamsResponse = components["schemas"]["ListStreamsResponse"];
 type ListWebhookAttemptsResponse = components["schemas"]["ListWebhookAttemptsResponse"];
 type ListWebhooksResponse = components["schemas"]["ListWebhooksResponse"];
 type ListWebsetItemResponse = components["schemas"]["ListWebsetItemResponse"];
 type ListWebsetsResponse = components["schemas"]["ListWebsetsResponse"];
+type Stream = components["schemas"]["Stream"];
+type StreamRun = components["schemas"]["StreamRun"];
+type UpdateStream = components["schemas"]["UpdateStream"];
 type UpdateWebhookParameters = components["schemas"]["UpdateWebhookParameters"];
 type UpdateWebsetRequest = components["schemas"]["UpdateWebsetRequest"];
 type Webhook = components["schemas"]["Webhook"];
@@ -938,9 +1150,6 @@ declare enum CreateEnrichmentParametersFormat {
     email = "email",
     phone = "phone"
 }
-declare enum CreateWebsetSearchParametersBehaviour {
-    override = "override"
-}
 declare enum EventType {
     webset_created = "webset.created",
     webset_deleted = "webset.deleted",
@@ -955,6 +1164,30 @@ declare enum EventType {
     webset_item_created = "webset.item.created",
     webset_item_enriched = "webset.item.enriched"
 }
+declare enum StreamObject {
+    stream = "stream"
+}
+declare enum StreamStatus {
+    open = "open",
+    closed = "closed"
+}
+declare enum StreamRunObject {
+    stream_run = "stream_run"
+}
+declare enum StreamRunStatus {
+    created = "created",
+    running = "running",
+    completed = "completed",
+    canceled = "canceled"
+}
+declare enum StreamRunType {
+    search = "search",
+    refresh = "refresh"
+}
+declare enum UpdateStreamStatus {
+    open = "open",
+    closed = "closed"
+}
 declare enum WebhookStatus {
     active = "active",
     inactive = "inactive"
@@ -978,23 +1211,28 @@ declare enum WebsetEnrichmentFormat {
     phone = "phone"
 }
 declare enum WebsetItemSource {
-    search = "search"
+    search = "search",
+    import = "import"
 }
 declare enum WebsetItemEvaluationSatisfied {
     yes = "yes",
     no = "no",
     unclear = "unclear"
 }
-declare enum WebsetSearchCanceledReason {
-    webset_deleted = "webset_deleted",
-    webset_canceled = "webset_canceled"
-}
 declare enum WebsetSearchStatus {
     created = "created",
     running = "running",
     completed = "completed",
     canceled = "canceled"
 }
+declare enum WebsetSearchBehavior {
+    override = "override",
+    append = "append"
+}
+declare enum WebsetSearchCanceledReason {
+    webset_deleted = "webset_deleted",
+    webset_canceled = "webset_canceled"
+}
 
 /**
  * Client for managing Webset Enrichments
@@ -1150,6 +1388,80 @@ declare class WebsetSearchesClient extends WebsetsBaseClient {
     cancel(websetId: string, id: string): Promise<WebsetSearch>;
 }
 
+/**
+ * Client for managing Webset Streams
+ */
+
+/**
+ * Options for listing streams
+ */
+interface ListStreamsOptions extends PaginationParams {
+    /**
+     * The id of the Webset to list streams for
+     */
+    websetId?: string;
+}
+/**
+ * Client for managing Stream Runs
+ */
+declare class WebsetStreamRunsClient extends WebsetsBaseClient {
+    /**
+     * List all runs for a Stream
+     * @param streamId The ID of the Stream
+     * @param options Pagination options
+     * @returns The list of Stream runs
+     */
+    list(streamId: string, options?: PaginationParams): Promise<ListStreamRunsResponse>;
+    /**
+     * Get a specific Stream run
+     * @param streamId The ID of the Stream
+     * @param runId The ID of the Stream run
+     * @returns The Stream run
+     */
+    get(streamId: string, runId: string): Promise<StreamRun>;
+}
+/**
+ * Client for managing Webset Streams
+ */
+declare class WebsetStreamsClient extends WebsetsBaseClient {
+    /**
+     * Client for managing Stream Runs
+     */
+    runs: WebsetStreamRunsClient;
+    constructor(client: Exa);
+    /**
+     * Create a Stream
+     * @param params The stream parameters
+     * @returns The created Stream
+     */
+    create(params: CreateStreamParameters): Promise<Stream>;
+    /**
+     * Get a Stream by ID
+     * @param id The ID of the Stream
+     * @returns The Stream
+     */
+    get(id: string): Promise<Stream>;
+    /**
+     * List all Streams
+     * @param options Pagination and filtering options
+     * @returns The list of Streams
+     */
+    list(options?: ListStreamsOptions): Promise<ListStreamsResponse>;
+    /**
+     * Update a Stream
+     * @param id The ID of the Stream
+     * @param params The stream update parameters (status, metadata)
+     * @returns The updated Stream
+     */
+    update(id: string, params: UpdateStream): Promise<Stream>;
+    /**
+     * Delete a Stream
+     * @param id The ID of the Stream
+     * @returns The deleted Stream
+     */
+    delete(id: string): Promise<Stream>;
+}
+
 /**
  * Client for managing Webset Webhooks
  */
@@ -1267,6 +1579,10 @@ declare class WebsetsClient extends WebsetsBaseClient {
      * Client for managing Webset Enrichments
      */
     enrichments: WebsetEnrichmentsClient;
+    /**
+     * Client for managing Webset Streams
+     */
+    streams: WebsetStreamsClient;
     /**
      * Client for managing Webset Webhooks
      */
@@ -1340,33 +1656,6 @@ declare class WebsetsClient extends WebsetsBaseClient {
     } | number): Promise<Webset>;
 }
 
-/**
- * Enum representing the status of a research task.
- */
-declare enum ResearchStatus {
-    /** The research request has finished successfully. */
-    completed = "completed",
-    /** The research request failed. */
-    failed = "failed"
-}
-/**
- * Response object returned from the research API.
- */
-type ResearchTaskResponse = {
-    /** Unique identifier for the task. */
-    id: string;
-    /** Current status (may include future enum values served by the API). */
-    status: ResearchStatus | string;
-    /** Structured output that follows the user-provided schema (null while running). */
-    output: Record<string, any> | null;
-    /**
-     * Citations collected while deriving each top-level field in `output`.
-     * The key is the field name, the value is the list of `SearchResult`s that
-     * were used to compute that field.
-     */
-    citations: Record<string, SearchResult<{}>[]>;
-};
-
 type QueryParams = Record<string, string | number | boolean | string[] | undefined>;
 interface RequestBody {
     [key: string]: unknown;
@@ -1398,7 +1687,7 @@ declare class ResearchBaseClient {
 declare class ResearchClient extends ResearchBaseClient {
     constructor(client: Exa);
     /**
-     * Create and run a research task (blocking call).
+     * Create a research task.
      *
      * Both parameters are required and have fixed shapes:
      * 1. `input`
@@ -1417,16 +1706,53 @@ declare class ResearchClient extends ResearchBaseClient {
         instructions: string;
     }, output: {
         schema: JSONSchema;
-    }): Promise<ResearchTaskResponse>;
+    }): Promise<{
+        id: string;
+    }>;
     /**
      * Retrieve a research task by ID.
-     *
-     * Not yet implemented server-side. Calling this will throw until the API is
-     * available.
      */
-    getTask(): Promise<ResearchTaskResponse>;
+    getTask(id: string): Promise<ResearchTask>;
+    /**
+     * Poll a research task until completion or failure.
+     * Polls every 1 second with a maximum timeout of 10 minutes.
+     */
+    pollTask(id: string): Promise<ResearchTask>;
 }
 
+/**
+ * Enum representing the status of a research task.
+ */
+declare enum ResearchStatus {
+    /** The research task is still in progress. */
+    in_progress = "in_progress",
+    /** The research request has finished successfully. */
+    completed = "completed",
+    /** The research task request failed. */
+    failed = "failed"
+}
+/**
+ * Response object returned from the research API.
+ */
+type ResearchTask = {
+    /** Unique identifier for the task. */
+    id: string;
+    /** Current status. */
+    status: ResearchStatus;
+    /** The original instructions provided along with the task. */
+    instructions: string;
+    /** The original schema defining the task */
+    schema: Record<string, any>;
+    /** Structured output that follows the user-provided schema (null while running or if failed). */
+    data: Record<string, any> | null;
+    /**
+     * Citations collected while deriving each top-level field in `output`.
+     * The key is the field name, the value is the list of `SearchResult`s that
+     * were used to compute that field.
+     */
+    citations: Record<string, SearchResult<{}>[]>;
+};
+
 /**
  * HTTP status codes
  */
@@ -1904,4 +2230,4 @@ declare class Exa {
     private parseSSEStream;
 }
 
-export { type AnswerOptions, type AnswerResponse, type AnswerStreamChunk, type AnswerStreamResponse, type BaseSearchOptions, type ContentsOptions, type ContentsResultComponent, type CostDollars, type CostDollarsContents, type CostDollarsSeearch, type CreateEnrichmentParameters, CreateEnrichmentParametersFormat, type CreateWebhookParameters, type CreateWebsetParameters, type CreateWebsetSearchParameters, CreateWebsetSearchParametersBehaviour, type Default, type EnrichmentResult, type Event, EventType, Exa, ExaError, type ExtrasOptions, type ExtrasResponse, type FindSimilarOptions, type GetWebsetResponse, type HighlightsContentsOptions, type HighlightsResponse, HttpStatusCode, type JSONSchema, type ListEventsResponse, type ListWebhooksOptions, type ListWebhooksResponse, type ListWebsetItemResponse, type ListWebsetsOptions, type ListWebsetsResponse, type LivecrawlOptions, type RegularSearchOptions, ResearchClient, ResearchStatus, type ResearchTaskResponse, type SearchResponse, type SearchResult, type SubpagesResponse, type SummaryContentsOptions, type SummaryResponse, type TextContentsOptions, type TextResponse, type UpdateWebhookParameters, type UpdateWebsetRequest, type Webhook, WebhookStatus, type Webset, type WebsetEnrichment, WebsetEnrichmentFormat, WebsetEnrichmentStatus, WebsetEnrichmentsClient, type WebsetItem, WebsetItemEvaluationSatisfied, WebsetItemSource, WebsetItemsClient, type WebsetSearch, WebsetSearchCanceledReason, WebsetSearchStatus, WebsetSearchesClient, WebsetStatus, WebsetWebhooksClient, WebsetsClient, Exa as default };
+export { type AnswerOptions, type AnswerResponse, type AnswerStreamChunk, type AnswerStreamResponse, type BaseSearchOptions, type ContentsOptions, type ContentsResultComponent, type CostDollars, type CostDollarsContents, type CostDollarsSeearch, type CreateEnrichmentParameters, CreateEnrichmentParametersFormat, type CreateStreamParameters, type CreateWebhookParameters, type CreateWebsetParameters, type CreateWebsetSearchParameters, type Default, type EnrichmentResult, type Event, EventType, Exa, ExaError, type ExtrasOptions, type ExtrasResponse, type FindSimilarOptions, type GetWebsetResponse, type HighlightsContentsOptions, type HighlightsResponse, HttpStatusCode, type JSONSchema, type ListEventsResponse, type ListStreamRunsResponse, type ListStreamsOptions, type ListStreamsResponse, type ListWebhooksOptions, type ListWebhooksResponse, type ListWebsetItemResponse, type ListWebsetsOptions, type ListWebsetsResponse, type LivecrawlOptions, type RegularSearchOptions, ResearchClient, ResearchStatus, type ResearchTask, type SearchResponse, type SearchResult, type Stream, type StreamRun, type SubpagesResponse, type SummaryContentsOptions, type SummaryResponse, type TextContentsOptions, type TextResponse, type UpdateStream, UpdateStreamStatus, type UpdateWebhookParameters, type UpdateWebsetRequest, type Webhook, WebhookStatus, type Webset, type WebsetEnrichment, WebsetEnrichmentFormat, WebsetEnrichmentStatus, WebsetEnrichmentsClient, type WebsetItem, WebsetItemEvaluationSatisfied, WebsetItemSource, WebsetItemsClient, type WebsetSearch, WebsetSearchBehavior, WebsetSearchCanceledReason, WebsetSearchStatus, WebsetSearchesClient, WebsetStatus, WebsetStreamsClient, WebsetWebhooksClient, WebsetsClient, Exa as default };