@perkos/util-errors 1.0.0

package/README.md

@@ -0,0 +1,93 @@
+# @perkos/util-errors
+
+Error handling utilities and classes for vendor services with Zod integration.
+
+## Installation
+
+```bash
+npm install @perkos/util-errors
+```
+
+## Usage
+
+```typescript
+import {
+  AppError,
+  ValidationError,
+  PaymentError,
+  formatErrorResponse,
+  getErrorStatusCode,
+} from "@perkos/util-errors";
+import { z } from "zod";
+
+// Throw application errors with context
+throw new AppError("Something went wrong", 500, true, { userId: "123" });
+
+// Throw validation errors
+throw new ValidationError("Invalid input", [{ field: "email", message: "Required" }]);
+
+// Create from Zod errors
+try {
+  schema.parse(data);
+} catch (error) {
+  if (error instanceof z.ZodError) {
+    throw ValidationError.fromZodError(error);
+  }
+}
+
+// Payment errors for x402
+throw new PaymentError("Payment failed", "Insufficient funds");
+
+// Format errors for API response
+const response = formatErrorResponse(error);
+const statusCode = getErrorStatusCode(error);
+```
+
+## Error Classes
+
+### `AppError`
+Base error class with HTTP status code and context.
+
+```typescript
+new AppError(message, statusCode?, isOperational?, context?)
+```
+
+### `ValidationError`
+For request validation failures with Zod integration.
+
+```typescript
+new ValidationError(message?, details?)
+ValidationError.fromZodError(zodError)
+```
+
+### `PaymentError`
+For x402 payment-related failures.
+
+```typescript
+new PaymentError(message, reason?, transactionHash?, context?)
+```
+
+### Other Errors
+- `NotFoundError` (404)
+- `UnauthorizedError` (401)
+- `ForbiddenError` (403)
+- `RateLimitError` (429)
+- `ServiceUnavailableError` (503)
+
+## Utilities
+
+### `formatErrorResponse(error)`
+Format any error for API response.
+
+### `getErrorStatusCode(error)`
+Get HTTP status code from any error.
+
+### `isOperationalError(error)`
+Check if error is operational (expected) vs programming error.
+
+### `createErrorHandler(options?)`
+Create error handler middleware.
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,126 @@
+import { ZodError } from 'zod';
+
+/**
+ * @perkos/error-handling
+ * Error handling utilities and classes for vendor services
+ */
+
+/**
+ * Base application error class
+ * Extends Error with HTTP status code and context
+ */
+declare class AppError extends Error {
+    readonly statusCode: number;
+    readonly isOperational: boolean;
+    readonly context?: Record<string, any>;
+    constructor(message: string, statusCode?: number, isOperational?: boolean, context?: Record<string, any>);
+    toJSON(): {
+        error: string;
+        statusCode: number;
+        context: Record<string, any> | undefined;
+    };
+}
+/**
+ * Validation error class
+ * For request validation failures with Zod integration
+ */
+declare class ValidationError extends AppError {
+    readonly details?: any;
+    constructor(message?: string, details?: any);
+    /**
+     * Create ValidationError from ZodError
+     */
+    static fromZodError(error: ZodError): ValidationError;
+    toJSON(): {
+        error: string;
+        details: any;
+        statusCode: number;
+        context: Record<string, any> | undefined;
+    };
+}
+/**
+ * Payment error class
+ * For x402 payment-related failures
+ */
+declare class PaymentError extends AppError {
+    readonly reason?: string;
+    readonly transactionHash?: string;
+    constructor(message: string, reason?: string, transactionHash?: string, context?: Record<string, any>);
+    toJSON(): {
+        error: string;
+        reason: string | undefined;
+        transactionHash: string | undefined;
+        statusCode: number;
+        context: Record<string, any> | undefined;
+    };
+}
+/**
+ * Not found error class
+ */
+declare class NotFoundError extends AppError {
+    constructor(message?: string, context?: Record<string, any>);
+}
+/**
+ * Unauthorized error class
+ */
+declare class UnauthorizedError extends AppError {
+    constructor(message?: string, context?: Record<string, any>);
+}
+/**
+ * Forbidden error class
+ */
+declare class ForbiddenError extends AppError {
+    constructor(message?: string, context?: Record<string, any>);
+}
+/**
+ * Rate limit error class
+ */
+declare class RateLimitError extends AppError {
+    readonly retryAfter?: number;
+    constructor(message?: string, retryAfter?: number, context?: Record<string, any>);
+    toJSON(): {
+        error: string;
+        retryAfter: number | undefined;
+        statusCode: number;
+        context: Record<string, any> | undefined;
+    };
+}
+/**
+ * Service unavailable error class
+ */
+declare class ServiceUnavailableError extends AppError {
+    constructor(message?: string, context?: Record<string, any>);
+}
+/**
+ * Check if error is operational (expected) or programming error
+ */
+declare function isOperationalError(error: Error): boolean;
+/**
+ * Error response formatter for API responses
+ */
+interface ErrorResponse {
+    error: string;
+    message?: string;
+    details?: any;
+    statusCode: number;
+}
+/**
+ * Format error for API response
+ */
+declare function formatErrorResponse(error: unknown): ErrorResponse;
+/**
+ * Get HTTP status code from error
+ */
+declare function getErrorStatusCode(error: unknown): number;
+/**
+ * Create error handler middleware (framework-agnostic)
+ */
+declare function createErrorHandler(options?: {
+    logger?: (error: Error, context?: Record<string, any>) => void;
+    includeStack?: boolean;
+}): (error: unknown) => {
+    response: ErrorResponse;
+    statusCode: number;
+};
+
+export { AppError, type ErrorResponse, ForbiddenError, NotFoundError, PaymentError, RateLimitError, ServiceUnavailableError, UnauthorizedError, ValidationError, createErrorHandler, formatErrorResponse, getErrorStatusCode, isOperationalError };

