@porulle/plugin-channel-connector 0.39.0 → 0.40.0

package/package.json

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

package/src/hooks.ts

@@ -1,10 +1,16 @@
 import { resolveOrgIdForCommerce } from "@porulle/core";
-import type { Actor, CommerceConfig, PluginHookRegistration } from "@porulle/core";
+import type {
+  Actor,
+  CommerceConfig,
+  HookContext,
+  PluginHookRegistration,
+} from "@porulle/core";
 import { and, eq, inArray } from "@porulle/core/drizzle";
 import { sellableEntities } from "@porulle/core/schema";
 import {
   ChannelConnectorService,
   type ChannelConnectorPluginOptions,
+  type ChannelPushTrigger,
   type ChannelStockLine,
 } from "./service.js";
 import {
@@ -12,6 +18,190 @@ import {
   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";
+
+/** The committed order, as much of it as the push needs. */
+interface PushOrderResult {
+  id: string;
+  status: string | undefined;
+  entityIds: string[];
+}
+
+/** The transition that produced a committed order, on `orders.afterStatusChange`. */
+interface StatusTransition {
+  fromStatus: string;
+  newStatus: string;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  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: unknown): PushOrderResult | null {
+  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: unknown): StatusTransition | null {
+  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: unknown): args is { context: HookContext } {
+  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: PushOrderResult,
+  context: HookContext,
+): Promise<void> {
+  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 is string => 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: ChannelPushTrigger): PluginHookRegistration[] {
+  switch (mode) {
+    case false:
+      return [];
+
+    case "create":
+      return [{
+        key: "orders.afterCreate",
+        async handler(args: unknown) {
+          const order = parseOrderResult(args);
+          if (order === null || !hasHookContext(args)) return;
+          await pushForOrder(order, args.context);
+        },
+      }];
+
+    case "payment":
+      return [{
+        key: "orders.afterCreate",
+        async handler(args: unknown) {
+          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: unknown) {
+          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: ChannelConnectorPluginOptions): PluginHookRegistration[] {
   return [{
     key: "checkout.beforePayment",
@@ -34,19 +224,9 @@ export function buildHooks(options: ChannelConnectorPluginOptions): PluginHookRe
       );
       return data;
     },
-  }, {
-    key: "orders.afterCreate",
-    async handler(args: unknown) {
-      const { result, context } = args as {
-        result: { id: string; lineItems?: Array<{ entityId: string }> };
-        context: { actor: Actor | null; commerceConfig?: CommerceConfig | null; db: ConstructorParameters<typeof ChannelConnectorService>[0]; services: Record<string, unknown>; jobs: { enqueue(task: string, input: Record<string, unknown>, options: { organizationId: string; concurrencyKey: string; supersedes: boolean }): Promise<string> } };
-      };
-      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 is string => 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: unknown) {
       const { data, context } = args as {

package/src/service.ts

@@ -224,8 +224,24 @@ 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;