apify-client 2.25.1-beta.7 → 3.0.0-beta.0

package/dist/apify_client.js

@@ -2,7 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ApifyClient = void 0;
 const tslib_1 = require("tslib");
-const ow_1 = tslib_1.__importDefault(require("ow"));
+const zod_1 = require("zod");
 const consts_1 = require("@apify/consts");
 const log_1 = tslib_1.__importDefault(require("@apify/log"));
 const http_client_1 = require("./http_client");
@@ -30,7 +30,23 @@ const webhook_collection_1 = require("./resource_clients/webhook_collection");
 const webhook_dispatch_1 = require("./resource_clients/webhook_dispatch");
 const webhook_dispatch_collection_1 = require("./resource_clients/webhook_dispatch_collection");
 const statistics_1 = require("./statistics");
+const utils_1 = require("./utils");
 const DEFAULT_TIMEOUT_SECS = 360;
+const clientOptionsSchema = zod_1.z.strictObject({
+    baseUrl: zod_1.z.string().default('https://api.apify.com'),
+    publicBaseUrl: zod_1.z.string().default('https://api.apify.com'),
+    maxRetries: zod_1.z.number().default(8),
+    minDelayBetweenRetriesMillis: zod_1.z.number().default(500),
+    requestInterceptors: zod_1.z.array(zod_1.z.unknown()).default([]),
+    timeoutSecs: zod_1.z.number().default(DEFAULT_TIMEOUT_SECS),
+    token: zod_1.z.string().optional(),
+    userAgentSuffix: zod_1.z.union([zod_1.z.string(), zod_1.z.array(zod_1.z.string())]).optional(),
+});
+const resourceIdSchema = zod_1.z.string().min(1);
+const requestQueueOptionsSchema = zod_1.z.strictObject({
+    clientKey: zod_1.z.string().min(1).optional(),
+    timeoutSecs: zod_1.z.number().optional(),
+});
 /**
  * The official JavaScript client for the Apify API.
  *
@@ -63,17 +79,8 @@ class ApifyClient {
     logger;
     httpClient;
     constructor(options = {}) {
-        (0, ow_1.default)(options, ow_1.default.object.exactShape({
-            baseUrl: ow_1.default.optional.string,
-            publicBaseUrl: ow_1.default.optional.string,
-            maxRetries: ow_1.default.optional.number,
-            minDelayBetweenRetriesMillis: ow_1.default.optional.number,
-            requestInterceptors: ow_1.default.optional.array,
-            timeoutSecs: ow_1.default.optional.number,
-            token: ow_1.default.optional.string,
-            userAgentSuffix: ow_1.default.optional.any(ow_1.default.string, ow_1.default.array.ofType(ow_1.default.string)),
-        }));
-        const { baseUrl = 'https://api.apify.com', publicBaseUrl = 'https://api.apify.com', maxRetries = 8, minDelayBetweenRetriesMillis = 500, requestInterceptors = [], timeoutSecs = DEFAULT_TIMEOUT_SECS, token, } = options;
+        const parsed = (0, utils_1.parseArgument)(options, clientOptionsSchema, 'ApifyClientOptions');
+        const { baseUrl, publicBaseUrl, maxRetries, minDelayBetweenRetriesMillis, requestInterceptors, timeoutSecs, token, } = parsed;
         const tempBaseUrl = baseUrl.endsWith('/') ? baseUrl.slice(0, baseUrl.length - 1) : baseUrl;
         this.baseUrl = `${tempBaseUrl}/v2`;
         const tempPublicBaseUrl = publicBaseUrl.endsWith('/')
@@ -91,7 +98,7 @@ class ApifyClient {
             timeoutSecs,
             logger: this.logger,
             token: this.token,
-            userAgentSuffix: options.userAgentSuffix,
+            userAgentSuffix: parsed.userAgentSuffix,
         });
     }
     _options() {
@@ -130,7 +137,7 @@ class ApifyClient {
      * ```
      */
     actor(id) {
-        (0, ow_1.default)(id, ow_1.default.string.nonEmpty);
+        (0, utils_1.parseArgument)(id, resourceIdSchema);
         return new actor_1.ActorClient({
             id,
             ...this._options(),
@@ -157,7 +164,7 @@ class ApifyClient {
      * @see https://docs.apify.com/api/v2/actor-build-get
      */
     build(id) {
-        (0, ow_1.default)(id, ow_1.default.string.nonEmpty);
+        (0, utils_1.parseArgument)(id, resourceIdSchema);
         return new build_1.BuildClient({
             id,
             ...this._options(),
@@ -198,7 +205,7 @@ class ApifyClient {
      * ```
      */
     dataset(id) {
-        (0, ow_1.default)(id, ow_1.default.string.nonEmpty);
+        (0, utils_1.parseArgument)(id, resourceIdSchema);
         return new dataset_1.DatasetClient({
             id,
             ...this._options(),
@@ -235,7 +242,7 @@ class ApifyClient {
      * ```
      */
     keyValueStore(id) {
-        (0, ow_1.default)(id, ow_1.default.string.nonEmpty);
+        (0, utils_1.parseArgument)(id, resourceIdSchema);
         return new key_value_store_1.KeyValueStoreClient({
             id,
             ...this._options(),
@@ -249,7 +256,7 @@ class ApifyClient {
      * @see https://docs.apify.com/api/v2/log-get
      */
     log(buildOrRunId) {
-        (0, ow_1.default)(buildOrRunId, ow_1.default.string.nonEmpty);
+        (0, utils_1.parseArgument)(buildOrRunId, resourceIdSchema);
         return new log_2.LogClient({
             id: buildOrRunId,
             ...this._options(),
@@ -288,16 +295,13 @@ class ApifyClient {
      * ```
      */
     requestQueue(id, options = {}) {
-        (0, ow_1.default)(id, ow_1.default.string.nonEmpty);
-        (0, ow_1.default)(options, ow_1.default.object.exactShape({
-            clientKey: ow_1.default.optional.string.nonEmpty,
-            timeoutSecs: ow_1.default.optional.number,
-        }));
+        (0, utils_1.parseArgument)(id, resourceIdSchema);
+        const parsed = (0, utils_1.parseArgument)(options, requestQueueOptionsSchema, 'RequestQueueUserOptions');
         const apiClientOptions = {
             id,
             ...this._options(),
         };
-        return new request_queue_1.RequestQueueClient(apiClientOptions, options);
+        return new request_queue_1.RequestQueueClient(apiClientOptions, parsed);
     }
     /**
      * Returns a client for managing Actor runs in your account.
@@ -333,7 +337,7 @@ class ApifyClient {
      * ```
      */
     run(id) {
-        (0, ow_1.default)(id, ow_1.default.string.nonEmpty);
+        (0, utils_1.parseArgument)(id, resourceIdSchema);
         return new run_1.RunClient({
             id,
             ...this._options(),
@@ -366,7 +370,7 @@ class ApifyClient {
      * ```
      */
     task(id) {
-        (0, ow_1.default)(id, ow_1.default.string.nonEmpty);
+        (0, utils_1.parseArgument)(id, resourceIdSchema);
         return new task_1.TaskClient({
             id,
             ...this._options(),
@@ -393,7 +397,7 @@ class ApifyClient {
      * @see https://docs.apify.com/api/v2/schedule-get
      */
     schedule(id) {
-        (0, ow_1.default)(id, ow_1.default.string.nonEmpty);
+        (0, utils_1.parseArgument)(id, resourceIdSchema);
         return new schedule_1.ScheduleClient({
             id,
             ...this._options(),
@@ -409,7 +413,7 @@ class ApifyClient {
      * @see https://docs.apify.com/api/v2/user-get
      */
     user(id = consts_1.ME_USER_NAME_PLACEHOLDER) {
-        (0, ow_1.default)(id, ow_1.default.string.nonEmpty);
+        (0, utils_1.parseArgument)(id, resourceIdSchema);
         return new user_1.UserClient({
             id,
             ...this._options(),
@@ -436,7 +440,7 @@ class ApifyClient {
      * @see https://docs.apify.com/api/v2/webhook-get
      */
     webhook(id) {
-        (0, ow_1.default)(id, ow_1.default.string.nonEmpty);
+        (0, utils_1.parseArgument)(id, resourceIdSchema);
         return new webhook_1.WebhookClient({
             id,
             ...this._options(),
@@ -461,7 +465,7 @@ class ApifyClient {
      * @see https://docs.apify.com/api/v2/webhook-dispatch-get
      */
     webhookDispatch(id) {
-        (0, ow_1.default)(id, ow_1.default.string.nonEmpty);
+        (0, utils_1.parseArgument)(id, resourceIdSchema);
         return new webhook_dispatch_1.WebhookDispatchClient({
             id,
             ...this._options(),

package/dist/argument_validation_error.d.ts

@@ -0,0 +1,17 @@
+import type { z } from 'zod';
+/**
+ * Thrown when an argument fails schema validation.
+ *
+ * Its `message` is a human-readable sentence naming the offending field and the
+ * value it received (rather than a raw JSON dump). The structured
+ * {@link https://zod.dev | zod} issues are available on `issues`, and the
+ * original `ZodError` on `cause`, for programmatic inspection.
+ *
+ * `apify-client` sits below `@crawlee/core` and the Apify SDK in the dependency
+ * graph, so it defines its own error type rather than importing one from them.
+ */
+export declare class ArgumentValidationError extends Error {
+    /** Structured issues from the underlying schema check. */
+    readonly issues: z.ZodError['issues'];
+    constructor(error: z.ZodError, value: unknown, label?: string);
+}

package/dist/argument_validation_error.js

@@ -0,0 +1,157 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ArgumentValidationError = void 0;
+/** Formats a zod issue path like `groups[0]` or `countryCode`. */
+function formatIssuePath(path) {
+    let out = '';
+    for (const key of path) {
+        if (typeof key === 'number')
+            out += `[${key}]`;
+        else
+            out += out ? `.${String(key)}` : String(key);
+    }
+    return out;
+}
+/** Reads the value at `path` from the validated input, to include in the error. */
+function valueAtPath(root, path) {
+    let current = root;
+    for (const key of path) {
+        if (current === null || typeof current !== 'object')
+            return undefined;
+        current = current[key];
+    }
+    return current;
+}
+/**
+ * How much of a received string the message renders. A rejected argument can be arbitrarily large - a
+ * whole JSON payload passed where an object was expected - and its full text would swamp the message.
+ */
+const MAX_RECEIVED_STRING_LENGTH = 80;
+/** Renders a primitive received value for an error; skips objects/Dates (noisy). */
+function describeReceived(value) {
+    switch (typeof value) {
+        case 'string':
+            // An empty string would render as bare backticks - make it visible.
+            if (value === '')
+                return "''";
+            return value.length > MAX_RECEIVED_STRING_LENGTH
+                ? `${value.slice(0, MAX_RECEIVED_STRING_LENGTH)}...`
+                : value;
+        case 'number':
+        case 'boolean':
+            return String(value);
+        case 'bigint':
+            // Keep the `n` suffix, so a rejected bigint is not mistaken for a number.
+            return `${value}n`;
+        default:
+            return undefined;
+    }
+}
+/**
+ * Renders the issue's own sentence, except where zod's contradicts itself: a value of the expected type
+ * that fails that type's implicit constraint is still reported as the wrong *type*, giving "expected
+ * number, received number" for `Infinity` / `NaN` and "expected date, received Date" for an invalid
+ * `Date`. Name the constraint that actually failed instead.
+ */
+function describeIssue(issue, value) {
+    if (issue.code === 'invalid_type') {
+        if (issue.expected === 'number' && typeof value === 'number') {
+            return 'Invalid input: expected a finite number';
+        }
+        // A tag check, not `instanceof`, so a `Date` from another realm is named too.
+        if (issue.expected === 'date' && Object.prototype.toString.call(value) === '[object Date]') {
+            return 'Invalid input: expected a valid date';
+        }
+    }
+    return issue.message;
+}
+/**
+ * How many issue lines the message renders, before a closing "... and N more" line. Validating a
+ * large array - a dataset push, a request batch - can fail on every element, and rendering all of
+ * them would make the message megabytes long. The full set stays on `issues` either way.
+ */
+const MAX_RENDERED_LINES = 10;
+/**
+ * How deep into the value the lines for `issue` would sit, as a path length. Computed without
+ * rendering anything, so a union can weigh its arms before any string is built.
+ */
+function deepestIssueDepth(issue, baseDepth) {
+    const depth = baseDepth + issue.path.length;
+    if (issue.code === 'invalid_union') {
+        let deepest = -1;
+        for (const arm of issue.errors) {
+            for (const nested of arm)
+                deepest = Math.max(deepest, deepestIssueDepth(nested, depth));
+        }
+        return deepest;
+    }
+    return depth;
+}
+/** Collects one line per issue into `lines`; a union expands into a line per deepest-failing arm. */
+function collectIssueLines(issue, root, basePath, lines, counter) {
+    const path = [...basePath, ...issue.path];
+    // A union's own message is a bare "Invalid input" - the useful part is in `errors`,
+    // whose paths are relative to the union, hence passing `path` down as the base.
+    if (issue.code === 'invalid_union') {
+        // Only the arms that reached deepest are reported. An arm that failed nearer the root rejected a
+        // shape the value never had - for `[{ ok: 1 }, 2]` against `object | string | array`, the object
+        // and string arms fail on the whole array, and only the array arm can point at `[1]`. When every
+        // arm fails at the same depth, as for an argument of an outright wrong type, they are all kept.
+        const armDepths = issue.errors.map((arm) => arm.reduce((deepest, nested) => Math.max(deepest, deepestIssueDepth(nested, path.length)), -1));
+        const deepest = Math.max(...armDepths);
+        for (const [index, arm] of issue.errors.entries()) {
+            if (armDepths[index] !== deepest)
+                continue;
+            for (const nested of arm)
+                collectIssueLines(nested, root, path, lines, counter);
+        }
+        return;
+    }
+    counter.total += 1;
+    if (lines.length >= MAX_RENDERED_LINES)
+        return;
+    const location = path.length ? ` at \`${formatIssuePath(path)}\`` : '';
+    const value = valueAtPath(root, path);
+    const received = describeReceived(value);
+    const got = received === undefined ? '' : `, got \`${received}\``;
+    lines.push(`${describeIssue(issue, value)}${location}${got}`);
+}
+/**
+ * Formats a `ZodError` as a plain, human-readable message that names the
+ * offending field *and* the value it received (e.g. ``must match pattern
+ * /^[A-Z]{2}$/ at `countryCode`, got `CZE` ``) - closer to the old `ow` errors
+ * than zod's default, which omits the received value.
+ */
+function formatZodError(error, root, label) {
+    const lines = [];
+    const counter = { total: 0 };
+    for (const issue of error.issues)
+        collectIssueLines(issue, root, [], lines, counter);
+    // The label names the validated interface, the way ow's errors ended with "in object `X`".
+    const rendered = label ? lines.map((line) => `${line} in \`${label}\``) : [...lines];
+    const hidden = counter.total - lines.length;
+    if (hidden > 0)
+        rendered.push(`... and ${hidden} more problem${hidden === 1 ? '' : 's'}`);
+    return rendered.join('\n');
+}
+/**
+ * Thrown when an argument fails schema validation.
+ *
+ * Its `message` is a human-readable sentence naming the offending field and the
+ * value it received (rather than a raw JSON dump). The structured
+ * {@link https://zod.dev | zod} issues are available on `issues`, and the
+ * original `ZodError` on `cause`, for programmatic inspection.
+ *
+ * `apify-client` sits below `@crawlee/core` and the Apify SDK in the dependency
+ * graph, so it defines its own error type rather than importing one from them.
+ */
+class ArgumentValidationError extends Error {
+    /** Structured issues from the underlying schema check. */
+    issues;
+    constructor(error, value, label) {
+        super(formatZodError(error, value, label), { cause: error });
+        this.name = 'ArgumentValidationError';
+        this.issues = error.issues;
+    }
+}
+exports.ArgumentValidationError = ArgumentValidationError;

package/dist/base/api_client.d.ts

@@ -31,8 +31,8 @@ export declare abstract class ApiClient {
     params?: Record<string, unknown>;
     constructor(options: ApiClientOptions);
     protected _subResourceOptions<T>(moreOptions?: T): BaseOptions & T;
-    protected _url(path?: string): string;
-    protected _publicUrl(path?: string): string;
+    protected _url(path?: string | string[]): string;
+    protected _publicUrl(path?: string | string[]): string;
     protected _params<T>(endpointParams?: T): Record<string, unknown>;
     protected _toSafeId(id: string): string;
     /**

package/dist/base/api_client.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ApiClient = void 0;
+const utils_1 = require("../utils");
 /** @private */
 class ApiClient {
     id;
@@ -22,7 +23,7 @@ class ApiClient {
         this.baseUrl = baseUrl;
         this.publicBaseUrl = publicBaseUrl;
         this.resourcePath = resourcePath;
-        this.url = id ? `${baseUrl}/${resourcePath}/${this.safeId}` : `${baseUrl}/${resourcePath}`;
+        this.url = id ? `${baseUrl}/${resourcePath}/${(0, utils_1.toPathSegment)(this.safeId)}` : `${baseUrl}/${resourcePath}`;
         this.apifyClient = apifyClient;
         this.httpClient = httpClient;
         this.params = params;
@@ -38,20 +39,19 @@ class ApiClient {
         return { ...baseOptions, ...moreOptions };
     }
     _url(path) {
-        return path ? `${this.url}/${path}` : this.url;
+        return path ? `${this.url}/${(0, utils_1.toPath)(path)}` : this.url;
     }
     _publicUrl(path) {
         const url = this.id
-            ? `${this.publicBaseUrl}/${this.resourcePath}/${this.safeId}`
+            ? `${this.publicBaseUrl}/${this.resourcePath}/${(0, utils_1.toPathSegment)(this.safeId)}`
             : `${this.publicBaseUrl}/${this.resourcePath}`;
-        return path ? `${url}/${path}` : url;
+        return path ? `${url}/${(0, utils_1.toPath)(path)}` : url;
     }
     _params(endpointParams) {
         return { ...this.params, ...endpointParams };
     }
     _toSafeId(id) {
-        // The id has the format `username/actor-name`, so we only need to replace the first `/`.
-        return id.replace('/', '~');
+        return id.replaceAll('/', '~');
     }
     /**
      * Returns async iterator to iterate through all items and Promise that can be awaited to get first page of results.
@@ -69,9 +69,12 @@ class ApiClient {
                 return a;
             return Math.min(a, b);
         };
+        // `chunkSize` only sizes this loop's requests; it is not an API parameter, so it must not reach
+        // `_params()` and the query string.
+        const { chunkSize, ...listOptions } = options;
         const paginatedListPromise = getPaginatedList({
-            ...options,
-            limit: minForLimitParam(options.limit, options.chunkSize),
+            ...listOptions,
+            limit: minForLimitParam(options.limit, chunkSize),
         });
         async function* asyncGenerator() {
             let currentPage = await paginatedListPromise;
@@ -83,8 +86,8 @@ class ApiClient {
             while (currentPage.items.length > 0 && // Continue only if at least some items were returned in the last page.
                 remainingItems > 0) {
                 const newOptions = {
-                    ...options,
-                    limit: minForLimitParam(remainingItems, options.chunkSize),
+                    ...listOptions,
+                    limit: minForLimitParam(remainingItems, chunkSize),
                     offset: currentOffset,
                 };
                 currentPage = await getPaginatedList(newOptions);