--

Author: alexasomba

CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## [1.10.6](https://github.com/alexasomba/paystack-node/compare/v1.10.5...v1.10.6) (2026-06-01)
+
+### Bug Fixes
+
+- preserve Paystack error envelope fields on `PaystackError`
+- keep raw error bodies and transport causes available for diagnostics
+- align generated SDK release-readiness metadata checks
+
 ## [1.9.0](https://github.com/alexasomba/paystack-node/compare/v1.8.0...v1.9.0) (2026-04-16)
 
 ### Features

README.md

@@ -13,7 +13,7 @@ TypeScript-first Paystack API client for Node.js, generated from the official Pa
 - **Smart Retries**: Automatic retries for transient failures with exponential backoff and jitter.
 - **Retry-After Compliance**: Automatically respects Paystack `Retry-After` headers on rate limit responses.
 - **Sophisticated Idempotency**: Built-in support for manual, static, or automatic UUID-based idempotency keys on POST requests.
-- **Detailed Error Handling**: `PaystackApiError` includes `status`, `url`, and Paystack `requestId`.
+- **Detailed Error Handling**: `PaystackError` preserves Paystack `code`, `type`, `meta`, request ID, HTTP status, and the raw response body.
 - **Webhook Verification**: Timing-safe webhook signature verification helper included.
 
 ## Install
@@ -61,7 +61,7 @@ const data = assertOk(result);
 console.log(data.authorization_url);
 ```
 
-`assertOk` returns the successful Paystack payload and throws a structured `PaystackApiError` for non-2xx responses.
+`assertOk` returns the successful Paystack payload and throws a structured `PaystackError` for non-2xx responses or `{ status: false }` envelopes.
 
 ## API Basics
 
@@ -200,11 +200,14 @@ const error = toPaystackApiError(result);
 
 if (error) {
   console.error(`Status ${error.status}: ${error.message}`);
+  console.error(`Paystack code: ${error.code}`);
+  console.error(`Paystack type: ${error.type}`);
   console.error(`Paystack Request ID: ${error.requestId}`);
+  console.error(error.raw);
 }
 ```
 
-The `requestId` is useful when correlating logs or escalating an issue with Paystack support.
+Use `error.code` and `error.type` for branching on validation, processor, and API failures. The `requestId` is useful when correlating logs or escalating an issue with Paystack support, while `error.raw` / `error.body` keeps the original response envelope available for diagnostics.
 
 ## Errors
 

package.json

@@ -74,7 +74,7 @@
     "lint": "vp lint . --fix",
     "lint:package": "publint run --strict",
     "lint:skills": "intent validate",
-    "lint:types": "npm_config_cache=/private/tmp/paystack-openapi-npm-cache attw --profile esm-only --pack .",
+    "lint:types": "npm_config_ignore_scripts=true npm_config_cache=/tmp/paystack-openapi-npm-cache attw --profile esm-only --pack .",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "clean": "rm -rf dist",
     "prepack": "pnpm build",

src/errors.ts

@@ -14,6 +14,27 @@ export function getPaystackRequestId(headers: Headers | HeadersInit): string | u
   return undefined;
 }
 
+export type PaystackErrorType =
+  | "api_error"
+  | "validation_error"
+  | "processor_error"
+  | (string & {});
+
+export interface PaystackErrorOptions {
+  message: string;
+  code?: string;
+  type?: PaystackErrorType;
+  status?: number;
+  requestId?: string;
+  meta?: Record<string, unknown>;
+  /** Parsed Paystack response envelope or transport payload used to create this error. */
+  raw?: unknown;
+  /** Alias for raw, kept for callers that prefer body-oriented naming. */
+  body?: unknown;
+  /** Original transport/openapi-fetch error, when one exists. */
+  cause?: unknown;
+}
+
 /**
  * Standard Paystack API Error
  */
