@dotdev/harmony-sdk 1.0.1

package/README.md

@@ -0,0 +1,132 @@
+# Harmony SDK
+
+Harmony SDK is a TypeScript library for interacting with the Harmony API. It provides a set of modules to perform various operations such as authentication, stock lookup, stock level lookup, point of sale operations, carrier management, diary management, and gift voucher handling.
+
+## Table of Contents
+
+- [Installation](#installation)
+- [Usage](#usage)
+- [Development](#development)
+- [Implemented Endpoints](#implemented-endpoints)
+
+## Installation
+
+To install the Harmony SDK, use the following command:
+
+```bash
+npm install @dotapparel/harmony-sdk
+```
+
+or if you're using pnpm:
+
+```bash
+pnpm add @dotapparel/harmony-sdk
+```
+
+## Usage
+
+Here's a basic example of how to use the Harmony SDK:
+
+```typescript
+import { HarmonyAPI, AuthenticationToken } from '@dotapparel/harmony-sdk';
+
+const api = new HarmonyAPI('https://your-harmony-api-url.com');
+
+async function main() {
+  const authToken: AuthenticationToken = {
+    // Fill in your authentication details
+  };
+
+  try {
+    const sessionId = await api.authenticate(authToken);
+    console.log('Authenticated successfully. Session ID:', sessionId);
+
+    // Example: Perform a stock lookup
+    const stockLookupParams = {
+      // Fill in your stock lookup parameters
+    };
+    const stockResults = await api.stockLookup(stockLookupParams, sessionId);
+    console.log('Stock lookup results:', stockResults);
+
+    // Use other methods as needed...
+
+  } catch (error) {
+    console.error('Error:', error);
+  }
+}
+
+main();
+```
+
+## Development
+
+To set up the development environment:
+
+1. Clone the repository:
+   ```bash
+   git clone https://github.com/your-repo/harmony-sdk.git
+   cd harmony-sdk
+   ```
+
+2. Install dependencies:
+   ```bash
+   pnpm install
+   ```
+
+3. Build the project:
+   ```bash
+   pnpm run build
+   ```
+
+4. Run tests:
+   ```bash
+   pnpm test
+   ```
+
+5. To watch for changes during development:
+   ```bash
+   pnpm run watch
+   ```
+
+## Implemented Endpoints
+
+The Harmony SDK implements the following endpoints:
+
+1. Authentication
+    - `authenticate(authToken: AuthenticationToken): Promise<string>`
+
+2. Stock Lookup Module
+    - `stockLookup(params: StockLookupRequestParams, sessionId: string): Promise<Stock[]>`
+    - `stockCategoryLookup(sessionId: string): Promise<StockCategory[]>`
+    - `stockBarcodeLookup(params: StockLookupRequestParams, sessionId: string): Promise<StockBarcode[]>`
+    - `stockColorLookup(sessionId: string): Promise<StockColor[]>`
+    - `sizeGridLookup(sessionId: string): Promise<SizeGrid[]>`
+    - `stockClassificationLookup(sessionId: string, searchType?: StockClassificationType): Promise<StockClassification[]>`
+
+3. Stock Level Lookup Module
+    - `warehouseLookup(sessionId: string): Promise<Warehouse[]>`
+    - `stockLevelLookup(params: StockLevelLookupQueryParams, sessionId: string): Promise<StockLevel[]>`
+    - `stockLevelLookupByWarehouseQuickView(params: StockLevelLookupQueryParams, sessionId: string): Promise<StockLevel[]>`
+
+4. Point of Sale Module
+    - `processSalesOrder(params: ProcessSaleOrderQueryParams, sessionId: string): Promise<boolean>`
+    - `processReturns(params: ProcessSaleOrderQueryParams, sessionId: string): Promise<boolean>`
+    - `modifyExistingSalesOrder(params: ProcessSaleOrderQueryParams, sessionId: string): Promise<boolean>`
+    - `cancelExistingSalesOrder(params: ProcessSaleOrderQueryParams, sessionId: string): Promise<boolean>`
+
+5. Carrier Module
+    - `getCarrier(sessionId: string): Promise<Carrier[]>`
+    - `getCarrierShipmentByOrderNo(orderNo: string, sessionId: string): Promise<CarrierShipment[]>`
+    - `getCarrierBySysTime(params: GetCarrierShipmentByTimeQueryParams, sessionId: string): Promise<CarrierShipment[]>`
+
+6. Diary Module
+    - `getDiaryBy(params: GetDiaryQueryParams, sessionId: string): Promise<Diary[]>`
+    - `createDiary(params: CreateDiaryQueryParams, sessionId: string): Promise<boolean>`
+
+7. Gift Voucher Module
+    - `giftVoucherLookup(params: GiftVoucherLookupQueryParams, sessionId: string): Promise<GiftVoucher[]>`
+    - `giftVoucherVerificationKey(params: GiftVoucherVerificationKeyQueryParams, sessionId: string): Promise<string>`
+    - `giftVoucherReservation(params: GiftVoucherReservationQueryParams, sessionId: string): Promise<string>`
+    - `giftVoucherUsed(params: GiftVoucherUsedQueryParams, sessionId: string): Promise<number>`
+
+For detailed information on each endpoint and its parameters, please refer to the source code and type definitions.

package/dist/HarmonyAPI.d.ts

@@ -0,0 +1,37 @@
+import { AuthenticationToken, Carrier, CarrierShipment, CreateDiaryQueryParams, Diary, GetCarrierShipmentByTimeQueryParams, GetDiaryQueryParams, ProcessSaleOrderQueryParams, SizeGrid, Stock, StockBarcode, StockCategory, StockClassification, StockClassificationType, StockColor, StockLevel, StockLevelLookupQueryParams, StockLookupRequestParams, Warehouse } from "./modules";
+import { GiftVoucher, GiftVoucherLookupQueryParams, GiftVoucherReservationQueryParams, GiftVoucherUsedQueryParams, GiftVoucherVerificationKeyQueryParams } from "./modules/gift-voucher/types";
+export declare class HarmonyAPI {
+    private baseUrl;
+    private axiosInstance;
+    private authModule;
+    private stockLookupModule;
+    private stockLevelLookupModule;
+    private pointOfSaleModule;
+    private carrierModule;
+    private diaryModule;
+    private giftVoucherModule;
+    constructor(url: string);
+    authenticate(authToken: AuthenticationToken): Promise<string>;
+    stockLookup(params: StockLookupRequestParams, sessionId: string): Promise<Stock[]>;
+    stockCategoryLookup(sessionId: string): Promise<StockCategory[]>;
+    stockBarcodeLookup(params: StockLookupRequestParams, sessionId: string): Promise<StockBarcode[]>;
+    stockColorLookup(sessionId: string): Promise<StockColor[]>;
+    sizeGridLookup(sessionId: string): Promise<SizeGrid[]>;
+    stockClassificationLookup(sessionId: string, searchType?: StockClassificationType): Promise<StockClassification[]>;
+    warehouseLookup(sessionId: string): Promise<Warehouse[]>;
+    stockLevelLookup(params: StockLevelLookupQueryParams, sessionId: string): Promise<StockLevel[]>;
+    stockLevelLookupByWarehouseQuickView(params: StockLevelLookupQueryParams, sessionId: string): Promise<StockLevel[]>;
+    processSalesOrder(params: ProcessSaleOrderQueryParams, sessionId: string): Promise<boolean>;
+    processReturns(params: ProcessSaleOrderQueryParams, sessionId: string): Promise<boolean>;
+    modifyExistingSalesOrder(params: ProcessSaleOrderQueryParams, sessionId: string): Promise<boolean>;
+    cancelExistingSalesOrder(params: ProcessSaleOrderQueryParams, sessionId: string): Promise<boolean>;
+    getCarrier(sessionId: string): Promise<Carrier[]>;
+    getCarrierShipmentByOrderNo(orderNo: string, sessionId: string): Promise<CarrierShipment[]>;
+    getCarrierBySysTime(params: GetCarrierShipmentByTimeQueryParams, sessionId: string): Promise<CarrierShipment[]>;
+    getDiaryBy(params: GetDiaryQueryParams, sessionId: string): Promise<Diary[]>;
+    createDiary(params: CreateDiaryQueryParams, sessionId: string): Promise<boolean>;
+    giftVoucherLookup(params: GiftVoucherLookupQueryParams, sessionId: string): Promise<GiftVoucher[]>;
+    giftVoucherVerificationKey(params: GiftVoucherVerificationKeyQueryParams, sessionId: string): Promise<string>;
+    giftVoucherReservation(params: GiftVoucherReservationQueryParams, sessionId: string): Promise<string>;
+    giftVoucherUsed(params: GiftVoucherUsedQueryParams, sessionId: string): Promise<number>;
+}

package/dist/HarmonyAPI.js

@@ -0,0 +1,113 @@
+import axios from "axios";
+import * as https from "https";
+import { promisify } from "util";
+import { parseString } from "xml2js";
+import { AuthModule, CarrierModule, DiaryModule, GiftVoucherModule, PointOfSaleModule, StockClassificationType, StockLevelLookupModule, StockLookupModule, } from "./modules";
+require("tls").DEFAULT_MIN_VERSION = "TLSv1";
+const parseXml = promisify(parseString);
+export class HarmonyAPI {
+    baseUrl;
+    axiosInstance;
+    authModule;
+    stockLookupModule;
+    stockLevelLookupModule;
+    pointOfSaleModule;
+    carrierModule;
+    diaryModule;
+    giftVoucherModule;
+    constructor(url) {
+        this.baseUrl = url;
+        this.axiosInstance = axios.create({
+            baseURL: this.baseUrl,
+            headers: {
+                "Content-Type": "text/xml;charset=UTF-8",
+            },
+            httpsAgent: new https.Agent({
+                rejectUnauthorized: false,
+            }),
+        });
+        // Initialise modules that correspond to Harmony API services
+        this.authModule = new AuthModule(this.axiosInstance);
+        this.stockLookupModule = new StockLookupModule(this.axiosInstance);
+        this.stockLevelLookupModule = new StockLevelLookupModule(this.axiosInstance);
+        this.pointOfSaleModule = new PointOfSaleModule(this.axiosInstance);
+        this.carrierModule = new CarrierModule(this.axiosInstance);
+        this.diaryModule = new DiaryModule(this.axiosInstance);
+        this.giftVoucherModule = new GiftVoucherModule(this.axiosInstance);
+    }
+    async authenticate(authToken) {
+        return await this.authModule.authenticate(authToken);
+    }
+    // Stock lookup module
+    async stockLookup(params, sessionId) {
+        return await this.stockLookupModule.stockLookup(params, sessionId);
+    }
+    async stockCategoryLookup(sessionId) {
+        return await this.stockLookupModule.stockCategoryLookup(sessionId);
+    }
+    async stockBarcodeLookup(params, sessionId) {
+        return await this.stockLookupModule.stockBarcodeLookup(params, sessionId);
+    }
+    async stockColorLookup(sessionId) {
+        return await this.stockLookupModule.stockColorLookup(sessionId);
+    }
+    async sizeGridLookup(sessionId) {
+        return await this.stockLookupModule.sizeGridLookup(sessionId);
+    }
+    async stockClassificationLookup(sessionId, searchType = StockClassificationType.STK1) {
+        return await this.stockLookupModule.stockClassificationLookup(sessionId, searchType);
+    }
+    // Stock level lookup module
+    async warehouseLookup(sessionId) {
+        return await this.stockLevelLookupModule.warehouseLookup(sessionId);
+    }
+    async stockLevelLookup(params, sessionId) {
+        return await this.stockLevelLookupModule.stockLevelLookup(params, sessionId);
+    }
+    async stockLevelLookupByWarehouseQuickView(params, sessionId) {
+        return await this.stockLevelLookupModule.stockLevelLookupByWarehouseQuickView(params, sessionId);
+    }
+    // Point of sale module
+    async processSalesOrder(params, sessionId) {
+        return await this.pointOfSaleModule.processSalesOrder(params, sessionId);
+    }
+    async processReturns(params, sessionId) {
+        return await this.pointOfSaleModule.processReturns(params, sessionId);
+    }
+    async modifyExistingSalesOrder(params, sessionId) {
+        return await this.pointOfSaleModule.modifyExistingSalesOrder(params, sessionId);
+    }
+    async cancelExistingSalesOrder(params, sessionId) {
+        return await this.pointOfSaleModule.cancelExistingSalesOrder(params, sessionId);
+    }
+    // Carrier module
+    async getCarrier(sessionId) {
+        return await this.carrierModule.getCarrier(sessionId);
+    }
+    async getCarrierShipmentByOrderNo(orderNo, sessionId) {
+        return await this.carrierModule.getCarrierShipmentByOrderNumber(orderNo, sessionId);
+    }
+    async getCarrierBySysTime(params, sessionId) {
+        return await this.carrierModule.getCarrierShipmentBySysTime(params, sessionId);
+    }
+    // Diary module
+    async getDiaryBy(params, sessionId) {
+        return await this.diaryModule.getDiaryBy(params, sessionId);
+    }
+    async createDiary(params, sessionId) {
+        return await this.diaryModule.createDiary(params, sessionId);
+    }
+    // Gift voucher module
+    async giftVoucherLookup(params, sessionId) {
+        return this.giftVoucherModule.giftVoucherLookup(params, sessionId);
+    }
+    async giftVoucherVerificationKey(params, sessionId) {
+        return this.giftVoucherModule.giftVoucherVerificationKey(params, sessionId);
+    }
+    async giftVoucherReservation(params, sessionId) {
+        return this.giftVoucherModule.giftVoucherVerificationKey(params, sessionId);
+    }
+    async giftVoucherUsed(params, sessionId) {
+        return this.giftVoucherModule.giftVoucherUsed(params, sessionId);
+    }
+}

package/dist/errors/index.d.ts

@@ -0,0 +1,15 @@
+export declare class HarmonyAPIError extends Error {
+    constructor(message: string);
+}
+export declare class AuthenticationError extends HarmonyAPIError {
+    constructor(message: string);
+}
+export declare class RequestError extends HarmonyAPIError {
+    constructor(message: string);
+}
+export interface ApiError {
+    status?: string;
+    code?: string;
+    name?: string;
+    message?: string;
+}

package/dist/errors/index.js

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

package/dist/helpers/index.d.ts

@@ -0,0 +1,50 @@
+import { AxiosInstance } from "axios";
+import { ApiError, RequestError } from "../errors";
+import { ParamLimits, ServiceAlias } from "../modules";
+export * from "./utils";
+export declare abstract class ApiHelper {
+    static sendSoapRequest(endpoint: string, axiosInstance: AxiosInstance, requestBody?: string, type?: "GET" | "POST"): Promise<any>;
+    /**
+     * Helper function to create SOAP request body for Harmony API
+     *
+     * @static
+     * @param {(string | string[])} methodName
+     * @param {string} sessionId
+     * @param {ServiceAlias} serviceAlias
+     * @param {?string} [body]
+     * @returns {string}
+     */
+    static createServiceRequestBody(methodName: string | string[], sessionId: string, serviceAlias: ServiceAlias, body?: string): string;
+    /**
+     * Private method to send SOAP request to different endpoint in Point Of Sale service in Harmony API
+     *
+     * @private
+     * @async
+     * @template R
+     * @param {string} methodName
+     * @param {string} sessionId
+     * @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>;
+    /**
+     * Extract error response from Harmony in XML format and convert it to JSON format for ease of debugging
+     *
+     * @static
+     * @async
+     * @param {*} error XML error string
+     * @returns {Promise<ApiError>} JSON error object
+     */
+    static parseHarmonyErrorResponse(error: any): Promise<ApiError>;
+}
+/**
+ * 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.
+ *
+ * @export
+ * @template T
+ * @param {T} params set of parameters to be checked
+ * @param {ParamLimits<T>} limits limit object with same properties as the parameter object, with value of each key being a number or a function that returns a boolean
+ * @returns {boolean} returns true if all checks passed
+ */
+export declare function checkParamLimits<T>(params: T, limits: ParamLimits<T>): boolean;

package/dist/helpers/index.js

@@ -0,0 +1,167 @@
+import axios from "axios";
+import { promisify } from "util";
+import { parseString } from "xml2js";
+import { RequestError } from "../errors";
+import { Utils } from "./utils";
+export * from "./utils";
+const parseXml = promisify(parseString);
+export class ApiHelper {
+    static async sendSoapRequest(endpoint, axiosInstance, requestBody, type = "POST") {
+        const url = `${endpoint}?wsdl`;
+        try {
+            let response;
+            switch (type) {
+                case "GET":
+                    response = await axiosInstance.get(url, {
+                        params: {},
+                    });
+                    break;
+                case "POST":
+                default:
+                    response = await axiosInstance.post(url, requestBody, {
+                    // headers: {
+                    //   'SOAPAction': request.action
+                    // }
+                    });
+                    break;
+            }
+            const result = (await parseXml(response?.data)); // fix type
+            return result["S:Envelope"]["S:Body"][0];
+        }
+        catch (error) {
+            throw await ApiHelper.parseError(error);
+        }
+    }
+    /**
+     * Helper function to create SOAP request body for Harmony API
+     *
+     * @static
+     * @param {(string | string[])} methodName
+     * @param {string} sessionId
+     * @param {ServiceAlias} serviceAlias
+     * @param {?string} [body]
+     * @returns {string}
+     */
+    static createServiceRequestBody(methodName, sessionId, serviceAlias, body) {
+        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 = Array.isArray(methodName)
+            ? methodName.join("")
+            : methodName;
+        const soapBody = `<${serviceAlias}:${bodyMethodName}>${body ?? ""}</${serviceAlias}:${bodyMethodName}>`;
+        const soapHeader = `
+				<${serviceAlias}:SessionId>${sessionId}</${serviceAlias}:SessionId>
+			`;
+        return `
+				<${soapNamespace}:Envelope xmlns:${soapNamespace}="http://schemas.xmlsoap.org/soap/envelope/" xmlns:${serviceAlias}="http://${serviceAlias}.ws.fbsaust.com.au">
+					<${soapNamespace}:Header>
+						${soapHeader}
+					</${soapNamespace}:Header>
+					<${soapNamespace}:Body>
+						${soapBody}
+					</${soapNamespace}:Body>
+				</${soapNamespace}:Envelope>
+			`;
+    }
+    /**
+     * Private method to send SOAP request to different endpoint in Point Of Sale service in Harmony API
+     *
+     * @private
+     * @async
+     * @template R
+     * @param {string} methodName
+     * @param {string} sessionId
+     * @returns {Promise<R>}
+     */
+    static async sendServiceRequest(serviceName, methodName, sessionId, serviceAlias, axios, body) {
+        // Extract method name and construct corresponding properties for the body of the SOAP request and the response from the API
+        const responseMethodName = Array.isArray(methodName)
+            ? `ns2:${methodName[0]}Response`
+            : `ns2:${methodName}Response`;
+        const requestBody = ApiHelper.createServiceRequestBody(methodName, sessionId, serviceAlias, body);
+        const response = await ApiHelper.sendSoapRequest(serviceName, axios, requestBody);
+        return response[responseMethodName][0];
+    }
+    static async parseError(error) {
+        if (axios.isAxiosError(error)) {
+            if (error?.response) {
+                const parsedError = await ApiHelper.parseHarmonyErrorResponse(error?.response?.data);
+                return new RequestError(`API request failed with status ${error.response.status}: {code: ${parsedError?.code}, name: ${parsedError?.name}, message: ${parsedError?.message}}`);
+            }
+            else if (error?.request) {
+                return new RequestError("No response received from the server during API call");
+            }
+            else {
+                return new RequestError(`API request setup failed: ${error?.message}`);
+            }
+        }
+        else {
+            return new RequestError(`An unexpected error occurred during API request: ${JSON.stringify(error.message)}`);
+        }
+    }
+    /**
+     * Extract error response from Harmony in XML format and convert it to JSON format for ease of debugging
+     *
+     * @static
+     * @async
+     * @param {*} error XML error string
+     * @returns {Promise<ApiError>} JSON error object
+     */
+    static async parseHarmonyErrorResponse(error) {
+        if (error == null)
+            return { code: "", name: "", message: "" };
+        const result = (await parseXml(error));
+        const errorDetails = result["S:Envelope"]["S:Body"][0]["S:Fault"][0];
+        // Extract error response body
+        const code = Utils.nonEmptyArray(errorDetails["faultcode"])
+            ? errorDetails["faultcode"][0]
+            : "";
+        const name = Utils.nonEmptyArray(errorDetails["faultstring"])
+            ? errorDetails["faultstring"][0]
+            : "";
+        // extract error message
+        const detail = errorDetails["detail"];
+        const fault = Utils.nonEmptyArray(detail)
+            ? detail[0]["ns2:ServiceFault"]
+            : [];
+        const message = Utils.nonEmptyArray(fault) ? fault[0]["errorDetails"] : [];
+        return {
+            code,
+            name,
+            message: message[0] ?? "",
+        };
+    }
+}
+/**
+ * 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.
+ *
+ * @export
+ * @template T
+ * @param {T} params set of parameters to be checked
+ * @param {ParamLimits<T>} limits limit object with same properties as the parameter object, with value of each key being a number or a function that returns a boolean
+ * @returns {boolean} returns true if all checks passed
+ */
+export function checkParamLimits(params, limits) {
+    for (const key in params) {
+        const val = params[key];
+        const limit = limits[key];
+        // Only perform checks if both param value and limit are defined
+        if (val && limit) {
+            // If limit type is a number a.k.a length limit, check if provided string value exceeds the length limit
+            if (typeof limit === "number") {
+                const valStr = typeof val === "string" ? val : val.toString();
+                if (valStr.length > limit) {
+                    throw new Error(`Provided value for "${key}" exceeds limit of ${limit}`);
+                }
+                // Otherwise call limit function to determine whether value meets the condition
+            }
+            else {
+                if (!limit(val)) {
+                    throw new Error(`Invalid value for parameter "${key}": ${val}`);
+                }
+            }
+        }
+    }
+    return true;
+}

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

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