@dotdev/harmony-sdk 1.18.1 → 1.20.0

package/dist/HarmonyAPI.d.ts

@@ -1,9 +1,11 @@
+import { AxiosInstance } from "axios";
 import { IAxiosRetryConfig } from "axios-retry";
-import { AuthenticationToken, Carrier, CarrierShipment, CreateDiaryQueryParams, Diary, DispatchData, GetCarrierShipmentByTimeQueryParams, GetDiaryQueryParams, GetDispatchDataByTimeQueryParams, ProcessInvoiceQueryParams, ProcessSaleOrderQueryParams, ProcessSaleOrderWithoutPaymentQueryParams, SizeGrid, Stock, StockBarcode, StockCategory, StockClassification, StockClassificationType, StockColor, StockLevel, StockLevelLookupQueryParams, StockLookupRequestParams, Warehouse } from "./modules";
+import { AuthenticationToken, Carrier, CarrierShipment, CreateDiaryQueryParams, Diary, DispatchData, GetCarrierShipmentByTimeQueryParams, GetDiaryQueryParams, GetDispatchDataByTimeQueryParams, ProcessInvoiceQueryParams, ProcessReturnsQueryParams, ProcessSaleOrderQueryParams, ProcessSaleOrderWithoutPaymentQueryParams, SizeGrid, Stock, StockBarcode, StockCategory, StockClassification, StockClassificationType, StockColor, StockLevel, StockLevelLookupQueryParams, StockLookupRequestParams, Warehouse } from "./modules";
 import { GiftVoucher, GiftVoucherLookupQueryParams, GiftVoucherReservationQueryParams, GiftVoucherUsedQueryParams, GiftVoucherVerificationKeyQueryParams } from "./modules/gift-voucher/types";
