From a2ca7c3bb3623581cbb3efabca49f8f47425d409 Mon Sep 17 00:00:00 2001 From: Jan Curn Date: Thu, 27 Nov 2025 13:48:24 -0800 Subject: [PATCH 01/18] Generated JSDocs based on API ref --- src/apify_client.ts | 259 +++++++++++++++++++++--- src/resource_clients/actor.ts | 158 +++++++++++++-- src/resource_clients/build.ts | 80 ++++++-- src/resource_clients/dataset.ts | 174 ++++++++++++++-- src/resource_clients/key_value_store.ts | 171 +++++++++++++--- src/resource_clients/request_queue.ts | 222 ++++++++++++++++++-- src/resource_clients/run.ts | 207 ++++++++++++++++--- 7 files changed, 1121 insertions(+), 150 deletions(-) diff --git a/src/apify_client.ts b/src/apify_client.ts index 93c6f88aa..29779744c 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 Actor collection + * @see https://docs.apify.com/api/v2#/reference/actors/actor-collection */ 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 specified Actor + * @see https://docs.apify.com/api/v2#/reference/actors/actor-object + * + * @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 the build collection + * @see https://docs.apify.com/api/v2#/reference/actor-builds/build-collection */ 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#/reference/actor-builds/build-object */ 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 dataset collection + * @see https://docs.apify.com/api/v2#/reference/datasets/dataset-collection */ 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 specified dataset + * @see https://docs.apify.com/api/v2#/reference/datasets/dataset + * + * @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 store collection + * @see https://docs.apify.com/api/v2#/reference/key-value-stores/store-collection */ 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 specified key-value store + * @see https://docs.apify.com/api/v2#/reference/key-value-stores/store-object + * + * @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#/reference/logs */ 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 queue collection + * @see https://docs.apify.com/api/v2#/reference/request-queues/queue-collection */ 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 specified request queue + * @see https://docs.apify.com/api/v2#/reference/request-queues/queue + * + * @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#/reference/actor-runs/run-collection */ 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#/reference/actor-runs/run-object-and-its-storages + * + * @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#/reference/actor-tasks/task-collection */ 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#/reference/actor-tasks/task-object + * + * @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 schedule collection + * @see https://docs.apify.com/api/v2#/reference/schedules/schedules-collection */ 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 specified schedule + * @see https://docs.apify.com/api/v2#/reference/schedules/schedule-object */ 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#/reference/users */ 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 webhook collection + * @see https://docs.apify.com/api/v2#/reference/webhooks/webhook-collection */ 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 specified webhook + * @see https://docs.apify.com/api/v2#/reference/webhooks/webhook-object */ 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 dispatch collection + * @see https://docs.apify.com/api/v2#/reference/webhook-dispatches */ 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 specified webhook dispatch + * @see https://docs.apify.com/api/v2#/reference/webhook-dispatches/webhook-dispatch-object */ 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/#/reference/store */ 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) { diff --git a/src/resource_clients/actor.ts b/src/resource_clients/actor.ts index 4d73cbb06..3dd923a9b 100644 --- a/src/resource_clients/actor.ts +++ b/src/resource_clients/actor.ts @@ -31,14 +31,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#/reference/actors/actor-object/get-actor */ 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#/reference/actors/actor-object/update-actor */ async update(newFields: ActorUpdateOptions): Promise { ow(newFields, ow.object); @@ -47,15 +54,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#/reference/actors/actor-object/delete-actor */ 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#/reference/actors/run-collection/run-actor + * + * @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 +161,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#/reference/actors/run-collection/run-actor + * + * @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 +236,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#/reference/actors/build-collection/build-actor + * + * @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); @@ -214,7 +310,19 @@ 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 + * @returns A client for the last run + * @see https://docs.apify.com/api/v2#/reference/actors/last-run-object-and-its-storages + * + * @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 +343,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#/reference/actors/build-collection */ builds(): BuildCollectionClient { return new BuildCollectionClient( @@ -246,7 +357,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#/reference/actors/run-collection */ runs(): RunCollectionClient { return new RunCollectionClient( @@ -257,7 +371,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#/reference/actors/version-object */ version(versionNumber: string): ActorVersionClient { ow(versionNumber, ow.string); @@ -269,16 +387,20 @@ 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#/reference/actors/version-collection */ 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#/reference/actors/webhook-collection */ webhooks(): WebhookCollectionClient { return new WebhookCollectionClient(this._subResourceOptions()); diff --git a/src/resource_clients/build.ts b/src/resource_clients/build.ts index e2f4fb37b..51e683feb 100644 --- a/src/resource_clients/build.ts +++ b/src/resource_clients/build.ts @@ -20,7 +20,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#/reference/actor-builds/build-object/get-build + * + * @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 +49,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#/reference/actor-builds/abort-build/abort-build + * + * @example + * ```javascript + * await client.build('build-id').abort(); + * ``` */ async abort(): Promise { const response = await this.httpClient.call({ @@ -47,7 +72,9 @@ 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#/reference/actor-builds/delete-build/delete-build */ async delete(): Promise { return this._delete(); @@ -67,15 +94,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. - * - * 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. - * + * 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. + * + * 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 +135,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#/reference/actor-builds/build-log + * + * @example + * ```javascript + * // Get build log + * const log = await client.build('build-id').log().get(); + * console.log(log); + * ``` */ log(): LogClient { return new LogClient( diff --git a/src/resource_clients/dataset.ts b/src/resource_clients/dataset.ts index 220b34099..d629c5cb5 100644 --- a/src/resource_clients/dataset.ts +++ b/src/resource_clients/dataset.ts @@ -29,14 +29,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#/reference/datasets/dataset/get-dataset */ 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#/reference/datasets/dataset/update-dataset */ async update(newFields: DatasetClientUpdateOptions): Promise { ow(newFields, ow.object); @@ -45,14 +52,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#/reference/datasets/dataset/delete-dataset */ 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#/reference/datasets/item-collection/get-items + * + * @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 +133,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#/reference/datasets/item-collection/get-items + * + * @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 +213,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#/reference/datasets/item-collection/put-items + * + * @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 +261,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#tag/DatasetsStatistics/operation/dataset_statistics_get */ async getStatistics(): Promise { const requestOpts: ApifyRequestConfig = { @@ -167,16 +286,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. - * - * 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. - * - * Any other options (like `limit` or `prefix`) will be included as query parameters in the URL. + * 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 + * + * @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}`); + * + * // 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( diff --git a/src/resource_clients/key_value_store.ts b/src/resource_clients/key_value_store.ts index 7a4d20a76..05c1d185e 100644 --- a/src/resource_clients/key_value_store.ts +++ b/src/resource_clients/key_value_store.ts @@ -39,14 +39,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#/reference/key-value-stores/store-object/get-store */ 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 access level (PUBLIC or PRIVATE) + * @returns The updated KeyValueStore object + * @see https://docs.apify.com/api/v2#/reference/key-value-stores/store-object/update-store */ async update(newFields: KeyValueClientUpdateOptions): Promise { ow(newFields, ow.object); @@ -55,14 +65,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#/reference/key-value-stores/store-object/delete-store */ 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#/reference/key-value-stores/key-collection/get-list-of-keys + * + * @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 +131,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 +163,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. - * - * Any other options (like `limit` or `prefix`) will be included as query parameters in the URL. + * @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 + * + * @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 +219,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#/reference/key-value-stores/record/get-record + * + * @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 = { @@ -245,15 +320,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. - * - * https://docs.apify.com/api/v2#/reference/key-value-stores/record/put-record + * 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. + * + * @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#/reference/key-value-stores/record/put-record + * + * @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 +420,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#/reference/key-value-stores/record/delete-record + * + * @example + * ```javascript + * await client.keyValueStore('my-store').deleteRecord('temp-data'); + * ``` */ async deleteRecord(key: string): Promise { ow(key, ow.string); diff --git a/src/resource_clients/request_queue.ts b/src/resource_clients/request_queue.ts index 7cec87716..429b89bc9 100644 --- a/src/resource_clients/request_queue.ts +++ b/src/resource_clients/request_queue.ts @@ -43,14 +43,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#/reference/request-queues/queue/get-request-queue */ 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#/reference/request-queues/queue/update-request-queue */ async update(newFields: RequestQueueClientUpdateOptions): Promise { ow(newFields, ow.object); @@ -59,14 +66,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#/reference/request-queues/queue/delete-request-queue */ 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#/reference/request-queues/queue-head/get-head */ async listHead(options: RequestQueueClientListHeadOptions = {}): Promise { ow( @@ -90,7 +106,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#/reference/request-queues/queue-head-with-locks/get-head-and-lock + * + * @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 +163,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#/reference/request-queues/request-collection/add-request + * + * @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, @@ -261,7 +341,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#/reference/request-queues/batch-request-operations/add-requests + * + * @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 +439,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#/reference/request-queues/batch-request-operations/delete-requests */ async batchDeleteRequests( requests: RequestQueueClientRequestToDelete[], @@ -354,7 +474,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#/reference/request-queues/request/get-request */ async getRequest(id: string): Promise { ow(id, ow.string); @@ -375,7 +499,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#/reference/request-queues/request/update-request */ async updateRequest( request: RequestQueueClientRequestSchema, @@ -409,6 +538,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 +557,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#/reference/request-queues/request-lock/prolong-request-lock + * + * @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 +608,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#/reference/request-queues/request-lock/delete-request-lock */ async deleteRequestLock(id: string, options: RequestQueueClientDeleteRequestLockOptions = {}): Promise { ow(id, ow.string); @@ -476,7 +638,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#/reference/request-queues/request-collection/list-requests */ async listRequests( options: RequestQueueClientListRequestsOptions = {}, @@ -504,7 +673,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 +695,21 @@ export class RequestQueueClient extends ResourceClient { } /** - * https://docs.apify.com/api/v2#/reference/request-queues/request-collection/list-requests - * - * Usage: - * for await (const { items } of client.paginateRequests({ limit: 10 })) { - * items.forEach((request) => console.log(request)); + * 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#/reference/request-queues/request-collection/list-requests + * + * @example + * ```javascript + * for await (const { items } of client.requestQueue('my-queue').paginateRequests({ limit: 100 })) { + * items.forEach((request) => console.log(request.url)); * } + * ``` */ paginateRequests( options: RequestQueueClientPaginateRequestsOptions = {}, diff --git a/src/resource_clients/run.ts b/src/resource_clients/run.ts index 8883e176f..009932bea 100644 --- a/src/resource_clients/run.ts +++ b/src/resource_clients/run.ts @@ -28,7 +28,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#/reference/actor-runs/run-object/get-run + * + * @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 +57,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#/reference/actor-runs/abort-run/abort-run + * + * @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 +91,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#/reference/actor-runs/delete-run/delete-run */ 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#/reference/actor-runs/metamorph-run/metamorph-run + * + * @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 +165,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#/reference/actor-runs/reboot-run/reboot-run + * + * @example + * ```javascript + * const run = await client.run('run-id').reboot(); + * ``` */ async reboot(): Promise { const request: AxiosRequestConfig = { @@ -124,6 +189,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 access level (PUBLIC or PRIVATE) + * @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 +213,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#/reference/actor-runs/resurrect-run/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( @@ -190,16 +292,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. - * - * 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. - * - * 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. + * 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. + * + * 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. + * + * @param options - Wait options + * @param options.waitSecs - Maximum time to wait for the run to finish, in seconds. 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 +331,16 @@ export class RunClient extends ResourceClient { } /** - * https://docs.apify.com/api/v2#/reference/actor-runs/run-object-and-its-storages - * - * 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 the default dataset of this Actor run. + * + * @returns A client for accessing the run's default dataset + * @see https://docs.apify.com/api/v2#/reference/actor-runs/run-object-and-its-storages + * + * @example + * ```javascript + * // Access run's dataset + * const { items } = await client.run('run-id').dataset().listItems(); + * ``` */ dataset(): DatasetClient { return new DatasetClient( @@ -227,10 +351,16 @@ export class RunClient extends ResourceClient { } /** - * https://docs.apify.com/api/v2#/reference/actor-runs/run-object-and-its-storages - * - * This also works through `actorClient.lastRun().keyValueStore()`. - * https://docs.apify.com/api/v2#/reference/actors/last-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#/reference/actor-runs/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 +371,16 @@ export class RunClient extends ResourceClient { } /** - * https://docs.apify.com/api/v2#/reference/actor-runs/run-object-and-its-storages - * - * 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 the default request queue of this Actor run. + * + * @returns A client for accessing the run's default request queue + * @see https://docs.apify.com/api/v2#/reference/actor-runs/run-object-and-its-storages + * + * @example + * ```javascript + * // Access run's request queue + * const { items } = await client.run('run-id').requestQueue().listHead(); + * ``` */ requestQueue(): RequestQueueClient { return new RequestQueueClient( @@ -255,10 +391,17 @@ export class RunClient extends ResourceClient { } /** - * https://docs.apify.com/api/v2#/reference/actor-runs/run-object-and-its-storages - * - * This also works through `actorClient.lastRun().log()`. - * https://docs.apify.com/api/v2#/reference/actors/last-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#/reference/actor-runs/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( From 90c248fb2e47cf3894710cc6b4570e29e579be74 Mon Sep 17 00:00:00 2001 From: Jan Curn Date: Thu, 27 Nov 2025 13:59:22 -0800 Subject: [PATCH 02/18] JSDocs for interfaces --- src/apify_client.ts | 3 + src/resource_clients/actor.ts | 143 ++++++++++++++++++++++++ src/resource_clients/build.ts | 30 +++++ src/resource_clients/dataset.ts | 39 +++++++ src/resource_clients/key_value_store.ts | 45 ++++++++ src/resource_clients/request_queue.ts | 57 ++++++++++ src/resource_clients/run.ts | 25 +++++ src/resource_clients/schedule.ts | 26 +++++ src/resource_clients/task.ts | 27 +++++ src/resource_clients/webhook.ts | 18 +++ src/utils.ts | 42 +++++++ 11 files changed, 455 insertions(+) diff --git a/src/apify_client.ts b/src/apify_client.ts index 29779744c..94ee12b57 100644 --- a/src/apify_client.ts +++ b/src/apify_client.ts @@ -562,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 3dd923a9b..51c5e4ee9 100644 --- a/src/resource_clients/actor.ts +++ b/src/resource_clients/actor.ts @@ -407,46 +407,89 @@ export class ActorClient extends ResourceClient { } } +/** + * 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; @@ -454,19 +497,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, @@ -485,6 +540,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; @@ -567,6 +628,11 @@ 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. @@ -580,6 +646,11 @@ export interface ActorCallOptions extends Omit; +/** + * 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: { @@ -738,6 +878,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/build.ts b/src/resource_clients/build.ts index 51e683feb..f6f0f6bb9 100644 --- a/src/resource_clients/build.ts +++ b/src/resource_clients/build.ts @@ -156,10 +156,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. @@ -169,12 +175,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; @@ -200,16 +215,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; @@ -217,6 +241,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/dataset.ts b/src/resource_clients/dataset.ts index d629c5cb5..22a7fe336 100644 --- a/src/resource_clients/dataset.ts +++ b/src/resource_clients/dataset.ts @@ -368,6 +368,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; @@ -387,6 +393,9 @@ export interface Dataset { itemsPublicUrl: string; } +/** + * Statistics about Dataset usage and storage. + */ export interface DatasetStats { readCount?: number; writeCount?: number; @@ -394,12 +403,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; @@ -415,10 +433,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', @@ -431,6 +457,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; @@ -440,10 +471,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/key_value_store.ts b/src/resource_clients/key_value_store.ts index 05c1d185e..299a39241 100644 --- a/src/resource_clients/key_value_store.ts +++ b/src/resource_clients/key_value_store.ts @@ -442,6 +442,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; @@ -458,6 +464,9 @@ export interface KeyValueStore { keysPublicUrl: string; } +/** + * Statistics about Key-Value Store usage and storage. + */ export interface KeyValueStoreStats { readCount?: number; writeCount?: number; @@ -466,12 +475,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; @@ -480,10 +495,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; @@ -493,29 +518,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/request_queue.ts b/src/resource_clients/request_queue.ts index 429b89bc9..c4551179e 100644 --- a/src/resource_clients/request_queue.ts +++ b/src/resource_clients/request_queue.ts @@ -732,11 +732,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; @@ -756,6 +765,9 @@ export interface RequestQueue { generalAccess?: STORAGE_GENERAL_ACCESS | null; } +/** + * Statistics about Request Queue usage and storage. + */ export interface RequestQueueStats { readCount?: number; writeCount?: number; @@ -764,16 +776,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; @@ -781,34 +802,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; @@ -842,6 +883,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; @@ -857,6 +903,9 @@ export interface RequestQueueClientRequestSchema { loadedUrl?: string; } +/** + * Result of adding a request to the queue. + */ export interface RequestQueueClientAddRequestResult { requestId: string; wasAlreadyPresent: boolean; @@ -880,6 +929,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[]; @@ -891,6 +945,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/run.ts b/src/resource_clients/run.ts index 009932bea..fc7262792 100644 --- a/src/resource_clients/run.ts +++ b/src/resource_clients/run.ts @@ -440,29 +440,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; @@ -472,6 +491,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; @@ -481,6 +503,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/schedule.ts b/src/resource_clients/schedule.ts index 52015333c..88cc44fea 100644 --- a/src/resource_clients/schedule.ts +++ b/src/resource_clients/schedule.ts @@ -61,6 +61,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 +86,9 @@ export interface Schedule { }; } +/** + * Data for creating or updating a Schedule. + */ export type ScheduleCreateOrUpdateData = Partial< Pick< Schedule, @@ -90,6 +98,9 @@ export type ScheduleCreateOrUpdateData = Partial< } >; +/** + * Types of actions that can be scheduled. + */ export enum ScheduleActions { RunActor = 'RUN_ACTOR', RunActorTask = 'RUN_ACTOR_TASK', @@ -100,19 +111,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 +143,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/task.ts b/src/resource_clients/task.ts index 6ef869b59..937e29cec 100644 --- a/src/resource_clients/task.ts +++ b/src/resource_clients/task.ts @@ -201,6 +201,12 @@ export class TaskClient extends ResourceClient { } } +/** + * Represents an Actor task. + * + * Tasks are pre-configured Actor runs with stored input and settings that can be executed + * repeatedly without having to specify the input each time. + */ export interface Task { id: string; userId: string; @@ -217,10 +223,16 @@ export interface Task { actorStandby?: Partial; } +/** + * Statistics about Task usage. + */ export interface TaskStats { totalRuns: number; } +/** + * Configuration options for a Task. + */ export interface TaskOptions { build?: string; timeoutSecs?: number; @@ -228,16 +240,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 (uses Task's configured permissions). + */ 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/webhook.ts b/src/resource_clients/webhook.ts index 80782ee78..dc5f38734 100644 --- a/src/resource_clients/webhook.ts +++ b/src/resource_clients/webhook.ts @@ -76,6 +76,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 +106,9 @@ export interface WebhookIdempotencyKey { idempotencyKey?: string; } +/** + * Data for updating a Webhook. + */ export type WebhookUpdateData = Partial< Pick< Webhook, @@ -118,12 +127,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/utils.ts b/src/utils.ts index 55b5775a5..a5d444b79 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; /** From 83b635dce999ffba92c53aa87c4c2b7f944cea51 Mon Sep 17 00:00:00 2001 From: Jan Curn Date: Thu, 27 Nov 2025 14:15:11 -0800 Subject: [PATCH 03/18] Fixed lint --- src/apify_client.ts | 124 ++++++++++++------------ src/resource_clients/actor.ts | 72 +++++++------- src/resource_clients/build.ts | 34 +++---- src/resource_clients/dataset.ts | 58 +++++------ src/resource_clients/key_value_store.ts | 58 +++++------ src/resource_clients/request_queue.ts | 78 +++++++-------- src/resource_clients/run.ts | 66 ++++++------- src/resource_clients/schedule.ts | 2 +- src/resource_clients/task.ts | 4 +- src/resource_clients/webhook.ts | 2 +- src/utils.ts | 16 +-- 11 files changed, 257 insertions(+), 257 deletions(-) diff --git a/src/apify_client.ts b/src/apify_client.ts index 94ee12b57..5e10ceead 100644 --- a/src/apify_client.ts +++ b/src/apify_client.ts @@ -37,23 +37,23 @@ const DEFAULT_TIMEOUT_SECS = 360; /** * 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 { @@ -126,9 +126,9 @@ export class ApifyClient { /** * 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 Actor collection * @see https://docs.apify.com/api/v2#/reference/actors/actor-collection */ @@ -138,14 +138,14 @@ export class ApifyClient { /** * 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 specified Actor * @see https://docs.apify.com/api/v2#/reference/actors/actor-object - * + * * @example * ```javascript * // Call an Actor and wait for it to finish @@ -163,9 +163,9 @@ export class ApifyClient { /** * Returns a client for managing Actor builds in your account. - * + * * Lists all builds across all of your Actors. - * + * * @returns A client for the build collection * @see https://docs.apify.com/api/v2#/reference/actor-builds/build-collection */ @@ -175,9 +175,9 @@ export class ApifyClient { /** * 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#/reference/actor-builds/build-object @@ -193,9 +193,9 @@ export class ApifyClient { /** * 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 dataset collection * @see https://docs.apify.com/api/v2#/reference/datasets/dataset-collection */ @@ -205,15 +205,15 @@ export class ApifyClient { /** * 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 specified dataset * @see https://docs.apify.com/api/v2#/reference/datasets/dataset - * + * * @example * ```javascript * // Push items to a dataset @@ -221,7 +221,7 @@ export class ApifyClient { * { url: 'https://example.com', title: 'Example' }, * { url: 'https://test.com', title: 'Test' } * ]); - * + * * // Retrieve items * const { items } = await client.dataset('my-dataset').listItems(); * ``` @@ -239,9 +239,9 @@ export class ApifyClient { /** * 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 store collection * @see https://docs.apify.com/api/v2#/reference/key-value-stores/store-collection */ @@ -251,19 +251,19 @@ export class ApifyClient { /** * 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 specified key-value store * @see https://docs.apify.com/api/v2#/reference/key-value-stores/store-object - * + * * @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'); * ``` @@ -279,7 +279,7 @@ export class ApifyClient { /** * 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#/reference/logs @@ -295,9 +295,9 @@ export class ApifyClient { /** * 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 queue collection * @see https://docs.apify.com/api/v2#/reference/request-queues/queue-collection */ @@ -307,21 +307,21 @@ export class ApifyClient { /** * 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 specified request queue * @see https://docs.apify.com/api/v2#/reference/request-queues/queue - * + * * @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 }); * ``` @@ -345,9 +345,9 @@ export class ApifyClient { /** * 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#/reference/actor-runs/run-collection */ @@ -360,19 +360,19 @@ export class ApifyClient { /** * 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#/reference/actor-runs/run-object-and-its-storages - * + * * @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(); * ``` @@ -388,9 +388,9 @@ export class ApifyClient { /** * 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#/reference/actor-tasks/task-collection */ @@ -400,13 +400,13 @@ export class ApifyClient { /** * 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#/reference/actor-tasks/task-object - * + * * @example * ```javascript * // Run a task and wait for it to finish @@ -424,9 +424,9 @@ export class ApifyClient { /** * Returns a client for managing schedules in your account. - * + * * Schedules automatically start Actor or task runs at specified times. - * + * * @returns A client for the schedule collection * @see https://docs.apify.com/api/v2#/reference/schedules/schedules-collection */ @@ -436,9 +436,9 @@ export class ApifyClient { /** * 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 specified schedule * @see https://docs.apify.com/api/v2#/reference/schedules/schedule-object @@ -454,9 +454,9 @@ export class ApifyClient { /** * 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#/reference/users @@ -472,9 +472,9 @@ export class ApifyClient { /** * 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 webhook collection * @see https://docs.apify.com/api/v2#/reference/webhooks/webhook-collection */ @@ -484,9 +484,9 @@ export class ApifyClient { /** * 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 specified webhook * @see https://docs.apify.com/api/v2#/reference/webhooks/webhook-object @@ -502,9 +502,9 @@ export class ApifyClient { /** * Returns a client for viewing webhook dispatches in your account. - * + * * Webhook dispatches represent individual invocations of webhooks. - * + * * @returns A client for the webhook dispatch collection * @see https://docs.apify.com/api/v2#/reference/webhook-dispatches */ @@ -514,7 +514,7 @@ export class ApifyClient { /** * Returns a client for a specific webhook dispatch. - * + * * @param id - Webhook dispatch ID * @returns A client for the specified webhook dispatch * @see https://docs.apify.com/api/v2#/reference/webhook-dispatches/webhook-dispatch-object @@ -530,9 +530,9 @@ export class ApifyClient { /** * 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/#/reference/store */ @@ -542,10 +542,10 @@ export class ApifyClient { /** * 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 diff --git a/src/resource_clients/actor.ts b/src/resource_clients/actor.ts index 51c5e4ee9..c2fcbc20f 100644 --- a/src/resource_clients/actor.ts +++ b/src/resource_clients/actor.ts @@ -32,7 +32,7 @@ export class ActorClient extends ResourceClient { /** * 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#/reference/actors/actor-object/get-actor */ @@ -42,7 +42,7 @@ export class ActorClient extends ResourceClient { /** * 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#/reference/actors/actor-object/update-actor @@ -55,7 +55,7 @@ export class ActorClient extends ResourceClient { /** * Deletes the Actor. - * + * * @see https://docs.apify.com/api/v2#/reference/actors/actor-object/delete-actor */ async delete(): Promise { @@ -64,11 +64,11 @@ export class ActorClient extends ResourceClient { /** * 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 @@ -82,13 +82,13 @@ export class ActorClient extends ResourceClient { * @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#/reference/actors/run-collection/run-actor - * + * * @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' }, @@ -162,11 +162,11 @@ export class ActorClient extends ResourceClient { /** * 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}) @@ -177,20 +177,20 @@ export class ActorClient extends ResourceClient { * @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#/reference/actors/run-collection/run-actor - * + * * @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' }); @@ -237,10 +237,10 @@ export class ActorClient extends ResourceClient { /** * 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. @@ -249,15 +249,15 @@ export class ActorClient extends ResourceClient { * @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#/reference/actors/build-collection/build-actor - * + * * @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', { + * const build = await client.actor('my-actor').build('0.1', { * waitForFinish: 120, * tag: 'latest', * useCache: true @@ -311,13 +311,13 @@ export class ActorClient extends ResourceClient { /** * 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 * @returns A client for the last run * @see https://docs.apify.com/api/v2#/reference/actors/last-run-object-and-its-storages - * + * * @example * ```javascript * // Get the last successful run @@ -344,7 +344,7 @@ export class ActorClient extends ResourceClient { /** * 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#/reference/actors/build-collection */ @@ -358,7 +358,7 @@ export class ActorClient extends ResourceClient { /** * 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#/reference/actors/run-collection */ @@ -372,7 +372,7 @@ export class ActorClient extends ResourceClient { /** * 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#/reference/actors/version-object @@ -388,7 +388,7 @@ export class ActorClient extends ResourceClient { /** * 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#/reference/actors/version-collection */ @@ -398,7 +398,7 @@ export class ActorClient extends ResourceClient { /** * 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#/reference/actors/webhook-collection */ @@ -409,7 +409,7 @@ export class ActorClient extends ResourceClient { /** * 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. @@ -542,7 +542,7 @@ 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. */ @@ -630,7 +630,7 @@ export interface ActorStartOptions { /** * 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 { @@ -648,7 +648,7 @@ export interface ActorCallOptions extends Omit; /** * 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 { diff --git a/src/resource_clients/build.ts b/src/resource_clients/build.ts index f6f0f6bb9..d6582d742 100644 --- a/src/resource_clients/build.ts +++ b/src/resource_clients/build.ts @@ -21,18 +21,18 @@ export class BuildClient extends ResourceClient { /** * 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#/reference/actor-builds/build-object/get-build - * + * * @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 }); * ``` @@ -50,12 +50,12 @@ export class BuildClient extends ResourceClient { /** * 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#/reference/actor-builds/abort-build/abort-build - * + * * @example * ```javascript * await client.build('build-id').abort(); @@ -73,7 +73,7 @@ export class BuildClient extends ResourceClient { /** * Deletes the Actor build. - * + * * @see https://docs.apify.com/api/v2#/reference/actor-builds/delete-build/delete-build */ async delete(): Promise { @@ -95,27 +95,27 @@ export class BuildClient extends ResourceClient { /** * 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. - * + * * 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') { @@ -136,10 +136,10 @@ export class BuildClient extends ResourceClient { /** * 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#/reference/actor-builds/build-log - * + * * @example * ```javascript * // Get build log @@ -186,7 +186,7 @@ export interface BuildMeta { /** * 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. */ @@ -243,7 +243,7 @@ export interface BuildOptions { /** * 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. */ diff --git a/src/resource_clients/dataset.ts b/src/resource_clients/dataset.ts index 22a7fe336..e36e6cc64 100644 --- a/src/resource_clients/dataset.ts +++ b/src/resource_clients/dataset.ts @@ -30,7 +30,7 @@ export class DatasetClient< /** * 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#/reference/datasets/dataset/get-dataset */ @@ -40,7 +40,7 @@ export class DatasetClient< /** * 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#/reference/datasets/dataset/update-dataset @@ -53,7 +53,7 @@ export class DatasetClient< /** * Deletes the dataset. - * + * * @see https://docs.apify.com/api/v2#/reference/datasets/dataset/delete-dataset */ async delete(): Promise { @@ -62,11 +62,11 @@ export class DatasetClient< /** * 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. @@ -81,20 +81,20 @@ export class DatasetClient< * @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#/reference/datasets/item-collection/get-items - * + * * @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, @@ -134,11 +134,11 @@ export class DatasetClient< /** * 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. @@ -151,20 +151,20 @@ export class DatasetClient< * @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#/reference/datasets/item-collection/get-items - * + * * @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', @@ -214,16 +214,16 @@ export class DatasetClient< /** * 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#/reference/datasets/item-collection/put-items - * + * * @example * ```javascript * // Store a single object @@ -232,14 +232,14 @@ export class DatasetClient< * 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']); * ``` @@ -262,10 +262,10 @@ export class DatasetClient< /** * 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#tag/DatasetsStatistics/operation/dataset_statistics_get */ @@ -287,18 +287,18 @@ export class DatasetClient< /** * 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 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 - * + * * @example * ```javascript * // Create a URL that expires in 1 hour with specific fields @@ -308,7 +308,7 @@ export class DatasetClient< * limit: 100 * }); * console.log(`Share this URL: ${url}`); - * + * * // Create a permanent public URL for clean items only * const url = await client.dataset('my-dataset').createItemsPublicUrl({ * clean: true, @@ -370,7 +370,7 @@ 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. */ @@ -414,7 +414,7 @@ export interface DatasetClientUpdateOptions { /** * Options for listing items from a Dataset. - * + * * Provides various filtering, pagination, and transformation options to customize * the output format and content of retrieved items. */ @@ -435,7 +435,7 @@ export interface DatasetClientListItemOptions { /** * Options for creating a public URL to access Dataset items. - * + * * Extends {@link DatasetClientListItemOptions} with URL expiration control. */ export interface DatasetClientCreateItemsUrlOptions extends DatasetClientListItemOptions { @@ -459,7 +459,7 @@ const validItemFormats = [...new Set(Object.values(DownloadItemsFormat).map((ite /** * Options for downloading Dataset items in a specific format. - * + * * Extends {@link DatasetClientListItemOptions} with format-specific options. */ export interface DatasetClientDownloadItemsOptions extends DatasetClientListItemOptions { @@ -473,7 +473,7 @@ export interface DatasetClientDownloadItemsOptions extends DatasetClientListItem /** * Statistical information about Dataset fields. - * + * * Provides insights into the data structure and content of the Dataset. */ export interface DatasetStatistics { diff --git a/src/resource_clients/key_value_store.ts b/src/resource_clients/key_value_store.ts index 299a39241..b7e12188e 100644 --- a/src/resource_clients/key_value_store.ts +++ b/src/resource_clients/key_value_store.ts @@ -40,7 +40,7 @@ export class KeyValueStoreClient extends ResourceClient { /** * 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#/reference/key-value-stores/store-object/get-store */ @@ -50,7 +50,7 @@ export class KeyValueStoreClient extends ResourceClient { /** * 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 @@ -66,7 +66,7 @@ export class KeyValueStoreClient extends ResourceClient { /** * Deletes the key-value store. - * + * * @see https://docs.apify.com/api/v2#/reference/key-value-stores/store-object/delete-store */ async delete(): Promise { @@ -75,10 +75,10 @@ export class KeyValueStoreClient extends ResourceClient { /** * 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. @@ -86,22 +86,22 @@ export class KeyValueStoreClient extends ResourceClient { * @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#/reference/key-value-stores/key-collection/get-list-of-keys - * + * * @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({ + * const result = await client.keyValueStore('my-store').listKeys({ * limit: 100, - * exclusiveStartKey + * exclusiveStartKey * }); * // Process result.items... * exclusiveStartKey = result.nextExclusiveStartKey; @@ -136,10 +136,10 @@ export class KeyValueStoreClient extends ResourceClient { * If the client has permission to access the key-value store's URL signing key, * 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'); @@ -173,11 +173,11 @@ export class KeyValueStoreClient extends ResourceClient { * @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 - * + * * @example * ```javascript * // Create a URL that expires in 1 hour - * const url = await client.keyValueStore('my-store').createKeysPublicUrl({ + * const url = await client.keyValueStore('my-store').createKeysPublicUrl({ * expiresInSecs: 3600, * prefix: 'image-' * }); @@ -220,11 +220,11 @@ export class KeyValueStoreClient extends ResourceClient { * Tests whether a record with the given key exists in the key-value store without retrieving its value. * * 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#/reference/key-value-stores/record/get-record - * + * * @example * ```javascript * const exists = await client.keyValueStore('my-store').recordExists('OUTPUT'); @@ -321,15 +321,15 @@ export class KeyValueStoreClient extends ResourceClient { /** * 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. - * + * * @param record - The record to store * @param record.key - Record key (unique identifier) * @param record.value - Record value (object, string, Buffer, or Stream) @@ -341,7 +341,7 @@ export class KeyValueStoreClient extends ResourceClient { * @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#/reference/key-value-stores/record/put-record - * + * * @example * ```javascript * // Store JSON object @@ -349,14 +349,14 @@ export class KeyValueStoreClient extends ResourceClient { * 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({ @@ -421,10 +421,10 @@ export class KeyValueStoreClient extends ResourceClient { /** * Deletes a record from the key-value store. - * + * * @param key - The record key to delete * @see https://docs.apify.com/api/v2#/reference/key-value-stores/record/delete-record - * + * * @example * ```javascript * await client.keyValueStore('my-store').deleteRecord('temp-data'); @@ -444,7 +444,7 @@ 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. */ @@ -497,7 +497,7 @@ export interface KeyValueClientListKeysOptions { /** * 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 { @@ -506,7 +506,7 @@ export interface KeyValueClientCreateKeysUrlOptions extends KeyValueClientListKe /** * Result of listing keys in a Key-Value Store. - * + * * Contains paginated list of keys with metadata and pagination information. */ export interface KeyValueClientListKeysResult { @@ -538,7 +538,7 @@ export interface KeyValueClientGetRecordOptions { /** * Represents a record (key-value pair) in a Key-Value Store. - * + * * @template T - The type of the record's value */ export interface KeyValueStoreRecord { @@ -557,7 +557,7 @@ export interface KeyValueStoreRecordOptions { /** * 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. */ diff --git a/src/resource_clients/request_queue.ts b/src/resource_clients/request_queue.ts index c4551179e..19382d755 100644 --- a/src/resource_clients/request_queue.ts +++ b/src/resource_clients/request_queue.ts @@ -44,7 +44,7 @@ export class RequestQueueClient extends ResourceClient { /** * 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#/reference/request-queues/queue/get-request-queue */ @@ -54,7 +54,7 @@ export class RequestQueueClient extends ResourceClient { /** * 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#/reference/request-queues/queue/update-request-queue @@ -67,7 +67,7 @@ export class RequestQueueClient extends ResourceClient { /** * Deletes the request queue. - * + * * @see https://docs.apify.com/api/v2#/reference/request-queues/queue/delete-request-queue */ async delete(): Promise { @@ -76,10 +76,10 @@ export class RequestQueueClient extends ResourceClient { /** * 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#/reference/request-queues/queue-head/get-head @@ -107,19 +107,19 @@ export class RequestQueueClient extends ResourceClient { /** * 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#/reference/request-queues/queue-head-with-locks/get-head-and-lock - * + * * @example * ```javascript * // Get and lock up to 10 requests for 60 seconds @@ -127,7 +127,7 @@ export class RequestQueueClient extends ResourceClient { * lockSecs: 60, * limit: 10 * }); - * + * * // Process each locked request * for (const request of items) { * console.log(`Processing: ${request.url}`); @@ -164,11 +164,11 @@ export class RequestQueueClient extends ResourceClient { /** * 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`. @@ -180,7 +180,7 @@ export class RequestQueueClient extends ResourceClient { * @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#/reference/request-queues/request-collection/add-request - * + * * @example * ```javascript * const result = await client.requestQueue('my-queue').addRequest({ @@ -192,7 +192,7 @@ export class RequestQueueClient extends ResourceClient { * 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' }, @@ -342,13 +342,13 @@ export class RequestQueueClient extends ResourceClient { /** * 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`. @@ -357,7 +357,7 @@ export class RequestQueueClient extends ResourceClient { * @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#/reference/request-queues/batch-request-operations/add-requests - * + * * @example * ```javascript * // Add a batch of URLs to crawl @@ -369,7 +369,7 @@ export class RequestQueueClient extends ResourceClient { * 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, @@ -440,9 +440,9 @@ export class RequestQueueClient extends ResourceClient { /** * 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#/reference/request-queues/batch-request-operations/delete-requests @@ -475,7 +475,7 @@ export class RequestQueueClient extends ResourceClient { /** * 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#/reference/request-queues/request/get-request @@ -500,7 +500,7 @@ export class RequestQueueClient extends ResourceClient { /** * 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 @@ -540,7 +540,7 @@ export class RequestQueueClient extends ResourceClient { /** * Deletes a specific request from the queue. - * + * * @param id - Request ID */ async deleteRequest(id: string): Promise { @@ -558,24 +558,24 @@ export class RequestQueueClient extends ResourceClient { /** * 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#/reference/request-queues/request-lock/prolong-request-lock - * + * * @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 }); * ``` @@ -609,10 +609,10 @@ export class RequestQueueClient extends ResourceClient { /** * 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#/reference/request-queues/request-lock/delete-request-lock @@ -639,10 +639,10 @@ export class RequestQueueClient extends ResourceClient { /** * 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#/reference/request-queues/request-collection/list-requests @@ -674,10 +674,10 @@ export class RequestQueueClient extends ResourceClient { /** * 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 */ @@ -696,14 +696,14 @@ export class RequestQueueClient extends ResourceClient { /** * 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#/reference/request-queues/request-collection/list-requests - * + * * @example * ```javascript * for await (const { items } of client.requestQueue('my-queue').paginateRequests({ limit: 100 })) { @@ -742,7 +742,7 @@ export interface RequestQueueUserOptions { /** * 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. */ @@ -838,7 +838,7 @@ export interface RequestQueueClientListAndLockHeadOptions { /** * Result of listing and locking requests from the queue head. - * + * * Extends {@link RequestQueueClientListHeadResult} with lock information. */ export interface RequestQueueClientListAndLockHeadResult extends RequestQueueClientListHeadResult { @@ -885,7 +885,7 @@ export interface RequestQueueClientBatchAddRequestWithRetriesOptions { /** * 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 { @@ -931,7 +931,7 @@ export interface RequestQueueClientUnlockRequestsResult { /** * Result of a batch operation on requests. - * + * * Contains lists of successfully processed and unprocessed requests. */ export interface RequestQueueClientBatchRequestsOperationResult { diff --git a/src/resource_clients/run.ts b/src/resource_clients/run.ts index fc7262792..b9f8a1acb 100644 --- a/src/resource_clients/run.ts +++ b/src/resource_clients/run.ts @@ -29,18 +29,18 @@ export class RunClient extends ResourceClient { /** * 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#/reference/actor-runs/run-object/get-run - * + * * @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 }); * ``` @@ -58,17 +58,17 @@ export class RunClient extends ResourceClient { /** * 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#/reference/actor-runs/abort-run/abort-run - * + * * @example * ```javascript * // Abort immediately * await client.run('run-id').abort(); - * + * * // Abort gracefully (allows cleanup) * await client.run('run-id').abort({ gracefully: true }); * ``` @@ -92,7 +92,7 @@ export class RunClient extends ResourceClient { /** * Deletes the Actor run. - * + * * @see https://docs.apify.com/api/v2#/reference/actor-runs/delete-run/delete-run */ async delete(): Promise { @@ -101,11 +101,11 @@ export class RunClient extends ResourceClient { /** * 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 @@ -113,7 +113,7 @@ export class RunClient extends ResourceClient { * @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#/reference/actor-runs/metamorph-run/metamorph-run - * + * * @example * ```javascript * // Transform current run into another Actor @@ -166,14 +166,14 @@ export class RunClient extends ResourceClient { /** * 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#/reference/actor-runs/reboot-run/reboot-run - * + * * @example * ```javascript * const run = await client.run('run-id').reboot(); @@ -191,18 +191,18 @@ export class RunClient extends ResourceClient { /** * 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 access level (PUBLIC or PRIVATE) * @returns The updated ActorRun object - * + * * @example * ```javascript * // Set a status message - * await client.run('run-id').update({ - * statusMessage: 'Processing items: 50/100' + * await client.run('run-id').update({ + * statusMessage: 'Processing items: 50/100' * }); * ``` */ @@ -214,10 +214,10 @@ export class RunClient extends ResourceClient { /** * 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. @@ -227,7 +227,7 @@ export class RunClient extends ResourceClient { * @param options.restartOnError - Whether to restart on error. * @returns The new (resurrected) ActorRun object * @see https://docs.apify.com/api/v2#/reference/actor-runs/resurrect-run/resurrect-run - * + * * @example * ```javascript * // Resurrect a failed run with more memory @@ -293,25 +293,25 @@ export class RunClient extends ResourceClient { /** * 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. - * + * * 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. - * + * * @param options - Wait options * @param options.waitSecs - Maximum time to wait for the run to finish, in seconds. 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') { @@ -332,10 +332,10 @@ export class RunClient extends ResourceClient { /** * Returns a client for the default dataset of this Actor run. - * + * * @returns A client for accessing the run's default dataset * @see https://docs.apify.com/api/v2#/reference/actor-runs/run-object-and-its-storages - * + * * @example * ```javascript * // Access run's dataset @@ -352,10 +352,10 @@ export class RunClient extends ResourceClient { /** * 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#/reference/actor-runs/run-object-and-its-storages - * + * * @example * ```javascript * // Access run's key-value store @@ -372,10 +372,10 @@ export class RunClient extends ResourceClient { /** * Returns a client for the default request queue of this Actor run. - * + * * @returns A client for accessing the run's default request queue * @see https://docs.apify.com/api/v2#/reference/actor-runs/run-object-and-its-storages - * + * * @example * ```javascript * // Access run's request queue @@ -392,10 +392,10 @@ export class RunClient extends ResourceClient { /** * 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#/reference/actor-runs/run-object-and-its-storages - * + * * @example * ```javascript * // Get run log diff --git a/src/resource_clients/schedule.ts b/src/resource_clients/schedule.ts index 88cc44fea..2bdb1b888 100644 --- a/src/resource_clients/schedule.ts +++ b/src/resource_clients/schedule.ts @@ -63,7 +63,7 @@ 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 { diff --git a/src/resource_clients/task.ts b/src/resource_clients/task.ts index 937e29cec..bdd86ba32 100644 --- a/src/resource_clients/task.ts +++ b/src/resource_clients/task.ts @@ -203,7 +203,7 @@ export class TaskClient extends ResourceClient { /** * Represents an Actor task. - * + * * Tasks are pre-configured Actor runs with stored input and settings that can be executed * repeatedly without having to specify the input each time. */ @@ -256,7 +256,7 @@ export interface TaskLastRunOptions { /** * Options for starting a Task. - * + * * Similar to {@link ActorStartOptions} but without contentType (Task input is predefined) * and forcePermissionLevel (uses Task's configured permissions). */ diff --git a/src/resource_clients/webhook.ts b/src/resource_clients/webhook.ts index dc5f38734..f86e420d9 100644 --- a/src/resource_clients/webhook.ts +++ b/src/resource_clients/webhook.ts @@ -78,7 +78,7 @@ 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). */ diff --git a/src/utils.ts b/src/utils.ts index a5d444b79..f11e8db6d 100644 --- a/src/utils.ts +++ b/src/utils.ts @@ -17,7 +17,7 @@ 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 { @@ -253,7 +253,7 @@ export interface PaginationOptions { /** * Standard paginated response format. - * + * * @template Data - The type of items in the response */ export interface PaginatedResponse { @@ -265,10 +265,10 @@ export interface PaginatedResponse { /** * 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 { @@ -288,9 +288,9 @@ export interface PaginatedList { /** * 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; @@ -309,14 +309,14 @@ export function asArray(value: T | T[]): T[] { /** * 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 */ From f21b4d785de4286d9bb02e501d45fb1a07fab6b6 Mon Sep 17 00:00:00 2001 From: Jan Curn Date: Thu, 27 Nov 2025 14:22:37 -0800 Subject: [PATCH 04/18] Better copy --- src/resource_clients/actor.ts | 4 ++-- src/resource_clients/build.ts | 8 ++++---- src/resource_clients/run.ts | 6 +++--- 3 files changed, 9 insertions(+), 9 deletions(-) diff --git a/src/resource_clients/actor.ts b/src/resource_clients/actor.ts index c2fcbc20f..8d7cde0d7 100644 --- a/src/resource_clients/actor.ts +++ b/src/resource_clients/actor.ts @@ -76,7 +76,7 @@ export class ActorClient extends ResourceClient { * @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.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. @@ -175,7 +175,7 @@ export class ActorClient extends ResourceClient { * @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) + * @returns The finished Actor run object with final status (`SUCCEEDED`, `FAILED`, `ABORTED`, or `TIMED-OUT`) * @see https://docs.apify.com/api/v2#/reference/actors/run-collection/run-actor * * @example diff --git a/src/resource_clients/build.ts b/src/resource_clients/build.ts index d6582d742..6b7ce5491 100644 --- a/src/resource_clients/build.ts +++ b/src/resource_clients/build.ts @@ -51,9 +51,9 @@ export class BuildClient extends ResourceClient { /** * Aborts the Actor build. * - * Stops the build process immediately. The build will have an ABORTED status. + * Stops the build process immediately. The build will have an `ABORTED` status. * - * @returns The updated Build object with ABORTED status + * @returns The updated Build object with `ABORTED` status * @see https://docs.apify.com/api/v2#/reference/actor-builds/abort-build/abort-build * * @example @@ -96,9 +96,9 @@ export class BuildClient extends ResourceClient { /** * 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). + * 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. + * Build object (status will be `RUNNING` or `READY`). The promise is NOT rejected based on build status. * * 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) diff --git a/src/resource_clients/run.ts b/src/resource_clients/run.ts index b9f8a1acb..bf7e7fe06 100644 --- a/src/resource_clients/run.ts +++ b/src/resource_clients/run.ts @@ -61,7 +61,7 @@ export class RunClient extends ResourceClient { * * @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 + * @returns The updated ActorRun object with `ABORTING` or `ABORTED` status * @see https://docs.apify.com/api/v2#/reference/actor-runs/abort-run/abort-run * * @example @@ -294,9 +294,9 @@ export class RunClient extends ResourceClient { /** * 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). + * 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. + * Run object (status will be `RUNNING` or `READY`). The promise is NOT rejected based on run status. * * 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) From 1dbbf39a2814f4c7afec0448c087ed499f294914 Mon Sep 17 00:00:00 2001 From: Jan Curn Date: Thu, 27 Nov 2025 14:34:31 -0800 Subject: [PATCH 05/18] Better copy --- src/resource_clients/actor.ts | 38 ++++++++++++------------- src/resource_clients/key_value_store.ts | 20 ++++++------- src/resource_clients/request_queue.ts | 10 +++---- src/resource_clients/run.ts | 16 +++++------ 4 files changed, 42 insertions(+), 42 deletions(-) diff --git a/src/resource_clients/actor.ts b/src/resource_clients/actor.ts index 8d7cde0d7..1f2ff7433 100644 --- a/src/resource_clients/actor.ts +++ b/src/resource_clients/actor.ts @@ -556,8 +556,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; @@ -570,20 +570,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). @@ -591,8 +591,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[]; @@ -635,11 +635,11 @@ export interface ActorStartOptions { */ 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. */ @@ -697,19 +697,19 @@ export interface ActorRun extends ActorRunListItem { export interface ActorRunUsage { /** Compute units consumed (combines CPU and memory usage over time) */ ACTOR_COMPUTE_UNITS?: number; - /** Number of dataset read operations */ + /** Number of Dataset read operations */ DATASET_READS?: number; - /** Number of dataset write operations */ + /** Number of Dataset write operations */ DATASET_WRITES?: number; - /** Number of key-value store read operations */ + /** Number of Key-value store read operations */ KEY_VALUE_STORE_READS?: number; - /** Number of key-value store write operations */ + /** Number of Key-value store write operations */ KEY_VALUE_STORE_WRITES?: number; - /** Number of key-value store list operations */ + /** Number of Key-value store list operations */ KEY_VALUE_STORE_LISTS?: number; - /** Number of request queue read operations */ + /** Number of Request queue read operations */ REQUEST_QUEUE_READS?: number; - /** Number of request queue write operations */ + /** Number of Request queue write operations */ REQUEST_QUEUE_WRITES?: number; /** Internal data transfer within Apify platform (in gigabytes) */ DATA_TRANSFER_INTERNAL_GBYTES?: number; diff --git a/src/resource_clients/key_value_store.ts b/src/resource_clients/key_value_store.ts index b7e12188e..d9d7a11b0 100644 --- a/src/resource_clients/key_value_store.ts +++ b/src/resource_clients/key_value_store.ts @@ -39,7 +39,7 @@ export class KeyValueStoreClient extends ResourceClient { } /** - * Gets the key-value store object from the Apify API. + * 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#/reference/key-value-stores/store-object/get-store @@ -49,9 +49,9 @@ export class KeyValueStoreClient extends ResourceClient { } /** - * Updates the key-value store with specified fields. + * Updates the Key-value store with specified fields. * - * @param newFields - Fields to update in the key-value store + * @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 access level (PUBLIC or PRIVATE) @@ -65,7 +65,7 @@ export class KeyValueStoreClient extends ResourceClient { } /** - * Deletes the key-value store. + * Deletes the Key-value store. * * @see https://docs.apify.com/api/v2#/reference/key-value-stores/store-object/delete-store */ @@ -131,9 +131,9 @@ export class KeyValueStoreClient extends ResourceClient { } /** - * Generates a public URL for accessing a specific record in the key-value store. + * 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, + * If the client has permission to access the Key-value store's URL signing key, * the URL will include a cryptographic signature for authenticated access without * requiring an API token. * @@ -163,9 +163,9 @@ export class KeyValueStoreClient extends ResourceClient { } /** - * Generates a public URL for accessing the list of keys in the key-value store. + * 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, + * If the client has permission to access the Key-value store's URL signing key, * the URL will include a cryptographic signature which allows access without authentication. * * @param options - URL generation options (extends all options from {@link listKeys}) @@ -217,7 +217,7 @@ export class KeyValueStoreClient extends ResourceClient { } /** - * Tests whether a record with the given key exists in the key-value store without retrieving its value. + * Tests whether a record with the given key exists in the Key-value store without retrieving its value. * * This is more efficient than {@link getRecord} when you only need to check for existence. * @@ -320,7 +320,7 @@ export class KeyValueStoreClient extends ResourceClient { } /** - * Stores a record in the key-value store. + * 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 diff --git a/src/resource_clients/request_queue.ts b/src/resource_clients/request_queue.ts index 19382d755..be9a00ce0 100644 --- a/src/resource_clients/request_queue.ts +++ b/src/resource_clients/request_queue.ts @@ -43,7 +43,7 @@ export class RequestQueueClient extends ResourceClient { } /** - * Gets the request queue object from the Apify API. + * 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#/reference/request-queues/queue/get-request-queue @@ -53,9 +53,9 @@ export class RequestQueueClient extends ResourceClient { } /** - * Updates the request queue with specified fields. + * Updates the Request queue with specified fields. * - * @param newFields - Fields to update in the request queue + * @param newFields - Fields to update in the Request queue * @returns The updated RequestQueue object * @see https://docs.apify.com/api/v2#/reference/request-queues/queue/update-request-queue */ @@ -66,7 +66,7 @@ export class RequestQueueClient extends ResourceClient { } /** - * Deletes the request queue. + * Deletes the Request queue. * * @see https://docs.apify.com/api/v2#/reference/request-queues/queue/delete-request-queue */ @@ -233,7 +233,7 @@ export class RequestQueueClient extends ResourceClient { } /** - * Writes requests to request queue in batch. + * Writes requests to Request queue in batch. * * @private */ diff --git a/src/resource_clients/run.ts b/src/resource_clients/run.ts index bf7e7fe06..a79e44ad8 100644 --- a/src/resource_clients/run.ts +++ b/src/resource_clients/run.ts @@ -102,7 +102,7 @@ export class RunClient extends ResourceClient { /** * Transforms the Actor run into a run of another Actor (metamorph). * - * This operation preserves the run ID, storages (dataset, key-value store, request queue), + * 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. * @@ -216,7 +216,7 @@ export class RunClient extends ResourceClient { * 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. + * 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. @@ -351,14 +351,14 @@ export class RunClient extends ResourceClient { } /** - * Returns a client for the default key-value store of this Actor run. + * 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 + * @returns A client for accessing the run's default Key-value store * @see https://docs.apify.com/api/v2#/reference/actor-runs/run-object-and-its-storages * * @example * ```javascript - * // Access run's key-value store + * // Access run's Key-value store * const output = await client.run('run-id').keyValueStore().getRecord('OUTPUT'); * ``` */ @@ -371,14 +371,14 @@ export class RunClient extends ResourceClient { } /** - * Returns a client for the default request queue of this Actor run. + * Returns a client for the default Request queue of this Actor run. * - * @returns A client for accessing the run's default request queue + * @returns A client for accessing the run's default Request queue * @see https://docs.apify.com/api/v2#/reference/actor-runs/run-object-and-its-storages * * @example * ```javascript - * // Access run's request queue + * // Access run's Request queue * const { items } = await client.run('run-id').requestQueue().listHead(); * ``` */ From 7f58e0cf174f739bf82d0126a8a443ced420be41 Mon Sep 17 00:00:00 2001 From: Jan Curn Date: Thu, 27 Nov 2025 14:49:23 -0800 Subject: [PATCH 06/18] Fixed links to API docs --- src/apify_client.ts | 76 +++++++++---------- src/resource_clients/actor.ts | 24 +++--- src/resource_clients/actor_collection.ts | 4 +- src/resource_clients/actor_env_var.ts | 6 +- .../actor_env_var_collection.ts | 4 +- src/resource_clients/actor_version.ts | 10 +-- .../actor_version_collection.ts | 4 +- src/resource_clients/build.ts | 8 +- src/resource_clients/build_collection.ts | 4 +- src/resource_clients/dataset.ts | 12 +-- src/resource_clients/dataset_collection.ts | 4 +- src/resource_clients/key_value_store.ts | 16 ++-- .../key_value_store_collection.ts | 4 +- src/resource_clients/log.ts | 4 +- src/resource_clients/request_queue.ts | 28 +++---- .../request_queue_collection.ts | 4 +- src/resource_clients/run.ts | 22 +++--- src/resource_clients/run_collection.ts | 4 +- src/resource_clients/schedule.ts | 8 +- src/resource_clients/schedule_collection.ts | 4 +- src/resource_clients/store_collection.ts | 2 +- src/resource_clients/task.ts | 20 ++--- src/resource_clients/task_collection.ts | 4 +- src/resource_clients/user.ts | 8 +- src/resource_clients/webhook.ts | 10 +-- src/resource_clients/webhook_collection.ts | 4 +- src/resource_clients/webhook_dispatch.ts | 2 +- .../webhook_dispatch_collection.ts | 4 +- 28 files changed, 152 insertions(+), 152 deletions(-) diff --git a/src/apify_client.ts b/src/apify_client.ts index 5e10ceead..8cb590641 100644 --- a/src/apify_client.ts +++ b/src/apify_client.ts @@ -129,8 +129,8 @@ export class ApifyClient { * * Provides access to the Actor collection, allowing you to list, create, and search for Actors. * - * @returns A client for the Actor collection - * @see https://docs.apify.com/api/v2#/reference/actors/actor-collection + * @returns A client for the Actors collection + * @see https://docs.apify.com/api/v2/acts-get */ actors(): ActorCollectionClient { return new ActorCollectionClient(this._options()); @@ -143,8 +143,8 @@ export class ApifyClient { * runs, versions, and webhooks. * * @param id - Actor ID or username/name - * @returns A client for the specified Actor - * @see https://docs.apify.com/api/v2#/reference/actors/actor-object + * @returns A client for the specific Actor + * @see https://docs.apify.com/api/v2/act-get * * @example * ```javascript @@ -166,8 +166,8 @@ export class ApifyClient { * * Lists all builds across all of your Actors. * - * @returns A client for the build collection - * @see https://docs.apify.com/api/v2#/reference/actor-builds/build-collection + * @returns A client for Actor builds collection + * @see https://docs.apify.com/api/v2/actor-builds-get */ builds(): BuildCollectionClient { return new BuildCollectionClient(this._options()); @@ -180,7 +180,7 @@ export class ApifyClient { * * @param id - Build ID * @returns A client for the specified build - * @see https://docs.apify.com/api/v2#/reference/actor-builds/build-object + * @see https://docs.apify.com/api/v2/actor-build-get */ build(id: string): BuildClient { ow(id, ow.string.nonEmpty); @@ -196,8 +196,8 @@ export class ApifyClient { * * Datasets store structured data results from Actor runs. Use this to list or create datasets. * - * @returns A client for the dataset collection - * @see https://docs.apify.com/api/v2#/reference/datasets/dataset-collection + * @returns A client for the Datasets collection + * @see https://docs.apify.com/api/v2/datasets-get */ datasets(): DatasetCollectionClient { return new DatasetCollectionClient(this._options()); @@ -211,8 +211,8 @@ export class ApifyClient { * * @template Data - Type of items stored in the dataset * @param id - Dataset ID or name - * @returns A client for the specified dataset - * @see https://docs.apify.com/api/v2#/reference/datasets/dataset + * @returns A client for the specific Dataset + * @see https://docs.apify.com/api/v2/dataset-get * * @example * ```javascript @@ -242,8 +242,8 @@ export class ApifyClient { * * Key-value stores are used to store arbitrary data records or files. * - * @returns A client for the key-value store collection - * @see https://docs.apify.com/api/v2#/reference/key-value-stores/store-collection + * @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()); @@ -256,8 +256,8 @@ export class ApifyClient { * any type of data including text, JSON, images, and other files. * * @param id - Key-value store ID or name - * @returns A client for the specified key-value store - * @see https://docs.apify.com/api/v2#/reference/key-value-stores/store-object + * @returns A client for the specific Key-value store + * @see https://docs.apify.com/api/v2/key-value-store-get * * @example * ```javascript @@ -282,7 +282,7 @@ export class ApifyClient { * * @param buildOrRunId - Build ID or run ID * @returns A client for accessing logs - * @see https://docs.apify.com/api/v2#/reference/logs + * @see https://docs.apify.com/api/v2/log-get */ log(buildOrRunId: string): LogClient { ow(buildOrRunId, ow.string.nonEmpty); @@ -298,8 +298,8 @@ export class ApifyClient { * * Request queues store URLs to be crawled, along with their metadata. * - * @returns A client for the request queue collection - * @see https://docs.apify.com/api/v2#/reference/request-queues/queue-collection + * @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()); @@ -313,8 +313,8 @@ export class ApifyClient { * * @param id - Request queue ID or name * @param options - Configuration options for the request queue client - * @returns A client for the specified request queue - * @see https://docs.apify.com/api/v2#/reference/request-queues/queue + * @returns A client for the specific Request queue + * @see https://docs.apify.com/api/v2/request-queue-get * * @example * ```javascript @@ -349,7 +349,7 @@ export class ApifyClient { * Lists all runs across all of your Actors. * * @returns A client for the run collection - * @see https://docs.apify.com/api/v2#/reference/actor-runs/run-collection + * @see https://docs.apify.com/api/v2/actor-runs-get */ runs(): RunCollectionClient { return new RunCollectionClient({ @@ -366,7 +366,7 @@ export class ApifyClient { * * @param id - Run ID * @returns A client for the specified run - * @see https://docs.apify.com/api/v2#/reference/actor-runs/run-object-and-its-storages + * @see https://docs.apify.com/api/v2/actor-run-get * * @example * ```javascript @@ -392,7 +392,7 @@ export class ApifyClient { * 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#/reference/actor-tasks/task-collection + * @see https://docs.apify.com/api/v2/actor-tasks-get */ tasks(): TaskCollectionClient { return new TaskCollectionClient(this._options()); @@ -405,7 +405,7 @@ export class ApifyClient { * * @param id - Task ID or username/task-name * @returns A client for the specified task - * @see https://docs.apify.com/api/v2#/reference/actor-tasks/task-object + * @see https://docs.apify.com/api/v2/actor-task-get * * @example * ```javascript @@ -427,8 +427,8 @@ export class ApifyClient { * * Schedules automatically start Actor or task runs at specified times. * - * @returns A client for the schedule collection - * @see https://docs.apify.com/api/v2#/reference/schedules/schedules-collection + * @returns A client for the Schedules collection + * @see https://docs.apify.com/api/v2/schedules-get */ schedules(): ScheduleCollectionClient { return new ScheduleCollectionClient(this._options()); @@ -440,8 +440,8 @@ export class ApifyClient { * Use this to get, update, or delete a schedule. * * @param id - Schedule ID - * @returns A client for the specified schedule - * @see https://docs.apify.com/api/v2#/reference/schedules/schedule-object + * @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); @@ -459,7 +459,7 @@ export class ApifyClient { * * @param id - User ID or username. Defaults to 'me' (current user) * @returns A client for the user - * @see https://docs.apify.com/api/v2#/reference/users + * @see https://docs.apify.com/api/v2/user-get */ user(id = ME_USER_NAME_PLACEHOLDER): UserClient { ow(id, ow.string.nonEmpty); @@ -475,8 +475,8 @@ export class ApifyClient { * * Webhooks notify external services when specific events occur (e.g., Actor run finishes). * - * @returns A client for the webhook collection - * @see https://docs.apify.com/api/v2#/reference/webhooks/webhook-collection + * @returns A client for the Webhooks collection + * @see https://docs.apify.com/api/v2/webhooks-get */ webhooks(): WebhookCollectionClient { return new WebhookCollectionClient(this._options()); @@ -488,8 +488,8 @@ export class ApifyClient { * Use this to get, update, delete, or test a webhook. * * @param id - Webhook ID - * @returns A client for the specified webhook - * @see https://docs.apify.com/api/v2#/reference/webhooks/webhook-object + * @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); @@ -505,8 +505,8 @@ export class ApifyClient { * * Webhook dispatches represent individual invocations of webhooks. * - * @returns A client for the webhook dispatch collection - * @see https://docs.apify.com/api/v2#/reference/webhook-dispatches + * @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()); @@ -516,8 +516,8 @@ export class ApifyClient { * Returns a client for a specific webhook dispatch. * * @param id - Webhook dispatch ID - * @returns A client for the specified webhook dispatch - * @see https://docs.apify.com/api/v2#/reference/webhook-dispatches/webhook-dispatch-object + * @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); @@ -534,7 +534,7 @@ export class ApifyClient { * Use this to search and retrieve information about public Actors. * * @returns A client for the Apify Store - * @see https://docs.apify.com/api/v2/#/reference/store + * @see https://docs.apify.com/api/v2/store-actors-get */ store(): StoreCollectionClient { return new StoreCollectionClient(this._options()); diff --git a/src/resource_clients/actor.ts b/src/resource_clients/actor.ts index 1f2ff7433..2bc48fca9 100644 --- a/src/resource_clients/actor.ts +++ b/src/resource_clients/actor.ts @@ -34,7 +34,7 @@ export class ActorClient extends ResourceClient { * 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#/reference/actors/actor-object/get-actor + * @see https://docs.apify.com/api/v2/act-get */ async get(): Promise { return this._get(); @@ -45,7 +45,7 @@ export class ActorClient extends ResourceClient { * * @param newFields - Fields to update in the Actor * @returns The updated Actor object - * @see https://docs.apify.com/api/v2#/reference/actors/actor-object/update-actor + * @see https://docs.apify.com/api/v2/act-put */ async update(newFields: ActorUpdateOptions): Promise { ow(newFields, ow.object); @@ -56,7 +56,7 @@ export class ActorClient extends ResourceClient { /** * Deletes the Actor. * - * @see https://docs.apify.com/api/v2#/reference/actors/actor-object/delete-actor + * @see https://docs.apify.com/api/v2/act-delete */ async delete(): Promise { return this._delete(); @@ -81,7 +81,7 @@ export class ActorClient extends ResourceClient { * @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#/reference/actors/run-collection/run-actor + * @see https://docs.apify.com/api/v2/act-runs-post * * @example * ```javascript @@ -176,7 +176,7 @@ export class ActorClient extends ResourceClient { * @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#/reference/actors/run-collection/run-actor + * @see https://docs.apify.com/api/v2/act-runs-post * * @example * ```javascript @@ -248,7 +248,7 @@ export class ActorClient extends ResourceClient { * @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#/reference/actors/build-collection/build-actor + * @see https://docs.apify.com/api/v2/act-builds-post * * @example * ```javascript @@ -316,7 +316,7 @@ export class ActorClient extends ResourceClient { * * @param options - Options to filter the last run * @returns A client for the last run - * @see https://docs.apify.com/api/v2#/reference/actors/last-run-object-and-its-storages + * @see https://docs.apify.com/api/v2/act-runs-last-get * * @example * ```javascript @@ -346,7 +346,7 @@ export class ActorClient extends ResourceClient { * 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#/reference/actors/build-collection + * @see https://docs.apify.com/api/v2/act-builds-get */ builds(): BuildCollectionClient { return new BuildCollectionClient( @@ -360,7 +360,7 @@ export class ActorClient extends ResourceClient { * 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#/reference/actors/run-collection + * @see https://docs.apify.com/api/v2/act-runs-get */ runs(): RunCollectionClient { return new RunCollectionClient( @@ -375,7 +375,7 @@ export class ActorClient extends ResourceClient { * * @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#/reference/actors/version-object + * @see https://docs.apify.com/api/v2/act-version-get */ version(versionNumber: string): ActorVersionClient { ow(versionNumber, ow.string); @@ -390,7 +390,7 @@ export class ActorClient extends ResourceClient { * 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#/reference/actors/version-collection + * @see https://docs.apify.com/api/v2/act-versions-get */ versions(): ActorVersionCollectionClient { return new ActorVersionCollectionClient(this._subResourceOptions()); @@ -400,7 +400,7 @@ export class ActorClient extends ResourceClient { * 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#/reference/actors/webhook-collection + * @see https://docs.apify.com/api/v2/act-webhooks-get */ webhooks(): WebhookCollectionClient { return new WebhookCollectionClient(this._subResourceOptions()); diff --git a/src/resource_clients/actor_collection.ts b/src/resource_clients/actor_collection.ts index 870a883aa..f04c33797 100644 --- a/src/resource_clients/actor_collection.ts +++ b/src/resource_clients/actor_collection.ts @@ -18,7 +18,7 @@ export class ActorCollectionClient extends ResourceCollectionClient { } /** - * https://docs.apify.com/api/v2#/reference/actors/actor-collection/get-list-of-actors + * https://docs.apify.com/api/v2/acts-get * * 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. @@ -49,7 +49,7 @@ export class ActorCollectionClient extends ResourceCollectionClient { } /** - * https://docs.apify.com/api/v2#/reference/actors/actor-collection/create-actor + * 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 f2643ddc7..619af0715 100644 --- a/src/resource_clients/actor_env_var.ts +++ b/src/resource_clients/actor_env_var.ts @@ -16,14 +16,14 @@ export class ActorEnvVarClient extends ResourceClient { } /** - * https://docs.apify.com/api/v2#/reference/actors/environment-variable-object/get-environment-variable + * 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 + * https://docs.apify.com/api/v2/act-version-env-var-put */ async update(actorEnvVar: ActorEnvironmentVariable): Promise { ow(actorEnvVar, ow.object); @@ -31,7 +31,7 @@ export class ActorEnvVarClient extends ResourceClient { } /** - * https://docs.apify.com/api/v2#/reference/actors/environment-variable-object/delete-environment-variable + * 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 89e7d2b7a..a1f9dca84 100644 --- a/src/resource_clients/actor_env_var_collection.ts +++ b/src/resource_clients/actor_env_var_collection.ts @@ -17,7 +17,7 @@ export class ActorEnvVarCollectionClient extends ResourceCollectionClient { } /** - * https://docs.apify.com/api/v2#/reference/actors/environment-variable-collection/get-list-of-environment-variables + * https://docs.apify.com/api/v2/act-version-env-vars-get * * 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. @@ -47,7 +47,7 @@ export class ActorEnvVarCollectionClient extends ResourceCollectionClient { } /** - * https://docs.apify.com/api/v2#/reference/actors/environment-variable-collection/create-environment-variable + * 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 f3f2490b2..508906741 100644 --- a/src/resource_clients/actor_version.ts +++ b/src/resource_clients/actor_version.ts @@ -17,14 +17,14 @@ export class ActorVersionClient extends ResourceClient { } /** - * https://docs.apify.com/api/v2#/reference/actors/version-object/get-version + * 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 + * https://docs.apify.com/api/v2/act-version-put */ async update(newFields: ActorVersion): Promise { ow(newFields, ow.object); @@ -33,14 +33,14 @@ export class ActorVersionClient extends ResourceClient { } /** - * https://docs.apify.com/api/v2#/reference/actors/version-object/delete-version + * 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 + * TODO: https://docs.apify.com/api/v2/act-version-env-var-get */ envVar(envVarName: string): ActorEnvVarClient { ow(envVarName, ow.string); @@ -52,7 +52,7 @@ export class ActorVersionClient extends ResourceClient { } /** - * TODO: https://docs.apify.com/api/v2#/reference/actors/env-var-collection + * TODO: https://docs.apify.com/api/v2/act-version-env-vars-get * @return {ActorVersionCollectionClient} */ envVars(): ActorEnvVarCollectionClient { diff --git a/src/resource_clients/actor_version_collection.ts b/src/resource_clients/actor_version_collection.ts index 160b1dafc..e0b1a3035 100644 --- a/src/resource_clients/actor_version_collection.ts +++ b/src/resource_clients/actor_version_collection.ts @@ -17,7 +17,7 @@ export class ActorVersionCollectionClient extends ResourceCollectionClient { } /** - * https://docs.apify.com/api/v2#/reference/actors/version-collection/get-list-of-versions + * https://docs.apify.com/api/v2/act-versions-get * * 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. @@ -48,7 +48,7 @@ export class ActorVersionCollectionClient extends ResourceCollectionClient { } /** - * https://docs.apify.com/api/v2#/reference/actors/version-collection/create-version + * 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 6b7ce5491..a478cbb53 100644 --- a/src/resource_clients/build.ts +++ b/src/resource_clients/build.ts @@ -25,7 +25,7 @@ export class BuildClient extends ResourceClient { * @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#/reference/actor-builds/build-object/get-build + * @see https://docs.apify.com/api/v2/actor-build-get * * @example * ```javascript @@ -54,7 +54,7 @@ export class BuildClient extends ResourceClient { * 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#/reference/actor-builds/abort-build/abort-build + * @see https://docs.apify.com/api/v2/actor-build-abort-post * * @example * ```javascript @@ -74,7 +74,7 @@ export class BuildClient extends ResourceClient { /** * Deletes the Actor build. * - * @see https://docs.apify.com/api/v2#/reference/actor-builds/delete-build/delete-build + * @see https://docs.apify.com/api/v2/actor-build-delete */ async delete(): Promise { return this._delete(); @@ -138,7 +138,7 @@ export class BuildClient extends ResourceClient { * 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#/reference/actor-builds/build-log + * @see https://docs.apify.com/api/v2/actor-build-log-get * * @example * ```javascript diff --git a/src/resource_clients/build_collection.ts b/src/resource_clients/build_collection.ts index 460e0f515..07a53777a 100644 --- a/src/resource_clients/build_collection.ts +++ b/src/resource_clients/build_collection.ts @@ -17,8 +17,8 @@ export class BuildCollectionClient extends ResourceCollectionClient { } /** - * https://docs.apify.com/api/v2#/reference/actors/build-collection/get-list-of-builds - * + * https://docs.apify.com/api/v2/actor-builds-get + */ * 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 diff --git a/src/resource_clients/dataset.ts b/src/resource_clients/dataset.ts index e36e6cc64..834ab4b96 100644 --- a/src/resource_clients/dataset.ts +++ b/src/resource_clients/dataset.ts @@ -32,7 +32,7 @@ export class DatasetClient< * 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#/reference/datasets/dataset/get-dataset + * @see https://docs.apify.com/api/v2/dataset-get */ async get(): Promise { return this._get({}, SMALL_TIMEOUT_MILLIS); @@ -43,7 +43,7 @@ export class DatasetClient< * * @param newFields - Fields to update in the dataset * @returns The updated Dataset object - * @see https://docs.apify.com/api/v2#/reference/datasets/dataset/update-dataset + * @see https://docs.apify.com/api/v2/dataset-put */ async update(newFields: DatasetClientUpdateOptions): Promise { ow(newFields, ow.object); @@ -54,7 +54,7 @@ export class DatasetClient< /** * Deletes the dataset. * - * @see https://docs.apify.com/api/v2#/reference/datasets/dataset/delete-dataset + * @see https://docs.apify.com/api/v2/dataset-delete */ async delete(): Promise { return this._delete(SMALL_TIMEOUT_MILLIS); @@ -80,7 +80,7 @@ export class DatasetClient< * @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#/reference/datasets/item-collection/get-items + * @see https://docs.apify.com/api/v2/dataset-items-get * * @example * ```javascript @@ -150,7 +150,7 @@ export class DatasetClient< * @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#/reference/datasets/item-collection/get-items + * @see https://docs.apify.com/api/v2/dataset-items-get * * @example * ```javascript @@ -222,7 +222,7 @@ export class DatasetClient< * * @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#/reference/datasets/item-collection/put-items + * @see https://docs.apify.com/api/v2/dataset-items-post * * @example * ```javascript diff --git a/src/resource_clients/dataset_collection.ts b/src/resource_clients/dataset_collection.ts index f239a45ae..ff81e2d62 100644 --- a/src/resource_clients/dataset_collection.ts +++ b/src/resource_clients/dataset_collection.ts @@ -17,7 +17,7 @@ export class DatasetCollectionClient extends ResourceCollectionClient { } /** - * https://docs.apify.com/api/v2#/reference/datasets/dataset-collection/get-list-of-datasets + * https://docs.apify.com/api/v2/datasets-get * * 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. @@ -47,7 +47,7 @@ export class DatasetCollectionClient extends ResourceCollectionClient { } /** - * https://docs.apify.com/api/v2#/reference/datasets/dataset-collection/create-dataset + * 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 d9d7a11b0..807dfdbe0 100644 --- a/src/resource_clients/key_value_store.ts +++ b/src/resource_clients/key_value_store.ts @@ -42,7 +42,7 @@ export class KeyValueStoreClient extends ResourceClient { * 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#/reference/key-value-stores/store-object/get-store + * @see https://docs.apify.com/api/v2/key-value-store-get */ async get(): Promise { return this._get({}, SMALL_TIMEOUT_MILLIS); @@ -56,7 +56,7 @@ export class KeyValueStoreClient extends ResourceClient { * @param newFields.title - New title for the store * @param newFields.generalAccess - General access level (PUBLIC or PRIVATE) * @returns The updated KeyValueStore object - * @see https://docs.apify.com/api/v2#/reference/key-value-stores/store-object/update-store + * @see https://docs.apify.com/api/v2/key-value-store-put */ async update(newFields: KeyValueClientUpdateOptions): Promise { ow(newFields, ow.object); @@ -67,7 +67,7 @@ export class KeyValueStoreClient extends ResourceClient { /** * Deletes the Key-value store. * - * @see https://docs.apify.com/api/v2#/reference/key-value-stores/store-object/delete-store + * @see https://docs.apify.com/api/v2/key-value-store-delete */ async delete(): Promise { return this._delete(SMALL_TIMEOUT_MILLIS); @@ -85,7 +85,7 @@ export class KeyValueStoreClient extends ResourceClient { * @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#/reference/key-value-stores/key-collection/get-list-of-keys + * @see https://docs.apify.com/api/v2/key-value-store-keys-get * * @example * ```javascript @@ -223,7 +223,7 @@ export class KeyValueStoreClient extends ResourceClient { * * @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#/reference/key-value-stores/record/get-record + * @see https://docs.apify.com/api/v2/key-value-store-record-get * * @example * ```javascript @@ -257,7 +257,7 @@ 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 + * https://docs.apify.com/api/v2/key-value-store-record-get */ async getRecord(key: string): Promise | undefined>; @@ -340,7 +340,7 @@ export class KeyValueStoreClient extends ResourceClient { * @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#/reference/key-value-stores/record/put-record + * @see https://docs.apify.com/api/v2/key-value-store-record-put * * @example * ```javascript @@ -423,7 +423,7 @@ export class KeyValueStoreClient extends ResourceClient { * Deletes a record from the key-value store. * * @param key - The record key to delete - * @see https://docs.apify.com/api/v2#/reference/key-value-stores/record/delete-record + * @see https://docs.apify.com/api/v2/key-value-store-record-delete * * @example * ```javascript diff --git a/src/resource_clients/key_value_store_collection.ts b/src/resource_clients/key_value_store_collection.ts index 3300b18d6..a5f9eb53d 100644 --- a/src/resource_clients/key_value_store_collection.ts +++ b/src/resource_clients/key_value_store_collection.ts @@ -17,7 +17,7 @@ export class KeyValueStoreCollectionClient extends ResourceCollectionClient { } /** - * https://docs.apify.com/api/v2#/reference/key-value-stores/store-collection/get-list-of-key-value-stores + * https://docs.apify.com/api/v2/key-value-stores-get * * 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. @@ -49,7 +49,7 @@ export class KeyValueStoreCollectionClient extends ResourceCollectionClient { } /** - * https://docs.apify.com/api/v2#/reference/key-value-stores/store-collection/create-key-value-store + * 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 c77b43bb5..4a17c4717 100644 --- a/src/resource_clients/log.ts +++ b/src/resource_clients/log.ts @@ -24,7 +24,7 @@ export class LogClient extends ResourceClient { } /** - * https://docs.apify.com/api/v2#/reference/logs/log/get-log + * https://docs.apify.com/api/v2/log-get */ async get(options: LogOptions = {}): Promise { const requestOpts: ApifyRequestConfig = { @@ -45,7 +45,7 @@ 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 + * 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 be9a00ce0..f4bca4795 100644 --- a/src/resource_clients/request_queue.ts +++ b/src/resource_clients/request_queue.ts @@ -46,7 +46,7 @@ export class RequestQueueClient extends ResourceClient { * 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#/reference/request-queues/queue/get-request-queue + * @see https://docs.apify.com/api/v2/request-queue-get */ async get(): Promise { return this._get({}, SMALL_TIMEOUT_MILLIS); @@ -57,7 +57,7 @@ export class RequestQueueClient extends ResourceClient { * * @param newFields - Fields to update in the Request queue * @returns The updated RequestQueue object - * @see https://docs.apify.com/api/v2#/reference/request-queues/queue/update-request-queue + * @see https://docs.apify.com/api/v2/request-queue-put */ async update(newFields: RequestQueueClientUpdateOptions): Promise { ow(newFields, ow.object); @@ -68,7 +68,7 @@ export class RequestQueueClient extends ResourceClient { /** * Deletes the Request queue. * - * @see https://docs.apify.com/api/v2#/reference/request-queues/queue/delete-request-queue + * @see https://docs.apify.com/api/v2/request-queue-delete */ async delete(): Promise { return this._delete(SMALL_TIMEOUT_MILLIS); @@ -82,7 +82,7 @@ export class RequestQueueClient extends ResourceClient { * * @param options - Options for listing (e.g., limit) * @returns List of requests from the queue head - * @see https://docs.apify.com/api/v2#/reference/request-queues/queue-head/get-head + * @see https://docs.apify.com/api/v2/request-queue-head-get */ async listHead(options: RequestQueueClientListHeadOptions = {}): Promise { ow( @@ -118,7 +118,7 @@ export class RequestQueueClient extends ResourceClient { * @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#/reference/request-queues/queue-head-with-locks/get-head-and-lock + * @see https://docs.apify.com/api/v2/request-queue-head-lock-post * * @example * ```javascript @@ -179,7 +179,7 @@ export class RequestQueueClient extends ResourceClient { * @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#/reference/request-queues/request-collection/add-request + * @see https://docs.apify.com/api/v2/request-queue-requests-post * * @example * ```javascript @@ -356,7 +356,7 @@ export class RequestQueueClient extends ResourceClient { * @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#/reference/request-queues/batch-request-operations/add-requests + * @see https://docs.apify.com/api/v2/request-queue-requests-batch-post * * @example * ```javascript @@ -445,7 +445,7 @@ export class RequestQueueClient extends ResourceClient { * * @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#/reference/request-queues/batch-request-operations/delete-requests + * @see https://docs.apify.com/api/v2/request-queue-requests-batch-delete */ async batchDeleteRequests( requests: RequestQueueClientRequestToDelete[], @@ -478,7 +478,7 @@ export class RequestQueueClient extends ResourceClient { * * @param id - Request ID * @returns The request object, or `undefined` if not found - * @see https://docs.apify.com/api/v2#/reference/request-queues/request/get-request + * @see https://docs.apify.com/api/v2/request-queue-request-get */ async getRequest(id: string): Promise { ow(id, ow.string); @@ -504,7 +504,7 @@ export class RequestQueueClient extends ResourceClient { * @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#/reference/request-queues/request/update-request + * @see https://docs.apify.com/api/v2/request-queue-request-put */ async updateRequest( request: RequestQueueClientRequestSchema, @@ -568,7 +568,7 @@ export class RequestQueueClient extends ResourceClient { * @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#/reference/request-queues/request-lock/prolong-request-lock + * @see https://docs.apify.com/api/v2/request-queue-request-lock-put * * @example * ```javascript @@ -615,7 +615,7 @@ export class RequestQueueClient extends ResourceClient { * * @param id - Request ID * @param options - Options such as whether to move to front - * @see https://docs.apify.com/api/v2#/reference/request-queues/request-lock/delete-request-lock + * @see https://docs.apify.com/api/v2/request-queue-request-lock-delete */ async deleteRequestLock(id: string, options: RequestQueueClientDeleteRequestLockOptions = {}): Promise { ow(id, ow.string); @@ -645,7 +645,7 @@ export class RequestQueueClient extends ResourceClient { * * @param options - Pagination options * @returns List of requests with pagination information - * @see https://docs.apify.com/api/v2#/reference/request-queues/request-collection/list-requests + * @see https://docs.apify.com/api/v2/request-queue-requests-get */ async listRequests( options: RequestQueueClientListRequestsOptions = {}, @@ -702,7 +702,7 @@ export class RequestQueueClient extends ResourceClient { * * @param options - Pagination options * @returns An async iterable of request pages - * @see https://docs.apify.com/api/v2#/reference/request-queues/request-collection/list-requests + * @see https://docs.apify.com/api/v2/request-queue-requests-get * * @example * ```javascript diff --git a/src/resource_clients/request_queue_collection.ts b/src/resource_clients/request_queue_collection.ts index 1076f1d08..d17e1ac94 100644 --- a/src/resource_clients/request_queue_collection.ts +++ b/src/resource_clients/request_queue_collection.ts @@ -17,7 +17,7 @@ export class RequestQueueCollectionClient extends ResourceCollectionClient { } /** - * https://docs.apify.com/api/v2#/reference/request-queues/queue-collection/get-list-of-request-queues + * https://docs.apify.com/api/v2/request-queues-get * * 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. @@ -49,7 +49,7 @@ export class RequestQueueCollectionClient extends ResourceCollectionClient { } /** - * https://docs.apify.com/api/v2#/reference/request-queues/queue-collection/create-request-queue + * 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 a79e44ad8..c9439fc56 100644 --- a/src/resource_clients/run.ts +++ b/src/resource_clients/run.ts @@ -33,7 +33,7 @@ export class RunClient extends ResourceClient { * @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#/reference/actor-runs/run-object/get-run + * @see https://docs.apify.com/api/v2/actor-run-get * * @example * ```javascript @@ -62,7 +62,7 @@ export class RunClient extends ResourceClient { * @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#/reference/actor-runs/abort-run/abort-run + * @see https://docs.apify.com/api/v2/actor-run-abort-post * * @example * ```javascript @@ -93,7 +93,7 @@ export class RunClient extends ResourceClient { /** * Deletes the Actor run. * - * @see https://docs.apify.com/api/v2#/reference/actor-runs/delete-run/delete-run + * @see https://docs.apify.com/api/v2/actor-run-delete */ async delete(): Promise { return this._delete(); @@ -112,7 +112,7 @@ export class RunClient extends ResourceClient { * @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#/reference/actor-runs/metamorph-run/metamorph-run + * @see https://docs.apify.com/api/v2/actor-run-metamorph-post * * @example * ```javascript @@ -172,7 +172,7 @@ export class RunClient extends ResourceClient { * with a fresh environment. * * @returns The updated ActorRun object - * @see https://docs.apify.com/api/v2#/reference/actor-runs/reboot-run/reboot-run + * @see https://docs.apify.com/api/v2/actor-run-reboot-post * * @example * ```javascript @@ -226,7 +226,7 @@ export class RunClient extends ResourceClient { * @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#/reference/actor-runs/resurrect-run/resurrect-run + * @see https://docs.apify.com/api/v2/post-resurrect-run * * @example * ```javascript @@ -258,7 +258,7 @@ export class RunClient extends ResourceClient { } /** - * https://docs.apify.com/api/v2#/reference/actor-runs/charge-events-in-run + * https://docs.apify.com/api/v2/post-charge-run */ async charge(options: RunChargeOptions): Promise>> { ow( @@ -334,7 +334,7 @@ export class RunClient extends ResourceClient { * Returns a client for the default dataset of this Actor run. * * @returns A client for accessing the run's default dataset - * @see https://docs.apify.com/api/v2#/reference/actor-runs/run-object-and-its-storages + * @see https://docs.apify.com/api/v2/actor-run-get * * @example * ```javascript @@ -354,7 +354,7 @@ export class RunClient extends ResourceClient { * 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#/reference/actor-runs/run-object-and-its-storages + * @see https://docs.apify.com/api/v2/actor-run-get * * @example * ```javascript @@ -374,7 +374,7 @@ export class RunClient extends ResourceClient { * Returns a client for the default Request queue of this Actor run. * * @returns A client for accessing the run's default Request queue - * @see https://docs.apify.com/api/v2#/reference/actor-runs/run-object-and-its-storages + * @see https://docs.apify.com/api/v2/actor-run-get * * @example * ```javascript @@ -394,7 +394,7 @@ export class RunClient extends ResourceClient { * 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#/reference/actor-runs/run-object-and-its-storages + * @see https://docs.apify.com/api/v2/actor-run-get * * @example * ```javascript diff --git a/src/resource_clients/run_collection.ts b/src/resource_clients/run_collection.ts index 5ad2e77d0..6062a4f61 100644 --- a/src/resource_clients/run_collection.ts +++ b/src/resource_clients/run_collection.ts @@ -19,8 +19,8 @@ export class RunCollectionClient extends ResourceCollectionClient { } /** - * https://docs.apify.com/api/v2#/reference/actors/run-collection/get-list-of-runs - * + * https://docs.apify.com/api/v2/actor-runs-get + */ * 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 diff --git a/src/resource_clients/schedule.ts b/src/resource_clients/schedule.ts index 2bdb1b888..8401d2942 100644 --- a/src/resource_clients/schedule.ts +++ b/src/resource_clients/schedule.ts @@ -20,14 +20,14 @@ export class ScheduleClient extends ResourceClient { } /** - * https://docs.apify.com/api/v2#/reference/schedules/schedule-object/get-schedule + * 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 + * https://docs.apify.com/api/v2/schedule-put */ async update(newFields: ScheduleCreateOrUpdateData): Promise { ow(newFields, ow.object); @@ -35,14 +35,14 @@ export class ScheduleClient extends ResourceClient { } /** - * https://docs.apify.com/api/v2#/reference/schedules/schedule-object/delete-schedule + * 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 + * https://docs.apify.com/api/v2/schedule-log-get */ async getLog(): Promise { const requestOpts: ApifyRequestConfig = { diff --git a/src/resource_clients/schedule_collection.ts b/src/resource_clients/schedule_collection.ts index 781832e03..5eb7a34c5 100644 --- a/src/resource_clients/schedule_collection.ts +++ b/src/resource_clients/schedule_collection.ts @@ -17,7 +17,7 @@ export class ScheduleCollectionClient extends ResourceCollectionClient { } /** - * https://docs.apify.com/api/v2#/reference/schedules/schedules-collection/get-list-of-schedules + * https://docs.apify.com/api/v2/schedules-get * * 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. @@ -46,7 +46,7 @@ export class ScheduleCollectionClient extends ResourceCollectionClient { } /** - * https://docs.apify.com/api/v2#/reference/schedules/schedules-collection/create-schedule + * 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 cfa2f4aa2..8e4fb5d81 100644 --- a/src/resource_clients/store_collection.ts +++ b/src/resource_clients/store_collection.ts @@ -17,7 +17,7 @@ export class StoreCollectionClient extends ResourceCollectionClient { } /** - * https://docs.apify.com/api/v2/#/reference/store/store-actors-collection/get-list-of-actors-in-store + * https://docs.apify.com/api/v2/store-actors-get * * 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. diff --git a/src/resource_clients/task.ts b/src/resource_clients/task.ts index bdd86ba32..55ebeb010 100644 --- a/src/resource_clients/task.ts +++ b/src/resource_clients/task.ts @@ -25,14 +25,14 @@ export class TaskClient extends ResourceClient { } /** - * https://docs.apify.com/api/v2#/reference/actor-tasks/task-object/get-task + * 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 + * https://docs.apify.com/api/v2/actor-task-put */ async update(newFields: TaskUpdateData): Promise { ow(newFields, ow.object); @@ -41,7 +41,7 @@ export class TaskClient extends ResourceClient { } /** - * https://docs.apify.com/api/v2#/reference/actor-tasks/task-object/delete-task + * https://docs.apify.com/api/v2/actor-task-delete */ async delete(): Promise { return this._delete(); @@ -49,7 +49,7 @@ export class TaskClient extends ResourceClient { /** * Starts a task and immediately returns the Run object. - * https://docs.apify.com/api/v2#/reference/actor-tasks/run-collection/run-task + * https://docs.apify.com/api/v2/actor-task-runs-post */ async start(input?: Dictionary, options: TaskStartOptions = {}): Promise { ow(input, ow.optional.object); @@ -100,7 +100,7 @@ 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 + * https://docs.apify.com/api/v2/actor-task-runs-post */ async call(input?: Dictionary, options: TaskCallOptions = {}): Promise { ow(input, ow.optional.object); @@ -129,7 +129,7 @@ export class TaskClient extends ResourceClient { } /** - * https://docs.apify.com/api/v2#/reference/actor-tasks/task-input-object/get-task-input + * https://docs.apify.com/api/v2/actor-task-input-get */ async getInput(): Promise { const requestOpts: ApifyRequestConfig = { @@ -148,7 +148,7 @@ export class TaskClient extends ResourceClient { } /** - * https://docs.apify.com/api/v2#/reference/actor-tasks/task-input-object/update-task-input + * https://docs.apify.com/api/v2/actor-task-input-put */ async updateInput(newFields: Dictionary | Dictionary[]): Promise { const response = await this.httpClient.call({ @@ -162,7 +162,7 @@ export class TaskClient extends ResourceClient { } /** - * https://docs.apify.com/api/v2#/reference/actor-tasks/last-run-object-and-its-storages + * https://docs.apify.com/api/v2/actor-task-runs-last-get */ lastRun(options: TaskLastRunOptions = {}): RunClient { ow( @@ -183,7 +183,7 @@ export class TaskClient extends ResourceClient { } /** - * https://docs.apify.com/api/v2#/reference/actor-tasks/run-collection + * https://docs.apify.com/api/v2/actor-task-runs-get */ runs(): RunCollectionClient { return new RunCollectionClient( @@ -194,7 +194,7 @@ export class TaskClient extends ResourceClient { } /** - * https://docs.apify.com/api/v2#/reference/actor-tasks/webhook-collection + * https://docs.apify.com/api/v2/actor-task-webhooks-get */ webhooks(): WebhookCollectionClient { return new WebhookCollectionClient(this._subResourceOptions()); diff --git a/src/resource_clients/task_collection.ts b/src/resource_clients/task_collection.ts index 3026f78f1..268ad2e2c 100644 --- a/src/resource_clients/task_collection.ts +++ b/src/resource_clients/task_collection.ts @@ -17,7 +17,7 @@ export class TaskCollectionClient extends ResourceCollectionClient { } /** - * https://docs.apify.com/api/v2#/reference/actor-tasks/task-collection/get-list-of-tasks + * https://docs.apify.com/api/v2/actor-tasks-get * @param {object} [options] * @param {number} [options.limit] * @param {number} [options.offset] @@ -51,7 +51,7 @@ export class TaskCollectionClient extends ResourceCollectionClient { } /** - * https://docs.apify.com/api/v2#/reference/actor-tasks/task-collection/create-task + * 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 3513a64a0..79eba25a8 100644 --- a/src/resource_clients/user.ts +++ b/src/resource_clients/user.ts @@ -18,14 +18,14 @@ export class UserClient extends ResourceClient { /** * 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 + * 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 + * https://docs.apify.com/api/v2/user-usage-monthly-get */ async monthlyUsage(): Promise { const requestOpts: ApifyRequestConfig = { @@ -50,7 +50,7 @@ export class UserClient extends ResourceClient { } /** - * https://docs.apify.com/api/v2/#/reference/users/account-and-usage-limits + * https://docs.apify.com/api/v2/user-limits-get */ async limits(): Promise { const requestOpts: ApifyRequestConfig = { @@ -69,7 +69,7 @@ export class UserClient extends ResourceClient { } /** - * https://docs.apify.com/api/v2/#/reference/users/account-and-usage-limits + * 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 f86e420d9..ff4168544 100644 --- a/src/resource_clients/webhook.ts +++ b/src/resource_clients/webhook.ts @@ -22,14 +22,14 @@ export class WebhookClient extends ResourceClient { } /** - * https://docs.apify.com/api/v2#/reference/webhooks/webhook-object/get-webhook + * 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 + * https://docs.apify.com/api/v2/webhook-put */ async update(newFields: WebhookUpdateData): Promise { ow(newFields, ow.object); @@ -38,14 +38,14 @@ export class WebhookClient extends ResourceClient { } /** - * https://docs.apify.com/api/v2#/reference/webhooks/webhook-object/delete-webhook + * 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 + * https://docs.apify.com/api/v2/webhook-test-post */ async test(): Promise { const request: ApifyRequestConfig = { @@ -65,7 +65,7 @@ export class WebhookClient extends ResourceClient { } /** - * https://docs.apify.com/api/v2#/reference/webhooks/dispatches-collection + * https://docs.apify.com/api/v2/webhook-webhook-dispatches-get */ dispatches(): WebhookDispatchCollectionClient { return new WebhookDispatchCollectionClient( diff --git a/src/resource_clients/webhook_collection.ts b/src/resource_clients/webhook_collection.ts index c6d666a74..549083355 100644 --- a/src/resource_clients/webhook_collection.ts +++ b/src/resource_clients/webhook_collection.ts @@ -17,7 +17,7 @@ export class WebhookCollectionClient extends ResourceCollectionClient { } /** - * https://docs.apify.com/api/v2#/reference/webhooks/webhook-collection/get-list-of-webhooks + * https://docs.apify.com/api/v2/webhooks-get * * 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. @@ -49,7 +49,7 @@ export class WebhookCollectionClient extends ResourceCollectionClient { } /** - * https://docs.apify.com/api/v2#/reference/webhooks/webhook-collection/create-webhook + * 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 43301de0d..1ca5dbf3f 100644 --- a/src/resource_clients/webhook_dispatch.ts +++ b/src/resource_clients/webhook_dispatch.ts @@ -14,7 +14,7 @@ export class WebhookDispatchClient extends ResourceClient { } /** - * https://docs.apify.com/api/v2#/reference/webhook-dispatches/webhook-dispatch-object/get-webhook-dispatch + * 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 b81156117..2ef006fb0 100644 --- a/src/resource_clients/webhook_dispatch_collection.ts +++ b/src/resource_clients/webhook_dispatch_collection.ts @@ -17,8 +17,8 @@ export class WebhookDispatchCollectionClient extends ResourceCollectionClient { } /** - * https://docs.apify.com/api/v2#/reference/webhook-dispatches/webhook-dispatches-collection/get-list-of-webhook-dispatches - * + * https://docs.apify.com/api/v2/webhook-dispatches-get + */ * 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 From 7bc9fd1f62286739dfb5384630607262e36bd838 Mon Sep 17 00:00:00 2001 From: Jan Curn Date: Thu, 27 Nov 2025 15:04:47 -0800 Subject: [PATCH 07/18] Fixed existing JSDocs for other functions --- src/resource_clients/actor.ts | 6 +- src/resource_clients/actor_collection.ts | 14 +++- src/resource_clients/actor_env_var.ts | 15 ++++- .../actor_env_var_collection.ts | 12 +++- src/resource_clients/actor_version.ts | 27 ++++++-- .../actor_version_collection.ts | 12 +++- src/resource_clients/build.ts | 5 +- src/resource_clients/build_collection.ts | 6 +- src/resource_clients/dataset.ts | 2 +- src/resource_clients/dataset_collection.ts | 13 +++- src/resource_clients/key_value_store.ts | 3 +- .../key_value_store_collection.ts | 13 +++- src/resource_clients/log.ts | 13 +++- .../request_queue_collection.ts | 12 +++- src/resource_clients/run.ts | 6 +- src/resource_clients/run_collection.ts | 6 +- src/resource_clients/schedule.ts | 20 ++++-- src/resource_clients/schedule_collection.ts | 14 +++- src/resource_clients/store_collection.ts | 6 +- src/resource_clients/task.ts | 66 ++++++++++++++----- src/resource_clients/task_collection.ts | 17 +++-- src/resource_clients/user.ts | 21 ++++-- src/resource_clients/webhook.ts | 25 +++++-- src/resource_clients/webhook_collection.ts | 14 +++- src/resource_clients/webhook_dispatch.ts | 5 +- .../webhook_dispatch_collection.ts | 6 +- 26 files changed, 282 insertions(+), 77 deletions(-) diff --git a/src/resource_clients/actor.ts b/src/resource_clients/actor.ts index 2bc48fca9..3c1cd6ebc 100644 --- a/src/resource_clients/actor.ts +++ b/src/resource_clients/actor.ts @@ -289,7 +289,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({ diff --git a/src/resource_clients/actor_collection.ts b/src/resource_clients/actor_collection.ts index f04c33797..f42df0f99 100644 --- a/src/resource_clients/actor_collection.ts +++ b/src/resource_clients/actor_collection.ts @@ -18,7 +18,11 @@ export class ActorCollectionClient extends ResourceCollectionClient { } /** - * https://docs.apify.com/api/v2/acts-get + * Lists all Actors. + * + * @param options - Pagination options. + * @returns A paginated iterator of Actors. + * @see https://docs.apify.com/api/v2/acts-get * * 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. @@ -49,9 +53,13 @@ export class ActorCollectionClient extends ResourceCollectionClient { } /** - * https://docs.apify.com/api/v2/acts-post + * 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 { + async create(actor: ActorUpdateOptions): Promise { ow(actor, ow.optional.object); return this._create(actor); diff --git a/src/resource_clients/actor_env_var.ts b/src/resource_clients/actor_env_var.ts index 619af0715..7ba559b40 100644 --- a/src/resource_clients/actor_env_var.ts +++ b/src/resource_clients/actor_env_var.ts @@ -16,14 +16,21 @@ export class ActorEnvVarClient extends ResourceClient { } /** - * https://docs.apify.com/api/v2/act-version-env-var-get + * 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/act-version-env-var-put + * 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 +38,9 @@ export class ActorEnvVarClient extends ResourceClient { } /** - * https://docs.apify.com/api/v2/act-version-env-var-delete + * 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 a1f9dca84..039f4fbad 100644 --- a/src/resource_clients/actor_env_var_collection.ts +++ b/src/resource_clients/actor_env_var_collection.ts @@ -17,7 +17,11 @@ export class ActorEnvVarCollectionClient extends ResourceCollectionClient { } /** - * https://docs.apify.com/api/v2/act-version-env-vars-get + * Lists all environment variables of this Actor version. + * + * @param options - Pagination options. + * @returns A paginated iterator of environment variables. + * @see https://docs.apify.com/api/v2/act-version-env-vars-get * * 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. @@ -47,7 +51,11 @@ export class ActorEnvVarCollectionClient extends ResourceCollectionClient { } /** - * https://docs.apify.com/api/v2/act-version-env-vars-post + * 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 508906741..e36caae58 100644 --- a/src/resource_clients/actor_version.ts +++ b/src/resource_clients/actor_version.ts @@ -17,14 +17,21 @@ export class ActorVersionClient extends ResourceClient { } /** - * https://docs.apify.com/api/v2/act-version-get + * 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/act-version-put + * 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 +40,20 @@ export class ActorVersionClient extends ResourceClient { } /** - * https://docs.apify.com/api/v2/act-version-delete + * 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/act-version-env-var-get + * 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 +65,10 @@ export class ActorVersionClient extends ResourceClient { } /** - * TODO: https://docs.apify.com/api/v2/act-version-env-vars-get - * @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 e0b1a3035..66370e435 100644 --- a/src/resource_clients/actor_version_collection.ts +++ b/src/resource_clients/actor_version_collection.ts @@ -17,7 +17,11 @@ export class ActorVersionCollectionClient extends ResourceCollectionClient { } /** - * https://docs.apify.com/api/v2/act-versions-get + * Lists all Actor versions. + * + * @param options - Pagination options. + * @returns A paginated iterator of Actor versions. + * @see https://docs.apify.com/api/v2/act-versions-get * * 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. @@ -48,7 +52,11 @@ export class ActorVersionCollectionClient extends ResourceCollectionClient { } /** - * https://docs.apify.com/api/v2/act-versions-post + * 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 a478cbb53..8d8b87743 100644 --- a/src/resource_clients/build.ts +++ b/src/resource_clients/build.ts @@ -81,7 +81,10 @@ export class BuildClient extends ResourceClient { } /** - * 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({ diff --git a/src/resource_clients/build_collection.ts b/src/resource_clients/build_collection.ts index 07a53777a..6da01d123 100644 --- a/src/resource_clients/build_collection.ts +++ b/src/resource_clients/build_collection.ts @@ -17,7 +17,11 @@ export class BuildCollectionClient extends ResourceCollectionClient { } /** - * https://docs.apify.com/api/v2/actor-builds-get + * Lists all Actor builds. + * + * @param options - Pagination and sorting options. + * @returns A paginated iterator of Actor builds. + * @see https://docs.apify.com/api/v2/actor-builds-get */ * 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. diff --git a/src/resource_clients/dataset.ts b/src/resource_clients/dataset.ts index 834ab4b96..a38aa8593 100644 --- a/src/resource_clients/dataset.ts +++ b/src/resource_clients/dataset.ts @@ -267,7 +267,7 @@ export class DatasetClient< * data types, null counts, and value ranges. * * @returns Dataset statistics, or `undefined` if not available - * @see https://docs.apify.com/api/v2#tag/DatasetsStatistics/operation/dataset_statistics_get + * @see https://docs.apify.com/api/v2/dataset-statistics-get */ async getStatistics(): Promise { const requestOpts: ApifyRequestConfig = { diff --git a/src/resource_clients/dataset_collection.ts b/src/resource_clients/dataset_collection.ts index ff81e2d62..3fd1523d7 100644 --- a/src/resource_clients/dataset_collection.ts +++ b/src/resource_clients/dataset_collection.ts @@ -17,7 +17,11 @@ export class DatasetCollectionClient extends ResourceCollectionClient { } /** - * https://docs.apify.com/api/v2/datasets-get + * Lists all Datasets. + * + * @param options - Pagination options. + * @returns A paginated iterator of Datasets. + * @see https://docs.apify.com/api/v2/datasets-get * * 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. @@ -47,7 +51,12 @@ export class DatasetCollectionClient extends ResourceCollectionClient { } /** - * https://docs.apify.com/api/v2/datasets-post + * 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 807dfdbe0..cbd583128 100644 --- a/src/resource_clients/key_value_store.ts +++ b/src/resource_clients/key_value_store.ts @@ -257,7 +257,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/key-value-store-record-get + * + * @see https://docs.apify.com/api/v2/key-value-store-record-get */ async getRecord(key: string): Promise | undefined>; diff --git a/src/resource_clients/key_value_store_collection.ts b/src/resource_clients/key_value_store_collection.ts index a5f9eb53d..64c6c91fe 100644 --- a/src/resource_clients/key_value_store_collection.ts +++ b/src/resource_clients/key_value_store_collection.ts @@ -17,7 +17,11 @@ export class KeyValueStoreCollectionClient extends ResourceCollectionClient { } /** - * https://docs.apify.com/api/v2/key-value-stores-get + * Lists all Key-value stores. + * + * @param options - Pagination options. + * @returns A paginated iterator of Key-value stores. + * @see https://docs.apify.com/api/v2/key-value-stores-get * * 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. @@ -49,7 +53,12 @@ export class KeyValueStoreCollectionClient extends ResourceCollectionClient { } /** - * https://docs.apify.com/api/v2/key-value-stores-post + * 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 4a17c4717..e2dcb961e 100644 --- a/src/resource_clients/log.ts +++ b/src/resource_clients/log.ts @@ -24,7 +24,11 @@ export class LogClient extends ResourceClient { } /** - * https://docs.apify.com/api/v2/log-get + * Retrieves the log as a string. + * + * @param options - Log retrieval options. + * @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 +48,11 @@ export class LogClient extends ResourceClient { } /** - * Gets the log in a Readable stream format. Only works in Node.js. - * https://docs.apify.com/api/v2/log-get + * Retrieves the log as a Readable stream. Only works in Node.js. + * + * @param options - Log retrieval options. + * @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_collection.ts b/src/resource_clients/request_queue_collection.ts index d17e1ac94..1e000d10d 100644 --- a/src/resource_clients/request_queue_collection.ts +++ b/src/resource_clients/request_queue_collection.ts @@ -17,7 +17,11 @@ export class RequestQueueCollectionClient extends ResourceCollectionClient { } /** - * https://docs.apify.com/api/v2/request-queues-get + * Lists all Request queues. + * + * @param options - Pagination options. + * @returns A paginated iterator of Request queues. + * @see https://docs.apify.com/api/v2/request-queues-get * * 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. @@ -49,7 +53,11 @@ export class RequestQueueCollectionClient extends ResourceCollectionClient { } /** - * https://docs.apify.com/api/v2/request-queues-post + * 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 c9439fc56..59f159607 100644 --- a/src/resource_clients/run.ts +++ b/src/resource_clients/run.ts @@ -258,7 +258,11 @@ export class RunClient extends ResourceClient { } /** - * https://docs.apify.com/api/v2/post-charge-run + * Charges the Actor run for a specific event. + * + * @param options - Charge options including event name and count. + * @returns Empty response object. + * @see https://docs.apify.com/api/v2/post-charge-run */ async charge(options: RunChargeOptions): Promise>> { ow( diff --git a/src/resource_clients/run_collection.ts b/src/resource_clients/run_collection.ts index 6062a4f61..7ab79cb16 100644 --- a/src/resource_clients/run_collection.ts +++ b/src/resource_clients/run_collection.ts @@ -19,7 +19,11 @@ export class RunCollectionClient extends ResourceCollectionClient { } /** - * https://docs.apify.com/api/v2/actor-runs-get + * Lists all Actor runs. + * + * @param options - Pagination and filtering options. + * @returns A paginated iterator of Actor runs. + * @see https://docs.apify.com/api/v2/actor-runs-get */ * 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. diff --git a/src/resource_clients/schedule.ts b/src/resource_clients/schedule.ts index 8401d2942..9b0a10243 100644 --- a/src/resource_clients/schedule.ts +++ b/src/resource_clients/schedule.ts @@ -20,14 +20,21 @@ export class ScheduleClient extends ResourceClient { } /** - * https://docs.apify.com/api/v2/schedule-get + * 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/schedule-put + * 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 +42,19 @@ export class ScheduleClient extends ResourceClient { } /** - * https://docs.apify.com/api/v2/schedule-delete + * Deletes the schedule. + * + * @see https://docs.apify.com/api/v2/schedule-delete */ async delete(): Promise { return this._delete(); } /** - * https://docs.apify.com/api/v2/schedule-log-get + * 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 = { diff --git a/src/resource_clients/schedule_collection.ts b/src/resource_clients/schedule_collection.ts index 5eb7a34c5..88a8678f9 100644 --- a/src/resource_clients/schedule_collection.ts +++ b/src/resource_clients/schedule_collection.ts @@ -17,7 +17,11 @@ export class ScheduleCollectionClient extends ResourceCollectionClient { } /** - * https://docs.apify.com/api/v2/schedules-get + * Lists all schedules. + * + * @param options - Pagination and sorting options. + * @returns A paginated iterator of schedules. + * @see https://docs.apify.com/api/v2/schedules-get * * 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. @@ -46,9 +50,13 @@ export class ScheduleCollectionClient extends ResourceCollectionClient { } /** - * https://docs.apify.com/api/v2/schedules-post + * 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 { + async create(schedule: ScheduleCreateOrUpdateData): Promise { ow(schedule, ow.optional.object); return this._create(schedule); diff --git a/src/resource_clients/store_collection.ts b/src/resource_clients/store_collection.ts index 8e4fb5d81..0c2ab458a 100644 --- a/src/resource_clients/store_collection.ts +++ b/src/resource_clients/store_collection.ts @@ -17,7 +17,11 @@ export class StoreCollectionClient extends ResourceCollectionClient { } /** - * https://docs.apify.com/api/v2/store-actors-get + * Lists Actors from the Apify Store. + * + * @param options - Search and pagination options. + * @returns A paginated iterator of store Actors. + * @see https://docs.apify.com/api/v2/store-actors-get * * 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. diff --git a/src/resource_clients/task.ts b/src/resource_clients/task.ts index 55ebeb010..40984d1cd 100644 --- a/src/resource_clients/task.ts +++ b/src/resource_clients/task.ts @@ -25,14 +25,21 @@ export class TaskClient extends ResourceClient { } /** - * https://docs.apify.com/api/v2/actor-task-get + * 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/actor-task-put + * 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 +48,21 @@ export class TaskClient extends ResourceClient { } /** - * https://docs.apify.com/api/v2/actor-task-delete + * 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/actor-task-runs-post + * 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. + * @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 +113,11 @@ 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/actor-task-runs-post + * + * @param input - Input overrides for the task. If not provided, the task's saved input is used. + * @param options - Run and wait options. + * @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 +146,10 @@ export class TaskClient extends ResourceClient { } /** - * https://docs.apify.com/api/v2/actor-task-input-get + * 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 +168,11 @@ export class TaskClient extends ResourceClient { } /** - * https://docs.apify.com/api/v2/actor-task-input-put + * 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 +186,11 @@ export class TaskClient extends ResourceClient { } /** - * https://docs.apify.com/api/v2/actor-task-runs-last-get + * Returns a client for the last run of this task. + * + * @param options - Filter options for the last run. + * @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 +211,10 @@ export class TaskClient extends ResourceClient { } /** - * https://docs.apify.com/api/v2/actor-task-runs-get + * 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,7 +225,10 @@ export class TaskClient extends ResourceClient { } /** - * https://docs.apify.com/api/v2/actor-task-webhooks-get + * 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()); @@ -202,10 +236,10 @@ export class TaskClient extends ResourceClient { } /** - * Represents an Actor task. + * Represents an Actor Task. * - * Tasks are pre-configured Actor runs with stored input and settings that can be executed - * repeatedly without having to specify the input each time. + * 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; @@ -224,14 +258,14 @@ export interface Task { } /** - * Statistics about Task usage. + * Statistics about Actor Task usage. */ export interface TaskStats { totalRuns: number; } /** - * Configuration options for a Task. + * Configuration options for an Actor Task. */ export interface TaskOptions { build?: string; diff --git a/src/resource_clients/task_collection.ts b/src/resource_clients/task_collection.ts index 268ad2e2c..a89962fee 100644 --- a/src/resource_clients/task_collection.ts +++ b/src/resource_clients/task_collection.ts @@ -17,12 +17,11 @@ export class TaskCollectionClient extends ResourceCollectionClient { } /** - * https://docs.apify.com/api/v2/actor-tasks-get - * @param {object} [options] - * @param {number} [options.limit] - * @param {number} [options.offset] - * @param {boolean} [options.desc] - * @return {PaginatedIterator} + * Lists all Tasks. + * + * @param options - Pagination and sorting options. + * @returns A paginated iterator of tasks. + * @see https://docs.apify.com/api/v2/actor-tasks-get * * 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. @@ -51,7 +50,11 @@ export class TaskCollectionClient extends ResourceCollectionClient { } /** - * https://docs.apify.com/api/v2/actor-tasks-post + * 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 79eba25a8..9a14c0c4a 100644 --- a/src/resource_clients/user.ts +++ b/src/resource_clients/user.ts @@ -16,16 +16,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/user-get + * + * @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/user-usage-monthly-get + * 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 +57,10 @@ export class UserClient extends ResourceClient { } /** - * https://docs.apify.com/api/v2/user-limits-get + * 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 +79,10 @@ export class UserClient extends ResourceClient { } /** - * https://docs.apify.com/api/v2/user-limits-put + * 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 ff4168544..74f785721 100644 --- a/src/resource_clients/webhook.ts +++ b/src/resource_clients/webhook.ts @@ -22,14 +22,21 @@ export class WebhookClient extends ResourceClient { } /** - * https://docs.apify.com/api/v2/webhook-get + * 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/webhook-put + * 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 +45,19 @@ export class WebhookClient extends ResourceClient { } /** - * https://docs.apify.com/api/v2/webhook-delete + * Deletes the webhook. + * + * @see https://docs.apify.com/api/v2/webhook-delete */ async delete(): Promise { return this._delete(); } /** - * https://docs.apify.com/api/v2/webhook-test-post + * 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 +77,10 @@ export class WebhookClient extends ResourceClient { } /** - * https://docs.apify.com/api/v2/webhook-webhook-dispatches-get + * 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( diff --git a/src/resource_clients/webhook_collection.ts b/src/resource_clients/webhook_collection.ts index 549083355..dccbda045 100644 --- a/src/resource_clients/webhook_collection.ts +++ b/src/resource_clients/webhook_collection.ts @@ -17,7 +17,11 @@ export class WebhookCollectionClient extends ResourceCollectionClient { } /** - * https://docs.apify.com/api/v2/webhooks-get + * Lists all Webhooks. + * + * @param options - Pagination and sorting options. + * @returns A paginated iterator of webhooks. + * @see https://docs.apify.com/api/v2/webhooks-get * * 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. @@ -49,9 +53,13 @@ export class WebhookCollectionClient extends ResourceCollectionClient { } /** - * https://docs.apify.com/api/v2/webhooks-post + * 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 { + async create(webhook: WebhookUpdateData): Promise { ow(webhook, ow.optional.object); return this._create(webhook); diff --git a/src/resource_clients/webhook_dispatch.ts b/src/resource_clients/webhook_dispatch.ts index 1ca5dbf3f..08da2e8d8 100644 --- a/src/resource_clients/webhook_dispatch.ts +++ b/src/resource_clients/webhook_dispatch.ts @@ -14,7 +14,10 @@ export class WebhookDispatchClient extends ResourceClient { } /** - * https://docs.apify.com/api/v2/webhook-dispatch-get + * 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 2ef006fb0..5949442f6 100644 --- a/src/resource_clients/webhook_dispatch_collection.ts +++ b/src/resource_clients/webhook_dispatch_collection.ts @@ -17,7 +17,11 @@ export class WebhookDispatchCollectionClient extends ResourceCollectionClient { } /** - * https://docs.apify.com/api/v2/webhook-dispatches-get + * Lists all webhook dispatches. + * + * @param options - Pagination and sorting options. + * @returns A paginated iterator of webhook dispatches. + * @see https://docs.apify.com/api/v2/webhook-dispatches-get */ * 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. From 8857b22b35e7240ef5141e57870afa0f357a35d0 Mon Sep 17 00:00:00 2001 From: Jan Curn Date: Thu, 27 Nov 2025 15:07:45 -0800 Subject: [PATCH 08/18] Expanded options --- src/resource_clients/actor.ts | 2 ++ src/resource_clients/log.ts | 2 ++ src/resource_clients/run.ts | 5 ++++- src/resource_clients/task.ts | 18 ++++++++++++++++++ 4 files changed, 26 insertions(+), 1 deletion(-) diff --git a/src/resource_clients/actor.ts b/src/resource_clients/actor.ts index 3c1cd6ebc..5153bb69e 100644 --- a/src/resource_clients/actor.ts +++ b/src/resource_clients/actor.ts @@ -319,6 +319,8 @@ export class ActorClient extends ResourceClient { * 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 * diff --git a/src/resource_clients/log.ts b/src/resource_clients/log.ts index e2dcb961e..7889d7817 100644 --- a/src/resource_clients/log.ts +++ b/src/resource_clients/log.ts @@ -27,6 +27,7 @@ export class LogClient extends ResourceClient { * 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 */ @@ -51,6 +52,7 @@ export class LogClient extends ResourceClient { * 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 */ diff --git a/src/resource_clients/run.ts b/src/resource_clients/run.ts index 59f159607..0b6cfebd3 100644 --- a/src/resource_clients/run.ts +++ b/src/resource_clients/run.ts @@ -261,6 +261,9 @@ export class RunClient extends ResourceClient { * 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 */ @@ -307,7 +310,7 @@ export class RunClient extends ResourceClient { * and continuously polls until the run finishes or the timeout is reached. * * @param options - Wait options - * @param options.waitSecs - Maximum time to wait for the run to finish, in seconds. If omitted, waits indefinitely. + * @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 diff --git a/src/resource_clients/task.ts b/src/resource_clients/task.ts index 40984d1cd..bead3f920 100644 --- a/src/resource_clients/task.ts +++ b/src/resource_clients/task.ts @@ -61,6 +61,14 @@ export class TaskClient extends ResourceClient { * * @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 */ @@ -116,6 +124,14 @@ export class TaskClient extends ResourceClient { * * @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 */ @@ -189,6 +205,8 @@ export class TaskClient extends ResourceClient { * 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 */ From ef35ff3a8fc009749beecfeca302639c073c0597 Mon Sep 17 00:00:00 2001 From: Jan Curn Date: Thu, 27 Nov 2025 15:17:16 -0800 Subject: [PATCH 09/18] Add more docs --- src/resource_clients/actor.ts | 20 +++++++++++++ src/resource_clients/actor_collection.ts | 23 ++++++++++++++ src/resource_clients/actor_env_var.ts | 22 ++++++++++++++ .../actor_env_var_collection.ts | 26 ++++++++++++++++ src/resource_clients/actor_version.ts | 21 +++++++++++++ .../actor_version_collection.ts | 24 +++++++++++++++ src/resource_clients/build.ts | 23 ++++++++++++++ src/resource_clients/build_collection.ts | 23 +++++++++++++- src/resource_clients/dataset.ts | 29 ++++++++++++++++++ src/resource_clients/dataset_collection.ts | 20 +++++++++++++ src/resource_clients/key_value_store.ts | 28 +++++++++++++++++ .../key_value_store_collection.ts | 20 +++++++++++++ src/resource_clients/log.ts | 22 ++++++++++++++ src/resource_clients/request_queue.ts | 30 +++++++++++++++++++ .../request_queue_collection.ts | 20 +++++++++++++ src/resource_clients/run.ts | 23 ++++++++++++++ src/resource_clients/run_collection.ts | 23 +++++++++++++- src/resource_clients/schedule.ts | 23 ++++++++++++++ src/resource_clients/schedule_collection.ts | 24 +++++++++++++++ src/resource_clients/store_collection.ts | 20 +++++++++++++ src/resource_clients/task.ts | 20 +++++++++++++ src/resource_clients/task_collection.ts | 24 +++++++++++++++ src/resource_clients/user.ts | 24 +++++++++++++++ src/resource_clients/webhook.ts | 28 +++++++++++++++++ src/resource_clients/webhook_collection.ts | 23 ++++++++++++++ src/resource_clients/webhook_dispatch.ts | 18 +++++++++++ .../webhook_dispatch_collection.ts | 20 ++++++++++++- 27 files changed, 618 insertions(+), 3 deletions(-) diff --git a/src/resource_clients/actor.ts b/src/resource_clients/actor.ts index 5153bb69e..52fd85e72 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({ 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 diff --git a/src/resource_clients/actor_collection.ts b/src/resource_clients/actor_collection.ts index f42df0f99..7facc36c0 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 diff --git a/src/resource_clients/actor_env_var.ts b/src/resource_clients/actor_env_var.ts index 7ba559b40..fad0dc2b1 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 diff --git a/src/resource_clients/actor_env_var_collection.ts b/src/resource_clients/actor_env_var_collection.ts index 039f4fbad..9126fd9ae 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 diff --git a/src/resource_clients/actor_version.ts b/src/resource_clients/actor_version.ts index e36caae58..7bb306e80 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 diff --git a/src/resource_clients/actor_version_collection.ts b/src/resource_clients/actor_version_collection.ts index 66370e435..0479814c8 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 diff --git a/src/resource_clients/build.ts b/src/resource_clients/build.ts index 8d8b87743..ac17ab697 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 diff --git a/src/resource_clients/build_collection.ts b/src/resource_clients/build_collection.ts index 6da01d123..71498552c 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 @@ -22,7 +43,7 @@ export class BuildCollectionClient extends ResourceCollectionClient { * @param options - Pagination and sorting options. * @returns A paginated iterator of Actor builds. * @see https://docs.apify.com/api/v2/actor-builds-get - */ + * * 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 diff --git a/src/resource_clients/dataset.ts b/src/resource_clients/dataset.ts index a38aa8593..823a68885 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 { diff --git a/src/resource_clients/dataset_collection.ts b/src/resource_clients/dataset_collection.ts index 3fd1523d7..1b2a5bd97 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 diff --git a/src/resource_clients/key_value_store.ts b/src/resource_clients/key_value_store.ts index cbd583128..ff8df6494 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 diff --git a/src/resource_clients/key_value_store_collection.ts b/src/resource_clients/key_value_store_collection.ts index 64c6c91fe..32a5e6712 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 diff --git a/src/resource_clients/log.ts b/src/resource_clients/log.ts index 7889d7817..68905673b 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 diff --git a/src/resource_clients/request_queue.ts b/src/resource_clients/request_queue.ts index f4bca4795..fccb7e8cd 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; diff --git a/src/resource_clients/request_queue_collection.ts b/src/resource_clients/request_queue_collection.ts index 1e000d10d..f73e323f0 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 diff --git a/src/resource_clients/run.ts b/src/resource_clients/run.ts index 0b6cfebd3..9c25053eb 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 diff --git a/src/resource_clients/run_collection.ts b/src/resource_clients/run_collection.ts index 7ab79cb16..13efe7347 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 @@ -24,7 +45,7 @@ export class RunCollectionClient extends ResourceCollectionClient { * @param options - Pagination and filtering options. * @returns A paginated iterator of Actor runs. * @see https://docs.apify.com/api/v2/actor-runs-get - */ + * * 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 diff --git a/src/resource_clients/schedule.ts b/src/resource_clients/schedule.ts index 9b0a10243..89eed1e47 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 diff --git a/src/resource_clients/schedule_collection.ts b/src/resource_clients/schedule_collection.ts index 88a8678f9..43b7066d9 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 diff --git a/src/resource_clients/store_collection.ts b/src/resource_clients/store_collection.ts index 0c2ab458a..f5ecbc88b 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 diff --git a/src/resource_clients/task.ts b/src/resource_clients/task.ts index bead3f920..43fa24421 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 diff --git a/src/resource_clients/task_collection.ts b/src/resource_clients/task_collection.ts index a89962fee..0e88780c8 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 diff --git a/src/resource_clients/user.ts b/src/resource_clients/user.ts index 9a14c0c4a..ab5bb34bd 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 diff --git a/src/resource_clients/webhook.ts b/src/resource_clients/webhook.ts index 74f785721..36b4230e9 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 diff --git a/src/resource_clients/webhook_collection.ts b/src/resource_clients/webhook_collection.ts index dccbda045..ce39dbcdc 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 diff --git a/src/resource_clients/webhook_dispatch.ts b/src/resource_clients/webhook_dispatch.ts index 08da2e8d8..3246befbc 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 diff --git a/src/resource_clients/webhook_dispatch_collection.ts b/src/resource_clients/webhook_dispatch_collection.ts index 5949442f6..0c0b39044 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 @@ -22,7 +40,7 @@ export class WebhookDispatchCollectionClient extends ResourceCollectionClient { * @param options - Pagination and sorting options. * @returns A paginated iterator of webhook dispatches. * @see https://docs.apify.com/api/v2/webhook-dispatches-get - */ + * * 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 From 35bf257c7c7cf2bd6c813c4112c0462da10aca90 Mon Sep 17 00:00:00 2001 From: Jan Curn Date: Thu, 27 Nov 2025 15:30:43 -0800 Subject: [PATCH 10/18] Fixed cases --- src/apify_client.ts | 8 +++---- src/resource_clients/actor.ts | 6 ++--- src/resource_clients/dataset.ts | 20 ++++++++--------- src/resource_clients/dataset_collection.ts | 8 +++---- src/resource_clients/key_value_store.ts | 22 +++++++++---------- .../key_value_store_collection.ts | 6 ++--- src/resource_clients/run.ts | 10 ++++----- src/resource_clients/schedule.ts | 2 +- src/resource_clients/task.ts | 14 ++++++------ src/resource_clients/webhook.ts | 6 ++--- .../webhook_dispatch_collection.ts | 2 +- 11 files changed, 52 insertions(+), 52 deletions(-) diff --git a/src/apify_client.ts b/src/apify_client.ts index 8cb590641..d0efc4b77 100644 --- a/src/apify_client.ts +++ b/src/apify_client.ts @@ -256,7 +256,7 @@ export class ApifyClient { * 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 + * @returns A client for the specific key-value store * @see https://docs.apify.com/api/v2/key-value-store-get * * @example @@ -488,7 +488,7 @@ export class ApifyClient { * Use this to get, update, delete, or test a webhook. * * @param id - Webhook ID - * @returns A client for the specific Webhook + * @returns A client for the specific webhook * @see https://docs.apify.com/api/v2/webhook-get */ webhook(id: string): WebhookClient { @@ -505,7 +505,7 @@ export class ApifyClient { * * Webhook dispatches represent individual invocations of webhooks. * - * @returns A client for the Webhook dispatches collection + * @returns A client for the webhook dispatches collection * @see https://docs.apify.com/api/v2/webhook-dispatches-get */ webhookDispatches(): WebhookDispatchCollectionClient { @@ -516,7 +516,7 @@ export class ApifyClient { * Returns a client for a specific webhook dispatch. * * @param id - Webhook dispatch ID - * @returns A client for the specific Webhook dispatch + * @returns A client for the specific webhook dispatch * @see https://docs.apify.com/api/v2/webhook-dispatch-get */ webhookDispatch(id: string): WebhookDispatchClient { diff --git a/src/resource_clients/actor.ts b/src/resource_clients/actor.ts index 52fd85e72..92e39b33c 100644 --- a/src/resource_clients/actor.ts +++ b/src/resource_clients/actor.ts @@ -727,11 +727,11 @@ export interface ActorRunUsage { DATASET_READS?: number; /** Number of Dataset write operations */ DATASET_WRITES?: number; - /** Number of Key-value store read operations */ + /** Number of key-value store read operations */ KEY_VALUE_STORE_READS?: number; - /** Number of Key-value store write operations */ + /** Number of key-value store write operations */ KEY_VALUE_STORE_WRITES?: number; - /** Number of Key-value store list operations */ + /** Number of key-value store list operations */ KEY_VALUE_STORE_LISTS?: number; /** Number of Request queue read operations */ REQUEST_QUEUE_READS?: number; diff --git a/src/resource_clients/dataset.ts b/src/resource_clients/dataset.ts index 823a68885..2de007364 100644 --- a/src/resource_clients/dataset.ts +++ b/src/resource_clients/dataset.ts @@ -398,7 +398,7 @@ export class DatasetClient< } /** - * Represents a Dataset storage on the Apify platform. + * 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. @@ -423,7 +423,7 @@ export interface Dataset { } /** - * Statistics about Dataset usage and storage. + * Statistics about dataset usage and storage. */ export interface DatasetStats { readCount?: number; @@ -433,7 +433,7 @@ export interface DatasetStats { } /** - * Options for updating a Dataset. + * Options for updating a dataset. */ export interface DatasetClientUpdateOptions { name?: string | null; @@ -442,7 +442,7 @@ export interface DatasetClientUpdateOptions { } /** - * Options for listing items from a Dataset. + * Options for listing items from a dataset. * * Provides various filtering, pagination, and transformation options to customize * the output format and content of retrieved items. @@ -463,7 +463,7 @@ export interface DatasetClientListItemOptions { } /** - * Options for creating a public URL to access Dataset items. + * Options for creating a public URL to access dataset items. * * Extends {@link DatasetClientListItemOptions} with URL expiration control. */ @@ -472,7 +472,7 @@ export interface DatasetClientCreateItemsUrlOptions extends DatasetClientListIte } /** - * Supported formats for downloading Dataset items. + * Supported formats for downloading dataset items. */ export enum DownloadItemsFormat { JSON = 'json', @@ -487,7 +487,7 @@ export enum DownloadItemsFormat { const validItemFormats = [...new Set(Object.values(DownloadItemsFormat).map((item) => item.toLowerCase()))]; /** - * Options for downloading Dataset items in a specific format. + * Options for downloading dataset items in a specific format. * * Extends {@link DatasetClientListItemOptions} with format-specific options. */ @@ -501,16 +501,16 @@ export interface DatasetClientDownloadItemsOptions extends DatasetClientListItem } /** - * Statistical information about Dataset fields. + * Statistical information about dataset fields. * - * Provides insights into the data structure and content of the Dataset. + * Provides insights into the data structure and content of the dataset. */ export interface DatasetStatistics { fieldStatistics: Record; } /** - * Statistics for a single field in a Dataset. + * Statistics for a single field in a dataset. */ export interface FieldStatistics { min?: number; diff --git a/src/resource_clients/dataset_collection.ts b/src/resource_clients/dataset_collection.ts index 1b2a5bd97..b9d2faba7 100644 --- a/src/resource_clients/dataset_collection.ts +++ b/src/resource_clients/dataset_collection.ts @@ -6,7 +6,7 @@ import type { PaginatedIterator, PaginatedList, PaginationOptions } from '../uti import type { Dataset } from './dataset'; /** - * Client for managing the collection of Datasets in your account. + * 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. @@ -71,11 +71,11 @@ export class DatasetCollectionClient extends ResourceCollectionClient { } /** - * Gets or creates a Dataset with the specified name. + * Gets or creates a dataset with the specified name. * - * @param name - Name of the Dataset. If not provided, a default dataset is used. + * @param name - Name of the dataset. If not provided, a default dataset is used. * @param options - Additional options like schema. - * @returns The Dataset object. + * @returns The dataset object. * @see https://docs.apify.com/api/v2/datasets-post */ async getOrCreate(name?: string, options?: DatasetCollectionClientGetOrCreateOptions): Promise { diff --git a/src/resource_clients/key_value_store.ts b/src/resource_clients/key_value_store.ts index ff8df6494..c3b31aa7f 100644 --- a/src/resource_clients/key_value_store.ts +++ b/src/resource_clients/key_value_store.ts @@ -28,7 +28,7 @@ import { } from '../utils'; /** - * Client for managing a specific Key-value store. + * 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 @@ -67,7 +67,7 @@ export class KeyValueStoreClient extends ResourceClient { } /** - * Gets the Key-value store object from the Apify API. + * 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 @@ -77,9 +77,9 @@ export class KeyValueStoreClient extends ResourceClient { } /** - * Updates the Key-value store with specified fields. + * Updates the key-value store with specified fields. * - * @param newFields - Fields to update in the Key-value store + * @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 access level (PUBLIC or PRIVATE) @@ -93,7 +93,7 @@ export class KeyValueStoreClient extends ResourceClient { } /** - * Deletes the Key-value store. + * Deletes the key-value store. * * @see https://docs.apify.com/api/v2/key-value-store-delete */ @@ -159,9 +159,9 @@ export class KeyValueStoreClient extends ResourceClient { } /** - * Generates a public URL for accessing a specific record in the Key-value store. + * 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, + * If the client has permission to access the key-value store's URL signing key, * the URL will include a cryptographic signature for authenticated access without * requiring an API token. * @@ -191,9 +191,9 @@ export class KeyValueStoreClient extends ResourceClient { } /** - * Generates a public URL for accessing the list of keys in the Key-value store. + * 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, + * If the client has permission to access the key-value store's URL signing key, * the URL will include a cryptographic signature which allows access without authentication. * * @param options - URL generation options (extends all options from {@link listKeys}) @@ -245,7 +245,7 @@ export class KeyValueStoreClient extends ResourceClient { } /** - * Tests whether a record with the given key exists in the Key-value store without retrieving its value. + * Tests whether a record with the given key exists in the key-value store without retrieving its value. * * This is more efficient than {@link getRecord} when you only need to check for existence. * @@ -349,7 +349,7 @@ export class KeyValueStoreClient extends ResourceClient { } /** - * Stores a record in the Key-value store. + * 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 diff --git a/src/resource_clients/key_value_store_collection.ts b/src/resource_clients/key_value_store_collection.ts index 32a5e6712..902efcd93 100644 --- a/src/resource_clients/key_value_store_collection.ts +++ b/src/resource_clients/key_value_store_collection.ts @@ -73,11 +73,11 @@ export class KeyValueStoreCollectionClient extends ResourceCollectionClient { } /** - * Gets or creates a Key-value store with the specified name. + * 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 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. + * @returns The key-value store object. * @see https://docs.apify.com/api/v2/key-value-stores-post */ async getOrCreate( diff --git a/src/resource_clients/run.ts b/src/resource_clients/run.ts index 9c25053eb..40cd84f0e 100644 --- a/src/resource_clients/run.ts +++ b/src/resource_clients/run.ts @@ -125,7 +125,7 @@ export class RunClient extends ResourceClient { /** * Transforms the Actor run into a run of another Actor (metamorph). * - * This operation preserves the run ID, storages (Dataset, Key-value store, Request queue), + * 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. * @@ -239,7 +239,7 @@ export class RunClient extends ResourceClient { * 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. + * 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. @@ -381,14 +381,14 @@ export class RunClient extends ResourceClient { } /** - * Returns a client for the default Key-value store of this Actor run. + * 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 + * @returns A client for accessing the run's default key-value store * @see https://docs.apify.com/api/v2/actor-run-get * * @example * ```javascript - * // Access run's Key-value store + * // Access run's key-value store * const output = await client.run('run-id').keyValueStore().getRecord('OUTPUT'); * ``` */ diff --git a/src/resource_clients/schedule.ts b/src/resource_clients/schedule.ts index 89eed1e47..e7c4bee1a 100644 --- a/src/resource_clients/schedule.ts +++ b/src/resource_clients/schedule.ts @@ -179,7 +179,7 @@ export interface ScheduledActorRunOptions { } /** - * Scheduled action to run an Actor Task. + * Scheduled action to run an Actor task. */ export interface ScheduleActionRunActorTask extends BaseScheduleAction { actorTaskId: string; diff --git a/src/resource_clients/task.ts b/src/resource_clients/task.ts index 43fa24421..63f0a84e4 100644 --- a/src/resource_clients/task.ts +++ b/src/resource_clients/task.ts @@ -45,7 +45,7 @@ export class TaskClient extends ResourceClient { } /** - * Retrieves the Actor 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 @@ -77,7 +77,7 @@ export class TaskClient extends ResourceClient { } /** - * Starts an Actor Task and immediately returns the Run object. + * 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. @@ -182,7 +182,7 @@ export class TaskClient extends ResourceClient { } /** - * Retrieves the Actor Task's input object. + * 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 @@ -204,7 +204,7 @@ export class TaskClient extends ResourceClient { } /** - * Updates the Actor Task's input object. + * Updates the Actor task's input object. * * @param newFields - New input data for the task. * @returns The updated task input. @@ -274,7 +274,7 @@ export class TaskClient extends ResourceClient { } /** - * Represents an Actor Task. + * 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. @@ -296,14 +296,14 @@ export interface Task { } /** - * Statistics about Actor Task usage. + * Statistics about Actor task usage. */ export interface TaskStats { totalRuns: number; } /** - * Configuration options for an Actor Task. + * Configuration options for an Actor task. */ export interface TaskOptions { build?: string; diff --git a/src/resource_clients/webhook.ts b/src/resource_clients/webhook.ts index 36b4230e9..6293e0020 100644 --- a/src/resource_clients/webhook.ts +++ b/src/resource_clients/webhook.ts @@ -11,7 +11,7 @@ import type { WebhookDispatch } from './webhook_dispatch'; import { WebhookDispatchCollectionClient } from './webhook_dispatch_collection'; /** - * Client for managing a specific Webhook. + * 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 @@ -150,7 +150,7 @@ export interface WebhookIdempotencyKey { } /** - * Data for updating a Webhook. + * Data for updating a webhook. */ export type WebhookUpdateData = Partial< Pick< @@ -171,7 +171,7 @@ export type WebhookUpdateData = Partial< WebhookIdempotencyKey; /** - * Statistics about Webhook usage. + * Statistics about webhook usage. */ export interface WebhookStats { totalDispatches: number; diff --git a/src/resource_clients/webhook_dispatch_collection.ts b/src/resource_clients/webhook_dispatch_collection.ts index 0c0b39044..0ac947aa2 100644 --- a/src/resource_clients/webhook_dispatch_collection.ts +++ b/src/resource_clients/webhook_dispatch_collection.ts @@ -6,7 +6,7 @@ import type { PaginatedIterator, PaginationOptions } from '../utils'; import type { WebhookDispatch } from './webhook_dispatch'; /** - * Client for managing the collection of Webhook dispatches. + * 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. From a531b88a5dc2807cde17c1943707502fa544cf11 Mon Sep 17 00:00:00 2001 From: Jan Curn Date: Thu, 27 Nov 2025 15:39:41 -0800 Subject: [PATCH 11/18] Fix --- src/resource_clients/actor_collection.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/resource_clients/actor_collection.ts b/src/resource_clients/actor_collection.ts index 7facc36c0..e9b0997cc 100644 --- a/src/resource_clients/actor_collection.ts +++ b/src/resource_clients/actor_collection.ts @@ -82,7 +82,7 @@ export class ActorCollectionClient extends ResourceCollectionClient { * @returns The created Actor object. * @see https://docs.apify.com/api/v2/acts-post */ - async create(actor: ActorUpdateOptions): Promise { + async create(actor: ActorCollectionCreateOptions): Promise { ow(actor, ow.optional.object); return this._create(actor); From 1142122ed8257b88d49bc0f81e04388ad76cec73 Mon Sep 17 00:00:00 2001 From: Jan Curn Date: Thu, 27 Nov 2025 15:46:42 -0800 Subject: [PATCH 12/18] Fixes --- src/resource_clients/schedule_collection.ts | 2 +- src/resource_clients/webhook_collection.ts | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/src/resource_clients/schedule_collection.ts b/src/resource_clients/schedule_collection.ts index 43b7066d9..fa0d43faa 100644 --- a/src/resource_clients/schedule_collection.ts +++ b/src/resource_clients/schedule_collection.ts @@ -80,7 +80,7 @@ export class ScheduleCollectionClient extends ResourceCollectionClient { * @returns The created schedule object. * @see https://docs.apify.com/api/v2/schedules-post */ - async create(schedule: ScheduleCreateOrUpdateData): Promise { + async create(schedule?: ScheduleCreateOrUpdateData): Promise { ow(schedule, ow.optional.object); return this._create(schedule); diff --git a/src/resource_clients/webhook_collection.ts b/src/resource_clients/webhook_collection.ts index ce39dbcdc..f5699d8d5 100644 --- a/src/resource_clients/webhook_collection.ts +++ b/src/resource_clients/webhook_collection.ts @@ -82,7 +82,7 @@ export class WebhookCollectionClient extends ResourceCollectionClient { * @returns The created webhook object. * @see https://docs.apify.com/api/v2/webhooks-post */ - async create(webhook: WebhookUpdateData): Promise { + async create(webhook?: WebhookUpdateData): Promise { ow(webhook, ow.optional.object); return this._create(webhook); From 1b49bdd6a37c8e799b1d57e96d35be8e07b01cfa Mon Sep 17 00:00:00 2001 From: Copilot <198982749+Copilot@users.noreply.github.com> Date: Fri, 28 Nov 2025 02:54:24 +0100 Subject: [PATCH 13/18] Fix inadvertent parameter optionality changes in create methods (#798) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Two `create()` method signatures were inadvertently changed from optional to required parameters during JSDoc additions, breaking backward compatibility. ## Changes - **schedule_collection.ts**: Restored `create(schedule?: ScheduleCreateOrUpdateData)` parameter optionality - **webhook_collection.ts**: Restored `create(webhook?: WebhookUpdateData)` parameter optionality Both methods use `ow.optional.object` validation internally, confirming the parameters should be optional. --- ✨ Let Copilot coding agent [set things up for you](https://github.com/apify/apify-client-js/issues/new?title=✨+Set+up+Copilot+instructions&body=Configure%20instructions%20for%20this%20repository%20as%20documented%20in%20%5BBest%20practices%20for%20Copilot%20coding%20agent%20in%20your%20repository%5D%28https://gh.io/copilot-coding-agent-tips%29%2E%0A%0A%3COnboard%20this%20repo%3E&assignees=copilot) — coding agent works faster and does higher quality work when set up for your repo. --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: jancurn <10612996+jancurn@users.noreply.github.com> From e2bb026f218b4183ba5f1a2c6c87455ace5a9622 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jan=20=C4=8Curn?= Date: Fri, 28 Nov 2025 19:28:39 +0100 Subject: [PATCH 14/18] Update src/resource_clients/actor.ts Co-authored-by: Daniil Poletaev <44584010+danpoletaev@users.noreply.github.com> --- src/resource_clients/actor.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/resource_clients/actor.ts b/src/resource_clients/actor.ts index 92e39b33c..bd6d46c8b 100644 --- a/src/resource_clients/actor.ts +++ b/src/resource_clients/actor.ts @@ -31,7 +31,7 @@ import { WebhookCollectionClient } from './webhook_collection'; * const actorClient = client.actor('my-actor-id'); * * // Start an Actor - * const run = await actorClient.start({ memory: 256 }); + * 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' }); From 2fc82f173bc2dba57965c0d4d5ea73cfe87c4081 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jan=20=C4=8Curn?= Date: Fri, 28 Nov 2025 19:28:54 +0100 Subject: [PATCH 15/18] Update src/resource_clients/run.ts Co-authored-by: Daniil Poletaev <44584010+danpoletaev@users.noreply.github.com> --- src/resource_clients/run.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/resource_clients/run.ts b/src/resource_clients/run.ts index 40cd84f0e..cf9066db2 100644 --- a/src/resource_clients/run.ts +++ b/src/resource_clients/run.ts @@ -218,7 +218,7 @@ export class RunClient extends ResourceClient { * @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 access level (PUBLIC or PRIVATE) + * @param newFields.generalAccess - General resource access level ('FOLLOW_USER_SETTING', 'ANYONE_WITH_ID_CAN_READ' or 'RESTRICTED') * @returns The updated ActorRun object * * @example From 532cfb566fa1d9d9c9283787454a7d0de30d1828 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jan=20=C4=8Curn?= Date: Fri, 28 Nov 2025 19:29:01 +0100 Subject: [PATCH 16/18] Update src/resource_clients/key_value_store.ts Co-authored-by: Daniil Poletaev <44584010+danpoletaev@users.noreply.github.com> --- src/resource_clients/key_value_store.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/resource_clients/key_value_store.ts b/src/resource_clients/key_value_store.ts index c3b31aa7f..9ddf0858e 100644 --- a/src/resource_clients/key_value_store.ts +++ b/src/resource_clients/key_value_store.ts @@ -82,7 +82,7 @@ export class KeyValueStoreClient extends ResourceClient { * @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 access level (PUBLIC or PRIVATE) + * @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 */ From be5294d554c92f896796ec8339d8def013d761be Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jan=20=C4=8Curn?= Date: Fri, 28 Nov 2025 19:29:19 +0100 Subject: [PATCH 17/18] Update src/resource_clients/task.ts Co-authored-by: Daniil Poletaev <44584010+danpoletaev@users.noreply.github.com> --- src/resource_clients/task.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/resource_clients/task.ts b/src/resource_clients/task.ts index 63f0a84e4..04d832b41 100644 --- a/src/resource_clients/task.ts +++ b/src/resource_clients/task.ts @@ -330,7 +330,7 @@ export interface TaskLastRunOptions { * Options for starting a Task. * * Similar to {@link ActorStartOptions} but without contentType (Task input is predefined) - * and forcePermissionLevel (uses Task's configured permissions). + * and forcePermissionLevel. */ export type TaskStartOptions = Omit; From c1214ce586ceadf1c956d9e321587630272d3240 Mon Sep 17 00:00:00 2001 From: Copilot <198982749+Copilot@users.noreply.github.com> Date: Mon, 1 Dec 2025 21:24:52 +0100 Subject: [PATCH 18/18] Fix JSDoc tag ordering for correct TypeDoc rendering (#802) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - [x] Understand the feedback: Move JSDoc tags (`@see`, `@param`, `@returns`, `@example`) to the end of comments, with descriptions above them - [x] Fix JSDoc comments in `src/resource_clients/actor_collection.ts` - `list()` method - [x] Fix JSDoc comments in `src/apify_client.ts` - all affected methods - [x] Fix JSDoc comments in `src/resource_clients/actor.ts` - `start()`, `call()`, `build()`, `lastRun()` methods - [x] Fix JSDoc comments in `src/resource_clients/run.ts` - all affected methods - [x] Fix JSDoc comments in `src/resource_clients/key_value_store.ts` - all affected methods - [x] Fix JSDoc comments in all collection files - `list()` methods - [x] Verify build passes - [x] **Reverted incorrectly introduced `@example` tags to inline code blocks** (per reviewer feedback) --- 💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more [Copilot coding agent tips](https://gh.io/copilot-coding-agent-tips) in the docs. --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: B4nan <615580+B4nan@users.noreply.github.com> --- src/resource_clients/actor_collection.ts | 10 +++++----- src/resource_clients/actor_env_var_collection.ts | 10 +++++----- src/resource_clients/actor_version_collection.ts | 10 +++++----- src/resource_clients/build_collection.ts | 10 +++++----- src/resource_clients/dataset_collection.ts | 10 +++++----- src/resource_clients/key_value_store_collection.ts | 10 +++++----- src/resource_clients/request_queue_collection.ts | 10 +++++----- src/resource_clients/run_collection.ts | 10 +++++----- src/resource_clients/schedule_collection.ts | 10 +++++----- src/resource_clients/store_collection.ts | 10 +++++----- src/resource_clients/task_collection.ts | 10 +++++----- src/resource_clients/webhook_collection.ts | 10 +++++----- src/resource_clients/webhook_dispatch_collection.ts | 10 +++++----- 13 files changed, 65 insertions(+), 65 deletions(-) diff --git a/src/resource_clients/actor_collection.ts b/src/resource_clients/actor_collection.ts index e9b0997cc..0add7fa3b 100644 --- a/src/resource_clients/actor_collection.ts +++ b/src/resource_clients/actor_collection.ts @@ -43,15 +43,11 @@ export class ActorCollectionClient extends ResourceCollectionClient { /** * Lists all Actors. * - * @param options - Pagination options. - * @returns A paginated iterator of Actors. - * @see https://docs.apify.com/api/v2/acts-get - * * 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. @@ -59,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( diff --git a/src/resource_clients/actor_env_var_collection.ts b/src/resource_clients/actor_env_var_collection.ts index 9126fd9ae..a215922c2 100644 --- a/src/resource_clients/actor_env_var_collection.ts +++ b/src/resource_clients/actor_env_var_collection.ts @@ -45,15 +45,11 @@ export class ActorEnvVarCollectionClient extends ResourceCollectionClient { /** * Lists all environment variables of this Actor version. * - * @param options - Pagination options. - * @returns A paginated iterator of environment variables. - * @see https://docs.apify.com/api/v2/act-version-env-vars-get - * * 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. @@ -61,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 = {}, diff --git a/src/resource_clients/actor_version_collection.ts b/src/resource_clients/actor_version_collection.ts index 0479814c8..f4b9d67f3 100644 --- a/src/resource_clients/actor_version_collection.ts +++ b/src/resource_clients/actor_version_collection.ts @@ -43,15 +43,11 @@ export class ActorVersionCollectionClient extends ResourceCollectionClient { /** * Lists all Actor versions. * - * @param options - Pagination options. - * @returns A paginated iterator of Actor versions. - * @see https://docs.apify.com/api/v2/act-versions-get - * * 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. @@ -59,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 = {}, diff --git a/src/resource_clients/build_collection.ts b/src/resource_clients/build_collection.ts index 71498552c..bb7b0d588 100644 --- a/src/resource_clients/build_collection.ts +++ b/src/resource_clients/build_collection.ts @@ -40,15 +40,11 @@ export class BuildCollectionClient extends ResourceCollectionClient { /** * Lists all Actor builds. * - * @param options - Pagination and sorting options. - * @returns A paginated iterator of Actor builds. - * @see https://docs.apify.com/api/v2/actor-builds-get - * * 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. @@ -56,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_collection.ts b/src/resource_clients/dataset_collection.ts index b9d2faba7..2d7fdf179 100644 --- a/src/resource_clients/dataset_collection.ts +++ b/src/resource_clients/dataset_collection.ts @@ -39,15 +39,11 @@ export class DatasetCollectionClient extends ResourceCollectionClient { /** * Lists all Datasets. * - * @param options - Pagination options. - * @returns A paginated iterator of Datasets. - * @see https://docs.apify.com/api/v2/datasets-get - * * 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. @@ -55,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( diff --git a/src/resource_clients/key_value_store_collection.ts b/src/resource_clients/key_value_store_collection.ts index 902efcd93..c2fe06701 100644 --- a/src/resource_clients/key_value_store_collection.ts +++ b/src/resource_clients/key_value_store_collection.ts @@ -39,15 +39,11 @@ export class KeyValueStoreCollectionClient extends ResourceCollectionClient { /** * Lists all Key-value stores. * - * @param options - Pagination options. - * @returns A paginated iterator of Key-value stores. - * @see https://docs.apify.com/api/v2/key-value-stores-get - * * 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. @@ -55,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 = {}, diff --git a/src/resource_clients/request_queue_collection.ts b/src/resource_clients/request_queue_collection.ts index f73e323f0..9bd422bc5 100644 --- a/src/resource_clients/request_queue_collection.ts +++ b/src/resource_clients/request_queue_collection.ts @@ -39,15 +39,11 @@ export class RequestQueueCollectionClient extends ResourceCollectionClient { /** * Lists all Request queues. * - * @param options - Pagination options. - * @returns A paginated iterator of Request queues. - * @see https://docs.apify.com/api/v2/request-queues-get - * * 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. @@ -55,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 = {}, diff --git a/src/resource_clients/run_collection.ts b/src/resource_clients/run_collection.ts index 13efe7347..1622dd049 100644 --- a/src/resource_clients/run_collection.ts +++ b/src/resource_clients/run_collection.ts @@ -42,15 +42,11 @@ export class RunCollectionClient extends ResourceCollectionClient { /** * Lists all Actor runs. * - * @param options - Pagination and filtering options. - * @returns A paginated iterator of Actor runs. - * @see https://docs.apify.com/api/v2/actor-runs-get - * * 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. @@ -58,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_collection.ts b/src/resource_clients/schedule_collection.ts index fa0d43faa..7b35397eb 100644 --- a/src/resource_clients/schedule_collection.ts +++ b/src/resource_clients/schedule_collection.ts @@ -43,15 +43,11 @@ export class ScheduleCollectionClient extends ResourceCollectionClient { /** * Lists all schedules. * - * @param options - Pagination and sorting options. - * @returns A paginated iterator of schedules. - * @see https://docs.apify.com/api/v2/schedules-get - * * 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. @@ -59,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( diff --git a/src/resource_clients/store_collection.ts b/src/resource_clients/store_collection.ts index f5ecbc88b..14365e681 100644 --- a/src/resource_clients/store_collection.ts +++ b/src/resource_clients/store_collection.ts @@ -39,15 +39,11 @@ export class StoreCollectionClient extends ResourceCollectionClient { /** * Lists Actors from the Apify Store. * - * @param options - Search and pagination options. - * @returns A paginated iterator of store Actors. - * @see https://docs.apify.com/api/v2/store-actors-get - * * 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. @@ -55,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_collection.ts b/src/resource_clients/task_collection.ts index 0e88780c8..2c5a9833b 100644 --- a/src/resource_clients/task_collection.ts +++ b/src/resource_clients/task_collection.ts @@ -43,15 +43,11 @@ export class TaskCollectionClient extends ResourceCollectionClient { /** * Lists all Tasks. * - * @param options - Pagination and sorting options. - * @returns A paginated iterator of tasks. - * @see https://docs.apify.com/api/v2/actor-tasks-get - * * 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. @@ -59,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( diff --git a/src/resource_clients/webhook_collection.ts b/src/resource_clients/webhook_collection.ts index f5699d8d5..1eaa67816 100644 --- a/src/resource_clients/webhook_collection.ts +++ b/src/resource_clients/webhook_collection.ts @@ -42,15 +42,11 @@ export class WebhookCollectionClient extends ResourceCollectionClient { /** * Lists all Webhooks. * - * @param options - Pagination and sorting options. - * @returns A paginated iterator of webhooks. - * @see https://docs.apify.com/api/v2/webhooks-get - * * 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. @@ -58,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( diff --git a/src/resource_clients/webhook_dispatch_collection.ts b/src/resource_clients/webhook_dispatch_collection.ts index 0ac947aa2..73823ad72 100644 --- a/src/resource_clients/webhook_dispatch_collection.ts +++ b/src/resource_clients/webhook_dispatch_collection.ts @@ -37,15 +37,11 @@ export class WebhookDispatchCollectionClient extends ResourceCollectionClient { /** * Lists all webhook dispatches. * - * @param options - Pagination and sorting options. - * @returns A paginated iterator of webhook dispatches. - * @see https://docs.apify.com/api/v2/webhook-dispatches-get - * * 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. @@ -53,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(