@porulle/plugin-channel-connector 0.56.0 → 0.57.1

package/dist/index.d.ts

@@ -1,5 +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 type { AbsentArchivePlan } from "./deletion-policy.js";
 export { mockChannelConnector } from "./mock-connector.js";
 export type { MockChannelConnectorOptions } from "./mock-connector.js";

package/dist/index.js

@@ -8,6 +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 { 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

@@ -236,6 +236,8 @@ 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. */
+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
  * label of the store domain (`kelly-felder.myshopify.com` → `kelly-felder`), slugified.

package/dist/service.js

@@ -123,9 +123,30 @@ const catalogPushTransitions = {
 export function canCatalogPushTransition(from, to) {
     return catalogPushTransitions[from].includes(to);
 }
-function hash(value) {
-    return createHash("sha256").update(JSON.stringify(value)).digest("hex");
+/**
+ * JSON with every object's keys sorted, recursively — the one form every hash here is taken over.
+ *
+ * The sync hash was `sha256(JSON.stringify(item))`, and JSON.stringify writes keys in insertion
+ * order. The host's page consumer rebuilds each landed item in its own key order while reconcile
+ * hashes the adapter's objects in theirs, so the fast path and reconcile hashed the SAME content
+ * differently and reconcile re-converged every freshly imported product. Content, not key order,
+ * is what a hash here must answer. `undefined` values are dropped exactly as JSON.stringify drops
+ * them; array order is kept (it carries meaning: images, variants, options).
+ */
+function canonicalJson(value) {
+    if (Array.isArray(value))
+        return `[${value.map((entry) => (entry === undefined ? "null" : canonicalJson(entry))).join(",")}]`;
+    if (value !== null && typeof value === "object" && !(value instanceof Date)) {
+        const entries = Object.entries(value).filter(([, entry]) => entry !== undefined).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+        return `{${entries.map(([key, entry]) => `${JSON.stringify(key)}:${canonicalJson(entry)}`).join(",")}}`;
+    }
+    return JSON.stringify(value) ?? "null";
+}
+/** THE sync hash: every path that records or compares a `channel_entity_map.sync_hash` uses this. */
+export function channelSyncHash(value) {
+    return createHash("sha256").update(canonicalJson(value)).digest("hex");
 }
+const hash = channelSyncHash;
 /**
  * The suffix a store's product takes when its handle is already another store's slug: the first
  * label of the store domain (`kelly-felder.myshopify.com` → `kelly-felder`), slugified.
@@ -1446,7 +1467,13 @@ export class ChannelConnectorService {
     }
     async applyMedia(orgId, entityId, item, variantIds, actor, warnings, owners) {
         // Uploads what is missing and PLANS the entity's media links; `commitEntityLinks` writes them.
-        const images = item.images ?? [];
+        //
+        // Only the images the import ruling allows — the SAME `selectImportImages` the page fast path
+        // uses: the hero plus the first photo of each other variant. This path attached EVERY image
+        // the item listed, so the first converge of a product whose price changed pulled in the whole
+        // gallery the fast path had deliberately left out: an upload, an embed and a bump per photo.
+        const selection = selectImportImages(item);
+        const images = selection.hero === null ? [] : [selection.hero, ...selection.perVariant];
         const externalIds = [...new Set(images.map((image) => image.externalId).filter((id) => id != null))];
         const urlHashes = [...new Set(images.map((image) => hash(image.url)))];
         const keyPredicates = [];
@@ -2923,7 +2950,9 @@ export class ChannelConnectorService {
      * products remain.
      */
     async claimUnrecordedLinks(orgId, storeId, items) {
-        if (items.length === 0)
+        // Nothing listed, nothing to claim: no query. Otherwise one select per converge call (a batch),
+        // never one per product.
+        if (!items.some((item) => (item.tags?.length ?? 0) > 0 || (item.categories?.length ?? 0) > 0 || item.brand !== undefined))
             return;
         const unclaimed = await this.db.select({ externalId: channelEntityMap.externalId, entityId: channelEntityMap.entityId }).from(channelEntityMap).where(and(eq(channelEntityMap.organizationId, orgId), eq(channelEntityMap.storeId, storeId), eq(channelEntityMap.kind, "entity"), inArray(channelEntityMap.externalId, items.map((item) => item.externalId)), sql `not exists (select 1 from ${channelEntityLinks} where ${channelEntityLinks.storeId} = ${channelEntityMap.storeId} and ${channelEntityLinks.entityId} = ${channelEntityMap.entityId})`));
         if (unclaimed.length === 0)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@porulle/plugin-channel-connector",
-  "version": "0.56.0",
+  "version": "0.57.1",
   "license": "MIT",
   "type": "module",
   "exports": {
@@ -19,15 +19,15 @@
   "dependencies": {
     "@hono/zod-openapi": "^1.2.2",
     "hono": "^4.12.5",
-    "@porulle/core": "0.56.0"
+    "@porulle/core": "0.57.1"
   },
   "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,6 +55,7 @@ type ChannelRouteContext = {
 };
 
 export { ABSENT_ARCHIVE_FLOOR, ABSENT_ARCHIVE_FRACTION, planAbsentArchives } from "./deletion-policy.js";
+export { channelSyncHash } 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

@@ -637,10 +637,32 @@ export function canCatalogPushTransition(from: CatalogPushState, to: CatalogPush
   return catalogPushTransitions[from].includes(to);
 }
 
-function hash(value: unknown): string {
-  return createHash("sha256").update(JSON.stringify(value)).digest("hex");
+/**
+ * JSON with every object's keys sorted, recursively — the one form every hash here is taken over.
+ *
+ * The sync hash was `sha256(JSON.stringify(item))`, and JSON.stringify writes keys in insertion
+ * order. The host's page consumer rebuilds each landed item in its own key order while reconcile
+ * hashes the adapter's objects in theirs, so the fast path and reconcile hashed the SAME content
+ * differently and reconcile re-converged every freshly imported product. Content, not key order,
+ * is what a hash here must answer. `undefined` values are dropped exactly as JSON.stringify drops
+ * them; array order is kept (it carries meaning: images, variants, options).
+ */
+function canonicalJson(value: unknown): string {
+  if (Array.isArray(value)) return `[${value.map((entry) => (entry === undefined ? "null" : canonicalJson(entry))).join(",")}]`;
+  if (value !== null && typeof value === "object" && !(value instanceof Date)) {
+    const entries = Object.entries(value).filter(([, entry]) => entry !== undefined).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+    return `{${entries.map(([key, entry]) => `${JSON.stringify(key)}:${canonicalJson(entry)}`).join(",")}}`;
+  }
+  return JSON.stringify(value) ?? "null";
 }
 
+/** THE sync hash: every path that records or compares a `channel_entity_map.sync_hash` uses this. */
+export function channelSyncHash(value: unknown): string {
+  return createHash("sha256").update(canonicalJson(value)).digest("hex");
+}
+
+const hash = channelSyncHash;
+
 /**
  * The suffix a store's product takes when its handle is already another store's slug: the first
  * label of the store domain (`kelly-felder.myshopify.com` → `kelly-felder`), slugified.
@@ -2206,7 +2228,13 @@ export class ChannelConnectorService {
     previousRoles: Map<string, string>;
   }>> {
     // Uploads what is missing and PLANS the entity's media links; `commitEntityLinks` writes them.
-    const images = item.images ?? [];
+    //
+    // Only the images the import ruling allows — the SAME `selectImportImages` the page fast path
+    // uses: the hero plus the first photo of each other variant. This path attached EVERY image
+    // the item listed, so the first converge of a product whose price changed pulled in the whole
+    // gallery the fast path had deliberately left out: an upload, an embed and a bump per photo.
+    const selection = selectImportImages(item);
+    const images = selection.hero === null ? [] : [selection.hero, ...selection.perVariant];
     const externalIds = [...new Set(images.map((image) => image.externalId).filter((id): id is string => id != null))];
     const urlHashes = [...new Set(images.map((image) => hash(image.url)))];
     const keyPredicates = [];
@@ -3914,7 +3942,9 @@ export class ChannelConnectorService {
    * products remain.
    */
   private async claimUnrecordedLinks(orgId: string, storeId: string, items: ChannelCatalogItem[]): Promise<void> {
-    if (items.length === 0) return;
+    // Nothing listed, nothing to claim: no query. Otherwise one select per converge call (a batch),
+    // never one per product.
+    if (!items.some((item) => (item.tags?.length ?? 0) > 0 || (item.categories?.length ?? 0) > 0 || item.brand !== undefined)) return;
     const unclaimed = await this.db.select({ externalId: channelEntityMap.externalId, entityId: channelEntityMap.entityId }).from(channelEntityMap).where(and(
       eq(channelEntityMap.organizationId, orgId),
       eq(channelEntityMap.storeId, storeId),