@porulle/plugin-channel-connector 0.27.0 → 0.29.0

package/dist/index.d.ts

@@ -4,6 +4,8 @@ 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 { 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. */
+export declare const CHANNEL_IMPORT_MAX_ITEMS_PER_INVOCATION = 20;
 export { signState, verifyState } from "./oauth-state.js";
 export type { BackfillCatalogOptions, BackfillCatalogReport, BuildCatalogPushItemsOptions, BuildCatalogPushItemsResult, CatalogPushAssemblyField, CatalogPushAssemblyImage, CatalogPushAssemblyItem, CatalogPushPreviewBefore, CatalogPushPreviewBeforeStatus, CatalogPushPreviewDiff, CatalogPushPreviewItem, CatalogPushPreviewResult, CatalogPushPreviewUnavailable, PushCatalogToStoreResult, CatalogPushJobResult, CatalogFieldConflict, CatalogFieldSkip, CatalogPushFieldSkip, CatalogPushSkipReason, CatalogConflictState, CatalogWriteSettings, ChannelComplianceData, ChannelConnectorPluginOptions, ChannelStockLine, ExportState, PublicConnectedStore, ReconcileReport, } from "./service.js";
 export type { OAuthStatePayload, OAuthStateResult } from "./oauth-state.js";

package/dist/index.js

@@ -10,6 +10,8 @@ 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 { 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;
 export { signState, verifyState } from "./oauth-state.js";
 function unwrap(result) {
     if (result.ok)
@@ -88,13 +90,26 @@ export function channelConnectorPlugin(options = {}) {
             concurrency: { key: (input) => String(input.storeId), supersedes: true },
             handler: async ({ input, ctx }) => {
                 const service = new ChannelConnectorService(ctx.db, ctx.services, options);
-                const result = await service.importCatalog(String(input.orgId), String(input.storeId), createSystemActor(String(input.orgId)));
+                const orgId = String(input.orgId);
+                const storeId = String(input.storeId);
+                const result = await service.importCatalog(orgId, storeId, createSystemActor(orgId), {
+                    maxItems: CHANNEL_IMPORT_MAX_ITEMS_PER_INVOCATION,
+                });
                 if (!result.ok)
                     throw new Error(result.error);
+                if (!result.value.exhausted) {
+                    const jobs = ctx.services.jobs;
+                    await jobs.enqueue("channel/import-catalog", { orgId, storeId }, {
+                        organizationId: orgId,
+                        concurrencyKey: storeId,
+                        supersedes: true,
+                    });
+                }
                 return {
                     output: {
                         imported: result.value.imported,
                         cursor: result.value.cursor,
+                        exhausted: result.value.exhausted,
                         ...(result.value.warnings ? { warnings: result.value.warnings } : {}),
                     },
                 };

package/dist/schema.js

@@ -1,4 +1,5 @@
 import { boolean, index, integer, jsonb, pgTable, text, timestamp, uniqueIndex, uuid, sql, } from "@porulle/core/drizzle";
+import { sellableEntities } from "@porulle/core/schema";
 export const connectedStores = pgTable("connected_stores", {
     id: uuid("id").defaultRandom().primaryKey(),
     organizationId: text("organization_id").notNull(),
@@ -29,7 +30,7 @@ export const channelEntityMap = pgTable("channel_entity_map", {
     storeId: uuid("store_id").references(() => connectedStores.id, { onDelete: "cascade" }).notNull(),
     kind: text("kind", { enum: ["entity", "variant"] }).notNull(),
     externalId: text("external_id").notNull(),
-    entityId: uuid("entity_id").notNull(),
+    entityId: uuid("entity_id").references(() => sellableEntities.id, { onDelete: "cascade" }).notNull(),
     variantId: uuid("variant_id"),
     lastSyncedAt: timestamp("last_synced_at", { withTimezone: true }).defaultNow().notNull(),
     syncHash: text("sync_hash").notNull(),

package/dist/service.d.ts

@@ -216,7 +216,17 @@ export declare class ChannelConnectorService {
     getStore(orgId: string, id: string): Promise<PluginResult<PublicConnectedStore>>;
     listStores(orgId: string): Promise<PluginResult<PublicConnectedStore[]>>;
     validateLineStock(orgId: string, lines: ChannelStockLine[], timeoutMs?: number): Promise<void>;
-    importCatalog(orgId: string, storeId: string, actor: Actor): Promise<PluginResult<{
+    importCatalog(orgId: string, storeId: string, actor: Actor, options: {
+        maxItems: number;
+    }): Promise<PluginResult<{
+        imported: number;
+        cursor: string | null;
+        exhausted: boolean;
+        skipped?: CatalogFieldSkip[];
+        conflicts?: CatalogFieldConflict[];
+        warnings?: string[];
+    }>>;
+    importCatalog(orgId: string, storeId: string, actor: Actor, options?: undefined): Promise<PluginResult<{
         imported: number;
         cursor: string | null;
         skipped?: CatalogFieldSkip[];

package/dist/service.js

@@ -48,6 +48,26 @@ export function isCatalogPushBreakerOpen(breakerState) {
 function catalogPushBatchSize(provider) {
     return CATALOG_PUSH_BATCH_SIZES[provider] ?? DEFAULT_CATALOG_PUSH_BATCH_SIZE;
 }
+function parseImportResumePosition(raw) {
+    if (!raw)
+        return { pageCursor: null, offset: 0 };
+    try {
+        const parsed = JSON.parse(raw);
+        if (typeof parsed === "object" && parsed !== null && "offset" in parsed) {
+            return {
+                pageCursor: parsed.pageCursor ?? null,
+                offset: typeof parsed.offset === "number" && parsed.offset >= 0 ? parsed.offset : 0,
+            };
+        }
+    }
+    catch {
+        // Legacy bare page cursor.
+    }
+    return { pageCursor: raw, offset: 0 };
+}
+function encodeImportResumePosition(position) {
+    return JSON.stringify(position);
+}
 const exportTransitions = {
     pending: ["exported", "abandoned"],
     exported: ["confirmed", "failed", "abandoned"],
@@ -72,6 +92,8 @@ export function canCatalogPushTransition(from, to) {
 function hash(value) {
     return createHash("sha256").update(JSON.stringify(value)).digest("hex");
 }
+/** Mid-import map rows carry this until convergence finishes; must not equal any real remote hash. */
+const PENDING_ENTITY_MAP_SYNC_HASH = "";
 export const CATALOG_OUTBOUND_SUPPRESSION_WINDOW_MS = 15 * 60 * 1000;
 function normalizeCanonicalValue(value) {
     if (typeof value === "string")
@@ -1536,7 +1558,7 @@ export class ChannelConnectorService {
             }
         }));
     }
-    async importCatalog(orgId, storeId, actor) {
+    async importCatalog(orgId, storeId, actor, options) {
         const store = await this.getStoreRecord(orgId, storeId);
         if (!store || store.status !== "connected") {
             return PluginErr("Connected store not found.", "NOT_FOUND");
@@ -1544,28 +1566,97 @@ export class ChannelConnectorService {
         const connector = this.connectors.get(store.provider);
         if (!connector)
             return PluginErr(`No connector registered for provider "${store.provider}".`);
-        const items = [];
-        let cursor = store.catalogCursor ?? undefined;
-        do {
-            const page = await connector.importCatalog(store, cursor);
+        const maxItems = options?.maxItems;
+        const bounded = maxItems !== undefined;
+        if (!bounded) {
+            const resume = parseImportResumePosition(store.catalogCursor);
+            const items = [];
+            let pageCursor = resume.pageCursor ?? undefined;
+            do {
+                const page = await connector.importCatalog(store, pageCursor);
+                if (!page.ok)
+                    return PluginErr(page.error.message);
+                items.push(...page.value.items);
+                pageCursor = page.value.nextCursor ?? undefined;
+            } while (pageCursor);
+            const result = await this.convergeCatalogItems(orgId, storeId, items, actor);
+            if (!result.ok)
+                return result;
+            await this.db
+                .update(connectedStores)
+                .set({ catalogCursor: null, lastSyncAt: new Date(), updatedAt: new Date() })
+                .where(and(eq(connectedStores.organizationId, orgId), eq(connectedStores.id, storeId)));
+            return Ok({
+                imported: result.value.imported,
+                cursor: null,
+                ...(result.value.skipped.length > 0 ? { skipped: uniqueSkipped(result.value.skipped) } : {}),
+                ...(result.value.conflicts.length > 0 ? { conflicts: result.value.conflicts } : {}),
+                ...(result.value.warnings.length > 0 ? { warnings: result.value.warnings } : {}),
+            });
+        }
+        let { pageCursor, offset } = parseImportResumePosition(store.catalogCursor);
+        let remaining = maxItems;
+        let exhausted = false;
+        let totalImported = 0;
+        const skipped = [];
+        const conflicts = [];
+        const warnings = [];
+        while (remaining > 0) {
+            const page = await connector.importCatalog(store, pageCursor ?? undefined);
             if (!page.ok)
                 return PluginErr(page.error.message);
-            items.push(...page.value.items);
-            cursor = page.value.nextCursor ?? undefined;
-        } while (cursor);
-        const result = await this.convergeCatalogItems(orgId, storeId, items, actor);
-        if (!result.ok)
-            return result;
+            const pageItems = page.value.items;
+            const slice = pageItems.slice(offset);
+            const batchSize = Math.min(remaining, slice.length);
+            if (batchSize === 0) {
+                if (page.value.nextCursor) {
+                    pageCursor = page.value.nextCursor;
+                    offset = 0;
+                    continue;
+                }
+                exhausted = true;
+                break;
+            }
+            const batch = slice.slice(0, batchSize);
+            const result = await this.convergeCatalogItems(orgId, storeId, batch, actor);
+            if (!result.ok)
+                return result;
+            totalImported += result.value.imported;
+            remaining -= result.value.consumed;
+            skipped.push(...result.value.skipped);
+            conflicts.push(...result.value.conflicts);
+            warnings.push(...result.value.warnings);
+            offset += result.value.consumed;
+            if (offset >= pageItems.length) {
+                if (page.value.nextCursor) {
+                    pageCursor = page.value.nextCursor;
+                    offset = 0;
+                }
+                else {
+                    exhausted = true;
+                }
+            }
+            if (remaining === 0)
+                break;
+            if (exhausted)
+                break;
+        }
+        const catalogCursor = exhausted ? null : encodeImportResumePosition({ pageCursor, offset });
         await this.db
             .update(connectedStores)
-            .set({ catalogCursor: null, lastSyncAt: new Date(), updatedAt: new Date() })
+            .set({
+            catalogCursor,
+            ...(exhausted ? { lastSyncAt: new Date() } : {}),
+            updatedAt: new Date(),
+        })
             .where(and(eq(connectedStores.organizationId, orgId), eq(connectedStores.id, storeId)));
         return Ok({
-            imported: result.value.imported,
-            cursor: null,
-            ...(result.value.skipped.length > 0 ? { skipped: uniqueSkipped(result.value.skipped) } : {}),
-            ...(result.value.conflicts.length > 0 ? { conflicts: result.value.conflicts } : {}),
-            ...(result.value.warnings.length > 0 ? { warnings: result.value.warnings } : {}),
+            imported: totalImported,
+            cursor: catalogCursor,
+            exhausted,
+            ...(skipped.length > 0 ? { skipped: uniqueSkipped(skipped) } : {}),
+            ...(conflicts.length > 0 ? { conflicts } : {}),
+            ...(warnings.length > 0 ? { warnings } : {}),
         });
     }
     async promoteLegacyAttributes(orgId, storeId, actor, dryRun) {
@@ -1726,12 +1817,14 @@ export class ChannelConnectorService {
             attributesCreated: 0,
             mediaImported: 0,
             variantsGivenOptionValues: 0,
+            consumed: 0,
             skipped: [],
             conflicts: [],
             warnings: [],
         };
         const assets = await this.db.select().from(mediaAssets).where(eq(mediaAssets.organizationId, orgId));
         for (const item of items) {
+            stats.consumed += 1;
             const [entityMapping] = await this.db.select().from(channelEntityMap).where(and(eq(channelEntityMap.organizationId, orgId), eq(channelEntityMap.storeId, storeId), eq(channelEntityMap.kind, "entity"), eq(channelEntityMap.externalId, item.externalId)));
             if (!entityMapping) {
                 stats.imported += 1;
@@ -1855,44 +1948,75 @@ export class ChannelConnectorService {
         let attributesCreated = 0;
         let mediaImported = 0;
         let variantsGivenOptionValues = 0;
+        let consumed = 0;
         const skipped = [];
         const conflicts = [];
         const warnings = [];
         for (const item of items) {
+            consumed += 1;
             const remoteHash = hash(item);
             const existing = await this.db
                 .select()
                 .from(channelEntityMap)
                 .where(and(eq(channelEntityMap.organizationId, orgId), eq(channelEntityMap.storeId, storeId), eq(channelEntityMap.kind, "entity"), eq(channelEntityMap.externalId, item.externalId)));
-            const entityMapping = existing.find((entry) => entry.kind === "entity");
+            let entityMapping = existing.find((entry) => entry.kind === "entity");
             let entityId;
             let isNew = false;
+            let adoptedOrphan = false;
             let entityTouched = false;
             let existingEntity;
             if (entityMapping) {
                 const [entity] = await this.db.select().from(sellableEntities).where(and(eq(sellableEntities.organizationId, orgId), eq(sellableEntities.id, entityMapping.entityId)));
                 if (!entity) {
-                    warnings.push(`Skipped "${item.externalId}": mapped entity ${entityMapping.entityId} no longer exists.`);
-                    continue;
+                    await this.db.delete(channelEntityMap).where(and(eq(channelEntityMap.organizationId, orgId), eq(channelEntityMap.storeId, storeId), eq(channelEntityMap.entityId, entityMapping.entityId)));
+                    entityMapping = undefined;
+                }
+                else {
+                    entityId = entityMapping.entityId;
+                    existingEntity = entity;
                 }
-                entityId = entityMapping.entityId;
-                existingEntity = entity;
             }
-            else {
-                const status = item.status;
-                const entity = await this.catalog.create({
-                    type: "product",
-                    slug: item.slug,
-                    sourceStoreId: storeId,
-                    metadata: mergeMetadata(undefined, item.metadata ?? {}),
-                    ...(status !== undefined ? { status, isVisible: status === "active" } : {}),
-                }, actor);
-                if (!entity.ok)
-                    return PluginErr(entity.error.message);
-                entityId = entity.value.id;
-                isNew = true;
-                imported += 1;
-                entityTouched = true;
+            if (entityId === undefined) {
+                const [orphan] = await this.db.select().from(sellableEntities).where(and(eq(sellableEntities.organizationId, orgId), eq(sellableEntities.sourceStoreId, storeId), eq(sellableEntities.slug, item.slug)));
+                if (orphan) {
+                    entityId = orphan.id;
+                    existingEntity = orphan;
+                    adoptedOrphan = true;
+                }
+                else {
+                    const status = item.status;
+                    try {
+                        entityId = await this.transact(async (tx) => {
+                            const txContext = createTxContext(tx, { actor });
+                            const created = await this.catalog.create({
+                                type: "product",
+                                slug: item.slug,
+                                sourceStoreId: storeId,
+                                metadata: mergeMetadata(undefined, item.metadata ?? {}),
+                                ...(status !== undefined ? { status, isVisible: status === "active" } : {}),
+                            }, actor, txContext);
+                            if (!created.ok)
+                                throw new Error(created.error.message);
+                            await tx.insert(channelEntityMap).values({
+                                organizationId: orgId,
+                                storeId,
+                                kind: "entity",
+                                externalId: item.externalId,
+                                entityId: created.value.id,
+                                syncHash: PENDING_ENTITY_MAP_SYNC_HASH,
+                                heldFieldPaths: [],
+                                forcedPushFieldPaths: [],
+                            });
+                            return created.value.id;
+                        });
+                    }
+                    catch (error) {
+                        return PluginErr(error instanceof Error ? error.message : "Failed to create catalog entity.");
+                    }
+                    isNew = true;
+                    imported += 1;
+                    entityTouched = true;
+                }
             }
             const ownershipBeforeSeed = await this.catalog.resolveFieldOwners(entityId, storeId);
             const seedPaths = importedFieldPaths(item).filter((path) => !ownershipBeforeSeed.has(path));
@@ -1989,6 +2113,14 @@ export class ChannelConnectorService {
             const latestRevisionAt = revisionMarkers.at(-1)?.createdAt;
             const lastSyncedAt = latestRevisionAt ?? entityMapping?.lastSyncedAt ?? new Date();
             if (isNew) {
+                await this.db.update(channelEntityMap).set({
+                    syncHash: remoteHash,
+                    lastSyncedAt,
+                    heldFieldPaths: heldSharedPaths,
+                    forcedPushFieldPaths: survivingForcedPaths,
+                }).where(and(eq(channelEntityMap.organizationId, orgId), eq(channelEntityMap.storeId, storeId), eq(channelEntityMap.kind, "entity"), eq(channelEntityMap.externalId, item.externalId), eq(channelEntityMap.entityId, entityId)));
+            }
+            else if (adoptedOrphan) {
                 await this.db.insert(channelEntityMap).values({
                     organizationId: orgId,
                     storeId,
@@ -2018,6 +2150,7 @@ export class ChannelConnectorService {
             attributesCreated,
             mediaImported,
             variantsGivenOptionValues,
+            consumed,
             skipped,
             conflicts,
             warnings,

package/package.json

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

package/src/index.ts

@@ -73,6 +73,9 @@ export type {
   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. */
+export const CHANNEL_IMPORT_MAX_ITEMS_PER_INVOCATION = 20;
+
 export { signState, verifyState } from "./oauth-state.js";
 export type {
   BackfillCatalogOptions,
@@ -193,12 +196,25 @@ export function channelConnectorPlugin(options: ChannelConnectorPluginOptions =
       concurrency: { key: (input: Record<string, unknown>) => String(input.storeId), supersedes: true },
       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.importCatalog(String(input.orgId), String(input.storeId), createSystemActor(String(input.orgId)));
+        const orgId = String(input.orgId);
+        const storeId = String(input.storeId);
+        const result = await service.importCatalog(orgId, storeId, createSystemActor(orgId), {
+          maxItems: CHANNEL_IMPORT_MAX_ITEMS_PER_INVOCATION,
+        });
         if (!result.ok) throw new Error(result.error);
+        if (!result.value.exhausted) {
+          const jobs = ctx.services.jobs as JobsAdapter;
+          await jobs.enqueue("channel/import-catalog", { orgId, storeId }, {
+            organizationId: orgId,
+            concurrencyKey: storeId,
+            supersedes: true,
+          });
+        }
         return {
           output: {
             imported: result.value.imported,
             cursor: result.value.cursor,
+            exhausted: result.value.exhausted,
             ...(result.value.warnings ? { warnings: result.value.warnings } : {}),
           },
         };

package/src/schema.ts

@@ -11,6 +11,7 @@ import {
   sql,
 } from "@porulle/core/drizzle";
 import type { ChannelPushCatalogItem, FieldPath } from "@porulle/core";
+import { sellableEntities } from "@porulle/core/schema";
 import type { CatalogFieldMapping } from "./catalog-field-mapping.js";
 
 export const connectedStores = pgTable(
@@ -50,7 +51,7 @@ export const channelEntityMap = pgTable(
     storeId: uuid("store_id").references(() => connectedStores.id, { onDelete: "cascade" }).notNull(),
     kind: text("kind", { enum: ["entity", "variant"] }).notNull(),
     externalId: text("external_id").notNull(),
-    entityId: uuid("entity_id").notNull(),
+    entityId: uuid("entity_id").references(() => sellableEntities.id, { onDelete: "cascade" }).notNull(),
     variantId: uuid("variant_id"),
     lastSyncedAt: timestamp("last_synced_at", { withTimezone: true }).defaultNow().notNull(),
     syncHash: text("sync_hash").notNull(),

package/src/service.ts

@@ -241,11 +241,34 @@ interface CatalogConvergenceStats {
   attributesCreated: number;
   mediaImported: number;
   variantsGivenOptionValues: number;
+  consumed: number;
   skipped: CatalogFieldSkip[];
   conflicts: CatalogFieldConflict[];
   warnings: string[];
 }
 
+type ImportResumePosition = { pageCursor: string | null; offset: number };
+
+function parseImportResumePosition(raw: string | null | undefined): ImportResumePosition {
+  if (!raw) return { pageCursor: null, offset: 0 };
+  try {
+    const parsed = JSON.parse(raw) as Partial<ImportResumePosition>;
+    if (typeof parsed === "object" && parsed !== null && "offset" in parsed) {
+      return {
+        pageCursor: parsed.pageCursor ?? null,
+        offset: typeof parsed.offset === "number" && parsed.offset >= 0 ? parsed.offset : 0,
+      };
+    }
+  } catch {
+    // Legacy bare page cursor.
+  }
+  return { pageCursor: raw, offset: 0 };
+}
+
+function encodeImportResumePosition(position: ImportResumePosition): string {
+  return JSON.stringify(position);
+}
+
 export interface BackfillCatalogOptions {
   dryRun?: boolean;
   resume?: boolean;
@@ -343,6 +366,7 @@ interface CatalogService {
       isVisible?: boolean;
     },
     actor: Actor,
+    ctx?: TxContext,
   ): Promise<{ ok: true; value: { id: string } } | { ok: false; error: { message: string } }>;
   createVariant(
     input: { entityId: string; options: Record<string, string>; sku?: string; barcode?: string },
@@ -481,6 +505,9 @@ function hash(value: unknown): string {
   return createHash("sha256").update(JSON.stringify(value)).digest("hex");
 }
 
+/** Mid-import map rows carry this until convergence finishes; must not equal any real remote hash. */
+const PENDING_ENTITY_MAP_SYNC_HASH = "";
+
 export const CATALOG_OUTBOUND_SUPPRESSION_WINDOW_MS = 15 * 60 * 1000;
 
 function normalizeCanonicalValue(value: unknown): unknown {
@@ -2171,7 +2198,40 @@ export class ChannelConnectorService {
     orgId: string,
     storeId: string,
     actor: Actor,
-  ): Promise<PluginResult<{ imported: number; cursor: string | null; skipped?: CatalogFieldSkip[]; conflicts?: CatalogFieldConflict[]; warnings?: string[] }>> {
+    options: { maxItems: number },
+  ): Promise<PluginResult<{
+    imported: number;
+    cursor: string | null;
+    exhausted: boolean;
+    skipped?: CatalogFieldSkip[];
+    conflicts?: CatalogFieldConflict[];
+    warnings?: string[];
+  }>>;
+  async importCatalog(
+    orgId: string,
+    storeId: string,
+    actor: Actor,
+    options?: undefined,
+  ): Promise<PluginResult<{
+    imported: number;
+    cursor: string | null;
+    skipped?: CatalogFieldSkip[];
+    conflicts?: CatalogFieldConflict[];
+    warnings?: string[];
+  }>>;
+  async importCatalog(
+    orgId: string,
+    storeId: string,
+    actor: Actor,
+    options?: { maxItems?: number },
+  ): Promise<PluginResult<{
+    imported: number;
+    cursor: string | null;
+    exhausted?: boolean;
+    skipped?: CatalogFieldSkip[];
+    conflicts?: CatalogFieldConflict[];
+    warnings?: string[];
+  }>> {
     const store = await this.getStoreRecord(orgId, storeId);
     if (!store || store.status !== "connected") {
       return PluginErr("Connected store not found.", "NOT_FOUND");
@@ -2179,28 +2239,103 @@ export class ChannelConnectorService {
     const connector = this.connectors.get(store.provider);
     if (!connector) return PluginErr(`No connector registered for provider "${store.provider}".`);
 
-    const items: ChannelCatalogItem[] = [];
-    let cursor: string | undefined = store.catalogCursor ?? undefined;
-    do {
-      const page = await connector.importCatalog(store as ChannelStore, cursor);
+    const maxItems = options?.maxItems;
+    const bounded = maxItems !== undefined;
+
+    if (!bounded) {
+      const resume = parseImportResumePosition(store.catalogCursor);
+      const items: ChannelCatalogItem[] = [];
+      let pageCursor: string | undefined = resume.pageCursor ?? undefined;
+      do {
+        const page = await connector.importCatalog(store as ChannelStore, pageCursor);
+        if (!page.ok) return PluginErr(page.error.message);
+        items.push(...page.value.items);
+        pageCursor = page.value.nextCursor ?? undefined;
+      } while (pageCursor);
+
+      const result = await this.convergeCatalogItems(orgId, storeId, items, actor);
+      if (!result.ok) return result;
+
+      await this.db
+        .update(connectedStores)
+        .set({ catalogCursor: null, lastSyncAt: new Date(), updatedAt: new Date() })
+        .where(and(eq(connectedStores.organizationId, orgId), eq(connectedStores.id, storeId)));
+      return Ok({
+        imported: result.value.imported,
+        cursor: null,
+        ...(result.value.skipped.length > 0 ? { skipped: uniqueSkipped(result.value.skipped) } : {}),
+        ...(result.value.conflicts.length > 0 ? { conflicts: result.value.conflicts } : {}),
+        ...(result.value.warnings.length > 0 ? { warnings: result.value.warnings } : {}),
+      });
+    }
+
+    let { pageCursor, offset } = parseImportResumePosition(store.catalogCursor);
+    let remaining = maxItems;
+    let exhausted = false;
+    let totalImported = 0;
+    const skipped: CatalogFieldSkip[] = [];
+    const conflicts: CatalogFieldConflict[] = [];
+    const warnings: string[] = [];
+
+    while (remaining > 0) {
+      const page = await connector.importCatalog(store as ChannelStore, pageCursor ?? undefined);
       if (!page.ok) return PluginErr(page.error.message);
-      items.push(...page.value.items);
-      cursor = page.value.nextCursor ?? undefined;
-    } while (cursor);
 
-    const result = await this.convergeCatalogItems(orgId, storeId, items, actor);
-    if (!result.ok) return result;
+      const pageItems = page.value.items;
+      const slice = pageItems.slice(offset);
+      const batchSize = Math.min(remaining, slice.length);
+
+      if (batchSize === 0) {
+        if (page.value.nextCursor) {
+          pageCursor = page.value.nextCursor;
+          offset = 0;
+          continue;
+        }
+        exhausted = true;
+        break;
+      }
+
+      const batch = slice.slice(0, batchSize);
+      const result = await this.convergeCatalogItems(orgId, storeId, batch, actor);
+      if (!result.ok) return result;
+
+      totalImported += result.value.imported;
+      remaining -= result.value.consumed;
+      skipped.push(...result.value.skipped);
+      conflicts.push(...result.value.conflicts);
+      warnings.push(...result.value.warnings);
+      offset += result.value.consumed;
+
+      if (offset >= pageItems.length) {
+        if (page.value.nextCursor) {
+          pageCursor = page.value.nextCursor;
+          offset = 0;
+        } else {
+          exhausted = true;
+        }
+      }
 
+      if (remaining === 0) break;
+      if (exhausted) break;
+    }
+
+    const catalogCursor = exhausted ? null : encodeImportResumePosition({ pageCursor, offset });
     await this.db
       .update(connectedStores)
-      .set({ catalogCursor: null, lastSyncAt: new Date(), updatedAt: new Date() })
+      .set({
+        catalogCursor,
+        ...(exhausted ? { lastSyncAt: new Date() } : {}),
+        updatedAt: new Date(),
+      })
       .where(and(eq(connectedStores.organizationId, orgId), eq(connectedStores.id, storeId)));
+
     return Ok({
-      imported: result.value.imported,
-      cursor: null,
-      ...(result.value.skipped.length > 0 ? { skipped: uniqueSkipped(result.value.skipped) } : {}),
-      ...(result.value.conflicts.length > 0 ? { conflicts: result.value.conflicts } : {}),
-      ...(result.value.warnings.length > 0 ? { warnings: result.value.warnings } : {}),
+      imported: totalImported,
+      cursor: catalogCursor,
+      exhausted,
+      ...(skipped.length > 0 ? { skipped: uniqueSkipped(skipped) } : {}),
+      ...(conflicts.length > 0 ? { conflicts } : {}),
+      ...(warnings.length > 0 ? { warnings } : {}),
     });
   }
 
@@ -2384,12 +2519,14 @@ export class ChannelConnectorService {
       attributesCreated: 0,
       mediaImported: 0,
       variantsGivenOptionValues: 0,
+      consumed: 0,
       skipped: [],
       conflicts: [],
       warnings: [],
     };
     const assets = await this.db.select().from(mediaAssets).where(eq(mediaAssets.organizationId, orgId));
     for (const item of items) {
+      stats.consumed += 1;
       const [entityMapping] = await this.db.select().from(channelEntityMap).where(and(
         eq(channelEntityMap.organizationId, orgId),
         eq(channelEntityMap.storeId, storeId),
@@ -2529,10 +2666,12 @@ export class ChannelConnectorService {
     let attributesCreated = 0;
     let mediaImported = 0;
     let variantsGivenOptionValues = 0;
+    let consumed = 0;
     const skipped: CatalogFieldSkip[] = [];
     const conflicts: CatalogFieldConflict[] = [];
     const warnings: string[] = [];
     for (const item of items) {
+      consumed += 1;
       const remoteHash = hash(item);
       const existing = await this.db
         .select()
@@ -2543,9 +2682,10 @@ export class ChannelConnectorService {
           eq(channelEntityMap.kind, "entity"),
           eq(channelEntityMap.externalId, item.externalId),
         ));
-      const entityMapping = existing.find((entry) => entry.kind === "entity");
-      let entityId: string;
+      let entityMapping = existing.find((entry) => entry.kind === "entity");
+      let entityId: string | undefined;
       let isNew = false;
+      let adoptedOrphan = false;
       let entityTouched = false;
       let existingEntity: typeof sellableEntities.$inferSelect | undefined;
       if (entityMapping) {
@@ -2554,25 +2694,59 @@ export class ChannelConnectorService {
           eq(sellableEntities.id, entityMapping.entityId),
         ));
         if (!entity) {
-          warnings.push(`Skipped "${item.externalId}": mapped entity ${entityMapping.entityId} no longer exists.`);
-          continue;
+          await this.db.delete(channelEntityMap).where(and(
+            eq(channelEntityMap.organizationId, orgId),
+            eq(channelEntityMap.storeId, storeId),
+            eq(channelEntityMap.entityId, entityMapping.entityId),
+          ));
+          entityMapping = undefined;
+        } else {
+          entityId = entityMapping.entityId;
+          existingEntity = entity;
+        }
+      }
+      if (entityId === undefined) {
+        const [orphan] = await this.db.select().from(sellableEntities).where(and(
+          eq(sellableEntities.organizationId, orgId),
+          eq(sellableEntities.sourceStoreId, storeId),
+          eq(sellableEntities.slug, item.slug),
+        ));
+        if (orphan) {
+          entityId = orphan.id;
+          existingEntity = orphan;
+          adoptedOrphan = true;
+        } else {
+          const status = item.status;
+          try {
+            entityId = await this.transact(async (tx) => {
+              const txContext = createTxContext(tx, { actor });
+              const created = await this.catalog.create({
+                type: "product",
+                slug: item.slug,
+                sourceStoreId: storeId,
+                metadata: mergeMetadata(undefined, item.metadata ?? {}),
+                ...(status !== undefined ? { status, isVisible: status === "active" } : {}),
+              }, actor, txContext);
+              if (!created.ok) throw new Error(created.error.message);
+              await tx.insert(channelEntityMap).values({
+                organizationId: orgId,
+                storeId,
+                kind: "entity",
+                externalId: item.externalId,
+                entityId: created.value.id,
+                syncHash: PENDING_ENTITY_MAP_SYNC_HASH,
+                heldFieldPaths: [],
+                forcedPushFieldPaths: [],
+              });
+              return created.value.id;
+            });
+          } catch (error) {
+            return PluginErr(error instanceof Error ? error.message : "Failed to create catalog entity.");
+          }
+          isNew = true;
+          imported += 1;
+          entityTouched = true;
         }
-        entityId = entityMapping.entityId;
-        existingEntity = entity;
-      } else {
-        const status = item.status;
-        const entity = await this.catalog.create({
-          type: "product",
-          slug: item.slug,
-          sourceStoreId: storeId,
-          metadata: mergeMetadata(undefined, item.metadata ?? {}),
-          ...(status !== undefined ? { status, isVisible: status === "active" } : {}),
-        }, actor);
-        if (!entity.ok) return PluginErr(entity.error.message);
-        entityId = entity.value.id;
-        isNew = true;
-        imported += 1;
-        entityTouched = true;
       }
 
       const ownershipBeforeSeed = await this.catalog.resolveFieldOwners(entityId, storeId);
@@ -2684,6 +2858,19 @@ export class ChannelConnectorService {
       const lastSyncedAt = latestRevisionAt ?? entityMapping?.lastSyncedAt ?? new Date();
 
       if (isNew) {
+        await this.db.update(channelEntityMap).set({
+          syncHash: remoteHash,
+          lastSyncedAt,
+          heldFieldPaths: heldSharedPaths,
+          forcedPushFieldPaths: survivingForcedPaths,
+        }).where(and(
+          eq(channelEntityMap.organizationId, orgId),
+          eq(channelEntityMap.storeId, storeId),
+          eq(channelEntityMap.kind, "entity"),
+          eq(channelEntityMap.externalId, item.externalId),
+          eq(channelEntityMap.entityId, entityId),
+        ));
+      } else if (adoptedOrphan) {
         await this.db.insert(channelEntityMap).values({
           organizationId: orgId,
           storeId,
@@ -2717,6 +2904,7 @@ export class ChannelConnectorService {
       attributesCreated,
       mediaImported,
       variantsGivenOptionValues,
+      consumed,
       skipped,
       conflicts,
       warnings,