@porulle/plugin-channel-connector 0.30.0 → 0.31.0

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import { type ChannelConnectorPluginOptions } from "./service.js";
 export { mockChannelConnector } from "./mock-connector.js";
 export type { MockChannelConnectorOptions } from "./mock-connector.js";
-export { ChannelConnectorService, CATALOG_OUTBOUND_SUPPRESSION_WINDOW_MS, CATALOG_PUSH_BATCH_SIZES, CATALOG_PUSH_MAX_ATTEMPTS, canCatalogPushTransition, canExportTransition, catalogPushConcurrencyKey, catalogPushRetryDelayMs, isCatalogPushBreakerOpen, } from "./service.js";
+export { ChannelConnectorService, CATALOG_OUTBOUND_SUPPRESSION_WINDOW_MS, CATALOG_PUSH_BATCH_SIZES, CATALOG_PUSH_MAX_ATTEMPTS, canCatalogPushTransition, canExportTransition, catalogPushConcurrencyKey, catalogPushRetryDelayMs, CHANNEL_INVENTORY_MAX_ITEMS_PER_INVOCATION, isCatalogPushBreakerOpen, } from "./service.js";
 export { isValidCatalogMappingFieldPath, matchFieldPath, mergeCatalogFieldMapping, normalizeCatalogFieldMapping, compareCatalogFieldMappingSpecificity, providerCatalogFieldMappingDefaults, selectCatalogFieldMapping, validateCatalogMappingRow, } from "./catalog-field-mapping.js";
 export type { CatalogFieldMapping, CatalogFieldMappingInput, CatalogFieldMappingRow, CatalogFieldTarget, } from "./catalog-field-mapping.js";
 /** ~320 Neon HTTP subrequests per product against a 10,000 per-invocation cap → hard ceiling near 31; 20 leaves margin for heavier products. */

package/dist/index.js

@@ -4,11 +4,11 @@ import { z } from "@hono/zod-openapi";
 import { and, eq } from "@porulle/core/drizzle";
 import { processedWebhookEvents } from "@porulle/core/schema";
 import { channelCatalogPushEvents, channelCatalogPushes, channelCatalogConflicts, channelCatalogConflictEvents, channelEntityMap, channelExportEvents, channelOrderExports, channelRefundEvents, channelRefundRequests, connectedStores, } from "./schema.js";
-import { ChannelConnectorService, catalogPushConcurrencyKey, } from "./service.js";
+import { ChannelConnectorService, catalogPushConcurrencyKey, CHANNEL_INVENTORY_MAX_ITEMS_PER_INVOCATION, } from "./service.js";
 import { buildHooks } from "./hooks.js";
 import { oauthStateEventId, signState, verifyState } from "./oauth-state.js";
 export { mockChannelConnector } from "./mock-connector.js";
-export { ChannelConnectorService, CATALOG_OUTBOUND_SUPPRESSION_WINDOW_MS, CATALOG_PUSH_BATCH_SIZES, CATALOG_PUSH_MAX_ATTEMPTS, canCatalogPushTransition, canExportTransition, catalogPushConcurrencyKey, catalogPushRetryDelayMs, isCatalogPushBreakerOpen, } from "./service.js";
+export { ChannelConnectorService, CATALOG_OUTBOUND_SUPPRESSION_WINDOW_MS, CATALOG_PUSH_BATCH_SIZES, CATALOG_PUSH_MAX_ATTEMPTS, canCatalogPushTransition, canExportTransition, catalogPushConcurrencyKey, catalogPushRetryDelayMs, CHANNEL_INVENTORY_MAX_ITEMS_PER_INVOCATION, isCatalogPushBreakerOpen, } from "./service.js";
 export { isValidCatalogMappingFieldPath, matchFieldPath, mergeCatalogFieldMapping, normalizeCatalogFieldMapping, compareCatalogFieldMappingSpecificity, providerCatalogFieldMappingDefaults, selectCatalogFieldMapping, validateCatalogMappingRow, } from "./catalog-field-mapping.js";
 /** ~320 Neon HTTP subrequests per product against a 10,000 per-invocation cap → hard ceiling near 31; 20 leaves margin for heavier products. */
 export const CHANNEL_IMPORT_MAX_ITEMS_PER_INVOCATION = 20;
