@adobe/aio-commerce-lib-webhooks 0.1.0

package/dist/es/api/index.mjs

@@ -0,0 +1,166 @@
+/**
+ * @license
+ *
+ * Copyright 2026 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+import { AdobeCommerceHttpClient, ApiClient } from "@adobe/aio-commerce-lib-api";
+import * as v from "valibot";
+
+//#region source/api/webhooks/schema.ts
+function nonEmptyString(fieldName) {
+	return v.pipe(v.string(`Expected a string for ${fieldName}`), v.nonEmpty(`${fieldName} must not be empty`));
+}
+function optionalString(fieldName) {
+	return v.optional(v.string(`Expected a string for ${fieldName}`));
+}
+/** Schema for a webhook field mapping ({ name, source? }). */
+const WebhookFieldSchema = v.object({
+	name: nonEmptyString("field name"),
+	source: optionalString("field source")
+});
+/** Schema for a conditional webhook rule ({ field, operator, value }). */
+const WebhookRuleSchema = v.object({
+	field: nonEmptyString("rule field"),
+	operator: nonEmptyString("rule operator"),
+	value: v.string("Expected a string for rule value")
+});
+/** Schema for a custom HTTP header ({ name, value }). */
+const WebhookHeaderSchema = v.object({
+	name: nonEmptyString("header name"),
+	value: nonEmptyString("header value")
+});
+/** Schema for Developer Console OAuth credentials. */
+const DeveloperConsoleOAuthSchema = v.object({
+	client_id: nonEmptyString("client_id"),
+	client_secret: nonEmptyString("client_secret"),
+	org_id: nonEmptyString("org_id"),
+	environment: optionalString("environment")
+});
+/**
+* Schema for the webhook payload sent to POST /webhooks/subscribe.
+* Matches the `webhook` property of the request body.
+* Required fields per the Commerce API: webhook_method, webhook_type, batch_name, hook_name, url.
+*/
+const WebhookSubscribeParamsSchema = v.object({
+	webhook_method: nonEmptyString("webhook_method"),
+	webhook_type: nonEmptyString("webhook_type"),
+	batch_name: nonEmptyString("batch_name"),
+	batch_order: v.optional(v.number()),
+	hook_name: nonEmptyString("hook_name"),
+	url: nonEmptyString("url"),
+	priority: v.optional(v.number()),
+	required: v.optional(v.boolean()),
+	soft_timeout: v.optional(v.number()),
+	timeout: v.optional(v.number()),
+	method: optionalString("method"),
+	fallback_error_message: optionalString("fallback_error_message"),
+	ttl: v.optional(v.number()),
+	fields: v.optional(v.array(WebhookFieldSchema, "Expected an array of field objects")),
+	rules: v.optional(v.array(WebhookRuleSchema, "Expected an array of rule objects")),
+	headers: v.optional(v.array(WebhookHeaderSchema, "Expected an array of header objects")),
+	developer_console_oauth: v.optional(DeveloperConsoleOAuthSchema)
+});
+/**
+* Schema for the parameters sent to POST /webhooks/unsubscribe.
+* Required: webhook_method, webhook_type, batch_name, hook_name.
+*/
+const WebhookUnsubscribeParamsSchema = v.object({
+	webhook_method: nonEmptyString("webhook_method"),
+	webhook_type: nonEmptyString("webhook_type"),
+	batch_name: nonEmptyString("batch_name"),
+	hook_name: nonEmptyString("hook_name")
+});
+
+//#endregion
+//#region source/api/webhooks/endpoints.ts
+/**
+* Returns a list of all subscribed webhooks in the Commerce instance.
+* @see https://developer.adobe.com/commerce/extensibility/webhooks/api/#get-a-list-of-all-subscribed-webhooks
+*
+* @param httpClient - The {@link AdobeCommerceHttpClient} to use to make the request.
+* @param fetchOptions - The {@link Options} to use to make the request.
+*/
+function getWebhookList(httpClient, fetchOptions) {
+	return httpClient.get("webhooks/list", fetchOptions).json();
+}
+/**
+* Subscribes a webhook in the Commerce instance.
+* @see https://developer.adobe.com/commerce/extensibility/webhooks/api/#subscribe-a-webhook
+*
+* @param httpClient - The {@link AdobeCommerceHttpClient} to use to make the request.
+* @param params - The webhook payload (webhook_method, webhook_type, batch_name, hook_name, url, etc.).
+* @param fetchOptions - The {@link Options} to use to make the request.
+*
+* @throws A {@link CommerceSdkValidationError} If the parameters are in the wrong format.
+* @throws An {@link HTTPError} If the status code is not 2XX.
+*/
+function subscribeWebhook(httpClient, params, fetchOptions) {
+	const validatedParams = v.parse(WebhookSubscribeParamsSchema, params);
+	return httpClient.post("webhooks/subscribe", {
+		...fetchOptions,
+		json: { webhook: validatedParams }
+	}).json();
+}
+/**
+* Unsubscribes a webhook from the Commerce instance.
+* @see https://developer.adobe.com/commerce/extensibility/webhooks/api/#unsubscribe-a-webhook
+*
+* @param httpClient - The {@link AdobeCommerceHttpClient} to use to make the request.
+* @param params - The webhook identifiers (webhook_method, webhook_type, batch_name, hook_name).
+* @param fetchOptions - The {@link Options} to use to make the request.
+*
+* @throws A {@link CommerceSdkValidationError} If the parameters are in the wrong format.
+* @throws An {@link HTTPError} If the status code is not 2XX.
+*/
+function unsubscribeWebhook(httpClient, params, fetchOptions) {
+	const validatedParams = v.parse(WebhookUnsubscribeParamsSchema, params);
+	return httpClient.post("webhooks/unsubscribe", {
+		...fetchOptions,
+		json: { webhook: validatedParams }
+	}).json();
+}
+/**
+* Returns the list of webhooks supported in Adobe Commerce as a Cloud Service (SaaS only).
+* @see https://developer.adobe.com/commerce/extensibility/webhooks/api/#get-supported-webhooks-for-saas
+*
+* @param httpClient - The {@link AdobeCommerceHttpClient} to use to make the request.
+* @param fetchOptions - The {@link Options} to use to make the request.
+*/
+function getSupportedWebhookList(httpClient, fetchOptions) {
+	return httpClient.get("webhooks/supportedList", fetchOptions).json();
+}
+
+//#endregion
+//#region source/lib/api-client.ts
+/**
+* Creates a new API client for the Commerce Webhooks API.
+* @param params - The parameters to build the Commerce HTTP client.
+*/
+function createCommerceWebhooksApiClient(params) {
+	return ApiClient.create(new AdobeCommerceHttpClient(params), {
+		getWebhookList,
+		subscribeWebhook,
+		unsubscribeWebhook,
+		getSupportedWebhookList
+	});
+}
+/**
+* Creates a customized Commerce Webhooks API client with a user-specified set of endpoint functions.
+* @param params - The parameters to build the Commerce HTTP client.
+* @param functions - The API functions to include in the client.
+*/
+function createCustomCommerceWebhooksApiClient(params, functions) {
+	return ApiClient.create(new AdobeCommerceHttpClient(params), functions);
+}
+
+//#endregion
+export { createCommerceWebhooksApiClient, createCustomCommerceWebhooksApiClient, getSupportedWebhookList, getWebhookList, subscribeWebhook, unsubscribeWebhook };

