@porulle/plugin-channel-connector 0.58.0 → 0.60.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;

package/dist/service.js

@@ -146,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");
 }
@@ -581,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);
     }
@@ -2316,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 });
@@ -2331,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();
@@ -2558,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);
@@ -2590,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;
@@ -2753,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);
@@ -2982,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:
@@ -3334,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);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@porulle/plugin-channel-connector",
-  "version": "0.58.0",
+  "version": "0.60.0",
   "license": "MIT",
   "type": "module",
   "exports": {
@@ -19,15 +19,15 @@
   "dependencies": {
     "@hono/zod-openapi": "^1.2.2",
     "hono": "^4.12.5",
-    "@porulle/core": "0.58.0"
+    "@porulle/core": "0.60.0"
   },
   "devDependencies": {
     "@types/node": "^24.5.2",
     "eslint": "^9.39.1",
     "typescript": "5.9.2",
     "vitest": "^3.2.4",
-    "@porulle/eslint-config": "0.1.0",
-    "@porulle/typescript-config": "0.1.0"
+    "@porulle/typescript-config": "0.1.0",
+    "@porulle/eslint-config": "0.1.0"
   },
   "publishConfig": {
     "access": "public"

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

@@ -660,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");
 }
@@ -1178,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);
   }
@@ -3196,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 });
   }
@@ -3214,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>();
@@ -3512,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;
@@ -3546,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;
@@ -3732,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;
@@ -3984,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
@@ -4355,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;