@shopfront/bridge 1.20.5 → 2.0.0

package/.idea/{shopfront-embedded-bridge.iml → embedded-bridge.iml}

@@ -1,7 +1,9 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <module type="WEB_MODULE" version="4">
   <component name="NewModuleRootManager">
-    <content url="file://$MODULE_DIR$" />
+    <content url="file://$MODULE_DIR$">
+      <excludeFolder url="file://$MODULE_DIR$/lib" />
+    </content>
     <orderEntry type="inheritedJdk" />
     <orderEntry type="sourceFolder" forTests="false" />
   </component>

package/.idea/misc.xml

@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="TaskProjectConfiguration">
+    <server type="JIRA" url="https://onshopfront.atlassian.net" />
+  </component>
+</project>

package/.idea/modules.xml

@@ -2,7 +2,7 @@
 <project version="4">
   <component name="ProjectModuleManager">
     <modules>
-      <module fileurl="file://$PROJECT_DIR$/.idea/shopfront-embedded-bridge.iml" filepath="$PROJECT_DIR$/.idea/shopfront-embedded-bridge.iml" />
+      <module fileurl="file://$PROJECT_DIR$/.idea/embedded-bridge.iml" filepath="$PROJECT_DIR$/.idea/embedded-bridge.iml" />
     </modules>
   </component>
 </project>

package/.idea/php.xml

@@ -7,7 +7,6 @@
     <option name="transferred" value="true" />
   </component>
   <component name="PHPCodeSnifferOptionsConfiguration">
-    <option name="highlightLevel" value="WARNING" />
     <option name="transferred" value="true" />
   </component>
   <component name="PhpStanOptionsConfiguration">

package/.idea/vcs.xml

@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <project version="4">
   <component name="VcsDirectoryMappings">
-    <mapping directory="" vcs="Git" />
+    <mapping directory="$PROJECT_DIR$" vcs="Git" />
   </component>
 </project>

package/eslint.config.js

@@ -0,0 +1,16 @@
+import { coreLintingRules } from "@onshopfront/core/linting";
+
+export default [
+    ...coreLintingRules({}),
+    {
+        ignores: [
+            "lib/**",
+            "tests/**",
+            "**/*.js",
+        ],
+    }, {
+        rules: {
+            "@typescript-eslint/no-useless-constructor": 0
+        }
+    }
+]

package/jest.config.js

@@ -0,0 +1,8 @@
+import { createTsESMConfig } from "@onshopfront/core/tests/config";
+
+export default {
+    ...createTsESMConfig("./tsconfig.json"),
+    setupFilesAfterEnv: ["<rootDir>/tests/setup.ts"],
+    verbose: true,
+    resolver: "ts-jest-resolver",
+};

package/lib/APIs/CurrentSale/Exceptions.d.ts

@@ -0,0 +1,6 @@
+export declare class SaleCancelledError extends Error {
+    constructor();
+}
+export declare class InvalidSaleDeviceError extends Error {
+    constructor();
+}

package/lib/APIs/CurrentSale/Exceptions.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InvalidSaleDeviceError = exports.SaleCancelledError = void 0;
+class SaleCancelledError extends Error {
+    constructor() {
+        super("The sale is no longer active.");
+    }
+}
+exports.SaleCancelledError = SaleCancelledError;
+class InvalidSaleDeviceError extends Error {
+    constructor() {
+        super("This device is no longer a register able to perform a sale.");
+    }
+}
+exports.InvalidSaleDeviceError = InvalidSaleDeviceError;

package/lib/APIs/CurrentSale/Sale.d.ts

