diff --git a/src/apify_client.ts b/src/apify_client.ts index 93c6f88a..d0efc4b7 100644 --- a/src/apify_client.ts +++ b/src/apify_client.ts @@ -36,8 +36,25 @@ import { Statistics } from './statistics'; const DEFAULT_TIMEOUT_SECS = 360; /** - * ApifyClient is the official library to access [Apify API](https://docs.apify.com/api/v2) from your - * JavaScript applications. It runs both in Node.js and browser. + * The official JavaScript client for the Apify API. + * + * Provides programmatic access to all Apify platform resources including Actors, runs, datasets, + * key-value stores, request queues, and more. Works in both Node.js and browser environments. + * + * @example + * ```javascript + * import { ApifyClient } from 'apify-client'; + * + * const client = new ApifyClient({ token: 'my-token' }); + * + * // Start an Actor and wait for it to finish + * const run = await client.actor('my-actor-id').call(); + * + * // Fetch dataset items + * const { items } = await client.dataset(run.defaultDatasetId).listItems(); + * ``` + * + * @see https://docs.apify.com/api/v2 */ export class ApifyClient { baseUrl: string; @@ -108,14 +125,32 @@ export class ApifyClient { } /** - * https://docs.apify.com/api/v2#/reference/actors/actor-collection + * Returns a client for managing Actors in your account. + * + * Provides access to the Actor collection, allowing you to list, create, and search for Actors. + * + * @returns A client for the Actors collection + * @see https://docs.apify.com/api/v2/acts-get */ actors(): ActorCollectionClient { return new ActorCollectionClient(this._options()); } /** - * https://docs.apify.com/api/v2#/reference/actors/actor-object + * Returns a client for a specific Actor. + * + * Use this to get, update, delete, start, or call an Actor, as well as manage its builds, + * runs, versions, and webhooks. + * + * @param id - Actor ID or username/name + * @returns A client for the specific Actor + * @see https://docs.apify.com/api/v2/act-get + * + * @example + * ```javascript + * // Call an Actor and wait for it to finish + * const run = await client.actor('apify/web-scraper').call({ url: 'https://example.com' }); + * ``` */ actor(id: string): ActorClient { ow(id, ow.string.nonEmpty); @@ -127,14 +162,25 @@ export class ApifyClient { } /** - * https://docs.apify.com/api/v2#/reference/actor-builds/build-collection + * Returns a client for managing Actor builds in your account. + * + * Lists all builds across all of your Actors. + * + * @returns A client for Actor builds collection + * @see https://docs.apify.com/api/v2/actor-builds-get */ builds(): BuildCollectionClient { return new BuildCollectionClient(this._options()); } /** - * https://docs.apify.com/api/v2#/reference/actor-builds/build-object + * Returns a client for a specific Actor build. + * + * Use this to get details about a build, wait for it to finish, or access its logs. + * + * @param id - Build ID + * @returns A client for the specified build + * @see https://docs.apify.com/api/v2/actor-build-get */ build(id: string): BuildClient { ow(id, ow.string.nonEmpty); @@ -146,14 +192,39 @@ export class ApifyClient { } /** - * https://docs.apify.com/api/v2#/reference/datasets/dataset-collection + * Returns a client for managing datasets in your account. + * + * Datasets store structured data results from Actor runs. Use this to list or create datasets. + * + * @returns A client for the Datasets collection + * @see https://docs.apify.com/api/v2/datasets-get */ datasets(): DatasetCollectionClient { return new DatasetCollectionClient(this._options()); } /** - * https://docs.apify.com/api/v2#/reference/datasets/dataset + * Returns a client for a specific dataset. + * + * Use this to read, write, and manage items in the dataset. Datasets contain structured + * data stored as individual items (records). + * + * @template Data - Type of items stored in the dataset + * @param id - Dataset ID or name + * @returns A client for the specific Dataset + * @see https://docs.apify.com/api/v2/dataset-get + * + * @example + * ```javascript + * // Push items to a dataset + * await client.dataset('my-dataset').pushItems([ + * { url: 'https://example.com', title: 'Example' }, + * { url: 'https://test.com', title: 'Test' } + * ]); + * + * // Retrieve items + * const { items } = await client.dataset('my-dataset').listItems(); + * ``` */ dataset = Record>( id: string, @@ -167,14 +238,35 @@ export class ApifyClient { } /** - * https://docs.apify.com/api/v2#/reference/key-value-stores/store-collection + * Returns a client for managing key-value stores in your account. + * + * Key-value stores are used to store arbitrary data records or files. + * + * @returns A client for the Key-value stores collection + * @see https://docs.apify.com/api/v2/key-value-stores-get */ keyValueStores(): KeyValueStoreCollectionClient { return new KeyValueStoreCollectionClient(this._options()); } /** - * https://docs.apify.com/api/v2#/reference/key-value-stores/store-object + * Returns a client for a specific key-value store. + * + * Use this to read, write, and delete records in the store. Key-value stores can hold + * any type of data including text, JSON, images, and other files. + * + * @param id - Key-value store ID or name + * @returns A client for the specific key-value store + * @see https://docs.apify.com/api/v2/key-value-store-get + * + * @example + * ```javascript + * // Save a record + * await client.keyValueStore('my-store').setRecord({ key: 'OUTPUT', value: { foo: 'bar' } }); + * + * // Get a record + * const record = await client.keyValueStore('my-store').getRecord('OUTPUT'); + * ``` */ keyValueStore(id: string): KeyValueStoreClient { ow(id, ow.string.nonEmpty); @@ -186,7 +278,11 @@ export class ApifyClient { } /** - * https://docs.apify.com/api/v2#/reference/logs + * Returns a client for accessing logs of an Actor build or run. + * + * @param buildOrRunId - Build ID or run ID + * @returns A client for accessing logs + * @see https://docs.apify.com/api/v2/log-get */ log(buildOrRunId: string): LogClient { ow(buildOrRunId, ow.string.nonEmpty); @@ -198,14 +294,37 @@ export class ApifyClient { } /** - * https://docs.apify.com/api/v2#/reference/request-queues/queue-collection + * Returns a client for managing request queues in your account. + * + * Request queues store URLs to be crawled, along with their metadata. + * + * @returns A client for the Request queues collection + * @see https://docs.apify.com/api/v2/request-queues-get */ requestQueues(): RequestQueueCollectionClient { return new RequestQueueCollectionClient(this._options()); } /** - * https://docs.apify.com/api/v2#/reference/request-queues/queue + * Returns a client for a specific request queue. + * + * Use this to add, retrieve, and manage requests in the queue. Request queues are used + * by web crawlers to manage URLs that need to be visited. + * + * @param id - Request queue ID or name + * @param options - Configuration options for the request queue client + * @returns A client for the specific Request queue + * @see https://docs.apify.com/api/v2/request-queue-get + * + * @example + * ```javascript + * // Add requests to a queue + * const queue = client.requestQueue('my-queue'); + * await queue.addRequest({ url: 'https://example.com', uniqueKey: 'example' }); + * + * // Get and lock the next request + * const { items } = await queue.listAndLockHead({ lockSecs: 60 }); + * ``` */ requestQueue(id: string, options: RequestQueueUserOptions = {}): RequestQueueClient { ow(id, ow.string.nonEmpty); @@ -225,7 +344,12 @@ export class ApifyClient { } /** - * https://docs.apify.com/api/v2#/reference/actor-runs/run-collection + * Returns a client for managing Actor runs in your account. + * + * Lists all runs across all of your Actors. + * + * @returns A client for the run collection + * @see https://docs.apify.com/api/v2/actor-runs-get */ runs(): RunCollectionClient { return new RunCollectionClient({ @@ -235,7 +359,23 @@ export class ApifyClient { } /** - * https://docs.apify.com/api/v2#/reference/actor-runs/run-object-and-its-storages + * Returns a client for a specific Actor run. + * + * Use this to get details about a run, wait for it to finish, abort it, or access its + * dataset, key-value store, and request queue. + * + * @param id - Run ID + * @returns A client for the specified run + * @see https://docs.apify.com/api/v2/actor-run-get + * + * @example + * ```javascript + * // Wait for a run to finish + * const run = await client.run('run-id').waitForFinish(); + * + * // Access run's dataset + * const { items } = await client.run('run-id').dataset().listItems(); + * ``` */ run(id: string): RunClient { ow(id, ow.string.nonEmpty); @@ -247,14 +387,31 @@ export class ApifyClient { } /** - * https://docs.apify.com/api/v2#/reference/actor-tasks/task-collection + * Returns a client for managing Actor tasks in your account. + * + * Tasks are pre-configured Actor runs with stored input that can be executed repeatedly. + * + * @returns A client for the task collection + * @see https://docs.apify.com/api/v2/actor-tasks-get */ tasks(): TaskCollectionClient { return new TaskCollectionClient(this._options()); } /** - * https://docs.apify.com/api/v2#/reference/actor-tasks/task-object + * Returns a client for a specific Actor task. + * + * Use this to get, update, delete, or run a task with pre-configured input. + * + * @param id - Task ID or username/task-name + * @returns A client for the specified task + * @see https://docs.apify.com/api/v2/actor-task-get + * + * @example + * ```javascript + * // Run a task and wait for it to finish + * const run = await client.task('my-task').call(); + * ``` */ task(id: string): TaskClient { ow(id, ow.string.nonEmpty); @@ -266,14 +423,25 @@ export class ApifyClient { } /** - * https://docs.apify.com/api/v2#/reference/schedules/schedules-collection + * Returns a client for managing schedules in your account. + * + * Schedules automatically start Actor or task runs at specified times. + * + * @returns A client for the Schedules collection + * @see https://docs.apify.com/api/v2/schedules-get */ schedules(): ScheduleCollectionClient { return new ScheduleCollectionClient(this._options()); } /** - * https://docs.apify.com/api/v2#/reference/schedules/schedule-object + * Returns a client for a specific schedule. + * + * Use this to get, update, or delete a schedule. + * + * @param id - Schedule ID + * @returns A client for the specific Schedule + * @see https://docs.apify.com/api/v2/schedule-get */ schedule(id: string): ScheduleClient { ow(id, ow.string.nonEmpty); @@ -285,7 +453,13 @@ export class ApifyClient { } /** - * https://docs.apify.com/api/v2#/reference/users + * Returns a client for accessing user data. + * + * By default, returns information about the current user (determined by the API token). + * + * @param id - User ID or username. Defaults to 'me' (current user) + * @returns A client for the user + * @see https://docs.apify.com/api/v2/user-get */ user(id = ME_USER_NAME_PLACEHOLDER): UserClient { ow(id, ow.string.nonEmpty); @@ -297,14 +471,25 @@ export class ApifyClient { } /** - * https://docs.apify.com/api/v2#/reference/webhooks/webhook-collection + * Returns a client for managing webhooks in your account. + * + * Webhooks notify external services when specific events occur (e.g., Actor run finishes). + * + * @returns A client for the Webhooks collection + * @see https://docs.apify.com/api/v2/webhooks-get */ webhooks(): WebhookCollectionClient { return new WebhookCollectionClient(this._options()); } /** - * https://docs.apify.com/api/v2#/reference/webhooks/webhook-object + * Returns a client for a specific webhook. + * + * Use this to get, update, delete, or test a webhook. + * + * @param id - Webhook ID + * @returns A client for the specific webhook + * @see https://docs.apify.com/api/v2/webhook-get */ webhook(id: string): WebhookClient { ow(id, ow.string.nonEmpty); @@ -316,14 +501,23 @@ export class ApifyClient { } /** - * https://docs.apify.com/api/v2#/reference/webhook-dispatches + * Returns a client for viewing webhook dispatches in your account. + * + * Webhook dispatches represent individual invocations of webhooks. + * + * @returns A client for the webhook dispatches collection + * @see https://docs.apify.com/api/v2/webhook-dispatches-get */ webhookDispatches(): WebhookDispatchCollectionClient { return new WebhookDispatchCollectionClient(this._options()); } /** - * https://docs.apify.com/api/v2#/reference/webhook-dispatches/webhook-dispatch-object + * Returns a client for a specific webhook dispatch. + * + * @param id - Webhook dispatch ID + * @returns A client for the specific webhook dispatch + * @see https://docs.apify.com/api/v2/webhook-dispatch-get */ webhookDispatch(id: string): WebhookDispatchClient { ow(id, ow.string.nonEmpty); @@ -335,12 +529,27 @@ export class ApifyClient { } /** - * https://docs.apify.com/api/v2/#/reference/store + * Returns a client for browsing Actors in Apify Store. + * + * Use this to search and retrieve information about public Actors. + * + * @returns A client for the Apify Store + * @see https://docs.apify.com/api/v2/store-actors-get */ store(): StoreCollectionClient { return new StoreCollectionClient(this._options()); } + /** + * Sets a status message for the current Actor run. + * + * This is a convenience method that updates the status message of the run specified by + * the `ACTOR_RUN_ID` environment variable. Only works when called from within an Actor run. + * + * @param message - The status message to set + * @param options - Additional options for the status message + * @throws {Error} If `ACTOR_RUN_ID` environment variable is not set + */ async setStatusMessage(message: string, options?: SetStatusMessageOptions): Promise { const runId = process.env[ACTOR_ENV_VARS.RUN_ID]; if (!runId) { @@ -353,6 +562,9 @@ export class ApifyClient { } } +/** + * Configuration options for ApifyClient. + */ export interface ApifyClientOptions { /** @default https://api.apify.com */ baseUrl?: string; diff --git a/src/resource_clients/actor.ts b/src/resource_clients/actor.ts index 4d73cbb0..bd6d46c8 100644 --- a/src/resource_clients/actor.ts +++ b/src/resource_clients/actor.ts @@ -19,6 +19,26 @@ import { RunCollectionClient } from './run_collection'; import type { WebhookUpdateData } from './webhook'; import { WebhookCollectionClient } from './webhook_collection'; +/** + * Client for managing a specific Actor. + * + * Provides methods to start, call, build, update, and delete an Actor, as well as manage its + * versions, builds, runs, and webhooks. + * + * @example + * ```javascript + * const client = new ApifyClient({ token: 'my-token' }); + * const actorClient = client.actor('my-actor-id'); + * + * // Start an Actor + * const run = await actorClient.start(input, { memory: 256 }); + * + * // Call an Actor and wait for it to finish + * const finishedRun = await actorClient.call({ url: 'https://example.com' }); + * ``` + * + * @see https://docs.apify.com/platform/actors + */ export class ActorClient extends ResourceClient { /** * @hidden @@ -31,14 +51,21 @@ export class ActorClient extends ResourceClient { } /** - * https://docs.apify.com/api/v2#/reference/actors/actor-object/get-actor + * Gets the Actor object from the Apify API. + * + * @returns The Actor object, or `undefined` if it does not exist + * @see https://docs.apify.com/api/v2/act-get */ async get(): Promise { return this._get(); } /** - * https://docs.apify.com/api/v2#/reference/actors/actor-object/update-actor + * Updates the Actor with specified fields. + * + * @param newFields - Fields to update in the Actor + * @returns The updated Actor object + * @see https://docs.apify.com/api/v2/act-put */ async update(newFields: ActorUpdateOptions): Promise { ow(newFields, ow.object); @@ -47,15 +74,47 @@ export class ActorClient extends ResourceClient { } /** - * https://docs.apify.com/api/v2#/reference/actors/actor-object/delete-actor + * Deletes the Actor. + * + * @see https://docs.apify.com/api/v2/act-delete */ async delete(): Promise { return this._delete(); } /** - * Starts an actor and immediately returns the Run object. - * https://docs.apify.com/api/v2#/reference/actors/run-collection/run-actor + * Starts the Actor and immediately returns the Run object. + * + * The Actor run can be configured with optional input and various options. The run starts + * asynchronously and this method returns immediately without waiting for completion. + * Use the {@link call} method if you want to wait for the Actor to finish. + * + * @param input - Input for the Actor. Can be any JSON-serializable value (object, array, string, number). + * If `contentType` is specified in options, input should be a string or Buffer. + * @param options - Run configuration options + * @param options.build - Tag or number of the build to run (e.g., `'beta'` or `'1.2.345'`). If not provided, uses the default build. + * @param options.memory - Memory in megabytes allocated for the run. If not provided, uses the Actor's default memory setting. + * @param options.timeout - Timeout for the run in seconds. Zero means no timeout. If not provided, uses the Actor's default timeout. + * @param options.waitForFinish - Maximum time to wait (in seconds, max 60s) for the run to finish on the API side before returning. Default is 0 (returns immediately). + * @param options.webhooks - Webhooks to trigger when the Actor run reaches a specific state (e.g., `SUCCEEDED`, `FAILED`). + * @param options.maxItems - Maximum number of dataset items that will be charged (only for pay-per-result Actors). + * @param options.maxTotalChargeUsd - Maximum cost in USD (only for pay-per-event Actors). + * @param options.contentType - Content type of the input. If specified, input must be a string or Buffer. + * @returns The Actor run object with status, usage, and storage IDs + * @see https://docs.apify.com/api/v2/act-runs-post + * + * @example + * ```javascript + * // Start Actor with simple input + * const run = await client.actor('my-actor').start({ url: 'https://example.com' }); + * console.log(`Run started with ID: ${run.id}, status: ${run.status}`); + * + * // Start Actor with specific build and memory + * const run = await client.actor('my-actor').start( + * { url: 'https://example.com' }, + * { build: '0.1.2', memory: 512, timeout: 300 } + * ); + * ``` */ async start(input?: unknown, options: ActorStartOptions = {}): Promise { // input can be anything, so no point in validating it. E.g. if you set content-type to application/pdf @@ -122,9 +181,41 @@ export class ActorClient extends ResourceClient { } /** - * Starts an actor and waits for it to finish before returning the Run object. - * It waits indefinitely, unless the `waitSecs` option is provided. - * https://docs.apify.com/api/v2#/reference/actors/run-collection/run-actor + * Starts the Actor and waits for it to finish before returning the Run object. + * + * This is a convenience method that starts the Actor run and waits for its completion + * by polling the run status. It optionally streams logs to the console or a custom Log instance. + * By default, it waits indefinitely unless the `waitSecs` option is provided. + * + * @param input - Input for the Actor. Can be any JSON-serializable value (object, array, string, number). + * If `contentType` is specified in options, input should be a string or Buffer. + * @param options - Run configuration options (extends all options from {@link start}) + * @param options.waitSecs - Maximum time to wait for the run to finish, in seconds. If omitted, waits indefinitely. + * @param options.log - Log instance for streaming run logs. Use `'default'` for console output, `null` to disable logging, or provide a custom Log instance. + * @param options.build - Tag or number of the build to run (e.g., `'beta'` or `'1.2.345'`). + * @param options.memory - Memory in megabytes allocated for the run. + * @param options.timeout - Maximum run duration in seconds. + * @returns The finished Actor run object with final status (`SUCCEEDED`, `FAILED`, `ABORTED`, or `TIMED-OUT`) + * @see https://docs.apify.com/api/v2/act-runs-post + * + * @example + * ```javascript + * // Run an Actor and wait for it to finish + * const run = await client.actor('my-actor').call({ url: 'https://example.com' }); + * console.log(`Run finished with status: ${run.status}`); + * console.log(`Dataset ID: ${run.defaultDatasetId}`); + * + * // Run with a timeout and log streaming to console + * const run = await client.actor('my-actor').call( + * { url: 'https://example.com' }, + * { waitSecs: 300, log: 'default' } + * ); + * + * // Run with custom log instance + * import { Log } from '@apify/log'; + * const log = new Log({ prefix: 'My Actor' }); + * const run = await client.actor('my-actor').call({ url: 'https://example.com' }, { log }); + * ``` */ async call(input?: unknown, options: ActorCallOptions = {}): Promise { // input can be anything, so no point in validating it. E.g. if you set content-type to application/pdf @@ -165,8 +256,33 @@ export class ActorClient extends ResourceClient { } /** - * https://docs.apify.com/api/v2#/reference/actors/build-collection/build-actor - * @return {Promise} + * Builds the Actor. + * + * Creates a new build of the specified Actor version. The build compiles the Actor's + * source code, installs dependencies, and prepares it for execution. + * + * @param versionNumber - Version number or tag to build (e.g., `'0.1'`, `'0.2'`, `'latest'`) + * @param options - Build configuration options + * @param options.betaPackages - If `true`, the build uses beta versions of Apify NPM packages. + * @param options.tag - Tag to be applied to the build (e.g., `'latest'`, `'beta'`). Existing tag with the same name will be replaced. + * @param options.useCache - If `false`, Docker build cache will be ignored. Default is `true`. + * @param options.waitForFinish - Maximum time to wait (in seconds, max 60s) for the build to finish on the API side before returning. Default is 0 (returns immediately). + * @returns The Build object with status and build details + * @see https://docs.apify.com/api/v2/act-builds-post + * + * @example + * ```javascript + * // Start a build and return immediately + * const build = await client.actor('my-actor').build('0.1'); + * console.log(`Build ${build.id} started with status: ${build.status}`); + * + * // Build and wait up to 120 seconds for it to finish + * const build = await client.actor('my-actor').build('0.1', { + * waitForFinish: 120, + * tag: 'latest', + * useCache: true + * }); + * ``` */ async build(versionNumber: string, options: ActorBuildOptions = {}): Promise { ow(versionNumber, ow.string); @@ -193,7 +309,11 @@ export class ActorClient extends ResourceClient { } /** - * https://docs.apify.com/api/v2/act-build-default-get + * Retrieves the default build of the Actor. + * + * @param options - Options for getting the build. + * @returns A client for the default build. + * @see https://docs.apify.com/api/v2/act-build-default-get */ async defaultBuild(options: BuildClientGetOptions = {}): Promise { const response = await this.httpClient.call({ @@ -214,7 +334,21 @@ export class ActorClient extends ResourceClient { } /** - * https://docs.apify.com/api/v2#/reference/actors/last-run-object-and-its-storages + * Returns a client for the last run of this Actor. + * + * Provides access to the most recent Actor run, optionally filtered by status or origin. + * + * @param options - Options to filter the last run + * @param options.status - Filter by run status (e.g., `'SUCCEEDED'`, `'FAILED'`, `'RUNNING'`, `'ABORTED'`, `'TIMED-OUT'`). + * @param options.origin - Filter by run origin (e.g., `'DEVELOPMENT'`, `'WEB'`, `'API'`, `'SCHEDULER'`). + * @returns A client for the last run + * @see https://docs.apify.com/api/v2/act-runs-last-get + * + * @example + * ```javascript + * // Get the last successful run + * const lastRun = await client.actor('my-actor').lastRun({ status: 'SUCCEEDED' }).get(); + * ``` */ lastRun(options: ActorLastRunOptions = {}): RunClient { ow( @@ -235,7 +369,10 @@ export class ActorClient extends ResourceClient { } /** - * https://docs.apify.com/api/v2#/reference/actors/build-collection + * Returns a client for managing builds of this Actor. + * + * @returns A client for the Actor's build collection + * @see https://docs.apify.com/api/v2/act-builds-get */ builds(): BuildCollectionClient { return new BuildCollectionClient( @@ -246,7 +383,10 @@ export class ActorClient extends ResourceClient { } /** - * https://docs.apify.com/api/v2#/reference/actors/run-collection + * Returns a client for managing runs of this Actor. + * + * @returns A client for the Actor's run collection + * @see https://docs.apify.com/api/v2/act-runs-get */ runs(): RunCollectionClient { return new RunCollectionClient( @@ -257,7 +397,11 @@ export class ActorClient extends ResourceClient { } /** - * https://docs.apify.com/api/v2#/reference/actors/version-object + * Returns a client for a specific version of this Actor. + * + * @param versionNumber - Version number (e.g., '0.1', '1.2.3') + * @returns A client for the specified Actor version + * @see https://docs.apify.com/api/v2/act-version-get */ version(versionNumber: string): ActorVersionClient { ow(versionNumber, ow.string); @@ -269,62 +413,109 @@ export class ActorClient extends ResourceClient { } /** - * https://docs.apify.com/api/v2#/reference/actors/version-collection - * @return {ActorVersionCollectionClient} + * Returns a client for managing versions of this Actor. + * + * @returns A client for the Actor's version collection + * @see https://docs.apify.com/api/v2/act-versions-get */ versions(): ActorVersionCollectionClient { return new ActorVersionCollectionClient(this._subResourceOptions()); } /** - * https://docs.apify.com/api/v2#/reference/actors/webhook-collection - * @return {WebhookCollectionClient} + * Returns a client for managing webhooks associated with this Actor. + * + * @returns A client for the Actor's webhook collection + * @see https://docs.apify.com/api/v2/act-webhooks-get */ webhooks(): WebhookCollectionClient { return new WebhookCollectionClient(this._subResourceOptions()); } } +/** + * Represents an Actor in the Apify platform. + * + * Actors are serverless computing units that can perform arbitrary tasks such as web scraping, + * data processing, automation, and more. Each Actor has versions, builds, and can be executed + * with different configurations. + */ export interface Actor { + /** Unique Actor ID */ id: string; + /** ID of the user who owns the Actor */ userId: string; + /** Unique name of the Actor (used in API paths, e.g., 'my-actor') */ name: string; + /** Username of the Actor's owner */ username: string; + /** Detailed description of what the Actor does */ description?: string; /** @deprecated Use defaultRunOptions.restartOnError instead */ restartOnError?: boolean; + /** Whether the Actor is publicly available in Apify Store */ isPublic: boolean; + /** Whether the Actor can be run by anonymous users without authentication */ isAnonymouslyRunnable?: boolean; + /** Timestamp when the Actor was created */ createdAt: Date; + /** Timestamp when the Actor was last modified */ modifiedAt: Date; + /** Usage and run statistics for the Actor */ stats: ActorStats; + /** All versions of this Actor */ versions: ActorVersion[]; + /** Pricing information for pay-per-result or pay-per-event Actors */ pricingInfos?: ActorRunPricingInfo[]; + /** Default configuration options for Actor runs */ defaultRunOptions: ActorDefaultRunOptions; + /** Example input to help users understand how to use the Actor */ exampleRunInput?: ActorExampleRunInput; + /** Whether the Actor is deprecated and should not be used */ isDeprecated?: boolean; + /** Deployment key used for automated deployments */ deploymentKey: string; + /** Human-readable title of the Actor (displayed in UI) */ title?: string; + /** Mapping of tags to specific builds (e.g., 'latest', 'beta') */ taggedBuilds?: ActorTaggedBuilds; + /** SEO-optimized title for the Actor's public page */ seoTitle?: string; + /** SEO-optimized description for the Actor's public page */ seoDescription?: string; + /** Categories the Actor belongs to (e.g., 'ECOMMERCE', 'SCRAPING') */ categories?: string[]; + /** Standby mode configuration for keeping Actor warm and responsive */ actorStandby?: ActorStandby & { isEnabled: boolean; }; } +/** + * Statistics about Actor usage and activity. + */ export interface ActorStats { + /** Total number of builds created for this Actor */ totalBuilds: number; + /** Total number of times this Actor has been run */ totalRuns: number; + /** Total number of unique users who have run this Actor */ totalUsers: number; + /** Number of unique users in the last 7 days */ totalUsers7Days: number; + /** Number of unique users in the last 30 days */ totalUsers30Days: number; + /** Number of unique users in the last 90 days */ totalUsers90Days: number; + /** Total number of times this Actor was used via metamorph */ totalMetamorphs: number; + /** Timestamp when the last run was started */ lastRunStartedAt: Date; } +/** + * Default configuration options for Actor runs. + */ export interface ActorDefaultRunOptions { build: string; timeoutSecs: number; @@ -332,19 +523,31 @@ export interface ActorDefaultRunOptions { restartOnError?: boolean; } +/** + * Example input data to demonstrate Actor usage. + */ export interface ActorExampleRunInput { body: string; contentType: string; } +/** + * Mapping of build tags (e.g., 'latest', 'beta') to their corresponding build information. + */ export type ActorTaggedBuilds = Record; +/** + * Information about a specific tagged build. + */ export interface ActorTaggedBuild { buildId?: string; buildNumber?: string; finishedAt?: Date; } +/** + * Fields that can be updated when modifying an Actor. + */ export type ActorUpdateOptions = Partial< Pick< Actor, @@ -363,6 +566,12 @@ export type ActorUpdateOptions = Partial< > >; +/** + * Configuration for Actor standby mode. + * + * Standby mode keeps Actor containers warm and ready to process requests with minimal latency. + * This is useful for Actors that need to respond quickly to incoming requests. + */ export interface ActorStandby { desiredRequestsPerActorRun: number; maxRequestsPerActorRun: number; @@ -373,8 +582,8 @@ export interface ActorStandby { export interface ActorStartOptions { /** - * Tag or number of the actor build to run (e.g. `beta` or `1.2.345`). - * If not provided, the run uses build tag or number from the default actor run configuration (typically `latest`). + * Tag or number of the Actor build to run (e.g. `beta` or `1.2.345`). + * If not provided, the run uses build tag or number from the default Actor run configuration (typically `latest`). */ build?: string; @@ -387,20 +596,20 @@ export interface ActorStartOptions { contentType?: string; /** - * Memory in megabytes which will be allocated for the new actor run. - * If not provided, the run uses memory of the default actor run configuration. + * Memory in megabytes which will be allocated for the new Actor run. + * If not provided, the run uses memory of the default Actor run configuration. */ memory?: number; /** - * Timeout for the actor run in seconds. Zero value means there is no timeout. - * If not provided, the run uses timeout of the default actor run configuration. + * Timeout for the Actor run in seconds. Zero value means there is no timeout. + * If not provided, the run uses timeout of the default Actor run configuration. */ timeout?: number; /** - * Maximum time to wait for the actor run to finish, in seconds. + * Maximum time to wait for the Actor run to finish, in seconds. * If the limit is reached, the returned promise is resolved to a run object that will have - * status `READY` or `RUNNING` and it will not contain the actor run output. + * status `READY` or `RUNNING` and it will not contain the Actor run output. * By default (or when `waitForFinish` is set to `0`), the function resolves immediately without waiting. * The wait is limited to 60s and happens on the API directly, as opposed to the `call` method and its * `waitSecs` option, which is implemented via polling on the client side instead (and has no limit like that). @@ -408,8 +617,8 @@ export interface ActorStartOptions { waitForFinish?: number; /** - * Specifies optional webhooks associated with the actor run, which can be used - * to receive a notification e.g. when the actor finished or failed, see + * Specifies optional webhooks associated with the Actor run, which can be used + * to receive a notification e.g. when the Actor finished or failed, see * [ad hook webhooks documentation](https://docs.apify.com/webhooks/ad-hoc-webhooks) for detailed description. */ webhooks?: readonly WebhookUpdateData[]; @@ -445,19 +654,29 @@ export interface ActorStartOptions { forcePermissionLevel?: ACTOR_PERMISSION_LEVEL; } +/** + * Options for calling an Actor and waiting for it to finish. + * + * Extends {@link ActorStartOptions} with additional options for waiting and log streaming. + */ export interface ActorCallOptions extends Omit { /** - * Wait time in seconds for the actor run to finish. + * Wait time in seconds for the Actor run to finish. */ waitSecs?: number; /** - * `Log` instance that should be used to redirect actor run logs to. + * `Log` instance that should be used to redirect Actor run logs to. * If `undefined` or `'default'` the pre-defined `Log` will be created and used. * If `null`, no log redirection will occur. */ log?: Log | null | 'default'; } +/** + * Simplified Actor run information used in list results. + * + * Contains basic information about a run without detailed statistics. + */ export interface ActorRunListItem { id: string; actId: string; @@ -474,6 +693,12 @@ export interface ActorRunListItem { usageTotalUsd?: number; } +/** + * Complete Actor run information including statistics and usage details. + * + * Represents a single execution of an Actor with all its configuration, status, + * and resource usage information. + */ export interface ActorRun extends ActorRunListItem { userId: string; statusMessage?: string; @@ -490,27 +715,52 @@ export interface ActorRun extends ActorRunListItem { generalAccess?: RUN_GENERAL_ACCESS | null; } +/** + * Resource usage metrics for an Actor run. + * + * All values represent the total consumption during the run's lifetime. + */ export interface ActorRunUsage { + /** Compute units consumed (combines CPU and memory usage over time) */ ACTOR_COMPUTE_UNITS?: number; + /** Number of Dataset read operations */ DATASET_READS?: number; + /** Number of Dataset write operations */ DATASET_WRITES?: number; + /** Number of key-value store read operations */ KEY_VALUE_STORE_READS?: number; + /** Number of key-value store write operations */ KEY_VALUE_STORE_WRITES?: number; + /** Number of key-value store list operations */ KEY_VALUE_STORE_LISTS?: number; + /** Number of Request queue read operations */ REQUEST_QUEUE_READS?: number; + /** Number of Request queue write operations */ REQUEST_QUEUE_WRITES?: number; + /** Internal data transfer within Apify platform (in gigabytes) */ DATA_TRANSFER_INTERNAL_GBYTES?: number; + /** External data transfer to/from internet (in gigabytes) */ DATA_TRANSFER_EXTERNAL_GBYTES?: number; + /** Residential proxy data transfer (in gigabytes) */ PROXY_RESIDENTIAL_TRANSFER_GBYTES?: number; + /** Number of SERP (Search Engine Results Page) proxy requests */ PROXY_SERPS?: number; } +/** + * Metadata about how an Actor run was initiated. + */ export interface ActorRunMeta { origin: string; clientIp?: string; userAgent: string; } +/** + * Runtime statistics for an Actor run. + * + * Provides detailed metrics about resource consumption and performance during the run. + */ export interface ActorRunStats { inputBodyLen: number; restartCount: number; @@ -529,6 +779,11 @@ export interface ActorRunStats { computeUnits: number; } +/** + * Configuration options used for an Actor run. + * + * These are the actual options that were applied to the run (may differ from requested options). + */ export interface ActorRunOptions { build: string; timeoutSecs: number; @@ -539,6 +794,9 @@ export interface ActorRunOptions { restartOnError?: boolean; } +/** + * Options for building an Actor. + */ export interface ActorBuildOptions { betaPackages?: boolean; tag?: string; @@ -546,10 +804,18 @@ export interface ActorBuildOptions { waitForFinish?: number; } +/** + * Options for filtering the last run of an Actor. + */ export interface ActorLastRunOptions { status?: keyof typeof ACT_JOB_STATUSES; } +/** + * Actor definition from the `.actor/actor.json` file. + * + * Contains the Actor's configuration, input schema, and other metadata. + */ export interface ActorDefinition { actorSpecification: number; name: string; @@ -581,10 +847,16 @@ interface CommonActorPricingInfo { reasonForChange?: string; } +/** + * Pricing information for free Actors. + */ export interface FreeActorPricingInfo extends CommonActorPricingInfo { pricingModel: 'FREE'; } +/** + * Pricing information for Actors with a flat monthly subscription fee. + */ export interface FlatPricePerMonthActorPricingInfo extends CommonActorPricingInfo { pricingModel: 'FLAT_PRICE_PER_MONTH'; /** For how long this Actor can be used for free in trial period */ @@ -593,6 +865,11 @@ export interface FlatPricePerMonthActorPricingInfo extends CommonActorPricingInf pricePerUnitUsd: number; } +/** + * Pricing information for pay-per-result Actors. + * + * These Actors charge based on the number of items saved to the dataset. + */ export interface PricePerDatasetItemActorPricingInfo extends CommonActorPricingInfo { pricingModel: 'PRICE_PER_DATASET_ITEM'; /** Name of the unit that is being charged */ @@ -600,14 +877,25 @@ export interface PricePerDatasetItemActorPricingInfo extends CommonActorPricingI pricePerUnitUsd: number; } +/** + * Definition of a chargeable event for pay-per-event Actors. + */ export interface ActorChargeEvent { eventPriceUsd: number; eventTitle: string; eventDescription?: string; } +/** + * Mapping of event names to their pricing information. + */ export type ActorChargeEvents = Record; +/** + * Pricing information for pay-per-event Actors. + * + * These Actors charge based on specific events (e.g., emails sent, API calls made). + */ export interface PricePerEventActorPricingInfo extends CommonActorPricingInfo { pricingModel: 'PAY_PER_EVENT'; pricingPerEvent: { @@ -616,6 +904,9 @@ export interface PricePerEventActorPricingInfo extends CommonActorPricingInfo { minimalMaxTotalChargeUsd?: number; } +/** + * Union type representing all possible Actor pricing models. + */ export type ActorRunPricingInfo = | PricePerEventActorPricingInfo | PricePerDatasetItemActorPricingInfo diff --git a/src/resource_clients/actor_collection.ts b/src/resource_clients/actor_collection.ts index 870a883a..0add7fa3 100644 --- a/src/resource_clients/actor_collection.ts +++ b/src/resource_clients/actor_collection.ts @@ -6,6 +6,29 @@ import type { PaginatedIterator, PaginatedList, PaginationOptions } from '../uti import type { Actor, ActorDefaultRunOptions, ActorExampleRunInput, ActorStandby } from './actor'; import type { ActorVersion } from './actor_version'; +/** + * Client for managing the collection of Actors in your account. + * + * Provides methods to list and create Actors. To access an individual Actor, + * use the `actor()` method on the main ApifyClient. + * + * @example + * ```javascript + * const client = new ApifyClient({ token: 'my-token' }); + * const actorsClient = client.actors(); + * + * // List all Actors + * const { items } = await actorsClient.list(); + * + * // Create a new Actor + * const newActor = await actorsClient.create({ + * name: 'my-actor', + * title: 'My Actor' + * }); + * ``` + * + * @see https://docs.apify.com/platform/actors + */ export class ActorCollectionClient extends ResourceCollectionClient { /** * @hidden @@ -18,13 +41,13 @@ export class ActorCollectionClient extends ResourceCollectionClient { } /** - * https://docs.apify.com/api/v2#/reference/actors/actor-collection/get-list-of-actors + * Lists all Actors. * * Awaiting the return value (as you would with a Promise) will result in a single API call. The amount of fetched * items in a single API call is limited. * ```javascript * const paginatedList = await client.list(options); - *``` + * ``` * * Asynchronous iteration is also supported. This will fetch additional pages if needed until all items are * retrieved. @@ -32,6 +55,10 @@ export class ActorCollectionClient extends ResourceCollectionClient { * ```javascript * for await (const singleItem of client.list(options)) {...} * ``` + * + * @param options - Pagination options. + * @returns A paginated iterator of Actors. + * @see https://docs.apify.com/api/v2/acts-get */ list(options: ActorCollectionListOptions = {}): PaginatedIterator { ow( @@ -49,7 +76,11 @@ export class ActorCollectionClient extends ResourceCollectionClient { } /** - * https://docs.apify.com/api/v2#/reference/actors/actor-collection/create-actor + * Creates a new Actor. + * + * @param actor - The Actor data. + * @returns The created Actor object. + * @see https://docs.apify.com/api/v2/acts-post */ async create(actor: ActorCollectionCreateOptions): Promise { ow(actor, ow.optional.object); diff --git a/src/resource_clients/actor_env_var.ts b/src/resource_clients/actor_env_var.ts index f2643ddc..fad0dc2b 100644 --- a/src/resource_clients/actor_env_var.ts +++ b/src/resource_clients/actor_env_var.ts @@ -4,6 +4,28 @@ import type { ApiClientSubResourceOptions } from '../base/api_client'; import { ResourceClient } from '../base/resource_client'; import type { ActorEnvironmentVariable } from './actor_version'; +/** + * Client for managing a specific Actor environment variable. + * + * Environment variables are key-value pairs that are available to the Actor during execution. + * This client provides methods to get, update, and delete environment variables. + * + * @example + * ```javascript + * const client = new ApifyClient({ token: 'my-token' }); + * const actorClient = client.actor('my-actor-id'); + * const versionClient = actorClient.version('0.1'); + * + * // Get an environment variable + * const envVarClient = versionClient.envVar('MY_VAR'); + * const envVar = await envVarClient.get(); + * + * // Update environment variable + * await envVarClient.update({ value: 'new-value' }); + * ``` + * + * @see https://docs.apify.com/platform/actors/development/actor-definition/environment-variables + */ export class ActorEnvVarClient extends ResourceClient { /** * @hidden @@ -16,14 +38,21 @@ export class ActorEnvVarClient extends ResourceClient { } /** - * https://docs.apify.com/api/v2#/reference/actors/environment-variable-object/get-environment-variable + * Retrieves the environment variable. + * + * @returns The environment variable object, or `undefined` if it does not exist. + * @see https://docs.apify.com/api/v2/act-version-env-var-get */ async get(): Promise { return this._get(); } /** - * https://docs.apify.com/api/v2#/reference/actors/environment-variable-object/update-environment-variable + * Updates the environment variable. + * + * @param actorEnvVar - The updated environment variable data. + * @returns The updated environment variable object. + * @see https://docs.apify.com/api/v2/act-version-env-var-put */ async update(actorEnvVar: ActorEnvironmentVariable): Promise { ow(actorEnvVar, ow.object); @@ -31,7 +60,9 @@ export class ActorEnvVarClient extends ResourceClient { } /** - * https://docs.apify.com/api/v2#/reference/actors/environment-variable-object/delete-environment-variable + * Deletes the environment variable. + * + * @see https://docs.apify.com/api/v2/act-version-env-var-delete */ async delete(): Promise { return this._delete(); diff --git a/src/resource_clients/actor_env_var_collection.ts b/src/resource_clients/actor_env_var_collection.ts index 89e7d2b7..a215922c 100644 --- a/src/resource_clients/actor_env_var_collection.ts +++ b/src/resource_clients/actor_env_var_collection.ts @@ -5,6 +5,32 @@ import { ResourceCollectionClient } from '../base/resource_collection_client'; import type { PaginatedList, PaginationOptions } from '../utils'; import type { ActorEnvironmentVariable } from './actor_version'; +/** + * Client for managing the collection of environment variables for an Actor version. + * + * Environment variables are key-value pairs that are available to the Actor during execution. + * This client provides methods to list and create environment variables. + * + * @example + * ```javascript + * const client = new ApifyClient({ token: 'my-token' }); + * const actorClient = client.actor('my-actor-id'); + * const versionClient = actorClient.version('0.1'); + * + * // List all environment variables + * const envVarsClient = versionClient.envVars(); + * const { items } = await envVarsClient.list(); + * + * // Create a new environment variable + * const newEnvVar = await envVarsClient.create({ + * name: 'MY_VAR', + * value: 'my-value', + * isSecret: false + * }); + * ``` + * + * @see https://docs.apify.com/platform/actors/development/actor-definition/environment-variables + */ export class ActorEnvVarCollectionClient extends ResourceCollectionClient { /** * @hidden @@ -17,13 +43,13 @@ export class ActorEnvVarCollectionClient extends ResourceCollectionClient { } /** - * https://docs.apify.com/api/v2#/reference/actors/environment-variable-collection/get-list-of-environment-variables + * Lists all environment variables of this Actor version. * * Awaiting the return value (as you would with a Promise) will result in a single API call. The amount of fetched * items in a single API call is limited. * ```javascript * const paginatedList = await client.list(options); - *``` + * ``` * * Asynchronous iteration is also supported. This will fetch additional pages if needed until all items are * retrieved. @@ -31,6 +57,10 @@ export class ActorEnvVarCollectionClient extends ResourceCollectionClient { * ```javascript * for await (const singleItem of client.list(options)) {...} * ``` + * + * @param options - Pagination options. + * @returns A paginated iterator of environment variables. + * @see https://docs.apify.com/api/v2/act-version-env-vars-get */ list( options: ActorEnvVarCollectionListOptions = {}, @@ -47,7 +77,11 @@ export class ActorEnvVarCollectionClient extends ResourceCollectionClient { } /** - * https://docs.apify.com/api/v2#/reference/actors/environment-variable-collection/create-environment-variable + * Creates a new environment variable for this Actor version. + * + * @param actorEnvVar - The environment variable data. + * @returns The created environment variable object. + * @see https://docs.apify.com/api/v2/act-version-env-vars-post */ async create(actorEnvVar: ActorEnvironmentVariable): Promise { ow(actorEnvVar, ow.optional.object); diff --git a/src/resource_clients/actor_version.ts b/src/resource_clients/actor_version.ts index f3f2490b..7bb306e8 100644 --- a/src/resource_clients/actor_version.ts +++ b/src/resource_clients/actor_version.ts @@ -5,6 +5,27 @@ import { ResourceClient } from '../base/resource_client'; import { ActorEnvVarClient } from './actor_env_var'; import { ActorEnvVarCollectionClient } from './actor_env_var_collection'; +/** + * Client for managing a specific Actor version. + * + * Actor versions represent specific builds or snapshots of an Actor's code. This client provides + * methods to get, update, and delete versions, as well as manage their environment variables. + * + * @example + * ```javascript + * const client = new ApifyClient({ token: 'my-token' }); + * const actorClient = client.actor('my-actor-id'); + * + * // Get a specific version + * const versionClient = actorClient.version('0.1'); + * const version = await versionClient.get(); + * + * // Update version + * await versionClient.update({ buildTag: 'latest' }); + * ``` + * + * @see https://docs.apify.com/platform/actors/development/actor-definition/versions + */ export class ActorVersionClient extends ResourceClient { /** * @hidden @@ -17,14 +38,21 @@ export class ActorVersionClient extends ResourceClient { } /** - * https://docs.apify.com/api/v2#/reference/actors/version-object/get-version + * Retrieves the Actor version. + * + * @returns The Actor version object, or `undefined` if it does not exist. + * @see https://docs.apify.com/api/v2/act-version-get */ async get(): Promise { return this._get(); } /** - * https://docs.apify.com/api/v2#/reference/actors/version-object/update-version + * Updates the Actor version with the specified fields. + * + * @param newFields - Fields to update. + * @returns The updated Actor version object. + * @see https://docs.apify.com/api/v2/act-version-put */ async update(newFields: ActorVersion): Promise { ow(newFields, ow.object); @@ -33,14 +61,20 @@ export class ActorVersionClient extends ResourceClient { } /** - * https://docs.apify.com/api/v2#/reference/actors/version-object/delete-version + * Deletes the Actor version. + * + * @see https://docs.apify.com/api/v2/act-version-delete */ async delete(): Promise { return this._delete(); } /** - * TODO: https://docs.apify.com/api/v2#/reference/actors/env-var-object + * Returns a client for the specified environment variable of this Actor version. + * + * @param envVarName - Name of the environment variable. + * @returns A client for the environment variable. + * @see https://docs.apify.com/api/v2/act-version-env-var-get */ envVar(envVarName: string): ActorEnvVarClient { ow(envVarName, ow.string); @@ -52,8 +86,10 @@ export class ActorVersionClient extends ResourceClient { } /** - * TODO: https://docs.apify.com/api/v2#/reference/actors/env-var-collection - * @return {ActorVersionCollectionClient} + * Returns a client for the environment variables of this Actor version. + * + * @returns A client for the Actor version's environment variables. + * @see https://docs.apify.com/api/v2/act-version-env-vars-get */ envVars(): ActorEnvVarCollectionClient { return new ActorEnvVarCollectionClient(this._subResourceOptions()); diff --git a/src/resource_clients/actor_version_collection.ts b/src/resource_clients/actor_version_collection.ts index 160b1daf..f4b9d67f 100644 --- a/src/resource_clients/actor_version_collection.ts +++ b/src/resource_clients/actor_version_collection.ts @@ -5,6 +5,30 @@ import { ResourceCollectionClient } from '../base/resource_collection_client'; import type { PaginatedList, PaginationOptions } from '../utils'; import type { ActorVersion, FinalActorVersion } from './actor_version'; +/** + * Client for managing the collection of Actor versions. + * + * Actor versions represent specific builds or snapshots of an Actor's code. This client provides + * methods to list and create versions for a specific Actor. + * + * @example + * ```javascript + * const client = new ApifyClient({ token: 'my-token' }); + * const actorClient = client.actor('my-actor-id'); + * + * // List all versions + * const versionsClient = actorClient.versions(); + * const { items } = await versionsClient.list(); + * + * // Create a new version + * const newVersion = await versionsClient.create({ + * versionNumber: '0.2', + * buildTag: 'latest' + * }); + * ``` + * + * @see https://docs.apify.com/platform/actors/development/actor-definition/versions + */ export class ActorVersionCollectionClient extends ResourceCollectionClient { /** * @hidden @@ -17,13 +41,13 @@ export class ActorVersionCollectionClient extends ResourceCollectionClient { } /** - * https://docs.apify.com/api/v2#/reference/actors/version-collection/get-list-of-versions + * Lists all Actor versions. * * Awaiting the return value (as you would with a Promise) will result in a single API call. The amount of fetched * items in a single API call is limited. * ```javascript * const paginatedList = await client.list(options); - *``` + * ``` * * Asynchronous iteration is also supported. This will fetch additional pages if needed until all items are * retrieved. @@ -31,6 +55,10 @@ export class ActorVersionCollectionClient extends ResourceCollectionClient { * ```javascript * for await (const singleItem of client.list(options)) {...} * ``` + * + * @param options - Pagination options. + * @returns A paginated iterator of Actor versions. + * @see https://docs.apify.com/api/v2/act-versions-get */ list( options: ActorVersionCollectionListOptions = {}, @@ -48,7 +76,11 @@ export class ActorVersionCollectionClient extends ResourceCollectionClient { } /** - * https://docs.apify.com/api/v2#/reference/actors/version-collection/create-version + * Creates a new Actor version. + * + * @param actorVersion - The Actor version data. + * @returns The created Actor version object. + * @see https://docs.apify.com/api/v2/act-versions-post */ async create(actorVersion: ActorVersion): Promise { ow(actorVersion, ow.optional.object); diff --git a/src/resource_clients/build.ts b/src/resource_clients/build.ts index e2f4fb37..ac17ab69 100644 --- a/src/resource_clients/build.ts +++ b/src/resource_clients/build.ts @@ -8,6 +8,29 @@ import { cast, parseDateFields, pluckData } from '../utils'; import type { ActorDefinition } from './actor'; import { LogClient } from './log'; +/** + * Client for managing a specific Actor build. + * + * Builds are created when an Actor is built from source code. This client provides methods + * to get build details, wait for the build to finish, abort it, and access its logs. + * + * @example + * ```javascript + * const client = new ApifyClient({ token: 'my-token' }); + * const buildClient = client.build('my-build-id'); + * + * // Get build details + * const build = await buildClient.get(); + * + * // Wait for the build to finish + * const finishedBuild = await buildClient.waitForFinish(); + * + * // Access build logs + * const log = await buildClient.log().get(); + * ``` + * + * @see https://docs.apify.com/platform/actors/running/runs-and-builds#builds + */ export class BuildClient extends ResourceClient { /** * @hidden @@ -20,7 +43,22 @@ export class BuildClient extends ResourceClient { } /** - * https://docs.apify.com/api/v2#/reference/actor-builds/build-object/get-build + * Gets the Actor build object from the Apify API. + * + * @param options - Get options + * @param options.waitForFinish - Maximum time to wait (in seconds, max 60s) for the build to finish on the API side before returning. Default is 0 (returns immediately). + * @returns The Build object, or `undefined` if it does not exist + * @see https://docs.apify.com/api/v2/actor-build-get + * + * @example + * ```javascript + * // Get build status immediately + * const build = await client.build('build-id').get(); + * console.log(`Status: ${build.status}`); + * + * // Wait up to 60 seconds for build to finish + * const build = await client.build('build-id').get({ waitForFinish: 60 }); + * ``` */ async get(options: BuildClientGetOptions = {}): Promise { ow( @@ -34,7 +72,17 @@ export class BuildClient extends ResourceClient { } /** - * https://docs.apify.com/api/v2#/reference/actor-builds/abort-build/abort-build + * Aborts the Actor build. + * + * Stops the build process immediately. The build will have an `ABORTED` status. + * + * @returns The updated Build object with `ABORTED` status + * @see https://docs.apify.com/api/v2/actor-build-abort-post + * + * @example + * ```javascript + * await client.build('build-id').abort(); + * ``` */ async abort(): Promise { const response = await this.httpClient.call({ @@ -47,14 +95,19 @@ export class BuildClient extends ResourceClient { } /** - * https://docs.apify.com/api/v2#/reference/actor-builds/delete-build/delete-build + * Deletes the Actor build. + * + * @see https://docs.apify.com/api/v2/actor-build-delete */ async delete(): Promise { return this._delete(); } /** - * https://docs.apify.com/api/v2/actor-build-openapi-json-get + * Retrieves the OpenAPI definition for the Actor build. + * + * @returns The OpenAPI definition object. + * @see https://docs.apify.com/api/v2/actor-build-openapi-json-get */ async getOpenApiDefinition(): Promise { const response = await this.httpClient.call({ @@ -67,15 +120,34 @@ export class BuildClient extends ResourceClient { } /** - * Returns a promise that resolves with the finished Build object when the provided actor build finishes - * or with the unfinished Build object when the `waitSecs` timeout lapses. The promise is NOT rejected - * based on run status. You can inspect the `status` property of the Build object to find out its status. + * Waits for the Actor build to finish and returns the finished Build object. + * + * The promise resolves when the build reaches a terminal state (`SUCCEEDED`, `FAILED`, `ABORTED`, or `TIMED-OUT`). + * If `waitSecs` is provided and the timeout is reached, the promise resolves with the unfinished + * Build object (status will be `RUNNING` or `READY`). The promise is NOT rejected based on build status. * - * The difference between this function and the `waitForFinish` parameter of the `get` method - * is the fact that this function can wait indefinitely. Its use is preferable to the - * `waitForFinish` parameter alone, which it uses internally. + * Unlike the `waitForFinish` parameter in {@link get}, this method can wait indefinitely + * by polling the build status. It uses the `waitForFinish` parameter internally (max 60s per call) + * and continuously polls until the build finishes or the timeout is reached. * * This is useful when you need to immediately start a run after a build finishes. + * + * @param options - Wait options + * @param options.waitSecs - Maximum time to wait for the build to finish, in seconds. If omitted, waits indefinitely. + * @returns The Build object (finished or still building if timeout was reached) + * + * @example + * ```javascript + * // Wait indefinitely for build to finish + * const build = await client.build('build-id').waitForFinish(); + * console.log(`Build finished with status: ${build.status}`); + * + * // Start a run immediately after build succeeds + * const build = await client.build('build-id').waitForFinish(); + * if (build.status === 'SUCCEEDED') { + * const run = await client.actor('my-actor').start(); + * } + * ``` */ async waitForFinish(options: BuildClientWaitForFinishOptions = {}): Promise { ow( @@ -89,7 +161,17 @@ export class BuildClient extends ResourceClient { } /** - * https://docs.apify.com/api/v2#/reference/actor-builds/build-log + * Returns a client for accessing the log of this Actor build. + * + * @returns A client for accessing the build's log + * @see https://docs.apify.com/api/v2/actor-build-log-get + * + * @example + * ```javascript + * // Get build log + * const log = await client.build('build-id').log().get(); + * console.log(log); + * ``` */ log(): LogClient { return new LogClient( @@ -100,10 +182,16 @@ export class BuildClient extends ResourceClient { } } +/** + * Options for getting a Build. + */ export interface BuildClientGetOptions { waitForFinish?: number; } +/** + * Options for waiting for a Build to finish. + */ export interface BuildClientWaitForFinishOptions { /** * Maximum time to wait for the build to finish, in seconds. @@ -113,12 +201,21 @@ export interface BuildClientWaitForFinishOptions { waitSecs?: number; } +/** + * Metadata about how a Build was initiated. + */ export interface BuildMeta { origin: string; clientIp: string; userAgent: string; } +/** + * Represents an Actor build. + * + * Builds compile Actor source code and prepare it for execution. Each build has a unique ID + * and can be tagged (e.g., 'latest', 'beta') for easy reference. + */ export interface Build { id: string; actId: string; @@ -144,16 +241,25 @@ export interface Build { actorDefinition?: ActorDefinition; } +/** + * Resource usage for an Actor build. + */ export interface BuildUsage { ACTOR_COMPUTE_UNITS?: number; } +/** + * Runtime statistics for an Actor build. + */ export interface BuildStats { durationMillis: number; runTimeSecs: number; computeUnits: number; } +/** + * Configuration options used for an Actor build. + */ export interface BuildOptions { useCache?: boolean; betaPackages?: boolean; @@ -161,6 +267,12 @@ export interface BuildOptions { diskMbytes?: number; } +/** + * OpenAPI specification for an Actor. + * + * Defines the Actor's API interface in OpenAPI 3.0 format, useful for integration + * with tools like ChatGPT plugins and other API consumers. + */ export interface OpenApiDefinition { openapi: string; info: { diff --git a/src/resource_clients/build_collection.ts b/src/resource_clients/build_collection.ts index 460e0f51..bb7b0d58 100644 --- a/src/resource_clients/build_collection.ts +++ b/src/resource_clients/build_collection.ts @@ -5,6 +5,27 @@ import { ResourceCollectionClient } from '../base/resource_collection_client'; import type { PaginatedIterator, PaginatedList, PaginationOptions } from '../utils'; import type { Build } from './build'; +/** + * Client for managing the collection of Actor builds. + * + * Provides methods to list Actor builds across all Actors or for a specific Actor. + * To access an individual build, use the `build()` method on the main ApifyClient. + * + * @example + * ```javascript + * const client = new ApifyClient({ token: 'my-token' }); + * + * // List all builds + * const buildsClient = client.builds(); + * const { items } = await buildsClient.list(); + * + * // List builds for a specific Actor + * const actorBuildsClient = client.actor('my-actor-id').builds(); + * const { items: actorBuilds } = await actorBuildsClient.list(); + * ``` + * + * @see https://docs.apify.com/platform/actors/running/runs-and-builds#builds + */ export class BuildCollectionClient extends ResourceCollectionClient { /** * @hidden @@ -17,13 +38,13 @@ export class BuildCollectionClient extends ResourceCollectionClient { } /** - * https://docs.apify.com/api/v2#/reference/actors/build-collection/get-list-of-builds + * Lists all Actor builds. * * Awaiting the return value (as you would with a Promise) will result in a single API call. The amount of fetched * items in a single API call is limited. * ```javascript * const paginatedList = await client.list(options); - *``` + * ``` * * Asynchronous iteration is also supported. This will fetch additional pages if needed until all items are * retrieved. @@ -31,6 +52,10 @@ export class BuildCollectionClient extends ResourceCollectionClient { * ```javascript * for await (const singleItem of client.list(options)) {...} * ``` + * + * @param options - Pagination and sorting options. + * @returns A paginated iterator of Actor builds. + * @see https://docs.apify.com/api/v2/actor-builds-get */ list(options: BuildCollectionClientListOptions = {}): PaginatedIterator { ow( diff --git a/src/resource_clients/dataset.ts b/src/resource_clients/dataset.ts index 220b3409..2de00736 100644 --- a/src/resource_clients/dataset.ts +++ b/src/resource_clients/dataset.ts @@ -15,6 +15,35 @@ import type { ApifyRequestConfig, ApifyResponse } from '../http_client'; import type { PaginatedList } from '../utils'; import { applyQueryParamsToUrl, cast, catchNotFoundOrThrow, pluckData } from '../utils'; +/** + * Client for managing a specific Dataset. + * + * Datasets store structured data results from Actor runs. This client provides methods to push items, + * list and retrieve items, download items in various formats (JSON, CSV, Excel, etc.), and manage + * the dataset. + * + * @template Data - Type of items stored in the dataset + * + * @example + * ```javascript + * const client = new ApifyClient({ token: 'my-token' }); + * const datasetClient = client.dataset('my-dataset-id'); + * + * // Push items to the dataset + * await datasetClient.pushItems([ + * { url: 'https://example.com', title: 'Example' }, + * { url: 'https://test.com', title: 'Test' } + * ]); + * + * // List all items + * const { items } = await datasetClient.listItems(); + * + * // Download items as CSV + * const buffer = await datasetClient.downloadItems('csv'); + * ``` + * + * @see https://docs.apify.com/platform/storage/dataset + */ export class DatasetClient< Data extends Record = Record, > extends ResourceClient { @@ -29,14 +58,21 @@ export class DatasetClient< } /** - * https://docs.apify.com/api/v2#/reference/datasets/dataset/get-dataset + * Gets the dataset object from the Apify API. + * + * @returns The Dataset object, or `undefined` if it does not exist + * @see https://docs.apify.com/api/v2/dataset-get */ async get(): Promise { return this._get({}, SMALL_TIMEOUT_MILLIS); } /** - * https://docs.apify.com/api/v2#/reference/datasets/dataset/update-dataset + * Updates the dataset with specified fields. + * + * @param newFields - Fields to update in the dataset + * @returns The updated Dataset object + * @see https://docs.apify.com/api/v2/dataset-put */ async update(newFields: DatasetClientUpdateOptions): Promise { ow(newFields, ow.object); @@ -45,14 +81,56 @@ export class DatasetClient< } /** - * https://docs.apify.com/api/v2#/reference/datasets/dataset/delete-dataset + * Deletes the dataset. + * + * @see https://docs.apify.com/api/v2/dataset-delete */ async delete(): Promise { return this._delete(SMALL_TIMEOUT_MILLIS); } /** - * https://docs.apify.com/api/v2#/reference/datasets/item-collection/get-items + * Lists items in the dataset. + * + * Returns a paginated list of dataset items. You can use pagination parameters to retrieve + * specific subsets of items, and various filtering and formatting options to customize + * the output. + * + * @param options - Options for listing items + * @param options.limit - Maximum number of items to return. Default is all items. + * @param options.offset - Number of items to skip from the beginning. Default is 0. + * @param options.desc - If `true`, items are returned in descending order (newest first). Default is `false`. + * @param options.fields - Array of field names to include in the results. Omits all other fields. + * @param options.omit - Array of field names to exclude from the results. + * @param options.clean - If `true`, returns only non-empty items and skips hidden fields. Default is `false`. + * @param options.skipEmpty - If `true`, skips empty items. Default is `false`. + * @param options.skipHidden - If `true`, skips hidden fields (fields starting with `#`). Default is `false`. + * @param options.flatten - Array of field names to flatten. Nested objects are converted to dot notation (e.g., `obj.field`). + * @param options.unwind - Field name or array of field names to unwind. Each array value creates a separate item. + * @param options.view - Name of a predefined view to use for field selection. + * @returns A paginated list with `items`, `total` count, `offset`, `count`, and `limit` + * @see https://docs.apify.com/api/v2/dataset-items-get + * + * @example + * ```javascript + * // Get first 100 items + * const { items, total } = await client.dataset('my-dataset').listItems({ limit: 100 }); + * console.log(`Retrieved ${items.length} of ${total} total items`); + * + * // Get items with specific fields only + * const { items } = await client.dataset('my-dataset').listItems({ + * fields: ['url', 'title'], + * skipEmpty: true, + * limit: 50 + * }); + * + * // Get items in descending order with pagination + * const { items } = await client.dataset('my-dataset').listItems({ + * desc: true, + * offset: 100, + * limit: 50 + * }); + * ``` */ async listItems(options: DatasetClientListItemOptions = {}): Promise> { ow( @@ -84,9 +162,44 @@ export class DatasetClient< } /** - * Unlike `listItems` which returns a {@link PaginationList} with an array of individual - * dataset items, `downloadItems` returns the items serialized to the provided format. - * https://docs.apify.com/api/v2#/reference/datasets/item-collection/get-items + * Downloads dataset items in a specific format. + * + * Unlike {@link listItems} which returns a {@link PaginatedList} with an array of individual + * dataset items, this method returns the items serialized to the provided format + * (JSON, CSV, Excel, etc.) as a Buffer. Useful for exporting data for further processing. + * + * @param format - Output format: `'json'`, `'jsonl'`, `'csv'`, `'xlsx'`, `'xml'`, `'rss'`, or `'html'` + * @param options - Download and formatting options (extends all options from {@link listItems}) + * @param options.attachment - If `true`, the response will have `Content-Disposition: attachment` header. + * @param options.bom - If `true`, adds UTF-8 BOM to the beginning of the file (useful for Excel compatibility). + * @param options.delimiter - CSV delimiter character. Default is `,` (comma). + * @param options.skipHeaderRow - If `true`, CSV export will not include the header row with field names. + * @param options.xmlRoot - Name of the root XML element. Default is `'items'`. + * @param options.xmlRow - Name of the XML element for each item. Default is `'item'`. + * @param options.fields - Array of field names to include in the export. + * @param options.omit - Array of field names to exclude from the export. + * @returns Buffer containing the serialized data in the specified format + * @see https://docs.apify.com/api/v2/dataset-items-get + * + * @example + * ```javascript + * // Download as CSV with BOM for Excel compatibility + * const csvBuffer = await client.dataset('my-dataset').downloadItems('csv', { bom: true }); + * require('fs').writeFileSync('output.csv', csvBuffer); + * + * // Download as Excel with custom options + * const xlsxBuffer = await client.dataset('my-dataset').downloadItems('xlsx', { + * fields: ['url', 'title', 'price'], + * skipEmpty: true, + * limit: 1000 + * }); + * + * // Download as XML with custom element names + * const xmlBuffer = await client.dataset('my-dataset').downloadItems('xml', { + * xmlRoot: 'products', + * xmlRow: 'product' + * }); + * ``` */ async downloadItems(format: DownloadItemsFormat, options: DatasetClientDownloadItemsOptions = {}): Promise { ow(format, ow.string.oneOf(validItemFormats)); @@ -129,7 +242,36 @@ export class DatasetClient< } /** - * https://docs.apify.com/api/v2#/reference/datasets/item-collection/put-items + * Stores one or more items into the dataset. + * + * Items can be objects, strings, or arrays thereof. Each item will be stored as a separate + * record in the dataset. Objects are automatically serialized to JSON. If you provide an array, + * all items will be stored in order. This method is idempotent - calling it multiple times + * with the same data will not create duplicates, but will append items each time. + * + * @param items - A single item (object or string) or an array of items to store. + * Objects are automatically stringified to JSON. Strings are stored as-is. + * @see https://docs.apify.com/api/v2/dataset-items-post + * + * @example + * ```javascript + * // Store a single object + * await client.dataset('my-dataset').pushItems({ + * url: 'https://example.com', + * title: 'Example Page', + * extractedAt: new Date() + * }); + * + * // Store multiple items at once + * await client.dataset('my-dataset').pushItems([ + * { url: 'https://example.com', title: 'Example' }, + * { url: 'https://test.com', title: 'Test' }, + * { url: 'https://demo.com', title: 'Demo' } + * ]); + * + * // Store string items + * await client.dataset('my-dataset').pushItems(['item1', 'item2', 'item3']); + * ``` */ async pushItems(items: Data | Data[] | string | string[]): Promise { ow(items, ow.any(ow.object, ow.string, ow.array.ofType(ow.any(ow.object, ow.string)))); @@ -148,7 +290,13 @@ export class DatasetClient< } /** - * https://docs.apify.com/api/v2#tag/DatasetsStatistics/operation/dataset_statistics_get + * Gets statistical information about the dataset. + * + * Returns statistics for each field in the dataset, including information about + * data types, null counts, and value ranges. + * + * @returns Dataset statistics, or `undefined` if not available + * @see https://docs.apify.com/api/v2/dataset-statistics-get */ async getStatistics(): Promise { const requestOpts: ApifyRequestConfig = { @@ -167,16 +315,35 @@ export class DatasetClient< } /** - * Generates a URL that can be used to access dataset items. + * Generates a public URL for accessing dataset items. * * If the client has permission to access the dataset's URL signing key, - * the URL will include a signature which will allow the link to work even without authentication. + * the URL will include a cryptographic signature allowing access without authentication. + * This is useful for sharing dataset results with external services or users. + * + * @param options - URL generation options (extends all options from {@link listItems}) + * @param options.expiresInSecs - Number of seconds until the signed URL expires. If omitted, the URL never expires. + * @param options.fields - Array of field names to include in the response. + * @param options.limit - Maximum number of items to return. + * @param options.offset - Number of items to skip. + * @returns A public URL string for accessing the dataset items * - * You can optionally control how long the signed URL should be valid using the `expiresInSecs` option. - * This value sets the expiration duration in seconds from the time the URL is generated. - * If not provided, the URL will not expire. + * @example + * ```javascript + * // Create a URL that expires in 1 hour with specific fields + * const url = await client.dataset('my-dataset').createItemsPublicUrl({ + * expiresInSecs: 3600, + * fields: ['url', 'title'], + * limit: 100 + * }); + * console.log(`Share this URL: ${url}`); * - * Any other options (like `limit` or `prefix`) will be included as query parameters in the URL. + * // Create a permanent public URL for clean items only + * const url = await client.dataset('my-dataset').createItemsPublicUrl({ + * clean: true, + * skipEmpty: true + * }); + * ``` */ async createItemsPublicUrl(options: DatasetClientCreateItemsUrlOptions = {}): Promise { ow( @@ -230,6 +397,12 @@ export class DatasetClient< } } +/** + * Represents a dataset storage on the Apify platform. + * + * Datasets store structured data as a sequence of items (records). Each item is a JSON object. + * Datasets are useful for storing results from web scraping, crawling, or data processing tasks. + */ export interface Dataset { id: string; name?: string; @@ -249,6 +422,9 @@ export interface Dataset { itemsPublicUrl: string; } +/** + * Statistics about dataset usage and storage. + */ export interface DatasetStats { readCount?: number; writeCount?: number; @@ -256,12 +432,21 @@ export interface DatasetStats { storageBytes?: number; } +/** + * Options for updating a dataset. + */ export interface DatasetClientUpdateOptions { name?: string | null; title?: string; generalAccess?: STORAGE_GENERAL_ACCESS | null; } +/** + * Options for listing items from a dataset. + * + * Provides various filtering, pagination, and transformation options to customize + * the output format and content of retrieved items. + */ export interface DatasetClientListItemOptions { clean?: boolean; desc?: boolean; @@ -277,10 +462,18 @@ export interface DatasetClientListItemOptions { signature?: string; } +/** + * Options for creating a public URL to access dataset items. + * + * Extends {@link DatasetClientListItemOptions} with URL expiration control. + */ export interface DatasetClientCreateItemsUrlOptions extends DatasetClientListItemOptions { expiresInSecs?: number; } +/** + * Supported formats for downloading dataset items. + */ export enum DownloadItemsFormat { JSON = 'json', JSONL = 'jsonl', @@ -293,6 +486,11 @@ export enum DownloadItemsFormat { const validItemFormats = [...new Set(Object.values(DownloadItemsFormat).map((item) => item.toLowerCase()))]; +/** + * Options for downloading dataset items in a specific format. + * + * Extends {@link DatasetClientListItemOptions} with format-specific options. + */ export interface DatasetClientDownloadItemsOptions extends DatasetClientListItemOptions { attachment?: boolean; bom?: boolean; @@ -302,10 +500,18 @@ export interface DatasetClientDownloadItemsOptions extends DatasetClientListItem xmlRow?: string; } +/** + * Statistical information about dataset fields. + * + * Provides insights into the data structure and content of the dataset. + */ export interface DatasetStatistics { fieldStatistics: Record; } +/** + * Statistics for a single field in a dataset. + */ export interface FieldStatistics { min?: number; max?: number; diff --git a/src/resource_clients/dataset_collection.ts b/src/resource_clients/dataset_collection.ts index f239a45a..2d7fdf17 100644 --- a/src/resource_clients/dataset_collection.ts +++ b/src/resource_clients/dataset_collection.ts @@ -5,6 +5,26 @@ import { ResourceCollectionClient } from '../base/resource_collection_client'; import type { PaginatedIterator, PaginatedList, PaginationOptions } from '../utils'; import type { Dataset } from './dataset'; +/** + * Client for managing the collection of datasets in your account. + * + * Datasets store structured data results from Actor runs. This client provides methods + * to list, create, or get datasets by name. + * + * @example + * ```javascript + * const client = new ApifyClient({ token: 'my-token' }); + * const datasetsClient = client.datasets(); + * + * // List all datasets + * const { items } = await datasetsClient.list(); + * + * // Get or create a dataset by name + * const dataset = await datasetsClient.getOrCreate('my-dataset'); + * ``` + * + * @see https://docs.apify.com/platform/storage/dataset + */ export class DatasetCollectionClient extends ResourceCollectionClient { /** * @hidden @@ -17,13 +37,13 @@ export class DatasetCollectionClient extends ResourceCollectionClient { } /** - * https://docs.apify.com/api/v2#/reference/datasets/dataset-collection/get-list-of-datasets + * Lists all Datasets. * * Awaiting the return value (as you would with a Promise) will result in a single API call. The amount of fetched * items in a single API call is limited. * ```javascript * const paginatedList = await client.list(options); - *``` + * ``` * * Asynchronous iteration is also supported. This will fetch additional pages if needed until all items are * retrieved. @@ -31,6 +51,10 @@ export class DatasetCollectionClient extends ResourceCollectionClient { * ```javascript * for await (const singleItem of client.list(options)) {...} * ``` + * + * @param options - Pagination options. + * @returns A paginated iterator of Datasets. + * @see https://docs.apify.com/api/v2/datasets-get */ list(options: DatasetCollectionClientListOptions = {}): PaginatedIterator { ow( @@ -47,7 +71,12 @@ export class DatasetCollectionClient extends ResourceCollectionClient { } /** - * https://docs.apify.com/api/v2#/reference/datasets/dataset-collection/create-dataset + * Gets or creates a dataset with the specified name. + * + * @param name - Name of the dataset. If not provided, a default dataset is used. + * @param options - Additional options like schema. + * @returns The dataset object. + * @see https://docs.apify.com/api/v2/datasets-post */ async getOrCreate(name?: string, options?: DatasetCollectionClientGetOrCreateOptions): Promise { ow(name, ow.optional.string); diff --git a/src/resource_clients/key_value_store.ts b/src/resource_clients/key_value_store.ts index 7a4d20a7..9ddf0858 100644 --- a/src/resource_clients/key_value_store.ts +++ b/src/resource_clients/key_value_store.ts @@ -27,6 +27,34 @@ import { pluckData, } from '../utils'; +/** + * Client for managing a specific key-value store. + * + * Key-value stores are used to store arbitrary data records or files. Each record is identified by + * a unique key and can contain any type of data. This client provides methods to get, set, and delete + * records, list keys, and manage the store. + * + * @example + * ```javascript + * const client = new ApifyClient({ token: 'my-token' }); + * const storeClient = client.keyValueStore('my-store-id'); + * + * // Set a record + * await storeClient.setRecord({ + * key: 'OUTPUT', + * value: { foo: 'bar' }, + * contentType: 'application/json' + * }); + * + * // Get a record + * const record = await storeClient.getRecord('OUTPUT'); + * + * // List all keys + * const { items } = await storeClient.listKeys(); + * ``` + * + * @see https://docs.apify.com/platform/storage/key-value-store + */ export class KeyValueStoreClient extends ResourceClient { /** * @hidden @@ -39,14 +67,24 @@ export class KeyValueStoreClient extends ResourceClient { } /** - * https://docs.apify.com/api/v2#/reference/key-value-stores/store-object/get-store + * Gets the key-value store object from the Apify API. + * + * @returns The KeyValueStore object, or `undefined` if it does not exist + * @see https://docs.apify.com/api/v2/key-value-store-get */ async get(): Promise { return this._get({}, SMALL_TIMEOUT_MILLIS); } /** - * https://docs.apify.com/api/v2#/reference/key-value-stores/store-object/update-store + * Updates the key-value store with specified fields. + * + * @param newFields - Fields to update in the key-value store + * @param newFields.name - New name for the store + * @param newFields.title - New title for the store + * @param newFields.generalAccess - General resource access level ('FOLLOW_USER_SETTING', 'ANYONE_WITH_ID_CAN_READ' or 'RESTRICTED') + * @returns The updated KeyValueStore object + * @see https://docs.apify.com/api/v2/key-value-store-put */ async update(newFields: KeyValueClientUpdateOptions): Promise { ow(newFields, ow.object); @@ -55,14 +93,48 @@ export class KeyValueStoreClient extends ResourceClient { } /** - * https://docs.apify.com/api/v2#/reference/key-value-stores/store-object/delete-store + * Deletes the key-value store. + * + * @see https://docs.apify.com/api/v2/key-value-store-delete */ async delete(): Promise { return this._delete(SMALL_TIMEOUT_MILLIS); } /** - * https://docs.apify.com/api/v2#/reference/key-value-stores/key-collection/get-list-of-keys + * Lists all keys in the key-value store. + * + * Returns a paginated list of all record keys in the store. Use pagination parameters + * to retrieve large lists efficiently. + * + * @param options - Listing options + * @param options.limit - Maximum number of keys to return. Default is 1000. + * @param options.exclusiveStartKey - Key to start listing from (for pagination). The listing starts with the next key after this one. + * @param options.collection - Filter keys by collection name. + * @param options.prefix - Filter keys that start with this prefix. + * @returns Object containing `items` array of key metadata, pagination info (`count`, `limit`, `isTruncated`, `nextExclusiveStartKey`) + * @see https://docs.apify.com/api/v2/key-value-store-keys-get + * + * @example + * ```javascript + * // List all keys + * const { items, isTruncated } = await client.keyValueStore('my-store').listKeys(); + * items.forEach(item => console.log(`${item.key}: ${item.size} bytes`)); + * + * // List keys with prefix + * const { items } = await client.keyValueStore('my-store').listKeys({ prefix: 'user-' }); + * + * // Paginate through all keys + * let exclusiveStartKey; + * do { + * const result = await client.keyValueStore('my-store').listKeys({ + * limit: 100, + * exclusiveStartKey + * }); + * // Process result.items... + * exclusiveStartKey = result.nextExclusiveStartKey; + * } while (result.isTruncated); + * ``` */ async listKeys(options: KeyValueClientListKeysOptions = {}): Promise { ow( @@ -87,10 +159,21 @@ export class KeyValueStoreClient extends ResourceClient { } /** - * Generates a URL that can be used to access key-value store record. + * Generates a public URL for accessing a specific record in the key-value store. * * If the client has permission to access the key-value store's URL signing key, - * the URL will include a signature to verify its authenticity. + * the URL will include a cryptographic signature for authenticated access without + * requiring an API token. + * + * @param key - The record key + * @returns A public URL string for accessing the record + * + * @example + * ```javascript + * const url = await client.keyValueStore('my-store').getRecordPublicUrl('OUTPUT'); + * console.log(`Public URL: ${url}`); + * // You can now share this URL or use it in a browser + * ``` */ async getRecordPublicUrl(key: string): Promise { ow(key, ow.string.nonEmpty); @@ -108,16 +191,26 @@ export class KeyValueStoreClient extends ResourceClient { } /** - * Generates a URL that can be used to access key-value store keys. + * Generates a public URL for accessing the list of keys in the key-value store. * * If the client has permission to access the key-value store's URL signing key, - * the URL will include a signature which will allow the link to work even without authentication. + * the URL will include a cryptographic signature which allows access without authentication. * - * You can optionally control how long the signed URL should be valid using the `expiresInSecs` option. - * This value sets the expiration duration in seconds from the time the URL is generated. - * If not provided, the URL will not expire. + * @param options - URL generation options (extends all options from {@link listKeys}) + * @param options.expiresInSecs - Number of seconds until the signed URL expires. If omitted, the URL never expires. + * @param options.limit - Maximum number of keys to return. + * @param options.prefix - Filter keys by prefix. + * @returns A public URL string for accessing the keys list * - * Any other options (like `limit` or `prefix`) will be included as query parameters in the URL. + * @example + * ```javascript + * // Create a URL that expires in 1 hour + * const url = await client.keyValueStore('my-store').createKeysPublicUrl({ + * expiresInSecs: 3600, + * prefix: 'image-' + * }); + * console.log(`Share this URL: ${url}`); + * ``` */ async createKeysPublicUrl(options: KeyValueClientCreateKeysUrlOptions = {}) { ow( @@ -154,9 +247,19 @@ export class KeyValueStoreClient extends ResourceClient { /** * Tests whether a record with the given key exists in the key-value store without retrieving its value. * - * https://docs.apify.com/api/v2#/reference/key-value-stores/record/get-record - * @param key The queried record key. - * @returns `true` if the record exists, `false` if it does not. + * This is more efficient than {@link getRecord} when you only need to check for existence. + * + * @param key - The record key to check + * @returns `true` if the record exists, `false` if it does not + * @see https://docs.apify.com/api/v2/key-value-store-record-get + * + * @example + * ```javascript + * const exists = await client.keyValueStore('my-store').recordExists('OUTPUT'); + * if (exists) { + * console.log('OUTPUT record exists'); + * } + * ``` */ async recordExists(key: string): Promise { const requestOpts: Record = { @@ -182,7 +285,8 @@ export class KeyValueStoreClient extends ResourceClient { * * When the record does not exist, the function resolves to `undefined`. It does * NOT resolve to a `KeyValueStore` record with an `undefined` value. - * https://docs.apify.com/api/v2#/reference/key-value-stores/record/get-record + * + * @see https://docs.apify.com/api/v2/key-value-store-record-get */ async getRecord(key: string): Promise | undefined>; @@ -245,15 +349,51 @@ export class KeyValueStoreClient extends ResourceClient { } /** - * The value in the record can be a stream object (detected by having the `.pipe` - * and `.on` methods). However, note that in that case following redirects or - * retrying the request if it fails (for example due to rate limiting) isn't - * possible. If you want to keep that behavior, you need to collect the whole - * stream contents into a Buffer and then send the full buffer. See [this - * StackOverflow answer](https://stackoverflow.com/a/14269536/7292139) for - * an example how to do that. + * Stores a record in the key-value store. + * + * The record value can be any JSON-serializable object, a string, or a Buffer/Stream. + * The content type is automatically determined based on the value type, but can be + * overridden using the `contentType` property. + * + * **Note about streams:** If the value is a stream object (has `.pipe` and `.on` methods), + * the upload cannot be retried on failure or follow redirects. For reliable uploads, + * buffer the entire stream into memory first. * - * https://docs.apify.com/api/v2#/reference/key-value-stores/record/put-record + * @param record - The record to store + * @param record.key - Record key (unique identifier) + * @param record.value - Record value (object, string, Buffer, or Stream) + * @param record.contentType - Optional MIME type. Auto-detected if not provided: + * - Objects: `'application/json; charset=utf-8'` + * - Strings: `'text/plain; charset=utf-8'` + * - Buffers/Streams: `'application/octet-stream'` + * @param options - Storage options + * @param options.timeoutSecs - Timeout for the upload in seconds. Default varies by value size. + * @param options.doNotRetryTimeouts - If `true`, don't retry on timeout errors. Default is `false`. + * @see https://docs.apify.com/api/v2/key-value-store-record-put + * + * @example + * ```javascript + * // Store JSON object + * await client.keyValueStore('my-store').setRecord({ + * key: 'OUTPUT', + * value: { crawledUrls: 100, items: [...] } + * }); + * + * // Store text + * await client.keyValueStore('my-store').setRecord({ + * key: 'README', + * value: 'This is my readme text', + * contentType: 'text/plain' + * }); + * + * // Store binary data + * const imageBuffer = await fetchImageBuffer(); + * await client.keyValueStore('my-store').setRecord({ + * key: 'screenshot.png', + * value: imageBuffer, + * contentType: 'image/png' + * }); + * ``` */ async setRecord(record: KeyValueStoreRecord, options: KeyValueStoreRecordOptions = {}): Promise { ow( @@ -309,7 +449,15 @@ export class KeyValueStoreClient extends ResourceClient { } /** - * https://docs.apify.com/api/v2#/reference/key-value-stores/record/delete-record + * Deletes a record from the key-value store. + * + * @param key - The record key to delete + * @see https://docs.apify.com/api/v2/key-value-store-record-delete + * + * @example + * ```javascript + * await client.keyValueStore('my-store').deleteRecord('temp-data'); + * ``` */ async deleteRecord(key: string): Promise { ow(key, ow.string); @@ -323,6 +471,12 @@ export class KeyValueStoreClient extends ResourceClient { } } +/** + * Represents a Key-Value Store storage on the Apify platform. + * + * Key-value stores are used to store arbitrary data records or files. Each record is identified + * by a unique key and can contain any data - JSON objects, strings, binary files, etc. + */ export interface KeyValueStore { id: string; name?: string; @@ -339,6 +493,9 @@ export interface KeyValueStore { keysPublicUrl: string; } +/** + * Statistics about Key-Value Store usage and storage. + */ export interface KeyValueStoreStats { readCount?: number; writeCount?: number; @@ -347,12 +504,18 @@ export interface KeyValueStoreStats { storageBytes?: number; } +/** + * Options for updating a Key-Value Store. + */ export interface KeyValueClientUpdateOptions { name?: string | null; title?: string; generalAccess?: STORAGE_GENERAL_ACCESS | null; } +/** + * Options for listing keys in a Key-Value Store. + */ export interface KeyValueClientListKeysOptions { limit?: number; exclusiveStartKey?: string; @@ -361,10 +524,20 @@ export interface KeyValueClientListKeysOptions { signature?: string; } +/** + * Options for creating a public URL to list keys in a Key-Value Store. + * + * Extends {@link KeyValueClientListKeysOptions} with URL expiration control. + */ export interface KeyValueClientCreateKeysUrlOptions extends KeyValueClientListKeysOptions { expiresInSecs?: number; } +/** + * Result of listing keys in a Key-Value Store. + * + * Contains paginated list of keys with metadata and pagination information. + */ export interface KeyValueClientListKeysResult { count: number; limit: number; @@ -374,29 +547,49 @@ export interface KeyValueClientListKeysResult { items: KeyValueListItem[]; } +/** + * Metadata about a single key in a Key-Value Store. + */ export interface KeyValueListItem { key: string; size: number; recordPublicUrl: string; } +/** + * Options for retrieving a record from a Key-Value Store. + */ export interface KeyValueClientGetRecordOptions { buffer?: boolean; stream?: boolean; signature?: string; } +/** + * Represents a record (key-value pair) in a Key-Value Store. + * + * @template T - The type of the record's value + */ export interface KeyValueStoreRecord { key: string; value: T; contentType?: string; } +/** + * Options for storing a record in a Key-Value Store. + */ export interface KeyValueStoreRecordOptions { timeoutSecs?: number; doNotRetryTimeouts?: boolean; } +/** + * Helper type to determine the return type based on getRecord options. + * + * Returns Readable if stream option is true, Buffer if buffer option is true, + * otherwise returns JsonValue. + */ export type ReturnTypeFromOptions = Options['stream'] extends true ? Readable : Options['buffer'] extends true diff --git a/src/resource_clients/key_value_store_collection.ts b/src/resource_clients/key_value_store_collection.ts index 3300b18d..c2fe0670 100644 --- a/src/resource_clients/key_value_store_collection.ts +++ b/src/resource_clients/key_value_store_collection.ts @@ -5,6 +5,26 @@ import { ResourceCollectionClient } from '../base/resource_collection_client'; import type { PaginatedList, PaginationOptions } from '../utils'; import type { KeyValueStore } from './key_value_store'; +/** + * Client for managing the collection of Key-value stores in your account. + * + * Key-value stores are used to store arbitrary data records or files. This client provides + * methods to list, create, or get key-value stores by name. + * + * @example + * ```javascript + * const client = new ApifyClient({ token: 'my-token' }); + * const storesClient = client.keyValueStores(); + * + * // List all key-value stores + * const { items } = await storesClient.list(); + * + * // Get or create a key-value store by name + * const store = await storesClient.getOrCreate('my-store'); + * ``` + * + * @see https://docs.apify.com/platform/storage/key-value-store + */ export class KeyValueStoreCollectionClient extends ResourceCollectionClient { /** * @hidden @@ -17,13 +37,13 @@ export class KeyValueStoreCollectionClient extends ResourceCollectionClient { } /** - * https://docs.apify.com/api/v2#/reference/key-value-stores/store-collection/get-list-of-key-value-stores + * Lists all Key-value stores. * * Awaiting the return value (as you would with a Promise) will result in a single API call. The amount of fetched * items in a single API call is limited. * ```javascript * const paginatedList = await client.list(options); - *``` + * ``` * * Asynchronous iteration is also supported. This will fetch additional pages if needed until all items are * retrieved. @@ -31,6 +51,10 @@ export class KeyValueStoreCollectionClient extends ResourceCollectionClient { * ```javascript * for await (const singleItem of client.list(options)) {...} * ``` + * + * @param options - Pagination options. + * @returns A paginated iterator of Key-value stores. + * @see https://docs.apify.com/api/v2/key-value-stores-get */ list( options: KeyValueStoreCollectionClientListOptions = {}, @@ -49,7 +73,12 @@ export class KeyValueStoreCollectionClient extends ResourceCollectionClient { } /** - * https://docs.apify.com/api/v2#/reference/key-value-stores/store-collection/create-key-value-store + * Gets or creates a key-value store with the specified name. + * + * @param name - Name of the key-value store. If not provided, a default store is used. + * @param options - Additional options like schema. + * @returns The key-value store object. + * @see https://docs.apify.com/api/v2/key-value-stores-post */ async getOrCreate( name?: string, diff --git a/src/resource_clients/log.ts b/src/resource_clients/log.ts index c77b43bb..68905673 100644 --- a/src/resource_clients/log.ts +++ b/src/resource_clients/log.ts @@ -12,6 +12,28 @@ import { ResourceClient } from '../base/resource_client'; import type { ApifyRequestConfig } from '../http_client'; import { cast, catchNotFoundOrThrow } from '../utils'; +/** + * Client for accessing Actor run or build logs. + * + * Provides methods to retrieve logs as text or stream them in real-time. Logs can be accessed + * for both running and finished Actor runs and builds. + * + * @example + * ```javascript + * const client = new ApifyClient({ token: 'my-token' }); + * const runClient = client.run('my-run-id'); + * + * // Get the log content + * const log = await runClient.log().get(); + * console.log(log); + * + * // Stream the log in real-time + * const stream = await runClient.log().stream(); + * stream.on('line', (line) => console.log(line)); + * ``` + * + * @see https://docs.apify.com/platform/actors/running/runs-and-builds#logging + */ export class LogClient extends ResourceClient { /** * @hidden @@ -24,7 +46,12 @@ export class LogClient extends ResourceClient { } /** - * https://docs.apify.com/api/v2#/reference/logs/log/get-log + * Retrieves the log as a string. + * + * @param options - Log retrieval options. + * @param options.raw - If `true`, returns raw log content without any processing. Default is `false`. + * @returns The log content as a string, or `undefined` if it does not exist. + * @see https://docs.apify.com/api/v2/log-get */ async get(options: LogOptions = {}): Promise { const requestOpts: ApifyRequestConfig = { @@ -44,8 +71,12 @@ export class LogClient extends ResourceClient { } /** - * Gets the log in a Readable stream format. Only works in Node.js. - * https://docs.apify.com/api/v2#/reference/logs/log/get-log + * Retrieves the log as a Readable stream. Only works in Node.js. + * + * @param options - Log retrieval options. + * @param options.raw - If `true`, returns raw log content without any processing. Default is `false`. + * @returns The log content as a Readable stream, or `undefined` if it does not exist. + * @see https://docs.apify.com/api/v2/log-get */ async stream(options: LogOptions = {}): Promise { const params = { diff --git a/src/resource_clients/request_queue.ts b/src/resource_clients/request_queue.ts index 7cec8771..fccb7e8c 100644 --- a/src/resource_clients/request_queue.ts +++ b/src/resource_clients/request_queue.ts @@ -24,6 +24,36 @@ const DEFAULT_MIN_DELAY_BETWEEN_UNPROCESSED_REQUESTS_RETRIES_MILLIS = 500; const DEFAULT_REQUEST_QUEUE_REQUEST_PAGE_LIMIT = 1000; const SAFETY_BUFFER_PERCENT = 0.01 / 100; // 0.01% +/** + * Client for managing a specific Request queue. + * + * Request queues store URLs to be crawled and their metadata. Each request in the queue has a unique ID + * and can be in various states (pending, handled). This client provides methods to add, get, update, + * and delete requests, as well as manage the queue itself. + * + * @example + * ```javascript + * const client = new ApifyClient({ token: 'my-token' }); + * const queueClient = client.requestQueue('my-queue-id'); + * + * // Add a request to the queue + * await queueClient.addRequest({ + * url: 'https://example.com', + * uniqueKey: 'example-com' + * }); + * + * // Get the next request from the queue + * const request = await queueClient.listHead(); + * + * // Mark request as handled + * await queueClient.updateRequest({ + * id: request.id, + * handledAt: new Date().toISOString() + * }); + * ``` + * + * @see https://docs.apify.com/platform/storage/request-queue + */ export class RequestQueueClient extends ResourceClient { private clientKey?: string; @@ -43,14 +73,21 @@ export class RequestQueueClient extends ResourceClient { } /** - * https://docs.apify.com/api/v2#/reference/request-queues/queue/get-request-queue + * Gets the Request queue object from the Apify API. + * + * @returns The RequestQueue object, or `undefined` if it does not exist + * @see https://docs.apify.com/api/v2/request-queue-get */ async get(): Promise { return this._get({}, SMALL_TIMEOUT_MILLIS); } /** - * https://docs.apify.com/api/v2#/reference/request-queues/queue/update-request-queue + * Updates the Request queue with specified fields. + * + * @param newFields - Fields to update in the Request queue + * @returns The updated RequestQueue object + * @see https://docs.apify.com/api/v2/request-queue-put */ async update(newFields: RequestQueueClientUpdateOptions): Promise { ow(newFields, ow.object); @@ -59,14 +96,23 @@ export class RequestQueueClient extends ResourceClient { } /** - * https://docs.apify.com/api/v2#/reference/request-queues/queue/delete-request-queue + * Deletes the Request queue. + * + * @see https://docs.apify.com/api/v2/request-queue-delete */ async delete(): Promise { return this._delete(SMALL_TIMEOUT_MILLIS); } /** - * https://docs.apify.com/api/v2#/reference/request-queues/queue-head/get-head + * Lists requests from the beginning of the queue (head). + * + * Returns the first N requests from the queue without locking them. This is useful for + * inspecting what requests are waiting to be processed. + * + * @param options - Options for listing (e.g., limit) + * @returns List of requests from the queue head + * @see https://docs.apify.com/api/v2/request-queue-head-get */ async listHead(options: RequestQueueClientListHeadOptions = {}): Promise { ow( @@ -90,7 +136,36 @@ export class RequestQueueClient extends ResourceClient { } /** - * https://docs.apify.com/api/v2#/reference/request-queues/queue-head-with-locks/get-head-and-lock + * Gets and locks the next requests from the queue head for processing. + * + * This method retrieves requests from the beginning of the queue and locks them for + * the specified duration to prevent other clients from processing them simultaneously. + * This is the primary method used by distributed web crawlers to coordinate work across + * multiple workers. Locked requests won't be returned to other clients until the lock expires + * or is explicitly released using {@link deleteRequestLock}. + * + * @param options - Lock configuration + * @param options.lockSecs - **Required.** Duration in seconds to lock the requests. After this time, the locks expire and requests can be retrieved by other clients. + * @param options.limit - Maximum number of requests to return. Default is 25. + * @returns Object containing `items` (locked requests), `queueModifiedAt`, `hadMultipleClients`, and lock information + * @see https://docs.apify.com/api/v2/request-queue-head-lock-post + * + * @example + * ```javascript + * // Get and lock up to 10 requests for 60 seconds + * const { items, lockSecs } = await client.requestQueue('my-queue').listAndLockHead({ + * lockSecs: 60, + * limit: 10 + * }); + * + * // Process each locked request + * for (const request of items) { + * console.log(`Processing: ${request.url}`); + * // ... process request ... + * // Delete lock after successful processing + * await client.requestQueue('my-queue').deleteRequestLock(request.id); + * } + * ``` */ async listAndLockHead( options: RequestQueueClientListAndLockHeadOptions, @@ -118,7 +193,42 @@ export class RequestQueueClient extends ResourceClient { } /** - * https://docs.apify.com/api/v2#/reference/request-queues/request-collection/add-request + * Adds a single request to the queue. + * + * If a request with the same `uniqueKey` already exists, the method will return information + * about the existing request without adding a duplicate. The `uniqueKey` is used for + * deduplication - typically it's the URL, but you can use any string to identify the request. + * + * @param request - The request object to add (excluding `id`, which is assigned by the API) + * @param request.url - URL to be crawled + * @param request.uniqueKey - Unique identifier for request deduplication. If not provided, defaults to `url`. + * @param request.method - HTTP method. Default is `'GET'`. + * @param request.userData - Custom user data (arbitrary JSON object) associated with the request. + * @param request.headers - HTTP headers to use for the request. + * @param request.payload - HTTP payload for POST/PUT requests (string). + * @param options - Additional options + * @param options.forefront - If `true`, adds the request to the beginning of the queue. Default is `false` (adds to the end). + * @returns Object with `requestId`, `wasAlreadyPresent`, and `wasAlreadyHandled` flags + * @see https://docs.apify.com/api/v2/request-queue-requests-post + * + * @example + * ```javascript + * const result = await client.requestQueue('my-queue').addRequest({ + * url: 'https://example.com', + * uniqueKey: 'example-page', + * method: 'GET', + * userData: { label: 'START', depth: 0 } + * }); + * console.log(`Request ID: ${result.requestId}`); + * console.log(`Already present: ${result.wasAlreadyPresent}`); + * console.log(`Already handled: ${result.wasAlreadyHandled}`); + * + * // Add urgent request to the front of the queue + * await client.requestQueue('my-queue').addRequest( + * { url: 'https://priority.com', uniqueKey: 'priority-page' }, + * { forefront: true } + * ); + * ``` */ async addRequest( request: Omit, @@ -153,7 +263,7 @@ export class RequestQueueClient extends ResourceClient { } /** - * Writes requests to request queue in batch. + * Writes requests to Request queue in batch. * * @private */ @@ -261,7 +371,41 @@ export class RequestQueueClient extends ResourceClient { } /** - * https://docs.apify.com/api/v2#/reference/request-queues/batch-request-operations/add-requests + * Adds multiple requests to the queue in a single operation. + * + * This is significantly more efficient than calling {@link addRequest} multiple times, especially + * for large batches. The method automatically handles batching (max 25 requests per API call), + * retries on rate limiting, and parallel processing. Requests are sent in chunks respecting the + * API payload size limit, and any unprocessed requests due to rate limits are automatically + * retried with exponential backoff. + * + * @param requests - Array of request objects to add (excluding `id` fields) + * @param options - Batch operation configuration + * @param options.forefront - If `true`, adds all requests to the beginning of the queue. Default is `false`. + * @param options.maxUnprocessedRequestsRetries - Maximum number of retry attempts for rate-limited requests. Default is 3. + * @param options.maxParallel - Maximum number of parallel batch API calls. Default is 5. + * @param options.minDelayBetweenUnprocessedRequestsRetriesMillis - Minimum delay before retrying rate-limited requests. Default is 500ms. + * @returns Object with `processedRequests` (successfully added) and `unprocessedRequests` (failed after all retries) + * @see https://docs.apify.com/api/v2/request-queue-requests-batch-post + * + * @example + * ```javascript + * // Add a batch of URLs to crawl + * const requests = [ + * { url: 'https://example.com', uniqueKey: 'page1', userData: { depth: 1 } }, + * { url: 'https://example.com/2', uniqueKey: 'page2', userData: { depth: 1 } }, + * { url: 'https://example.com/3', uniqueKey: 'page3', userData: { depth: 1 } } + * ]; + * const result = await client.requestQueue('my-queue').batchAddRequests(requests); + * console.log(`Successfully added: ${result.processedRequests.length}`); + * console.log(`Failed: ${result.unprocessedRequests.length}`); + * + * // Batch add with custom retry settings + * const result = await client.requestQueue('my-queue').batchAddRequests( + * requests, + * { maxUnprocessedRequestsRetries: 5, maxParallel: 10 } + * ); + * ``` */ async batchAddRequests( requests: Omit[], @@ -325,7 +469,13 @@ export class RequestQueueClient extends ResourceClient { } /** - * https://docs.apify.com/api/v2#/reference/request-queues/batch-request-operations/delete-requests + * Deletes multiple requests from the queue in a single operation. + * + * Requests can be identified by either their ID or unique key. + * + * @param requests - Array of requests to delete (by id or uniqueKey) + * @returns Result containing processed and unprocessed requests + * @see https://docs.apify.com/api/v2/request-queue-requests-batch-delete */ async batchDeleteRequests( requests: RequestQueueClientRequestToDelete[], @@ -354,7 +504,11 @@ export class RequestQueueClient extends ResourceClient { } /** - * https://docs.apify.com/api/v2#/reference/request-queues/request/get-request + * Gets a specific request from the queue by its ID. + * + * @param id - Request ID + * @returns The request object, or `undefined` if not found + * @see https://docs.apify.com/api/v2/request-queue-request-get */ async getRequest(id: string): Promise { ow(id, ow.string); @@ -375,7 +529,12 @@ export class RequestQueueClient extends ResourceClient { } /** - * https://docs.apify.com/api/v2#/reference/request-queues/request/update-request + * Updates a request in the queue. + * + * @param request - The updated request object (must include id) + * @param options - Update options such as whether to move to front + * @returns Information about the updated request + * @see https://docs.apify.com/api/v2/request-queue-request-put */ async updateRequest( request: RequestQueueClientRequestSchema, @@ -409,6 +568,11 @@ export class RequestQueueClient extends ResourceClient { return cast(parseDateFields(pluckData(response.data))); } + /** + * Deletes a specific request from the queue. + * + * @param id - Request ID + */ async deleteRequest(id: string): Promise { ow(id, ow.string); @@ -423,7 +587,28 @@ export class RequestQueueClient extends ResourceClient { } /** - * https://docs.apify.com/api/v2#/reference/request-queues/request-lock/prolong-request-lock + * Prolongs the lock on a request to prevent it from being returned to other clients. + * + * This is useful when processing a request takes longer than expected and you need + * to extend the lock duration to prevent other workers from picking it up. The lock + * expiration time is reset to the current time plus the specified duration. + * + * @param id - Request ID (obtained from {@link listAndLockHead} or {@link getRequest}) + * @param options - Lock extension options + * @param options.lockSecs - **Required.** New lock duration in seconds from now. + * @param options.forefront - If `true`, moves the request to the beginning of the queue when the lock expires. Default is `false`. + * @returns Object with new `lockExpiresAt` timestamp + * @see https://docs.apify.com/api/v2/request-queue-request-lock-put + * + * @example + * ```javascript + * // Lock request for initial processing + * const { items } = await client.requestQueue('my-queue').listAndLockHead({ lockSecs: 60, limit: 1 }); + * const request = items[0]; + * + * // Processing takes longer than expected, extend the lock + * await client.requestQueue('my-queue').prolongRequestLock(request.id, { lockSecs: 120 }); + * ``` */ async prolongRequestLock( id: string, @@ -453,7 +638,14 @@ export class RequestQueueClient extends ResourceClient { } /** - * https://docs.apify.com/api/v2#/reference/request-queues/request-lock/delete-request-lock + * Releases the lock on a request, allowing other clients to process it. + * + * This should be called after successfully processing a request or when you decide + * not to process it. + * + * @param id - Request ID + * @param options - Options such as whether to move to front + * @see https://docs.apify.com/api/v2/request-queue-request-lock-delete */ async deleteRequestLock(id: string, options: RequestQueueClientDeleteRequestLockOptions = {}): Promise { ow(id, ow.string); @@ -476,7 +668,14 @@ export class RequestQueueClient extends ResourceClient { } /** - * https://docs.apify.com/api/v2#/reference/request-queues/request-collection/list-requests + * Lists all requests in the queue. + * + * Returns a paginated list of all requests, allowing you to iterate through the entire + * queue contents. + * + * @param options - Pagination options + * @returns List of requests with pagination information + * @see https://docs.apify.com/api/v2/request-queue-requests-get */ async listRequests( options: RequestQueueClientListRequestsOptions = {}, @@ -504,7 +703,13 @@ export class RequestQueueClient extends ResourceClient { } /** - * https://docs.apify.com/api/v2/request-queue-requests-unlock-post + * Unlocks all requests locked by this client. + * + * This is useful for releasing all locks at once, for example when shutting down + * a crawler gracefully. + * + * @returns Number of requests that were unlocked + * @see https://docs.apify.com/api/v2/request-queue-requests-unlock-post */ async unlockRequests(): Promise { const response = await this.httpClient.call({ @@ -520,12 +725,21 @@ export class RequestQueueClient extends ResourceClient { } /** - * https://docs.apify.com/api/v2#/reference/request-queues/request-collection/list-requests + * Returns an async iterable for paginating through all requests in the queue. + * + * This allows you to efficiently process all requests using a for-await-of loop, + * automatically handling pagination behind the scenes. + * + * @param options - Pagination options + * @returns An async iterable of request pages + * @see https://docs.apify.com/api/v2/request-queue-requests-get * - * Usage: - * for await (const { items } of client.paginateRequests({ limit: 10 })) { - * items.forEach((request) => console.log(request)); + * @example + * ```javascript + * for await (const { items } of client.requestQueue('my-queue').paginateRequests({ limit: 100 })) { + * items.forEach((request) => console.log(request.url)); * } + * ``` */ paginateRequests( options: RequestQueueClientPaginateRequestsOptions = {}, @@ -548,11 +762,20 @@ export class RequestQueueClient extends ResourceClient { } } +/** + * User-specific options for RequestQueueClient. + */ export interface RequestQueueUserOptions { clientKey?: string; timeoutSecs?: number; } +/** + * Represents a Request Queue storage on the Apify platform. + * + * Request queues store URLs (requests) to be processed by web crawlers. They provide + * automatic deduplication, request locking for parallel processing, and persistence. + */ export interface RequestQueue { id: string; name?: string; @@ -572,6 +795,9 @@ export interface RequestQueue { generalAccess?: STORAGE_GENERAL_ACCESS | null; } +/** + * Statistics about Request Queue usage and storage. + */ export interface RequestQueueStats { readCount?: number; writeCount?: number; @@ -580,16 +806,25 @@ export interface RequestQueueStats { storageBytes?: number; } +/** + * Options for updating a Request Queue. + */ export interface RequestQueueClientUpdateOptions { name?: string | null; title?: string; generalAccess?: STORAGE_GENERAL_ACCESS | null; } +/** + * Options for listing requests from the queue head. + */ export interface RequestQueueClientListHeadOptions { limit?: number; } +/** + * Result of listing requests from the queue head. + */ export interface RequestQueueClientListHeadResult { limit: number; queueModifiedAt: Date; @@ -597,34 +832,54 @@ export interface RequestQueueClientListHeadResult { items: RequestQueueClientListItem[]; } +/** + * Options for listing all requests in the queue. + */ export interface RequestQueueClientListRequestsOptions { limit?: number; exclusiveStartId?: string; } +/** + * Options for paginating through requests in the queue. + */ export interface RequestQueueClientPaginateRequestsOptions { limit?: number; maxPageLimit?: number; exclusiveStartId?: string; } +/** + * Result of listing all requests in the queue. + */ export interface RequestQueueClientListRequestsResult { limit: number; exclusiveStartId?: string; items: RequestQueueClientRequestSchema[]; } +/** + * Options for listing and locking requests from the queue head. + */ export interface RequestQueueClientListAndLockHeadOptions { lockSecs: number; limit?: number; } +/** + * Result of listing and locking requests from the queue head. + * + * Extends {@link RequestQueueClientListHeadResult} with lock information. + */ export interface RequestQueueClientListAndLockHeadResult extends RequestQueueClientListHeadResult { lockSecs: number; queueHasLockedRequests: boolean; clientKey: string; } +/** + * Simplified request information used in list results. + */ export interface RequestQueueClientListItem { id: string; retryCount: number; @@ -658,6 +913,11 @@ export interface RequestQueueClientBatchAddRequestWithRetriesOptions { minDelayBetweenUnprocessedRequestsRetriesMillis?: number; } +/** + * Complete schema for a request in the queue. + * + * Represents a URL to be crawled along with its metadata, retry information, and custom data. + */ export interface RequestQueueClientRequestSchema { id: string; uniqueKey: string; @@ -673,6 +933,9 @@ export interface RequestQueueClientRequestSchema { loadedUrl?: string; } +/** + * Result of adding a request to the queue. + */ export interface RequestQueueClientAddRequestResult { requestId: string; wasAlreadyPresent: boolean; @@ -696,6 +959,11 @@ export interface RequestQueueClientUnlockRequestsResult { unlockedCount: number; } +/** + * Result of a batch operation on requests. + * + * Contains lists of successfully processed and unprocessed requests. + */ export interface RequestQueueClientBatchRequestsOperationResult { processedRequests: ProcessedRequest[]; unprocessedRequests: UnprocessedRequest[]; @@ -707,6 +975,9 @@ export type RequestQueueClientRequestToDelete = export type RequestQueueClientGetRequestResult = Omit; +/** + * HTTP methods supported by Request Queue requests. + */ export type AllowedHttpMethods = 'GET' | 'HEAD' | 'POST' | 'PUT' | 'DELETE' | 'TRACE' | 'OPTIONS' | 'CONNECT' | 'PATCH'; export type RequestQueueRequestsAsyncIterable = AsyncIterable; diff --git a/src/resource_clients/request_queue_collection.ts b/src/resource_clients/request_queue_collection.ts index 1076f1d0..9bd422bc 100644 --- a/src/resource_clients/request_queue_collection.ts +++ b/src/resource_clients/request_queue_collection.ts @@ -5,6 +5,26 @@ import { ResourceCollectionClient } from '../base/resource_collection_client'; import type { PaginatedList, PaginationOptions } from '../utils'; import type { RequestQueue } from './request_queue'; +/** + * Client for managing the collection of Request queues in your account. + * + * Request queues store URLs to be crawled and their metadata. This client provides methods + * to list, create, or get request queues by name. + * + * @example + * ```javascript + * const client = new ApifyClient({ token: 'my-token' }); + * const queuesClient = client.requestQueues(); + * + * // List all request queues + * const { items } = await queuesClient.list(); + * + * // Get or create a request queue by name + * const queue = await queuesClient.getOrCreate('my-queue'); + * ``` + * + * @see https://docs.apify.com/platform/storage/request-queue + */ export class RequestQueueCollectionClient extends ResourceCollectionClient { /** * @hidden @@ -17,13 +37,13 @@ export class RequestQueueCollectionClient extends ResourceCollectionClient { } /** - * https://docs.apify.com/api/v2#/reference/request-queues/queue-collection/get-list-of-request-queues + * Lists all Request queues. * * Awaiting the return value (as you would with a Promise) will result in a single API call. The amount of fetched * items in a single API call is limited. * ```javascript * const paginatedList = await client.list(options); - *``` + * ``` * * Asynchronous iteration is also supported. This will fetch additional pages if needed until all items are * retrieved. @@ -31,6 +51,10 @@ export class RequestQueueCollectionClient extends ResourceCollectionClient { * ```javascript * for await (const singleItem of client.list(options)) {...} * ``` + * + * @param options - Pagination options. + * @returns A paginated iterator of Request queues. + * @see https://docs.apify.com/api/v2/request-queues-get */ list( options: RequestQueueCollectionListOptions = {}, @@ -49,7 +73,11 @@ export class RequestQueueCollectionClient extends ResourceCollectionClient { } /** - * https://docs.apify.com/api/v2#/reference/request-queues/queue-collection/create-request-queue + * Gets or creates a Request queue with the specified name. + * + * @param name - Name of the Request queue. If not provided, a default queue is used. + * @returns The Request queue object. + * @see https://docs.apify.com/api/v2/request-queues-post */ async getOrCreate(name?: string): Promise { ow(name, ow.optional.string); diff --git a/src/resource_clients/run.ts b/src/resource_clients/run.ts index 8883e176..cf9066db 100644 --- a/src/resource_clients/run.ts +++ b/src/resource_clients/run.ts @@ -16,6 +16,29 @@ import { RequestQueueClient } from './request_queue'; const RUN_CHARGE_IDEMPOTENCY_HEADER = 'idempotency-key'; +/** + * Client for managing a specific Actor run. + * + * Provides methods to get run details, abort, metamorph, resurrect, wait for completion, + * and access the run's dataset, key-value store, request queue, and logs. + * + * @example + * ```javascript + * const client = new ApifyClient({ token: 'my-token' }); + * const runClient = client.run('my-run-id'); + * + * // Get run details + * const run = await runClient.get(); + * + * // Wait for the run to finish + * const finishedRun = await runClient.waitForFinish(); + * + * // Access the run's dataset + * const { items } = await runClient.dataset().listItems(); + * ``` + * + * @see https://docs.apify.com/platform/actors/running/runs-and-builds + */ export class RunClient extends ResourceClient { /** * @hidden @@ -28,7 +51,22 @@ export class RunClient extends ResourceClient { } /** - * https://docs.apify.com/api/v2#/reference/actor-runs/run-object/get-run + * Gets the Actor run object from the Apify API. + * + * @param options - Get options + * @param options.waitForFinish - Maximum time to wait (in seconds, max 60s) for the run to finish on the API side before returning. Default is 0 (returns immediately). + * @returns The ActorRun object, or `undefined` if it does not exist + * @see https://docs.apify.com/api/v2/actor-run-get + * + * @example + * ```javascript + * // Get run status immediately + * const run = await client.run('run-id').get(); + * console.log(`Status: ${run.status}`); + * + * // Wait up to 60 seconds for run to finish + * const run = await client.run('run-id').get({ waitForFinish: 60 }); + * ``` */ async get(options: RunGetOptions = {}): Promise { ow( @@ -42,7 +80,21 @@ export class RunClient extends ResourceClient { } /** - * https://docs.apify.com/api/v2#/reference/actor-runs/abort-run/abort-run + * Aborts the Actor run. + * + * @param options - Abort options + * @param options.gracefully - If `true`, the Actor run will abort gracefully - it can send status messages and perform cleanup. Default is `false` (immediate abort). + * @returns The updated ActorRun object with `ABORTING` or `ABORTED` status + * @see https://docs.apify.com/api/v2/actor-run-abort-post + * + * @example + * ```javascript + * // Abort immediately + * await client.run('run-id').abort(); + * + * // Abort gracefully (allows cleanup) + * await client.run('run-id').abort({ gracefully: true }); + * ``` */ async abort(options: RunAbortOptions = {}): Promise { ow( @@ -62,14 +114,38 @@ export class RunClient extends ResourceClient { } /** - * https://docs.apify.com/api/v2#/reference/actor-runs/delete-run/delete-run + * Deletes the Actor run. + * + * @see https://docs.apify.com/api/v2/actor-run-delete */ async delete(): Promise { return this._delete(); } /** - * https://docs.apify.com/api/v2#/reference/actor-runs/metamorph-run/metamorph-run + * Transforms the Actor run into a run of another Actor (metamorph). + * + * This operation preserves the run ID, storages (dataset, key-value store, request queue), + * and resource allocation. The run effectively becomes a run of the target Actor with new input. + * This is useful for chaining Actor executions or implementing complex workflows. + * + * @param targetActorId - ID or username/name of the target Actor + * @param input - Input for the target Actor. Can be any JSON-serializable value. + * @param options - Metamorph options + * @param options.build - Tag or number of the target Actor's build to run. Default is the target Actor's default build. + * @param options.contentType - Content type of the input. If specified, input must be a string or Buffer. + * @returns The metamorphed ActorRun object (same ID, but now running the target Actor) + * @see https://docs.apify.com/api/v2/actor-run-metamorph-post + * + * @example + * ```javascript + * // Transform current run into another Actor + * const metamorphedRun = await client.run('original-run-id').metamorph( + * 'target-actor-id', + * { url: 'https://example.com' } + * ); + * console.log(`Run ${metamorphedRun.id} is now running ${metamorphedRun.actId}`); + * ``` */ async metamorph(targetActorId: string, input: unknown, options: RunMetamorphOptions = {}): Promise { ow(targetActorId, ow.string); @@ -112,7 +188,19 @@ export class RunClient extends ResourceClient { } /** - * https://docs.apify.com/api/v2#/reference/actor-runs/reboot-run/reboot-run + * Reboots the Actor run. + * + * Rebooting restarts the Actor's Docker container while preserving the run ID and storages. + * This can be useful to recover from certain errors or to force the Actor to restart + * with a fresh environment. + * + * @returns The updated ActorRun object + * @see https://docs.apify.com/api/v2/actor-run-reboot-post + * + * @example + * ```javascript + * const run = await client.run('run-id').reboot(); + * ``` */ async reboot(): Promise { const request: AxiosRequestConfig = { @@ -124,6 +212,23 @@ export class RunClient extends ResourceClient { return cast(parseDateFields(pluckData(response.data))); } + /** + * Updates the Actor run with specified fields. + * + * @param newFields - Fields to update + * @param newFields.statusMessage - Custom status message to display (e.g., "Processing page 10/100") + * @param newFields.isStatusMessageTerminal - If `true`, the status message is final and won't be overwritten. Default is `false`. + * @param newFields.generalAccess - General resource access level ('FOLLOW_USER_SETTING', 'ANYONE_WITH_ID_CAN_READ' or 'RESTRICTED') + * @returns The updated ActorRun object + * + * @example + * ```javascript + * // Set a status message + * await client.run('run-id').update({ + * statusMessage: 'Processing items: 50/100' + * }); + * ``` + */ async update(newFields: RunUpdateOptions): Promise { ow(newFields, ow.object); @@ -131,7 +236,27 @@ export class RunClient extends ResourceClient { } /** - * https://docs.apify.com/api/v2#/reference/actor-runs/resurrect-run/resurrect-run + * Resurrects a finished Actor run, starting it again with the same settings. + * + * This creates a new run with the same configuration as the original run. The original + * run's storages (dataset, key-value store, request queue) are preserved and reused. + * + * @param options - Resurrection options (override original run settings) + * @param options.build - Tag or number of the build to use. If not provided, uses the original run's build. + * @param options.memory - Memory in megabytes. If not provided, uses the original run's memory. + * @param options.timeout - Timeout in seconds. If not provided, uses the original run's timeout. + * @param options.maxItems - Maximum number of dataset items (pay-per-result Actors). + * @param options.maxTotalChargeUsd - Maximum cost in USD (pay-per-event Actors). + * @param options.restartOnError - Whether to restart on error. + * @returns The new (resurrected) ActorRun object + * @see https://docs.apify.com/api/v2/post-resurrect-run + * + * @example + * ```javascript + * // Resurrect a failed run with more memory + * const newRun = await client.run('failed-run-id').resurrect({ memory: 2048 }); + * console.log(`New run started: ${newRun.id}`); + * ``` */ async resurrect(options: RunResurrectOptions = {}): Promise { ow( @@ -156,7 +281,14 @@ export class RunClient extends ResourceClient { } /** - * https://docs.apify.com/api/v2#/reference/actor-runs/charge-events-in-run + * Charges the Actor run for a specific event. + * + * @param options - Charge options including event name and count. + * @param options.eventName - **Required.** Name of the event to charge for. + * @param options.count - Number of times to charge the event. Default is 1. + * @param options.idempotencyKey - Optional key to ensure the charge is not duplicated. If not provided, one is auto-generated. + * @returns Empty response object. + * @see https://docs.apify.com/api/v2/post-charge-run */ async charge(options: RunChargeOptions): Promise>> { ow( @@ -190,16 +322,32 @@ export class RunClient extends ResourceClient { } /** - * Returns a promise that resolves with the finished Run object when the provided actor run finishes - * or with the unfinished Run object when the `waitSecs` timeout lapses. The promise is NOT rejected - * based on run status. You can inspect the `status` property of the Run object to find out its status. + * Waits for the Actor run to finish and returns the finished Run object. + * + * The promise resolves when the run reaches a terminal state (`SUCCEEDED`, `FAILED`, `ABORTED`, or `TIMED-OUT`). + * If `waitSecs` is provided and the timeout is reached, the promise resolves with the unfinished + * Run object (status will be `RUNNING` or `READY`). The promise is NOT rejected based on run status. * - * The difference between this function and the `waitForFinish` parameter of the `get` method - * is the fact that this function can wait indefinitely. Its use is preferable to the - * `waitForFinish` parameter alone, which it uses internally. + * Unlike the `waitForFinish` parameter in {@link get}, this method can wait indefinitely + * by polling the run status. It uses the `waitForFinish` parameter internally (max 60s per call) + * and continuously polls until the run finishes or the timeout is reached. * - * This is useful when you need to chain actor executions. Similar effect can be achieved - * by using webhooks, so be sure to review which technique fits your use-case better. + * @param options - Wait options + * @param options.waitSecs - Maximum time to wait for the run to finish, in seconds. If the limit is reached, the returned promise resolves to a run object that will have status `READY` or `RUNNING`. If omitted, waits indefinitely. + * @returns The ActorRun object (finished or still running if timeout was reached) + * + * @example + * ```javascript + * // Wait indefinitely for run to finish + * const run = await client.run('run-id').waitForFinish(); + * console.log(`Run finished with status: ${run.status}`); + * + * // Wait up to 5 minutes + * const run = await client.run('run-id').waitForFinish({ waitSecs: 300 }); + * if (run.status === 'SUCCEEDED') { + * console.log('Run succeeded!'); + * } + * ``` */ async waitForFinish(options: RunWaitForFinishOptions = {}): Promise { ow( @@ -213,10 +361,16 @@ export class RunClient extends ResourceClient { } /** - * https://docs.apify.com/api/v2#/reference/actor-runs/run-object-and-its-storages + * Returns a client for the default dataset of this Actor run. * - * This also works through `actorClient.lastRun().dataset()`. - * https://docs.apify.com/api/v2#/reference/actors/last-run-object-and-its-storages + * @returns A client for accessing the run's default dataset + * @see https://docs.apify.com/api/v2/actor-run-get + * + * @example + * ```javascript + * // Access run's dataset + * const { items } = await client.run('run-id').dataset().listItems(); + * ``` */ dataset(): DatasetClient { return new DatasetClient( @@ -227,10 +381,16 @@ export class RunClient extends ResourceClient { } /** - * https://docs.apify.com/api/v2#/reference/actor-runs/run-object-and-its-storages + * Returns a client for the default key-value store of this Actor run. + * + * @returns A client for accessing the run's default key-value store + * @see https://docs.apify.com/api/v2/actor-run-get * - * This also works through `actorClient.lastRun().keyValueStore()`. - * https://docs.apify.com/api/v2#/reference/actors/last-run-object-and-its-storages + * @example + * ```javascript + * // Access run's key-value store + * const output = await client.run('run-id').keyValueStore().getRecord('OUTPUT'); + * ``` */ keyValueStore(): KeyValueStoreClient { return new KeyValueStoreClient( @@ -241,10 +401,16 @@ export class RunClient extends ResourceClient { } /** - * https://docs.apify.com/api/v2#/reference/actor-runs/run-object-and-its-storages + * Returns a client for the default Request queue of this Actor run. * - * This also works through `actorClient.lastRun().requestQueue()`. - * https://docs.apify.com/api/v2#/reference/actors/last-run-object-and-its-storages + * @returns A client for accessing the run's default Request queue + * @see https://docs.apify.com/api/v2/actor-run-get + * + * @example + * ```javascript + * // Access run's Request queue + * const { items } = await client.run('run-id').requestQueue().listHead(); + * ``` */ requestQueue(): RequestQueueClient { return new RequestQueueClient( @@ -255,10 +421,17 @@ export class RunClient extends ResourceClient { } /** - * https://docs.apify.com/api/v2#/reference/actor-runs/run-object-and-its-storages + * Returns a client for accessing the log of this Actor run. + * + * @returns A client for accessing the run's log + * @see https://docs.apify.com/api/v2/actor-run-get * - * This also works through `actorClient.lastRun().log()`. - * https://docs.apify.com/api/v2#/reference/actors/last-run-object-and-its-storages + * @example + * ```javascript + * // Get run log + * const log = await client.run('run-id').log().get(); + * console.log(log); + * ``` */ log(): LogClient { return new LogClient( @@ -297,29 +470,48 @@ export class RunClient extends ResourceClient { } } +/** + * Options for getting a streamed log. + */ export interface GetStreamedLogOptions { toLog?: Log | null | 'default'; fromStart?: boolean; } +/** + * Options for getting a Run. + */ export interface RunGetOptions { waitForFinish?: number; } +/** + * Options for aborting a Run. + */ export interface RunAbortOptions { gracefully?: boolean; } +/** + * Options for metamorphing a Run into another Actor. + */ export interface RunMetamorphOptions { contentType?: string; build?: string; } + +/** + * Options for updating a Run. + */ export interface RunUpdateOptions { statusMessage?: string; isStatusMessageTerminal?: boolean; generalAccess?: RUN_GENERAL_ACCESS | null; } +/** + * Options for resurrecting a finished Run. + */ export interface RunResurrectOptions { build?: string; memory?: number; @@ -329,6 +521,9 @@ export interface RunResurrectOptions { restartOnError?: boolean; } +/** + * Options for charging events in a pay-per-event Actor run. + */ export interface RunChargeOptions { /** Name of the event to charge. Must be defined in the Actor's pricing info else the API will throw. */ eventName: string; @@ -338,6 +533,9 @@ export interface RunChargeOptions { idempotencyKey?: string; } +/** + * Options for waiting for a Run to finish. + */ export interface RunWaitForFinishOptions { /** * Maximum time to wait for the run to finish, in seconds. diff --git a/src/resource_clients/run_collection.ts b/src/resource_clients/run_collection.ts index 5ad2e77d..1622dd04 100644 --- a/src/resource_clients/run_collection.ts +++ b/src/resource_clients/run_collection.ts @@ -7,6 +7,27 @@ import { ResourceCollectionClient } from '../base/resource_collection_client'; import type { PaginatedIterator, PaginationOptions } from '../utils'; import type { ActorRunListItem } from './actor'; +/** + * Client for managing the collection of Actor runs. + * + * Provides methods to list Actor runs across all Actors or for a specific Actor. + * To access an individual run, use the `run()` method on the main ApifyClient. + * + * @example + * ```javascript + * const client = new ApifyClient({ token: 'my-token' }); + * + * // List all runs + * const runsClient = client.runs(); + * const { items } = await runsClient.list(); + * + * // List runs for a specific Actor + * const actorRunsClient = client.actor('my-actor-id').runs(); + * const { items: actorRuns } = await actorRunsClient.list(); + * ``` + * + * @see https://docs.apify.com/platform/actors/running/runs-and-builds + */ export class RunCollectionClient extends ResourceCollectionClient { /** * @hidden @@ -19,13 +40,13 @@ export class RunCollectionClient extends ResourceCollectionClient { } /** - * https://docs.apify.com/api/v2#/reference/actors/run-collection/get-list-of-runs + * Lists all Actor runs. * * Awaiting the return value (as you would with a Promise) will result in a single API call. The amount of fetched * items in a single API call is limited. * ```javascript * const paginatedList = await client.list(options); - *``` + * ``` * * Asynchronous iteration is also supported. This will fetch additional pages if needed until all items are * retrieved. @@ -33,6 +54,10 @@ export class RunCollectionClient extends ResourceCollectionClient { * ```javascript * for await (const singleItem of client.list(options)) {...} * ``` + * + * @param options - Pagination and filtering options. + * @returns A paginated iterator of Actor runs. + * @see https://docs.apify.com/api/v2/actor-runs-get */ list(options: RunCollectionListOptions = {}): PaginatedIterator { ow( diff --git a/src/resource_clients/schedule.ts b/src/resource_clients/schedule.ts index 52015333..e7c4bee1 100644 --- a/src/resource_clients/schedule.ts +++ b/src/resource_clients/schedule.ts @@ -8,6 +8,29 @@ import type { Timezone } from '../timezones'; import type { DistributiveOptional } from '../utils'; import { cast, catchNotFoundOrThrow, parseDateFields, pluckData } from '../utils'; +/** + * Client for managing a specific Schedule. + * + * Schedules are used to automatically start Actors or tasks at specified times. This client provides + * methods to get, update, and delete schedules, as well as retrieve schedule logs. + * + * @example + * ```javascript + * const client = new ApifyClient({ token: 'my-token' }); + * const scheduleClient = client.schedule('my-schedule-id'); + * + * // Get schedule details + * const schedule = await scheduleClient.get(); + * + * // Update schedule + * await scheduleClient.update({ + * cronExpression: '0 12 * * *', + * isEnabled: true + * }); + * ``` + * + * @see https://docs.apify.com/platform/schedules + */ export class ScheduleClient extends ResourceClient { /** * @hidden @@ -20,14 +43,21 @@ export class ScheduleClient extends ResourceClient { } /** - * https://docs.apify.com/api/v2#/reference/schedules/schedule-object/get-schedule + * Retrieves the schedule. + * + * @returns The schedule object, or `undefined` if it does not exist. + * @see https://docs.apify.com/api/v2/schedule-get */ async get(): Promise { return this._get(); } /** - * https://docs.apify.com/api/v2#/reference/schedules/schedule-object/update-schedule + * Updates the schedule with the specified fields. + * + * @param newFields - Fields to update. + * @returns The updated schedule object. + * @see https://docs.apify.com/api/v2/schedule-put */ async update(newFields: ScheduleCreateOrUpdateData): Promise { ow(newFields, ow.object); @@ -35,14 +65,19 @@ export class ScheduleClient extends ResourceClient { } /** - * https://docs.apify.com/api/v2#/reference/schedules/schedule-object/delete-schedule + * Deletes the schedule. + * + * @see https://docs.apify.com/api/v2/schedule-delete */ async delete(): Promise { return this._delete(); } /** - * https://docs.apify.com/api/v2#/reference/schedules/schedule-log/get-schedule-log + * Retrieves the schedule's log. + * + * @returns The schedule log as a string, or `undefined` if it does not exist. + * @see https://docs.apify.com/api/v2/schedule-log-get */ async getLog(): Promise { const requestOpts: ApifyRequestConfig = { @@ -61,6 +96,11 @@ export class ScheduleClient extends ResourceClient { } } +/** + * Represents a schedule for automated Actor or Task runs. + * + * Schedules use cron expressions to define when Actors or Tasks should run automatically. + */ export interface Schedule { id: string; userId: string; @@ -81,6 +121,9 @@ export interface Schedule { }; } +/** + * Data for creating or updating a Schedule. + */ export type ScheduleCreateOrUpdateData = Partial< Pick< Schedule, @@ -90,6 +133,9 @@ export type ScheduleCreateOrUpdateData = Partial< } >; +/** + * Types of actions that can be scheduled. + */ export enum ScheduleActions { RunActor = 'RUN_ACTOR', RunActorTask = 'RUN_ACTOR_TASK', @@ -100,19 +146,31 @@ interface BaseScheduleAction { type: Type; } +/** + * Union type representing all possible scheduled actions. + */ export type ScheduleAction = ScheduleActionRunActor | ScheduleActionRunActorTask; +/** + * Scheduled action to run an Actor. + */ export interface ScheduleActionRunActor extends BaseScheduleAction { actorId: string; runInput?: ScheduledActorRunInput; runOptions?: ScheduledActorRunOptions; } +/** + * Input configuration for a scheduled Actor run. + */ export interface ScheduledActorRunInput { body: string; contentType: string; } +/** + * Run options for a scheduled Actor run. + */ export interface ScheduledActorRunOptions { build: string; timeoutSecs: number; @@ -120,6 +178,9 @@ export interface ScheduledActorRunOptions { restartOnError?: boolean; } +/** + * Scheduled action to run an Actor task. + */ export interface ScheduleActionRunActorTask extends BaseScheduleAction { actorTaskId: string; input?: string; diff --git a/src/resource_clients/schedule_collection.ts b/src/resource_clients/schedule_collection.ts index 781832e0..7b35397e 100644 --- a/src/resource_clients/schedule_collection.ts +++ b/src/resource_clients/schedule_collection.ts @@ -5,6 +5,30 @@ import { ResourceCollectionClient } from '../base/resource_collection_client'; import type { PaginatedIterator, PaginationOptions } from '../utils'; import type { Schedule, ScheduleCreateOrUpdateData } from './schedule'; +/** + * Client for managing the collection of Schedules in your account. + * + * Schedules are used to automatically start Actors or tasks at specified times. + * This client provides methods to list and create schedules. + * + * @example + * ```javascript + * const client = new ApifyClient({ token: 'my-token' }); + * const schedulesClient = client.schedules(); + * + * // List all schedules + * const { items } = await schedulesClient.list(); + * + * // Create a new schedule + * const newSchedule = await schedulesClient.create({ + * actorId: 'my-actor-id', + * cronExpression: '0 9 * * *', + * isEnabled: true + * }); + * ``` + * + * @see https://docs.apify.com/platform/schedules + */ export class ScheduleCollectionClient extends ResourceCollectionClient { /** * @hidden @@ -17,13 +41,13 @@ export class ScheduleCollectionClient extends ResourceCollectionClient { } /** - * https://docs.apify.com/api/v2#/reference/schedules/schedules-collection/get-list-of-schedules + * Lists all schedules. * * Awaiting the return value (as you would with a Promise) will result in a single API call. The amount of fetched * items in a single API call is limited. * ```javascript * const paginatedList = await client.list(options); - *``` + * ``` * * Asynchronous iteration is also supported. This will fetch additional pages if needed until all items are * retrieved. @@ -31,6 +55,10 @@ export class ScheduleCollectionClient extends ResourceCollectionClient { * ```javascript * for await (const singleItem of client.list(options)) {...} * ``` + * + * @param options - Pagination and sorting options. + * @returns A paginated iterator of schedules. + * @see https://docs.apify.com/api/v2/schedules-get */ list(options: ScheduleCollectionListOptions = {}): PaginatedIterator { ow( @@ -46,7 +74,11 @@ export class ScheduleCollectionClient extends ResourceCollectionClient { } /** - * https://docs.apify.com/api/v2#/reference/schedules/schedules-collection/create-schedule + * Creates a new schedule. + * + * @param schedule - The schedule data. + * @returns The created schedule object. + * @see https://docs.apify.com/api/v2/schedules-post */ async create(schedule?: ScheduleCreateOrUpdateData): Promise { ow(schedule, ow.optional.object); diff --git a/src/resource_clients/store_collection.ts b/src/resource_clients/store_collection.ts index cfa2f4aa..14365e68 100644 --- a/src/resource_clients/store_collection.ts +++ b/src/resource_clients/store_collection.ts @@ -5,6 +5,26 @@ import { ResourceCollectionClient } from '../base/resource_collection_client'; import type { PaginatedIterator, PaginationOptions } from '../utils'; import type { ActorStats } from './actor'; +/** + * Client for browsing Actors in the Apify Store. + * + * The Apify Store contains publicly available Actors that can be used by anyone. + * This client provides methods to search and list Actors from the Store. + * + * @example + * ```javascript + * const client = new ApifyClient(); + * const storeClient = client.store(); + * + * // Search for Actors in the Store + * const { items } = await storeClient.list({ search: 'web scraper' }); + * + * // Get details about a specific Store Actor + * const actor = await storeClient.list({ username: 'apify', actorName: 'web-scraper' }); + * ``` + * + * @see https://docs.apify.com/platform/actors/publishing + */ export class StoreCollectionClient extends ResourceCollectionClient { /** * @hidden @@ -17,13 +37,13 @@ export class StoreCollectionClient extends ResourceCollectionClient { } /** - * https://docs.apify.com/api/v2/#/reference/store/store-actors-collection/get-list-of-actors-in-store + * Lists Actors from the Apify Store. * * Awaiting the return value (as you would with a Promise) will result in a single API call. The amount of fetched * items in a single API call is limited. * ```javascript * const paginatedList = await client.list(options); - *``` + * ``` * * Asynchronous iteration is also supported. This will fetch additional pages if needed until all items are * retrieved. @@ -31,6 +51,10 @@ export class StoreCollectionClient extends ResourceCollectionClient { * ```javascript * for await (const singleItem of client.list(options)) {...} * ``` + * + * @param options - Search and pagination options. + * @returns A paginated iterator of store Actors. + * @see https://docs.apify.com/api/v2/store-actors-get */ list(options: StoreCollectionListOptions = {}): PaginatedIterator { ow( diff --git a/src/resource_clients/task.ts b/src/resource_clients/task.ts index 6ef869b5..04d832b4 100644 --- a/src/resource_clients/task.ts +++ b/src/resource_clients/task.ts @@ -13,6 +13,26 @@ import { RunClient } from './run'; import { RunCollectionClient } from './run_collection'; import { WebhookCollectionClient } from './webhook_collection'; +/** + * Client for managing a specific Actor task. + * + * Tasks are pre-configured Actor runs with saved input and options. This client provides methods + * to start, call, update, and delete tasks, as well as manage their runs and webhooks. + * + * @example + * ```javascript + * const client = new ApifyClient({ token: 'my-token' }); + * const taskClient = client.task('my-task-id'); + * + * // Start a task + * const run = await taskClient.start(); + * + * // Call a task and wait for it to finish + * const finishedRun = await taskClient.call(); + * ``` + * + * @see https://docs.apify.com/platform/actors/running/tasks + */ export class TaskClient extends ResourceClient { /** * @hidden @@ -25,14 +45,21 @@ export class TaskClient extends ResourceClient { } /** - * https://docs.apify.com/api/v2#/reference/actor-tasks/task-object/get-task + * Retrieves the Actor task. + * + * @returns The task object, or `undefined` if it does not exist. + * @see https://docs.apify.com/api/v2/actor-task-get */ async get(): Promise { return this._get(); } /** - * https://docs.apify.com/api/v2#/reference/actor-tasks/task-object/update-task + * Updates the task with the specified fields. + * + * @param newFields - Fields to update. + * @returns The updated task object. + * @see https://docs.apify.com/api/v2/actor-task-put */ async update(newFields: TaskUpdateData): Promise { ow(newFields, ow.object); @@ -41,15 +68,29 @@ export class TaskClient extends ResourceClient { } /** - * https://docs.apify.com/api/v2#/reference/actor-tasks/task-object/delete-task + * Deletes the Task. + * + * @see https://docs.apify.com/api/v2/actor-task-delete */ async delete(): Promise { return this._delete(); } /** - * Starts a task and immediately returns the Run object. - * https://docs.apify.com/api/v2#/reference/actor-tasks/run-collection/run-task + * Starts an Actor task and immediately returns the Run object. + * + * @param input - Input overrides for the task. If not provided, the task's saved input is used. + * @param options - Run options. + * @param options.build - Tag or number of the Actor build to run (e.g., `'beta'` or `'1.2.345'`). + * @param options.memory - Memory in megabytes allocated for the run. + * @param options.timeout - Timeout for the run in seconds. Zero means no timeout. + * @param options.waitForFinish - Maximum time to wait (in seconds, max 60s) for the run to finish before returning. + * @param options.webhooks - Webhooks to trigger for specific Actor run events. + * @param options.maxItems - Maximum number of dataset items (for pay-per-result Actors). + * @param options.maxTotalChargeUsd - Maximum cost in USD (for pay-per-event Actors). + * @param options.restartOnError - Whether to restart the run on error. + * @returns The Actor Run object. + * @see https://docs.apify.com/api/v2/actor-task-runs-post */ async start(input?: Dictionary, options: TaskStartOptions = {}): Promise { ow(input, ow.optional.object); @@ -100,7 +141,19 @@ export class TaskClient extends ResourceClient { /** * Starts a task and waits for it to finish before returning the Run object. * It waits indefinitely, unless the `waitSecs` option is provided. - * https://docs.apify.com/api/v2#/reference/actor-tasks/run-collection/run-task + * + * @param input - Input overrides for the task. If not provided, the task's saved input is used. + * @param options - Run and wait options. + * @param options.build - Tag or number of the Actor build to run. + * @param options.memory - Memory in megabytes allocated for the run. + * @param options.timeout - Timeout for the run in seconds. + * @param options.waitSecs - Maximum time to wait for the run to finish, in seconds. If omitted, waits indefinitely. + * @param options.webhooks - Webhooks to trigger for specific Actor run events. + * @param options.maxItems - Maximum number of dataset items (for pay-per-result Actors). + * @param options.maxTotalChargeUsd - Maximum cost in USD (for pay-per-event Actors). + * @param options.restartOnError - Whether to restart the run on error. + * @returns The Actor run object. + * @see https://docs.apify.com/api/v2/actor-task-runs-post */ async call(input?: Dictionary, options: TaskCallOptions = {}): Promise { ow(input, ow.optional.object); @@ -129,7 +182,10 @@ export class TaskClient extends ResourceClient { } /** - * https://docs.apify.com/api/v2#/reference/actor-tasks/task-input-object/get-task-input + * Retrieves the Actor task's input object. + * + * @returns The Task's input, or `undefined` if it does not exist. + * @see https://docs.apify.com/api/v2/actor-task-input-get */ async getInput(): Promise { const requestOpts: ApifyRequestConfig = { @@ -148,7 +204,11 @@ export class TaskClient extends ResourceClient { } /** - * https://docs.apify.com/api/v2#/reference/actor-tasks/task-input-object/update-task-input + * Updates the Actor task's input object. + * + * @param newFields - New input data for the task. + * @returns The updated task input. + * @see https://docs.apify.com/api/v2/actor-task-input-put */ async updateInput(newFields: Dictionary | Dictionary[]): Promise { const response = await this.httpClient.call({ @@ -162,7 +222,13 @@ export class TaskClient extends ResourceClient { } /** - * https://docs.apify.com/api/v2#/reference/actor-tasks/last-run-object-and-its-storages + * Returns a client for the last run of this task. + * + * @param options - Filter options for the last run. + * @param options.status - Filter by run status (e.g., `'SUCCEEDED'`, `'FAILED'`, `'RUNNING'`). + * @param options.origin - Filter by run origin (e.g., `'WEB'`, `'API'`, `'SCHEDULE'`). + * @returns A client for the last run. + * @see https://docs.apify.com/api/v2/actor-task-runs-last-get */ lastRun(options: TaskLastRunOptions = {}): RunClient { ow( @@ -183,7 +249,10 @@ export class TaskClient extends ResourceClient { } /** - * https://docs.apify.com/api/v2#/reference/actor-tasks/run-collection + * Returns a client for the Runs of this Task. + * + * @returns A client for the task's runs. + * @see https://docs.apify.com/api/v2/actor-task-runs-get */ runs(): RunCollectionClient { return new RunCollectionClient( @@ -194,13 +263,22 @@ export class TaskClient extends ResourceClient { } /** - * https://docs.apify.com/api/v2#/reference/actor-tasks/webhook-collection + * Returns a client for the Webhooks of this Task. + * + * @returns A client for the task's webhooks. + * @see https://docs.apify.com/api/v2/actor-task-webhooks-get */ webhooks(): WebhookCollectionClient { return new WebhookCollectionClient(this._subResourceOptions()); } } +/** + * Represents an Actor task. + * + * Tasks are saved Actor configurations with input and settings that can be executed + * repeatedly without having to specify the full input each time. + */ export interface Task { id: string; userId: string; @@ -217,10 +295,16 @@ export interface Task { actorStandby?: Partial; } +/** + * Statistics about Actor task usage. + */ export interface TaskStats { totalRuns: number; } +/** + * Configuration options for an Actor task. + */ export interface TaskOptions { build?: string; timeoutSecs?: number; @@ -228,16 +312,31 @@ export interface TaskOptions { restartOnError?: boolean; } +/** + * Fields that can be updated when modifying a Task. + */ export type TaskUpdateData = Partial< Pick >; +/** + * Options for filtering the last run of a Task. + */ export interface TaskLastRunOptions { status?: keyof typeof ACT_JOB_STATUSES; } +/** + * Options for starting a Task. + * + * Similar to {@link ActorStartOptions} but without contentType (Task input is predefined) + * and forcePermissionLevel. + */ export type TaskStartOptions = Omit; +/** + * Options for calling a Task and waiting for it to finish. + */ export interface TaskCallOptions extends Omit { waitSecs?: number; } diff --git a/src/resource_clients/task_collection.ts b/src/resource_clients/task_collection.ts index 3026f78f..2c5a9833 100644 --- a/src/resource_clients/task_collection.ts +++ b/src/resource_clients/task_collection.ts @@ -5,6 +5,30 @@ import { ResourceCollectionClient } from '../base/resource_collection_client'; import type { PaginatedIterator, PaginationOptions } from '../utils'; import type { Task, TaskUpdateData } from './task'; +/** + * Client for managing the collection of Actor tasks in your account. + * + * Tasks are pre-configured Actor runs with saved input and options. This client provides + * methods to list and create tasks. + * + * @example + * ```javascript + * const client = new ApifyClient({ token: 'my-token' }); + * const tasksClient = client.tasks(); + * + * // List all tasks + * const { items } = await tasksClient.list(); + * + * // Create a new task + * const newTask = await tasksClient.create({ + * actId: 'my-actor-id', + * name: 'my-task', + * input: { url: 'https://example.com' } + * }); + * ``` + * + * @see https://docs.apify.com/platform/actors/running/tasks + */ export class TaskCollectionClient extends ResourceCollectionClient { /** * @hidden @@ -17,18 +41,13 @@ export class TaskCollectionClient extends ResourceCollectionClient { } /** - * https://docs.apify.com/api/v2#/reference/actor-tasks/task-collection/get-list-of-tasks - * @param {object} [options] - * @param {number} [options.limit] - * @param {number} [options.offset] - * @param {boolean} [options.desc] - * @return {PaginatedIterator} + * Lists all Tasks. * * Awaiting the return value (as you would with a Promise) will result in a single API call. The amount of fetched * items in a single API call is limited. * ```javascript * const paginatedList = await client.list(options); - *``` + * ``` * * Asynchronous iteration is also supported. This will fetch additional pages if needed until all items are * retrieved. @@ -36,6 +55,10 @@ export class TaskCollectionClient extends ResourceCollectionClient { * ```javascript * for await (const singleItem of client.list(options)) {...} * ``` + * + * @param options - Pagination and sorting options. + * @returns A paginated iterator of tasks. + * @see https://docs.apify.com/api/v2/actor-tasks-get */ list(options: TaskCollectionListOptions = {}): PaginatedIterator { ow( @@ -51,7 +74,11 @@ export class TaskCollectionClient extends ResourceCollectionClient { } /** - * https://docs.apify.com/api/v2#/reference/actor-tasks/task-collection/create-task + * Creates a new task. + * + * @param task - The task data. + * @returns The created task object. + * @see https://docs.apify.com/api/v2/actor-tasks-post */ async create(task: TaskCreateData): Promise { ow(task, ow.object); diff --git a/src/resource_clients/user.ts b/src/resource_clients/user.ts index 3513a64a..ab5bb34b 100644 --- a/src/resource_clients/user.ts +++ b/src/resource_clients/user.ts @@ -4,6 +4,30 @@ import { ResourceClient } from '../base/resource_client'; import type { ApifyRequestConfig } from '../http_client'; import { cast, catchNotFoundOrThrow, parseDateFields, pluckData } from '../utils'; +/** + * Client for managing user account information. + * + * Provides methods to retrieve user details, monthly usage statistics, and account limits. + * When using an API token, you can access your own user information or public information + * about other users. + * + * @example + * ```javascript + * const client = new ApifyClient({ token: 'my-token' }); + * const userClient = client.user('my-user-id'); + * + * // Get user information + * const user = await userClient.get(); + * + * // Get monthly usage + * const usage = await userClient.monthlyUsage(); + * + * // Get account limits + * const limits = await userClient.limits(); + * ``` + * + * @see https://docs.apify.com/platform/actors/running + */ export class UserClient extends ResourceClient { /** * @hidden @@ -16,16 +40,23 @@ export class UserClient extends ResourceClient { } /** + * Retrieves the user data. + * * Depending on whether ApifyClient was created with a token, * the method will either return public or private user data. - * https://docs.apify.com/api/v2#/reference/users + * + * @returns The user object. + * @see https://docs.apify.com/api/v2/user-get */ async get(): Promise { return this._get() as Promise; } /** - * https://docs.apify.com/api/v2/#/reference/users/monthly-usage + * Retrieves the user's monthly usage data. + * + * @returns The monthly usage object, or `undefined` if it does not exist. + * @see https://docs.apify.com/api/v2/user-usage-monthly-get */ async monthlyUsage(): Promise { const requestOpts: ApifyRequestConfig = { @@ -50,7 +81,10 @@ export class UserClient extends ResourceClient { } /** - * https://docs.apify.com/api/v2/#/reference/users/account-and-usage-limits + * Retrieves the user's account and usage limits. + * + * @returns The account and usage limits object, or `undefined` if it does not exist. + * @see https://docs.apify.com/api/v2/user-limits-get */ async limits(): Promise { const requestOpts: ApifyRequestConfig = { @@ -69,7 +103,10 @@ export class UserClient extends ResourceClient { } /** - * https://docs.apify.com/api/v2/#/reference/users/account-and-usage-limits + * Updates the user's account and usage limits. + * + * @param options - The new limits to set. + * @see https://docs.apify.com/api/v2/user-limits-put */ async updateLimits(options: LimitsUpdateOptions): Promise { const requestOpts: ApifyRequestConfig = { diff --git a/src/resource_clients/webhook.ts b/src/resource_clients/webhook.ts index 80782ee7..6293e002 100644 --- a/src/resource_clients/webhook.ts +++ b/src/resource_clients/webhook.ts @@ -10,6 +10,34 @@ import { cast, catchNotFoundOrThrow, parseDateFields, pluckData } from '../utils import type { WebhookDispatch } from './webhook_dispatch'; import { WebhookDispatchCollectionClient } from './webhook_dispatch_collection'; +/** + * Client for managing a specific webhook. + * + * Webhooks allow you to receive notifications when specific events occur in your Actors or tasks. + * This client provides methods to get, update, delete, and test webhooks, as well as retrieve + * webhook dispatches. + * + * @example + * ```javascript + * const client = new ApifyClient({ token: 'my-token' }); + * const webhookClient = client.webhook('my-webhook-id'); + * + * // Get webhook details + * const webhook = await webhookClient.get(); + * + * // Update webhook + * await webhookClient.update({ + * isEnabled: true, + * eventTypes: ['ACTOR.RUN.SUCCEEDED'], + * requestUrl: 'https://example.com/webhook' + * }); + * + * // Test webhook + * await webhookClient.test(); + * ``` + * + * @see https://docs.apify.com/platform/integrations/webhooks + */ export class WebhookClient extends ResourceClient { /** * @hidden @@ -22,14 +50,21 @@ export class WebhookClient extends ResourceClient { } /** - * https://docs.apify.com/api/v2#/reference/webhooks/webhook-object/get-webhook + * Retrieves the webhook. + * + * @returns The webhook object, or `undefined` if it does not exist. + * @see https://docs.apify.com/api/v2/webhook-get */ async get(): Promise { return this._get(); } /** - * https://docs.apify.com/api/v2#/reference/webhooks/webhook-object/update-webhook + * Updates the webhook with the specified fields. + * + * @param newFields - Fields to update. + * @returns The updated webhook object. + * @see https://docs.apify.com/api/v2/webhook-put */ async update(newFields: WebhookUpdateData): Promise { ow(newFields, ow.object); @@ -38,14 +73,19 @@ export class WebhookClient extends ResourceClient { } /** - * https://docs.apify.com/api/v2#/reference/webhooks/webhook-object/delete-webhook + * Deletes the webhook. + * + * @see https://docs.apify.com/api/v2/webhook-delete */ async delete(): Promise { return this._delete(); } /** - * https://docs.apify.com/api/v2#/reference/webhooks/webhook-test/test-webhook + * Tests the webhook by dispatching a test event. + * + * @returns The webhook dispatch object, or `undefined` if the test fails. + * @see https://docs.apify.com/api/v2/webhook-test-post */ async test(): Promise { const request: ApifyRequestConfig = { @@ -65,7 +105,10 @@ export class WebhookClient extends ResourceClient { } /** - * https://docs.apify.com/api/v2#/reference/webhooks/dispatches-collection + * Returns a client for the dispatches of this webhook. + * + * @returns A client for the webhook's dispatches. + * @see https://docs.apify.com/api/v2/webhook-webhook-dispatches-get */ dispatches(): WebhookDispatchCollectionClient { return new WebhookDispatchCollectionClient( @@ -76,6 +119,12 @@ export class WebhookClient extends ResourceClient { } } +/** + * Represents a webhook for receiving notifications about Actor events. + * + * Webhooks send HTTP POST requests to specified URLs when certain events occur + * (e.g., Actor run succeeds, fails, or times out). + */ export interface Webhook { id: string; userId: string; @@ -100,6 +149,9 @@ export interface WebhookIdempotencyKey { idempotencyKey?: string; } +/** + * Data for updating a webhook. + */ export type WebhookUpdateData = Partial< Pick< Webhook, @@ -118,12 +170,21 @@ export type WebhookUpdateData = Partial< > & WebhookIdempotencyKey; +/** + * Statistics about webhook usage. + */ export interface WebhookStats { totalDispatches: number; } +/** + * Event types that can trigger webhooks. + */ export type WebhookEventType = (typeof WEBHOOK_EVENT_TYPES)[keyof typeof WEBHOOK_EVENT_TYPES]; +/** + * Condition that determines when a webhook should be triggered. + */ export type WebhookCondition = | WebhookAnyRunOfActorCondition | WebhookAnyRunOfActorTaskCondition diff --git a/src/resource_clients/webhook_collection.ts b/src/resource_clients/webhook_collection.ts index c6d666a7..1eaa6781 100644 --- a/src/resource_clients/webhook_collection.ts +++ b/src/resource_clients/webhook_collection.ts @@ -5,6 +5,29 @@ import { ResourceCollectionClient } from '../base/resource_collection_client'; import type { PaginatedIterator, PaginationOptions } from '../utils'; import type { Webhook, WebhookUpdateData } from './webhook'; +/** + * Client for managing the collection of Webhooks. + * + * Webhooks allow you to receive notifications when specific events occur in your Actors or tasks. + * This client provides methods to list and create webhooks for specific Actors or tasks. + * + * @example + * ```javascript + * const client = new ApifyClient({ token: 'my-token' }); + * + * // List webhooks for an Actor + * const actorWebhooksClient = client.actor('my-actor-id').webhooks(); + * const { items } = await actorWebhooksClient.list(); + * + * // Create a webhook + * const newWebhook = await actorWebhooksClient.create({ + * eventTypes: ['ACTOR.RUN.SUCCEEDED'], + * requestUrl: 'https://example.com/webhook' + * }); + * ``` + * + * @see https://docs.apify.com/platform/integrations/webhooks + */ export class WebhookCollectionClient extends ResourceCollectionClient { /** * @hidden @@ -17,13 +40,13 @@ export class WebhookCollectionClient extends ResourceCollectionClient { } /** - * https://docs.apify.com/api/v2#/reference/webhooks/webhook-collection/get-list-of-webhooks + * Lists all Webhooks. * * Awaiting the return value (as you would with a Promise) will result in a single API call. The amount of fetched * items in a single API call is limited. * ```javascript * const paginatedList = await client.list(options); - *``` + * ``` * * Asynchronous iteration is also supported. This will fetch additional pages if needed until all items are * retrieved. @@ -31,6 +54,10 @@ export class WebhookCollectionClient extends ResourceCollectionClient { * ```javascript * for await (const singleItem of client.list(options)) {...} * ``` + * + * @param options - Pagination and sorting options. + * @returns A paginated iterator of webhooks. + * @see https://docs.apify.com/api/v2/webhooks-get */ list( @@ -49,7 +76,11 @@ export class WebhookCollectionClient extends ResourceCollectionClient { } /** - * https://docs.apify.com/api/v2#/reference/webhooks/webhook-collection/create-webhook + * Creates a new webhook. + * + * @param webhook - The webhook data. + * @returns The created webhook object. + * @see https://docs.apify.com/api/v2/webhooks-post */ async create(webhook?: WebhookUpdateData): Promise { ow(webhook, ow.optional.object); diff --git a/src/resource_clients/webhook_dispatch.ts b/src/resource_clients/webhook_dispatch.ts index 43301de0..3246befb 100644 --- a/src/resource_clients/webhook_dispatch.ts +++ b/src/resource_clients/webhook_dispatch.ts @@ -2,6 +2,24 @@ import type { ApiClientSubResourceOptions } from '../base/api_client'; import { ResourceClient } from '../base/resource_client'; import type { Webhook, WebhookEventType } from './webhook'; +/** + * Client for managing a specific webhook dispatch. + * + * Webhook dispatches represent individual notifications sent by webhooks. This client provides + * methods to retrieve details about a specific dispatch. + * + * @example + * ```javascript + * const client = new ApifyClient({ token: 'my-token' }); + * const webhookClient = client.webhook('my-webhook-id'); + * + * // Get a specific dispatch + * const dispatchClient = webhookClient.dispatches().get('dispatch-id'); + * const dispatch = await dispatchClient.get(); + * ``` + * + * @see https://docs.apify.com/platform/integrations/webhooks + */ export class WebhookDispatchClient extends ResourceClient { /** * @hidden @@ -14,7 +32,10 @@ export class WebhookDispatchClient extends ResourceClient { } /** - * https://docs.apify.com/api/v2#/reference/webhook-dispatches/webhook-dispatch-object/get-webhook-dispatch + * Retrieves the webhook dispatch. + * + * @returns The webhook dispatch object, or `undefined` if it does not exist. + * @see https://docs.apify.com/api/v2/webhook-dispatch-get */ async get(): Promise { return this._get(); diff --git a/src/resource_clients/webhook_dispatch_collection.ts b/src/resource_clients/webhook_dispatch_collection.ts index b8115611..73823ad7 100644 --- a/src/resource_clients/webhook_dispatch_collection.ts +++ b/src/resource_clients/webhook_dispatch_collection.ts @@ -5,6 +5,24 @@ import { ResourceCollectionClient } from '../base/resource_collection_client'; import type { PaginatedIterator, PaginationOptions } from '../utils'; import type { WebhookDispatch } from './webhook_dispatch'; +/** + * Client for managing the collection of webhook dispatches. + * + * Webhook dispatches represent individual notifications sent by a webhook. This client provides + * methods to list all dispatches for a specific webhook. + * + * @example + * ```javascript + * const client = new ApifyClient({ token: 'my-token' }); + * const webhookClient = client.webhook('my-webhook-id'); + * + * // List all dispatches for this webhook + * const dispatchesClient = webhookClient.dispatches(); + * const { items } = await dispatchesClient.list(); + * ``` + * + * @see https://docs.apify.com/platform/integrations/webhooks + */ export class WebhookDispatchCollectionClient extends ResourceCollectionClient { /** * @hidden @@ -17,13 +35,13 @@ export class WebhookDispatchCollectionClient extends ResourceCollectionClient { } /** - * https://docs.apify.com/api/v2#/reference/webhook-dispatches/webhook-dispatches-collection/get-list-of-webhook-dispatches + * Lists all webhook dispatches. * * Awaiting the return value (as you would with a Promise) will result in a single API call. The amount of fetched * items in a single API call is limited. * ```javascript * const paginatedList = await client.list(options); - *``` + * ``` * * Asynchronous iteration is also supported. This will fetch additional pages if needed until all items are * retrieved. @@ -31,6 +49,10 @@ export class WebhookDispatchCollectionClient extends ResourceCollectionClient { * ```javascript * for await (const singleItem of client.list(options)) {...} * ``` + * + * @param options - Pagination and sorting options. + * @returns A paginated iterator of webhook dispatches. + * @see https://docs.apify.com/api/v2/webhook-dispatches-get */ list(options: WebhookDispatchCollectionListOptions = {}): PaginatedIterator { ow( diff --git a/src/utils.ts b/src/utils.ts index 55b5775a..f11e8db6 100644 --- a/src/utils.ts +++ b/src/utils.ts @@ -15,6 +15,11 @@ const RECORD_NOT_FOUND_TYPE = 'record-not-found'; const RECORD_OR_TOKEN_NOT_FOUND_TYPE = 'record-or-token-not-found'; const MIN_GZIP_BYTES = 1024; +/** + * Generic interface for objects that may contain a data property. + * + * @template R - The type of the data property + */ export interface MaybeData { data?: R; } @@ -226,6 +231,9 @@ declare global { export const VERSION: string | undefined; } +/** + * Options for creating a pagination iterator. + */ export interface PaginationIteratorOptions { maxPageLimit: number; getPage: (opts: RequestQueueClientListRequestsOptions) => Promise; @@ -233,6 +241,9 @@ export interface PaginationIteratorOptions { exclusiveStartId?: string; } +/** + * Standard pagination options for API requests. + */ export interface PaginationOptions { /** Position of the first returned entry. */ offset?: number; @@ -240,6 +251,11 @@ export interface PaginationOptions { limit?: number; } +/** + * Standard paginated response format. + * + * @template Data - The type of items in the response + */ export interface PaginatedResponse { /** Total count of entries. */ total: number; @@ -247,6 +263,14 @@ export interface PaginatedResponse { items: Data[]; } +/** + * Paginated list with detailed pagination information. + * + * Used primarily for Dataset items and other list operations that support + * offset-based pagination and field transformations. + * + * @template Data - The type of items in the list + */ export interface PaginatedList { /** Total count of entries in the dataset. */ total: number; @@ -262,6 +286,13 @@ export interface PaginatedList { items: Data[]; } +/** + * Type representing both a Promise of a paginated list and an async iterable. + * + * Allows both awaiting the first page and iterating through all pages. + * + * @template T - The type of items in the paginated list + */ export type PaginatedIterator = Promise> & AsyncIterable; export function cast(input: unknown): T { @@ -276,8 +307,19 @@ export function asArray(value: T | T[]): T[] { return [value]; } +/** + * Generic dictionary type (key-value map). + * + * @template T - The type of values in the dictionary + */ export type Dictionary = Record; +/** + * Utility type that makes specific keys optional while preserving union types. + * + * @template T - The base type + * @template K - Keys to make optional + */ export type DistributiveOptional = T extends any ? Omit & Partial> : never; /**