apify-client 3.0.0-beta.61 → 3.0.0-beta.63

package/dist/index.d.ts

@@ -26,6 +26,7 @@ export * from './resource_clients/webhook.js';
 export * from './resource_clients/webhook_collection.js';
 export * from './resource_clients/webhook_dispatch.js';
 export * from './resource_clients/webhook_dispatch_collection.js';
+export * from './apify_client_error.js';
 export * from './apify_api_error.js';
 export { ArgumentValidationError } from '@apify/validations';
 export * from './response_validation_error.js';

package/dist/index.js

@@ -26,6 +26,7 @@ export * from './resource_clients/webhook.js';
 export * from './resource_clients/webhook_collection.js';
 export * from './resource_clients/webhook_dispatch.js';
 export * from './resource_clients/webhook_dispatch_collection.js';
+export * from './apify_client_error.js';
 export * from './apify_api_error.js';
 export { ArgumentValidationError } from '@apify/validations';
 export * from './response_validation_error.js';

package/dist/invalid_response_body_error.d.ts

@@ -1,10 +1,11 @@
+import { ApifyClientError } from './apify_client_error.js';
 import type { HttpResponse } from './http_clients/base.js';
 /**
  * Thrown when a response body does not parse as its content type claims, typically a JSON document cut short by a
  * connection dropped mid-response. The client retries such requests, so the error surfaces once the retries are
  * exhausted.
  */
