@porulle/plugin-channel-connector 0.51.0 → 0.53.0

package/dist/index.d.ts

@@ -5,8 +5,6 @@ export { ChannelConnectorService, HERO_IMAGE_BYTE_CAP, selectImportImages, CATAL
 export { isValidCatalogMappingFieldPath, matchFieldPath, mergeCatalogFieldMapping, normalizeCatalogFieldMapping, compareCatalogFieldMappingSpecificity, providerCatalogFieldMappingDefaults, selectCatalogFieldMapping, validateCatalogMappingRow, } from "./catalog-field-mapping.js";
 export type { CatalogDeferredMedia, CatalogMediaFailure, CatalogMediaFailureReason, CatalogPageConvergence, ImportImageSelection, } from "./service.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;
 /**
  * How many bounded batches one sweep may walk before it refuses rather than loops.
  *

package/dist/index.js

@@ -10,8 +10,6 @@ import { oauthStateEventId, signState, verifyState } from "./oauth-state.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";
-/** ~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;
 /**
  * How many bounded batches one sweep may walk before it refuses rather than loops.
  *
@@ -169,67 +167,6 @@ export function channelConnectorPlugin(options = {}) {
                 return { output: { enqueued: stores.length } };
             },
         },
-        {
-            slug: "channel/import-catalog",
-            concurrency: { key: (input) => String(input.storeId), supersedes: true },
-            durableSteps: true,
-            handler: async ({ input, ctx }) => {
-                const service = new ChannelConnectorService(ctx.db, ctx.services, options);
-                const orgId = String(input.orgId);
-                const storeId = String(input.storeId);
-                const result = await walkBatches(ctx, "import-catalog", storeId, async () => {
-                    const page = await service.importCatalog(orgId, storeId, createSystemActor(orgId), {
-                        maxItems: CHANNEL_IMPORT_MAX_ITEMS_PER_INVOCATION,
-                    });
-                    if (!page.ok)
-                        throw new Error(page.error);
-                    return {
-                        exhausted: page.value.exhausted,
-                        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 } : {}),
-                    };
-                });
-                const jobs = ctx.services.jobs;
-                // The catalog is always exhausted by the time the walk above returns, so this hand-off is
-                // unconditional. It is the ONE enqueue this task is allowed: it starts a DIFFERENT task
-                // once, spending a single level of the request chain's 32, rather than one per page the
-                // way the continuation it replaced did.
-                //
-                // A finished catalog is not a usable one. `importCatalog` writes entities, variants and
-                // prices and never touches `inventory_levels`, so a store whose sweep ends here has a
-                // catalog in which every variant rolls up as out of stock — which is what a consumer
-                // projection publishes and what a shopper is shown.
-                //
-                // Inventory used to arrive from `reconcile`, reachable only through the
-                // `channel/reconcile-sweep` cron. A deployment that removes its crons therefore loses a
-                // data-plane write silently, with every suite still green. Levelling inventory here keeps
-                // it inside the one operator action — "import this store" — instead of behind a second
-                // one somebody has to remember.
-                await jobs.enqueue("channel/sync-inventory", { orgId, storeId }, {
-                    organizationId: orgId,
-                    concurrencyKey: storeId,
-                });
-                return {
-                    output: {
-                        imported: result.counted,
-                        cursor: result.last.cursor ?? null,
-                        exhausted: true,
-                        batches: result.batches,
-                        ...(result.warnings.length > 0 ? { warnings: result.warnings } : {}),
-                    },
-                };
-            },
-        },
         {
             slug: "channel/backfill-catalog",
             concurrency: { key: (input) => String(input.storeId) },

package/dist/service.d.ts

@@ -309,6 +309,20 @@ export declare class ChannelConnectorService {
     private localFieldValue;
     private lastSyncedSnapshot;
     private detectSharedConflicts;
+    /**
+     * Apply upstream SKU and barcode changes to variants this store already maps, for a whole batch.
+     *
+     * SKU is unique per source store, so variants EXCHANGING SKUs cannot be updated one at a time.
+     * One transaction first releases every SKU that is changing (NULL is outside the unique index),
+     * then sets the new values, so any swap inside the batch lands atomically. If that fails on a
+     * unique violation — a new SKU is held by a variant whose upstream did not change, or by a
+     * variant in a batch not converged yet — each entity is retried alone, then each variant alone,
+     * and the SKU that still cannot be taken is returned as a clash. A clash is the caller's to
+     * record as a conflict; it never fails the item, which still converges every other field.
+     */
+    private applyUpstreamVariantIdentity;
+    /** Close this entity's open `variants.sku` conflict: the SKUs it was waiting on have now landed. */
+    private resolveSkuConflict;
     private persistCatalogConflicts;
     private setCatalogAttributes;
     private setCatalogAttributesIfWritable;
@@ -378,7 +392,6 @@ export declare class ChannelConnectorService {
         storeDomain: string;
         webhookSecret?: string;
     }): Promise<PluginResult<PublicConnectedStore>>;