+import { RequestConfig } from "./types";
 export declare class HarmonyAPI {
     private baseUrl;
-    private axiosInstance;
+    axiosInstance: AxiosInstance;
     private authModule;
     private stockLookupModule;
     private stockLevelLookupModule;
@@ -11,7 +13,7 @@ export declare class HarmonyAPI {
     private carrierModule;
     private diaryModule;
     private giftVoucherModule;
-    constructor(url: string, axiosRetryConfig?: IAxiosRetryConfig);
+    constructor(url: string, axiosRetryConfig?: IAxiosRetryConfig, config?: RequestConfig);
     authenticate(authToken: AuthenticationToken): Promise<string>;
     stockLookup(params: StockLookupRequestParams, sessionId: string): Promise<Stock[]>;
     stockCategoryLookup(sessionId: string): Promise<StockCategory[]>;
@@ -25,8 +27,9 @@ export declare class HarmonyAPI {
     processSalesOrder(params: ProcessSaleOrderQueryParams, sessionId: string): Promise<boolean>;
     processSalesOrderWithoutPayment(params: ProcessSaleOrderWithoutPaymentQueryParams, sessionId: string): Promise<boolean>;
     mapOrderPayloadToXml(params: Partial<ProcessSaleOrderQueryParams>, sessionId: string, method?: "ProcessSalesOrder" | "ProcessSalesOrderWithoutPayment" | "ProcessInvoice"): Promise<string>;
+    mapReturnPayloadToXml(params: ProcessReturnsQueryParams, sessionId: string): Promise<string>;
     processInvoice(params: ProcessInvoiceQueryParams, sessionId: string): Promise<boolean>;
-    processReturns(params: ProcessSaleOrderQueryParams, sessionId: string): Promise<boolean>;
+    processReturns(params: ProcessReturnsQueryParams, sessionId: string): Promise<boolean>;
     modifyExistingSalesOrder(params: ProcessSaleOrderQueryParams, sessionId: string): Promise<boolean>;
     cancelExistingSalesOrder(params: ProcessSaleOrderQueryParams, sessionId: string): Promise<boolean>;
     getCarrier(sessionId: string): Promise<Carrier[]>;

package/dist/HarmonyAPI.js

@@ -16,12 +16,14 @@ export class HarmonyAPI {
     carrierModule;
     diaryModule;
     giftVoucherModule;
-    constructor(url, axiosRetryConfig) {
+    constructor(url, axiosRetryConfig, config) {
         this.baseUrl = url;
         this.axiosInstance = axios.create({
             baseURL: this.baseUrl,
             headers: {
+                ...config?.headers,
                 "Content-Type": "text/xml;charset=UTF-8",
+                "Accept-Encoding": "gzip, deflate, br", // Override default Accept-Encoding
             },
             httpsAgent: new https.Agent({
                 rejectUnauthorized: false,
@@ -91,6 +93,9 @@ export class HarmonyAPI {
     async mapOrderPayloadToXml(params, sessionId, method) {
         return await this.pointOfSaleModule.mapOrderPayloadToXml(params, sessionId, method);
     }
+    async mapReturnPayloadToXml(params, sessionId) {
+        return await this.pointOfSaleModule.mapReturnPayloadToXml(params, sessionId);
+    }
     // Post fulfilled orders
     async processInvoice(params, sessionId) {
         return await this.pointOfSaleModule.processInvoice(params, sessionId);

package/dist/helpers/index.js

@@ -2,6 +2,7 @@ import axios from "axios";
 import { promisify } from "util";
 import { parseString } from "xml2js";
 import { RequestError } from "../errors";
+import logger from "./logger";
 import { Utils } from "./utils";
 export * from "./utils";
 const parseXml = promisify(parseString);
@@ -9,36 +10,29 @@ export class ApiHelper {
     static async sendSoapRequest(endpoint, axiosInstance, requestBody, type = "POST") {
         const url = `${endpoint}?wsdl`;
         let response;
-        let defaultConfig = {
-            headers: {
-                'Accept-Encoding': 'gzip, deflate, br' //Override default Accept-Encoding
-            }
-        };
         try {
             let response;
             switch (type) {
                 case "GET":
-                    response = await axiosInstance.get(url, {
-                        ...defaultConfig,
-                        params: {},
-                    });
+                    response = await axiosInstance.get(url);
                     break;
                 case "POST":
                 default:
-                    response = await axiosInstance.post(url, requestBody, {
-                        ...defaultConfig
-                        // headers: {
-                        //   'SOAPAction': request.action
-                        // }
-                    });
+                    response = await axiosInstance.post(url, requestBody);
                     break;
             }
-            console.debug(`Harmony response (success) - size [${+response?.headers?.['content-length']}]: `, { response: response?.data });
+            const child = logger.child({
+                request: requestBody,
+                response: response?.data,
+                size: +response?.headers?.["content-length"],
+                status: response?.status,
+            });
+            child.debug(`Harmony response (success) - size [${+response?.headers?.["content-length"]}]: `, { response: response?.data });
             const result = (await parseXml(response?.data)); // fix type
             return result["S:Envelope"]["S:Body"][0];
         }
         catch (error) {
-            console.error(`Harmony reponse (fail): `, { response });
+            logger.error(`Harmony reponse (fail): `, { response });
             throw await ApiHelper.parseError(error);
         }
     }
@@ -89,7 +83,10 @@ export class ApiHelper {
             ? `ns2:${methodName[0]}Response`
             : `ns2:${methodName}Response`;
         const requestBody = ApiHelper.createServiceRequestBody(methodName, sessionId, serviceAlias, body);
-        console.debug(`Harmony request body`, { request: requestBody });
+        const child = logger.child({
+            request: requestBody,
+        });
+        child.debug(`Sending API request`);
         const response = await ApiHelper.sendSoapRequest(serviceName, axios, requestBody);
         return response[responseMethodName][0];
     }
@@ -100,8 +97,6 @@ export class ApiHelper {
                 return new RequestError(`API request failed with status ${error.response.status}: {code: ${parsedError?.code}, name: ${parsedError?.name}, message: ${parsedError?.message}}`);
             }
             else if (error?.request) {
-                console.log(`The following request was sent to server`);
-                console.log(error?.toJSON());
                 return new RequestError("No response received from the server during API call");
             }
             else {

package/dist/helpers/logger.d.ts

@@ -0,0 +1,2 @@
+declare const logger: import("pino").Logger<never, boolean>;
+export default logger;

package/dist/helpers/logger.js

@@ -0,0 +1,3 @@
+import pino from "pino";
+const logger = pino();
+export default logger;

package/dist/helpers/utils.spec.js

@@ -1,4 +1,6 @@
+import { HarmonyAPI } from "../HarmonyAPI";
 import { Utils } from "./utils";
+jest.unmock("axios");
 describe("Utils", () => {
     test("isEmptyArray", () => {
         expect.assertions(7);
@@ -94,3 +96,15 @@ describe("Utils", () => {
         });
     });
 });
+describe("Misc", () => {
+    test("Axios should pass through request headers correctly", () => {
+        const harmonyApi = new HarmonyAPI("test", undefined, {
+            headers: { "test-header": "test-value" },
+        });
+        expect(harmonyApi.axiosInstance.defaults.headers["test-header"]).toEqual("test-value");
+        // Default header for Content-Type should be set to text/xml;charset=UTF-8
+        expect(harmonyApi.axiosInstance.defaults.headers["Content-Type"]).toEqual("text/xml;charset=UTF-8");
+        // Check if Accept-Encoding is set to gzip, deflate, br for compression support (currently enabled for S2)
+        expect(harmonyApi.axiosInstance.defaults.headers["Accept-Encoding"]).toEqual("gzip, deflate, br");
+    });
+});

package/dist/modules/point-of-sale/mappings/process-returns.mapper.d.ts

@@ -0,0 +1,15 @@
+import { ProcessReturnsQueryDebtor, ProcessReturnsQueryExtra, ProcessReturnsQueryHeader, ProcessReturnsQueryParams, ProcessReturnsQueryStock } from "../types";
+export declare function mapProcessReturnsQueryParams(params: ProcessReturnsQueryParams): string;
+export declare function mapProcessReturnsBaseQueryParams(params: ProcessReturnsQueryParams): {
+    mode: import("../types").PosQueryMode | undefined;
+    audit_no: string;
+    export_no: string | undefined;
+    header: string;
+    extra: string;
+    stock: string[];
+};
+export declare function mapProcessReturnsQueryHeaders(params: ProcessReturnsQueryHeader): string;
+export declare function mapProcessReturnsQueryExtra(params: ProcessReturnsQueryExtra): string;
+export declare function mapReturnsInvoiceQuery(params: ProcessReturnsQueryParams): string;
+export declare function mapProcessReturnsQueryStock(params: ProcessReturnsQueryStock): string;
+export declare function mapProcessReturnsQueryDebtor(params: ProcessReturnsQueryDebtor): string;

package/dist/modules/point-of-sale/mappings/process-returns.mapper.js

@@ -0,0 +1,128 @@
+import { Utils } from "../../../helpers";
+export function mapProcessReturnsQueryParams(params) {
+    const body = {
+        ...mapProcessReturnsBaseQueryParams(params),
+        invoice: mapReturnsInvoiceQuery(params),
+        debtor: (params?.debtor ?? []).map(mapProcessReturnsQueryDebtor),
+    };
+    return Utils.toXml(Utils.deleteEmptyProps(body));
+}
+export function mapProcessReturnsBaseQueryParams(params) {
+    return {
+        mode: params?.mode,
+        audit_no: params?.auditNo,
+        export_no: params?.exportNo,
+        header: mapProcessReturnsQueryHeaders(params?.header),
+        extra: params?.extra ? mapProcessReturnsQueryExtra(params.extra) : "",
+        stock: params?.stock.map(mapProcessReturnsQueryStock),
+    };
+}
+export function mapProcessReturnsQueryHeaders(params) {
+    // XML body in JSON format, to be converted to XML string
+    const body = {
+        credit_no: params?.creditNo,
+        customer_order_no: params?.customerOrderNo,
+        transaction_date: params?.transactionDate,
+        transaction_time_hour: params?.transactionTimeHour,
+        transaction_time_min: params?.transactionTimeMin,
+        transaction_time_sec: params?.transactionTimeSec,
+        shop_debtor: params?.shopDebtor,
+        diary: params?.diary,
+        diary_name_1: params?.diaryName1,
+        diary_name_2: params?.diaryName2,
+        warehouse: params?.warehouse,
+        originated_warehouse: params?.originatedWarehouse,
+        agent_zone_1: params?.agentZone1,
+        agent_zone_2: params?.agentZone2 ?? "",
+        agent_zone_3: params?.agentZone3 ?? "",
+        terminal_id: params?.terminalId,
+        order_class: params?.orderClass,
+        user: params?.user,
+        comment_1: params?.comment1,
+        comment_2: params?.comment2,
+        comment_3: params?.comment3,
+        comment_4: params?.comment4,
+        comment_5: params?.comment5,
+        comment_6: params?.comment6,
+        comment_7: params?.comment7,
+        comment_8: params?.comment8,
+        comment_9: params?.comment9,
+        comment_10: params?.comment10,
+        order_tax_exemption: params?.orderTaxExemption,
+        originator_software: params?.originatorSoftware,
+        account_sale_flag: params?.accountSaleFlag,
+    };
+    return Utils.deleteEmptyProps(body);
+}
+export function mapProcessReturnsQueryExtra(params) {
+    // XML body in JSON format, to be converted to XML string
+    const body = {
+        email: params?.email,
+        telephone_home: params?.telephoneHome,
+        telephone_mobile: params?.telephoneMobile,
+        telephone_work: params?.telephoneWork,
+        billing_surname: params?.billingSurname,
+        billing_first_name: params?.billingFirstname,
+        billing_address_1: params?.billingAddress1,
+        billing_address_2: params?.billingAddress2,
+        billing_address_3: params?.billingAddress3,
+        billing_address_4: params?.billingAddress4,
+        billing_postcode: params?.billingPostcode,
+        billing_telephone_home: params?.billingTelephoneHome,
+        billing_telephone_mobile: params?.billingTelephoneMobile,
+        billing_telephone_work: params?.billingTelephoneWork,
+        customised_info: params?.customisedInfo,
+    };
+    return Utils.deleteEmptyProps(body);
+}
+export function mapReturnsInvoiceQuery(params) {
+    const body = {
+        invoice_price_inc: params?.invoice?.invoicePriceInc,
+        rounding: params?.invoice?.rounding,
+        total_tax: params?.invoice?.totalTax,
+        cash_drawer_id: params?.invoice?.cashDrawerId,
+    };
+    return Utils.deleteEmptyProps(body);
+}
+export function mapProcessReturnsQueryStock(params) {
+    // XML body in JSON format, to be converted to XML string
+    const body = {
+        stock: params?.stock,
+        stock_description: params?.stockDescription,
+        size: params?.size,
+        qdp: params?.qdp,
+        pdp: params?.pdp,
+        return_qty: params?.returnQty,
+        discount_price: params?.discountPrice,
+        line_tax: params?.lineTax,
+        discount_rate: params?.discountRate,
+        discount_reason: params?.discountReason,
+        credit_note_reason: params?.creditNoteReason,
+        serial_no: params?.serialNo,
+        comment: params?.comment,
+        credit_note_reference: params?.creditNoteReference,
+        current_rrp_inc: params?.currentRrpInc,
+        per: params?.per,
+        singles_per_pack: params?.singlesPerPack,
+        packs_per_carton: params?.packsPerCarton,
+        size_pack_name: params?.sizePackName,
+    };
+    return Utils.deleteEmptyProps(body);
+}
+export function mapProcessReturnsQueryDebtor(params) {
+    // XML body in JSON format, to be converted to XML string
+    const body = {
+        payment_type: params?.paymentType,
+        payment_amount: params?.paymentAmount,
+        card_name: params?.cardName,
+        card_no: params?.cardNo,
+        card_holder: params?.cardHolder,
+        card_expiry_month: params?.cardExpiryMonth,
+        card_expiry_year: params?.cardExpiryYear,
+        comment: params?.comment,
+        cash_drawer_id: params?.cashDrawerId,
+        gift_voucher_stock: params?.giftVoucherStock,
+        gift_voucher_serial_no: params?.giftVoucherSerialNo,
+    };
+    return Utils.deleteEmptyProps(body);
+}

package/dist/modules/point-of-sale/point-of-sale.module.d.ts

@@ -1,5 +1,5 @@
 import { AxiosInstance } from "axios";
-import { ProcessInvoiceQueryParams, ProcessSaleOrderQueryParams, ProcessSaleOrderWithoutPaymentQueryParams } from "./types";
+import { ProcessInvoiceQueryParams, ProcessReturnsQueryParams, ProcessSaleOrderQueryParams, ProcessSaleOrderWithoutPaymentQueryParams } from "./types";
 export declare class PointOfSaleModule {
     private axiosInstance;
     private readonly SERVICE_URL;
@@ -22,6 +22,7 @@ export declare class PointOfSaleModule {
      * @param {string} sessionId
      */
     mapOrderPayloadToXml(params: Partial<ProcessSaleOrderQueryParams>, sessionId: string, method?: "ProcessSalesOrder" | "ProcessSalesOrderWithoutPayment" | "ProcessInvoice"): Promise<string>;
+    mapReturnPayloadToXml(params: ProcessReturnsQueryParams, sessionId: string): Promise<string>;
     /**
      * Function to call the ProcessSalesOrderWithoutPayment endpoint in Harmony Point Of Sale service
      *
@@ -42,11 +43,11 @@ export declare class PointOfSaleModule {
      * Function to call the ProcessReturns endpoint in Harmony Point Of Sale service
      *
      * @async
-     * @param {ProcessSaleOrderQueryParams} params
+     * @param {ProcessReturnsQueryParams} params
      * @param {string} sessionId
      * @returns {Promise<boolean>}
      */
-    processReturns(params: ProcessSaleOrderQueryParams, sessionId: string): Promise<boolean>;
+    processReturns(params: ProcessReturnsQueryParams, sessionId: string): Promise<boolean>;
     /**
      * Function to call the ModifyExistingSalesOrder endpoint in Harmony Point Of Sale service
      *

package/dist/modules/point-of-sale/point-of-sale.module.js

@@ -3,6 +3,7 @@ import { ServiceAlias } from "../shared";
 import { mapPosInvoiceQuery, mapProcessInvoiceQueryParams, mapProcessSaleOrderQueryDebtor, mapProcessSaleOrderQueryExtra, mapProcessSaleOrderQueryHeaders, mapProcessSaleOrderQueryParams, mapProcessSaleOrderQueryStock, mapProcessSaleOrderWithoutPaymentQueryParams, } from "./mappings/process-sale-order.mapper";
 import { promisify } from "util";
 import { parseString } from "xml2js";
+import { mapProcessReturnsQueryExtra, mapProcessReturnsQueryHeaders, mapProcessReturnsQueryParams, mapProcessReturnsQueryStock, mapReturnsInvoiceQuery } from "./mappings/process-returns.mapper";
 const parseXml = promisify(parseString);
 export class PointOfSaleModule {
     axiosInstance;
@@ -81,6 +82,38 @@ export class PointOfSaleModule {
         const parsedJson = await parseXml(fullXml);
         return Utils.objectToXml(parsedJson);
     }
+    async mapReturnPayloadToXml(params, sessionId) {
+        const soapNamespace = "S";
+        // Extract method name and construct corresponding properties for the body of the SOAP request and the response from the API
+        const bodyMethodName = "ProcessReturnsRequest";
+        let body = {
+            mode: params?.mode,
+            audit_no: params?.auditNo,
+            export_no: params?.exportNo,
+            header: mapProcessReturnsQueryHeaders(params?.header),
+            extra: params?.extra ? mapProcessReturnsQueryExtra(params.extra) : "",
+            stock: params?.stock?.map(mapProcessReturnsQueryStock),
+            invoice: mapReturnsInvoiceQuery(params),
+            debtor: (params?.debtor ?? []).map(mapProcessSaleOrderQueryDebtor)
+        };
+        const soapBodyJson = {};
+        soapBodyJson[`${ServiceAlias.POINT_OF_SALE}:${bodyMethodName}`] =
+            body;
+        const soapBody = Utils.objectToXml(soapBodyJson);
+        const soapHeader = `
+				<${ServiceAlias.POINT_OF_SALE}:SessionId>${sessionId}</${ServiceAlias.POINT_OF_SALE}:SessionId>
+			`;
+        const fullXml = `
+				<${soapNamespace}:Envelope xmlns:${soapNamespace}="http://schemas.xmlsoap.org/soap/envelope/" xmlns:${ServiceAlias.POINT_OF_SALE}="http://${ServiceAlias.POINT_OF_SALE}.ws.fbsaust.com.au">
+					<${soapNamespace}:Header>${soapHeader}</${soapNamespace}:Header>
+					<${soapNamespace}:Body>
+						${soapBody}
+					</${soapNamespace}:Body>
+				</${soapNamespace}:Envelope>
+			`;
+        const parsedJson = await parseXml(fullXml);
+        return Utils.objectToXml(parsedJson);
+    }
     /**
      * Function to call the ProcessSalesOrderWithoutPayment endpoint in Harmony Point Of Sale service
      *
@@ -119,13 +152,19 @@ export class PointOfSaleModule {
      * Function to call the ProcessReturns endpoint in Harmony Point Of Sale service
      *
      * @async
-     * @param {ProcessSaleOrderQueryParams} params
+     * @param {ProcessReturnsQueryParams} params
      * @param {string} sessionId
      * @returns {Promise<boolean>}
      */
     async processReturns(params, sessionId) {
-        // TODO: add implementation
-        return true;
+        try {
+            const requestBody = mapProcessReturnsQueryParams(params);
+            const response = await ApiHelper.sendServiceRequest(this.SERVICE_URL, ["ProcessReturns", "Request"], sessionId, ServiceAlias.POINT_OF_SALE, this.axiosInstance, requestBody);
+            return Boolean(response?.result[0] ?? "false");
+        }
+        catch (error) {
+            throw await ApiHelper.parseError(error);
+        }
     }
     /**
      * Function to call the ModifyExistingSalesOrder endpoint in Harmony Point Of Sale service

package/dist/modules/point-of-sale/types/process-returns.interface.d.ts

@@ -14,4 +14,6 @@ export interface ProcessReturnsQueryStock extends PosQueryStock {
 }
 export type ProcessReturnsQueryExtra = PosQueryExtra;
 export type ProcessReturnsQueryInvoice = PosQueryInvoice;
-export type ProcessReturnsQueryDebtor = PosQueryDebtor;
+export type ProcessReturnsQueryDebtor = Omit<PosQueryDebtor, "creditReference" | "reservationHistoryNo"> & {
+    cashDrawerId: string;
+};

package/dist/types/index.d.ts

@@ -4,3 +4,6 @@ export * from "../modules/carrier/types";
 export * from "../modules/point-of-sale/types";
 export * from "../modules/stock-level-lookup/types";
 export * from "../modules/stock-lookup/types";
+export type RequestConfig = {
+    headers?: Record<string, string>;
+};

package/dist/types/index.js

@@ -3,4 +3,3 @@ export * from "../modules/carrier/types";
 export * from "../modules/point-of-sale/types";
 export * from "../modules/stock-level-lookup/types";
 export * from "../modules/stock-lookup/types";
-// other types could be added here

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dotdev/harmony-sdk",
-  "version": "1.18.1",
+  "version": "1.20.0",
   "description": "Harmony API SDK",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -19,6 +19,7 @@
   "dependencies": {
     "axios": "^1.7.2",
     "axios-retry": "^4.5.0",
+    "pino": "^9.7.0",
     "xml2js": "0.6.2"
   },
   "devDependencies": {