-export declare class InvalidResponseBodyError extends Error {
+export declare class InvalidResponseBodyError extends ApifyClientError {
     code: string;
     /** The response whose body did not parse, with the body as the transport returned it. */
     response: HttpResponse;

package/dist/invalid_response_body_error.js

@@ -1,9 +1,10 @@
+import { ApifyClientError } from './apify_client_error.js';
 /**
  * Thrown when a response body does not parse as its content type claims, typically a JSON document cut short by a
  * connection dropped mid-response. The client retries such requests, so the error surfaces once the retries are
  * exhausted.
  */
-export class InvalidResponseBodyError extends Error {
+export class InvalidResponseBodyError extends ApifyClientError {
     code;
     /** The response whose body did not parse, with the body as the transport returned it. */
     response;

package/dist/resource_clients/dataset.d.ts

@@ -1,3 +1,4 @@
+import type { Readable } from 'node:stream';
 import type { STORAGE_GENERAL_ACCESS } from '@apify/consts';
 import type { ApiClientSubResourceOptions } from '../base/api_client.js';
 import { ResourceClient } from '../base/resource_client.js';
@@ -167,6 +168,34 @@ export declare class DatasetClient<Data extends Record<string | number, any> = R
      * ```
      */
     downloadItems(format: `${DownloadItemsFormat}`, options?: DatasetClientDownloadItemsOptions): Promise<Buffer>;
+    /**
+     * Downloads dataset items in a specific format as a Readable stream. Only works in Node.js.
+     *
+     * Takes the same arguments as {@link downloadItems}, but resolves to the response body as a stream, so a large
+     * export is processed in chunks without holding all of it in memory.
+     *
+     * The stream holds its connection open until you consume it to the end or destroy it. Iterating it with
+     * `for await` or passing it to `pipeline()` from `node:stream/promises` does either one for you.
+     *
+     * @param format - Output format: `'json'`, `'jsonl'`, `'csv'`, `'xlsx'`, `'xml'`, `'rss'`, or `'html'`
+     * @param options - Download and formatting options, the same as for {@link downloadItems}
+     * @param options.timeoutSecs - Timeout for the API to start responding. Default is `'long'`. Once the stream is
+     * returned, it only limits inactivity: the stream errors if no data arrives for that long. To stop the download
+     * early or cap its total duration, destroy the stream or abort `signal`.
+     * @returns Readable stream of the items serialized to the specified format
+     * @see https://docs.apify.com/api/v2/dataset-items-get
+     *
+     * @example
+     * ```javascript
+     * const { createWriteStream } = require('node:fs');
+     * const { pipeline } = require('node:stream/promises');
+     *
+     * // Write a CSV export straight to a file
+     * const stream = await client.dataset('my-dataset').streamItems('csv', { bom: true });
+     * await pipeline(stream, createWriteStream('output.csv'));
+     * ```
+     */
+    streamItems(format: `${DownloadItemsFormat}`, options?: DatasetClientDownloadItemsOptions): Promise<Readable>;
     /**
      * Stores one or more items into the dataset.
      *

package/dist/resource_clients/dataset.js

@@ -3,6 +3,7 @@ import { createStorageContentSignatureAsync } from '@apify/utilities';
 import { ResourceClient } from '../base/resource_client.js';
 import * as schemas from '../schemas.js';
 import { timeoutOptionsSchema, timeoutOptionsShape } from '../timeouts.js';
+import { runtime } from '#runtime';
 import { anyObjectSchema, applyQueryParamsToUrl, cast, isNonArrayObject, paginationOptionsShape, parseArgument, parseResponse, SCANNED_COUNT, } from '../utils.js';
 /**
  * Supported formats for downloading dataset items.
@@ -269,6 +270,52 @@ export class DatasetClient extends ResourceClient {
         });
         return cast(data);
     }
+    /**
+     * Downloads dataset items in a specific format as a Readable stream. Only works in Node.js.
+     *
+     * Takes the same arguments as {@link downloadItems}, but resolves to the response body as a stream, so a large
+     * export is processed in chunks without holding all of it in memory.
+     *
+     * The stream holds its connection open until you consume it to the end or destroy it. Iterating it with
+     * `for await` or passing it to `pipeline()` from `node:stream/promises` does either one for you.
+     *
+     * @param format - Output format: `'json'`, `'jsonl'`, `'csv'`, `'xlsx'`, `'xml'`, `'rss'`, or `'html'`
+     * @param options - Download and formatting options, the same as for {@link downloadItems}
+     * @param options.timeoutSecs - Timeout for the API to start responding. Default is `'long'`. Once the stream is
+     * returned, it only limits inactivity: the stream errors if no data arrives for that long. To stop the download
+     * early or cap its total duration, destroy the stream or abort `signal`.
+     * @returns Readable stream of the items serialized to the specified format
+     * @see https://docs.apify.com/api/v2/dataset-items-get
+     *
+     * @example
+     * ```javascript
+     * const { createWriteStream } = require('node:fs');
+     * const { pipeline } = require('node:stream/promises');
+     *
+     * // Write a CSV export straight to a file
+     * const stream = await client.dataset('my-dataset').streamItems('csv', { bom: true });
+     * await pipeline(stream, createWriteStream('output.csv'));
+     * ```
+     */
+    async streamItems(format, options = {}) {
+        parseArgument(format, itemFormatSchema);
+        const { timeoutSecs = 'long', signal, ...query } = parseArgument(options, downloadItemsOptionsSchema, 'DatasetClientDownloadItemsOptions');
+        if (!runtime.isNode) {
+            throw new Error('The streamItems() method can only be used in Node.js environment.');
+        }
+        const { data } = await this.httpClient.call({
+            url: this.buildUrl('items'),
+            method: 'GET',
+            params: this.buildParams({
+                format,
+                ...query,
+            }),
+            responseType: 'stream',
+            timeoutSecs,
+            signal,
+        });
+        return cast(data);
+    }
     /**
      * Stores one or more items into the dataset.
      *

package/dist/response_validation_error.d.ts

@@ -1,4 +1,5 @@
 import type { z } from 'zod';
+import { ApifyClientError } from './apify_client_error.js';
 /**
  * Thrown when an API response does not match the schema the client expects for it.
  *
@@ -12,7 +13,7 @@ import type { z } from 'zod';
  * {@link https://zod.dev | zod} issues are available on `issues`, and the original `ZodError` on `cause`,
  * for programmatic inspection.
  */
-export declare class ResponseValidationError extends Error {
+export declare class ResponseValidationError extends ApifyClientError {
     /** Structured issues from the underlying schema check. */
     readonly issues: z.ZodError['issues'];
     /** HTTP method of the request whose response failed validation, upper-cased. */

package/dist/response_validation_error.js

@@ -1,4 +1,5 @@
 import { ArgumentValidationError } from '@apify/validations';
+import { ApifyClientError } from './apify_client_error.js';
 const REPORT_HINT = 'The API returned something its OpenAPI specification does not describe. ' +
     'Please report this at https://github.com/apify/apify-client-js/issues.';
 /**
@@ -14,7 +15,7 @@ const REPORT_HINT = 'The API returned something its OpenAPI specification does n
  * {@link https://zod.dev | zod} issues are available on `issues`, and the original `ZodError` on `cause`,
  * for programmatic inspection.
  */
-export class ResponseValidationError extends Error {
+export class ResponseValidationError extends ApifyClientError {
     /** Structured issues from the underlying schema check. */
     issues;
     /** HTTP method of the request whose response failed validation, upper-cased. */

package/dist/utils.d.ts

@@ -27,14 +27,6 @@ export declare function isNonArrayObject(value: unknown): value is Record<string
  * @internal
  */
 export declare const anyObjectSchema: z.ZodCustom<Record<string, unknown>, Record<string, unknown>>;
-/**
- * Generic interface for objects that may contain a data property.
- *
- * @template R - The type of the data property
- */
-export interface MaybeData<R> {
-    data?: R;
-}
 /**
  * Turns a JSON API response into the value a resource method returns: unwraps the `data` envelope and validates the
  * result against `schema`, one of the schemas generated from the OpenAPI specification. The validated copy is what
@@ -46,11 +38,6 @@ export interface MaybeData<R> {
  * @internal
  */
 export declare function parseResponse<R>(response: ApifyResponse, schema: z.ZodType): R;
-/**
- * Returns object's 'data' property or throws if parameter is not an object,
- * or an object without a 'data' property.
- */
-export declare function pluckData<R>(obj: MaybeData<R>): R;
 /**
  * Swallows a 404 Not Found API error and rethrows anything else.
  */

package/dist/utils.js

@@ -80,6 +80,7 @@ export const anyObjectSchema = z.custom(isNonArrayObject, {
 // any tree-shaking bundler drops it and every message degrades to a bare "Invalid input". Passing it
 // in per parse keeps them intact without reaching into the zod config the whole process shares.
 const { localeError } = z.locales.en();
+const RESPONSE_ENVELOPE_SCHEMA = z.object({ data: z.unknown() });
 /**
  * Turns a JSON API response into the value a resource method returns: unwraps the `data` envelope and validates the
  * result against `schema`, one of the schemas generated from the OpenAPI specification. The validated copy is what
@@ -91,25 +92,18 @@ const { localeError } = z.locales.en();
  * @internal
  */
 export function parseResponse(response, schema) {
-    const data = pluckData(response.data);
+    const { method = 'GET', url = '' } = response.config;
+    const envelope = RESPONSE_ENVELOPE_SCHEMA.safeParse(response.data, { error: localeError });
+    if (!envelope.success) {
+        throw new ResponseValidationError(envelope.error, response.data, { method, url });
+    }
+    const { data } = envelope.data;
     const result = schema.safeParse(data, { error: localeError });
     if (!result.success) {
-        const { method = 'GET', url = '' } = response.config;
         throw new ResponseValidationError(result.error, data, { method, url });
     }
     return result.data;
 }
-/**
- * Returns object's 'data' property or throws if parameter is not an object,
- * or an object without a 'data' property.
- */
-export function pluckData(obj) {
-    if (typeof obj === 'object' && obj) {
-        if (typeof obj.data !== 'undefined')
-            return obj.data;
-    }
-    throw new Error(`Expected response object with a "data" property, but received: ${obj}`);
-}
 /**
  * Swallows a 404 Not Found API error and rethrows anything else.
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "apify-client",
-  "version": "3.0.0-beta.61",
+  "version": "3.0.0-beta.63",
   "description": "Apify API client for JavaScript",
   "engines": {
     "node": ">=22.13.0"