-    private get optionsJobs();
     disconnectStore(orgId: string, id: string): Promise<PluginResult<PublicConnectedStore>>;
     disconnectStoreSystem(orgId: string, id: string, redactDomain?: boolean): Promise<PluginResult<PublicConnectedStore>>;
     getStore(orgId: string, id: string): Promise<PluginResult<PublicConnectedStore>>;

package/dist/service.js

@@ -153,6 +153,18 @@ export function isSlugConflict(error) {
     }
     return false;
 }
+/** Postgres 23505 anywhere in a driver error's `cause` chain. */
+function isUniqueViolation(error) {
+    let cursor = error;
+    for (let depth = 0; depth < 5; depth += 1) {
+        if (typeof cursor !== "object" || cursor === null)
+            return false;
+        if ("code" in cursor && cursor.code === "23505")
+            return true;
+        cursor = "cause" in cursor ? cursor.cause : undefined;
+    }
+    return false;
+}
 function errorMessage(error) {
     if (typeof error === "string")
         return error;
@@ -784,7 +796,143 @@ export class ChannelConnectorService {
         }));
         return { paths: changed, conflicts };
     }
-    async persistCatalogConflicts(orgId, conflicts, changedBy) {
+    /**
+     * Apply upstream SKU and barcode changes to variants this store already maps, for a whole batch.
+     *
+     * SKU is unique per source store, so variants EXCHANGING SKUs cannot be updated one at a time.
+     * One transaction first releases every SKU that is changing (NULL is outside the unique index),
+     * then sets the new values, so any swap inside the batch lands atomically. If that fails on a
+     * unique violation — a new SKU is held by a variant whose upstream did not change, or by a
+     * variant in a batch not converged yet — each entity is retried alone, then each variant alone,
+     * and the SKU that still cannot be taken is returned as a clash. A clash is the caller's to
+     * record as a conflict; it never fails the item, which still converges every other field.
+     */
+    async applyUpstreamVariantIdentity(orgId, storeId, items) {
+        const outcome = { written: new Set(), clashes: new Map(), openSkuConflicts: new Set() };
+        const externalIds = [...new Set(items.flatMap((item) => item.variants.map((variant) => variant.externalId)))];
+        if (externalIds.length === 0)
+            return outcome;
+        const mapped = await this.db.select({
+            externalId: channelEntityMap.externalId,
+            variantId: variants.id,
+            entityId: variants.entityId,
+            sku: variants.sku,
+            barcode: variants.barcode,
+        }).from(channelEntityMap)
+            .innerJoin(variants, eq(variants.id, channelEntityMap.variantId))
+            .where(and(eq(channelEntityMap.organizationId, orgId), eq(channelEntityMap.storeId, storeId), eq(channelEntityMap.kind, "variant"), inArray(channelEntityMap.externalId, externalIds)));
+        if (mapped.length === 0)
+            return outcome;
+        const byExternalId = new Map(mapped.map((row) => [row.externalId, row]));
+        const entityIds = [...new Set(mapped.map((row) => row.entityId))];
+        const openRows = await this.db.select({ entityId: channelCatalogConflicts.entityId }).from(channelCatalogConflicts).where(and(eq(channelCatalogConflicts.storeId, storeId), eq(channelCatalogConflicts.fieldPath, "variants.sku"), eq(channelCatalogConflicts.state, "open"), inArray(channelCatalogConflicts.entityId, entityIds)));
+        for (const row of openRows)
+            outcome.openSkuConflicts.add(row.entityId);
+        const candidates = [];
+        for (const item of items) {
+            for (const variant of item.variants) {
+                const row = byExternalId.get(variant.externalId);
+                if (!row)
+                    continue;
+                const toSku = variant.sku !== undefined && variant.sku !== row.sku ? variant.sku : undefined;
+                const toBarcode = variant.barcode !== undefined && variant.barcode !== row.barcode ? variant.barcode : undefined;
+                if (toSku === undefined && toBarcode === undefined)
+                    continue;
+                candidates.push({
+                    itemExternalId: item.externalId, entityId: row.entityId, variantId: row.variantId, variantExternalId: variant.externalId, fromSku: row.sku,
+                    ...(toSku !== undefined ? { toSku } : {}), ...(toBarcode !== undefined ? { toBarcode } : {}),
+                });
+            }
+        }
+        if (candidates.length === 0)
+            return outcome;
+        // Ownership, per entity that has a change: a platform-owned or held path stays local.
+        const candidateEntities = [...new Set(candidates.map((write) => write.entityId))];
+        const held = new Map((await this.db.select({ entityId: channelEntityMap.entityId, held: channelEntityMap.heldFieldPaths }).from(channelEntityMap).where(and(eq(channelEntityMap.storeId, storeId), eq(channelEntityMap.kind, "entity"), inArray(channelEntityMap.entityId, candidateEntities)))).map((row) => [row.entityId, new Set(row.held ?? [])]));
+        const allowed = new Map();
+        for (const entityId of candidateEntities) {
+            const owners = await this.catalog.resolveFieldOwners(entityId, storeId);
+            const entityHeld = held.get(entityId) ?? new Set();
+            allowed.set(entityId, {
+                sku: ownerAllows(owners, "variants.sku") && !entityHeld.has("variants.sku"),
+                barcode: ownerAllows(owners, "variants.barcode") && !entityHeld.has("variants.barcode"),
+            });
+        }
+        const writes = candidates.flatMap((write) => {
+            const permitted = allowed.get(write.entityId) ?? { sku: false, barcode: false };
+            const next = {
+                itemExternalId: write.itemExternalId, entityId: write.entityId, variantId: write.variantId, variantExternalId: write.variantExternalId, fromSku: write.fromSku,
+                ...(permitted.sku && write.toSku !== undefined ? { toSku: write.toSku } : {}),
+                ...(permitted.barcode && write.toBarcode !== undefined ? { toBarcode: write.toBarcode } : {}),
+            };
+            return next.toSku === undefined && next.toBarcode === undefined ? [] : [next];
+        });
+        if (writes.length === 0)
+            return outcome;
+        const apply = (group) => this.transact(async (tx) => {
+            const releasing = group.filter((write) => write.toSku !== undefined).map((write) => write.variantId);
+            if (releasing.length > 0)
+                await tx.update(variants).set({ sku: null }).where(inArray(variants.id, releasing));
+            for (const write of group) {
+                await tx.update(variants).set({
+                    ...(write.toSku !== undefined ? { sku: write.toSku } : {}),
+                    ...(write.toBarcode !== undefined ? { barcode: write.toBarcode } : {}),
+                    updatedAt: sql `now()`,
+                }).where(eq(variants.id, write.variantId));
+            }
+        });
+        const landed = (group) => { for (const write of group)
+            outcome.written.add(write.itemExternalId); };
+        const attempt = async (group) => {
+            try {
+                await apply(group);
+                landed(group);
+                return true;
+            }
+            catch (error) {
+                if (!isUniqueViolation(error))
+                    throw error;
+                return false;
+            }
+        };
+        if (await attempt(writes))
+            return outcome;
+        for (const entityId of [...new Set(writes.map((write) => write.entityId))]) {
+            const group = writes.filter((write) => write.entityId === entityId);
+            if (await attempt(group))
+                continue;
+            for (const write of group) {
+                if (await attempt([write]))
+                    continue;
+                // The SKU cannot be taken this batch. The barcode, which nothing else can hold, still lands.
+                if (write.toBarcode !== undefined) {
+                    await attempt([{ itemExternalId: write.itemExternalId, entityId: write.entityId, variantId: write.variantId, variantExternalId: write.variantExternalId, fromSku: write.fromSku, toBarcode: write.toBarcode }]);
+                }
+                if (write.toSku === undefined)
+                    continue;
+                const [holder] = await this.db.select({ id: variants.id }).from(variants).where(and(eq(variants.sourceStoreId, storeId), eq(variants.sku, write.toSku)));
+                const clashes = outcome.clashes.get(write.itemExternalId) ?? [];
+                clashes.push({ variantExternalId: write.variantExternalId, fromSku: write.fromSku, toSku: write.toSku, heldByVariantId: holder?.id ?? null });
+                outcome.clashes.set(write.itemExternalId, clashes);
+            }
+        }
+        return outcome;
+    }
+    /** Close this entity's open `variants.sku` conflict: the SKUs it was waiting on have now landed. */
+    async resolveSkuConflict(orgId, storeId, entityId, changedBy) {
+        const resolved = await this.db.update(channelCatalogConflicts).set({ state: "resolved", resolvedBy: changedBy, updatedAt: new Date() }).where(and(eq(channelCatalogConflicts.storeId, storeId), eq(channelCatalogConflicts.entityId, entityId), eq(channelCatalogConflicts.fieldPath, "variants.sku"), eq(channelCatalogConflicts.state, "open"))).returning({ id: channelCatalogConflicts.id });
+        if (resolved.length === 0)
+            return;
+        await this.db.insert(channelCatalogConflictEvents).values(resolved.map((row) => ({
+            organizationId: orgId,
+            conflictId: row.id,
+            fromState: "open",
+            toState: "resolved",
+            reason: "The upstream SKUs this product was waiting on have converged.",
+            changedBy,
+        })));
+    }
+    async persistCatalogConflicts(orgId, conflicts, changedBy, reason = "Shared catalog field changed on both sides.") {
         for (const conflict of conflicts) {
             const [inserted] = await this.db.insert(channelCatalogConflicts).values({
                 organizationId: orgId,
@@ -816,7 +964,7 @@ export class ChannelConnectorService {
                 conflictId: inserted.id,
                 fromState: null,
                 toState: "open",
-                reason: "Shared catalog field changed on both sides.",
+                reason,
                 changedBy,
             });
         }
@@ -1978,19 +2126,10 @@ export class ChannelConnectorService {
                 return PluginErr(registration.error.message, "CONNECTOR_REGISTRATION_FAILED");
             }
         }
-        const jobs = this.optionsJobs;
-        if (jobs) {
-            await jobs.enqueue("channel/import-catalog", { orgId, storeId: rows[0].id }, {
-                organizationId: orgId,
-                concurrencyKey: rows[0].id,
-                supersedes: true,
-            });
-        }
+        // Connecting starts no import. The host's operator route starts one (and levels inventory after
+        // it); connect used to enqueue a second, sequential walk that ran beside the host's own.
         return Ok(redactStore(store));
     }
-    get optionsJobs() {
-        return this.jobs;
-    }
     async disconnectStore(orgId, id) {
         return this.disconnectStoreSystem(orgId, id);
     }
@@ -2743,6 +2882,9 @@ export class ChannelConnectorService {
         const committed = new Set();
         // One resolution for the whole batch, not two round trips per changed product.
         const slugFor = await this.resolveStoreSlugs(orgId, storeId, items.map((item) => item.slug));
+        // Upstream SKU/barcode changes on already-mapped variants, for the whole batch at once, so that
+        // variants exchanging SKUs across products in this batch land together.
+        const identity = await this.applyUpstreamVariantIdentity(orgId, storeId, items);
         for (const item of items) {
             consumed += 1;
             try {
@@ -2846,7 +2988,11 @@ export class ChannelConnectorService {
                 // An unchanged remote item writes nothing and advances no baseline:
                 // converging a stale replay would revert local edits to shared and
                 // unowned fields that the store never actually changed.
-                if (!force && !remoteChanged && existingEntity && existingEntity.status !== "archived") {
+                // ...unless its SKUs moved this batch, clashed, or were waiting on an open conflict: a swap that
+                // spanned two import pages leaves both map hashes current, and only this pass can close it.
+                const identityPending = identity.written.has(item.externalId) || identity.clashes.has(item.externalId)
+                    || identity.openSkuConflicts.has(entityId);
+                if (!force && !remoteChanged && !identityPending && existingEntity && existingEntity.status !== "archived") {
                     continue;
                 }
                 const shared = existingEntity
@@ -2943,7 +3089,33 @@ export class ChannelConnectorService {
                 mediaImported += media.value.imported;
                 variantsGivenOptionValues += variantIds.value.repaired;
                 skipped.push(...media.value.skipped.map((fieldPath) => ({ entityId, fieldPath })));
-                entityTouched = entityTouched || optionAxes.value.changed || variantIds.value.changed || taxonomy.value.changed || media.value.changed || attributes.value.changed;
+                entityTouched = entityTouched || optionAxes.value.changed || variantIds.value.changed || taxonomy.value.changed || media.value.changed || attributes.value.changed
+                    || identity.written.has(item.externalId);
+                const skuClashes = identity.clashes.get(item.externalId);
+                if (skuClashes) {
+                    // Loud, not fatal: the product converges everything else, its SKU keeps the old value, and
+                    // the next reconcile — which sees the whole catalogue in one batch — resolves a swap that
+                    // spanned two import pages and closes this conflict.
+                    const conflict = {
+                        entityId,
+                        storeId,
+                        fieldPath: "variants.sku",
+                        localValueSummary: skuClashes.map((clash) => `${clash.variantExternalId}=${clash.fromSku ?? "(none)"}`).join(", "),
+                        remoteValueSummary: skuClashes.map((clash) => `${clash.variantExternalId}=${clash.toSku} (held by ${clash.heldByVariantId ?? "unknown"})`).join(", "),
+                        platformValue: Object.fromEntries(skuClashes.map((clash) => [clash.variantExternalId, { sku: clash.fromSku, heldByVariantId: clash.heldByVariantId }])),
+                        storeValue: Object.fromEntries(skuClashes.map((clash) => [clash.variantExternalId, clash.toSku])),
+                    };
+                    const recorded = await this.persistCatalogConflicts(orgId, [conflict], requireUserId(actor), "Upstream SKU is held by another variant of this store.");
+                    if (!recorded.ok) {
+                        failures.push({ externalId: item.externalId, error: recorded.error });
+                        continue;
+                    }
+                    conflicts.push({ entityId, storeId, fieldPath: "variants.sku", localValueSummary: conflict.localValueSummary, remoteValueSummary: conflict.remoteValueSummary });
+                    warnings.push(`Kept the local SKU for entity "${entityId}": ${conflict.remoteValueSummary}.`);
+                }
+                else if (identity.openSkuConflicts.has(entityId)) {
+                    await this.resolveSkuConflict(orgId, storeId, entityId, requireUserId(actor));
+                }
                 if (entityTouched)
                     entitiesTouched += 1;
                 // Counted from what was written, not from the stored hash: a hash that moved while the