@porulle/plugin-channel-connector 0.57.1 → 0.59.0

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import { type ChannelConnectorPluginOptions } from "./service.js";
 export { ABSENT_ARCHIVE_FLOOR, ABSENT_ARCHIVE_FRACTION, planAbsentArchives } from "./deletion-policy.js";
-export { channelSyncHash } from "./service.js";
+export { channelSyncHash, withDistinctVariantSkus } from "./service.js";
 export type { AbsentArchivePlan } from "./deletion-policy.js";
 export { mockChannelConnector } from "./mock-connector.js";
 export type { MockChannelConnectorOptions } from "./mock-connector.js";

package/dist/index.js

@@ -8,7 +8,7 @@ import { ChannelConnectorService, catalogPushConcurrencyKey, CHANNEL_INVENTORY_M
 import { buildHooks } from "./hooks.js";
 import { oauthStateEventId, signState, verifyState } from "./oauth-state.js";
 export { ABSENT_ARCHIVE_FLOOR, ABSENT_ARCHIVE_FRACTION, planAbsentArchives } from "./deletion-policy.js";
-export { channelSyncHash } from "./service.js";
+export { channelSyncHash, withDistinctVariantSkus } from "./service.js";
 export { mockChannelConnector } from "./mock-connector.js";
 export { ChannelConnectorService, HERO_IMAGE_BYTE_CAP, selectImportImages, 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";

package/dist/service.d.ts

@@ -237,6 +237,18 @@ export interface CatalogPushPreviewResult {
 export declare function canExportTransition(from: ExportState, to: ExportState): boolean;
 export declare function canCatalogPushTransition(from: CatalogPushState, to: CatalogPushState): boolean;
 /** THE sync hash: every path that records or compares a `channel_entity_map.sync_hash` uses this. */
+/**
+ * A product whose own variants repeat a SKU would break the `(source_store_id, sku)` unique key and
+ * lose the whole product. Per item, group variants by SKU: the smallest externalId (string order)
+ * keeps it, every other variant becomes `${sku}-${externalId}`. Deterministic, independent of
+ * upstream order, and idempotent (a normalised item has no repeats left).
+ *
+ * Applied at the service's item intake — every `importCatalog` read and both converge entries — so
+ * converge, the sync hash and reconcile's `applyUpstreamVariantIdentity` all see the same variants.
+ * When only the host normalised, reconcile compared the stored suffixed SKU with the raw upstream one
+ * and recorded a `variants.sku` conflict on every pass.
+ */
+export declare function withDistinctVariantSkus(item: ChannelCatalogItem): ChannelCatalogItem;
 export declare function channelSyncHash(value: unknown): string;
 /**
  * The suffix a store's product takes when its handle is already another store's slug: the first
@@ -301,6 +313,8 @@ export declare class ChannelConnectorService {
     private readonly jobs;
     private readonly options;
     constructor(db: PluginDb, services: Record<string, unknown>, options?: ChannelConnectorPluginOptions, transaction?: PluginTxFn);
+    /** Every catalogue read goes through here, so each item leaves the intake normalised once. */
+    private readCatalogPage;
     getConnector(providerId: string): ChannelConnector | undefined;
     private get catalog();
     private get media();
@@ -436,7 +450,7 @@ export declare class ChannelConnectorService {
      * linked at entity level as `primary` plus to the variants it shows. The first photo of every
      * other variant comes back in `deferredMedia` for the host to land later.
      */
-    convergeCatalogPage(orgId: string, storeId: string, items: ChannelCatalogItem[], actor: Actor): Promise<PluginResult<CatalogPageConvergence>>;
+    convergeCatalogPage(orgId: string, storeId: string, rawItems: ChannelCatalogItem[], actor: Actor): Promise<PluginResult<CatalogPageConvergence>>;
     private importHeroes;
     importCatalog(orgId: string, storeId: string, actor: Actor, options: {
         maxItems: number;
@@ -501,6 +515,14 @@ export declare class ChannelConnectorService {
         synced: number;
         exhausted?: boolean;
     }>>;
+    /**
+     * One step of a store's inventory sync for a connector that pages its inventory: ONE page fetch,
+     * ONE mapping read for that page's variants, and ONE `inventory.setAbsoluteMany` (a constant
+     * number of statements, one `inventory.afterAdjustMany` for the page). The next page's cursor is
+     * stored on the store, so no step re-reads what an earlier one levelled — the old path re-read
+     * the whole inventory and every map row on every 20-level step.
+     */
+    private syncInventoryPage;
     handleWebhook(orgId: string, storeId: string, event: {
         id: string;
         type: string;

package/dist/service.js

@@ -88,6 +88,9 @@ function parseInventoryResumePosition(raw) {
         return { offset: 0 };
     try {
         const parsed = JSON.parse(raw);
+        if (typeof parsed === "object" && parsed !== null && "pageCursor" in parsed) {
+            return { offset: 0, pageCursor: typeof parsed.pageCursor === "string" ? parsed.pageCursor : null };
+        }
         if (typeof parsed === "object" && parsed !== null && "offset" in parsed) {
             return {
                 offset: typeof parsed.offset === "number" && parsed.offset >= 0 ? parsed.offset : 0,
@@ -143,6 +146,35 @@ function canonicalJson(value) {
     return JSON.stringify(value) ?? "null";
 }
 /** THE sync hash: every path that records or compares a `channel_entity_map.sync_hash` uses this. */
+/**
+ * A product whose own variants repeat a SKU would break the `(source_store_id, sku)` unique key and
+ * lose the whole product. Per item, group variants by SKU: the smallest externalId (string order)
+ * keeps it, every other variant becomes `${sku}-${externalId}`. Deterministic, independent of
+ * upstream order, and idempotent (a normalised item has no repeats left).
+ *
+ * Applied at the service's item intake — every `importCatalog` read and both converge entries — so
+ * converge, the sync hash and reconcile's `applyUpstreamVariantIdentity` all see the same variants.
+ * When only the host normalised, reconcile compared the stored suffixed SKU with the raw upstream one
+ * and recorded a `variants.sku` conflict on every pass.
+ */
+export function withDistinctVariantSkus(item) {
+    const keeper = new Map();
+    for (const variant of item.variants) {
+        if (variant.sku === undefined)
+            continue;
+        const held = keeper.get(variant.sku);
+        if (held === undefined || variant.externalId < held)
+            keeper.set(variant.sku, variant.externalId);
+    }
+    if (keeper.size === item.variants.filter((variant) => variant.sku !== undefined).length)
+        return item;
+    return {
+        ...item,
+        variants: item.variants.map((variant) => variant.sku === undefined || keeper.get(variant.sku) === variant.externalId
+            ? variant
+            : { ...variant, sku: `${variant.sku}-${variant.externalId}` }),
+    };
+}
 export function channelSyncHash(value) {
     return createHash("sha256").update(canonicalJson(value)).digest("hex");
 }
@@ -578,6 +610,13 @@ export class ChannelConnectorService {
         this.jobs = options.jobs ?? services.jobs;
         this.transact = transaction ?? ((fn) => this.db.transaction(fn));
     }
+    /** Every catalogue read goes through here, so each item leaves the intake normalised once. */
+    async readCatalogPage(connector, store, cursor) {
+        const page = await connector.importCatalog(store, cursor);
+        if (!page.ok)
+            return page;
+        return { ...page, value: { ...page.value, items: page.value.items.map(withDistinctVariantSkus) } };
+    }
     getConnector(providerId) {
         return this.connectors.get(providerId);
     }
@@ -2313,7 +2352,7 @@ export class ChannelConnectorService {
         const connector = this.connectors.get(store.provider);
         if (!connector)
             return PluginErr(`No connector registered for provider "${store.provider}".`);
-        const page = await connector.importCatalog(store, cursor ?? undefined);
+        const page = await this.readCatalogPage(connector, store, cursor ?? undefined);
         if (!page.ok)
             return PluginErr(page.error.message);
         return Ok({ items: page.value.items, nextCursor: page.value.nextCursor ?? null });
@@ -2328,7 +2367,9 @@ export class ChannelConnectorService {
      * linked at entity level as `primary` plus to the variants it shows. The first photo of every
      * other variant comes back in `deferredMedia` for the host to land later.
      */
-    async convergeCatalogPage(orgId, storeId, items, actor) {
+    async convergeCatalogPage(orgId, storeId, rawItems, actor) {
+        // A host may hand items it never read through this service's intake; the rule is idempotent.
+        const items = rawItems.map(withDistinctVariantSkus);
         const failures = [];
         const warnings = [];
         const entityByExternalId = new Map();
@@ -2555,7 +2596,7 @@ export class ChannelConnectorService {
             const items = [];
             let pageCursor = resume.pageCursor ?? undefined;
             do {
-                const page = await connector.importCatalog(store, pageCursor);
+                const page = await this.readCatalogPage(connector, store, pageCursor);
                 if (!page.ok)
                     return PluginErr(page.error.message);
                 items.push(...page.value.items);
@@ -2587,7 +2628,7 @@ export class ChannelConnectorService {
         const failures = [];
         const entityIds = [];
         while (remaining > 0) {
-            const page = await connector.importCatalog(store, pageCursor ?? undefined);
+            const page = await this.readCatalogPage(connector, store, pageCursor ?? undefined);
             if (!page.ok)
                 return PluginErr(page.error.message);
             const pageItems = page.value.items;
@@ -2750,7 +2791,7 @@ export class ChannelConnectorService {
             });
         }
         do {
-            const page = await connector.importCatalog(store, cursor);
+            const page = await this.readCatalogPage(connector, store, cursor);
             if (!page.ok)
                 return PluginErr(page.error.message);
             const converged = await this.convergeCatalogItems(orgId, storeId, page.value.items, actor, true, dryRun);
@@ -2979,7 +3020,8 @@ export class ChannelConnectorService {
         await claim("tag", listed((item) => item.tags ?? []), sql `join ${tags} t on t.slug = v.slug and t.organization_id = ${orgId}
         join ${entityTags} l on l.entity_id = v.entity_id and l.tag_id = t.id`);
     }
-    async convergeCatalogItems(orgId, storeId, items, actor, force = false, dryRun = false) {
+    async convergeCatalogItems(orgId, storeId, rawItems, actor, force = false, dryRun = false) {
+        const items = rawItems.map(withDistinctVariantSkus);
         if (dryRun)
             return this.estimateCatalogItems(orgId, storeId, items);
         // One converge, one taxonomy snapshot. Cleared HERE rather than left to the service's lifetime:
@@ -3331,7 +3373,7 @@ export class ChannelConnectorService {
         const items = [];
         let cursor;
         do {
-            const page = await connector.importCatalog(store, cursor);
+            const page = await this.readCatalogPage(connector, store, cursor);
             if (!page.ok)
                 return PluginErr(page.error.message);
             items.push(...page.value.items);
@@ -3552,6 +3594,8 @@ export class ChannelConnectorService {
         const connector = this.connectors.get(store.provider);
         if (!connector)
             return PluginErr(`No connector registered for provider "${store.provider}".`);
+        if (connector.fetchInventoryPage)
+            return this.syncInventoryPage(orgId, storeId, store, connector.fetchInventoryPage.bind(connector), actor);
         const inventory = await connector.fetchInventory(store);
         if (!inventory.ok)
             return PluginErr(inventory.error.message);
@@ -3613,6 +3657,49 @@ export class ChannelConnectorService {
         }).where(and(eq(connectedStores.organizationId, orgId), eq(connectedStores.id, storeId)));
         return Ok({ synced, exhausted });
     }
+    /**
+     * One step of a store's inventory sync for a connector that pages its inventory: ONE page fetch,
+     * ONE mapping read for that page's variants, and ONE `inventory.setAbsoluteMany` (a constant
+     * number of statements, one `inventory.afterAdjustMany` for the page). The next page's cursor is
+     * stored on the store, so no step re-reads what an earlier one levelled — the old path re-read
+     * the whole inventory and every map row on every 20-level step.
+     */
+    async syncInventoryPage(orgId, storeId, store, fetchPage, actor) {
+        const { pageCursor } = parseInventoryResumePosition(store.inventoryCursor);
+        const page = await fetchPage(store, pageCursor ?? null);
+        if (!page.ok)
+            return PluginErr(page.error.message);
+        const externalIds = [...new Set(page.value.levels.map((level) => level.externalId))];
+        const mappings = externalIds.length === 0 ? [] : await this.db.select({
+            externalId: channelEntityMap.externalId, kind: channelEntityMap.kind, entityId: channelEntityMap.entityId, variantId: channelEntityMap.variantId,
+        }).from(channelEntityMap).where(and(eq(channelEntityMap.organizationId, orgId), eq(channelEntityMap.storeId, storeId), inArray(channelEntityMap.externalId, externalIds)));
+        // A variant's own mapping wins over a product's mapping of the same external id.
+        const byExternalId = new Map();
+        for (const mapping of mappings) {
+            if (!byExternalId.has(mapping.externalId) || mapping.kind === "variant")
+                byExternalId.set(mapping.externalId, mapping);
+        }
+        const rows = page.value.levels.flatMap((level) => {
+            const mapping = byExternalId.get(level.externalId);
+            return mapping === undefined ? [] : [{
+                    entityId: mapping.entityId,
+                    ...(mapping.variantId ? { variantId: mapping.variantId } : {}),
+                    quantity: Math.max(0, level.available),
+                }];
+        });
+        const inventoryService = this.services.inventory;
+        const written = await inventoryService.setAbsoluteMany(rows, actor, undefined, { reason: `Inventory sync from ${store.provider}` });
+        if (!written.ok)
+            return PluginErr(written.error.message);
+        const synced = written.value.entities.reduce((total, entity) => total + entity.levels.length, 0);
+        const exhausted = page.value.nextCursor === null;
+        await this.db.update(connectedStores).set({
+            inventoryCursor: exhausted ? null : JSON.stringify({ pageCursor: page.value.nextCursor }),
+            ...(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);
         if (!store)

package/package.json

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

package/src/index.ts

@@ -55,7 +55,7 @@ type ChannelRouteContext = {
 };
 
 export { ABSENT_ARCHIVE_FLOOR, ABSENT_ARCHIVE_FRACTION, planAbsentArchives } from "./deletion-policy.js";
-export { channelSyncHash } from "./service.js";
+export { channelSyncHash, withDistinctVariantSkus } from "./service.js";
 export type { AbsentArchivePlan } from "./deletion-policy.js";
 export { mockChannelConnector } from "./mock-connector.js";
 export type { MockChannelConnectorOptions } from "./mock-connector.js";

package/src/service.ts

@@ -385,7 +385,7 @@ function encodeImportResumePosition(position: ImportResumePosition): string {
   return JSON.stringify(position);
 }
 
-type InventoryResumePosition = { offset: number };
+type InventoryResumePosition = { offset: number; pageCursor?: string | null };
 
 /** Resume position for bounded `syncInventory` — stored on `connected_stores.inventory_cursor`.
  *  Last-sync time lives on `connected_stores.lastSyncAt` (set when a run exhausts). */
@@ -393,6 +393,9 @@ function parseInventoryResumePosition(raw: string | null | undefined): Inventory
   if (!raw) return { offset: 0 };
   try {
     const parsed = JSON.parse(raw) as Partial<InventoryResumePosition>;
+    if (typeof parsed === "object" && parsed !== null && "pageCursor" in parsed) {
+      return { offset: 0, pageCursor: typeof parsed.pageCursor === "string" ? parsed.pageCursor : null };
+    }
     if (typeof parsed === "object" && parsed !== null && "offset" in parsed) {
       return {
         offset: typeof parsed.offset === "number" && parsed.offset >= 0 ? parsed.offset : 0,
@@ -657,6 +660,34 @@ function canonicalJson(value: unknown): string {
 }
 
 /** THE sync hash: every path that records or compares a `channel_entity_map.sync_hash` uses this. */
+/**
+ * A product whose own variants repeat a SKU would break the `(source_store_id, sku)` unique key and
+ * lose the whole product. Per item, group variants by SKU: the smallest externalId (string order)
+ * keeps it, every other variant becomes `${sku}-${externalId}`. Deterministic, independent of
+ * upstream order, and idempotent (a normalised item has no repeats left).
+ *
+ * Applied at the service's item intake — every `importCatalog` read and both converge entries — so
+ * converge, the sync hash and reconcile's `applyUpstreamVariantIdentity` all see the same variants.
+ * When only the host normalised, reconcile compared the stored suffixed SKU with the raw upstream one
+ * and recorded a `variants.sku` conflict on every pass.
+ */
+export function withDistinctVariantSkus(item: ChannelCatalogItem): ChannelCatalogItem {
+  const keeper = new Map<string, string>();
+  for (const variant of item.variants) {
+    if (variant.sku === undefined) continue;
+    const held = keeper.get(variant.sku);
+    if (held === undefined || variant.externalId < held) keeper.set(variant.sku, variant.externalId);
+  }
+  if (keeper.size === item.variants.filter((variant) => variant.sku !== undefined).length) return item;
+  return {
+    ...item,
+    variants: item.variants.map((variant) =>
+      variant.sku === undefined || keeper.get(variant.sku) === variant.externalId
+        ? variant
+        : { ...variant, sku: `${variant.sku}-${variant.externalId}` }),
+  };
+}
+
 export function channelSyncHash(value: unknown): string {
   return createHash("sha256").update(canonicalJson(value)).digest("hex");
 }
@@ -1175,6 +1206,13 @@ export class ChannelConnectorService {
     this.transact = transaction ?? ((fn) => this.db.transaction(fn));
   }
 
+  /** Every catalogue read goes through here, so each item leaves the intake normalised once. */
+  private async readCatalogPage(connector: ChannelConnector, store: ChannelStore, cursor: string | undefined): ReturnType<ChannelConnector["importCatalog"]> {
+    const page = await connector.importCatalog(store, cursor);
+    if (!page.ok) return page;
+    return { ...page, value: { ...page.value, items: page.value.items.map(withDistinctVariantSkus) } };
+  }
+
   getConnector(providerId: string): ChannelConnector | undefined {
     return this.connectors.get(providerId);
   }
@@ -3193,7 +3231,7 @@ export class ChannelConnectorService {
     if (!store || store.status !== "connected") return PluginErr("Connected store not found.", "NOT_FOUND");
     const connector = this.connectors.get(store.provider);
     if (!connector) return PluginErr(`No connector registered for provider "${store.provider}".`);
-    const page = await connector.importCatalog(store as ChannelStore, cursor ?? undefined);
+    const page = await this.readCatalogPage(connector, store as ChannelStore, cursor ?? undefined);
     if (!page.ok) return PluginErr(page.error.message);
     return Ok({ items: page.value.items, nextCursor: page.value.nextCursor ?? null });
   }
@@ -3211,9 +3249,11 @@ export class ChannelConnectorService {
   async convergeCatalogPage(
     orgId: string,
     storeId: string,
-    items: ChannelCatalogItem[],
+    rawItems: ChannelCatalogItem[],
     actor: Actor,
   ): Promise<PluginResult<CatalogPageConvergence>> {
+    // A host may hand items it never read through this service's intake; the rule is idempotent.
+    const items = rawItems.map(withDistinctVariantSkus);
     const failures: CatalogConvergenceFailure[] = [];
     const warnings: string[] = [];
     const entityByExternalId = new Map<string, string>();
@@ -3509,7 +3549,7 @@ export class ChannelConnectorService {
       const items: ChannelCatalogItem[] = [];
       let pageCursor: string | undefined = resume.pageCursor ?? undefined;
       do {
-        const page = await connector.importCatalog(store as ChannelStore, pageCursor);
+        const page = await this.readCatalogPage(connector, store as ChannelStore, pageCursor);
         if (!page.ok) return PluginErr(page.error.message);
         items.push(...page.value.items);
         pageCursor = page.value.nextCursor ?? undefined;
@@ -3543,7 +3583,7 @@ export class ChannelConnectorService {
     const entityIds: string[] = [];
 
     while (remaining > 0) {
-      const page = await connector.importCatalog(store as ChannelStore, pageCursor ?? undefined);
+      const page = await this.readCatalogPage(connector, store as ChannelStore, pageCursor ?? undefined);
       if (!page.ok) return PluginErr(page.error.message);
 
       const pageItems = page.value.items;
@@ -3729,7 +3769,7 @@ export class ChannelConnectorService {
       });
     }
     do {
-      const page = await connector.importCatalog(store as ChannelStore, cursor);
+      const page = await this.readCatalogPage(connector, store as ChannelStore, cursor);
       if (!page.ok) return PluginErr(page.error.message);
       const converged = await this.convergeCatalogItems(orgId, storeId, page.value.items, actor, true, dryRun);
       if (!converged.ok) return converged;
@@ -3981,11 +4021,12 @@ export class ChannelConnectorService {
   private async convergeCatalogItems(
     orgId: string,
     storeId: string,
-    items: ChannelCatalogItem[],
+    rawItems: ChannelCatalogItem[],
     actor: Actor,
     force = false,
     dryRun = false,
   ): Promise<PluginResult<CatalogConvergenceStats>> {
+    const items = rawItems.map(withDistinctVariantSkus);
     if (dryRun) return this.estimateCatalogItems(orgId, storeId, items);
     // One converge, one taxonomy snapshot. Cleared HERE rather than left to the service's lifetime:
     // the instance can outlive a batch on a warm isolate, and a taxonomy cached across batches would
@@ -4352,7 +4393,7 @@ export class ChannelConnectorService {
     const items: ChannelCatalogItem[] = [];
     let cursor: string | undefined;
     do {
-      const page = await connector.importCatalog(store as ChannelStore, cursor);
+      const page = await this.readCatalogPage(connector, store as ChannelStore, cursor);
       if (!page.ok) return PluginErr(page.error.message);
       items.push(...page.value.items);
       cursor = page.value.nextCursor ?? undefined;
@@ -4598,6 +4639,7 @@ export class ChannelConnectorService {
     if (!store || store.status !== "connected") return PluginErr("Connected store not found.", "NOT_FOUND");
     const connector = this.connectors.get(store.provider);
     if (!connector) return PluginErr(`No connector registered for provider "${store.provider}".`);
+    if (connector.fetchInventoryPage) return this.syncInventoryPage(orgId, storeId, store, connector.fetchInventoryPage.bind(connector), actor);
     const inventory = await connector.fetchInventory(store as ChannelStore);
     if (!inventory.ok) return PluginErr(inventory.error.message);
     const mappings = await this.db.select().from(channelEntityMap).where(and(
@@ -4666,6 +4708,65 @@ export class ChannelConnectorService {
     return Ok({ synced, exhausted });
   }
 
+  /**
+   * One step of a store's inventory sync for a connector that pages its inventory: ONE page fetch,
+   * ONE mapping read for that page's variants, and ONE `inventory.setAbsoluteMany` (a constant
+   * number of statements, one `inventory.afterAdjustMany` for the page). The next page's cursor is
+   * stored on the store, so no step re-reads what an earlier one levelled — the old path re-read
+   * the whole inventory and every map row on every 20-level step.
+   */
+  private async syncInventoryPage(
+    orgId: string,
+    storeId: string,
+    store: typeof connectedStores.$inferSelect,
+    fetchPage: NonNullable<ChannelConnector["fetchInventoryPage"]>,
+    actor: Actor,
+  ): Promise<PluginResult<{ synced: number; exhausted?: boolean }>> {
+    const { pageCursor } = parseInventoryResumePosition(store.inventoryCursor);
+    const page = await fetchPage(store as ChannelStore, pageCursor ?? null);
+    if (!page.ok) return PluginErr(page.error.message);
+    const externalIds = [...new Set(page.value.levels.map((level) => level.externalId))];
+    const mappings = externalIds.length === 0 ? [] : await this.db.select({
+      externalId: channelEntityMap.externalId, kind: channelEntityMap.kind, entityId: channelEntityMap.entityId, variantId: channelEntityMap.variantId,
+    }).from(channelEntityMap).where(and(
+      eq(channelEntityMap.organizationId, orgId),
+      eq(channelEntityMap.storeId, storeId),
+      inArray(channelEntityMap.externalId, externalIds),
+    ));
+    // A variant's own mapping wins over a product's mapping of the same external id.
+    const byExternalId = new Map<string, (typeof mappings)[number]>();
+    for (const mapping of mappings) {
+      if (!byExternalId.has(mapping.externalId) || mapping.kind === "variant") byExternalId.set(mapping.externalId, mapping);
+    }
+    const rows = page.value.levels.flatMap((level) => {
+      const mapping = byExternalId.get(level.externalId);
+      return mapping === undefined ? [] : [{
+        entityId: mapping.entityId,
+        ...(mapping.variantId ? { variantId: mapping.variantId } : {}),
+        quantity: Math.max(0, level.available),
+      }];
+    });
+    const inventoryService = this.services.inventory as {
+      setAbsoluteMany(
+        rows: ReadonlyArray<{ entityId: string; variantId?: string; quantity: number }>,
+        actor: Actor,
+        ctx?: undefined,
+        options?: { reason?: string },
+      ): Promise<{ ok: true; value: { entities: Array<{ levels: unknown[] }> } } | { ok: false; error: { message: string } }>;
+    };
+    const written = await inventoryService.setAbsoluteMany(rows, actor, undefined, { reason: `Inventory sync from ${store.provider}` });
+    if (!written.ok) return PluginErr(written.error.message);
+    const synced = written.value.entities.reduce((total, entity) => total + entity.levels.length, 0);
+
+    const exhausted = page.value.nextCursor === null;
+    await this.db.update(connectedStores).set({
+      inventoryCursor: exhausted ? null : JSON.stringify({ pageCursor: page.value.nextCursor }),
+      ...(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 }>> {
     const store = await this.getStoreRecord(orgId, storeId);
     if (!store) return PluginErr("Connected store not found.", "NOT_FOUND");