@porulle/plugin-channel-connector 0.68.4 → 0.70.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,23 @@ 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>>;
+    /**
+     * One core fulfilment record per store fulfilment the order body carries, keyed on the store's
+     * fulfilment id (`metadata.channelFulfillmentId`) so a replay records nothing twice. Each records
+     * the lines it shipped, matched by the store's variant id; one whose lines cannot be matched
+     * records every line not yet fulfilled. A fulfilment the store cancelled is not a parcel.
+     */
+    private recordChannelFulfillments;
+    /** Every line with quantity still to ship, for a parcel whose own lines could not be matched. */
+    private unfulfilledLines;
+    /** 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

@@ -5,7 +5,7 @@ import { isValidFieldPath, requireUserId } from "@porulle/core";
 import { CHANNEL_CONVERGENCE_CTX } from "./catalog-push-trigger.js";
 import { resolveLiveCredentials, withLiveCredentials } from "./live-credentials.js";
 import { and, desc, eq, inArray, isNull, lte, or, sql } from "@porulle/core/drizzle";
-import { brands, categories, customerAddresses, customers, entityBrands, entityCategories, entityMedia, entityTags, inventoryLevels, mediaAssets, optionTypes, optionValues, orderLineItems, orders, prices, sellableAttributes, sellableCustomFields, sellableEntities, sellableEntityRevisions, entityFieldDefinitions, tags, variants, variantOptionValues, } from "@porulle/core/schema";
+import { brands, categories, customerAddresses, customers, entityBrands, entityCategories, entityMedia, entityTags, inventoryLevels, mediaAssets, optionTypes, optionValues, fulfillmentLineItems, fulfillmentRecords, orderLineItems, orders, prices, sellableAttributes, sellableCustomFields, sellableEntities, sellableEntityRevisions, entityFieldDefinitions, tags, variants, variantOptionValues, } from "@porulle/core/schema";
 import { planAbsentArchives } from "./deletion-policy.js";
 import { channelCatalogPushEvents, channelCatalogPushes, channelCatalogConflicts, channelCatalogConflictEvents, channelEntityLinks, channelEntityMap, channelExportEvents, channelOrderExports, connectedStores, channelRefundEvents, channelRefundRequests, } from "./schema.js";
 import { mergeCatalogFieldMapping, normalizeCatalogFieldMapping, selectCatalogFieldMapping, } from "./catalog-field-mapping.js";
@@ -29,6 +29,20 @@ 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";
+/** The slice of a store order body's `fulfillments` (Shopify's REST spelling) a parcel is read from. */
+const channelFulfillmentsSchema = z.array(z.object({
+    id: z.union([z.string(), z.number()]),
+    status: z.string().nullish(),
+    tracking_company: z.string().nullish(),
+    tracking_number: z.string().nullish(),
+    tracking_url: z.string().nullish(),
+    line_items: z.array(z.object({ variant_id: z.union([z.string(), z.number()]).nullish(), quantity: z.number().int().positive() })).default([]),
+}));
 const CATALOG_PUSH_RETRY_BASE_MS = 60_000;
 const CATALOG_PUSH_RETRY_MAX_MS = 60 * 60 * 1000;
 export function catalogPushRetryDelayMs(attempts) {
@@ -2269,6 +2283,7 @@ export class ChannelConnectorService {
                 "products/delete",
                 "inventory_levels/update",
                 "orders/fulfilled",
+                "orders/partially_fulfilled",
                 "orders/cancelled",
                 "app/uninstalled",
             ], callbackUrl);
@@ -3875,20 +3890,35 @@ export class ChannelConnectorService {
                 await this.setMappedInventory(orgId, storeId, externalId, available, actor);
             }
         }
-        else if (event.type === "orders/fulfilled" || event.type === "orders/cancelled") {
+        else if (event.type === "orders/fulfilled" || event.type === "orders/partially_fulfilled" || event.type === "orders/cancelled") {
             const orderId = await this.resolveOrderId(orgId, storeId, data);
             if (orderId) {
                 const ordersService = this.services.orders;
                 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/fulfilled") {
+                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" || event.type === "orders/partially_fulfilled") {
+                    // The parcels first, so whatever the status move announces (a shipped email) can read them.
+                    const recorded = await this.recordChannelFulfillments(orgId, storeId, orderId, data, actor);
+                    if (!recorded.ok)
+                        return recorded;
+                    const target = event.type === "orders/fulfilled" ? "fulfilled" : "partially_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);
                     const [after] = await this.db.select({ status: orders.status }).from(orders).where(and(eq(orders.organizationId, orgId), eq(orders.id, orderId)));
-                    if (after?.status === "processing")
-                        await ordersService.changeStatus({ orderId, newStatus: "fulfilled", reason: "channel_order_fulfilled" }, actor);
+                    if (after?.status === "processing" || (target === "fulfilled" && after?.status === "partially_fulfilled")) {
+                        await ordersService.changeStatus({ orderId, newStatus: target, reason: "channel_order_fulfilled" }, actor);
+                    }
                 }
             }
         }
