@porulle/plugin-channel-connector 0.69.0 → 0.70.1

package/dist/service.d.ts

@@ -664,6 +664,15 @@ export declare class ChannelConnectorService {
      * 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>>;

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";
@@ -34,6 +34,15 @@ export const CHANNEL_INVENTORY_MAX_ITEMS_PER_INVOCATION = 20;
  * 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) {
@@ -2274,7 +2283,9 @@ export class ChannelConnectorService {
                 "products/delete",
                 "inventory_levels/update",
                 "orders/fulfilled",
+                "orders/partially_fulfilled",
                 "orders/cancelled",
+                "refunds/create",
                 "app/uninstalled",
             ], callbackUrl);
             if (!registration.ok) {
@@ -3880,7 +3891,7 @@ 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;
@@ -3896,13 +3907,19 @@ export class ChannelConnectorService {
                         await ordersService.changeStatus({ orderId, newStatus: "cancelled", reason: CHANNEL_ORDER_CANCELLED_REASON }, actor);
                     }
                 }
-                if (event.type === "orders/fulfilled") {
+                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);
+                    }
                 }
             }
         }
@@ -4170,7 +4187,15 @@ export class ChannelConnectorService {
         const existing = await this.db.select().from(channelRefundRequests).where(and(eq(channelRefundRequests.storeId, store.id), eq(channelRefundRequests.remoteRefundId, remoteRefundId)));
         if (existing[0])
             return Ok(existing[0]);
-        const lineData = Array.isArray(data.line_items) ? data.line_items : Array.isArray(data.lineItems) ? data.lineItems : [];
+        // Shopify names the refunded lines in `refund_line_items`, each with its order line under
+        // `line_item`; other providers send a flat `line_items`. Both reduce to { variant_id, quantity }.
+        const lineData = Array.isArray(data.refund_line_items)
+            ? data.refund_line_items.map((raw) => {
+                const entry = (raw ?? {});
+                const orderLine = (entry.line_item ?? {});
+                return { variant_id: orderLine.variant_id, product_id: orderLine.product_id, quantity: entry.quantity };
+            })
+            : Array.isArray(data.line_items) ? data.line_items : Array.isArray(data.lineItems) ? data.lineItems : [];
         const orderLines = await this.db.select().from(orderLineItems).where(eq(orderLineItems.orderId, orderId));
         const mappings = await this.db.select().from(channelEntityMap).where(and(eq(channelEntityMap.organizationId, orgId), eq(channelEntityMap.storeId, store.id)));
         const refundLines = [];
@@ -4325,6 +4350,69 @@ export class ChannelConnectorService {
         }
         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)));

package/package.json

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

package/src/service.ts

@@ -56,6 +56,8 @@ import {
   mediaAssets,
   optionTypes,
   optionValues,
+  fulfillmentLineItems,
+  fulfillmentRecords,
   orderLineItems,
   orders,
   prices,
@@ -130,6 +132,16 @@ export const CHANNEL_INVENTORY_MAX_ITEMS_PER_INVOCATION = 20;
  */
 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;
 
@@ -3189,7 +3201,9 @@ export class ChannelConnectorService {
         "products/delete",
         "inventory_levels/update",
         "orders/fulfilled",
+        "orders/partially_fulfilled",
         "orders/cancelled",
+        "refunds/create",
         "app/uninstalled",
       ], callbackUrl);
       if (!registration.ok) {
@@ -4985,10 +4999,10 @@ 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" | "cancelled"; 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/cancelled") {
@@ -5000,11 +5014,17 @@ export class ChannelConnectorService {
             await ordersService.changeStatus({ orderId, newStatus: "cancelled", reason: CHANNEL_ORDER_CANCELLED_REASON }, actor);
           }
         }
-        if (event.type === "orders/fulfilled") {
+        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") {
@@ -5294,7 +5314,15 @@ export class ChannelConnectorService {
     if (!remoteRefundId || !orderId) return PluginErr("Refund webhook is missing a mapped order or refund id.", "REFUND_MAPPING_MISSING");
     const existing = await this.db.select().from(channelRefundRequests).where(and(eq(channelRefundRequests.storeId, store.id), eq(channelRefundRequests.remoteRefundId, remoteRefundId)));
     if (existing[0]) return Ok(existing[0] as ChannelRefundRequest);
-    const lineData = Array.isArray(data.line_items) ? data.line_items : Array.isArray(data.lineItems) ? data.lineItems : [];
+    // Shopify names the refunded lines in `refund_line_items`, each with its order line under
+    // `line_item`; other providers send a flat `line_items`. Both reduce to { variant_id, quantity }.
+    const lineData = Array.isArray(data.refund_line_items)
+      ? data.refund_line_items.map((raw) => {
+        const entry = (raw ?? {}) as Record<string, unknown>;
+        const orderLine = (entry.line_item ?? {}) as Record<string, unknown>;
+        return { variant_id: orderLine.variant_id, product_id: orderLine.product_id, quantity: entry.quantity };
+      })
+      : Array.isArray(data.line_items) ? data.line_items : Array.isArray(data.lineItems) ? data.lineItems : [];
     const orderLines = await this.db.select().from(orderLineItems).where(eq(orderLineItems.orderId, orderId));
     const mappings = await this.db.select().from(channelEntityMap).where(and(eq(channelEntityMap.organizationId, orgId), eq(channelEntityMap.storeId, store.id)));
     const refundLines: Array<{ lineItemId: string; quantity: number }> = [];
@@ -5470,6 +5498,67 @@ export class ChannelConnectorService {
     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)));