@llamaindex/llama-cloud 1.7.0 → 2.0.0

package/src/client.ts

@@ -25,8 +25,6 @@ import {
   type PaginatedCursorPostParams,
   PaginatedCursorPostResponse,
   PaginatedCursorResponse,
-  type PaginatedExtractRunsParams,
-  PaginatedExtractRunsResponse,
   type PaginatedJobsHistoryParams,
   PaginatedJobsHistoryResponse,
   type PaginatedPipelineFilesParams,
@@ -37,6 +35,19 @@ import {
 import * as Uploads from './core/uploads';
 import * as API from './resources/index';
 import { APIPromise } from './core/api-promise';
+import {
+  Classify,
+  ClassifyConfiguration,
+  ClassifyCreateParams,
+  ClassifyCreateRequest,
+  ClassifyCreateResponse,
+  ClassifyGetParams,
+  ClassifyGetResponse,
+  ClassifyListParams,
+  ClassifyListResponse,
+  ClassifyListResponsesPaginatedCursor,
+  ClassifyResult,
+} from './resources/classify';
 import {
   DataSink,
   DataSinkCreateParams,
@@ -54,6 +65,28 @@ import {
   DataSourceUpdateParams,
   DataSources,
 } from './resources/data-sources';
+import {
+  Extract,
+  ExtractConfiguration,
+  ExtractCreateParams,
+  ExtractDeleteParams,
+  ExtractDeleteResponse,
+  ExtractGenerateSchemaParams,
+  ExtractGenerateSchemaResponse,
+  ExtractGetParams,
+  ExtractJobMetadata,
+  ExtractJobUsage,
+  ExtractListParams,
+  ExtractV2Job,
+  ExtractV2JobCreate,
+  ExtractV2JobQueryResponse,
+  ExtractV2JobsPaginatedCursor,
+  ExtractV2SchemaGenerateRequest,
+  ExtractV2SchemaValidateRequest,
+  ExtractV2SchemaValidateResponse,
+  ExtractValidateSchemaParams,
+  ExtractedFieldMetadata,
+} from './resources/extract';
 import {
   File,
   FileCreate,
@@ -104,7 +137,6 @@ import {
 } from './resources/projects';
 import { Beta } from './resources/beta/beta';
 import { Classifier } from './resources/classifier/classifier';
-import { Extraction, ExtractionRunParams } from './resources/extraction/extraction';
 import {
   AdvancedModeTransformConfig,
   AutoTransformConfig,
@@ -178,7 +210,7 @@ import { isEmptyObj } from './internal/utils/values';
 
 export interface ClientOptions {
   /**
-   * Defaults to process.env['LLAMA_CLOUD_API_KEY'].
+   * Defaults to process.env['LLAMA_CLOUD_API_KEY'] or process.env['LLAMA_PARSE_API_KEY'].
    */
   apiKey?: string | undefined;
 
@@ -272,7 +304,7 @@ export class LlamaCloud {
   /**
    * API Client for interfacing with the Llama Cloud API.
    *
-   * @param {string | undefined} [opts.apiKey=process.env['LLAMA_CLOUD_API_KEY'] ?? undefined]
+   * @param {string | undefined} [opts.apiKey=process.env['LLAMA_CLOUD_API_KEY'] ?? process.env['LLAMA_PARSE_API_KEY'] ?? undefined]
    * @param {string} [opts.baseURL=process.env['LLAMA_CLOUD_BASE_URL'] ?? https://api.cloud.llamaindex.ai] - Override the default base URL for the API.
    * @param {number} [opts.timeout=1 minute] - The maximum amount of time (in milliseconds) the client will wait for a response before timing out.
    * @param {MergedRequestInit} [opts.fetchOptions] - Additional `RequestInit` options to be passed to `fetch` calls.
@@ -283,12 +315,12 @@ export class LlamaCloud {
    */
   constructor({
     baseURL = readEnv('LLAMA_CLOUD_BASE_URL'),
-    apiKey = readEnv('LLAMA_CLOUD_API_KEY'),
+    apiKey = readEnv('LLAMA_CLOUD_API_KEY') ?? readEnv('LLAMA_PARSE_API_KEY'),
     ...opts
   }: ClientOptions = {}) {
     if (apiKey === undefined && !isRunningInBrowser()) {
       throw new Errors.LlamaCloudError(
-        "The LLAMA_CLOUD_API_KEY environment variable is missing or empty; either provide it, or instantiate the LlamaCloud client with an apiKey option, like new LlamaCloud({ apiKey: 'My API Key' }).",
+        "The LLAMA_CLOUD_API_KEY or LLAMA_PARSE_API_KEY environment variable is missing or empty; either provide it, or instantiate the LlamaCloud client with an apiKey option, like new LlamaCloud({ apiKey: 'My API Key' }).",
       );
     }
 
@@ -313,7 +345,7 @@ export class LlamaCloud {
       parseLogLevel(readEnv('LLAMA_CLOUD_LOG'), "process.env['LLAMA_CLOUD_LOG']", this) ??
       defaultLogLevel;
     this.fetchOptions = options.fetchOptions;
-    this.maxRetries = options.maxRetries ?? 2;
+    this.maxRetries = options.maxRetries ?? 5;
     this.fetch = options.fetch ?? Shims.getDefaultFetch();
     this.#encoder = Opts.FallbackEncoder;
 
@@ -396,8 +428,9 @@ export class LlamaCloud {
       : 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)) {
@@ -730,9 +763,9 @@ export class LlamaCloud {
       }
     }
 
-    // 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);
     }
@@ -892,8 +925,9 @@ export class LlamaCloud {
 
   files: API.Files = new API.Files(this);
   parsing: API.Parsing = new API.Parsing(this);
-  extraction: API.Extraction = new API.Extraction(this);
+  extract: API.Extract = new API.Extract(this);
   classifier: API.Classifier = new API.Classifier(this);
+  classify: API.Classify = new API.Classify(this);
   projects: API.Projects = new API.Projects(this);
   dataSinks: API.DataSinks = new API.DataSinks(this);
   dataSources: API.DataSources = new API.DataSources(this);
@@ -904,8 +938,9 @@ export class LlamaCloud {
 
 LlamaCloud.Files = Files;
 LlamaCloud.Parsing = Parsing;
-LlamaCloud.Extraction = Extraction;
+LlamaCloud.Extract = Extract;
 LlamaCloud.Classifier = Classifier;
+LlamaCloud.Classify = Classify;
 LlamaCloud.Projects = Projects;
 LlamaCloud.DataSinks = DataSinks;
 LlamaCloud.DataSources = DataSources;
@@ -934,12 +969,6 @@ export declare namespace LlamaCloud {
     type PaginatedBatchItemsResponse as PaginatedBatchItemsResponse,
   };
 
-  export import PaginatedExtractRuns = Pagination.PaginatedExtractRuns;
-  export {
-    type PaginatedExtractRunsParams as PaginatedExtractRunsParams,
-    type PaginatedExtractRunsResponse as PaginatedExtractRunsResponse,
-  };
-
   export import PaginatedCloudDocuments = Pagination.PaginatedCloudDocuments;
   export {
     type PaginatedCloudDocumentsParams as PaginatedCloudDocumentsParams,
@@ -1007,10 +1036,45 @@ export declare namespace LlamaCloud {
     type ParsingGetParams as ParsingGetParams,
   };
 
-  export { Extraction as Extraction, type ExtractionRunParams as ExtractionRunParams };
+  export {
+    Extract as Extract,
+    type ExtractConfiguration as ExtractConfiguration,
+    type ExtractJobMetadata as ExtractJobMetadata,
+    type ExtractJobUsage as ExtractJobUsage,
+    type ExtractV2Job as ExtractV2Job,
+    type ExtractV2JobCreate as ExtractV2JobCreate,
+    type ExtractV2JobQueryResponse as ExtractV2JobQueryResponse,
+    type ExtractV2SchemaGenerateRequest as ExtractV2SchemaGenerateRequest,
+    type ExtractV2SchemaValidateRequest as ExtractV2SchemaValidateRequest,
+    type ExtractV2SchemaValidateResponse as ExtractV2SchemaValidateResponse,
+    type ExtractedFieldMetadata as ExtractedFieldMetadata,
+    type ExtractDeleteResponse as ExtractDeleteResponse,
+    type ExtractGenerateSchemaResponse as ExtractGenerateSchemaResponse,
+    type ExtractV2JobsPaginatedCursor as ExtractV2JobsPaginatedCursor,
+    type ExtractCreateParams as ExtractCreateParams,
+    type ExtractListParams as ExtractListParams,
+    type ExtractDeleteParams as ExtractDeleteParams,
+    type ExtractGenerateSchemaParams as ExtractGenerateSchemaParams,
+    type ExtractGetParams as ExtractGetParams,
+    type ExtractValidateSchemaParams as ExtractValidateSchemaParams,
+  };
 
   export { Classifier as Classifier };
 
+  export {
+    Classify as Classify,
+    type ClassifyConfiguration as ClassifyConfiguration,
+    type ClassifyCreateRequest as ClassifyCreateRequest,
+    type ClassifyResult as ClassifyResult,
+    type ClassifyCreateResponse as ClassifyCreateResponse,
+    type ClassifyListResponse as ClassifyListResponse,
+    type ClassifyGetResponse as ClassifyGetResponse,
+    type ClassifyListResponsesPaginatedCursor as ClassifyListResponsesPaginatedCursor,
+    type ClassifyCreateParams as ClassifyCreateParams,
+    type ClassifyListParams as ClassifyListParams,
+    type ClassifyGetParams as ClassifyGetParams,
+  };
+
   export {
     Projects as Projects,
     type Project as Project,

package/src/core/pagination.ts

@@ -315,77 +315,6 @@ export class PaginatedBatchItems<Item>
   }
 }
 
-export interface PaginatedExtractRunsResponse<Item> {
-  items: Array<Item>;
-
-  total: number;
-
-  skip: number;
-}
-
-export interface PaginatedExtractRunsParams {
-  /**
-   * Number of extraction runs to skip
-   */
-  skip?: number;
-
-  /**
-   * Maximum number of extraction runs to return
-   */
-  limit?: number;
-}
-
-export class PaginatedExtractRuns<Item>
-  extends AbstractPage<Item>
-  implements PaginatedExtractRunsResponse<Item>
-{
-  items: Array<Item>;
-
-  total: number;
-
-  skip: number;
-
-  constructor(
-    client: LlamaCloud,
-    response: Response,
-    body: PaginatedExtractRunsResponse<Item>,
-    options: FinalRequestOptions,
-  ) {
-    super(client, response, body, options);
-
-    this.items = body.items || [];
-    this.total = body.total || 0;
-    this.skip = body.skip || 0;
-  }
-
-  getPaginatedItems(): Item[] {
-    return this.items ?? [];
-  }
-
-  nextPageRequestOptions(): PageRequestOptions | null {
-    const offset = this.skip ?? 0;
-    const length = this.getPaginatedItems().length;
-    const currentCount = offset + length;
-
-    const totalCount = this.total;
-    if (!totalCount) {
-      return null;
-    }
-
-    if (currentCount < totalCount) {
-      return {
-        ...this.options,
-        query: {
-          ...maybeObj(this.options.query),
-          skip: currentCount,
-        },
-      };
-    }
-
-    return null;
-  }
-}
-
 export interface PaginatedCloudDocumentsResponse<Item> {
   documents: Array<Item>;
 

package/src/resources/beta/batch/batch.ts

@@ -3,7 +3,6 @@
 import { APIResource } from '../../../core/resource';
 import * as ParsingAPI from '../../parsing';
 import * as JobsAPI from '../../classifier/jobs';
-import * as ExtractionJobsAPI from '../../extraction/jobs';
 import * as JobItemsAPI from './job-items';
 import {
   JobItemGetProcessingResultsParams,
@@ -23,11 +22,14 @@ export class Batch extends APIResource {
   jobItems: JobItemsAPI.JobItems = new JobItemsAPI.JobItems(this._client);
 
   /**
-   * Create a new batch processing job for a directory.
+   * Create a batch processing job.
    *
-   * Processes all files in the specified directory according to the job
-   * configuration. The job runs asynchronously and you can monitor progress using
-   * the job status endpoint.
+   * Processes files from a directory or a specific list of item IDs. Supports batch
+   * parsing and classification operations.
+   *
+   * Provide either `directory_id` to process all files in a directory, or `item_ids`
+   * for specific items. The job runs asynchronously — poll `GET /batch/{job_id}` for
+   * progress.
    */
   create(params: BatchCreateParams, options?: RequestOptions): APIPromise<BatchCreateResponse> {
     const { organization_id, project_id, 'temporal-namespace': temporalNamespace, ...body } = params;
@@ -43,11 +45,10 @@ export class Batch extends APIResource {
   }
 
   /**
-   * List all batch processing jobs for a project with optional filtering.
+   * List batch processing jobs with optional filtering.
    *
-   * Returns a paginated list of batch jobs with filters for directory, job type, and
-   * status. Useful for viewing job history, monitoring progress, and finding
-   * specific jobs.
+   * Filter by `directory_id`, `job_type`, or `status`. Results are paginated with
+   * configurable `limit` and `offset`.
    */
   list(
     query: BatchListParams | null | undefined = {},
@@ -62,8 +63,8 @@ export class Batch extends APIResource {
   /**
    * Cancel a running batch processing job.
    *
-   * Stops processing and marks all pending items as cancelled. Items currently being
-   * processed may complete depending on their state.
+   * Stops processing and marks pending items as cancelled. Items currently being
+   * processed may still complete.
    */
   cancel(
     jobID: string,
@@ -85,7 +86,8 @@ export class Batch extends APIResource {
   /**
    * Get detailed status of a batch processing job.
    *
-   * Returns current progress, file counts, and estimated completion time.
+   * Returns current progress percentage, file counts (total, processed, failed,
+   * skipped), and timestamps.
    */
   getStatus(
     jobID: string,
@@ -108,7 +110,7 @@ export interface BatchCreateResponse {
   id: string;
 
   /**
-   * Type of processing operation
+   * Type of processing operation (parse or classify)
    */
   job_type: 'parse' | 'extract' | 'classify';
 
@@ -118,7 +120,7 @@ export interface BatchCreateResponse {
   project_id: string;
 
   /**
-   * Current status of the job
+   * Current job status
    */
   status: 'pending' | 'running' | 'dispatched' | 'completed' | 'failed' | 'cancelled';
 
@@ -180,7 +182,7 @@ export interface BatchCreateResponse {
   updated_at?: string | null;
 
   /**
-   * Temporal workflow ID for this batch job
+   * Async job tracking ID
    */
   workflow_id?: string | null;
 }
@@ -195,7 +197,7 @@ export interface BatchListResponse {
   id: string;
 
   /**
-   * Type of processing operation
+   * Type of processing operation (parse or classify)
    */
   job_type: 'parse' | 'extract' | 'classify';
 
@@ -205,7 +207,7 @@ export interface BatchListResponse {
   project_id: string;
 
   /**
-   * Current status of the job
+   * Current job status
    */
   status: 'pending' | 'running' | 'dispatched' | 'completed' | 'failed' | 'cancelled';
 
@@ -267,7 +269,7 @@ export interface BatchListResponse {
   updated_at?: string | null;
 
   /**
-   * Temporal workflow ID for this batch job
+   * Async job tracking ID
    */
   workflow_id?: string | null;
 }
@@ -323,7 +325,7 @@ export namespace BatchGetStatusResponse {
     id: string;
 
     /**
-     * Type of processing operation
+     * Type of processing operation (parse or classify)
      */
     job_type: 'parse' | 'extract' | 'classify';
 
@@ -333,7 +335,7 @@ export namespace BatchGetStatusResponse {
     project_id: string;
 
     /**
-     * Current status of the job
+     * Current job status
      */
     status: 'pending' | 'running' | 'dispatched' | 'completed' | 'failed' | 'cancelled';
 
@@ -395,7 +397,7 @@ export namespace BatchGetStatusResponse {
     updated_at?: string | null;
 
     /**
-     * Temporal workflow ID for this batch job
+     * Async job tracking ID
      */
     workflow_id?: string | null;
   }
@@ -403,8 +405,7 @@ export namespace BatchGetStatusResponse {
 
 export interface BatchCreateParams {
   /**
-   * Body param: Job configuration for batch processing. Can be
-   * BatchParseJobRecordCreate or ClassifyJob.
+   * Body param: Job configuration — either a parse or classify config
    */
   job_config: BatchCreateParams.BatchParseJobRecordCreate | JobsAPI.ClassifyJob;
 
@@ -419,9 +420,8 @@ export interface BatchCreateParams {
   project_id?: string | null;
 
   /**
-   * Body param: Maximum number of files to process before calling continue-as-new.
-   * If None, continue-as-new is called after every batch. (only used in directory
-   * mode)
+   * Body param: Maximum files to process per execution cycle in directory mode.
+   * Defaults to page_size.
    */
   continue_as_new_threshold?: number | null;
 
@@ -437,8 +437,7 @@ export interface BatchCreateParams {
   item_ids?: Array<string> | null;
 
   /**
-   * Body param: Number of files to fetch per batch from the directory (only used in
-   * directory mode)
+   * Body param: Number of files to process per batch when using directory mode
    */
   page_size?: number;
 
@@ -813,12 +812,58 @@ export namespace BatchCreateParams {
       version?: string | null;
 
       /**
-       * The outbound webhook configurations
+       * Outbound webhook endpoints to notify on job status changes
        */
-      webhook_configurations?: Array<ExtractionJobsAPI.WebhookConfiguration> | null;
+      webhook_configurations?: Array<Parameters.WebhookConfiguration> | null;
 
       webhook_url?: string | null;
     }
+
+    export namespace Parameters {
+      /**
+       * Configuration for a single outbound webhook endpoint.
+       */
+      export interface WebhookConfiguration {
+        /**
+         * Events to subscribe to (e.g. 'parse.success', 'extract.error'). If null, all
+         * events are delivered.
+         */
+        webhook_events?: Array<
+          | 'extract.pending'
+          | 'extract.success'
+          | 'extract.error'
+          | 'extract.partial_success'
+          | 'extract.cancelled'
+          | 'parse.pending'
+          | 'parse.running'
+          | 'parse.success'
+          | 'parse.error'
+          | 'parse.partial_success'
+          | 'parse.cancelled'
+          | 'classify.pending'
+          | 'classify.success'
+          | 'classify.error'
+          | 'classify.partial_success'
+          | 'classify.cancelled'
+          | 'unmapped_event'
+        > | null;
+
+        /**
+         * Custom HTTP headers sent with each webhook request (e.g. auth tokens)
+         */
+        webhook_headers?: { [key: string]: string } | null;
+
+        /**
+         * Response format sent to the webhook: 'string' (default) or 'json'
+         */
+        webhook_output_format?: string | null;
+
+        /**
+         * URL to receive webhook POST notifications
+         */
+        webhook_url?: string | null;
+      }
+    }
   }
 }
 

package/src/resources/beta/batch/job-items.ts

@@ -3,7 +3,6 @@
 import { APIResource } from '../../../core/resource';
 import * as ParsingAPI from '../../parsing';
 import * as JobsAPI from '../../classifier/jobs';
-import * as ExtractionJobsAPI from '../../extraction/jobs';
 import { APIPromise } from '../../../core/api-promise';
 import { PagePromise, PaginatedBatchItems, type PaginatedBatchItemsParams } from '../../../core/pagination';
 import { RequestOptions } from '../../../internal/request-options';
@@ -13,9 +12,8 @@ export class JobItems extends APIResource {
   /**
    * List items in a batch job with optional status filtering.
    *
-   * Useful for finding failed items, viewing completed items, or debugging issues.
-   * Results are paginated for performance with configurable limit and offset
-   * parameters.
+   * Useful for finding failed items, viewing completed items, or debugging
+   * processing issues.
    */
   list(
     jobID: string,
@@ -30,12 +28,11 @@ export class JobItems extends APIResource {
   }
 
   /**
-   * Get all processing results for a specific item (lineage query).
+   * Get all processing results for a specific item.
    *
-   * Shows complete processing history including what operations have been performed,
-   * with what parameters, and where outputs are stored. Useful for understanding
-   * what processing has already been done to avoid redundant work. Optionally filter
-   * by job type to see only specific processing operations.
+   * Returns the complete processing history for an item including what operations
+   * were performed, parameters used, and where outputs are stored. Optionally filter
+   * by `job_type`.
    */
   getProcessingResults(
     itemID: string,
@@ -144,12 +141,12 @@ export namespace JobItemGetProcessingResultsResponse {
     job_type: 'parse' | 'extract' | 'classify';
 
     /**
-     * S3 location of processing output
+     * Location of the processing output
      */
     output_s3_path: string;
 
     /**
-     * Hash of parameters for deduplication
+     * Content hash of the job configuration for dedup
      */
     parameters_hash: string;
 
@@ -537,12 +534,58 @@ export namespace JobItemGetProcessingResultsResponse {
         version?: string | null;
 
         /**
-         * The outbound webhook configurations
+         * Outbound webhook endpoints to notify on job status changes
          */
-        webhook_configurations?: Array<ExtractionJobsAPI.WebhookConfiguration> | null;
+        webhook_configurations?: Array<Parameters.WebhookConfiguration> | null;
 
         webhook_url?: string | null;
       }
+
+      export namespace Parameters {
+        /**
+         * Configuration for a single outbound webhook endpoint.
+         */
+        export interface WebhookConfiguration {
+          /**
+           * Events to subscribe to (e.g. 'parse.success', 'extract.error'). If null, all
+           * events are delivered.
+           */
+          webhook_events?: Array<
+            | 'extract.pending'
+            | 'extract.success'
+            | 'extract.error'
+            | 'extract.partial_success'
+            | 'extract.cancelled'
+            | 'parse.pending'
+            | 'parse.running'
+            | 'parse.success'
+            | 'parse.error'
+            | 'parse.partial_success'
+            | 'parse.cancelled'
+            | 'classify.pending'
+            | 'classify.success'
+            | 'classify.error'
+            | 'classify.partial_success'
+            | 'classify.cancelled'
+            | 'unmapped_event'
+          > | null;
+
+          /**
+           * Custom HTTP headers sent with each webhook request (e.g. auth tokens)
+           */
+          webhook_headers?: { [key: string]: string } | null;
+
+          /**
+           * Response format sent to the webhook: 'string' (default) or 'json'
+           */
+          webhook_output_format?: string | null;
+
+          /**
+           * URL to receive webhook POST notifications
+           */
+          webhook_url?: string | null;
+        }
+      }
     }
   }
 }

package/src/resources/beta/sheets.ts

@@ -417,11 +417,31 @@ export interface SheetCreateParams {
 }
 
 export interface SheetListParams extends PaginatedCursorParams {
+  /**
+   * Include jobs created at or after this timestamp (inclusive)
+   */
+  created_at_on_or_after?: string | null;
+
+  /**
+   * Include jobs created at or before this timestamp (inclusive)
+   */
+  created_at_on_or_before?: string | null;
+
   include_results?: boolean;
 
+  /**
+   * Filter by specific job IDs
+   */
+  job_ids?: Array<string> | null;
+
   organization_id?: string | null;
 
   project_id?: string | null;
+
+  /**
+   * Filter by job status
+   */
+  status?: ParsingAPI.StatusEnum | null;
 }
 
 export interface SheetDeleteJobParams {