@@ -162,10 +162,21 @@ export function channelConnectorPlugin(options = {}) {
             concurrency: { key: (input) => String(input.storeId) },
             handler: async ({ input, ctx }) => {
                 const service = new ChannelConnectorService(ctx.db, ctx.services, options);
-                const result = await service.syncInventory(String(input.orgId), String(input.storeId), createSystemActor(String(input.orgId)));
+                const orgId = String(input.orgId);
+                const storeId = String(input.storeId);
+                const result = await service.syncInventory(orgId, storeId, createSystemActor(orgId), {
+                    maxItems: CHANNEL_INVENTORY_MAX_ITEMS_PER_INVOCATION,
+                });
                 if (!result.ok)
                     throw new Error(result.error);
-                return { output: { synced: result.value.synced } };
+                const jobs = ctx.services.jobs;
+                if (!result.value.exhausted) {
+                    await jobs.enqueue("channel/sync-inventory", { orgId, storeId }, {
+                        organizationId: orgId,
+                        concurrencyKey: storeId,
+                    });
+                }
+                return { output: { synced: result.value.synced, exhausted: result.value.exhausted } };
             },
         },
         {

package/dist/service.d.ts

@@ -8,6 +8,18 @@ export type CatalogPushState = ChannelCatalogPush["state"];
 export type CatalogConflictState = ChannelCatalogConflict["state"];
 export declare const CATALOG_PUSH_BATCH_SIZES: Record<string, number>;
 export declare const CATALOG_PUSH_MAX_ATTEMPTS = 8;
+/**
+ * How many inventory levels one `channel/sync-inventory` invocation may write before it persists a
+ * resume position and hands off to its own continuation.
+ *
+ * The catalog's bound exists because a single invocation ran out of subrequests. This one exists
+ * because a single invocation runs out of TIME: measured on the deployed Worker on 2026-09-14,
+ * instance 1428d7e0, `channel/sync-inventory` was killed by `WorkflowTimeoutError: Execution timed
+ * out after 600000ms` having written 232 of ~1,299 levels — 2.6 s per level, so a bound of 20 is
+ * roughly 52 s of work and a 1,000-product merchant becomes ~650 bounded invocations instead of one
+ * nine-hour one that discards everything if it fails.
+ */
+export declare const CHANNEL_INVENTORY_MAX_ITEMS_PER_INVOCATION = 20;
 export declare function catalogPushRetryDelayMs(attempts: number): number;
 export interface CatalogPushJobResult extends Record<string, unknown> {
     noop?: boolean;
@@ -247,8 +259,11 @@ export declare class ChannelConnectorService {
     listCatalogConflicts(orgId: string, storeId?: string, state?: ChannelCatalogConflict["state"]): Promise<PluginResult<ChannelCatalogConflict[]>>;
     resolveCatalogConflict(orgId: string, id: string, choose: "platform" | "store", actor: Pick<Actor, "userId">): Promise<PluginResult<ChannelCatalogConflict>>;
     private applyStoreConflictValue;
-    syncInventory(orgId: string, storeId: string, actor: Actor): Promise<PluginResult<{
+    syncInventory(orgId: string, storeId: string, actor: Actor, options?: {
+        maxItems?: number;
+    }): Promise<PluginResult<{
         synced: number;
+        exhausted?: boolean;
     }>>;
     handleWebhook(orgId: string, storeId: string, event: {
         id: string;

package/dist/service.js

@@ -14,6 +14,18 @@ export const CATALOG_PUSH_BATCH_SIZES = {
 const DEFAULT_CATALOG_PUSH_BATCH_SIZE = 50;
 const CATALOG_PUSH_BREAKER_RETRY_MS = 60_000;
 export const CATALOG_PUSH_MAX_ATTEMPTS = 8;
+/**
+ * How many inventory levels one `channel/sync-inventory` invocation may write before it persists a
+ * resume position and hands off to its own continuation.
+ *
+ * The catalog's bound exists because a single invocation ran out of subrequests. This one exists
+ * because a single invocation runs out of TIME: measured on the deployed Worker on 2026-09-14,
+ * instance 1428d7e0, `channel/sync-inventory` was killed by `WorkflowTimeoutError: Execution timed
+ * out after 600000ms` having written 232 of ~1,299 levels — 2.6 s per level, so a bound of 20 is
+ * roughly 52 s of work and a 1,000-product merchant becomes ~650 bounded invocations instead of one
+ * nine-hour one that discards everything if it fails.
+ */
+export const CHANNEL_INVENTORY_MAX_ITEMS_PER_INVOCATION = 20;
 const CATALOG_PUSH_RETRY_BASE_MS = 60_000;
 const CATALOG_PUSH_RETRY_MAX_MS = 60 * 60 * 1000;
 export function catalogPushRetryDelayMs(attempts) {
@@ -68,6 +80,27 @@ function parseImportResumePosition(raw) {
 function encodeImportResumePosition(position) {
     return JSON.stringify(position);
 }
+/** Resume position for bounded `syncInventory` — stored on `connected_stores.inventory_cursor`.
+ *  Last-sync time lives on `connected_stores.lastSyncAt` (set when a run exhausts). */
+function parseInventoryResumePosition(raw) {
+    if (!raw)
+        return { offset: 0 };
+    try {
+        const parsed = JSON.parse(raw);
+        if (typeof parsed === "object" && parsed !== null && "offset" in parsed) {
+            return {
+                offset: typeof parsed.offset === "number" && parsed.offset >= 0 ? parsed.offset : 0,
+            };
+        }
+    }
+    catch {
+        // Legacy value was an ISO timestamp written when a sync completed.
+    }
+    return { offset: 0 };
+}
+function encodeInventoryResumePosition(position) {
+    return JSON.stringify(position);
+}
 const exportTransitions = {
     pending: ["exported", "abandoned"],
     exported: ["confirmed", "failed", "abandoned"],
@@ -2375,7 +2408,7 @@ export class ChannelConnectorService {
         }
         return PluginErr(`Conflict field path "${conflict.fieldPath}" cannot be resolved to the store value.`, "UNSUPPORTED_CONFLICT_FIELD");
     }
-    async syncInventory(orgId, storeId, actor) {
+    async syncInventory(orgId, storeId, actor, options) {
         const store = await this.getStoreRecord(orgId, storeId);
         if (!store || store.status !== "connected")
             return PluginErr("Connected store not found.", "NOT_FOUND");
@@ -2387,11 +2420,40 @@ export class ChannelConnectorService {
             return PluginErr(inventory.error.message);
         const mappings = await this.db.select().from(channelEntityMap).where(and(eq(channelEntityMap.organizationId, orgId), eq(channelEntityMap.storeId, storeId)));
         const inventoryService = this.services.inventory;
+        const maxItems = options?.maxItems ?? CHANNEL_INVENTORY_MAX_ITEMS_PER_INVOCATION;
+        const levels = inventory.value;
+        let { offset } = parseInventoryResumePosition(store.inventoryCursor);
+        const entityIdsForSlice = (from, to) => {
+            const ids = new Set();
+            for (const level of levels.slice(from, to)) {
+                const mapping = mappings.find((entry) => entry.externalId === level.externalId);
+                if (mapping)
+                    ids.add(mapping.entityId);
+            }
+            return ids;
+        };
+        const loadedThrough = Math.min(offset + maxItems, levels.length);
+        const batchEntityIds = entityIdsForSlice(offset, loadedThrough);
+        const existingLevels = batchEntityIds.size === 0
+            ? []
+            : await this.db.select().from(inventoryLevels).where(and(eq(inventoryLevels.organizationId, orgId), inArray(inventoryLevels.entityId, [...batchEntityIds])));
         let synced = 0;
-        for (const level of inventory.value) {
+        let levelsWalked = 0;
+        let exhausted = false;
+        // No refill inside the loop: the window loaded above spans exactly `maxItems` levels and the
+        // walk breaks at `maxItems`, so `offset` can never pass `loadedThrough` within one invocation.
+        while (offset < levels.length) {
+            if (levelsWalked >= maxItems)
+                break;
+            const level = levels[offset];
+            offset += 1;
+            levelsWalked += 1;
             const mapping = mappings.find((entry) => entry.externalId === level.externalId);
             if (!mapping)
                 continue;
+            const current = existingLevels.find((entry) => entry.entityId === mapping.entityId && entry.variantId === (mapping.variantId ?? null));
+            if (current?.quantityOnHand === level.available)
+                continue;
             const result = await inventoryService.setAbsolute({
                 entityId: mapping.entityId,
                 ...(mapping.variantId ? { variantId: mapping.variantId } : {}),
@@ -2402,8 +2464,15 @@ export class ChannelConnectorService {
                 return PluginErr(result.error?.message ?? "Inventory sync failed.");
             synced += 1;
         }
-        await this.db.update(connectedStores).set({ inventoryCursor: new Date().toISOString(), lastSyncAt: new Date(), updatedAt: new Date() }).where(and(eq(connectedStores.organizationId, orgId), eq(connectedStores.id, storeId)));
-        return Ok({ synced });
+        if (offset >= levels.length)
+            exhausted = true;
+        const inventoryCursor = exhausted ? null : encodeInventoryResumePosition({ offset });
+        await this.db.update(connectedStores).set({
+            inventoryCursor,
+            ...(exhausted ? { lastSyncAt: new Date() } : {}),
+            updatedAt: new Date(),
+        }).where(and(eq(connectedStores.organizationId, orgId), eq(connectedStores.id, storeId)));
+        return Ok({ synced, exhausted });
     }
     async handleWebhook(orgId, storeId, event) {
         const store = await this.getStoreRecord(orgId, storeId);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@porulle/plugin-channel-connector",
-  "version": "0.30.0",
+  "version": "0.31.0",
   "license": "MIT",
   "type": "module",
   "exports": {
@@ -19,15 +19,15 @@
   "dependencies": {
     "@hono/zod-openapi": "^1.2.2",
     "hono": "^4.12.5",
-    "@porulle/core": "0.30.0"
+    "@porulle/core": "0.31.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/index.ts

@@ -29,6 +29,7 @@ import {
 import {
   ChannelConnectorService,
   catalogPushConcurrencyKey,
+  CHANNEL_INVENTORY_MAX_ITEMS_PER_INVOCATION,
   type CatalogConflictState,
   type ChannelComplianceData,
   type ChannelConnectorPluginOptions,
@@ -55,6 +56,7 @@ export {
   canExportTransition,
   catalogPushConcurrencyKey,
   catalogPushRetryDelayMs,
+  CHANNEL_INVENTORY_MAX_ITEMS_PER_INVOCATION,
   isCatalogPushBreakerOpen,
 } from "./service.js";
 export {
@@ -265,9 +267,20 @@ export function channelConnectorPlugin(options: ChannelConnectorPluginOptions =
       concurrency: { key: (input: Record<string, unknown>) => String(input.storeId) },
       handler: async ({ input, ctx }: { input: Record<string, unknown>; ctx: import("@porulle/core").TaskContext }) => {
         const service = new ChannelConnectorService(ctx.db, ctx.services, options);
-        const result = await service.syncInventory(String(input.orgId), String(input.storeId), createSystemActor(String(input.orgId)));
+        const orgId = String(input.orgId);
+        const storeId = String(input.storeId);
+        const result = await service.syncInventory(orgId, storeId, createSystemActor(orgId), {
+          maxItems: CHANNEL_INVENTORY_MAX_ITEMS_PER_INVOCATION,
+        });
         if (!result.ok) throw new Error(result.error);
-        return { output: { synced: result.value.synced } };
+        const jobs = ctx.services.jobs as JobsAdapter;
+        if (!result.value.exhausted) {
+          await jobs.enqueue("channel/sync-inventory", { orgId, storeId }, {
+            organizationId: orgId,
+            concurrencyKey: storeId,
+          });
+        }
+        return { output: { synced: result.value.synced, exhausted: result.value.exhausted } };
       },
     },
     {

package/src/service.ts

@@ -93,6 +93,20 @@ export const CATALOG_PUSH_BATCH_SIZES: Record<string, number> = {
 const DEFAULT_CATALOG_PUSH_BATCH_SIZE = 50;
 const CATALOG_PUSH_BREAKER_RETRY_MS = 60_000;
 export const CATALOG_PUSH_MAX_ATTEMPTS = 8;
+
+/**
+ * How many inventory levels one `channel/sync-inventory` invocation may write before it persists a
+ * resume position and hands off to its own continuation.
+ *
+ * The catalog's bound exists because a single invocation ran out of subrequests. This one exists
+ * because a single invocation runs out of TIME: measured on the deployed Worker on 2026-09-14,
+ * instance 1428d7e0, `channel/sync-inventory` was killed by `WorkflowTimeoutError: Execution timed
+ * out after 600000ms` having written 232 of ~1,299 levels — 2.6 s per level, so a bound of 20 is
+ * roughly 52 s of work and a 1,000-product merchant becomes ~650 bounded invocations instead of one
+ * nine-hour one that discards everything if it fails.
+ */
+export const CHANNEL_INVENTORY_MAX_ITEMS_PER_INVOCATION = 20;
+
 const CATALOG_PUSH_RETRY_BASE_MS = 60_000;
 const CATALOG_PUSH_RETRY_MAX_MS = 60 * 60 * 1000;
 
@@ -269,6 +283,29 @@ function encodeImportResumePosition(position: ImportResumePosition): string {
   return JSON.stringify(position);
 }
 
+type InventoryResumePosition = { offset: number };
+
+/** Resume position for bounded `syncInventory` — stored on `connected_stores.inventory_cursor`.
+ *  Last-sync time lives on `connected_stores.lastSyncAt` (set when a run exhausts). */
+function parseInventoryResumePosition(raw: string | null | undefined): InventoryResumePosition {
+  if (!raw) return { offset: 0 };
+  try {
+    const parsed = JSON.parse(raw) as Partial<InventoryResumePosition>;
+    if (typeof parsed === "object" && parsed !== null && "offset" in parsed) {
+      return {
+        offset: typeof parsed.offset === "number" && parsed.offset >= 0 ? parsed.offset : 0,
+      };
+    }
+  } catch {
+    // Legacy value was an ISO timestamp written when a sync completed.
+  }
+  return { offset: 0 };
+}
+
+function encodeInventoryResumePosition(position: InventoryResumePosition): string {
+  return JSON.stringify(position);
+}
+
 export interface BackfillCatalogOptions {
   dryRun?: boolean;
   resume?: boolean;
@@ -3159,7 +3196,8 @@ export class ChannelConnectorService {
     orgId: string,
     storeId: string,
     actor: Actor,
-  ): Promise<PluginResult<{ synced: number }>> {
+    options?: { maxItems?: number },
+  ): Promise<PluginResult<{ synced: number; exhausted?: boolean }>> {
     const store = await this.getStoreRecord(orgId, storeId);
     if (!store || store.status !== "connected") return PluginErr("Connected store not found.", "NOT_FOUND");
     const connector = this.connectors.get(store.provider);
@@ -3173,10 +3211,42 @@ export class ChannelConnectorService {
     const inventoryService = this.services.inventory as {
       setAbsolute(input: { entityId: string; variantId?: string; quantity: number; reason?: string }, actor: Actor): Promise<{ ok: boolean; error?: { message: string } }>;
     };
+    const maxItems = options?.maxItems ?? CHANNEL_INVENTORY_MAX_ITEMS_PER_INVOCATION;
+    const levels = inventory.value;
+    let { offset } = parseInventoryResumePosition(store.inventoryCursor);
+
+    const entityIdsForSlice = (from: number, to: number) => {
+      const ids = new Set<string>();
+      for (const level of levels.slice(from, to)) {
+        const mapping = mappings.find((entry) => entry.externalId === level.externalId);
+        if (mapping) ids.add(mapping.entityId);
+      }
+      return ids;
+    };
+    const loadedThrough = Math.min(offset + maxItems, levels.length);
+    const batchEntityIds = entityIdsForSlice(offset, loadedThrough);
+    const existingLevels = batchEntityIds.size === 0
+      ? []
+      : await this.db.select().from(inventoryLevels).where(and(
+        eq(inventoryLevels.organizationId, orgId),
+        inArray(inventoryLevels.entityId, [...batchEntityIds]),
+      ));
+
     let synced = 0;
-    for (const level of inventory.value) {
+    let levelsWalked = 0;
+    let exhausted = false;
+
+    // No refill inside the loop: the window loaded above spans exactly `maxItems` levels and the
+    // walk breaks at `maxItems`, so `offset` can never pass `loadedThrough` within one invocation.
+    while (offset < levels.length) {
+      if (levelsWalked >= maxItems) break;
+      const level = levels[offset]!;
+      offset += 1;
+      levelsWalked += 1;
       const mapping = mappings.find((entry) => entry.externalId === level.externalId);
       if (!mapping) continue;
+      const current = existingLevels.find((entry) => entry.entityId === mapping.entityId && entry.variantId === (mapping.variantId ?? null));
+      if (current?.quantityOnHand === level.available) continue;
       const result = await inventoryService.setAbsolute({
         entityId: mapping.entityId,
         ...(mapping.variantId ? { variantId: mapping.variantId } : {}),
@@ -3186,11 +3256,16 @@ export class ChannelConnectorService {
       if (!result.ok) return PluginErr(result.error?.message ?? "Inventory sync failed.");
       synced += 1;
     }
-    await this.db.update(connectedStores).set({ inventoryCursor: new Date().toISOString(), lastSyncAt: new Date(), updatedAt: new Date() }).where(and(
-      eq(connectedStores.organizationId, orgId),
-      eq(connectedStores.id, storeId),
-    ));
-    return Ok({ synced });
+
+    if (offset >= levels.length) exhausted = true;
+    const inventoryCursor = exhausted ? null : encodeInventoryResumePosition({ offset });
+    await this.db.update(connectedStores).set({
+      inventoryCursor,
+      ...(exhausted ? { lastSyncAt: new Date() } : {}),
+      updatedAt: new Date(),
+    }).where(and(eq(connectedStores.organizationId, orgId), eq(connectedStores.id, storeId)));
+
+    return Ok({ synced, exhausted });
   }
 
   async handleWebhook(orgId: string, storeId: string, event: { id: string; type: string; data: unknown }): Promise<PluginResult<{ processed: true; data?: ChannelComplianceData; redacted?: number }>> {