@@ -0,0 +1,182 @@
+import { Application } from "../../Application";
+import { ShopfrontSaleState } from "./ShopfrontSaleState";
+import { SaleUpdate, SaleUpdateChanges } from "../../Actions/SaleUpdate";
+import { SaleProduct } from "./SaleProduct";
+import { SalePayment } from "./SalePayment";
+import { SaleCustomer } from "./SaleCustomer";
+export declare class Sale {
+    protected application: Application;
+    protected sale: ShopfrontSaleState;
+    protected cancelled: boolean;
+    /**
+     * Create a sale from a sale state.
+     * It's highly recommend to not construct a sale manually, instead use application.getCurrentSale().
+     *
+     * @param {Application} application
+     * @param {ShopfrontSaleState} sale
+     */
+    constructor(application: Application, sale: ShopfrontSaleState);
+    /**
+     * Get the raw state of the sale, it is highly recommend that you DO NOT use this method as the
+     * returned data may be quite volatile.
+     *
+     * @internal
+     * @returns {ShopfrontSaleState}
+     */
+    getRawState(): ShopfrontSaleState;
+    /**
+     * Update the sale to be the latest sale that exists on the sell screen.
+     *
+     * @returns {Promise<void>}
+     */
+    refreshSale(): Promise<void>;
+    /**
+     * Check if the sale has already been cancelled, if it has, throw a SaleCancelledError.
+     *
+     * @protected
+     */
+    protected checkIfCancelled(): void;
+    /**
+     * Send a sale update to Shopfront.
+     *
+     * @protected
+     * @param {SaleUpdate} update
+     * @returns {Promise<void>}
+     */
+    protected sendSaleUpdate(update: SaleUpdate<keyof SaleUpdateChanges>): Promise<void>;
+    /**
+     * Get the products that are currently on the sale.
+     *
+     * @returns {Array<SaleProduct>}
+     */
+    getProducts(): Array<SaleProduct>;
+    /**
+     * Get the payments that are currently on the sale.
+     *
+     * @returns {Array<SalePayment>}
+     */
+    getPayments(): Array<SalePayment>;
+    /**
+     * Get the current customer on the sale.
+     *
+     * @returns {SaleCustomer | null}
+     */
+    getCustomer(): null | SaleCustomer;
+    /**
+     * Get the external sale note (visible to the customer).
+     *
+     * @returns {string}
+     */
+    getExternalNote(): string;
+    /**
+     * Get the internal sale note.
+     *
+     * @returns {string}
+     */
+    getInternalNote(): string;
+    /**
+     * Get the order reference (visible to the customer).
+     *
+     * @returns {string}
+     */
+    getOrderReference(): string;
+    /**
+     * Get the current meta data for the sale
+     *
+     * @returns {Record<string, unknown>}
+     */
+    getMetaData(): Record<string, unknown>;
+    /**
+     * Cancel the current sale in progress.
+     *
+     * @returns {Promise<void>}
+     */
+    cancelSale(): Promise<void>;
+    /**
+     * Add a product to the sale.
+     *
+     * @param {SaleProduct} product
+     * @returns {Promise<void>}
+     */
+    addProduct(product: SaleProduct): Promise<void>;
+    /**
+     * Remove a product from the sale.
+     * It's highly recommended that you pass in a product that has been retrieved using sale.getProducts().
+     *
+     * @param {SaleProduct} product
+     * @returns {Promise<void>}
+     */
+    removeProduct(product: SaleProduct): Promise<void>;
+    /**
+     * Add a payment to the sell screen.
+     *
+     * If you specify a payment with a status, it will bypass the payment gateway (i.e. it won't request that the
+     * user takes money from the customer).
+     *
+     * If you don't specify a cashout amount, it will automatically determine if the payment method normally requests
+     * cashout (from the payment method settings).
+     *
+     * @param {SalePayment} payment
+     * @returns {Promise<void>}
+     */
+    addPayment(payment: SalePayment): Promise<void>;
+    /**
+     * Reverse a payment on the sell screen.
+     *
+     * This is used to issue a refund to the customer. The sale payment amount should be positive.
+     *
+     * @param {SalePayment} payment
+     * @returns {Promise<void>}
+     */
+    reversePayment(payment: SalePayment): Promise<void>;
+    /**
+     * Add a customer to the sale.
+     * If there is already a customer on the sale this will override that customer.
+     *
+     * @param {SaleCustomer} customer
+     * @returns {Promise<void>}
+     */
+    addCustomer(customer: SaleCustomer): Promise<void>;
+    /**
+     * Remove the customer from the current sale.
+     * If there is no customer currently on the sale this will be ignored.
+     * If there are "on account" or loyalty payments still on the sale, this will be ignored.
+     *
+     * @returns {Promise<void>}
+     */
+    removeCustomer(): Promise<void>;
+    /**
+     * Set the external note for the sale.
+     *
+     * @param {string} note The note to set.
+     * @param {boolean} append Whether to append the note to the current sale note.
+     * @returns {Promise<void>}
+     */
+    setExternalNote(note: string, append?: boolean): Promise<void>;
+    /**
+     * Set the internal note for the sale.
+     *
+     * @param {string} note The note to set.
+     * @param {boolean} append Whether to append the note to the current sale note.
+     * @returns {Promise<void>}
+     */
+    setInternalNote(note: string, append?: boolean): Promise<void>;
+    /**
+     * Set the order reference to the provided string.
+     *
+     * @param {string} reference
+     * @returns {Promise<void>}
+     */
+    setOrderReference(reference: string): Promise<void>;
+    /**
+     * Set the meta data of the sale, this will override the previous meta data.
+     *
+     * @param metaData
+     */
+    setMetaData(metaData: Record<string, unknown>): Promise<void>;
+    /**
+     * Update a product's details, currently this only updates the top-level meta data
+     * @param product
+     */
+    updateProduct(product: SaleProduct): Promise<void>;
+}

