@porulle/plugin-channel-connector 0.39.0 → 0.40.0

package/dist/hooks.js

@@ -3,6 +3,160 @@ import { and, eq, inArray } from "@porulle/core/drizzle";
 import { sellableEntities } from "@porulle/core/schema";
 import { 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
+ * and its machine runs `pending_payment -> confirmed | cancelled`.
+ */
+const PENDING_PAYMENT = "pending_payment";
+function isRecord(value) {
+    return typeof value === "object" && value !== null;
+}
+/**
+ * Parse the committed order out of a hook payload rather than asserting its
+ * shape. The kernel is a trust boundary for this plugin: an order that arrives
+ * without an `id`, or whose line items are not the shape we expect, is skipped
+ * rather than pushed against a half-read payload.
+ *
+ * `orders.afterCreate` and `orders.afterStatusChange` both deliver the committed
+ * order as `result`, so one parser serves both.
+ */
+function parseOrderResult(args) {
+    if (!isRecord(args))
+        return null;
+    const { result } = args;
+    if (!isRecord(result))
+        return null;
+    const { id, status, lineItems } = result;
+    if (typeof id !== "string" || id === "")
+        return null;
+    const entityIds = Array.isArray(lineItems)
+        ? lineItems.flatMap((line) => isRecord(line) && typeof line.entityId === "string" ? [line.entityId] : [])
+        : [];
+    return {
+        id,
+        status: typeof status === "string" ? status : undefined,
+        entityIds,
+    };
+}
+/**
+ * Parse the transition from a hook payload. `data` carries it on
+ * `orders.afterStatusChange`; a payload without both statuses is not a
+ * transition this plugin can reason about, so it pushes nothing.
+ */
+function parseStatusTransition(args) {
+    if (!isRecord(args))
+        return null;
+    const { data } = args;
+    if (!isRecord(data))
+        return null;
+    const { fromStatus, newStatus } = data;
+    if (typeof fromStatus !== "string" || typeof newStatus !== "string")
+        return null;
+    return { fromStatus, newStatus };
+}
+/**
+ * Narrow a hook payload to one carrying the kernel's own `HookContext`.
+ *
+ * A type predicate rather than a cast: the capabilities it carries are live
+ * objects — a Drizzle handle and a jobs adapter — which cannot be validated by
+ * shape, so this checks that they are present and callable and lets the kernel's
+ * published type describe them. A payload missing either is skipped rather than
+ * pushed against.
+ */
+function hasHookContext(args) {
+    if (!isRecord(args))
+        return false;
+    const { context } = args;
+    if (!isRecord(context))
+        return false;
+    const { db, jobs } = context;
+    return (isRecord(db) &&
+        isRecord(jobs) &&
+        typeof jobs.enqueue === "function");
+}
+/**
+ * Enqueue one `channel/push-order` job per store that owns a line of this order.
+ * `concurrencyKey` + `supersedes` collapse repeats on the same order and store.
+ */
+async function pushForOrder(order, context) {
+    if (order.entityIds.length === 0)
+        return;
+    const orgId = resolveOrgIdForCommerce(context.actor, context.commerceConfig);
+    const entities = await context.db
+        .select({
+        id: sellableEntities.id,
+        sourceStoreId: sellableEntities.sourceStoreId,
+    })
+        .from(sellableEntities)
+        .where(and(eq(sellableEntities.organizationId, orgId), inArray(sellableEntities.id, order.entityIds)));
+    const stores = new Set(entities
+        .map((entity) => entity.sourceStoreId)
+        .filter((storeId) => storeId !== null));
+    await Promise.all([...stores].map((storeId) => context.jobs.enqueue("channel/push-order", { orgId, storeId, orderId: order.id }, {
+        organizationId: orgId,
+        concurrencyKey: `push:${order.id}:${storeId}`,
+        supersedes: true,
+    })));
+}
+/**
+ * The hooks that trigger the order push, by mode. The switch is exhaustive over
+ * `ChannelPushTrigger`, so a fourth mode fails to compile rather than silently
+ * registering nothing.
+ *
+ * `"payment"` registers BOTH hooks on purpose. An order created directly in
+ * `pending` — a store with no payment step, which is most consumers — never
+ * transitions out of `pending_payment`, so dropping `orders.afterCreate`
+ * entirely would silently stop pushing for them.
+ *
+ * On the transition side the predicate is `fromStatus === PENDING_PAYMENT`, not
+ * "the new status looks paid". That is exactly-once by construction: core
+ * commits the status with a compare-and-swap, so only one caller wins a given
+ * transition. Keying on the new status alone would re-push on every later move
+ * (`confirmed -> processing -> fulfilled`), and `exportOrder` short-circuits only
+ * on an already-`confirmed` export — one still `exported` is pushed again.
+ */
+function pushHooks(mode) {
+    switch (mode) {
+        case false:
+            return [];
+        case "create":
+            return [{
+                    key: "orders.afterCreate",
+                    async handler(args) {
+                        const order = parseOrderResult(args);
+                        if (order === null || !hasHookContext(args))
+                            return;
+                        await pushForOrder(order, args.context);
+                    },
+                }];
+        case "payment":
+            return [{
+                    key: "orders.afterCreate",
+                    async handler(args) {
+                        const order = parseOrderResult(args);
+                        if (order === null || !hasHookContext(args))
+                            return;
+                        // A gateway order waits for its notify; anything else is unchanged.
+                        if (order.status === PENDING_PAYMENT)
+                            return;
+                        await pushForOrder(order, args.context);
+                    },
+                }, {
+                    key: "orders.afterStatusChange",
+                    async handler(args) {
+                        const transition = parseStatusTransition(args);
+                        const order = parseOrderResult(args);
+                        if (transition === null || order === null || !hasHookContext(args))
+                            return;
+                        if (transition.fromStatus !== PENDING_PAYMENT)
+                            return;
+                        if (transition.newStatus === "cancelled")
+                            return;
+                        await pushForOrder(order, args.context);
+                    },
+                }];
+    }
+}
 export function buildHooks(options) {
     return [{
             key: "checkout.beforePayment",
@@ -14,16 +168,9 @@ export function buildHooks(options) {
                 await service.validateLineStock(resolveOrgIdForCommerce(context.actor, context.commerceConfig), data.lineItems, options.inventoryTimeoutMs);
                 return data;
             },
-        }, {
-            key: "orders.afterCreate",
-            async handler(args) {
-                const { result, context } = args;
-                const orgId = resolveOrgIdForCommerce(context.actor, context.commerceConfig);
-                const entities = await context.db.select({ id: sellableEntities.id, sourceStoreId: sellableEntities.sourceStoreId }).from(sellableEntities).where(and(eq(sellableEntities.organizationId, orgId), inArray(sellableEntities.id, (result.lineItems ?? []).map((line) => line.entityId))));
-                const stores = new Set(entities.map((entity) => entity.sourceStoreId).filter((storeId) => storeId !== null));
-                await Promise.all([...stores].map((storeId) => context.jobs.enqueue("channel/push-order", { orgId, storeId, orderId: result.id }, { organizationId: orgId, concurrencyKey: `push:${result.id}:${storeId}`, supersedes: true })));
-            },
-        }, {
+        },
+        ...pushHooks(options.pushOrderOn ?? "payment"),
+        {
             key: "catalog.beforeUpdate",
             handler(args) {
                 const { data, context } = args;

package/dist/service.d.ts

@@ -100,7 +100,22 @@ export interface ChannelConnectorPluginOptions {
     newStoreDays?: number;
     driftAlertThreshold?: number;
     reconcileJitterWindowMs?: number;
+    /**
+     * When the order push fires. Default `"payment"`.
+     *
+     * - `"payment"` — an order created in `pending_payment` is NOT pushed; it is
+     *   pushed when it leaves that state for anything but `cancelled`. An order
+     *   created in `pending` is pushed on creation, as before, because a store
+     *   with no payment step has no transition to hang the push on.
+     * - `"create"` — the pre-0.40.0 trigger: push as soon as the order row exists,
+     *   whatever its status.
+     * - `false` — never push automatically; the consumer enqueues
+     *   `channel/push-order` itself.
+     */
+    pushOrderOn?: ChannelPushTrigger;
 }
+/** When {@link ChannelConnectorPluginOptions.pushOrderOn} fires the order push. */
+export type ChannelPushTrigger = "create" | "payment" | false;
 export interface ChannelStockLine {
     entityId: string;
     variantId?: string;