@porulle/plugin-channel-connector 0.47.0 → 0.48.1

package/package.json

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

package/src/index.ts

@@ -104,11 +104,25 @@ export const CHANNEL_MAX_BATCHES_PER_SWEEP = 5_000;
 
 /** What one bounded batch reports back: whether the store is drained, how much work it did, and
  *  where it stopped. Everything here crosses a durable-step boundary, so it must stay JSON. */
+import type { CatalogConvergenceFailure } from "./service.js";
+
 interface BatchOutcome {
   exhausted: boolean;
   counted: number;
   cursor: unknown;
   warnings?: string[];
+  /**
+   * The entities this batch committed, in input order, failures excluded — so the caller can emit
+   * ONE message naming the page instead of one enqueue per product.
+   *
+   * Optional in the type and unconditional in the value the service returns. `undefined` means no
+   * batch produced an outcome (the initial `last` below, or a plugin build that predates this
+   * field); `[]` means a batch ran and committed nothing. A caller that collapses those two enqueues
+   * nothing and reports success.
+   */
+  entityIds?: string[];
+  /** The items that did not land, so the caller can record them against the run rather than drop them. */
+  failures?: CatalogConvergenceFailure[];
 }
 
 /**
@@ -321,6 +335,15 @@ export function channelConnectorPlugin(options: ChannelConnectorPluginOptions =
               counted: page.value.imported,
               cursor: page.value.cursor ?? null,
               ...(page.value.warnings ? { warnings: page.value.warnings } : {}),
+              // UNCONDITIONAL, unlike `warnings` and `failures` beside it. The step's return value is
+              // the only per-batch seam a host application has — `walkBatches` keeps just `last` — so
+              // this is where a page gets its identity. Omitting it when empty would make "this batch
+              // committed nothing" and "this plugin build does not report entities" the same
+              // `undefined` at the seam, and a caller that collapses those enqueues nothing and
+              // reports success. The service's own return declares it unconditional for the same
+              // reason; dropping it here would have undone that one line later.
+              entityIds: page.value.entityIds,
+              ...(page.value.failures ? { failures: page.value.failures } : {}),
             };
           },
         );

package/src/service.ts

@@ -324,6 +324,26 @@ interface CatalogConvergenceStats {
    * REJECT_FAILED_ROWS as against REJECT_EVERYTHING; this is the former.
    */
   failures: CatalogConvergenceFailure[];
+  /**
+   * The entities this batch actually COMMITTED, in input order, with failures excluded.
+   *
+   * It exists so a caller can name the page it just converged — one queue message carrying these
+   * ids instead of one enqueue per product. Everything about that use makes the exact membership
+   * load-bearing, so the ways it can be wrong are worth stating rather than discovering:
+   *
+   *  - **A failed item must not appear.** Every failure path above `continue`s before the push, so
+   *    an id is added only after the item's last write. An id here that was never committed makes
+   *    the consumer pay a model call for a row that does not exist.
+   *  - **Order is input order.** The page message is rebuilt from this array, so a stable order is
+   *    what makes the same page produce the same message on a Workflow retry.
+   *  - **No duplicates.** A connector that returns one `externalId` twice in a page would otherwise
+   *    put the same entity in the message twice, and the consumer would pay for it twice. The push
+   *    is de-duplicated on first occurrence.
+   *  - **It must stay JSON.** This crosses a durable step boundary as part of `BatchOutcome`.
+   *  - **It is per BATCH, never accumulated across a walk.** `walkBatches` keeps only `last`, so a
+   *    3,000-product store never builds a 3,000-element array against the 1 MiB step-result limit.
+   */
+  entityIds: string[];
 }
 
 type ImportResumePosition = { pageCursor: string | null; offset: number };
