apify-client 3.0.0-beta.2 → 3.0.0-beta.21

package/dist/schemas.d.ts

@@ -0,0 +1,15 @@
+/**
+ * The schemas the resource clients validate API responses with.
+ *
+ * Today these are exactly the generated ones. The module still exists as the one place where a generated
+ * schema is widened when the API is known to return something the specification does not describe, so a
+ * documented deviation never sends a resource client reaching into `./generated` directly. An override
+ * declared here shadows the generated export of the same name and takes the same form, a `lazySchema()` thunk
+ * built on the generated schema it replaces. Every schema that embeds an overridden one has to be rebuilt on
+ * top of it, and `spec_guards.ts` checks that each override still produces what the specification describes,
+ * so one cannot narrow by accident.
+ *
+ * Spec gaps need no override: the generated objects are loose, so a field the specification omits passes
+ * through. Neither do client narrowings: a schema only ever accepts more than the published type.
+ */
+export * from './generated/schemas.js';

package/dist/schemas.js

@@ -0,0 +1,15 @@
+/**
+ * The schemas the resource clients validate API responses with.
+ *
+ * Today these are exactly the generated ones. The module still exists as the one place where a generated
+ * schema is widened when the API is known to return something the specification does not describe, so a
+ * documented deviation never sends a resource client reaching into `./generated` directly. An override
+ * declared here shadows the generated export of the same name and takes the same form, a `lazySchema()` thunk
+ * built on the generated schema it replaces. Every schema that embeds an overridden one has to be rebuilt on
+ * top of it, and `spec_guards.ts` checks that each override still produces what the specification describes,
+ * so one cannot narrow by accident.
+ *
+ * Spec gaps need no override: the generated objects are loose, so a field the specification omits passes
+ * through. Neither do client narrowings: a schema only ever accepts more than the published type.
+ */
+export * from './generated/schemas.js';

package/dist/statistics.d.ts