@@ -28,27 +49,29 @@ export class PaystackError extends Error {
   public readonly requestId?: string;
   /** Additional metadata from the error response */
   public readonly meta?: Record<string, unknown>;
+  /** Parsed Paystack response envelope or transport payload used to create this error. */
+  public readonly raw?: unknown;
+  /** Alias for raw, kept for callers that prefer body-oriented naming. */
+  public readonly body?: unknown;
 
-  constructor(options: {
-    message: string;
-    code?: string;
-    type?: string;
-    status?: number;
-    requestId?: string;
-    meta?: Record<string, unknown>;
-  }) {
+  constructor(options: PaystackErrorOptions) {
     const requestId = options.requestId;
     const suffix =
       requestId !== undefined && requestId !== null && requestId !== ""
         ? ` (requestId: ${requestId})`
         : "";
-    super(`${options.message}${suffix}`);
+    super(
+      `${options.message}${suffix}`,
+      options.cause === undefined ? undefined : { cause: options.cause },
+    );
     this.name = "PaystackError";
     this.code = options.code;
     this.type = options.type;
     this.status = options.status;
     this.requestId = options.requestId;
     this.meta = options.meta;
+    this.raw = options.raw ?? options.body;
+    this.body = options.body ?? options.raw;
 
     // Ensure proper stack trace in Node.js
     if (typeof Error.captureStackTrace === "function") {
@@ -71,3 +94,15 @@ export class PaystackError extends Error {
     return this.type === "validation_error";
   }
 }
+
+/**
+ * @deprecated Use PaystackError
+ */
+export const PaystackApiError = PaystackError;
+
+/**
+ * @deprecated Use PaystackError
+ */
+export function isPaystackApiError(value: unknown): value is PaystackError {
+  return value instanceof PaystackError;
+}

src/response.ts

@@ -1,4 +1,4 @@
-import { PaystackError, getPaystackRequestId } from "./errors.js";
+import { PaystackError, getPaystackRequestId, type PaystackErrorType } from "./errors.js";
 
 /**
  * Base structure of a Paystack API response body
@@ -7,7 +7,53 @@ export interface PaystackRawResponse<T = unknown> {
   status: boolean;
   message: string;
   data: T;
+  code?: string;
+  type?: PaystackErrorType;
   meta?: Record<string, unknown>;
+  errorCodeMappingNotFound?: boolean;
+}
+
+interface PaystackErrorEnvelope {
+  message?: string;
+  code?: string;
+  type?: PaystackErrorType;
+  meta?: Record<string, unknown>;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}
+
+function getStringField(source: unknown, field: string): string | undefined {
+  if (!isRecord(source)) return undefined;
+  const value = source[field];
+  return typeof value === "string" && value !== "" ? value : undefined;
+}
+
+function getMeta(source: unknown): Record<string, unknown> | undefined {
+  if (!isRecord(source)) return undefined;
+  const value = source.meta;
+  return isRecord(value) ? value : undefined;
+}
+
+function getPaystackEnvelope(source: unknown): PaystackErrorEnvelope {
+  return {
+    message: getStringField(source, "message"),
+    code: getStringField(source, "code"),
+    type: getStringField(source, "type") as PaystackErrorType | undefined,
+    meta: getMeta(source),
+  };
+}
+
+function resolveErrorMessage(error: unknown, raw: unknown): string {
+  const errorEnvelope = getPaystackEnvelope(error);
+  if (errorEnvelope.message !== undefined) return errorEnvelope.message;
+
+  const rawEnvelope = getPaystackEnvelope(raw);
+  if (rawEnvelope.message !== undefined) return rawEnvelope.message;
+
+  if (error instanceof Error && error.message !== "") return error.message;
+  return "Network or HTTP Error";
 }
 
 /**
@@ -48,19 +94,19 @@ export class PaystackResponse<T> {
     const requestId = getPaystackRequestId(this.response.headers);
 
     if (this.error !== undefined && this.error !== null) {
-      // Handle HTTP or Network errors
-      let message = "Network or HTTP Error";
-      if (typeof this.error === "object" && this.error !== null && "message" in this.error) {
-        message = String((this.error as { message: unknown }).message);
-      } else if (this.raw && typeof this.raw === "object" && "message" in this.raw) {
-        message = this.raw.message;
-      }
+      const errorEnvelope = getPaystackEnvelope(this.error);
+      const rawEnvelope = getPaystackEnvelope(this.raw);
 
       throw new PaystackError({
-        message,
+        message: resolveErrorMessage(this.error, this.raw),
+        code: errorEnvelope.code ?? rawEnvelope.code,
+        type: errorEnvelope.type ?? rawEnvelope.type,
         status: this.response.status,
         requestId,
-        meta: this.raw?.meta,
+        meta: errorEnvelope.meta ?? rawEnvelope.meta,
+        raw: this.error,
+        body: this.error,
+        cause: this.error,
       });
     }
 
@@ -70,16 +116,24 @@ export class PaystackResponse<T> {
         message: "Empty response body",
         status: this.response.status,
         requestId,
+        raw: this.raw,
+        body: this.raw,
       });
     }
 
     if (!this.raw.status) {
+      const rawEnvelope = getPaystackEnvelope(this.raw);
+
       // Handle Paystack-level errors (status: false)
       throw new PaystackError({
-        message: this.raw.message,
+        message: rawEnvelope.message ?? "Paystack API Error",
+        code: rawEnvelope.code,
+        type: rawEnvelope.type,
         status: this.response.status,
         requestId,
-        meta: this.raw.meta,
+        meta: rawEnvelope.meta,
+        raw: this.raw,
+        body: this.raw,
       });
     }
 
@@ -93,9 +147,20 @@ export class PaystackResponse<T> {
    * @throws {PaystackError} if status is false.
    */
   public get data(): T {
-    if (this.raw === undefined || this.raw === null) {
-      return this.unwrap();
-    }
-    return this.raw.data;
+    return this.unwrap();
+  }
+}
+
+export function assertOk<T>(result: PaystackResponse<T>): T {
+  return result.unwrap();
+}
+
+export function toPaystackApiError<T>(result: PaystackResponse<T>): PaystackError | undefined {
+  try {
+    result.unwrap();
+    return undefined;
+  } catch (error) {
+    if (error instanceof PaystackError) return error;
+    throw error;
   }
 }

test/errors.test.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect } from "vite-plus/test";
-import { PaystackError, getPaystackRequestId } from "../src/errors.js";
+import { PaystackError, getPaystackRequestId, isPaystackApiError } from "../src/errors.js";
 
 describe("Error Handling", () => {
   describe("getPaystackRequestId", () => {
@@ -22,13 +22,22 @@ describe("Error Handling", () => {
 
   describe("PaystackError", () => {
     it("should correctly capture error details", () => {
+      const raw = {
+        status: false,
+        message: "Failed",
+        code: "invalid_params",
+        type: "validation_error",
+      };
+      const cause = new Error("Original transport error");
       const error = new PaystackError({
         message: "Failed",
         status: 400,
         requestId: "req_123",
         code: "invalid_params",
         type: "validation_error",
         meta: { field: "email" },
+        raw,
+        cause,
       });
 
       expect(error.message).toContain("Failed");
@@ -38,6 +47,10 @@ describe("Error Handling", () => {
       expect(error.code).toBe("invalid_params");
       expect(error.type).toBe("validation_error");
       expect(error.meta).toEqual({ field: "email" });
+      expect(error.raw).toBe(raw);
+      expect(error.body).toBe(raw);
+      expect(error.cause).toBe(cause);
+      expect(isPaystackApiError(error)).toBe(true);
     });
 
     it("should identify validation errors", () => {