@@ -2420,6 +2440,18 @@ export class ChannelConnectorService {
     conflicts?: CatalogFieldConflict[];
     warnings?: string[];
     failures?: CatalogConvergenceFailure[];
+    /**
+     * The entities this batch committed — see `CatalogConvergenceStats.entityIds`.
+     *
+     * Declared on the BOUNDED overload only. This is the one a per-batch step wrapper calls, so it
+     * is the one with a page to name. The unbounded overload walks a whole catalogue and would hand
+     * back thousands of ids across a durable step boundary, which is the opposite of the point.
+     *
+     * Required rather than optional here, unlike its siblings, for the reason the implementation
+     * states: a caller must be able to tell "this batch committed nothing" from "this build does
+     * not report entities", and one of those is `[]` while the other is `undefined`.
+     */
+    entityIds: string[];
   }>>;
   async importCatalog(
     orgId: string,
@@ -2447,6 +2479,7 @@ export class ChannelConnectorService {
     conflicts?: CatalogFieldConflict[];
     warnings?: string[];
     failures?: CatalogConvergenceFailure[];
+    entityIds?: string[];
   }>> {
     const store = await this.getStoreRecord(orgId, storeId);
     if (!store || store.status !== "connected") {
@@ -2494,6 +2527,7 @@ export class ChannelConnectorService {
     const conflicts: CatalogFieldConflict[] = [];
     const warnings: string[] = [];
     const failures: CatalogConvergenceFailure[] = [];
+    const entityIds: string[] = [];
 
     while (remaining > 0) {
       const page = await connector.importCatalog(store as ChannelStore, pageCursor ?? undefined);
@@ -2523,6 +2557,7 @@ export class ChannelConnectorService {
       conflicts.push(...result.value.conflicts);
       warnings.push(...result.value.warnings);
       failures.push(...result.value.failures);
+      entityIds.push(...result.value.entityIds);
       offset += result.value.consumed;
 
       if (offset >= pageItems.length) {
@@ -2558,6 +2593,13 @@ export class ChannelConnectorService {
       // Always surfaced when non-empty. A silently dropped product is worse than the halt this
       // replaced: the caller must be able to see which externalIds did not land.
       ...(failures.length > 0 ? { failures } : {}),
+      // UNCONDITIONAL, unlike every optional field above it, and the asymmetry is deliberate.
+      // The caller turns this into one queue message naming the page it just converged. If the key
+      // were omitted when empty, a caller reading `outcome.entityIds` could not tell "this batch
+      // committed nothing" from "this plugin version does not report entities" — both read as
+      // `undefined`, and the second one silently produces an import that enqueues nothing. An
+      // empty array says the first; a missing key says the second. They deserve different answers.
+      entityIds,
     });
   }
 
@@ -2746,6 +2788,7 @@ export class ChannelConnectorService {
       conflicts: [],
       warnings: [],
       failures: [],   // a dry run converges nothing, so it can fail nothing
+      entityIds: [],  // ...and commits nothing, so it names nothing
     };
     const assets = await this.db.select().from(mediaAssets).where(eq(mediaAssets.organizationId, orgId));
     for (const item of items) {
@@ -2894,6 +2937,8 @@ export class ChannelConnectorService {
     const conflicts: CatalogFieldConflict[] = [];
     const warnings: string[] = [];
     const failures: CatalogConvergenceFailure[] = [];
+    const entityIds: string[] = [];
+    const committed = new Set<string>();
     for (const item of items) {
       consumed += 1;
       try {
@@ -3122,6 +3167,14 @@ export class ChannelConnectorService {
         eq(channelEntityMap.entityId, entityId),
         eq(channelEntityMap.kind, "variant"),
       ));
+      // LAST statement of the try, and that position is the whole guarantee: every failure path
+      // above reaches `continue` before here, so an id is recorded only once the item's writes are
+      // done. De-duplicated because a connector returning one externalId twice in a page would
+      // otherwise have the consumer pay for the same entity twice.
+      if (!committed.has(entityId)) {
+        committed.add(entityId);
+        entityIds.push(entityId);
+      }
       } catch (error) {
         // Anything the stages throw rather than returning. Same disposition: record it against the
         // item and carry on, so an unforeseen throw costs one product and not the remaining page.
@@ -3141,6 +3194,7 @@ export class ChannelConnectorService {
       conflicts,
       warnings,
       failures,
+      entityIds,
     });
   }