@@ -4283,6 +4313,102 @@ 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);
+    }
+    /**
+     * One core fulfilment record per store fulfilment the order body carries, keyed on the store's
+     * fulfilment id (`metadata.channelFulfillmentId`) so a replay records nothing twice. Each records
+     * the lines it shipped, matched by the store's variant id; one whose lines cannot be matched
+     * records every line not yet fulfilled. A fulfilment the store cancelled is not a parcel.
+     */
+    async recordChannelFulfillments(orgId, storeId, orderId, data, actor) {
+        const parsed = channelFulfillmentsSchema.safeParse(data.fulfillments ?? []);
+        if (!parsed.success)
+            return PluginErr(`Channel order fulfilments did not parse: ${parsed.error.message}`);
+        const existing = await this.db.select({ metadata: fulfillmentRecords.metadata }).from(fulfillmentRecords).where(eq(fulfillmentRecords.orderId, orderId));
+        const recorded = new Set(existing.map((row) => String(row.metadata?.channelFulfillmentId ?? "")));
+        const lines = await this.db.select({ id: orderLineItems.id, variantId: orderLineItems.variantId, quantity: orderLineItems.quantity }).from(orderLineItems).where(eq(orderLineItems.orderId, orderId));
+        const fulfillment = this.services.fulfillment;
+        let created = 0;
+        for (const parcel of parsed.data) {
+            const parcelId = String(parcel.id);
+            if (recorded.has(parcelId) || parcel.status === "cancelled" || parcel.status === "error" || parcel.status === "failure")
+                continue;
+            const externalIds = parcel.line_items.flatMap((line) => (line.variant_id == null ? [] : [String(line.variant_id)]));
+            const mapped = externalIds.length === 0 ? [] : await this.db
+                .select({ externalId: channelEntityMap.externalId, variantId: channelEntityMap.variantId })
+                .from(channelEntityMap)
+                .where(and(eq(channelEntityMap.organizationId, orgId), eq(channelEntityMap.storeId, storeId), eq(channelEntityMap.kind, "variant"), inArray(channelEntityMap.externalId, externalIds)));
+            const variantFor = new Map(mapped.map((row) => [row.externalId, row.variantId]));
+            const matched = parcel.line_items.flatMap((line) => {
+                const variantId = line.variant_id == null ? undefined : variantFor.get(String(line.variant_id));
+                const orderLine = variantId == null ? undefined : lines.find((candidate) => candidate.variantId === variantId);
+                return orderLine ? [{ orderLineItemId: orderLine.id, quantity: line.quantity }] : [];
+            });
+            const lineItems = matched.length > 0 ? matched : await this.unfulfilledLines(lines);
+            if (lineItems.length === 0)
+                continue;
+            const result = await fulfillment.createFulfillment({
+                orderId,
+                lineItems,
+                ...(parcel.tracking_company ? { carrier: parcel.tracking_company } : {}),
+                ...(parcel.tracking_number ? { trackingNumber: parcel.tracking_number } : {}),
+                ...(parcel.tracking_url ? { trackingUrl: parcel.tracking_url } : {}),
+                status: "shipped",
+                metadata: { channelFulfillmentId: parcelId, storeId },
+            }, actor);
+            if (!result.ok)
+                return PluginErr(result.error?.message ?? "Could not record the store's fulfilment.");
+            recorded.add(parcelId);
+            created += 1;
+        }
+        return Ok(created);
+    }
+    /** Every line with quantity still to ship, for a parcel whose own lines could not be matched. */
+    async unfulfilledLines(lines) {
+        const ids = lines.map((line) => line.id);
+        const shipped = ids.length === 0 ? [] : await this.db
+            .select({ lineId: fulfillmentLineItems.orderLineItemId, quantity: sql `coalesce(sum(${fulfillmentLineItems.quantity}), 0)::int` })
+            .from(fulfillmentLineItems)
+            .where(inArray(fulfillmentLineItems.orderLineItemId, ids))
+            .groupBy(fulfillmentLineItems.orderLineItemId);
+        const shippedBy = new Map(shipped.map((row) => [row.lineId, row.quantity]));
+        return lines.flatMap((line) => {
+            const remaining = line.quantity - (shippedBy.get(line.id) ?? 0);
+            return remaining > 0 ? [{ orderLineItemId: line.id, quantity: remaining }] : [];
+        });
+    }
+    /** 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") {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@porulle/plugin-channel-connector",
-  "version": "0.68.4",
+  "version": "0.70.0",
   "license": "MIT",
   "type": "module",
   "exports": {
@@ -22,15 +22,15 @@
   "dependencies": {
     "@hono/zod-openapi": "^1.2.2",
     "hono": "^4.12.5",
-    "@porulle/core": "0.68.4"
+    "@porulle/core": "0.70.0"
   },
   "devDependencies": {
     "@types/node": "^24.5.2",
     "eslint": "^9.39.1",
     "typescript": "5.9.2",
     "vitest": "^3.2.4",
-    "@porulle/typescript-config": "0.1.0",
-    "@porulle/eslint-config": "0.1.0"
+    "@porulle/eslint-config": "0.1.0",
+    "@porulle/typescript-config": "0.1.0"
   },
   "publishConfig": {
     "access": "public"

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,
@@ -55,6 +56,8 @@ import {
   mediaAssets,
   optionTypes,
   optionValues,
+  fulfillmentLineItems,
+  fulfillmentRecords,
   orderLineItems,
   orders,
   prices,
@@ -123,6 +126,22 @@ 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";
+
+/** The slice of a store order body's `fulfillments` (Shopify's REST spelling) a parcel is read from. */
+const channelFulfillmentsSchema = z.array(z.object({
+  id: z.union([z.string(), z.number()]),
+  status: z.string().nullish(),
+  tracking_company: z.string().nullish(),
+  tracking_number: z.string().nullish(),
+  tracking_url: z.string().nullish(),
+  line_items: z.array(z.object({ variant_id: z.union([z.string(), z.number()]).nullish(), quantity: z.number().int().positive() })).default([]),
+}));
+
 const CATALOG_PUSH_RETRY_BASE_MS = 60_000;
 const CATALOG_PUSH_RETRY_MAX_MS = 60 * 60 * 1000;
 