package/dist/es/responses/index.d.mts

@@ -0,0 +1,175 @@
+/**
+ * @license
+ *
+ * Copyright 2026 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+import { SuccessResponse } from "@adobe/aio-commerce-lib-core/responses";
+
+//#region source/responses/operations/types.d.ts
+/**
+ * Success operation response
+ * The process that triggered the original event continues without any changes.
+ */
+type SuccessOperation = {
+  op: "success";
+};
+/**
+ * Exception operation response
+ * Causes Commerce to terminate the process that triggered the original event.
+ */
+type ExceptionOperation = {
+  op: "exception"; /** Specifies the exception class. If not set, \Magento\Framework\Exception\LocalizedException will be thrown. */
+  class?: string; /** Specifies the exception message. If not set, fallbackErrorMessage or system default will be used. */
+  message?: string;
+};
+/**
+ * Add operation response
+ * Causes Commerce to add the provided value to the provided path in the triggered event arguments.
+ * @template TValue - The type of the value to be added (defaults to unknown)
+ */
+type AddOperation<TValue = unknown> = {
+  op: "add"; /** Specifies the path at which the value should be added to the triggered event arguments. */
+  path: string; /** Specifies the value to be added. This can be a single value or in an array format. */
+  value: TValue; /** Specifies the DataObject class name to create, based on the value and added to the provided path. */
+  instance?: string;
+};
+/**
+ * Replace operation response
+ * Causes Commerce to replace a value in triggered event arguments for the provided path.
+ * @template TValue - The type of the replacement value (defaults to unknown)
+ */
+type ReplaceOperation<TValue = unknown> = {
+  op: "replace"; /** Specifies the path at which the value should be replaced with the provided value. */
+  path: string; /** Specifies the replacement value. This can be a single value or in an array format. */
+  value: TValue; /** Specifies the DataObject class name to create, based on the value and added to the provided path. */
+  instance?: string;
+};
+/**
+ * Remove operation response
+ * Causes Commerce to remove a value or node in triggered event arguments by the provided path.
+ */
+type RemoveOperation = {
+  op: "remove"; /** Specifies the path at which the value should be removed. */
+  path: string;
+};
+/**
+ * Union type representing any webhook operation response
+ *
+ * @template TValue - The type of the value for operations that carry a value (defaults to unknown)
+ */
+type WebhookOperationResponse<TValue = unknown> = SuccessOperation | ExceptionOperation | AddOperation<TValue> | ReplaceOperation<TValue> | RemoveOperation;
+//#endregion
+//#region source/responses/operations/presets.d.ts
+/**
+ * Creates a success operation response
+ * The process that triggered the original event continues without any changes.
+ *
+ * @example
+ * ```typescript
+ * return successOperation();
+ * ```
+ */
+declare const successOperation: () => SuccessOperation;
+/**
+ * Creates an exception operation response with a message
+ * Causes Commerce to terminate the process that triggered the original event.
+ *
+ * @param message - Exception message
+ * @param exceptionClass - Optional exception class name
+ *
+ * @example
+ * ```typescript
+ * return exceptionOperation("The product cannot be added to the cart because it is out of stock");
+ *
+ * return exceptionOperation(
+ *   "Custom error occurred",
+ *   "Path\\To\\Exception\\Class"
+ * );
+ * ```
+ */
+declare const exceptionOperation: (message: string, exceptionClass?: string) => ExceptionOperation;
+/**
+ * Creates an add operation response
+ * Causes Commerce to add the provided value to the provided path in the triggered event arguments.
+ *
+ * @template TValue - The type of the value to be added
+ * @param path - Path at which the value should be added
+ * @param value - Value to be added
+ * @param instance - Optional DataObject class name
+ *
+ * @example
+ * ```typescript
+ * return addOperation(
+ *   "result",
+ *   { data: { amount: "5", carrier_code: "newshipmethod" } },
+ *   "Magento\\Quote\\Api\\Data\\ShippingMethodInterface"
+ * );
+ * ```
+ */
+declare const addOperation: <TValue = unknown>(path: string, value: TValue, instance?: string) => AddOperation<TValue>;
+/**
+ * Creates a replace operation response
+ * Causes Commerce to replace a value in triggered event arguments for the provided path.
+ *
+ * @template TValue - The type of the replacement value
+ * @param path - Path at which the value should be replaced
+ * @param value - Replacement value
+ * @param instance - Optional DataObject class name
+ *
+ * @example
+ * ```typescript
+ * return replaceOperation("result/shipping_methods/shipping_method_one/amount", 6);
+ * ```
+ */
+declare const replaceOperation: <TValue = unknown>(path: string, value: TValue, instance?: string) => ReplaceOperation<TValue>;
+/**
+ * Creates a remove operation response
+ * Causes Commerce to remove a value or node in triggered event arguments by the provided path.
+ *
+ * @param path - Path at which the value should be removed
+ *
+ * @example
+ * ```typescript
+ * return removeOperation("result/key2");
+ * ```
+ */
+declare const removeOperation: (path: string) => RemoveOperation;
+//#endregion
+//#region source/responses/presets.d.ts
+/**
+ * Creates an HTTP 200 OK response with webhook operation(s)
+ * Webhook-optimized version of ok() that automatically wraps operations in the response body.
+ *
+ * This function shadows the core library's ok() to provide a cleaner API for webhook actions.
+ * Instead of `ok({ body: operation })`, you can simply use `ok(operation)`.
+ *
+ * @template TValue - The type of the value for add/replace operations (defaults to unknown)
+ * @param operations - Single webhook operation or array of operations
+ * @returns Success response with operations in body
+ *
+ * @example
+ * ```typescript
+ * import { ok, successOperation } from "@adobe/aio-commerce-lib-webhooks/responses";
+ *
+ * // Single operation
+ * return ok(successOperation());
+ *
+ * // Array of operations
+ * return ok([
+ *   addOperation("result", data),
+ *   removeOperation("result/old_field")
+ * ]);
+ * ```
+ */
+declare function ok<TValue = unknown>(operations: WebhookOperationResponse<TValue> | WebhookOperationResponse[]): SuccessResponse;
+//#endregion
+export { type AddOperation, type ExceptionOperation, type RemoveOperation, type ReplaceOperation, type SuccessOperation, type WebhookOperationResponse, addOperation, exceptionOperation, ok, removeOperation, replaceOperation, successOperation };