package/lib/APIs/CurrentSale/Sale.js

@@ -0,0 +1,290 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Sale = void 0;
+const SaleUpdate_1 = require("../../Actions/SaleUpdate");
+const SaleProduct_1 = require("./SaleProduct");
+const SalePayment_1 = require("./SalePayment");
+const SaleCustomer_1 = require("./SaleCustomer");
+const Exceptions_1 = require("./Exceptions");
+class Sale {
+    /**
+     * Create a sale from a sale state.
+     * It's highly recommend to not construct a sale manually, instead use application.getCurrentSale().
+     *
+     * @param {Application} application
+     * @param {ShopfrontSaleState} sale
+     */
+    constructor(application, sale) {
+        this.application = application;
+        this.sale = sale;
+        this.cancelled = false;
+    }
+    /**
+     * Get the raw state of the sale, it is highly recommend that you DO NOT use this method as the
+     * returned data may be quite volatile.
+     *
+     * @internal
+     * @returns {ShopfrontSaleState}
+     */
+    getRawState() {
+        return this.sale;
+    }
+    /**
+     * Update the sale to be the latest sale that exists on the sell screen.
+     *
+     * @returns {Promise<void>}
+     */
+    async refreshSale() {
+        this.checkIfCancelled();
+        const newSale = await this.application.getCurrentSale();
+        if (newSale === false) {
+            throw new Exceptions_1.InvalidSaleDeviceError();
+        }
+        this.sale = newSale.getRawState();
+    }
+    /**
+     * Check if the sale has already been cancelled, if it has, throw a SaleCancelledError.
+     *
+     * @protected
+     */
+    checkIfCancelled() {
+        if (this.cancelled) {
+            throw new Exceptions_1.SaleCancelledError();
+        }
+    }
+    /**
+     * Send a sale update to Shopfront.
+     *
+     * @protected
+     * @param {SaleUpdate} update
+     * @returns {Promise<void>}
+     */
+    sendSaleUpdate(update) {
+        this.checkIfCancelled();
+        this.application.send(update);
+        return this.refreshSale();
+    }
+    /**
+     * Get the products that are currently on the sale.
+     *
+     * @returns {Array<SaleProduct>}
+     */
+    getProducts() {
+        const products = [];
+        for (let i = 0, l = this.sale.products.length; i < l; i++) {
+            // The hydration method loops through child products so we don't have to
+            // worry about that here.
+            products.push(SaleProduct_1.SaleProduct.HydrateFromState(this.sale.products[i], [i]));
+        }
+        return products;
+    }
+    /**
+     * Get the payments that are currently on the sale.
+     *
+     * @returns {Array<SalePayment>}
+     */
+    getPayments() {
+        const payments = [];
+        for (let i = 0, l = this.sale.payments.length; i < l; i++) {
+            payments.push(SalePayment_1.SalePayment.HydrateFromState(this.sale.payments[i]));
+        }
+        return payments;
+    }
+    /**
+     * Get the current customer on the sale.
+     *
+     * @returns {SaleCustomer | null}
+     */
+    getCustomer() {
+        if (this.sale.customer === false) {
+            return null;
+        }
+        return new SaleCustomer_1.SaleCustomer(this.sale.customer.uuid);
+    }
+    /**
+     * Get the external sale note (visible to the customer).
+     *
+     * @returns {string}
+     */
+    getExternalNote() {
+        return this.sale.notes.sale;
+    }
+    /**
+     * Get the internal sale note.
+     *
+     * @returns {string}
+     */
+    getInternalNote() {
+        return this.sale.notes.internal;
+    }
+    /**
+     * Get the order reference (visible to the customer).
+     *
+     * @returns {string}
+     */
+    getOrderReference() {
+        return this.sale.orderReference;
+    }
+    /**
+     * Get the current meta data for the sale
+     *
+     * @returns {Record<string, unknown>}
+     */
+    getMetaData() {
+        return this.sale.metaData;
+    }
+    /**
+     * Cancel the current sale in progress.
+     *
+     * @returns {Promise<void>}
+     */
+    async cancelSale() {
+        await this.sendSaleUpdate(new SaleUpdate_1.SaleUpdate("SALE_CANCEL", {}));
+        this.cancelled = true;
+    }
+    /**
+     * Add a product to the sale.
+     *
+     * @param {SaleProduct} product
+     * @returns {Promise<void>}
+     */
+    addProduct(product) {
+        return this.sendSaleUpdate(new SaleUpdate_1.SaleUpdate("PRODUCT_ADD", {
+            id: product.getId(),
+            quantity: product.getQuantity(),
+            price: product.getPrice(),
+            indexAddress: product.getIndexAddress(),
+            metaData: product.getMetaData(),
+        }));
+    }
+    /**
+     * Remove a product from the sale.
+     * It's highly recommended that you pass in a product that has been retrieved using sale.getProducts().
+     *
+     * @param {SaleProduct} product
+     * @returns {Promise<void>}
+     */
+    removeProduct(product) {
+        return this.sendSaleUpdate(new SaleUpdate_1.SaleUpdate("PRODUCT_REMOVE", {
+            id: product.getId(),
+            indexAddress: product.getIndexAddress(),
+        }));
+    }
+    /**
+     * Add a payment to the sell screen.
+     *
+     * If you specify a payment with a status, it will bypass the payment gateway (i.e. it won't request that the
+     * user takes money from the customer).
+     *
+     * If you don't specify a cashout amount, it will automatically determine if the payment method normally requests
+     * cashout (from the payment method settings).
+     *
+     * @param {SalePayment} payment
+     * @returns {Promise<void>}
+     */
+    addPayment(payment) {
+        return this.sendSaleUpdate(new SaleUpdate_1.SaleUpdate("PAYMENT_ADD", {
+            id: payment.getId(),
+            amount: payment.getAmount(),
+            cashout: payment.getCashout(),
+            status: payment.getStatus(),
+        }));
+    }
+    /**
+     * Reverse a payment on the sell screen.
+     *
+     * This is used to issue a refund to the customer. The sale payment amount should be positive.
+     *
+     * @param {SalePayment} payment
+     * @returns {Promise<void>}
+     */
+    reversePayment(payment) {
+        return this.sendSaleUpdate(new SaleUpdate_1.SaleUpdate("PAYMENT_REVERSE", {
+            id: payment.getId(),
+            amount: payment.getAmount(),
+            cashout: payment.getCashout(),
+            status: payment.getStatus(),
+        }));
+    }
+    /**
+     * Add a customer to the sale.
+     * If there is already a customer on the sale this will override that customer.
+     *
+     * @param {SaleCustomer} customer
+     * @returns {Promise<void>}
+     */
+    addCustomer(customer) {
+        return this.sendSaleUpdate(new SaleUpdate_1.SaleUpdate("CUSTOMER_ADD", {
+            id: customer.getId(),
+        }));
+    }
+    /**
+     * Remove the customer from the current sale.
+     * If there is no customer currently on the sale this will be ignored.
+     * If there are "on account" or loyalty payments still on the sale, this will be ignored.
+     *
+     * @returns {Promise<void>}
+     */
+    removeCustomer() {
+        return this.sendSaleUpdate(new SaleUpdate_1.SaleUpdate("CUSTOMER_REMOVE", {}));
+    }
+    /**
+     * Set the external note for the sale.
+     *
+     * @param {string} note The note to set.
+     * @param {boolean} append Whether to append the note to the current sale note.
+     * @returns {Promise<void>}
+     */
+    setExternalNote(note, append = false) {
+        return this.sendSaleUpdate(new SaleUpdate_1.SaleUpdate("SALE_EXTERNAL_NOTE", {
+            note,
+            append,
+        }));
+    }
+    /**
+     * Set the internal note for the sale.
+     *
+     * @param {string} note The note to set.
+     * @param {boolean} append Whether to append the note to the current sale note.
+     * @returns {Promise<void>}
+     */
+    setInternalNote(note, append = false) {
+        return this.sendSaleUpdate(new SaleUpdate_1.SaleUpdate("SALE_INTERNAL_NOTE", {
+            note,
+            append,
+        }));
+    }
+    /**
+     * Set the order reference to the provided string.
+     *
+     * @param {string} reference
+     * @returns {Promise<void>}
+     */
+    setOrderReference(reference) {
+        return this.sendSaleUpdate(new SaleUpdate_1.SaleUpdate("SALE_ORDER_REFERENCE", {
+            reference,
+        }));
+    }
+    /**
+     * Set the meta data of the sale, this will override the previous meta data.
+     *
+     * @param metaData
+     */
+    setMetaData(metaData) {
+        return this.sendSaleUpdate(new SaleUpdate_1.SaleUpdate("SALE_META_DATA", {
+            metaData,
+        }));
+    }
+    /**
+     * Update a product's details, currently this only updates the top-level meta data
+     * @param product
+     */
+    updateProduct(product) {
+        return this.sendSaleUpdate(new SaleUpdate_1.SaleUpdate("PRODUCT_UPDATE", {
+            id: product.getId(),
+            indexAddress: product.getIndexAddress(),
+            metaData: product.getMetaData(),
+        }));
+    }
+}
+exports.Sale = Sale;

