@prismicio/custom-types-client - npm Package Compare versions

Comparing version 1.2.0 to 1.3.0

dist/client.d.ts

@@ -1,3 +0,4 @@
-import type * as prismicT from "@prismicio/types";
+import type * as prismic from "@prismicio/client";
 import type { AbortSignalLike, FetchLike, RequestInitLike } from "./types";
+import { BulkOperation, BulkTransaction } from "./bulk";
 /**
@@ -58,2 +59,14 @@ * Configuration for creating a `CustomTypesClient`.
 /**
+ * Parameters for the `bulk()` client method.
+ */
+type BulkParams = {
+    /**
+     * Determines if the method stops a bulk request if the changes require
+     * deleting Prismic documents.
+     *
+     * @defaultValue false
+     */
+    deleteDocuments?: boolean;
+};
+/**
  * Create a client for the Prismic Custom Types API.
@@ -104,9 +117,11 @@ */
      * @typeParam TCustomType - The Custom Type returned from the API.
+     *
      * @param params - Parameters to override the client's default configuration.
      *
      * @returns All Custom Type models from the Prismic repository.
+     *
      * @throws {@link ForbiddenError} Thrown if the client is unauthorized to make
      *   requests.
      */
-    getAllCustomTypes<TCustomType extends prismicT.CustomTypeModel>(params?: CustomTypesClientMethodParams & FetchParams): Promise<TCustomType[]>;
+    getAllCustomTypes<TCustomType extends prismic.CustomTypeModel>(params?: CustomTypesClientMethodParams & FetchParams): Promise<TCustomType[]>;
     /**
@@ -116,2 +131,3 @@ * Returns a Custom Type model with a given ID from the Prismic repository.
      * @typeParam TCustomType - The Custom Type returned from the API.
+     *
      * @param id - ID of the Custom Type.
@@ -121,2 +137,3 @@ * @param params - Parameters to override the client's default configuration.
      * @returns The Custom Type model from the Prismic repository.
+     *
      * @throws {@link ForbiddenError} Thrown if the client is unauthorized to make
@@ -127,3 +144,3 @@ *   requests.
      */
-    getCustomTypeByID<TCustomType extends prismicT.CustomTypeModel>(id: string, params?: CustomTypesClientMethodParams & FetchParams): Promise<TCustomType>;
+    getCustomTypeByID<TCustomType extends prismic.CustomTypeModel>(id: string, params?: CustomTypesClientMethodParams & FetchParams): Promise<TCustomType>;
     /**
@@ -133,2 +150,3 @@ * Inserts a Custom Type model to the Prismic repository.
      * @typeParam TCustomType - The Custom Type to insert.
+     *
      * @param customType - The Custom Type to insert.
@@ -138,2 +156,3 @@ * @param params - Parameters to override the client's default configuration.
      * @returns The inserted Custom Type.
+     *
      * @throws {@link ForbiddenError} Thrown if the client is unauthorized to make
@@ -146,3 +165,3 @@ *   requests.
      */
-    insertCustomType<TCustomType extends prismicT.CustomTypeModel>(customType: TCustomType, params?: CustomTypesClientMethodParams & FetchParams): Promise<TCustomType>;
+    insertCustomType<TCustomType extends prismic.CustomTypeModel>(customType: TCustomType, params?: CustomTypesClientMethodParams & FetchParams): Promise<TCustomType>;
     /**
@@ -152,2 +171,3 @@ * Updates a Custom Type model from the Prismic repository.
      * @typeParam TCustomType - The updated Custom Type.
+     *
      * @param customType - The updated Custom Type.
@@ -157,2 +177,3 @@ * @param params - Parameters to override the client's default configuration.
      * @returns The updated Custom Type.
+     *
      * @throws {@link ForbiddenError} Thrown if the client is unauthorized to make
@@ -165,3 +186,3 @@ *   requests.
      */
-    updateCustomType<TCustomType extends prismicT.CustomTypeModel>(customType: TCustomType, params?: CustomTypesClientMethodParams & FetchParams): Promise<TCustomType>;
+    updateCustomType<TCustomType extends prismic.CustomTypeModel>(customType: TCustomType, params?: CustomTypesClientMethodParams & FetchParams): Promise<TCustomType>;
     /**
@@ -171,2 +192,3 @@ * Removes a Custom Type model from the Prismic repository.
      * @typeParam TCustomTypeID - The ID of the Custom Type.
+     *
      * @param id - The ID of the Custom Type to remove.
@@ -176,2 +198,3 @@ * @param params - Parameters to override the client's default configuration.
      * @returns The ID of the removed Custom Type.
+     *
      * @throws {@link ForbiddenError} Thrown if the client is unauthorized to make
@@ -186,9 +209,11 @@ *   requests.
      *   API.
+     *
      * @param params - Parameters to override the client's default configuration.
      *
      * @returns All Shared Slice models from the Prismic repository.
+     *
      * @throws {@link ForbiddenError} Thrown if the client is unauthorized to make
      *   requests.
      */