@@ -3182,6 +3201,7 @@ export class ChannelConnectorService {
         "products/delete",
         "inventory_levels/update",
         "orders/fulfilled",
+        "orders/partially_fulfilled",
         "orders/cancelled",
         "app/uninstalled",
       ], callbackUrl);
@@ -4978,17 +4998,32 @@ export class ChannelConnectorService {
         const externalId = String(data.variation_id ?? data.product_id ?? inventoryItemId ?? "");
         await this.setMappedInventory(orgId, storeId, externalId, available, actor);
       }
-    } else if (event.type === "orders/fulfilled" || event.type === "orders/cancelled") {
+    } else if (event.type === "orders/fulfilled" || event.type === "orders/partially_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" | "partially_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/fulfilled") {
+        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" || event.type === "orders/partially_fulfilled") {
+          // The parcels first, so whatever the status move announces (a shipped email) can read them.
+          const recorded = await this.recordChannelFulfillments(orgId, storeId, orderId, data, actor);
+          if (!recorded.ok) return recorded;
+          const target = event.type === "orders/fulfilled" ? "fulfilled" : "partially_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);
           const [after] = await this.db.select({ status: orders.status }).from(orders).where(and(eq(orders.organizationId, orgId), eq(orders.id, orderId)));
-          if (after?.status === "processing") await ordersService.changeStatus({ orderId, newStatus: "fulfilled", reason: "channel_order_fulfilled" }, actor);
+          if (after?.status === "processing" || (target === "fulfilled" && after?.status === "partially_fulfilled")) {
+            await ordersService.changeStatus({ orderId, newStatus: target, reason: "channel_order_fulfilled" }, actor);
+          }
         }
       }
     } else if (event.type === "refunds/create") {
@@ -5429,6 +5464,98 @@ 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);
+  }
+
+  /**
+   * One core fulfilment record per store fulfilment the order body carries, keyed on the store's
+   * fulfilment id (`metadata.channelFulfillmentId`) so a replay records nothing twice. Each records
+   * the lines it shipped, matched by the store's variant id; one whose lines cannot be matched
+   * records every line not yet fulfilled. A fulfilment the store cancelled is not a parcel.
+   */
+  private async recordChannelFulfillments(orgId: string, storeId: string, orderId: string, data: Record<string, unknown>, actor: Actor): Promise<PluginResult<number>> {
+    const parsed = channelFulfillmentsSchema.safeParse(data.fulfillments ?? []);
+    if (!parsed.success) return PluginErr(`Channel order fulfilments did not parse: ${parsed.error.message}`);
+    const existing = await this.db.select({ metadata: fulfillmentRecords.metadata }).from(fulfillmentRecords).where(eq(fulfillmentRecords.orderId, orderId));
+    const recorded = new Set(existing.map((row) => String(row.metadata?.channelFulfillmentId ?? "")));
+    const lines = await this.db.select({ id: orderLineItems.id, variantId: orderLineItems.variantId, quantity: orderLineItems.quantity }).from(orderLineItems).where(eq(orderLineItems.orderId, orderId));
+    const fulfillment = this.services.fulfillment as { createFulfillment(input: { orderId: string; lineItems: Array<{ orderLineItemId: string; quantity: number }>; carrier?: string; trackingNumber?: string; trackingUrl?: string; status?: string; metadata?: Record<string, unknown> }, actor: Actor): Promise<{ ok: boolean; error?: { message: string } }> };
+    let created = 0;
+    for (const parcel of parsed.data) {
+      const parcelId = String(parcel.id);
+      if (recorded.has(parcelId) || parcel.status === "cancelled" || parcel.status === "error" || parcel.status === "failure") continue;
+      const externalIds = parcel.line_items.flatMap((line) => (line.variant_id == null ? [] : [String(line.variant_id)]));
+      const mapped = externalIds.length === 0 ? [] : await this.db
+        .select({ externalId: channelEntityMap.externalId, variantId: channelEntityMap.variantId })
+        .from(channelEntityMap)
+        .where(and(eq(channelEntityMap.organizationId, orgId), eq(channelEntityMap.storeId, storeId), eq(channelEntityMap.kind, "variant"), inArray(channelEntityMap.externalId, externalIds)));
+      const variantFor = new Map(mapped.map((row) => [row.externalId, row.variantId]));
+      const matched = parcel.line_items.flatMap((line) => {
+        const variantId = line.variant_id == null ? undefined : variantFor.get(String(line.variant_id));
+        const orderLine = variantId == null ? undefined : lines.find((candidate) => candidate.variantId === variantId);
+        return orderLine ? [{ orderLineItemId: orderLine.id, quantity: line.quantity }] : [];
+      });
+      const lineItems = matched.length > 0 ? matched : await this.unfulfilledLines(lines);
+      if (lineItems.length === 0) continue;
+      const result = await fulfillment.createFulfillment({
+        orderId,
+        lineItems,
+        ...(parcel.tracking_company ? { carrier: parcel.tracking_company } : {}),
+        ...(parcel.tracking_number ? { trackingNumber: parcel.tracking_number } : {}),
+        ...(parcel.tracking_url ? { trackingUrl: parcel.tracking_url } : {}),
+        status: "shipped",
+        metadata: { channelFulfillmentId: parcelId, storeId },
+      }, actor);
+      if (!result.ok) return PluginErr(result.error?.message ?? "Could not record the store's fulfilment.");
+      recorded.add(parcelId);
+      created += 1;
+    }
+    return Ok(created);
+  }
+
+  /** Every line with quantity still to ship, for a parcel whose own lines could not be matched. */
+  private async unfulfilledLines(lines: Array<{ id: string; quantity: number }>): Promise<Array<{ orderLineItemId: string; quantity: number }>> {
+    const ids = lines.map((line) => line.id);
+    const shipped = ids.length === 0 ? [] : await this.db
+      .select({ lineId: fulfillmentLineItems.orderLineItemId, quantity: sql<number>`coalesce(sum(${fulfillmentLineItems.quantity}), 0)::int` })
+      .from(fulfillmentLineItems)
+      .where(inArray(fulfillmentLineItems.orderLineItemId, ids))
+      .groupBy(fulfillmentLineItems.orderLineItemId);
+    const shippedBy = new Map(shipped.map((row) => [row.lineId, row.quantity]));
+    return lines.flatMap((line) => {
+      const remaining = line.quantity - (shippedBy.get(line.id) ?? 0);
+      return remaining > 0 ? [{ orderLineItemId: line.id, quantity: remaining }] : [];
+    });
+  }
+
+  /** 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,