package/lib/APIs/CurrentSale/SaleCustomer.d.ts

@@ -0,0 +1,10 @@
+export declare class SaleCustomer {
+    protected id: string;
+    constructor(id: string);
+    /**
+     * Get the ID of the customer.
+     *
+     * @returns {string}
+     */
+    getId(): string;
+}

package/lib/APIs/CurrentSale/SaleCustomer.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SaleCustomer = void 0;
+class SaleCustomer {
+    constructor(id) {
+        this.id = id;
+    }
+    /**
+     * Get the ID of the customer.
+     *
+     * @returns {string}
+     */
+    getId() {
+        return this.id;
+    }
+}
+exports.SaleCustomer = SaleCustomer;

package/lib/APIs/CurrentSale/SalePayment.d.ts

@@ -0,0 +1,68 @@
+import { ShopfrontSalePayment } from "./ShopfrontSaleState";
+export declare enum SalePaymentStatus {
+    APPROVED = "completed",
+    DECLINED = "failed",
+    CANCELLED = "cancelled"
+}
+export declare class SalePayment {
+    protected id: string;
+    protected type?: string;
+    protected status?: SalePaymentStatus;
+    protected amount: number;
+    protected cashout?: number;
+    protected rounding?: number;
+    constructor(id: string, amount: number, cashout?: number, status?: SalePaymentStatus);
+    /**
+     * Hydrate a sale payment from the SaleState.
+     *
+     * @internal
+     * @param {ShopfrontSalePayment} payment
+     * @returns {SalePayment}
+     * @constructor
+     */
+    static HydrateFromState(payment: ShopfrontSalePayment): SalePayment;
+    /**
+     * Set the internal data for the payment.
+     * This method is for hydration of the payment from Shopfront, it's highly recommend that you DO NOT use this method.
+     *
+     * @internal
+     * @param {ShopfrontSalePayment} data
+     */
+    setInternal(data: ShopfrontSalePayment): void;
+    /**
+     * Get the ID of the sale payment method.
+     *
+     * @returns {string}
+     */
+    getId(): string;
+    /**
+     * Get the type of payment method this is.
+     *
+     * @returns {string | undefined}
+     */
+    getType(): string | undefined;
+    /**
+     * Get the status of this payment method.
+     *
+     * @returns {SalePaymentStatus | undefined}
+     */
+    getStatus(): SalePaymentStatus | undefined;
+    /**
+     * Get the value of this payment method.
+     *
+     * @returns {number}
+     */
+    getAmount(): number;
+    /**
+     * Get the cashout amount paid for on this payment method.
+     *
+     * @returns {number | undefined}
+     */
+    getCashout(): number | undefined;
+    /**
+     * Get the amount of rounding applied to this payment method.
+     *
+     * @returns {number | undefined}
+     */
+    getRounding(): number | undefined;
+}