@@ -1,4 +1,5 @@
 export declare class Statistics {
+    #private;
     /**
      * Number of Apify client function calls
      */
@@ -13,10 +14,4 @@ export declare class Statistics {
      */
     rateLimitErrors: number[];
     addRateLimitError(attempt: number): void;
-    /**
-     * Removes the necessity to pre-initialize array with correct
-     * number of zeroes by dynamically filling the empty indexes
-     * when necessary.
-     */
-    private _fillBlanksWithZeroes;
 }

package/dist/statistics.js

@@ -20,7 +20,7 @@ export class Statistics {
         // attempt is never 0,
         // but we don't want index 0 empty
         const index = attempt - 1;
-        this._fillBlanksWithZeroes(index);
+        this.#fillBlanksWithZeroes(index);
         this.rateLimitErrors[index]++;
     }
     /**
@@ -28,7 +28,7 @@ export class Statistics {
      * number of zeroes by dynamically filling the empty indexes
      * when necessary.
      */
-    _fillBlanksWithZeroes(inclusiveIndex) {
+    #fillBlanksWithZeroes(inclusiveIndex) {
         if (this.rateLimitErrors.length <= inclusiveIndex) {
             for (let k = 0; k <= inclusiveIndex; k++) {
                 if (typeof this.rateLimitErrors[k] !== 'number') {

package/dist/timeouts.d.ts

@@ -0,0 +1,72 @@
+import { z } from 'zod';
+/** Default duration of the `short` timeout tier, in seconds. */
+export declare const DEFAULT_TIMEOUT_SHORT_SECS = 5;
+/** Default duration of the `medium` timeout tier, in seconds. */
+export declare const DEFAULT_TIMEOUT_MEDIUM_SECS = 30;
+/** Default duration of the `long` timeout tier, in seconds. */
+export declare const DEFAULT_TIMEOUT_LONG_SECS = 360;
+/** Default cap on the timeout of a single request attempt, in seconds. */
+export declare const DEFAULT_TIMEOUT_MAX_SECS = 360;
+/**
+ * Preconfigured timeout tiers. Every client method picks the tier that fits the expected duration of its
+ * request: `short` for simple metadata reads and writes, `medium` for listing, batch and trigger operations,
+ * `long` for downloads, uploads and streaming. The duration of each tier is set on the {@link ApifyClient}
+ * constructor.
+ */
+export type TimeoutTier = 'short' | 'medium' | 'long';
+/**
+ * Timeout of a single API request.
+ *
+ * A tier name picks the duration configured for that tier on the {@link ApifyClient} constructor, a number is
+ * an exact duration in seconds, and `'noTimeout'` lets the request run for as long as it takes. A tier or an
+ * explicit duration above `timeoutMaxSecs` is capped at it, and the client logs a warning when that happens.
+ * The timeout applies to each attempt separately, and doubles with every retry up to the same cap.
+ *
+ * With `'noTimeout'` the client never aborts the request, so a connection that stalls is not retried either.
+ */
+export type Timeout = TimeoutTier | 'noTimeout' | number;
+/**
+ * Options shared by every method that sends a request to the API.
+ */
+export interface TimeoutOptions {
+    /**
+     * Timeout for the API request: a tier name (`'short'`, `'medium'`, `'long'`), a number of seconds, or
+     * `'noTimeout'`. Defaults to the tier the method is assigned, which its documentation names.
+     */
+    timeoutSecs?: Timeout;
+}
+/**
+ * Schema of {@link Timeout}, optional, for the methods that validate `timeoutSecs` on its own.
+ * @internal
+ */
+export declare const optionalTimeoutSchema: z.ZodOptional<z.ZodUnion<readonly [z.ZodEnum<{
+    short: "short";
+    medium: "medium";
+    long: "long";
+    noTimeout: "noTimeout";
+}>, z.ZodNumber]>>;
+/**
+ * Schema shape of {@link TimeoutOptions}, to spread into the option schema of every method that sends a
+ * request. One copy stops it drifting from the interface.
+ * @internal
+ */
+export declare const timeoutOptionsShape: {
+    timeoutSecs: z.ZodOptional<z.ZodUnion<readonly [z.ZodEnum<{
+        short: "short";
+        medium: "medium";
+        long: "long";
+        noTimeout: "noTimeout";
+    }>, z.ZodNumber]>>;
+};
+/**
+ * Schema of {@link TimeoutOptions}, for the methods that take no other option.
+ * @internal
+ */
+export declare const timeoutOptionsSchema: z.ZodObject<{
+    timeoutSecs: z.ZodOptional<z.ZodUnion<readonly [z.ZodEnum<{
+        short: "short";
+        medium: "medium";
+        long: "long";
+        noTimeout: "noTimeout";
+    }>, z.ZodNumber]>>;
+}, z.core.$strict>;

package/dist/timeouts.js

@@ -0,0 +1,31 @@
+import { z } from 'zod';
+/** Default duration of the `short` timeout tier, in seconds. */
+export const DEFAULT_TIMEOUT_SHORT_SECS = 5;
+/** Default duration of the `medium` timeout tier, in seconds. */
+export const DEFAULT_TIMEOUT_MEDIUM_SECS = 30;
+/** Default duration of the `long` timeout tier, in seconds. */
+export const DEFAULT_TIMEOUT_LONG_SECS = 360;
+/** Default cap on the timeout of a single request attempt, in seconds. */
+export const DEFAULT_TIMEOUT_MAX_SECS = 360;
+/**
+ * Schema of {@link Timeout}. Zero is rejected on purpose - `'noTimeout'` is the explicit way to run without one.
+ */
+const timeoutSchema = z.union([z.enum(['short', 'medium', 'long', 'noTimeout']), z.number().positive()]);
+/**
+ * Schema of {@link Timeout}, optional, for the methods that validate `timeoutSecs` on its own.
+ * @internal
+ */
+export const optionalTimeoutSchema = timeoutSchema.optional();
+/**
+ * Schema shape of {@link TimeoutOptions}, to spread into the option schema of every method that sends a
+ * request. One copy stops it drifting from the interface.
+ * @internal
+ */
+export const timeoutOptionsShape = {
+    timeoutSecs: optionalTimeoutSchema,
+};
+/**
+ * Schema of {@link TimeoutOptions}, for the methods that take no other option.
+ * @internal
+ */
+export const timeoutOptionsSchema = z.strictObject(timeoutOptionsShape);

package/dist/utils.d.ts

@@ -1,18 +1,14 @@
 import type { Readable } from 'node:stream';
-import type { JsonValue, TypedArray } from 'type-fest';
+import type { TypedArray } from 'type-fest';
 import { z } from 'zod';
 import type { ApifyApiError } from './apify_api_error.js';
+import { parseArgument } from '@apify/validations';
+import type { ApifyResponse } from './http_client.js';
+import type { CompressedValue } from './runtime/types.js';
 import type { RequestQueueClientListRequestsOptions, RequestQueueClientListRequestsResult } from './resource_clients/request_queue.js';
 import type { WebhookUpdateData } from './resource_clients/webhook.js';
-/**
- * Parses `value` with `schema`, returning the typed result (with schema defaults applied).
- * Throws {@link ArgumentValidationError} on failure.
- *
- * The optional `label` names the interface being validated and is appended to every error line
- * (e.g. ``... at `memory` in `ActorStartOptions` ``).
- * @internal
- */
-export declare function parseArgument<TValue, TSchema extends z.ZodType>(value: TValue, schema: TSchema, label?: string): TValue & z.output<TSchema>;
+export declare const version: any;
+export { parseArgument };
 /**
  * Accepts any non-null, non-array object as a predicate for `z.custom()`.
  * @internal
@@ -33,71 +29,93 @@ export declare const anyObjectSchema: z.ZodCustom<Record<string, unknown>, Recor
 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
+ * callers get, so it is the schema's output -- unknown fields and unknown enum values included, since the schemas let
+ * both through, date-time fields turned into `Date` objects, and URL fields normalized, since `z.url()` hands back the
+ * parsed URL's serialization.
+ *
+ * Throws {@link ResponseValidationError} when the response does not match the specification.
+ * @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;
 /**
- * If given HTTP error has NOT_FOUND_STATUS_CODE status code then returns undefined.
- * Otherwise rethrows error.
+ * Swallows a 404 Not Found API error and rethrows anything else.
  */
 export declare function catchNotFoundOrThrow(err: ApifyApiError): void;
-type ReturnJsonValue = string | number | boolean | null | Date | ReturnJsonObject | ReturnJsonArray;
-type ReturnJsonObject = {
-    [Key in string]?: ReturnJsonValue;
-};
-type ReturnJsonArray = ReturnJsonValue[];
 /**
- * Traverses JSON structure and converts fields that end with "At" to a Date object (fields such as "modifiedAt" or
- * "createdAt").
- *
- * If you want parse other fields as well, you can provide a custom matcher function shouldParseField(). This
- * admittedly awkward approach allows this function to be reused for various purposes without introducing potential
- * breaking changes.
+ * Like `catchNotFoundOrThrow()`, but swallows the 404 only when the client names its resource by ID.
  *
- * If the field cannot be converted to Date, it is left as is.
+ * A chained client without an ID, such as `run.dataset()` or `run.log()`, requests a path where a 404 can mean either
+ * the parent or the default sub-resource is missing. The response cannot tell the two apart, so the error propagates.
+ * @internal
  */
-export declare function parseDateFields(input: JsonValue, shouldParseField?: ((key: string) => boolean) | null, depth?: number): ReturnJsonValue;
+export declare function catchNotFoundForResourceOrThrow(err: ApifyApiError, resourceId: string | undefined): void;
 /**
  * Helper function that converts array of webhooks to base64 string
  */
 export declare function stringifyWebhooksToBase64(webhooks?: readonly WebhookUpdateData[]): string | undefined;
-export interface CompressedValue {
-    data: Buffer;
-    encoding: 'br' | 'gzip';
-}
 /**
- * Compress the passed value using brotli, falling back to gzip. Returns undefined if the data is
- * too small / wrong type, or if neither algorithm is available.
+ * Encodes bytes as base64. `btoa()` takes a binary string, and the bytes are turned into one in slices,
+ * because spreading them all into a single `String.fromCharCode()` call overflows the argument limit on
+ * inputs of a few tens of kilobytes.
+ */
+export declare function bytesToBase64(bytes: Uint8Array): string;
+/**
+ * Concatenates byte chunks into one array.
+ */
+export declare function concatBytes(chunks: Uint8Array[]): Uint8Array;
+/**
+ * Decides whether a request body with the given content type is worth compressing.
+ *
+ * Images, audio, video and archives already carry their own compression. Running them through brotli or gzip
+ * burns CPU, holds a second full copy of the body in memory, and usually produces output slightly larger than
+ * the input. Formats that are raw despite such a media type, for example `image/bmp` or `audio/wav`, are still
+ * compressed. A body with no content type is assumed to be compressible.
+ * @internal
+ */
+export declare function isCompressibleContentType(contentType?: string): boolean;
+/**
+ * Compresses the passed value with the runtime's best available algorithm. Returns `undefined` if the data
+ * is too small, is not a string or binary value, or if the runtime does not offer compression.
  */
 export declare function maybeCompressValue(value: unknown): Promise<CompressedValue | undefined>;
 /**
- * Helper function slice the items from array to fit the max byte length.
+ * Reads an environment variable, on runtimes that have them.
+ */
+export declare function getEnv(name: string): string | undefined;
+/**
+ * Returns the UTF-8 byte length of a string.
+ */
+export declare function utf8ByteLength(value: string): number;
+/**
+ * Splits JSON-serialized items into consecutive batches of at most `maxCount` items, each of which fits into a JSON
+ * array body - the items joined by commas between brackets - of at most `maxByteLength` bytes. The `byteLength` of an
+ * item is the UTF-8 byte length of its serialization. An item too large for a body of its own still gets one, so a
+ * caller that cannot send such an item has to reject it beforehand.
  */
-export declare function sliceArrayByByteLength<T>(array: T[], maxByteLength: number, startIndex: number): T[];
-export declare function isNode(): boolean;
+export declare function splitIntoJsonArrayBatches<T extends {
+    byteLength: number;
+}>(items: readonly T[], { maxCount, maxByteLength }: {
+    maxCount: number;
+    maxByteLength: number;
+}): T[][];
 export declare function isBuffer(value: unknown): value is Buffer | ArrayBuffer | TypedArray;
 export declare function isStream(value: unknown): value is Readable;
-export declare function getVersionData(): {
-    version: string;
-};
 /**
- * Helper class to create async iterators from paginated list endpoints with exclusive start key.
+ * Helper class to create async iterators from paginated list endpoints.
  */
 export declare class RequestQueuePaginationIterator {
-    private readonly maxPageLimit;
-    private readonly getPage;
-    private readonly limit?;
-    private readonly exclusiveStartId?;
-    private readonly cursor?;
+    #private;
     constructor(options: RequestQueuePaginationIteratorOptions);
     [Symbol.asyncIterator](): AsyncIterator<RequestQueueClientListRequestsResult>;
 }
-declare global {
-    export const BROWSER_BUILD: boolean | undefined;
-    export const VERSION: string | undefined;
-}
 /**
  * Options for creating a pagination iterator.
  */
@@ -105,7 +123,6 @@ export interface RequestQueuePaginationIteratorOptions {
     maxPageLimit: number;
     getPage: (opts: RequestQueueClientListRequestsOptions) => Promise<RequestQueueClientListRequestsResult>;
     limit?: number;
-    exclusiveStartId?: string;
     cursor?: string;
 }
 /**
@@ -164,6 +181,16 @@ export interface PaginatedList<Data> extends PaginatedResponse<Data> {
     /** Should the results be in descending order. */
     desc: boolean;
 }
+/**
+ * Key under which a page of dataset items carries the number of rows the API scanned to produce it, as a
+ * non-enumerable property that stays out of the page's public shape. The API applies `offset` and `limit` to the
+ * dataset's rows first and shapes the result afterwards: filters (`clean`, `skipEmpty`, `skipHidden`) drop items and
+ * `unwind` splits or drops them, so `items.length` can land on either side of the rows scanned. The
+ * `x-apify-pagination-count` header reports the scanned number, and the offset iterator advances and terminates by it
+ * alone. A page without the property falls back to `items.length`.
+ * @internal
+ */
+export declare const SCANNED_COUNT: unique symbol;
 /**
  * Type representing both a Promise of a paginated list and an async iterable.
  *
@@ -192,12 +219,6 @@ export type DistributiveOptional<T, K extends keyof T> = T extends any ? Omit<T,
  * Adds query parameters to a given URL based on the provided options object.
  */
 export declare function applyQueryParamsToUrl(url: URL, options?: Record<string, string | number | boolean | string[] | undefined>): URL;
-/**
- * Builds a `[check, message]` pair to spread into `.refine()`, asserting that at most one of `keys`
- * is present. Pass the options interface as `T`, so that a misspelled key is a type error.
- * @internal
- */
-export declare const mutuallyExclusive: <T extends object>(...keys: (keyof T & string)[]) => [(value: T) => boolean, string];
 /**
  * Percent-encodes a caller-supplied URL path segment so it cannot restructure the request path.
  *
@@ -210,4 +231,3 @@ export declare function toPathSegment(value: string): string;
  * `requests/batch` keep their separators; an array has each of its segments encoded individually.
  */
 export declare function toPath(path: string | string[]): string;
-export {};