package/dist/index.d.ts

@@ -0,0 +1,126 @@
+import { ZodError } from 'zod';
+
+/**
+ * @perkos/error-handling
+ * Error handling utilities and classes for vendor services
+ */
+
+/**
+ * Base application error class
+ * Extends Error with HTTP status code and context
+ */
+declare class AppError extends Error {
+    readonly statusCode: number;
+    readonly isOperational: boolean;
+    readonly context?: Record<string, any>;
+    constructor(message: string, statusCode?: number, isOperational?: boolean, context?: Record<string, any>);
+    toJSON(): {
+        error: string;
+        statusCode: number;
+        context: Record<string, any> | undefined;
+    };
+}
+/**
+ * Validation error class
+ * For request validation failures with Zod integration
+ */
+declare class ValidationError extends AppError {
+    readonly details?: any;
+    constructor(message?: string, details?: any);
+    /**
+     * Create ValidationError from ZodError
+     */
+    static fromZodError(error: ZodError): ValidationError;
+    toJSON(): {
+        error: string;
+        details: any;
+        statusCode: number;
+        context: Record<string, any> | undefined;
+    };
+}
+/**
+ * Payment error class
+ * For x402 payment-related failures
+ */
+declare class PaymentError extends AppError {
+    readonly reason?: string;
+    readonly transactionHash?: string;
+    constructor(message: string, reason?: string, transactionHash?: string, context?: Record<string, any>);
+    toJSON(): {
+        error: string;
+        reason: string | undefined;
+        transactionHash: string | undefined;
+        statusCode: number;
+        context: Record<string, any> | undefined;
+    };
+}
+/**
+ * Not found error class
+ */
+declare class NotFoundError extends AppError {
+    constructor(message?: string, context?: Record<string, any>);
+}
+/**
+ * Unauthorized error class
+ */
+declare class UnauthorizedError extends AppError {
+    constructor(message?: string, context?: Record<string, any>);
+}
+/**
+ * Forbidden error class
+ */
+declare class ForbiddenError extends AppError {
+    constructor(message?: string, context?: Record<string, any>);
+}
+/**
+ * Rate limit error class
+ */
+declare class RateLimitError extends AppError {
+    readonly retryAfter?: number;
+    constructor(message?: string, retryAfter?: number, context?: Record<string, any>);
+    toJSON(): {
+        error: string;
+        retryAfter: number | undefined;
+        statusCode: number;
+        context: Record<string, any> | undefined;
+    };
+}
+/**
+ * Service unavailable error class
+ */
+declare class ServiceUnavailableError extends AppError {
+    constructor(message?: string, context?: Record<string, any>);
+}
+/**
+ * Check if error is operational (expected) or programming error
+ */
+declare function isOperationalError(error: Error): boolean;
+/**
+ * Error response formatter for API responses
+ */
+interface ErrorResponse {
+    error: string;
+    message?: string;
+    details?: any;
+    statusCode: number;
+}
+/**
+ * Format error for API response
+ */
+declare function formatErrorResponse(error: unknown): ErrorResponse;
+/**
+ * Get HTTP status code from error
+ */
+declare function getErrorStatusCode(error: unknown): number;
+/**
+ * Create error handler middleware (framework-agnostic)
+ */
+declare function createErrorHandler(options?: {
+    logger?: (error: Error, context?: Record<string, any>) => void;
+    includeStack?: boolean;
+}): (error: unknown) => {
+    response: ErrorResponse;
+    statusCode: number;
+};
+
+export { AppError, type ErrorResponse, ForbiddenError, NotFoundError, PaymentError, RateLimitError, ServiceUnavailableError, UnauthorizedError, ValidationError, createErrorHandler, formatErrorResponse, getErrorStatusCode, isOperationalError };

