/**
 * @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";
import { HTTP_OK } from "@adobe/aio-commerce-lib-api/utils";
//#region source/responses/helpers.d.ts
/**
 * Determines whether a webhook action's result represents a successful outcome.
 * Adobe Commerce webhooks always respond with HTTP 200, even when the handler
 * wants to block the triggering process, so the actual outcome is only visible
 * in the response body's `op` field (`op: "exception"` signals a failure).
 *
 * @param result - The result of the instrumented webhook action.
 * @returns True if the webhook response is successful, false otherwise.
 *
 * @example
 * ```typescript
 * import { isWebhookSuccessful } from "@adobe/aio-commerce-lib-webhooks/responses";
 *
 * const result = await runWebhookAction(params);
 * span.setStatus(isWebhookSuccessful(result) ? { code: SpanStatusCode.OK } : { code: SpanStatusCode.ERROR });
 * ```
 */
declare function isWebhookSuccessful(result: unknown): boolean;
//#endregion
//#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. */
  type?: 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
//#region source/responses/types.d.ts
/**
 * Successful SDK response containing webhook operation response body data.
 */
type WebhookSuccessResponse = Omit<SuccessResponse, "body" | "statusCode"> & {
  body?: WebhookOperationResponse | WebhookOperationResponse[];
  statusCode: typeof HTTP_OK;
};
/**
 * Determines whether a value is a successful SDK response containing webhook operation response body data.
 *
 * @param response - Value to inspect.
 * @returns True when the value matches the webhook success response shape.
 */
declare function isWebhookSuccessResponse(response: unknown): response is WebhookSuccessResponse;
//#endregion
export { type AddOperation, type ExceptionOperation, type RemoveOperation, type ReplaceOperation, type SuccessOperation, type WebhookOperationResponse, type WebhookSuccessResponse, addOperation, exceptionOperation, isWebhookSuccessResponse, isWebhookSuccessful, ok, removeOperation, replaceOperation, successOperation };