-    getAllSharedSlices<TSharedSliceModel extends prismicT.SharedSliceModel>(params?: CustomTypesClientMethodParams & FetchParams): Promise<TSharedSliceModel[]>;
+    getAllSharedSlices<TSharedSliceModel extends prismic.SharedSliceModel>(params?: CustomTypesClientMethodParams & FetchParams): Promise<TSharedSliceModel[]>;
     /**
@@ -199,2 +224,3 @@ * Returns a Shared Slice model with a given ID from the Prismic repository.
      *   API.
+     *
      * @param id - ID of the Shared Slice.
@@ -204,2 +230,3 @@ * @param params - Parameters to override the client's default configuration.
      * @returns The Shared Slice model from the Prismic repository.
+     *
      * @throws {@link ForbiddenError} Thrown if the client is unauthorized to make
@@ -210,3 +237,3 @@ *   requests.
      */
-    getSharedSliceByID<TSharedSliceModel extends prismicT.SharedSliceModel>(id: string, params?: CustomTypesClientMethodParams & FetchParams): Promise<TSharedSliceModel>;
+    getSharedSliceByID<TSharedSliceModel extends prismic.SharedSliceModel>(id: string, params?: CustomTypesClientMethodParams & FetchParams): Promise<TSharedSliceModel>;
     /**
@@ -216,2 +243,3 @@ * Inserts a Shared Slice model to the Prismic repository.
      * @typeParam TSharedSliceModel - The Shared Slice model to insert.
+     *
      * @param slice - The Shared Slice model to insert.
@@ -221,2 +249,3 @@ * @param params - Parameters to override the client's default configuration.
      * @returns The inserted Shared Slice model.
+     *
      * @throws {@link ForbiddenError} Thrown if the client is unauthorized to make
@@ -229,3 +258,3 @@ *   requests.
      */
-    insertSharedSlice<TSharedSliceModel extends prismicT.SharedSliceModel>(slice: TSharedSliceModel, params?: CustomTypesClientMethodParams & FetchParams): Promise<TSharedSliceModel>;
+    insertSharedSlice<TSharedSliceModel extends prismic.SharedSliceModel>(slice: TSharedSliceModel, params?: CustomTypesClientMethodParams & FetchParams): Promise<TSharedSliceModel>;
     /**
@@ -235,2 +264,3 @@ * Updates a Shared Slice model from the Prismic repository.
      * @typeParam TSharedSliceModel - The updated Shared Slice model.
+     *
      * @param slice - The updated Shared Slice model.
@@ -240,2 +270,3 @@ * @param params - Parameters to override the client's default configuration.
      * @returns The updated Shared Slice model.
+     *
      * @throws {@link ForbiddenError} Thrown if the client is unauthorized to make
@@ -248,3 +279,3 @@ *   requests.
      */
-    updateSharedSlice<TSharedSliceModel extends prismicT.SharedSliceModel>(slice: TSharedSliceModel, params?: CustomTypesClientMethodParams & FetchParams): Promise<TSharedSliceModel>;
+    updateSharedSlice<TSharedSliceModel extends prismic.SharedSliceModel>(slice: TSharedSliceModel, params?: CustomTypesClientMethodParams & FetchParams): Promise<TSharedSliceModel>;
     /**
@@ -254,2 +285,3 @@ * Removes a Shared Slice model from the Prismic repository.
      * @typeParam TSharedSliceID - The ID of the Shared Slice.
+     *
      * @param id - The ID of the Shared Slice to remove.
@@ -259,2 +291,3 @@ * @param params - Parameters to override the client's default configuration.
      * @returns The ID of the removed Shared Slice.
+     *
      * @throws {@link ForbiddenError} Thrown if the client is unauthorized to make
@@ -265,2 +298,24 @@ *   requests.
     /**
+     * Performs multiple insert, update, and/or delete operations in a single
+     * transaction.
+     *
+     * @example
+     *
+     * ```ts
+     * const bulkTransaction = createBulkTransaction();
+     * bulkTransaction.insertCustomType(myCustomType);
+     * bulkTransaction.deleteSlice(mySlice);
+     *
+     * await client.bulk(bulkTransaction);
+     * ```
+     *
+     * @param operations - A `BulkTransaction` containing all operations or an
+     *   array of objects describing an operation.
+     * @param params - Parameters that determine how the method behaves and for
+     *   overriding the client's default configuration.
+     *
+     * @returns An array of objects describing the operations.
+     */
+    bulk(operations: BulkTransaction | BulkOperation[], params?: BulkParams & CustomTypesClientMethodParams & FetchParams): Promise<BulkOperation[]>;
+    /**
      * Performs a network request using the configured `fetch` function. It
@@ -271,2 +326,3 @@ * assumes all successful responses will have a JSON content type. It also
      * @typeParam T - The JSON response.
+     *
      * @param path - URL to the resource to fetch.
@@ -277,2 +333,3 @@ * @param params - Parameters to override the client's default configuration.
      * @returns The response from the network request, if any.
+     *
      * @throws {@link ForbiddenError} Thrown if the client is unauthorized to make
@@ -279,0 +336,0 @@ *   requests.

dist/client.js

@@ -7,3 +7,4 @@ var __defProp = Object.defineProperty;
 };
-import { MissingFetchError, NotFoundError, ConflictError, ForbiddenError, UnauthorizedError, InvalidPayloadError, PrismicError } from "./errors.js";
+import { MissingFetchError, NotFoundError, ConflictError, BulkTransactionLimitError, ForbiddenError, UnauthorizedError, InvalidPayloadError, BulkTransactionConfirmationError, PrismicError } from "./errors.js";
+import { BulkTransaction } from "./bulk.js";
 const DEFAULT_CUSTOM_TYPES_API_ENDPOINT = "https://customtypes.prismic.io";
@@ -18,7 +19,33 @@ const createPostFetchRequestInit = (body) => {
 class CustomTypesClient {
+  /**
+   * Create a client for the Prismic Custom Types API.
+   */
   constructor(config) {
+    /**
+     * Name of the Prismic repository.
+     */
     __publicField(this, "repositoryName");
+    /**
+     * The Prismic Custom Types API endpoint for the repository. The standard
+     * Custom Types API endpoint will be used if no value is provided.
+     *
+     * @defaultValue `https://customtypes.prismic.io`
+     */
     __publicField(this, "endpoint");
+    /**
+     * The secure token for accessing the Prismic Custom Types API. This is
+     * required to call any Custom Type API methods.
+     */
     __publicField(this, "token");
+    /**
+     * The function used to make network requests to the Prismic Custom Types API.
+     * In environments where a global `fetch` function does not exist, such as
+     * Node.js, this function must be provided.
+     */
     __publicField(this, "fetchFn");
+    /**
+     * Options provided to the client's `fetch()` on all network requests. These
+     * options will be merged with internally required options. They can also be
+     * overriden on a per-query basis using the query's `fetchOptions` parameter.
+     */
     __publicField(this, "fetchOptions");
@@ -43,8 +70,52 @@ this.repositoryName = config.repositoryName;
   }
