apify-client 3.0.0-beta.9 → 3.0.0-beta.90

package/dist/resource_clients/key_value_store.d.ts

@@ -1,10 +1,11 @@
 import type { Readable } from 'node:stream';
-import type { JsonValue } from 'type-fest';
+import type { JsonValue, TypedArray } from 'type-fest';
 import type { STORAGE_GENERAL_ACCESS } from '@apify/consts';
 import type { ApiClientSubResourceOptions } from '../base/api_client.js';
 import { ResourceClient } from '../base/resource_client.js';
-import type { KeyValueClientListKeysResult, KeyValueListItem, KeyValueStore } from '../models.js';
-export type { KeyValueClientListKeysResult, KeyValueListItem, KeyValueStore, KeyValueStoreStats } from '../models.js';
+import type { KeyValueStoreResource, KeyValueStoreKey, ListOfKeys } from '../models.js';
+import type { TimeoutOptions } from '../timeouts.js';
+export type { KeyValueStoreResource, KeyValueStoreKey, KeyValueStoreStats, ListOfKeys } from '../models.js';
 /**
  * Client for managing a specific key-value store.
  *
@@ -41,10 +42,12 @@ export declare class KeyValueStoreClient extends ResourceClient {
     /**
      * Gets the key-value store object from the Apify API.
      *
+     * @param options - Request options
+     * @param options.timeoutSecs - Timeout for the API request. Default is `'short'`.
      * @returns The KeyValueStore object, or `undefined` if it does not exist
      * @see https://docs.apify.com/api/v2/key-value-store-get
      */
-    get(): Promise<KeyValueStore | undefined>;
+    get(options?: TimeoutOptions): Promise<KeyValueStoreResource | undefined>;
     /**
      * Updates the key-value store with specified fields.
      *
@@ -52,16 +55,20 @@ export declare class KeyValueStoreClient extends ResourceClient {
      * @param newFields.name - New name for the store
      * @param newFields.title - New title for the store
      * @param newFields.generalAccess - General resource access level ('FOLLOW_USER_SETTING', 'ANYONE_WITH_ID_CAN_READ' or 'RESTRICTED')
+     * @param options - Request options
+     * @param options.timeoutSecs - Timeout for the API request. Default is `'long'`.
      * @returns The updated KeyValueStore object
      * @see https://docs.apify.com/api/v2/key-value-store-put
      */
-    update(newFields: KeyValueClientUpdateOptions): Promise<KeyValueStore>;
+    update(newFields: KeyValueClientUpdateOptions, options?: TimeoutOptions): Promise<KeyValueStoreResource>;
     /**
      * Deletes the key-value store.
      *
+     * @param options - Request options
+     * @param options.timeoutSecs - Timeout for the API request. Default is `'short'`.
      * @see https://docs.apify.com/api/v2/key-value-store-delete
      */
-    delete(): Promise<void>;
+    delete(options?: TimeoutOptions): Promise<void>;
     /**
      * Lists all keys in the key-value store.
      *
@@ -70,9 +77,12 @@ export declare class KeyValueStoreClient extends ResourceClient {
      *
      * @param options - Listing options
      * @param options.limit - Maximum number of keys to return. Default is 1000.
+     * @param options.chunkSize - Maximum number of keys requested per API call when iterating across pages. `limit`
+     *   then caps the total across all pages.
      * @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.
+     * @param options.timeoutSecs - Timeout for each API request. Default is `'medium'`.
      * @returns Object containing `items` array of key metadata, pagination info (`count`, `limit`, `isTruncated`, `nextExclusiveStartKey`)
      * @see https://docs.apify.com/api/v2/key-value-store-keys-get
      *
@@ -97,7 +107,7 @@ export declare class KeyValueStoreClient extends ResourceClient {
      * } while (result.isTruncated);
      * ```
      */
