@adobe/aio-commerce-lib-core/dist/es/error/index.d.ts

Core utilities for AIO Commerce SDK Libraries

/**
 * @license
 * 
 * Copyright 2025 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 { GenericIssue } from "valibot";

//#region source/error/base-error.d.ts
/** Defines the base options for {@link CommerceSdkErrorBase}. */
type CommerceSdkErrorBaseOptions = ErrorOptions & {
  traceId?: string;
};
/**
 * Helper type to define custom error options.
 * @example
 * ```ts
 * type ValidationErrorOptions = CommerceSdkErrorOptions<{
 *   field: string;
 *   value: unknown;
 * }>;
 * ```
 */
type CommerceSdkErrorOptions<T extends Record<string, unknown> = Record<string, unknown>> = CommerceSdkErrorBaseOptions & T;
/**
 * Base class for all the errors in the AIO Commerce SDK.
 * @example
 * ```ts
 * class ValidationError extends CommerceSdkErrorBase {
 *   constructor(message: string, options: ValidationErrorOptions) {
 *     super(message, options);
 *   }
 * }
 *
 * const err = new ValidationError("Invalid value", {
 *   tag: "ValidationError",
 *   field: "name",
 *   value: "John Doe",
 * });
 *
 * console.log(err.toJSON());
 * ```
 */
declare abstract class CommerceSdkErrorBase extends Error {
  readonly traceId?: string;
  /**
   * Constructs a new CommerceSdkErrorBase instance. This is an abstract class so you
   * should not instantiate it directly. Only invoke this constructor from a subclass.
   *
   * @param message - A human-friendly description of the error.
   * @param options - Optional error options (additional information).
   */
  constructor(message: string, options?: CommerceSdkErrorBaseOptions);
  /**
   * Checks if the error is any CommerceSdkErrorBase instance.
   * @example
   * ```ts
   * class ValidationError extends CommerceSdkErrorBase {}
   * const err = new ValidationError("Invalid", {});
   *
   * CommerceSdkErrorBase.isSdkError(err); // true
   * ValidationError.isSdkError(err); // true
   * CommerceSdkErrorBase.isSdkError(new Error("Regular")); // false
   * ```
   */
  static isSdkError(error: unknown): error is CommerceSdkErrorBase;
  /** Returns the full stack trace of the error and its causes. */
  get fullStack(): string;
  /** Returns the root cause of the error. */
  get rootCause(): unknown;
  /** Converts the error to a JSON-like representation. */
  toJSON(): {
    name: string;
    message: string;
    stack: string;
    cause: unknown;
    traceId: string | undefined;
  };
  /**
   * Returns a pretty string representation of the error.
   * @param inspect - Whether to inspect the error (returns a more detailed string, useful for debugging).
   */
  toString(inspect?: boolean): string;
}
//#endregion
//#region source/error/validation-error.d.ts
/** Defines the base options for {@link CommerceSdkValidationError}. */
type CommerceSdkValidationErrorOptions = CommerceSdkErrorOptions<{
  issues: GenericIssue[];
}>;
/**
 * Represents a validation error in the Commerce SDK.
 * This error should be thrown when an input does not conform to the expected schema.
 * It contains a list of issues that describe the validation errors.
 *
 * @example
 * ```ts
 * const error = new CommerceSdkValidationError("Invalid input", {
 *   // `someIssues` is in scope, returned by some `valibot` operation.
 *   issues: someIssues
 * });
 *
 * console.log(error.display());
 * ```
 */
declare class CommerceSdkValidationError extends CommerceSdkErrorBase {
  readonly issues: GenericIssue[];
  /**
   * Constructs a new {@link CommerceSdkValidationError} instance.
   *
   * @param message - A human-friendly description of the validation error.
   * @param options - Options for the validation error, including the issues that caused the error.
   */
  constructor(message: string, {
    issues,
    ...options
  }: CommerceSdkValidationErrorOptions);
  /**
   * Returns a pretty string (and colored) representation of the validation error.
   * @param withColor Whether to use color in the output.
   */
  display(withColor?: boolean): string;
}
//#endregion
export { CommerceSdkErrorBase, CommerceSdkValidationError };