apify-client 3.0.0-beta.60 → 3.0.0-beta.62

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/key_value_store.d.ts

@@ -225,6 +225,15 @@ export declare class KeyValueStoreClient extends ResourceClient {
      *                             whose content type already carries its own compression. The
      *                             `'application/octet-stream'` fallback is treated as compressible, because
      *                             it could hold any binary data.
+     * @param record.contentEncoding - Optional encoding already applied to `value`, sent as the `Content-Encoding`
+     *                                 header. Set it to upload a pre-compressed value: the client then sends the
+     *                                 bytes as they are and does not compress them again. The API accepts `gzip`,
+     *                                 `br`, `deflate`, and `identity`, and stores the record exactly as uploaded, so
+     *                                 this is also the encoding the record is served with. Only binary values and
+     *                                 streams can carry a compression, so any encoding other than `identity` throws
+     *                                 a `TypeError` when `value` is a string, or a plain object, array, or other
+     *                                 value that the client serializes to JSON. Node.js only, since browsers cannot
+     *                                 send the header to the API.
      * @param options - Storage options
      * @param options.timeoutSecs - Timeout for the API request. Default is `'long'`.
      * @param options.doNotRetryTimeouts - If `true`, don't retry on timeout errors. Default is `false`.
@@ -252,9 +261,18 @@ export declare class KeyValueStoreClient extends ResourceClient {
      *   value: imageBuffer,
      *   contentType: 'image/png'
      * });
+     *
+     * // Store a gzipped file without compressing it again
+     * const gzippedReport = await readFile('report.json.gz');
+     * await client.keyValueStore('my-store').setRecord({
+     *   key: 'report.json',
+     *   value: gzippedReport,
+     *   contentType: 'application/json',
+     *   contentEncoding: 'gzip'
+     * });
      * ```
      */
-    setRecord(record: KeyValueStoreRecord<KeyValueStoreRecordValue>, options?: KeyValueStoreRecordOptions): Promise<void>;
+    setRecord(record: KeyValueStoreRecordInput, options?: KeyValueStoreRecordOptions): Promise<void>;
     /**
      * Deletes a record from the key-value store.
      *
@@ -345,6 +363,16 @@ export interface KeyValueStoreRecord<T> {
     value: T;
     contentType?: string;
 }
+/**
+ * A record to store with {@link KeyValueStoreClient.setRecord}.
+ */
+export interface KeyValueStoreRecordInput extends KeyValueStoreRecord<KeyValueStoreRecordValue> {
+    /**
+     * Encoding already applied to `value`, sent as the `Content-Encoding` header. See
+     * {@link KeyValueStoreClient.setRecord}.
+     */
+    contentEncoding?: string;
+}
 /**
  * Options for storing a record in a Key-Value Store.
  * @since Added in 2.12.4

package/dist/resource_clients/key_value_store.js

@@ -46,6 +46,7 @@ const recordSchema = z.strictObject({
         typeof value !== 'function' &&
         (typeof value !== 'number' || Number.isFinite(value)), 'Expected a JSON-serializable value, binary data, or a stream'),
     contentType: z.string().min(1).optional(),
+    contentEncoding: z.string().trim().min(1).optional(),
 });
 const recordOptionsSchema = z.strictObject({
     ...timeoutOptionsShape,
@@ -378,6 +379,15 @@ export class KeyValueStoreClient extends ResourceClient {
      *                             whose content type already carries its own compression. The
      *                             `'application/octet-stream'` fallback is treated as compressible, because
      *                             it could hold any binary data.
+     * @param record.contentEncoding - Optional encoding already applied to `value`, sent as the `Content-Encoding`
+     *                                 header. Set it to upload a pre-compressed value: the client then sends the
+     *                                 bytes as they are and does not compress them again. The API accepts `gzip`,
+     *                                 `br`, `deflate`, and `identity`, and stores the record exactly as uploaded, so
+     *                                 this is also the encoding the record is served with. Only binary values and
+     *                                 streams can carry a compression, so any encoding other than `identity` throws
+     *                                 a `TypeError` when `value` is a string, or a plain object, array, or other
+     *                                 value that the client serializes to JSON. Node.js only, since browsers cannot
+     *                                 send the header to the API.
      * @param options - Storage options
      * @param options.timeoutSecs - Timeout for the API request. Default is `'long'`.
      * @param options.doNotRetryTimeouts - If `true`, don't retry on timeout errors. Default is `false`.
@@ -405,15 +415,35 @@ export class KeyValueStoreClient extends ResourceClient {
      *   value: imageBuffer,
      *   contentType: 'image/png'
      * });
+     *
+     * // Store a gzipped file without compressing it again
+     * const gzippedReport = await readFile('report.json.gz');
+     * await client.keyValueStore('my-store').setRecord({
+     *   key: 'report.json',
+     *   value: gzippedReport,
+     *   contentType: 'application/json',
+     *   contentEncoding: 'gzip'
+     * });
      * ```
      */
     async setRecord(record, options = {}) {
         parseArgument(record, recordSchema);
         const parsed = parseArgument(options, recordOptionsSchema, 'KeyValueStoreRecordOptions');
-        const { key } = record;
+        const { key, contentEncoding } = record;
         let { value, contentType } = record;
         const { timeoutSecs = 'long', signal, doNotRetryTimeouts } = parsed;
+        if (contentEncoding !== undefined && !runtime.isNode) {
+            throw new Error('The contentEncoding option can only be used in Node.js environment.');
+        }
         const isValueStreamOrBuffer = isStream(value) || isBuffer(value);
+        // The client forwards the header without inspecting the body, so a string or a value serialized to JSON, which
+        // cannot hold compressed bytes, would be stored under an encoding that misdescribes it.
+        const declaresCompression = contentEncoding !== undefined && contentEncoding.trim().toLowerCase() !== 'identity';
+        if (declaresCompression && !isValueStreamOrBuffer) {
+            throw new TypeError(`Cannot upload a value of type ${typeof value} with Content-Encoding: ${contentEncoding}. ` +
+                'An encoding other than identity declares the value is already compressed, so pass the ' +
+                'compressed bytes as a Buffer, an ArrayBuffer, a typed array, or a readable stream.');
+        }
         // To allow saving Objects to JSON without providing content type
         if (!contentType) {
             if (isValueStreamOrBuffer)
@@ -438,7 +468,10 @@ export class KeyValueStoreClient extends ResourceClient {
             method: 'PUT',
             params: this.buildParams(),
             data: value,
-            headers: contentType ? { 'content-type': contentType } : undefined,
+            headers: {
+                'content-type': contentType,
+                ...(contentEncoding !== undefined && { 'content-encoding': contentEncoding }),
+            },
             doNotRetryTimeouts,
             timeoutSecs,
             signal,

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.60",
+  "version": "3.0.0-beta.62",
   "description": "Apify API client for JavaScript",
   "engines": {
     "node": ">=22.13.0"