@porulle/plugin-channel-connector 0.68.3 → 0.69.0

package/dist/hooks.js

@@ -1,7 +1,7 @@
-import { resolveOrgIdForCommerce } from "@porulle/core";
+import { CommerceValidationError, resolveOrgIdForCommerce } from "@porulle/core";
 import { and, eq, inArray } from "@porulle/core/drizzle";
 import { sellableEntities } from "@porulle/core/schema";
-import { ChannelConnectorService, } from "./service.js";
+import { CHANNEL_ORDER_CANCELLED_REASON, ChannelConnectorService, } from "./service.js";
 import { handleCatalogAfterUpdate, recordUpdateFieldPaths, } from "./catalog-push-trigger.js";
 /**
  * The state an order sits in while it waits for a payment gateway. Core owns it
@@ -157,8 +157,54 @@ function pushHooks(mode) {
                 }];
     }
 }
+function parseCancelRequest(args) {
+    if (!isRecord(args))
+        return null;
+    const { data } = args;
+    if (!isRecord(data))
+        return null;
+    const { orderId, newStatus, reason } = data;
+    if (typeof orderId !== "string" || newStatus !== "cancelled")
+        return null;
+    return { orderId, reason: typeof reason === "string" ? reason : undefined };
+}
+/** The store's reason, read loosely from the platform's free-text one. */
+function storeCancelReason(reason) {
+    if (reason === undefined)
+        return "other";
+    if (/customer|shopper/i.test(reason))
+        return "customer";
+    if (/stock|inventory/i.test(reason))
+        return "inventory";
+    return "other";
+}
+/**
+ * Cancel at the store BEFORE the platform cancels, so a store that refuses — it has shipped — blocks
+ * the platform's cancel instead of the shopper being refunded for goods on their way. A cancel the
+ * store itself started is not sent back to it.
+ */
+function cancelAtStoreHook(options) {
+    return {
+        key: "orders.beforeStatusChange",
+        async handler(args) {
+            // A before-hook's return value REPLACES the data, so every path hands it back unchanged.
+            if (!isRecord(args))
+                throw new Error("orders.beforeStatusChange delivered no payload.");
+            const { data } = args;
+            const request = parseCancelRequest(args);
+            if (request === null || request.reason === CHANNEL_ORDER_CANCELLED_REASON || !hasHookContext(args))
+                return data;
+            const { context } = args;
+            const service = new ChannelConnectorService(context.db, context.services, options);
+            const cancelled = await service.cancelRemoteOrders(resolveOrgIdForCommerce(context.actor, context.commerceConfig), request.orderId, { reason: storeCancelReason(request.reason), staffNote: `Cancelled on the marketplace${request.reason ? ` (${request.reason})` : ""}.` });
+            if (!cancelled.ok)
+                throw new CommerceValidationError(`The store would not cancel this order: ${cancelled.error}`);
+            return data;
+        },
+    };
+}
 export function buildHooks(options) {
-    return [{
+    return [cancelAtStoreHook(options), {
             key: "checkout.beforePayment",
             async handler(args) {
                 const { data, context } = args;

package/dist/index.js

@@ -240,6 +240,9 @@ export function channelConnectorPlugin(options = {}) {
                 const orgId = String(input.orgId);
                 const storeId = String(input.storeId);
                 const orderId = String(input.orderId);
+                // Cancelled before this ran: the store must never receive an order nobody is paying for.
+                if (await service.isOrderClosed(orgId, orderId))
+                    return { output: { state: "skipped", reason: "order closed" } };
                 const existing = await service.createExport(orgId, storeId, orderId);
                 if (!existing.ok)
                     throw new Error(existing.error);

package/dist/live-credentials.js

@@ -76,5 +76,6 @@ export function withLiveCredentials(connector, db) {
         ...(connector.pushCatalog ? { pushCatalog: around(connector.pushCatalog) } : {}),
         ...(connector.reserve ? { reserve: around(connector.reserve) } : {}),
         ...(connector.registerWebhooks ? { registerWebhooks: around(connector.registerWebhooks) } : {}),
+        ...(connector.cancelOrder ? { cancelOrder: around(connector.cancelOrder) } : {}),
     };
 }

package/dist/service.d.ts

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import type { Actor, ChannelCatalogItem, ChannelConnector, ChannelOrderSlice, ChannelPushCatalogField, ChannelPushCatalogImage, ChannelPushCatalogItem, ChannelPushCatalogItemOutcome, ChannelPushCatalogResult, ChannelStore, PluginDb, PluginResult, PluginTxFn } from "@porulle/core";
+import type { Actor, ChannelCancelOrderInput, ChannelCatalogItem, ChannelConnector, ChannelOrderSlice, ChannelPushCatalogField, ChannelPushCatalogImage, ChannelPushCatalogItem, ChannelPushCatalogItemOutcome, ChannelPushCatalogResult, ChannelStore, PluginDb, PluginResult, PluginTxFn } from "@porulle/core";
 import type { ChannelCatalogImage } from "@porulle/core";
 import type { FieldOwner, FieldPath } from "@porulle/core";
 import type { JobsAdapter } from "@porulle/core";
@@ -22,6 +22,11 @@ export declare const CATALOG_PUSH_MAX_ATTEMPTS = 8;
  * nine-hour one that discards everything if it fails.
  */
 export declare const CHANNEL_INVENTORY_MAX_ITEMS_PER_INVOCATION = 20;
+/**
+ * The reason a platform order is cancelled under when its STORE cancelled it. The cancel hook skips
+ * cancelling at the store for exactly this reason, so the two directions cannot loop.
+ */
+export declare const CHANNEL_ORDER_CANCELLED_REASON = "channel_order_cancelled";
 export declare function catalogPushRetryDelayMs(attempts: number): number;
 export interface CatalogPushJobResult extends Record<string, unknown> {
     noop?: boolean;
@@ -653,6 +658,14 @@ export declare class ChannelConnectorService {
     private refundLinesForRequest;
     createExport(orgId: string, storeId: string, orderId: string): Promise<PluginResult<ChannelOrderExport>>;
     transitionExport(orgId: string, exportId: string, toState: ExportState, changedBy: string, reason?: string, failureKind?: "definitive" | "transient"): Promise<PluginResult<ChannelOrderExport>>;
+    /**
+     * Cancels this order at every store it was pushed to. Any refusal is returned as the error, so the
+     * caller can refuse its own cancel: a store that has shipped must not see the marketplace refund
+     * goods already on their way. A store with no connector able to cancel is left to its merchant.
+     */
+    cancelRemoteOrders(orgId: string, orderId: string, input: ChannelCancelOrderInput): Promise<PluginResult<number>>;
+    /** A cancelled or refunded order: nothing to push to a store, ever again. */
+    isOrderClosed(orgId: string, orderId: string): Promise<boolean>;
     exportOrder(orgId: string, storeId: string, slice: ChannelOrderSlice, actor: Actor): Promise<PluginResult<ChannelOrderExport>>;
     buildOrderSlice(orgId: string, storeId: string, orderId: string): Promise<PluginResult<ChannelOrderSlice>>;
     reapExports(input: {

package/dist/service.js

@@ -29,6 +29,11 @@ export const CATALOG_PUSH_MAX_ATTEMPTS = 8;
  * nine-hour one that discards everything if it fails.
  */
 export const CHANNEL_INVENTORY_MAX_ITEMS_PER_INVOCATION = 20;
+/**
+ * The reason a platform order is cancelled under when its STORE cancelled it. The cancel hook skips
+ * cancelling at the store for exactly this reason, so the two directions cannot loop.
+ */
+export const CHANNEL_ORDER_CANCELLED_REASON = "channel_order_cancelled";
 const CATALOG_PUSH_RETRY_BASE_MS = 60_000;
 const CATALOG_PUSH_RETRY_MAX_MS = 60 * 60 * 1000;
 export function catalogPushRetryDelayMs(attempts) {
@@ -3882,6 +3887,15 @@ export class ChannelConnectorService {
                 const note = await ordersService.addNote(orderId, { body: `Channel ${event.type}: ${String(data.id ?? data.order_id ?? "remote order")}.` }, actor);
                 if (!note.ok)
                     return PluginErr(note.error?.message ?? "Could not add channel order note.");
+                if (event.type === "orders/cancelled") {
+                    // The store cancelled: the platform follows, under a reason the cancel hook recognises, so
+                    // it does not turn round and cancel at the store again. An order already closed, or one the
+                    // machine cannot cancel (shipped), keeps its status; the note above records the delivery.
+                    const [order] = await this.db.select({ status: orders.status }).from(orders).where(and(eq(orders.organizationId, orgId), eq(orders.id, orderId)));
+                    if (order && !["cancelled", "refunded"].includes(order.status)) {
+                        await ordersService.changeStatus({ orderId, newStatus: "cancelled", reason: CHANNEL_ORDER_CANCELLED_REASON }, actor);
+                    }
+                }
                 if (event.type === "orders/fulfilled") {
                     const [order] = await this.db.select({ status: orders.status }).from(orders).where(and(eq(orders.organizationId, orgId), eq(orders.id, orderId)));
                     if (order?.status === "confirmed")
@@ -4283,6 +4297,39 @@ export class ChannelConnectorService {
             return Ok(updated);
         });
     }
+    /**
+     * Cancels this order at every store it was pushed to. Any refusal is returned as the error, so the
+     * caller can refuse its own cancel: a store that has shipped must not see the marketplace refund
+     * goods already on their way. A store with no connector able to cancel is left to its merchant.
+     */
+    async cancelRemoteOrders(orgId, orderId, input) {
+        const exports = await this.db
+            .select({ storeId: channelOrderExports.storeId, remoteOrderId: channelOrderExports.remoteOrderId })
+            .from(channelOrderExports)
+            .where(and(eq(channelOrderExports.organizationId, orgId), eq(channelOrderExports.orderId, orderId)));
+        let cancelled = 0;
+        for (const exported of exports) {
+            if (exported.remoteOrderId === null)
+                continue;
+            const store = await this.getStoreRecord(orgId, exported.storeId);
+            if (!store || store.status !== "connected")
+                continue;
+            // ponytail: a provider without cancelOrder is skipped silently; refuse instead if one ever ships without it.
+            const connector = this.connectors.get(store.provider);
+            if (!connector?.cancelOrder)
+                continue;
+            const result = await connector.cancelOrder(store, exported.remoteOrderId, input);
+            if (!result.ok)
+                return PluginErr(result.error.message, result.error.code);
+            cancelled += 1;
+        }
+        return Ok(cancelled);
+    }
+    /** A cancelled or refunded order: nothing to push to a store, ever again. */
+    async isOrderClosed(orgId, orderId) {
+        const [order] = await this.db.select({ status: orders.status }).from(orders).where(and(eq(orders.organizationId, orgId), eq(orders.id, orderId)));
+        return order?.status === "cancelled" || order?.status === "refunded";
+    }
     async exportOrder(orgId, storeId, slice, actor) {
         const store = await this.getStoreRecord(orgId, storeId);
         if (!store || store.status !== "connected") {
@@ -4387,7 +4434,10 @@ export class ChannelConnectorService {
         }
         if (!email || !shippingAddress)
             return PluginErr("Customer email and shipping address are required for channel order export.", "CUSTOMER_DATA_MISSING");
-        return Ok({ orderId, currency: order.currency, grandTotal: lines.reduce((sum, line) => sum + line.totalPrice, 0), lines, customer: { name, email, shippingAddress } });
+        const linesTotal = lines.reduce((sum, line) => sum + line.totalPrice, 0);
+        // ponytail: a multi-store order sends no shipping to any store; apportion it when such orders exist.
+        const shipping = selected.length === lineItems.length && order.shippingTotal > 0 ? { title: "Shipping", amount: order.shippingTotal } : null;
+        return Ok({ orderId, currency: order.currency, grandTotal: linesTotal + (shipping?.amount ?? 0), lines, ...(shipping ? { shipping } : {}), customer: { name, email, shippingAddress } });
     }
     async reapExports(input) {
         const now = Date.now();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@porulle/plugin-channel-connector",
-  "version": "0.68.3",
+  "version": "0.69.0",
   "license": "MIT",
   "type": "module",
   "exports": {
@@ -22,7 +22,7 @@
   "dependencies": {
     "@hono/zod-openapi": "^1.2.2",
     "hono": "^4.12.5",
-    "@porulle/core": "0.68.3"
+    "@porulle/core": "0.69.0"
   },
   "devDependencies": {
     "@types/node": "^24.5.2",

package/src/hooks.ts

@@ -1,6 +1,7 @@
-import { resolveOrgIdForCommerce } from "@porulle/core";
+import { CommerceValidationError, resolveOrgIdForCommerce } from "@porulle/core";
 import type {
   Actor,
+  ChannelCancelReason,
   CommerceConfig,
   HookContext,
   PluginHookRegistration,
@@ -8,6 +9,7 @@ import type {
 import { and, eq, inArray } from "@porulle/core/drizzle";
 import { sellableEntities } from "@porulle/core/schema";
 import {
+  CHANNEL_ORDER_CANCELLED_REASON,
   ChannelConnectorService,
   type ChannelConnectorPluginOptions,
   type ChannelPushTrigger,
@@ -202,8 +204,58 @@ function pushHooks(mode: ChannelPushTrigger): PluginHookRegistration[] {
   }
 }
 
+/** The cancel a status change asks for, on `orders.beforeStatusChange`. */
+interface CancelRequest {
+  orderId: string;
+  reason: string | undefined;
+}
+
+function parseCancelRequest(args: unknown): CancelRequest | null {
+  if (!isRecord(args)) return null;
+  const { data } = args;
+  if (!isRecord(data)) return null;
+  const { orderId, newStatus, reason } = data;
+  if (typeof orderId !== "string" || newStatus !== "cancelled") return null;
+  return { orderId, reason: typeof reason === "string" ? reason : undefined };
+}
+
+/** The store's reason, read loosely from the platform's free-text one. */
+function storeCancelReason(reason: string | undefined): ChannelCancelReason {
+  if (reason === undefined) return "other";
+  if (/customer|shopper/i.test(reason)) return "customer";
+  if (/stock|inventory/i.test(reason)) return "inventory";
+  return "other";
+}
+
+/**
+ * Cancel at the store BEFORE the platform cancels, so a store that refuses — it has shipped — blocks
+ * the platform's cancel instead of the shopper being refunded for goods on their way. A cancel the
+ * store itself started is not sent back to it.
+ */
+function cancelAtStoreHook(options: ChannelConnectorPluginOptions): PluginHookRegistration {
+  return {
+    key: "orders.beforeStatusChange",
+    async handler(args: unknown) {
+      // A before-hook's return value REPLACES the data, so every path hands it back unchanged.
+      if (!isRecord(args)) throw new Error("orders.beforeStatusChange delivered no payload.");
+      const { data } = args;
+      const request = parseCancelRequest(args);
+      if (request === null || request.reason === CHANNEL_ORDER_CANCELLED_REASON || !hasHookContext(args)) return data;
+      const { context } = args;
+      const service = new ChannelConnectorService(context.db, context.services, options);
+      const cancelled = await service.cancelRemoteOrders(
+        resolveOrgIdForCommerce(context.actor, context.commerceConfig),
+        request.orderId,
+        { reason: storeCancelReason(request.reason), staffNote: `Cancelled on the marketplace${request.reason ? ` (${request.reason})` : ""}.` },
+      );
+      if (!cancelled.ok) throw new CommerceValidationError(`The store would not cancel this order: ${cancelled.error}`);
+      return data;
+    },
+  };
+}
+
 export function buildHooks(options: ChannelConnectorPluginOptions): PluginHookRegistration[] {
-  return [{
+  return [cancelAtStoreHook(options), {
     key: "checkout.beforePayment",
     async handler(args: unknown) {
       const { data, context } = args as {

package/src/index.ts

@@ -409,6 +409,8 @@ export function channelConnectorPlugin(options: ChannelConnectorPluginOptions =
         const orgId = String(input.orgId);
         const storeId = String(input.storeId);
         const orderId = String(input.orderId);
+        // Cancelled before this ran: the store must never receive an order nobody is paying for.
+        if (await service.isOrderClosed(orgId, orderId)) return { output: { state: "skipped", reason: "order closed" } };
         const existing = await service.createExport(orgId, storeId, orderId);
         if (!existing.ok) throw new Error(existing.error);
         const slice = await service.buildOrderSlice(orgId, storeId, orderId);

package/src/live-credentials.ts

@@ -73,5 +73,6 @@ export function withLiveCredentials(connector: ChannelConnector, db: PluginDb):
     ...(connector.pushCatalog ? { pushCatalog: around(connector.pushCatalog) } : {}),
     ...(connector.reserve ? { reserve: around(connector.reserve) } : {}),
     ...(connector.registerWebhooks ? { registerWebhooks: around(connector.registerWebhooks) } : {}),
+    ...(connector.cancelOrder ? { cancelOrder: around(connector.cancelOrder) } : {}),
   };
 }

package/src/service.ts

@@ -14,6 +14,7 @@ import {
 } from "@porulle/core";
 import type {
   Actor,
+  ChannelCancelOrderInput,
   EntityLinkRows,
   ChannelCatalogItem,
   ChannelConnector,
@@ -123,6 +124,12 @@ export const CATALOG_PUSH_MAX_ATTEMPTS = 8;
  */
 export const CHANNEL_INVENTORY_MAX_ITEMS_PER_INVOCATION = 20;
 
+/**
+ * The reason a platform order is cancelled under when its STORE cancelled it. The cancel hook skips
+ * cancelling at the store for exactly this reason, so the two directions cannot loop.
+ */
+export const CHANNEL_ORDER_CANCELLED_REASON = "channel_order_cancelled";
+
 const CATALOG_PUSH_RETRY_BASE_MS = 60_000;
 const CATALOG_PUSH_RETRY_MAX_MS = 60 * 60 * 1000;
 
@@ -4981,9 +4988,18 @@ export class ChannelConnectorService {
     } else if (event.type === "orders/fulfilled" || event.type === "orders/cancelled") {
       const orderId = await this.resolveOrderId(orgId, storeId, data);
       if (orderId) {
-        const ordersService = this.services.orders as { addNote(orderId: string, input: { body: string }, actor: Actor): Promise<{ ok: boolean; error?: { message: string } }>; changeStatus(input: { orderId: string; newStatus: "processing" | "fulfilled"; reason: string }, actor: Actor): Promise<{ ok: boolean }> };
+        const ordersService = this.services.orders as { addNote(orderId: string, input: { body: string }, actor: Actor): Promise<{ ok: boolean; error?: { message: string } }>; changeStatus(input: { orderId: string; newStatus: "processing" | "fulfilled" | "cancelled"; reason: string }, actor: Actor): Promise<{ ok: boolean }> };
         const note = await ordersService.addNote(orderId, { body: `Channel ${event.type}: ${String(data.id ?? data.order_id ?? "remote order")}.` }, actor);
         if (!note.ok) return PluginErr(note.error?.message ?? "Could not add channel order note.");
+        if (event.type === "orders/cancelled") {
+          // The store cancelled: the platform follows, under a reason the cancel hook recognises, so
+          // it does not turn round and cancel at the store again. An order already closed, or one the
+          // machine cannot cancel (shipped), keeps its status; the note above records the delivery.
+          const [order] = await this.db.select({ status: orders.status }).from(orders).where(and(eq(orders.organizationId, orgId), eq(orders.id, orderId)));
+          if (order && !["cancelled", "refunded"].includes(order.status)) {
+            await ordersService.changeStatus({ orderId, newStatus: "cancelled", reason: CHANNEL_ORDER_CANCELLED_REASON }, actor);
+          }
+        }
         if (event.type === "orders/fulfilled") {
           const [order] = await this.db.select({ status: orders.status }).from(orders).where(and(eq(orders.organizationId, orgId), eq(orders.id, orderId)));
           if (order?.status === "confirmed") await ordersService.changeStatus({ orderId, newStatus: "processing", reason: "channel_order_fulfilled" }, actor);
@@ -5429,6 +5445,37 @@ export class ChannelConnectorService {
     });
   }
 
+  /**
+   * Cancels this order at every store it was pushed to. Any refusal is returned as the error, so the
+   * caller can refuse its own cancel: a store that has shipped must not see the marketplace refund
+   * goods already on their way. A store with no connector able to cancel is left to its merchant.
+   */
+  async cancelRemoteOrders(orgId: string, orderId: string, input: ChannelCancelOrderInput): Promise<PluginResult<number>> {
+    const exports = await this.db
+      .select({ storeId: channelOrderExports.storeId, remoteOrderId: channelOrderExports.remoteOrderId })
+      .from(channelOrderExports)
+      .where(and(eq(channelOrderExports.organizationId, orgId), eq(channelOrderExports.orderId, orderId)));
+    let cancelled = 0;
+    for (const exported of exports) {
+      if (exported.remoteOrderId === null) continue;
+      const store = await this.getStoreRecord(orgId, exported.storeId);
+      if (!store || store.status !== "connected") continue;
+      // ponytail: a provider without cancelOrder is skipped silently; refuse instead if one ever ships without it.
+      const connector = this.connectors.get(store.provider);
+      if (!connector?.cancelOrder) continue;
+      const result = await connector.cancelOrder(store as ChannelStore, exported.remoteOrderId, input);
+      if (!result.ok) return PluginErr(result.error.message, result.error.code);
+      cancelled += 1;
+    }
+    return Ok(cancelled);
+  }
+
+  /** A cancelled or refunded order: nothing to push to a store, ever again. */
+  async isOrderClosed(orgId: string, orderId: string): Promise<boolean> {
+    const [order] = await this.db.select({ status: orders.status }).from(orders).where(and(eq(orders.organizationId, orgId), eq(orders.id, orderId)));
+    return order?.status === "cancelled" || order?.status === "refunded";
+  }
+
   async exportOrder(
     orgId: string,
     storeId: string,
@@ -5583,7 +5630,10 @@ export class ChannelConnectorService {
       shippingAddress = withoutUndefined(parsed.data);
     }
     if (!email || !shippingAddress) return PluginErr("Customer email and shipping address are required for channel order export.", "CUSTOMER_DATA_MISSING");
-    return Ok({ orderId, currency: order.currency, grandTotal: lines.reduce((sum, line) => sum + line.totalPrice, 0), lines, customer: { name, email, shippingAddress } });
+    const linesTotal = lines.reduce((sum, line) => sum + line.totalPrice, 0);
+    // ponytail: a multi-store order sends no shipping to any store; apportion it when such orders exist.
+    const shipping = selected.length === lineItems.length && order.shippingTotal > 0 ? { title: "Shipping", amount: order.shippingTotal } : null;
+    return Ok({ orderId, currency: order.currency, grandTotal: linesTotal + (shipping?.amount ?? 0), lines, ...(shipping ? { shipping } : {}), customer: { name, email, shippingAddress } });
   }
 
   async reapExports(input: { definitiveMs: number; transientMs: number }): Promise<{ abandonedCount: number; refundedOrderIds: string[] }> {