+  /**
+   * Returns all Custom Types models from the Prismic repository.
+   *
+   * @typeParam TCustomType - The Custom Type returned from the API.
+   *
+   * @param params - Parameters to override the client's default configuration.
+   *
+   * @returns All Custom Type models from the Prismic repository.
+   *
+   * @throws {@link ForbiddenError} Thrown if the client is unauthorized to make
+   *   requests.
+   */
   async getAllCustomTypes(params) {
     return await this.fetch("./customtypes", params);
   }
+  /**
+   * Returns a Custom Type model with a given ID from the Prismic repository.
+   *
+   * @typeParam TCustomType - The Custom Type returned from the API.
+   *
+   * @param id - ID of the Custom Type.
+   * @param params - Parameters to override the client's default configuration.
+   *
+   * @returns The Custom Type model from the Prismic repository.
+   *
+   * @throws {@link ForbiddenError} Thrown if the client is unauthorized to make
+   *   requests.
+   * @throws {@link NotFoundError} Thrown if a Custom Type with the given ID
+   *   cannot be found.
+   */
   async getCustomTypeByID(id, params) {
     return await this.fetch(`./customtypes/${id}`, params);
   }
+  /**
+   * Inserts a Custom Type model to the Prismic repository.
+   *
+   * @typeParam TCustomType - The Custom Type to insert.
+   *
+   * @param customType - The Custom Type to insert.
+   * @param params - Parameters to override the client's default configuration.
+   *
+   * @returns The inserted Custom Type.
+   *
+   * @throws {@link ForbiddenError} Thrown if the client is unauthorized to make
+   *   requests.
+   * @throws {@link InvalidPayloadError} Thrown if an invalid Custom Type is
+   *   provided.
+   * @throws {@link ConflictError} Thrown if a Custom Type with the given ID
+   *   already exists.
+   */
   async insertCustomType(customType, params) {
@@ -54,2 +125,19 @@ await this.fetch("./customtypes/insert", params, createPostFetchRequestInit(customType));
   }
+  /**
+   * Updates a Custom Type model from the Prismic repository.
+   *
+   * @typeParam TCustomType - The updated Custom Type.
+   *
+   * @param customType - The updated Custom Type.
+   * @param params - Parameters to override the client's default configuration.
+   *
+   * @returns The updated Custom Type.
+   *
+   * @throws {@link ForbiddenError} Thrown if the client is unauthorized to make
+   *   requests.
+   * @throws {@link InvalidPayloadError} Thrown if an invalid Custom Type is
+   *   provided.
+   * @throws {@link NotFoundError} Thrown if a Custom Type with the given ID
+   *   cannot be found.
+   */
   async updateCustomType(customType, params) {
@@ -59,2 +147,15 @@ await this.fetch("./customtypes/update", params, createPostFetchRequestInit(customType));
   }
