apify-client 3.0.0-beta.4 → 3.0.0-beta.6

package/README.md

@@ -47,7 +47,9 @@ Besides greatly simplifying the process of querying the Apify API, the client pr
 Based on the endpoint, the client automatically extracts the relevant data and returns it in the
 expected format. Date strings are automatically converted to `Date` objects. For exceptions,
 we throw an `ApifyApiError`, which wraps the plain JSON errors returned by API and enriches
-them with other context for easier debugging.
+them with other context for easier debugging. The error is an instance of the subclass matching the
+HTTP status code, such as `NotFoundError` or `RateLimitError`, so a `catch` block can tell them apart
+with `instanceof`.
 
 ### Retries with exponential backoff
 

package/dist/apify_api_error.d.ts

@@ -1,10 +1,20 @@
 import type { AxiosResponse } from 'axios';
+import type { LiteralUnion } from 'type-fest';
+import type { ApifyApiErrorType } from './models.js';
+export type { ApifyApiErrorType } from './models.js';
 /**
  * An `ApifyApiError` is thrown for successful HTTP requests that reach the API,
  * but the API responds with an error response. Typically, those are rate limit
  * errors and internal errors, which are automatically retried, or validation
  * errors, which are thrown immediately, because a correction by the user is
  * needed.
+ *
+ * The thrown error is an instance of the subclass matching the HTTP status code of the response:
+ * {@link InvalidRequestError} (400), {@link UnauthorizedError} (401), {@link ForbiddenError} (403),
+ * {@link NotFoundError} (404), {@link ConflictError} (409), {@link RateLimitError} (429) or
+ * {@link ServerError} (5xx). Any other status code is thrown as a plain `ApifyApiError`. Every
+ * subclass extends `ApifyApiError`, so `instanceof ApifyApiError` matches all of them. Errors that
+ * share a status code are told apart by their `type`.
  */
 export declare class ApifyApiError extends Error {
     name: string;
@@ -18,9 +28,10 @@ export declare class ApifyApiError extends Error {
      */
     statusCode: number;
     /**
-     * The type of the error, as returned by the API.
+     * The type of the error, as returned by the API. Typed as the known {@link ApifyApiErrorType}
+     * values for autocompletion, while still accepting any string the API may return.
      */
-    type?: string;
+    type?: LiteralUnion<ApifyApiErrorType, string>;
     /**
      * Number of the API call attempt.
      */
@@ -46,6 +57,11 @@ export declare class ApifyApiError extends Error {
      * @hidden
      */
     constructor(response: AxiosResponse, attempt: number);
+    /**
+     * Creates the error for a failed response as an instance of the subclass matching its HTTP status code.
+     * @hidden
+     */
+    static fromResponse(response: AxiosResponse, attempt: number): ApifyApiError;
     private _safelyParsePathFromResponse;
     private _extractClientAndMethodFromStack;
     /**
@@ -54,7 +70,7 @@ export declare class ApifyApiError extends Error {
      *
      * Example:
      *
-     * ApifyApiError: Actor task was not found
+     * NotFoundError: Actor task was not found
      *   clientMethod: TaskClient.start
      *   statusCode: 404
      *   type: record-not-found
@@ -64,3 +80,43 @@ export declare class ApifyApiError extends Error {
      */
     private _createApiStack;
 }
+/**
+ * Thrown when the Apify API responds with HTTP 400 Bad Request, typically because the request
+ * failed validation.
+ */
+export declare class InvalidRequestError extends ApifyApiError {
+}
+/**
+ * Thrown when the Apify API responds with HTTP 401 Unauthorized, because the token is missing
+ * or invalid.
+ */
+export declare class UnauthorizedError extends ApifyApiError {
+}
+/**
+ * Thrown when the Apify API responds with HTTP 403 Forbidden, because the token lacks the
+ * permission for the operation.
+ */
+export declare class ForbiddenError extends ApifyApiError {
+}
+/**
+ * Thrown when the Apify API responds with HTTP 404 Not Found.
+ */
+export declare class NotFoundError extends ApifyApiError {
+}
+/**
+ * Thrown when the Apify API responds with HTTP 409 Conflict.
+ */
+export declare class ConflictError extends ApifyApiError {
+}
+/**
+ * Thrown when the Apify API responds with HTTP 429 Too Many Requests. The client retries such
+ * requests, so the error surfaces once the retries are exhausted.
+ */
+export declare class RateLimitError extends ApifyApiError {
+}
+/**
+ * Thrown when the Apify API responds with an HTTP 5xx status. The client retries such requests,
+ * so the error surfaces once the retries are exhausted.
+ */
+export declare class ServerError extends ApifyApiError {
+}

package/dist/apify_api_error.js

@@ -16,6 +16,13 @@ const CLIENT_METHOD_REGEX = /at( async)? ([A-Za-z]+(Collection)?Client)\._?([A-Z
  * errors and internal errors, which are automatically retried, or validation
  * errors, which are thrown immediately, because a correction by the user is
  * needed.
+ *
+ * The thrown error is an instance of the subclass matching the HTTP status code of the response:
+ * {@link InvalidRequestError} (400), {@link UnauthorizedError} (401), {@link ForbiddenError} (403),
+ * {@link NotFoundError} (404), {@link ConflictError} (409), {@link RateLimitError} (429) or
+ * {@link ServerError} (5xx). Any other status code is thrown as a plain `ApifyApiError`. Every
+ * subclass extends `ApifyApiError`, so `instanceof ApifyApiError` matches all of them. Errors that
+ * share a status code are told apart by their `type`.
  */
 export class ApifyApiError extends Error {
     name;
@@ -29,7 +36,8 @@ export class ApifyApiError extends Error {
      */
     statusCode;
     /**
-     * The type of the error, as returned by the API.
+     * The type of the error, as returned by the API. Typed as the known {@link ApifyApiErrorType}
+     * values for autocompletion, while still accepting any string the API may return.
      */
     type;
     /**
@@ -100,6 +108,14 @@ export class ApifyApiError extends Error {
         this.stack = this._createApiStack();
         this.data = errorData;
     }
+    /**
+     * Creates the error for a failed response as an instance of the subclass matching its HTTP status code.
+     * @hidden
+     */
+    static fromResponse(response, attempt) {
+        const ErrorClass = ERROR_CLASS_BY_STATUS[response.status] ?? (response.status >= 500 ? ServerError : ApifyApiError);
+        return new ErrorClass(response, attempt);
+    }
     _safelyParsePathFromResponse(response) {
         const urlString = response.config?.url;
         let url;
@@ -123,7 +139,7 @@ export class ApifyApiError extends Error {
      *
      * Example:
      *
-     * ApifyApiError: Actor task was not found
+     * NotFoundError: Actor task was not found
      *   clientMethod: TaskClient.start
      *   statusCode: 404
      *   type: record-not-found
@@ -145,3 +161,51 @@ export class ApifyApiError extends Error {
         return `${name}: ${this.message}\n${stack}`;
     }
 }
+/**
+ * Thrown when the Apify API responds with HTTP 400 Bad Request, typically because the request
+ * failed validation.
+ */
+export class InvalidRequestError extends ApifyApiError {
+}
+/**
+ * Thrown when the Apify API responds with HTTP 401 Unauthorized, because the token is missing
+ * or invalid.
+ */
+export class UnauthorizedError extends ApifyApiError {
+}
+/**
+ * Thrown when the Apify API responds with HTTP 403 Forbidden, because the token lacks the
+ * permission for the operation.
+ */
+export class ForbiddenError extends ApifyApiError {
+}
+/**
+ * Thrown when the Apify API responds with HTTP 404 Not Found.
+ */
+export class NotFoundError extends ApifyApiError {
+}
+/**
+ * Thrown when the Apify API responds with HTTP 409 Conflict.
+ */
+export class ConflictError extends ApifyApiError {
+}
+/**
+ * Thrown when the Apify API responds with HTTP 429 Too Many Requests. The client retries such
+ * requests, so the error surfaces once the retries are exhausted.
+ */
+export class RateLimitError extends ApifyApiError {
+}
+/**
+ * Thrown when the Apify API responds with an HTTP 5xx status. The client retries such requests,
+ * so the error surfaces once the retries are exhausted.
+ */
+export class ServerError extends ApifyApiError {
+}
+const ERROR_CLASS_BY_STATUS = {
+    400: InvalidRequestError,
+    401: UnauthorizedError,
+    403: ForbiddenError,
+    404: NotFoundError,
+    409: ConflictError,
+    429: RateLimitError,
+};

package/dist/base/resource_client.d.ts

@@ -1,4 +1,5 @@
 import type { ACT_JOB_STATUSES } from '@apify/consts';
+import type { z } from 'zod';
 import { ApiClient } from './api_client.js';
 export declare const SMALL_TIMEOUT_MILLIS: number;
 export declare const MEDIUM_TIMEOUT_MILLIS: number;
@@ -8,8 +9,8 @@ export declare const DEFAULT_TIMEOUT_MILLIS: number;
  * @private
  */
 export declare class ResourceClient extends ApiClient {
-    protected _get<T, R>(options?: T, timeoutMillis?: number): Promise<R | undefined>;
-    protected _update<T, R>(newFields: T, timeoutMillis?: number): Promise<R>;
+    protected _get<T, R>(schema: z.ZodType, options?: T, timeoutMillis?: number): Promise<R | undefined>;
+    protected _update<T, R>(schema: z.ZodType, newFields: T, timeoutMillis?: number): Promise<R>;
     protected _delete(timeoutMillis?: number): Promise<void>;
     /**
      * This function is used in Build and Run endpoints so it's kept
@@ -17,7 +18,7 @@ export declare class ResourceClient extends ApiClient {
      */
     protected _waitForFinish<R extends {
         status: (typeof ACT_JOB_STATUSES)[keyof typeof ACT_JOB_STATUSES];
-    }>(options?: WaitForFinishOptions): Promise<R>;
+    }>(schema: z.ZodType, options?: WaitForFinishOptions): Promise<R>;
 }
 export interface WaitForFinishOptions {
     waitSecs?: number;

package/dist/base/resource_client.js

@@ -1,5 +1,5 @@
 import { ACT_JOB_TERMINAL_STATUSES } from '@apify/consts';
-import { catchNotFoundOrThrow, parseDateFields, pluckData } from '../utils.js';
+import { catchNotFoundOrThrow, parseResponse } from '../utils.js';
 import { ApiClient } from './api_client.js';
 /**
  * We need to supply some number for the API,
@@ -15,7 +15,7 @@ export const DEFAULT_TIMEOUT_MILLIS = 360 * 1000; // 6 minutes
  * @private
  */
 export class ResourceClient extends ApiClient {
-    async _get(options = {}, timeoutMillis) {
+    async _get(schema, options = {}, timeoutMillis) {
         const requestOpts = {
             url: this._url(),
             method: 'GET',
@@ -24,14 +24,14 @@ export class ResourceClient extends ApiClient {
         };
         try {
             const response = await this.httpClient.call(requestOpts);
-            return parseDateFields(pluckData(response.data));
+            return parseResponse(response, schema);
         }
         catch (err) {
             catchNotFoundOrThrow(err);
         }
         return undefined;
     }
-    async _update(newFields, timeoutMillis) {
+    async _update(schema, newFields, timeoutMillis) {
         const response = await this.httpClient.call({
             url: this._url(),
             method: 'PUT',
@@ -39,7 +39,7 @@ export class ResourceClient extends ApiClient {
             data: newFields,
             timeout: timeoutMillis,
         });
-        return parseDateFields(pluckData(response.data));
+        return parseResponse(response, schema);
     }
     async _delete(timeoutMillis) {
         try {
@@ -58,7 +58,7 @@ export class ResourceClient extends ApiClient {
      * This function is used in Build and Run endpoints so it's kept
      * here to stay DRY.
      */
-    async _waitForFinish(options = {}) {
+    async _waitForFinish(schema, options = {}) {
         const { waitSecs = MAX_WAIT_FOR_FINISH } = options;
         const waitMillis = waitSecs * 1000;
         let job;
@@ -81,7 +81,7 @@ export class ResourceClient extends ApiClient {
             };
             try {
                 const response = await this.httpClient.call(requestOpts);
-                job = parseDateFields(pluckData(response.data));
+                job = parseResponse(response, schema);
             }
             catch (err) {
                 catchNotFoundOrThrow(err);

package/dist/base/resource_collection_client.d.ts

@@ -1,3 +1,4 @@
+import type { z } from 'zod';
 import type { PaginatedResponse, PaginationOptions } from '../utils.js';
 import { ApiClient } from './api_client.js';
 /**
@@ -8,11 +9,11 @@ export declare class ResourceCollectionClient extends ApiClient {
     /**
      * @private
      */
-    protected _list<T, R>(options?: T): Promise<R>;
+    protected _list<T, R>(schema: z.ZodType, options?: T): Promise<R>;
     /**
      * Returns async iterator to iterate through all items and Promise that can be awaited to get first page of results.
      */
-    protected _listPaginated<T extends PaginationOptions, Data, R extends PaginatedResponse<Data>>(options?: T): AsyncIterable<Data> & Promise<R>;
-    protected _create<D, R>(resource: D): Promise<R>;
-    protected _getOrCreate<D, R>(name?: string, resource?: D): Promise<R>;
+    protected _listPaginated<T extends PaginationOptions, Data, R extends PaginatedResponse<Data>>(schema: z.ZodType, options?: T): AsyncIterable<Data> & Promise<R>;
+    protected _create<D, R>(schema: z.ZodType, resource: D): Promise<R>;
+    protected _getOrCreate<D, R>(schema: z.ZodType, name?: string, resource?: D): Promise<R>;
 }

package/dist/base/resource_collection_client.js

@@ -1,4 +1,4 @@
-import { parseDateFields, pluckData } from '../utils.js';
+import { parseResponse } from '../utils.js';
 import { ApiClient } from './api_client.js';
 /**
  * Resource collection client.
@@ -8,36 +8,36 @@ export class ResourceCollectionClient extends ApiClient {
     /**
      * @private
      */
-    async _list(options = {}) {
+    async _list(schema, options = {}) {
         const response = await this.httpClient.call({
             url: this._url(),
             method: 'GET',
             params: this._params(options),
         });
-        return parseDateFields(pluckData(response.data));
+        return parseResponse(response, schema);
     }
     /**
      * Returns async iterator to iterate through all items and Promise that can be awaited to get first page of results.
      */
-    _listPaginated(options = {}) {
-        return this._listPaginatedFromCallback((this._list.bind(this)), options);
+    _listPaginated(schema, options = {}) {
+        return this._listPaginatedFromCallback(async (listOptions) => this._list(schema, listOptions), options);
     }
-    async _create(resource) {
+    async _create(schema, resource) {
         const response = await this.httpClient.call({
             url: this._url(),
             method: 'POST',
             params: this._params(),
             data: resource,
         });
-        return parseDateFields(pluckData(response.data));
+        return parseResponse(response, schema);
     }
-    async _getOrCreate(name, resource) {
+    async _getOrCreate(schema, name, resource) {
         const response = await this.httpClient.call({
             url: this._url(),
             method: 'POST',
             params: this._params({ name }),
             data: resource,
         });
-        return parseDateFields(pluckData(response.data));
+        return parseResponse(response, schema);
     }
 }