-    listKeys(options?: KeyValueClientListKeysOptions): Promise<KeyValueClientListKeysResult> & AsyncIterable<KeyValueListItem>;
+    listKeys(options?: KeyValueClientListKeysOptions): Promise<ListOfKeys> & AsyncIterable<KeyValueStoreKey>;
     /**
      * Generates a public URL for accessing a specific record in the key-value store.
      *
@@ -106,6 +116,8 @@ export declare class KeyValueStoreClient extends ResourceClient {
      * requiring an API token.
      *
      * @param key - The record key
+     * @param options - Request options
+     * @param options.timeoutSecs - Timeout for the API request that fetches the store. Default is `'long'`.
      * @returns A public URL string for accessing the record
      *
      * @example
@@ -116,7 +128,7 @@ export declare class KeyValueStoreClient extends ResourceClient {
      * ```
      * @since Added in 2.14.0
      */
-    getRecordPublicUrl(key: string): Promise<string>;
+    getRecordPublicUrl(key: string, options?: TimeoutOptions): Promise<string>;
     /**
      * Generates a public URL for accessing the list of keys in the key-value store.
      *
@@ -124,9 +136,11 @@ export declare class KeyValueStoreClient extends ResourceClient {
      * the URL will include a cryptographic signature which allows access without authentication.
      *
      * @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.expiresInSecs - Number of seconds until the signed URL expires. Must be positive. If omitted, the URL
+     * never expires.
      * @param options.limit - Maximum number of keys to return.
      * @param options.prefix - Filter keys by prefix.
+     * @param options.timeoutSecs - Timeout for the API request that fetches the store. Default is `'long'`.
      * @returns A public URL string for accessing the keys list
      *
      * @example
@@ -147,6 +161,8 @@ export declare class KeyValueStoreClient extends ResourceClient {
      * This is more efficient than {@link getRecord} when you only need to check for existence.
      *
      * @param key - The record key to check
+     * @param options - Request options
+     * @param options.timeoutSecs - Timeout for the API request. Default is `'long'`.
      * @returns `true` if the record exists, `false` if it does not
      * @see https://docs.apify.com/api/v2/key-value-store-record-get
      *
@@ -159,15 +175,27 @@ export declare class KeyValueStoreClient extends ResourceClient {
      * ```
      * @since Added in 2.9.0
      */
-    recordExists(key: string): Promise<boolean>;
+    recordExists(key: string, options?: TimeoutOptions): Promise<boolean>;
     /**
+     * By default, the value is parsed by the record's content type: `application/json` is parsed into a value,
+     * `text/*` and `application/*xml` are decoded to a string, and anything else is returned as a Buffer (Node.js)
+     * or ArrayBuffer (browser). A record whose body does not parse as its content type claims, such as a non-JSON
+     * string stored under `application/json`, makes the call throw an {@link InvalidResponseBodyError}, which
+     * carries the raw body in `error.response`.
+     *
      * You can use the `buffer` option to get the value in a Buffer (Node.js)
-     * or ArrayBuffer (browser) format. In Node.js (not in browser) you can also
+     * or ArrayBuffer (browser) format, which skips the parsing. In Node.js (not in browser) you can also
      * use the `stream` option to get a Readable stream.
      *
      * When the record does not exist, the function resolves to `undefined`. It does
-     * NOT resolve to a `KeyValueStore` record with an `undefined` value.
+     * NOT resolve to a `KeyValueStoreRecord` with an `undefined` value.
      *
+     * @param key - The record key
+     * @param options - Retrieval options
+     * @param options.buffer - If `true`, the value is returned as a Buffer (Node.js) or ArrayBuffer (browser).
+     * @param options.stream - If `true`, the value is returned as a Readable stream. Node.js only.
+     * @param options.signature - Signature of a public URL, for reading a record without a token.
+     * @param options.timeoutSecs - Timeout for the API request. Default is `'long'`.
      * @see https://docs.apify.com/api/v2/key-value-store-record-get
      */
     getRecord(key: string): Promise<KeyValueStoreRecord<JsonValue> | undefined>;