+  /**
+   * Removes a Custom Type model from the Prismic repository.
+   *
+   * @typeParam TCustomTypeID - The ID of the Custom Type.
+   *
+   * @param id - The ID of the Custom Type to remove.
+   * @param params - Parameters to override the client's default configuration.
+   *
+   * @returns The ID of the removed Custom Type.
+   *
+   * @throws {@link ForbiddenError} Thrown if the client is unauthorized to make
+   *   requests.
+   */
   async removeCustomType(id, params) {
@@ -66,8 +167,54 @@ await this.fetch(`./customtypes/${id}`, params, {
   }
+  /**
+   * Returns all Shared Slice models from the Prismic repository.
+   *
+   * @typeParam TSharedSliceModel - The Shared Slice model returned from the
+   *   API.
+   *
+   * @param params - Parameters to override the client's default configuration.
+   *
+   * @returns All Shared Slice models from the Prismic repository.
+   *
+   * @throws {@link ForbiddenError} Thrown if the client is unauthorized to make
+   *   requests.
+   */
   async getAllSharedSlices(params) {
     return await this.fetch("./slices", params);
   }
+  /**
+   * Returns a Shared Slice model with a given ID from the Prismic repository.
+   *
+   * @typeParam TSharedSliceModel - The Shared Slice model returned from the
+   *   API.
+   *
+   * @param id - ID of the Shared Slice.
+   * @param params - Parameters to override the client's default configuration.
+   *
+   * @returns The Shared Slice model from the Prismic repository.
+   *
+   * @throws {@link ForbiddenError} Thrown if the client is unauthorized to make
+   *   requests.
+   * @throws {@link NotFoundError} Thrown if a Shared Slice with the given ID
+   *   cannot be found.
+   */
   async getSharedSliceByID(id, params) {
     return await this.fetch(`./slices/${id}`, params);
   }
+  /**
+   * Inserts a Shared Slice model to the Prismic repository.
+   *
+   * @typeParam TSharedSliceModel - The Shared Slice model to insert.
+   *
+   * @param slice - The Shared Slice model to insert.
+   * @param params - Parameters to override the client's default configuration.
+   *
+   * @returns The inserted Shared Slice model.
+   *
+   * @throws {@link ForbiddenError} Thrown if the client is unauthorized to make
+   *   requests.
+   * @throws {@link InvalidPayloadError} Thrown if an invalid Shared Slice model
+   *   is provided.
+   * @throws {@link ConflictError} Thrown if a Shared Slice with the given ID
+   *   already exists.
+   */
   async insertSharedSlice(slice, params) {
@@ -77,2 +224,19 @@ await this.fetch("./slices/insert", params, createPostFetchRequestInit(slice));
   }
+  /**
+   * Updates a Shared Slice model from the Prismic repository.
+   *
+   * @typeParam TSharedSliceModel - The updated Shared Slice model.
+   *
+   * @param slice - The updated Shared Slice model.
+   * @param params - Parameters to override the client's default configuration.
+   *
+   * @returns The updated Shared Slice model.
+   *
+   * @throws {@link ForbiddenError} Thrown if the client is unauthorized to make
+   *   requests.
+   * @throws {@link InvalidPayloadError} Thrown if an invalid Shared Slice model
+   *   is provided.
+   * @throws {@link NotFoundError} Thrown if a Shared Slice with the given ID
+   *   cannot be found.
+   */
   async updateSharedSlice(slice, params) {
@@ -82,2 +246,15 @@ await this.fetch("./slices/update", params, createPostFetchRequestInit(slice));
   }
+  /**
+   * Removes a Shared Slice model from the Prismic repository.
+   *
+   * @typeParam TSharedSliceID - The ID of the Shared Slice.
+   *
+   * @param id - The ID of the Shared Slice to remove.
+   * @param params - Parameters to override the client's default configuration.
+   *
+   * @returns The ID of the removed Shared Slice.
+   *
+   * @throws {@link ForbiddenError} Thrown if the client is unauthorized to make
+   *   requests.
+   */
   async removeSharedSlice(id, params) {
@@ -89,2 +266,52 @@ await this.fetch(`./slices/${id}`, params, {
   }
+  /**
+   * Performs multiple insert, update, and/or delete operations in a single
+   * transaction.
+   *
+   * @example
+   *
+   * ```ts
+   * const bulkTransaction = createBulkTransaction();
+   * bulkTransaction.insertCustomType(myCustomType);
+   * bulkTransaction.deleteSlice(mySlice);
+   *
+   * await client.bulk(bulkTransaction);
+   * ```
+   *
+   * @param operations - A `BulkTransaction` containing all operations or an
+   *   array of objects describing an operation.
+   * @param params - Parameters that determine how the method behaves and for
+   *   overriding the client's default configuration.
+   *
+   * @returns An array of objects describing the operations.
+   */
+  async bulk(operations, params) {
+    const resolvedOperations = operations instanceof BulkTransaction ? operations.operations : operations;
+    await this.fetch("./bulk", params, createPostFetchRequestInit({
+      confirmDeleteDocuments: (params == null ? void 0 : params.deleteDocuments) ?? false,
+      changes: resolvedOperations
+    }));
+    return resolvedOperations;
+  }
+  /**
+   * Performs a network request using the configured `fetch` function. It
+   * assumes all successful responses will have a JSON content type. It also
+   * normalizes unsuccessful network requests.
+   *
+   * @typeParam T - The JSON response.
+   *
+   * @param path - URL to the resource to fetch.
+   * @param params - Parameters to override the client's default configuration.
+   * @param requestInit - `RequestInit` overrides for the `fetch` request.
+   *
+   * @returns The response from the network request, if any.
+   *
+   * @throws {@link ForbiddenError} Thrown if the client is unauthorized to make
+   *   requests.
+   * @throws {@link InvalidPayloadError} Thrown if the given body is invalid.
+   * @throws {@link ConflictError} Thrown if an entity with the given ID already
+   *   exists.
+   * @throws {@link NotFoundError} Thrown if the requested entity could not be
+   *   found.
+   */
   async fetch(path, params = {}, requestInit = {}) {
@@ -116,2 +343,6 @@ var _a, _b, _c, _d;
       }
+      case 202: {
+        const json = await res.json();
+        throw new BulkTransactionConfirmationError("The bulk transaction will delete documents. Confirm before trying again.", { url, response: json });
+      }
       case 400: {
@@ -127,2 +358,5 @@ const text = await res.text();
         const json = await res.json();
+        if ("details" in json) {
+          throw new BulkTransactionLimitError("The bulk transaction reached or surpassed the limit of allowed commands.", { url, response: json });
+        }
         throw new ForbiddenError(json.message, { url, response: json });
@@ -129,0 +363,0 @@ }

dist/errors.d.ts

@@ -47,2 +47,15 @@ /**
 /**
+ * The response returned by the Prismic Custom Types API bulk transaction
+ * endpoint when a soft or hard limit is reached.
+ */
+type BulkTransactionErrorAPIResponse = {
+    details: {
+        customTypes: {
+            id: string;
+            numberOfDocuments: number;
+            url: string;
+        }[];
+    };
+};
+/**
  * Represents an error when making an unauthorized Prismic Custom Types API
@@ -74,2 +87,14 @@ * request.
 /**
+ * Represents an error when a bulk transaction requires confirmation to delete
+ * documents.
+ */
+export declare class BulkTransactionConfirmationError extends PrismicError<BulkTransactionErrorAPIResponse> {
+}
+/**
+ * Represents an error when a bulk transaction reached the limit of operations
+ * allowed by the API.
+ */
+export declare class BulkTransactionLimitError extends PrismicError<BulkTransactionErrorAPIResponse> {
+}
+/**
  * Represents an error when a valid `fetch` function is not available to the
@@ -76,0 +101,0 @@ * Prismic Custom Types API client.

dist/errors.js

@@ -8,5 +8,19 @@ var __defProp = Object.defineProperty;
 class PrismicError extends Error {
+  /**
+   * Creates a new `PrismicError`.
+   *
+   * @param message - A description of the error.
+   * @param args - Metadata about the failed network request.
+   *
+   * @returns A `PrismicError` for the given error state.
+   */
   constructor(message, args) {
     super(message);
+    /**
+     * The Prismic Custom Types API URL used for the failed request.
+     */
     __publicField(this, "url");
+    /**
+     * The Prismic Custom Types API response from the failed request.
+     */
     __publicField(this, "response");
@@ -27,5 +41,11 @@ this.url = args.url;
 }
+class BulkTransactionConfirmationError extends PrismicError {
+}
+class BulkTransactionLimitError extends PrismicError {
+}
 class MissingFetchError extends Error {
 }
 export {
+  BulkTransactionConfirmationError,
+  BulkTransactionLimitError,
   ConflictError,
@@ -32,0 +52,0 @@ ForbiddenError,

dist/index.d.ts

 export { createClient, CustomTypesClient } from "./client";
 export type { CustomTypesClientConfig, CustomTypesClientMethodParams, } from "./client";
-export { PrismicError, ConflictError, ForbiddenError, UnauthorizedError, InvalidPayloadError, MissingFetchError, NotFoundError, } from "./errors";
+export { createBulkTransaction, BulkTransaction, BulkOperationType, } from "./bulk";
+export type { BulkOperation, BulkTransactionModels } from "./bulk";
+export { PrismicError, ConflictError, ForbiddenError, UnauthorizedError, InvalidPayloadError, MissingFetchError, NotFoundError, BulkTransactionLimitError, BulkTransactionConfirmationError, } from "./errors";
 export type { FetchLike, ResponseLike, RequestInitLike } from "./types";

dist/index.js

 import { CustomTypesClient, createClient } from "./client.js";
-import { ConflictError, ForbiddenError, InvalidPayloadError, MissingFetchError, NotFoundError, PrismicError, UnauthorizedError } from "./errors.js";
+import { BulkOperationType, BulkTransaction, createBulkTransaction } from "./bulk.js";
+import { BulkTransactionConfirmationError, BulkTransactionLimitError, ConflictError, ForbiddenError, InvalidPayloadError, MissingFetchError, NotFoundError, PrismicError, UnauthorizedError } from "./errors.js";
 export {
+  BulkOperationType,
+  BulkTransaction,
+  BulkTransactionConfirmationError,
+  BulkTransactionLimitError,
   ConflictError,
@@ -12,4 +17,5 @@ CustomTypesClient,
   UnauthorizedError,
+  createBulkTransaction,
   createClient
 };
 //# sourceMappingURL=index.js.map

package.json

 {
 	"name": "@prismicio/custom-types-client",
-	"version": "1.2.0",
+	"version": "1.3.0",
 	"description": "JavaScript client to interact with the Prismic Custom Types API",
@@ -47,25 +47,25 @@ "keywords": [
 	"dependencies": {
-		"@prismicio/types": "^0.2.4"
+		"@prismicio/client": "^7.3.1"
 	},
 	"devDependencies": {
-		"@prismicio/mock": "^0.1.1",
-		"@size-limit/preset-small-lib": "^8.1.0",
-		"@typescript-eslint/eslint-plugin": "^5.46.1",
-		"@typescript-eslint/parser": "^5.46.1",
-		"@vitest/coverage-c8": "^0.25.8",
-		"abort-controller": "^3.0.0",
-		"eslint": "^8.29.0",
-		"eslint-config-prettier": "^8.5.0",
-		"eslint-plugin-prettier": "^4.2.1",
+		"@prismicio/mock": "^0.3.1",
+		"@size-limit/preset-small-lib": "^11.0.2",
+		"@trivago/prettier-plugin-sort-imports": "^4.3.0",
+		"@types/node": "^20.11.7",
+		"@typescript-eslint/eslint-plugin": "^6.19.1",
+		"@typescript-eslint/parser": "^6.19.1",
+		"@vitest/coverage-v8": "^1.2.2",
+		"eslint": "^8.56.0",
+		"eslint-config-prettier": "^9.1.0",
+		"eslint-plugin-prettier": "^5.1.3",
 		"eslint-plugin-tsdoc": "^0.2.17",
-		"msw": "^0.49.2",
-		"node-fetch": "^3.3.0",
-		"prettier": "^2.8.1",
-		"prettier-plugin-jsdoc": "^0.4.2",
-		"size-limit": "^8.1.0",
+		"msw": "^2.1.5",
+		"prettier": "^3.2.4",
+		"prettier-plugin-jsdoc": "^1.3.0",
+		"size-limit": "^11.0.2",
 		"standard-version": "^9.5.0",
-		"typescript": "^4.9.4",
-		"vite": "^4.0.1",
-		"vite-plugin-sdk": "^0.1.0",
-		"vitest": "^0.25.8"
+		"typescript": "^5.3.3",
+		"vite": "^5.0.12",
+		"vite-plugin-sdk": "^0.1.2",
+		"vitest": "^1.2.2"
 	},
@@ -72,0 +72,0 @@ "engines": {

src/client.ts

@@ -1,14 +0,19 @@
-import type * as prismicT from "@prismicio/types";
+import type * as prismic from "@prismicio/client";
 
 import type { AbortSignalLike, FetchLike, RequestInitLike } from "./types";
+
 import {
-	PrismicError,
+	BulkTransactionConfirmationError,
+	BulkTransactionLimitError,
+	ConflictError,
+	ForbiddenError,
+	InvalidPayloadError,
 	MissingFetchError,
-	ConflictError,
 	NotFoundError,
-	ForbiddenError,
+	PrismicError,
 	UnauthorizedError,
-	InvalidPayloadError,
 } from "./errors";
 
+import { BulkOperation, BulkTransaction } from "./bulk";
+
 /**
@@ -84,2 +89,15 @@ * The default endpoint for the Prismic Custom Types API.
 /**
+ * Parameters for the `bulk()` client method.
+ */
+type BulkParams = {
+	/**
+	 * Determines if the method stops a bulk request if the changes require
+	 * deleting Prismic documents.
+	 *
+	 * @defaultValue false
+	 */
+	deleteDocuments?: boolean;
+};
+
+/**
  * Create a `RequestInit` object for a POST `fetch` request. The provided body
@@ -187,9 +205,11 @@ * will be run through `JSON.stringify`.
 	 * @typeParam TCustomType - The Custom Type returned from the API.
+	 *
 	 * @param params - Parameters to override the client's default configuration.
 	 *
 	 * @returns All Custom Type models from the Prismic repository.
+	 *
 	 * @throws {@link ForbiddenError} Thrown if the client is unauthorized to make
 	 *   requests.
 	 */
-	async getAllCustomTypes<TCustomType extends prismicT.CustomTypeModel>(
+	async getAllCustomTypes<TCustomType extends prismic.CustomTypeModel>(
 		params?: CustomTypesClientMethodParams & FetchParams,
@@ -204,2 +224,3 @@ ): Promise<TCustomType[]> {
 	 * @typeParam TCustomType - The Custom Type returned from the API.
+	 *
 	 * @param id - ID of the Custom Type.
@@ -209,2 +230,3 @@ * @param params - Parameters to override the client's default configuration.
 	 * @returns The Custom Type model from the Prismic repository.
+	 *
 	 * @throws {@link ForbiddenError} Thrown if the client is unauthorized to make
@@ -215,3 +237,3 @@ *   requests.
 	 */
-	async getCustomTypeByID<TCustomType extends prismicT.CustomTypeModel>(
+	async getCustomTypeByID<TCustomType extends prismic.CustomTypeModel>(
 		id: string,
@@ -227,2 +249,3 @@ params?: CustomTypesClientMethodParams & FetchParams,
 	 * @typeParam TCustomType - The Custom Type to insert.
+	 *
 	 * @param customType - The Custom Type to insert.
@@ -232,2 +255,3 @@ * @param params - Parameters to override the client's default configuration.
 	 * @returns The inserted Custom Type.
+	 *
 	 * @throws {@link ForbiddenError} Thrown if the client is unauthorized to make
@@ -240,3 +264,3 @@ *   requests.
 	 */
-	async insertCustomType<TCustomType extends prismicT.CustomTypeModel>(
+	async insertCustomType<TCustomType extends prismic.CustomTypeModel>(
 		customType: TCustomType,
@@ -258,2 +282,3 @@ params?: CustomTypesClientMethodParams & FetchParams,
 	 * @typeParam TCustomType - The updated Custom Type.
+	 *
 	 * @param customType - The updated Custom Type.
@@ -263,2 +288,3 @@ * @param params - Parameters to override the client's default configuration.
 	 * @returns The updated Custom Type.
+	 *
 	 * @throws {@link ForbiddenError} Thrown if the client is unauthorized to make
@@ -271,3 +297,3 @@ *   requests.
 	 */
-	async updateCustomType<TCustomType extends prismicT.CustomTypeModel>(
+	async updateCustomType<TCustomType extends prismic.CustomTypeModel>(
 		customType: TCustomType,
@@ -289,2 +315,3 @@ params?: CustomTypesClientMethodParams & FetchParams,
 	 * @typeParam TCustomTypeID - The ID of the Custom Type.
+	 *
 	 * @param id - The ID of the Custom Type to remove.
@@ -294,2 +321,3 @@ * @param params - Parameters to override the client's default configuration.
 	 * @returns The ID of the removed Custom Type.
+	 *
 	 * @throws {@link ForbiddenError} Thrown if the client is unauthorized to make
@@ -314,9 +342,11 @@ *   requests.
 	 *   API.
+	 *
 	 * @param params - Parameters to override the client's default configuration.
 	 *
 	 * @returns All Shared Slice models from the Prismic repository.
+	 *
 	 * @throws {@link ForbiddenError} Thrown if the client is unauthorized to make
 	 *   requests.
 	 */
-	async getAllSharedSlices<TSharedSliceModel extends prismicT.SharedSliceModel>(
+	async getAllSharedSlices<TSharedSliceModel extends prismic.SharedSliceModel>(
 		params?: CustomTypesClientMethodParams & FetchParams,
@@ -332,2 +362,3 @@ ): Promise<TSharedSliceModel[]> {
 	 *   API.
+	 *
 	 * @param id - ID of the Shared Slice.
@@ -337,2 +368,3 @@ * @param params - Parameters to override the client's default configuration.
 	 * @returns The Shared Slice model from the Prismic repository.
+	 *
 	 * @throws {@link ForbiddenError} Thrown if the client is unauthorized to make
@@ -343,3 +375,3 @@ *   requests.
 	 */
-	async getSharedSliceByID<TSharedSliceModel extends prismicT.SharedSliceModel>(
+	async getSharedSliceByID<TSharedSliceModel extends prismic.SharedSliceModel>(
 		id: string,
@@ -355,2 +387,3 @@ params?: CustomTypesClientMethodParams & FetchParams,
 	 * @typeParam TSharedSliceModel - The Shared Slice model to insert.
+	 *
 	 * @param slice - The Shared Slice model to insert.
@@ -360,2 +393,3 @@ * @param params - Parameters to override the client's default configuration.
 	 * @returns The inserted Shared Slice model.
+	 *
 	 * @throws {@link ForbiddenError} Thrown if the client is unauthorized to make
@@ -368,3 +402,3 @@ *   requests.
 	 */
-	async insertSharedSlice<TSharedSliceModel extends prismicT.SharedSliceModel>(
+	async insertSharedSlice<TSharedSliceModel extends prismic.SharedSliceModel>(
 		slice: TSharedSliceModel,
@@ -386,2 +420,3 @@ params?: CustomTypesClientMethodParams & FetchParams,
 	 * @typeParam TSharedSliceModel - The updated Shared Slice model.
+	 *
 	 * @param slice - The updated Shared Slice model.
@@ -391,2 +426,3 @@ * @param params - Parameters to override the client's default configuration.
 	 * @returns The updated Shared Slice model.
+	 *
 	 * @throws {@link ForbiddenError} Thrown if the client is unauthorized to make
@@ -399,3 +435,3 @@ *   requests.
 	 */
-	async updateSharedSlice<TSharedSliceModel extends prismicT.SharedSliceModel>(
+	async updateSharedSlice<TSharedSliceModel extends prismic.SharedSliceModel>(
 		slice: TSharedSliceModel,
@@ -417,2 +453,3 @@ params?: CustomTypesClientMethodParams & FetchParams,
 	 * @typeParam TSharedSliceID - The ID of the Shared Slice.
+	 *
 	 * @param id - The ID of the Shared Slice to remove.
@@ -422,2 +459,3 @@ * @param params - Parameters to override the client's default configuration.
 	 * @returns The ID of the removed Shared Slice.
+	 *
 	 * @throws {@link ForbiddenError} Thrown if the client is unauthorized to make
@@ -438,2 +476,44 @@ *   requests.
 	/**
+	 * Performs multiple insert, update, and/or delete operations in a single
+	 * transaction.
+	 *
+	 * @example
+	 *
+	 * ```ts
+	 * const bulkTransaction = createBulkTransaction();
+	 * bulkTransaction.insertCustomType(myCustomType);
+	 * bulkTransaction.deleteSlice(mySlice);
+	 *
+	 * await client.bulk(bulkTransaction);
+	 * ```
+	 *
+	 * @param operations - A `BulkTransaction` containing all operations or an
+	 *   array of objects describing an operation.
+	 * @param params - Parameters that determine how the method behaves and for
+	 *   overriding the client's default configuration.
+	 *
+	 * @returns An array of objects describing the operations.
+	 */
+	async bulk(
+		operations: BulkTransaction | BulkOperation[],
+		params?: BulkParams & CustomTypesClientMethodParams & FetchParams,
+	): Promise<BulkOperation[]> {
+		const resolvedOperations =
+			operations instanceof BulkTransaction
+				? operations.operations
+				: operations;
+
+		await this.fetch(
+			"./bulk",
+			params,
+			createPostFetchRequestInit({
+				confirmDeleteDocuments: params?.deleteDocuments ?? false,
+				changes: resolvedOperations,
+			}),
+		);
+
+		return resolvedOperations;
+	}
+
+	/**
 	 * Performs a network request using the configured `fetch` function. It
@@ -444,2 +524,3 @@ * assumes all successful responses will have a JSON content type. It also
 	 * @typeParam T - The JSON response.
+	 *
 	 * @param path - URL to the resource to fetch.
@@ -450,2 +531,3 @@ * @param params - Parameters to override the client's default configuration.
 	 * @returns The response from the network request, if any.
+	 *
 	 * @throws {@link ForbiddenError} Thrown if the client is unauthorized to make
@@ -513,2 +595,13 @@ *   requests.
 
+			// Accepted
+			// - Soft limit reached for bulk request (requires confirmation)
+			case 202: {
+				const json = await res.json();
+
+				throw new BulkTransactionConfirmationError(
+					"The bulk transaction will delete documents. Confirm before trying again.",
+					{ url, response: json },
+				);
+			}
+
 			// Bad Request
@@ -533,5 +626,13 @@ // - Invalid body sent
 			// - Incorrect token
+			// - Hard limit reached for bulk request (cannot process)
 			case 403: {
 				const json = await res.json();
 
+				if ("details" in json) {
+					throw new BulkTransactionLimitError(
+						"The bulk transaction reached or surpassed the limit of allowed commands.",
+						{ url, response: json },
+					);
+				}
+
 				throw new ForbiddenError(json.message, { url, response: json });
@@ -538,0 +639,0 @@ }

src/errors.ts

@@ -58,2 +58,16 @@ /**
 /**
+ * The response returned by the Prismic Custom Types API bulk transaction
+ * endpoint when a soft or hard limit is reached.
+ */
+type BulkTransactionErrorAPIResponse = {
+	details: {
+		customTypes: {
+			id: string;
+			numberOfDocuments: number;
+			url: string;
+		}[];
+	};
+};
+
+/**
  * Represents an error when making an unauthorized Prismic Custom Types API
@@ -85,2 +99,14 @@ * request.
 /**
+ * Represents an error when a bulk transaction requires confirmation to delete
+ * documents.
+ */
+export class BulkTransactionConfirmationError extends PrismicError<BulkTransactionErrorAPIResponse> {}
+
+/**
+ * Represents an error when a bulk transaction reached the limit of operations
+ * allowed by the API.
+ */
+export class BulkTransactionLimitError extends PrismicError<BulkTransactionErrorAPIResponse> {}
+
+/**
  * Represents an error when a valid `fetch` function is not available to the
@@ -87,0 +113,0 @@ * Prismic Custom Types API client.

src/index.ts

@@ -8,2 +8,9 @@ export { createClient, CustomTypesClient } from "./client";
 export {
+	createBulkTransaction,
+	BulkTransaction,
+	BulkOperationType,
+} from "./bulk";
+export type { BulkOperation, BulkTransactionModels } from "./bulk";
+
+export {
 	PrismicError,
@@ -16,4 +23,6 @@ ConflictError,
 	NotFoundError,
+	BulkTransactionLimitError,
+	BulkTransactionConfirmationError,
 } from "./errors";
 
 export type { FetchLike, ResponseLike, RequestInitLike } from "./types";

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

177912

increased by51.22%

Number of package files

29

increased by26.09%

Lines of code

2516

increased by81.53%

Dependency changes

• + Added@prismicio/client@^7.3.1

• + Added@prismicio/client@7.12.0(transitive)

• + Addedimgix-url-builder@0.0.5(transitive)

• - Removed@prismicio/types@^0.2.4

• - Removed@prismicio/types@0.2.9(transitive)