@dotdev/harmony-sdk 1.31.0 → 1.32.1

package/dist/errors/index.d.ts

@@ -1,11 +1,17 @@
+export type HarmonyErrorDetails = {
+    status?: number;
+    code?: string;
+};
 export declare class HarmonyAPIError extends Error {
-    constructor(message: string);
+    readonly status?: number;
+    readonly code?: string;
+    constructor(message: string, details?: HarmonyErrorDetails);
 }
 export declare class AuthenticationError extends HarmonyAPIError {
-    constructor(message: string);
+    constructor(message: string, details?: HarmonyErrorDetails);
 }
 export declare class RequestError extends HarmonyAPIError {
-    constructor(message: string);
+    constructor(message: string, details?: HarmonyErrorDetails);
 }
 export interface ApiError {
     status?: string;

package/dist/errors/index.js

@@ -1,18 +1,22 @@
 export class HarmonyAPIError extends Error {
-    constructor(message) {
+    status;
+    code;
+    constructor(message, details) {
         super(message);
         this.name = "HarmonyAPIError";
+        this.status = details?.status;
+        this.code = details?.code;
     }
 }
 export class AuthenticationError extends HarmonyAPIError {
-    constructor(message) {
-        super(message);
+    constructor(message, details) {
+        super(message, details);
         this.name = "AuthenticationError";
     }
 }
 export class RequestError extends HarmonyAPIError {
-    constructor(message) {
-        super(message);
+    constructor(message, details) {
+        super(message, details);
         this.name = "RequestError";
     }
 }

package/dist/errors/index.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/errors/index.spec.js

@@ -0,0 +1,56 @@
+import { AuthenticationError, HarmonyAPIError, RequestError, } from "./index";
+describe("HarmonyAPIError", () => {
+    it("constructs with message only (backward compat)", () => {
+        const e = new HarmonyAPIError("boom");
+        expect(e.message).toBe("boom");
+        expect(e.name).toBe("HarmonyAPIError");
+        expect(e.status).toBeUndefined();
+        expect(e.code).toBeUndefined();
+    });
+    it("accepts optional status and code via details arg", () => {
+        const e = new HarmonyAPIError("boom", { status: 400, code: "S:Server" });
+        expect(e.message).toBe("boom");
+        expect(e.status).toBe(400);
+        expect(e.code).toBe("S:Server");
+    });
+    it("accepts partial details (status only, code only)", () => {
+        const s = new HarmonyAPIError("a", { status: 500 });
+        expect(s.status).toBe(500);
+        expect(s.code).toBeUndefined();
+        const c = new HarmonyAPIError("b", { code: "X" });
+        expect(c.status).toBeUndefined();
+        expect(c.code).toBe("X");
+    });
+    it("is instanceof Error", () => {
+        expect(new HarmonyAPIError("x")).toBeInstanceOf(Error);
+    });
+});
+describe("RequestError", () => {
+    it("inherits HarmonyAPIError and exposes status/code", () => {
+        const e = new RequestError("req fail", { status: 502, code: "" });
+        expect(e).toBeInstanceOf(HarmonyAPIError);
+        expect(e).toBeInstanceOf(Error);
+        expect(e.name).toBe("RequestError");
+        expect(e.status).toBe(502);
+        expect(e.code).toBe("");
+    });
+    it("constructs with message only (backward compat)", () => {
+        const e = new RequestError("just msg");
+        expect(e.message).toBe("just msg");
+        expect(e.status).toBeUndefined();
+        expect(e.code).toBeUndefined();
+    });
+});
+describe("AuthenticationError", () => {
+    it("inherits HarmonyAPIError and supports details arg", () => {
+        const e = new AuthenticationError("no token", { status: 401 });
+        expect(e).toBeInstanceOf(HarmonyAPIError);
+        expect(e.name).toBe("AuthenticationError");
+        expect(e.status).toBe(401);
+    });
+    it("constructs with message only (backward compat)", () => {
+        const e = new AuthenticationError("no token");
+        expect(e.message).toBe("no token");
+        expect(e.status).toBeUndefined();
+    });
+});

package/dist/helpers/index.d.ts

@@ -1,5 +1,5 @@
 import { AxiosInstance } from "axios";
-import { ApiError, RequestError } from "../errors";
+import { ApiError, HarmonyAPIError } from "../errors";
 import { ParamLimits, ServiceAlias } from "../modules";
 export * from "./utils";
 export declare abstract class ApiHelper {
@@ -26,7 +26,7 @@ export declare abstract class ApiHelper {
      * @returns {Promise<R>}
      */
     static sendServiceRequest<R>(serviceName: string, methodName: string | string[], sessionId: string, serviceAlias: ServiceAlias, axios: AxiosInstance, body?: string): Promise<R>;
-    static parseError(error: any): Promise<RequestError>;
+    static parseError(error: any): Promise<HarmonyAPIError>;
     /**
      * Extract error response from Harmony in XML format and convert it to JSON format for ease of debugging
      *

package/dist/helpers/index.js

@@ -1,7 +1,7 @@
 import axios from "axios";
 import { promisify } from "util";
 import { parseString } from "xml2js";
-import { RequestError } from "../errors";
+import { HarmonyAPIError, RequestError } from "../errors";
 import { logger } from "./logger";
 import { Utils } from "./utils";
 export * from "./utils";
@@ -98,34 +98,53 @@ export class ApiHelper {
         return response[responseMethodName][0];
     }
     static async parseError(error) {
+        // An already-parsed Harmony error (re-thrown up through a module-level
+        // catch) must pass through unchanged. Re-parsing it would hit the
+        // non-axios fallthrough below and discard its status/code, masking the
+        // real fault (e.g. a 500 "Invalid Session") behind the generic
+        // "Unexpected error" message before it reaches the caller. The first
+        // parse already logged this fault, so we deliberately don't re-log it
+        // here. [DAT-2135]
+        if (error instanceof HarmonyAPIError) {
+            return error;
+        }
         if (axios.isAxiosError(error)) {
+            const status = error?.response?.status;
             const childLogger = logger.child({
                 error: {
                     config: error?.config,
                     request: error?.request,
                     data: error?.response?.data,
-                    status: error?.response?.status,
+                    status,
                 },
             });
             if (error?.response) {
+                const statusCategory = statusToCategory(status);
                 if (Utils.isValidXml(error?.response?.data)) {
                     const parsedError = await ApiHelper.parseHarmonyErrorResponse(error?.response?.data);
-                    childLogger.error(`Harmony request error`);
-                    return new RequestError(`API request failed with status ${error.response.status}: {code: ${parsedError?.code}, name: ${parsedError?.name}, message: ${parsedError?.message}}`);
+                    childLogger.error({
+                        statusCategory,
+                        harmonyCode: parsedError?.code,
+                        harmonyName: parsedError?.name,
+                        harmonyMessage: parsedError?.message,
+                    }, `Harmony request error`);
+                    return new RequestError(`API request failed with status ${error.response.status}: {code: ${parsedError?.code}, name: ${parsedError?.name}, message: ${parsedError?.message}}`, { status, code: parsedError?.code });
                 }
                 else {
-                    childLogger.error(`API request error due to response not in Harmony XML format`);
-                    return new RequestError(`API request failed but error response is not in Harmony XML format. Please check the logs for more details.`);
+                    childLogger.error({ statusCategory }, `API request error due to response not in Harmony XML format`);
+                    return new RequestError(`API request failed but error response is not in Harmony XML format. Please check the logs for more details.`, { status });
                 }
             }
             else if (error?.request) {
+                childLogger.error({ statusCategory: "no_response" }, `No response received from Harmony API`);
                 return new RequestError("No response received from the server during API call");
             }
             else {
+                childLogger.error({ statusCategory: "setup_failure" }, `Harmony API request setup failed`);
                 return new RequestError(`API request setup failed: ${error?.message}`);
             }
         }
-        logger.error(error, `⛔️ Unexpected error occurred during API request`);
+        logger.error({ err: error, statusCategory: "unexpected" }, `⛔️ Unexpected error occurred during API request`);
         return new RequestError(`Unexpected error occurred during API request`);
     }
     /**
@@ -161,6 +180,15 @@ export class ApiHelper {
         };
     }
 }
+function statusToCategory(status) {
+    if (status === undefined)
+        return "unknown";
+    if (status >= 400 && status < 500)
+        return "client_error";
+    if (status >= 500 && status < 600)
+        return "server_error";
+    return "unknown";
+}
 /**
  * Check whether the provided parameters meet the specified limits. If any parameter exceeds the limit, an error will be thrown.
  * If all checks passed, return true.

package/dist/helpers/index.spec.js

@@ -1,5 +1,6 @@
 import axios from "axios";
 import { ApiHelper, checkParamLimits, TEST_HEADERS, Utils } from ".";
+import { AuthenticationError, RequestError } from "../errors";
 import { ServiceAlias } from "../modules/shared/types";
 // Increase timeout due to Harmony API having long response time
 jest.setTimeout(999999);
@@ -146,3 +147,156 @@ describe("parseRequestError", () => {
         expect(await ApiHelper.parseHarmonyErrorResponse(errResp)).toEqual(expected);
     });
 });
+describe("ApiHelper.parseError", () => {
+    // Note: XML declaration must be at position 0 — no leading whitespace, or
+    // fast-xml-parser's XMLValidator rejects it and parseError takes the non-XML branch.
+    const HARMONY_XML_FAULT = `<?xml version='1.0' encoding='UTF-8'?><S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/"><S:Body><S:Fault xmlns:ns4="http://www.w3.org/2003/05/soap-envelope"><faultcode>S:Server</faultcode><faultstring>Failed Test Request</faultstring><detail><ns2:ServiceFault xmlns:ns2="http://pos.ws.fbsaust.com.au"><errorDetails>[204-104-2408071537-0000851206]  (Invalid value)</errorDetails></ns2:ServiceFault></detail></S:Fault></S:Body></S:Envelope>`;
+    const GIFT_CARD_SERIAL_FAULT = `<?xml version='1.0' encoding='UTF-8'?><S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/"><S:Body><S:Fault><faultcode>S:Server</faultcode><faultstring>Validation</faultstring><detail><ns2:ServiceFault xmlns:ns2="http://gv.ws.fbsaust.com.au"><errorDetails>SN00001 is not a valid Serial Number value</errorDetails></ns2:ServiceFault></detail></S:Fault></S:Body></S:Envelope>`;
+    const makeAxiosError = (overrides) => {
+        const err = new Error(overrides.message ?? "Request failed");
+        err.isAxiosError = true;
+        err.config = {};
+        if (overrides.response)
+            err.response = overrides.response;
+        if (overrides.request)
+            err.request = overrides.request;
+        return err;
+    };
+    // axios.isAxiosError is auto-mocked by jest.mock("axios") at top of file.
+    // Point it at real behaviour per-test so constructed errors pass isAxiosError().
+    // Also silence the pino logger and capture structured context passed to it.
+    const { logger: realLogger } = require("./logger");
+    let childErrorSpy;
+    beforeEach(() => {
+        mAxios.isAxiosError.mockImplementation((e) => !!e?.isAxiosError);
+        childErrorSpy = jest.fn();
+        jest.spyOn(realLogger, "error").mockImplementation(jest.fn());
+        jest.spyOn(realLogger, "child").mockReturnValue({
+            error: childErrorSpy,
+            debug: jest.fn(),
+            info: jest.fn(),
+            warn: jest.fn(),
+        });
+    });
+    afterEach(() => {
+        jest.restoreAllMocks();
+    });
+    it("populates status and code for 4xx with Harmony XML body", async () => {
+        const err = makeAxiosError({
+            response: { status: 400, data: HARMONY_XML_FAULT },
+        });
+        const result = await ApiHelper.parseError(err);
+        expect(result).toBeInstanceOf(RequestError);
+        expect(result.status).toBe(400);
+        expect(result.code).toBe("S:Server");
+        expect(result.message).toBe(`API request failed with status 400: {code: S:Server, name: Failed Test Request, message: [204-104-2408071537-0000851206]  (Invalid value)}`);
+    });
+    it("populates status for 5xx with Harmony XML body", async () => {
+        const err = makeAxiosError({
+            response: { status: 500, data: HARMONY_XML_FAULT },
+        });
+        const result = await ApiHelper.parseError(err);
+        expect(result.status).toBe(500);
+        expect(result.code).toBe("S:Server");
+    });
+    it("populates status but no code for non-XML 4xx response", async () => {
+        const err = makeAxiosError({
+            response: { status: 404, data: "Not Found" },
+        });
+        const result = await ApiHelper.parseError(err);
+        expect(result.status).toBe(404);
+        expect(result.code).toBeUndefined();
+        expect(result.message).toBe(`API request failed but error response is not in Harmony XML format. Please check the logs for more details.`);
+    });
+    it("populates status but no code for non-XML 5xx response", async () => {
+        const err = makeAxiosError({
+            response: { status: 502, data: "502 Bad Gateway" },
+        });
+        const result = await ApiHelper.parseError(err);
+        expect(result.status).toBe(502);
+        expect(result.code).toBeUndefined();
+    });
+    it("returns no status when request was sent but no response received", async () => {
+        const err = makeAxiosError({ request: {} });
+        const result = await ApiHelper.parseError(err);
+        expect(result.status).toBeUndefined();
+        expect(result.code).toBeUndefined();
+        expect(result.message).toBe("No response received from the server during API call");
+    });
+    it("returns no status for axios setup failure", async () => {
+        const err = makeAxiosError({ message: "bad URL" });
+        const result = await ApiHelper.parseError(err);
+        expect(result.status).toBeUndefined();
+        expect(result.message).toBe("API request setup failed: bad URL");
+    });
+    it("returns a RequestError for non-axios errors (fallthrough)", async () => {
+        const result = await ApiHelper.parseError(new Error("random"));
+        expect(result).toBeInstanceOf(RequestError);
+        expect(result.status).toBeUndefined();
+        expect(result.message).toBe("Unexpected error occurred during API request");
+    });
+    it("returns an already-parsed HarmonyAPIError unchanged (no re-masking) [DAT-2135]", async () => {
+        // A module-level catch may re-parse an error that sendSoapRequest already
+        // turned into a RequestError carrying status/code. Re-parsing must NOT
+        // discard those — otherwise the real fault (e.g. a 500 "Invalid Session")
+        // is masked behind the generic "Unexpected error" message and never
+        // reaches the caller.
+        const alreadyParsed = new RequestError(`API request failed with status 500: {code: S:Server, name: Invalid Session., message: }`, { status: 500, code: "S:Server" });
+        const result = await ApiHelper.parseError(alreadyParsed);
+        expect(result).toBe(alreadyParsed);
+        expect(result.status).toBe(500);
+        expect(result.code).toBe("S:Server");
+        expect(result.message).toContain("Invalid Session.");
+    });
+    it("does not downgrade an already-parsed AuthenticationError [DAT-2135]", async () => {
+        // AuthenticationError is the other HarmonyAPIError subclass; a 401 session
+        // drop must keep its type and status, not be re-parsed into a RequestError.
+        const authErr = new AuthenticationError("Invalid Session.", {
+            status: 401,
+            code: "S:Server",
+        });
+        const result = await ApiHelper.parseError(authErr);
+        expect(result).toBe(authErr);
+        expect(result).toBeInstanceOf(AuthenticationError);
+        expect(result.status).toBe(401);
+    });
+    it("preserves gift-card serial-number substring in message (backward-compat)", async () => {
+        const err = makeAxiosError({
+            response: { status: 400, data: GIFT_CARD_SERIAL_FAULT },
+        });
+        const result = await ApiHelper.parseError(err);
+        // core-v2 services/gift-cards/strategies/harmony.ts:158 does
+        // err.message.includes("is not a valid Serial Number value") — must remain true.
+        expect(result.message.includes("is not a valid Serial Number value")).toBe(true);
+    });
+    it("logs structured fields for 4xx XML (statusCategory=client_error + harmonyCode)", async () => {
+        const err = makeAxiosError({
+            response: { status: 400, data: HARMONY_XML_FAULT },
+        });
+        await ApiHelper.parseError(err);
+        expect(childErrorSpy).toHaveBeenCalledTimes(1);
+        const [ctx, msg] = childErrorSpy.mock.calls[0];
+        expect(ctx).toMatchObject({
+            statusCategory: "client_error",
+            harmonyCode: "S:Server",
+            harmonyName: "Failed Test Request",
+            harmonyMessage: "[204-104-2408071537-0000851206]  (Invalid value)",
+        });
+        expect(msg).toBe("Harmony request error");
+    });
+    it("logs statusCategory=server_error for 5xx", async () => {
+        const err = makeAxiosError({
+            response: { status: 500, data: HARMONY_XML_FAULT },
+        });
+        await ApiHelper.parseError(err);
+        const [ctx] = childErrorSpy.mock.calls[0];
+        expect(ctx).toMatchObject({ statusCategory: "server_error" });
+    });
+    it("logs statusCategory=no_response when request never got a response", async () => {
+        const err = makeAxiosError({ request: {} });
+        await ApiHelper.parseError(err);
+        const [ctx, msg] = childErrorSpy.mock.calls[0];
+        expect(ctx).toMatchObject({ statusCategory: "no_response" });
+        expect(msg).toBe("No response received from Harmony API");
+    });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dotdev/harmony-sdk",
-  "version": "1.31.0",
+  "version": "1.32.1",
   "description": "Harmony API SDK",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",