@pinelab/vendure-plugin-qls-fulfillment 1.0.1 → 1.1.0

package/CHANGELOG.md

@@ -1,3 +1,9 @@
-# 1.0.0 (2025-11-07) ## CHANGE THIS DATE AND VERSION
+# 1.1.0 (2026-01-07)
+
+- Fix delivery options to be an array of objects with a tag property
+- Emit event for failed order push
+- Delay 10s before setting custom field `syncedToQls` to prevent race conditions.
+
+# 1.0.0 (2025-11-07)
 
 - Initial release

package/README.md

@@ -78,20 +78,30 @@ mutation {
 }
 ```
 
-## Monitoring
+## Monitoring failed orders
 
-Make sure to monitor failed jobs: A job that failed after its retries were exhausted, means:
+Whenever an order fails to be pushed to QLS, an event is emitted. You can listen to this event to monitor failed orders.
 
-1. An order was not pushed to QLS
-2. A product was not synced to QLS
+```ts
+this.eventBus.ofType(QlsOrderFailedEvent).subscribe((event) => {
+  console.log('Order failed to be pushed to QLS:', event.order.code);
+});
+```
 
-Monitor your logs for the following text:
+Because a job can be retried, this event can be emitted multiple times for the same order. You can use the date field together with the order code to determine if you have already processed this event.
 
-- `QLS webhook error` - This means an incoming stock update webhook was not processed correctly.
-- `Error creating or updating variant` - This means a product was not synced to QLS.
+```ts
+this.eventBus.ofType(QlsOrderFailedEvent).subscribe((event) => {
+  // Determine if we have already processed this event.
+  const uniqueEventId = `${event.order.code}_${
+    event.failedAt.toISOString().split('T')[0]
+  }`; // "JHD82JS8868_2026-01-01"
+  console.log('Order failed to be pushed to QLS:', event.order.code);
+});
+```
 
-Make sure to filter by logger context `QlsPlugin`, to prevent false positive alerts.
+## Manually pushing orders to QLS
 
-## Cancelling orders and manually pushing orders to QLS
+This plugin adds a button `push to QLS` to the order detail page in the Admin UI. This will push the order to QLS again. If the order has been pushed before, you need to uncheck the checkbox `synced to QLS` in the order custom fields first.
 
-// TODO: Push will just create a new order in QLS, it will not cancel the existing order in QLS. Cancel existing order first via https://mijn.pakketdienstqls.nl/
+Pushing an order to QLS again will not cancel the existing order in QLS. Cancel existing orders first via https://mijn.pakketdienstqls.nl/.

package/dist/lib/client-types.d.ts

@@ -79,7 +79,9 @@ export interface FulfillmentOrderInput {
     receiver_contact: FulfillmentOrderReceiverContactInput;
     custom_values?: CustomValue[];
     products: FulfillmentOrderLineInput[];
-    delivery_options: string[];
+    delivery_options: {
+        tag: string;
+    }[];
 }
 export interface FulfillmentOrderReceiverContactInput {
     name: string;

package/dist/services/qls-order-failed-event.d.ts

@@ -0,0 +1,35 @@
+import { Order, RequestContext, VendureEvent } from '@vendure/core';
+export declare enum QLSOrderError {
+    INCORRECT_POSTAL_CODE = "INCORRECT_POSTAL_CODE",
+    INCORRECT_HOUSE_NUMBER = "INCORRECT_HOUSE_NUMBER",
+    UNKNOWN_ERROR = "UNKNOWN_ERROR"
+}
+/**
+ * This event is emitted when an order fails to be pushed to QLS.
+ */
+export declare class QlsOrderFailedEvent extends VendureEvent {
+    ctx: RequestContext;
+    order: Order;
+    /**
+     * The date and time the order failed to be pushed to QLS.
+     */
+    failedAt: Date;
+    /**
+     * The full error response JSON from QLS.
+     */
+    fullError: unknown;
+    /**
+     * The error code that caused the order to fail to be pushed to QLS.
+     */
+    errorCode: QLSOrderError;
+    constructor(ctx: RequestContext, order: Order, 
+    /**
+     * The date and time the order failed to be pushed to QLS.
+     */
+    failedAt: Date, 
+    /**
+     * The full error response JSON from QLS.
+     */
+    fullError: unknown);
+}
+export declare function getQLSErrorCode(errorResponse: unknown): QLSOrderError;

package/dist/services/qls-order-failed-event.js

@@ -0,0 +1,44 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.QlsOrderFailedEvent = exports.QLSOrderError = void 0;
+exports.getQLSErrorCode = getQLSErrorCode;
+const core_1 = require("@vendure/core");
+var QLSOrderError;
+(function (QLSOrderError) {
+    QLSOrderError["INCORRECT_POSTAL_CODE"] = "INCORRECT_POSTAL_CODE";
+    QLSOrderError["INCORRECT_HOUSE_NUMBER"] = "INCORRECT_HOUSE_NUMBER";
+    QLSOrderError["UNKNOWN_ERROR"] = "UNKNOWN_ERROR";
+})(QLSOrderError || (exports.QLSOrderError = QLSOrderError = {}));
+/**
+ * This event is emitted when an order fails to be pushed to QLS.
+ */
+class QlsOrderFailedEvent extends core_1.VendureEvent {
+    constructor(ctx, order, 
+    /**
+     * The date and time the order failed to be pushed to QLS.
+     */
+    failedAt, 
+    /**
+     * The full error response JSON from QLS.
+     */
+    fullError) {
+        super();
+        this.ctx = ctx;
+        this.order = order;
+        this.failedAt = failedAt;
+        this.fullError = fullError;
+        this.errorCode = getQLSErrorCode(fullError);
+    }
+}
+exports.QlsOrderFailedEvent = QlsOrderFailedEvent;
+function getQLSErrorCode(errorResponse) {
+    const errorString = JSON.stringify(errorResponse);
+    if (errorString.includes('containsNumber')) {
+        return QLSOrderError.INCORRECT_HOUSE_NUMBER;
+    }
+    if (errorString.includes('validPostalCode') ||
+        errorString.includes('needPostalCodeVerification')) {
+        return QLSOrderError.INCORRECT_POSTAL_CODE;
+    }
+    return QLSOrderError.UNKNOWN_ERROR;
+}

package/dist/services/qls-order-failed-event.spec.d.ts

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

package/dist/services/qls-order-failed-event.spec.js

@@ -0,0 +1,79 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const vitest_1 = require("vitest");
+const qls_order_failed_event_1 = require("./qls-order-failed-event");
+(0, vitest_1.describe)('QlsOrderFailedEvent', () => {
+    const mockCtx = {};
+    const mockOrder = { id: 1, code: 'ORDER-001' };
+    const mockFailedAt = new Date('2026-01-03T04:34:52.473Z');
+    (0, vitest_1.it)('sets errorCode to INCORRECT_HOUSE_NUMBER for containsNumber error', () => {
+        const fullError = {
+            errors: {
+                receiver_contact: {
+                    housenumber: { containsNumber: 'Huisnummer bevat geen nummer' },
+                },
+            },
+            pagination: null,
+        };
+        const event = new qls_order_failed_event_1.QlsOrderFailedEvent(mockCtx, mockOrder, mockFailedAt, fullError);
+        (0, vitest_1.expect)(event.errorCode).toBe(qls_order_failed_event_1.QLSOrderError.INCORRECT_HOUSE_NUMBER);
+        (0, vitest_1.expect)(event.ctx).toBe(mockCtx);
+        (0, vitest_1.expect)(event.order).toBe(mockOrder);
+        (0, vitest_1.expect)(event.failedAt).toBe(mockFailedAt);
+        (0, vitest_1.expect)(event.fullError).toBe(fullError);
+    });
+    (0, vitest_1.it)('sets errorCode to INCORRECT_POSTAL_CODE for validPostalCode error', () => {
+        const fullError = {
+            errors: {
+                receiver_contact: {
+                    postalcode: { validPostalCode: 'Ongeldige indeling (NNNN)' },
+                },
+            },
+            pagination: null,
+        };
+        const event = new qls_order_failed_event_1.QlsOrderFailedEvent(mockCtx, mockOrder, mockFailedAt, fullError);
+        (0, vitest_1.expect)(event.errorCode).toBe(qls_order_failed_event_1.QLSOrderError.INCORRECT_POSTAL_CODE);
+    });
+    (0, vitest_1.it)('sets errorCode to INCORRECT_POSTAL_CODE for needPostalCodeVerification error', () => {
+        const fullError = {
+            errors: {
+                receiver_contact: {
+                    postalcode: { needPostalCodeVerification: 'Ongeldige postcode' },
+                },
+            },
+            pagination: null,
+        };
+        const event = new qls_order_failed_event_1.QlsOrderFailedEvent(mockCtx, mockOrder, mockFailedAt, fullError);
+        (0, vitest_1.expect)(event.errorCode).toBe(qls_order_failed_event_1.QLSOrderError.INCORRECT_POSTAL_CODE);
+    });
+    (0, vitest_1.it)('sets errorCode to INCORRECT_POSTAL_CODE for combined postal code errors', () => {
+        const fullError = {
+            errors: {
+                receiver_contact: {
+                    postalcode: {
+                        needPostalCodeVerification: 'Ongeldige postcode',
+                        validPostalCode: 'Ongeldige indeling (NNNN LL)',
+                    },
+                },
+            },
+            pagination: null,
+        };
+        const event = new qls_order_failed_event_1.QlsOrderFailedEvent(mockCtx, mockOrder, mockFailedAt, fullError);
+        (0, vitest_1.expect)(event.errorCode).toBe(qls_order_failed_event_1.QLSOrderError.INCORRECT_POSTAL_CODE);
+    });
+    (0, vitest_1.it)('sets errorCode to UNKNOWN_ERROR for 502 Bad Gateway HTML response', () => {
+        const fullError = {
+            html: '<html> <head><title>502 Bad Gateway</title></head> <body> <center><h1>502 Bad Gateway</h1></center> <hr><center>nginx</center> </body> </html>',
+        };
+        const event = new qls_order_failed_event_1.QlsOrderFailedEvent(mockCtx, mockOrder, mockFailedAt, fullError);
+        (0, vitest_1.expect)(event.errorCode).toBe(qls_order_failed_event_1.QLSOrderError.UNKNOWN_ERROR);
+    });
+    (0, vitest_1.it)('sets errorCode to UNKNOWN_ERROR for unknown error format', () => {
+        const fullError = {
+            meta: { code: 500 },
+            errors: { unknown: 'Some other error' },
+        };
+        const event = new qls_order_failed_event_1.QlsOrderFailedEvent(mockCtx, mockOrder, mockFailedAt, fullError);
+        (0, vitest_1.expect)(event.errorCode).toBe(qls_order_failed_event_1.QLSOrderError.UNKNOWN_ERROR);
+    });
+});

package/dist/services/qls-order.service.js

@@ -23,6 +23,7 @@ const catch_unknown_1 = require("catch-unknown");
 const util_1 = __importDefault(require("util"));
 const constants_1 = require("../constants");
 const qls_client_1 = require("../lib/qls-client");
+const qls_order_failed_event_1 = require("./qls-order-failed-event");
 let QlsOrderService = class QlsOrderService {
     constructor(options, jobQueueService, eventBus, orderService, moduleRef) {
         this.options = options;
@@ -157,15 +158,23 @@ let QlsOrderService = class QlsOrderService {
                 ...(additionalOrderFields ?? {}),
             };
             const result = await client.createFulfillmentOrder(qlsOrder);
-            await this.orderService.updateCustomFields(ctx, orderId, {
-                syncedToQls: true,
-            });
             core_2.Logger.info(`Successfully created order '${order.code}' in QLS with id '${result.id}'`, constants_1.loggerCtx);
             await this.orderService.addNoteToOrder(ctx, {
                 id: orderId,
                 isPublic: false,
                 note: `Created order '${result.id}' in QLS`,
             });
+            // Delay 10s to prevent race conditions: OrderPlacedEvent is emitted before transition to PaymentSettled is complete
+            setTimeout(() => {
+                this.orderService
+                    .updateCustomFields(ctx, orderId, {
+                    syncedToQls: true,
+                })
+                    .catch((e) => {
+                    const error = (0, catch_unknown_1.asError)(e);
+                    core_2.Logger.error(`Error updating custom field 'syncedToQls: true' for order '${order.code}': ${error.message}`, constants_1.loggerCtx, error.stack);
+                });
+            }, 10000);
             return `Order '${order.code}' created in QLS with id '${result.id}'`;
         }
         catch (e) {
@@ -175,6 +184,7 @@ let QlsOrderService = class QlsOrderService {
                 isPublic: false,
                 note: `Failed to create order '${order.code}' in QLS: ${error.message}`,
             });
+            await this.eventBus.publish(new qls_order_failed_event_1.QlsOrderFailedEvent(ctx, order, new Date(), error.message));
             throw error;
         }
     }

package/dist/types.d.ts

@@ -57,7 +57,9 @@ export type AdditionalVariantFields = Partial<FulfillmentProductInput & {
 }>;
 export interface AdditionalOrderFields {
     servicepoint_code?: string;
-    delivery_options?: string[];
+    delivery_options?: {
+        tag: string;
+    }[];
     custom_values?: CustomValue[];
 }
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pinelab/vendure-plugin-qls-fulfillment",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "description": "Vendure plugin to fulfill orders via QLS.",
   "keywords": [
     "fulfillment",
@@ -32,5 +32,5 @@
   "dependencies": {
     "catch-unknown": "^2.0.0"
   },
-  "gitHead": "6bdee4f31075af25589b52e08cb0ac5658d90f92"
+  "gitHead": "8f5d76680b66b12b9fb3732a4205b4ce20686076"
 }