@@ -179,19 +207,39 @@ export declare class KeyValueStoreClient extends ResourceClient {
      * The content type is automatically determined based on the value type, but can be
      * overridden using the `contentType` property.
      *
+     * A string is sent as it is, even under `application/json`, so a string stored under a JSON content type has
+     * to be valid JSON already, or {@link getRecord} fails to parse it back.
+     *
      * **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.
+     * the upload cannot be retried on failure or follow redirects. For reliable uploads of a file,
+     * pass a `Blob` from `fs.openAsBlob()` instead: it is read again for every attempt and never held
+     * in memory whole.
      *
      * @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.value - Record value (a JSON-serializable value, Buffer, ArrayBuffer, typed array, Blob, or
+     *                       Readable)
      * @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'`
+     *                             - Blobs: their `type`, or `'application/octet-stream'` when it is empty
+     *                             - Binary values and streams: `'application/octet-stream'`
+     *
+     *                             Worth setting for media and archives: the client skips compressing a body
+     *                             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 upload in seconds. Default varies by value size.
+     * @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`.
      * @see https://docs.apify.com/api/v2/key-value-store-record-put
      *
@@ -217,13 +265,24 @@ 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<JsonValue>, options?: KeyValueStoreRecordOptions): Promise<void>;
+    setRecord(record: KeyValueStoreRecordInput, options?: KeyValueStoreRecordOptions): Promise<void>;
     /**
      * Deletes a record from the key-value store.
      *
      * @param key - The record key to delete
+     * @param options - Request options
+     * @param options.timeoutSecs - Timeout for the API request. Default is `'short'`.
      * @see https://docs.apify.com/api/v2/key-value-store-record-delete
      *
      * @example
@@ -231,7 +290,7 @@ export declare class KeyValueStoreClient extends ResourceClient {
      * await client.keyValueStore('my-store').deleteRecord('temp-data');
      * ```
      */
-    deleteRecord(key: string): Promise<void>;
+    deleteRecord(key: string, options?: TimeoutOptions): Promise<void>;
 }
 /**
  * Options for updating a Key-Value Store.
@@ -250,8 +309,14 @@ export interface KeyValueClientUpdateOptions {
 /**
  * Options for listing keys in a Key-Value Store.
  */
-export interface KeyValueClientListKeysOptions {
+export interface KeyValueClientListKeysOptions extends TimeoutOptions {
     limit?: number;
+    /**
+     * Maximum number of keys returned in one API response. When the call is iterated with `for await`, the iterator
+     * fetches keys in chunks of this size and yields them one by one, until `limit` is reached or the store has no
+     * more keys. Awaiting the call returns only the first chunk.
+     */
+    chunkSize?: number;
     exclusiveStartKey?: string;
     collection?: string;
     /**
@@ -266,17 +331,17 @@ export interface KeyValueClientListKeysOptions {
 /**
  * Options for creating a public URL to list keys in a Key-Value Store.
  *
- * Extends {@link KeyValueClientListKeysOptions} with URL expiration control, minus `signature` (this
- * method produces one).
+ * Extends {@link KeyValueClientListKeysOptions} with URL expiration control, minus `chunkSize` (it only sizes a
+ * client-side iteration) and `signature` (this method produces one).
  * @since Added in 2.16.0
  */
-export interface KeyValueClientCreateKeysUrlOptions extends Omit<KeyValueClientListKeysOptions, 'signature'> {
+export interface KeyValueClientCreateKeysUrlOptions extends Omit<KeyValueClientListKeysOptions, 'chunkSize' | 'signature'> {
     expiresInSecs?: number;
 }
 /**
  * Options for retrieving a record from a Key-Value Store.
  */
-export interface KeyValueClientGetRecordOptions {
+export interface KeyValueClientGetRecordOptions extends TimeoutOptions {
     buffer?: boolean;
     stream?: boolean;
     /**
@@ -284,6 +349,14 @@ export interface KeyValueClientGetRecordOptions {
      */
     signature?: string;
 }
+/**
+ * A value that `setRecord` accepts.
+ *
+ * Anything JSON-serializable, or binary content the client uploads as bytes instead of JSON-encoding
+ * it: a `Buffer`, an `ArrayBuffer`, a typed array, a `Blob`, or a readable stream. `Buffer` is a
+ * `Uint8Array`, so `TypedArray` covers it.
+ */
+export type KeyValueStoreRecordValue = JsonValue | ArrayBuffer | TypedArray | Blob | Readable;
 /**
  * Represents a record (key-value pair) in a Key-Value Store.
  *
@@ -294,12 +367,21 @@ 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
  */
-export interface KeyValueStoreRecordOptions {
-    timeoutSecs?: number;
+export interface KeyValueStoreRecordOptions extends TimeoutOptions {
     doNotRetryTimeouts?: boolean;
 }
 /**