package/dist/es/responses/index.mjs

@@ -0,0 +1,144 @@
+/**
+ * @license
+ *
+ * Copyright 2026 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+import { ok as ok$1 } from "@adobe/aio-commerce-lib-core/responses";
+
+//#region source/responses/operations/presets.ts
+/**
+* Creates a success operation response
+* The process that triggered the original event continues without any changes.
+*
+* @example
+* ```typescript
+* return successOperation();
+* ```
+*/
+const successOperation = () => ({ op: "success" });
+/**
+* Creates an exception operation response with a message
+* Causes Commerce to terminate the process that triggered the original event.
+*
+* @param message - Exception message
+* @param exceptionClass - Optional exception class name
+*
+* @example
+* ```typescript
+* return exceptionOperation("The product cannot be added to the cart because it is out of stock");
+*
+* return exceptionOperation(
+*   "Custom error occurred",
+*   "Path\\To\\Exception\\Class"
+* );
+* ```
+*/
+const exceptionOperation = (message, exceptionClass) => {
+	return {
+		op: "exception",
+		...message && { message },
+		...exceptionClass && { class: exceptionClass }
+	};
+};
+/**
+* Creates an add operation response
+* Causes Commerce to add the provided value to the provided path in the triggered event arguments.
+*
+* @template TValue - The type of the value to be added
+* @param path - Path at which the value should be added
+* @param value - Value to be added
+* @param instance - Optional DataObject class name
+*
+* @example
+* ```typescript
+* return addOperation(
+*   "result",
+*   { data: { amount: "5", carrier_code: "newshipmethod" } },
+*   "Magento\\Quote\\Api\\Data\\ShippingMethodInterface"
+* );
+* ```
+*/
+const addOperation = (path, value, instance) => ({
+	op: "add",
+	path,
+	value,
+	...instance && { instance }
+});
+/**
+* Creates a replace operation response
+* Causes Commerce to replace a value in triggered event arguments for the provided path.
+*
+* @template TValue - The type of the replacement value
+* @param path - Path at which the value should be replaced
+* @param value - Replacement value
+* @param instance - Optional DataObject class name
+*
+* @example
+* ```typescript
+* return replaceOperation("result/shipping_methods/shipping_method_one/amount", 6);
+* ```
+*/
+const replaceOperation = (path, value, instance) => ({
+	op: "replace",
+	path,
+	value,
+	...instance && { instance }
+});
+/**
+* Creates a remove operation response
+* Causes Commerce to remove a value or node in triggered event arguments by the provided path.
+*
+* @param path - Path at which the value should be removed
+*
+* @example
+* ```typescript
+* return removeOperation("result/key2");
+* ```
+*/
+const removeOperation = (path) => ({
+	op: "remove",
+	path
+});
+
+//#endregion
+//#region source/responses/presets.ts
+/**
+* Creates an HTTP 200 OK response with webhook operation(s)
+* Webhook-optimized version of ok() that automatically wraps operations in the response body.
+*
+* This function shadows the core library's ok() to provide a cleaner API for webhook actions.
+* Instead of `ok({ body: operation })`, you can simply use `ok(operation)`.
+*
+* @template TValue - The type of the value for add/replace operations (defaults to unknown)
+* @param operations - Single webhook operation or array of operations
+* @returns Success response with operations in body
+*
+* @example
+* ```typescript
+* import { ok, successOperation } from "@adobe/aio-commerce-lib-webhooks/responses";
+*
+* // Single operation
+* return ok(successOperation());
+*
+* // Array of operations
+* return ok([
+*   addOperation("result", data),
+*   removeOperation("result/old_field")
+* ]);
+* ```
+*/
+function ok(operations) {
+	return ok$1({ body: operations });
+}
+
+//#endregion
+export { addOperation, exceptionOperation, ok, removeOperation, replaceOperation, successOperation };