package/dist/index.js

@@ -0,0 +1,193 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  AppError: () => AppError,
+  ForbiddenError: () => ForbiddenError,
+  NotFoundError: () => NotFoundError,
+  PaymentError: () => PaymentError,
+  RateLimitError: () => RateLimitError,
+  ServiceUnavailableError: () => ServiceUnavailableError,
+  UnauthorizedError: () => UnauthorizedError,
+  ValidationError: () => ValidationError,
+  createErrorHandler: () => createErrorHandler,
+  formatErrorResponse: () => formatErrorResponse,
+  getErrorStatusCode: () => getErrorStatusCode,
+  isOperationalError: () => isOperationalError
+});
+module.exports = __toCommonJS(index_exports);
+var import_zod = require("zod");
+var AppError = class extends Error {
+  constructor(message, statusCode = 500, isOperational = true, context) {
+    super(message);
+    Object.setPrototypeOf(this, new.target.prototype);
+    this.name = this.constructor.name;
+    this.statusCode = statusCode;
+    this.isOperational = isOperational;
+    this.context = context;
+    Error.captureStackTrace(this);
+  }
+  toJSON() {
+    return {
+      error: this.message,
+      statusCode: this.statusCode,
+      context: this.context
+    };
+  }
+};
+var ValidationError = class _ValidationError extends AppError {
+  constructor(message = "Validation failed", details) {
+    super(message, 400, true, { details });
+    this.details = details;
+  }
+  /**
+   * Create ValidationError from ZodError
+   */
+  static fromZodError(error) {
+    const details = error.errors.map((e) => ({
+      path: e.path.join("."),
+      message: e.message,
+      code: e.code
+    }));
+    return new _ValidationError("Validation error", details);
+  }
+  toJSON() {
+    return {
+      error: this.message,
+      details: this.details,
+      statusCode: this.statusCode,
+      context: this.context
+    };
+  }
+};
+var PaymentError = class extends AppError {
+  constructor(message, reason, transactionHash, context) {
+    super(message, 402, true, context);
+    this.reason = reason;
+    this.transactionHash = transactionHash;
+  }
+  toJSON() {
+    return {
+      error: this.message,
+      reason: this.reason,
+      transactionHash: this.transactionHash,
+      statusCode: this.statusCode,
+      context: this.context
+    };
+  }
+};
+var NotFoundError = class extends AppError {
+  constructor(message = "Resource not found", context) {
+    super(message, 404, true, context);
+  }
+};
+var UnauthorizedError = class extends AppError {
+  constructor(message = "Unauthorized", context) {
+    super(message, 401, true, context);
+  }
+};
+var ForbiddenError = class extends AppError {
+  constructor(message = "Forbidden", context) {
+    super(message, 403, true, context);
+  }
+};
+var RateLimitError = class extends AppError {
+  constructor(message = "Rate limit exceeded", retryAfter, context) {
+    super(message, 429, true, context);
+    this.retryAfter = retryAfter;
+  }
+  toJSON() {
+    return {
+      error: this.message,
+      retryAfter: this.retryAfter,
+      statusCode: this.statusCode,
+      context: this.context
+    };
+  }
+};
+var ServiceUnavailableError = class extends AppError {
+  constructor(message = "Service unavailable", context) {
+    super(message, 503, true, context);
+  }
+};
+function isOperationalError(error) {
+  if (error instanceof AppError) {
+    return error.isOperational;
+  }
+  return false;
+}
+function formatErrorResponse(error) {
+  if (error instanceof import_zod.ZodError) {
+    const validationError = ValidationError.fromZodError(error);
+    return validationError.toJSON();
+  }
+  if (error instanceof AppError) {
+    return error.toJSON();
+  }
+  if (error instanceof Error) {
+    return {
+      error: error.message,
+      statusCode: 500
+    };
+  }
+  return {
+    error: "Unknown error",
+    statusCode: 500
+  };
+}
+function getErrorStatusCode(error) {
+  if (error instanceof AppError) {
+    return error.statusCode;
+  }
+  if (error instanceof import_zod.ZodError) {
+    return 400;
+  }
+  return 500;
+}
+function createErrorHandler(options) {
+  return (error) => {
+    const response = formatErrorResponse(error);
+    const statusCode = getErrorStatusCode(error);
+    if (options?.logger && error instanceof Error) {
+      options.logger(error, { statusCode });
+    }
+    if (options?.includeStack && error instanceof Error) {
+      response.stack = error.stack;
+    }
+    return { response, statusCode };
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  AppError,
+  ForbiddenError,
+  NotFoundError,
+  PaymentError,
+  RateLimitError,
+  ServiceUnavailableError,
+  UnauthorizedError,
+  ValidationError,
+  createErrorHandler,
+  formatErrorResponse,
+  getErrorStatusCode,
+  isOperationalError
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["/**\n * @perkos/error-handling\n * Error handling utilities and classes for vendor services\n */\n\nimport { ZodError } from \"zod\";\n\n/**\n * Base application error class\n * Extends Error with HTTP status code and context\n */\nexport class AppError extends Error {\n  public readonly statusCode: number;\n  public readonly isOperational: boolean;\n  public readonly context?: Record<string, any>;\n\n  constructor(\n    message: string,\n    statusCode: number = 500,\n    isOperational: boolean = true,\n    context?: Record<string, any>\n  ) {\n    super(message);\n    Object.setPrototypeOf(this, new.target.prototype);\n\n    this.name = this.constructor.name;\n    this.statusCode = statusCode;\n    this.isOperational = isOperational;\n    this.context = context;\n\n    Error.captureStackTrace(this);\n  }\n\n  toJSON() {\n    return {\n      error: this.message,\n      statusCode: this.statusCode,\n      context: this.context,\n    };\n  }\n}\n\n/**\n * Validation error class\n * For request validation failures with Zod integration\n */\nexport class ValidationError extends AppError {\n  public readonly details?: any;\n\n  constructor(message: string = \"Validation failed\", details?: any) {\n    super(message, 400, true, { details });\n    this.details = details;\n  }\n\n  /**\n   * Create ValidationError from ZodError\n   */\n  static fromZodError(error: ZodError): ValidationError {\n    const details = error.errors.map((e) => ({\n      path: e.path.join(\".\"),\n      message: e.message,\n      code: e.code,\n    }));\n    return new ValidationError(\"Validation error\", details);\n  }\n\n  toJSON() {\n    return {\n      error: this.message,\n      details: this.details,\n      statusCode: this.statusCode,\n      context: this.context,\n    };\n  }\n}\n\n/**\n * Payment error class\n * For x402 payment-related failures\n */\nexport class PaymentError extends AppError {\n  public readonly reason?: string;\n  public readonly transactionHash?: string;\n\n  constructor(\n    message: string,\n    reason?: string,\n    transactionHash?: string,\n    context?: Record<string, any>\n  ) {\n    super(message, 402, true, context);\n    this.reason = reason;\n    this.transactionHash = transactionHash;\n  }\n\n  toJSON() {\n    return {\n      error: this.message,\n      reason: this.reason,\n      transactionHash: this.transactionHash,\n      statusCode: this.statusCode,\n      context: this.context,\n    };\n  }\n}\n\n/**\n * Not found error class\n */\nexport class NotFoundError extends AppError {\n  constructor(message: string = \"Resource not found\", context?: Record<string, any>) {\n    super(message, 404, true, context);\n  }\n}\n\n/**\n * Unauthorized error class\n */\nexport class UnauthorizedError extends AppError {\n  constructor(message: string = \"Unauthorized\", context?: Record<string, any>) {\n    super(message, 401, true, context);\n  }\n}\n\n/**\n * Forbidden error class\n */\nexport class ForbiddenError extends AppError {\n  constructor(message: string = \"Forbidden\", context?: Record<string, any>) {\n    super(message, 403, true, context);\n  }\n}\n\n/**\n * Rate limit error class\n */\nexport class RateLimitError extends AppError {\n  public readonly retryAfter?: number;\n\n  constructor(\n    message: string = \"Rate limit exceeded\",\n    retryAfter?: number,\n    context?: Record<string, any>\n  ) {\n    super(message, 429, true, context);\n    this.retryAfter = retryAfter;\n  }\n\n  toJSON() {\n    return {\n      error: this.message,\n      retryAfter: this.retryAfter,\n      statusCode: this.statusCode,\n      context: this.context,\n    };\n  }\n}\n\n/**\n * Service unavailable error class\n */\nexport class ServiceUnavailableError extends AppError {\n  constructor(message: string = \"Service unavailable\", context?: Record<string, any>) {\n    super(message, 503, true, context);\n  }\n}\n\n/**\n * Check if error is operational (expected) or programming error\n */\nexport function isOperationalError(error: Error): boolean {\n  if (error instanceof AppError) {\n    return error.isOperational;\n  }\n  return false;\n}\n\n/**\n * Error response formatter for API responses\n */\nexport interface ErrorResponse {\n  error: string;\n  message?: string;\n  details?: any;\n  statusCode: number;\n}\n\n/**\n * Format error for API response\n */\nexport function formatErrorResponse(error: unknown): ErrorResponse {\n  if (error instanceof ZodError) {\n    const validationError = ValidationError.fromZodError(error);\n    return validationError.toJSON() as ErrorResponse;\n  }\n\n  if (error instanceof AppError) {\n    return error.toJSON() as ErrorResponse;\n  }\n\n  if (error instanceof Error) {\n    return {\n      error: error.message,\n      statusCode: 500,\n    };\n  }\n\n  return {\n    error: \"Unknown error\",\n    statusCode: 500,\n  };\n}\n\n/**\n * Get HTTP status code from error\n */\nexport function getErrorStatusCode(error: unknown): number {\n  if (error instanceof AppError) {\n    return error.statusCode;\n  }\n  if (error instanceof ZodError) {\n    return 400;\n  }\n  return 500;\n}\n\n/**\n * Create error handler middleware (framework-agnostic)\n */\nexport function createErrorHandler(options?: {\n  logger?: (error: Error, context?: Record<string, any>) => void;\n  includeStack?: boolean;\n}) {\n  return (error: unknown) => {\n    const response = formatErrorResponse(error);\n    const statusCode = getErrorStatusCode(error);\n\n    if (options?.logger && error instanceof Error) {\n      options.logger(error, { statusCode });\n    }\n\n    if (options?.includeStack && error instanceof Error) {\n      (response as any).stack = error.stack;\n    }\n\n    return { response, statusCode };\n  };\n}\n"],"mappings":"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","names":[]}

package/dist/index.mjs

@@ -0,0 +1,157 @@
+// src/index.ts
+import { ZodError } from "zod";
+var AppError = class extends Error {
+  constructor(message, statusCode = 500, isOperational = true, context) {
+    super(message);
+    Object.setPrototypeOf(this, new.target.prototype);
+    this.name = this.constructor.name;
+    this.statusCode = statusCode;
+    this.isOperational = isOperational;
+    this.context = context;
+    Error.captureStackTrace(this);
+  }
+  toJSON() {
+    return {
+      error: this.message,
+      statusCode: this.statusCode,
+      context: this.context
+    };
+  }
+};
+var ValidationError = class _ValidationError extends AppError {
+  constructor(message = "Validation failed", details) {
+    super(message, 400, true, { details });
+    this.details = details;
+  }
+  /**
+   * Create ValidationError from ZodError
+   */
+  static fromZodError(error) {
+    const details = error.errors.map((e) => ({
+      path: e.path.join("."),
+      message: e.message,
+      code: e.code
+    }));
+    return new _ValidationError("Validation error", details);
+  }
+  toJSON() {
+    return {
+      error: this.message,
+      details: this.details,
+      statusCode: this.statusCode,
+      context: this.context
+    };
+  }
+};
+var PaymentError = class extends AppError {
+  constructor(message, reason, transactionHash, context) {
+    super(message, 402, true, context);
+    this.reason = reason;
+    this.transactionHash = transactionHash;
+  }
+  toJSON() {
+    return {
+      error: this.message,
+      reason: this.reason,
+      transactionHash: this.transactionHash,
+      statusCode: this.statusCode,
+      context: this.context
+    };
+  }
+};
+var NotFoundError = class extends AppError {
+  constructor(message = "Resource not found", context) {
+    super(message, 404, true, context);
+  }
+};
+var UnauthorizedError = class extends AppError {
+  constructor(message = "Unauthorized", context) {
+    super(message, 401, true, context);
+  }
+};
+var ForbiddenError = class extends AppError {
+  constructor(message = "Forbidden", context) {
+    super(message, 403, true, context);
+  }
+};
+var RateLimitError = class extends AppError {
+  constructor(message = "Rate limit exceeded", retryAfter, context) {
+    super(message, 429, true, context);
+    this.retryAfter = retryAfter;
+  }
+  toJSON() {
+    return {
+      error: this.message,
+      retryAfter: this.retryAfter,
+      statusCode: this.statusCode,
+      context: this.context
+    };
+  }
+};
+var ServiceUnavailableError = class extends AppError {
+  constructor(message = "Service unavailable", context) {
+    super(message, 503, true, context);
+  }
+};
+function isOperationalError(error) {
+  if (error instanceof AppError) {
+    return error.isOperational;
+  }
+  return false;
+}
+function formatErrorResponse(error) {
+  if (error instanceof ZodError) {
+    const validationError = ValidationError.fromZodError(error);
+    return validationError.toJSON();
+  }
+  if (error instanceof AppError) {
+    return error.toJSON();
+  }
+  if (error instanceof Error) {
+    return {
+      error: error.message,
+      statusCode: 500
+    };
+  }
+  return {
+    error: "Unknown error",
+    statusCode: 500
+  };
+}
+function getErrorStatusCode(error) {
+  if (error instanceof AppError) {
+    return error.statusCode;
+  }
+  if (error instanceof ZodError) {
+    return 400;
+  }
+  return 500;
+}
+function createErrorHandler(options) {
+  return (error) => {
+    const response = formatErrorResponse(error);
+    const statusCode = getErrorStatusCode(error);
+    if (options?.logger && error instanceof Error) {
+      options.logger(error, { statusCode });
+    }
+    if (options?.includeStack && error instanceof Error) {
+      response.stack = error.stack;
+    }
+    return { response, statusCode };
+  };
+}
+export {
+  AppError,
+  ForbiddenError,
+  NotFoundError,
+  PaymentError,
+  RateLimitError,
+  ServiceUnavailableError,
+  UnauthorizedError,
+  ValidationError,
+  createErrorHandler,
+  formatErrorResponse,
+  getErrorStatusCode,
+  isOperationalError
+};
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["/**\n * @perkos/error-handling\n * Error handling utilities and classes for vendor services\n */\n\nimport { ZodError } from \"zod\";\n\n/**\n * Base application error class\n * Extends Error with HTTP status code and context\n */\nexport class AppError extends Error {\n  public readonly statusCode: number;\n  public readonly isOperational: boolean;\n  public readonly context?: Record<string, any>;\n\n  constructor(\n    message: string,\n    statusCode: number = 500,\n    isOperational: boolean = true,\n    context?: Record<string, any>\n  ) {\n    super(message);\n    Object.setPrototypeOf(this, new.target.prototype);\n\n    this.name = this.constructor.name;\n    this.statusCode = statusCode;\n    this.isOperational = isOperational;\n    this.context = context;\n\n    Error.captureStackTrace(this);\n  }\n\n  toJSON() {\n    return {\n      error: this.message,\n      statusCode: this.statusCode,\n      context: this.context,\n    };\n  }\n}\n\n/**\n * Validation error class\n * For request validation failures with Zod integration\n */\nexport class ValidationError extends AppError {\n  public readonly details?: any;\n\n  constructor(message: string = \"Validation failed\", details?: any) {\n    super(message, 400, true, { details });\n    this.details = details;\n  }\n\n  /**\n   * Create ValidationError from ZodError\n   */\n  static fromZodError(error: ZodError): ValidationError {\n    const details = error.errors.map((e) => ({\n      path: e.path.join(\".\"),\n      message: e.message,\n      code: e.code,\n    }));\n    return new ValidationError(\"Validation error\", details);\n  }\n\n  toJSON() {\n    return {\n      error: this.message,\n      details: this.details,\n      statusCode: this.statusCode,\n      context: this.context,\n    };\n  }\n}\n\n/**\n * Payment error class\n * For x402 payment-related failures\n */\nexport class PaymentError extends AppError {\n  public readonly reason?: string;\n  public readonly transactionHash?: string;\n\n  constructor(\n    message: string,\n    reason?: string,\n    transactionHash?: string,\n    context?: Record<string, any>\n  ) {\n    super(message, 402, true, context);\n    this.reason = reason;\n    this.transactionHash = transactionHash;\n  }\n\n  toJSON() {\n    return {\n      error: this.message,\n      reason: this.reason,\n      transactionHash: this.transactionHash,\n      statusCode: this.statusCode,\n      context: this.context,\n    };\n  }\n}\n\n/**\n * Not found error class\n */\nexport class NotFoundError extends AppError {\n  constructor(message: string = \"Resource not found\", context?: Record<string, any>) {\n    super(message, 404, true, context);\n  }\n}\n\n/**\n * Unauthorized error class\n */\nexport class UnauthorizedError extends AppError {\n  constructor(message: string = \"Unauthorized\", context?: Record<string, any>) {\n    super(message, 401, true, context);\n  }\n}\n\n/**\n * Forbidden error class\n */\nexport class ForbiddenError extends AppError {\n  constructor(message: string = \"Forbidden\", context?: Record<string, any>) {\n    super(message, 403, true, context);\n  }\n}\n\n/**\n * Rate limit error class\n */\nexport class RateLimitError extends AppError {\n  public readonly retryAfter?: number;\n\n  constructor(\n    message: string = \"Rate limit exceeded\",\n    retryAfter?: number,\n    context?: Record<string, any>\n  ) {\n    super(message, 429, true, context);\n    this.retryAfter = retryAfter;\n  }\n\n  toJSON() {\n    return {\n      error: this.message,\n      retryAfter: this.retryAfter,\n      statusCode: this.statusCode,\n      context: this.context,\n    };\n  }\n}\n\n/**\n * Service unavailable error class\n */\nexport class ServiceUnavailableError extends AppError {\n  constructor(message: string = \"Service unavailable\", context?: Record<string, any>) {\n    super(message, 503, true, context);\n  }\n}\n\n/**\n * Check if error is operational (expected) or programming error\n */\nexport function isOperationalError(error: Error): boolean {\n  if (error instanceof AppError) {\n    return error.isOperational;\n  }\n  return false;\n}\n\n/**\n * Error response formatter for API responses\n */\nexport interface ErrorResponse {\n  error: string;\n  message?: string;\n  details?: any;\n  statusCode: number;\n}\n\n/**\n * Format error for API response\n */\nexport function formatErrorResponse(error: unknown): ErrorResponse {\n  if (error instanceof ZodError) {\n    const validationError = ValidationError.fromZodError(error);\n    return validationError.toJSON() as ErrorResponse;\n  }\n\n  if (error instanceof AppError) {\n    return error.toJSON() as ErrorResponse;\n  }\n\n  if (error instanceof Error) {\n    return {\n      error: error.message,\n      statusCode: 500,\n    };\n  }\n\n  return {\n    error: \"Unknown error\",\n    statusCode: 500,\n  };\n}\n\n/**\n * Get HTTP status code from error\n */\nexport function getErrorStatusCode(error: unknown): number {\n  if (error instanceof AppError) {\n    return error.statusCode;\n  }\n  if (error instanceof ZodError) {\n    return 400;\n  }\n  return 500;\n}\n\n/**\n * Create error handler middleware (framework-agnostic)\n */\nexport function createErrorHandler(options?: {\n  logger?: (error: Error, context?: Record<string, any>) => void;\n  includeStack?: boolean;\n}) {\n  return (error: unknown) => {\n    const response = formatErrorResponse(error);\n    const statusCode = getErrorStatusCode(error);\n\n    if (options?.logger && error instanceof Error) {\n      options.logger(error, { statusCode });\n    }\n\n    if (options?.includeStack && error instanceof Error) {\n      (response as any).stack = error.stack;\n    }\n\n    return { response, statusCode };\n  };\n}\n"],"mappings":"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","names":[]}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@perkos/util-errors",
+  "version": "1.0.0",
+  "description": "Error handling utilities and classes for vendor services",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "lint": "tsc --noEmit",
+    "test": "vitest run",
+    "clean": "rm -rf dist",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "error",
+    "handling",
+    "validation",
+    "zod",
+    "api",
+    "perkos"
+  ],
+  "author": "PerkOS",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/PerkOS-xyz/pkg-util-errors.git"
+  },
+  "dependencies": {
+    "zod": "^3.22.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.10.0",
+    "tsup": "^8.0.1",
+    "typescript": "^5.3.3",
+    "vitest": "^1.2.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}