package/package.json

@@ -0,0 +1,95 @@
+{
+  "name": "@adobe/aio-commerce-lib-webhooks",
+  "type": "module",
+  "author": "Adobe Inc.",
+  "version": "0.1.0",
+  "private": false,
+  "engines": {
+    "node": ">=20 <=24"
+  },
+  "license": "Apache-2.0",
+  "description": "A library to interact with the Adobe Commerce Webhooks API",
+  "keywords": [
+    "aio",
+    "commerce",
+    "adobe-commerce",
+    "adobe-commerce-webhooks",
+    "aio-commerce-sdk"
+  ],
+  "bugs": {
+    "url": "https://github.com/adobe/aio-commerce-sdk/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/adobe/aio-commerce-sdk.git",
+    "directory": "packages/aio-commerce-lib-webhooks"
+  },
+  "exports": {
+    "./api": {
+      "import": {
+        "types": "./dist/es/api/index.d.mts",
+        "default": "./dist/es/api/index.mjs"
+      },
+      "require": {
+        "types": "./dist/cjs/api/index.d.cts",
+        "default": "./dist/cjs/api/index.cjs"
+      }
+    },
+    "./responses": {
+      "import": {
+        "types": "./dist/es/responses/index.d.mts",
+        "default": "./dist/es/responses/index.mjs"
+      },
+      "require": {
+        "types": "./dist/cjs/responses/index.d.cts",
+        "default": "./dist/cjs/responses/index.cjs"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "imports": {
+    "#*": "./source/*.ts",
+    "#test/*": "./test/*.ts"
+  },
+  "files": [
+    "dist",
+    "package.json",
+    "CHANGELOG.md",
+    "README.md"
+  ],
+  "dependencies": {
+    "ky": "^1.9.0",
+    "valibot": "^1.1.0",
+    "@adobe/aio-commerce-lib-api": "1.0.1",
+    "@adobe/aio-commerce-lib-core": "1.0.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.3",
+    "msw": "^2.11.1",
+    "@aio-commerce-sdk/config-tsdown": "1.0.1",
+    "@aio-commerce-sdk/config-typescript": "1.0.0",
+    "@aio-commerce-sdk/config-vitest": "1.0.0",
+    "@aio-commerce-sdk/scripting-utils": "0.3.0",
+    "@aio-commerce-sdk/scripts": "0.1.0"
+  },
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsdown",
+    "pack": "pnpm pack",
+    "publint": "publint",
+    "docs": "typedoc && prettier --write '**/*.md'",
+    "assist": "biome check --formatter-enabled=false --linter-enabled=false --assist-enabled=true --no-errors-on-unmatched",
+    "assist:apply": "biome check --write --formatter-enabled=false --linter-enabled=false --assist-enabled=true --no-errors-on-unmatched",
+    "check:ci": "biome ci --formatter-enabled=true --linter-enabled=true --assist-enabled=true --no-errors-on-unmatched",
+    "code:fix": "pnpm run lint:fix && pnpm run assist:apply && pnpm run format && pnpm run format:markdown",
+    "format": "biome format --write --no-errors-on-unmatched",
+    "format:markdown": "prettier --no-error-on-unmatched-pattern --write '**/*.md' \"!**/{CODE_OF_CONDUCT.md,COPYRIGHT,LICENSE,SECURITY.md,CONTRIBUTING.md}\"",
+    "format:check": "biome format --no-errors-on-unmatched",
+    "lint": "biome lint --no-errors-on-unmatched",
+    "lint:fix": "biome lint --write --no-errors-on-unmatched",
+    "typecheck": "tsc --noEmit && echo '✅ No type errors found.'",
+    "test": "vitest run --coverage",
+    "test:ui": "vitest --ui --coverage",
+    "test:watch": "vitest --watch --coverage"
+  }
+}