@porulle/plugin-channel-connector 0.49.0 → 0.50.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@porulle/plugin-channel-connector",
-  "version": "0.49.0",
+  "version": "0.50.0",
   "license": "MIT",
   "type": "module",
   "exports": {
@@ -19,15 +19,15 @@
   "dependencies": {
     "@hono/zod-openapi": "^1.2.2",
     "hono": "^4.12.5",
-    "@porulle/core": "0.49.0"
+    "@porulle/core": "0.50.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/service.ts

@@ -636,6 +636,39 @@ function hash(value: unknown): string {
   return createHash("sha256").update(JSON.stringify(value)).digest("hex");
 }
 
+/**
+ * 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.
+ */
+export function storeSlugSuffix(storeDomain: string): string {
+  const label = storeDomain.trim().toLowerCase().split(".")[0] ?? "";
+  return label.replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+}
+
+const SLUG_CONFLICT = /sellable_entities_org_slug_unique|Entity with slug .+ already exists|Slug ".+" already exists/;
+
+/**
+ * Whether a create or update lost a slug to another writer — core's pre-check message, or the
+ * unique index itself, which a driver error can carry several `cause`s deep.
+ */
+export function isSlugConflict(error: unknown): boolean {
+  let cursor: unknown = error;
+  for (let depth = 0; depth < 5; depth += 1) {
+    if (typeof cursor === "string") return SLUG_CONFLICT.test(cursor);
+    if (typeof cursor !== "object" || cursor === null) return false;
+    if ("constraint" in cursor && cursor.constraint === "sellable_entities_org_slug_unique") return true;
+    if ("message" in cursor && typeof cursor.message === "string" && SLUG_CONFLICT.test(cursor.message)) return true;
+    cursor = "cause" in cursor ? cursor.cause : undefined;
+  }
+  return false;
+}
+
+function errorMessage(error: unknown): string {
+  if (typeof error === "string") return error;
+  if (typeof error === "object" && error !== null && "message" in error && typeof error.message === "string") return error.message;
+  return String(error);
+}
+
 /** Mid-import map rows carry this until convergence finishes; must not equal any real remote hash. */
 const PENDING_ENTITY_MAP_SYNC_HASH = "";
 
@@ -2050,6 +2083,65 @@ export class ChannelConnectorService {
     return rows[0] as ConnectedStore | undefined;
   }
 
+  /**
+   * The slug each wanted handle takes for THIS store. Slugs stay unique across the organization —
+   * the storefront resolves `/:idOrSlug` org-wide — but one platform organization holds many
+   * merchants, and two of them may sell the same handle.
+   *
+   * A handle's FAMILY for a store is, in order: the bare handle, `<handle>-<store suffix>`, and
+   * `<handle>-<store suffix>-<store id prefix>`. The last is unique per store, so a third store with
+   * the same domain label still gets a slug of its own. A new product takes the first member no
+   * other store holds. An existing product whose slug is already in its handle's family KEEPS it
+   * (see `slugToKeep`): a slug, once assigned, is a shared link and is never recomputed.
+   */
+  private async resolveStoreSlugs(
+    orgId: string,
+    storeId: string,
+    handles: readonly string[],
+  ): Promise<Map<string, { slug: string; family: string[] }>> {
+    const wanted = [...new Set(handles)];
+    const resolved = new Map<string, { slug: string; family: string[] }>();
+    if (wanted.length === 0) return resolved;
+    const suffix = await this.storeSlugSuffixFor(orgId, storeId);
+    const idPart = storeId.replace(/[^a-z0-9]/gi, "").slice(0, 8).toLowerCase();
+    const familyOf = (handle: string): string[] => suffix
+      ? [handle, `${handle}-${suffix}`, `${handle}-${suffix}-${idPart}`]
+      : [handle, `${handle}-${idPart}`];
+    const families = new Map(wanted.map((handle) => [handle, familyOf(handle)]));
+    const owners = await this.db.select({ slug: sellableEntities.slug, sourceStoreId: sellableEntities.sourceStoreId })
+      .from(sellableEntities)
+      .where(and(eq(sellableEntities.organizationId, orgId), inArray(sellableEntities.slug, [...families.values()].flat())));
+    // Only ANOTHER STORE's product moves this one to a qualified slug. A product a person made in
+    // Merchant Center (no source store) holding the handle stays a loud slug conflict, as before.
+    const heldElsewhere = new Set(owners.filter((row) => row.sourceStoreId !== null && row.sourceStoreId !== storeId).map((row) => row.slug));
+    for (const [handle, family] of families) {
+      // Every member held by another store is only reachable through a hand-made slug; the last
+      // member is then used anyway and the create fails loudly on the unique index.
+      const slug = family.find((candidate) => !heldElsewhere.has(candidate)) ?? family[family.length - 1] ?? handle;
+      resolved.set(handle, { slug, family });
+    }
+    return resolved;
+  }
+
+  // ponytail: cached for the service instance's lifetime (one task invocation), so a batched import
+  // reads the store once. A store whose domain changes mid-invocation keeps the old suffix until the
+  // next one — a new slug family only, never a rename of a slug already assigned.
+  private readonly slugSuffixByStore = new Map<string, string>();
+
+  private async storeSlugSuffixFor(orgId: string, storeId: string): Promise<string> {
+    const cached = this.slugSuffixByStore.get(storeId);
+    if (cached !== undefined) return cached;
+    const suffix = storeSlugSuffix((await this.getStoreRecord(orgId, storeId))?.storeDomain ?? "");
+    this.slugSuffixByStore.set(storeId, suffix);
+    return suffix;
+  }
+
+  /** The slug an existing product converges to: its current one while that is still in the family
+   *  of the handle the store sends, so a slug is never recomputed out from under a shared link. */
+  private slugToKeep(currentSlug: string, resolved: { slug: string; family: string[] }): string {
+    return resolved.family.includes(currentSlug) ? currentSlug : resolved.slug;
+  }
+
   async getStoreByDomain(shopDomain: string): Promise<ConnectedStore | undefined> {
     const rows = await this.db
       .select()
@@ -2796,13 +2888,15 @@ export class ChannelConnectorService {
       inArray(channelEntityMap.externalId, externalIds),
     ));
     const mappingByExternalId = new Map(mappings.map((row) => [row.externalId, row]));
-    const slugs = [...new Set(items.map((item) => item.slug))];
+    const slugFor = await this.resolveStoreSlugs(orgId, storeId, items.map((item) => item.slug));
+    const slugs = [...new Set([...slugFor.values()].flatMap((resolved) => resolved.family))];
     const orphans = slugs.length === 0 ? [] : await this.db.select({ slug: sellableEntities.slug }).from(sellableEntities).where(and(
       eq(sellableEntities.organizationId, orgId),
       eq(sellableEntities.sourceStoreId, storeId),
       inArray(sellableEntities.slug, slugs),
     ));
     const orphanSlugs = new Set(orphans.map((row) => row.slug));
+    const isOrphan = (handle: string): boolean => (slugFor.get(handle)?.family ?? [handle]).some((slug) => orphanSlugs.has(slug));
 
     const fresh: ChannelCatalogItem[] = [];
     const editor: ChannelCatalogItem[] = [];
@@ -2817,7 +2911,7 @@ export class ChannelConnectorService {
       if (mapping && mapping.syncHash === hash(item)) {
         entityByExternalId.set(item.externalId, mapping.entityId);
         unchanged += 1;
-      } else if (mapping || orphanSlugs.has(item.slug)) {
+      } else if (mapping || isOrphan(item.slug)) {
         editor.push(item);
       } else {
         fresh.push(item);
@@ -2839,31 +2933,58 @@ export class ChannelConnectorService {
     }
 
     const createdItems: Array<{ item: ChannelCatalogItem; entityId: string; variantIds: Record<string, string> }> = [];
-    if (fresh.length > 0) {
-      const report = await this.catalog.importProducts(fresh.map(toImportProduct), { sourceStoreId: storeId, errorPolicy: "reject-failed-rows" }, actor);
+    // Two stores onboarding at once can both resolve a handle as free and then both create it. The
+    // loser's collision is transient: re-resolve those items once (the winner is now visible, so they
+    // take the store-qualified slug) and try again. A second collision is reported as the item's.
+    let pending = fresh;
+    for (let attempt = 0; pending.length > 0; attempt += 1) {
+      // The slug is resolved on the import row only: the map row's hash stays the hash of the item
+      // as the store sent it, so the next page still reads it as unchanged.
+      const report = await this.catalog.importProducts(
+        pending.map((item) => toImportProduct({ ...item, slug: slugFor.get(item.slug)?.slug ?? item.slug })),
+        { sourceStoreId: storeId, errorPolicy: "reject-failed-rows" },
+        actor,
+      );
       if (!report.ok) return PluginErr(report.error.message, report.error.code);
+      const collided: Array<{ item: ChannelCatalogItem; failure: CatalogConvergenceFailure }> = [];
       for (const [index, row] of report.value.rows.entries()) {
-        const item = fresh[index];
+        const item = pending[index];
         if (!item) continue;
         if (row.status === "failed") {
-          failures.push({ externalId: row.ref, error: `${row.code}: ${row.error}` });
+          const failure = { externalId: row.ref, error: `${row.code}: ${row.error}` };
+          const lostSlug = row.code === "slug-conflict" || (row.code === "conflict" && isSlugConflict(row.error));
+          if (attempt === 0 && lostSlug) collided.push({ item, failure });
+          else failures.push(failure);
           continue;
         }
         warnings.push(...row.warnings);
         entityByExternalId.set(item.externalId, row.entityId);
         createdItems.push({ item, entityId: row.entityId, variantIds: row.variantIds });
       }
-      if (createdItems.length > 0) {
-        const now = new Date();
-        await this.db.insert(channelEntityMap).values(createdItems.flatMap(({ item, entityId, variantIds }) => [
-          { organizationId: orgId, storeId, kind: "entity" as const, externalId: item.externalId, entityId, syncHash: hash(item), lastSyncedAt: now },
-          ...item.variants.flatMap((variant) => {
-            const variantId = variantIds[variant.externalId];
-            return variantId === undefined ? [] : [{ organizationId: orgId, storeId, kind: "variant" as const, externalId: variant.externalId, entityId, variantId, syncHash: hash(variant), lastSyncedAt: now }];
-          }),
-        ])).onConflictDoNothing();
+      pending = [];
+      if (collided.length > 0) {
+        const again = await this.resolveStoreSlugs(orgId, storeId, collided.map(({ item }) => item.slug));
+        for (const { item, failure } of collided) {
+          const before = slugFor.get(item.slug)?.slug ?? item.slug;
+          const after = again.get(item.slug);
+          // Retry only when another STORE took the handle: a slug held by a product made in
+          // Merchant Center resolves to the same slug again, and stays the loud conflict it was.
+          if (after === undefined || after.slug === before) { failures.push(failure); continue; }
+          slugFor.set(item.slug, after);
+          pending.push(item);
+        }
       }
     }
+    if (createdItems.length > 0) {
+      const now = new Date();
+      await this.db.insert(channelEntityMap).values(createdItems.flatMap(({ item, entityId, variantIds }) => [
+        { organizationId: orgId, storeId, kind: "entity" as const, externalId: item.externalId, entityId, syncHash: hash(item), lastSyncedAt: now },
+        ...item.variants.flatMap((variant) => {
+          const variantId = variantIds[variant.externalId];
+          return variantId === undefined ? [] : [{ organizationId: orgId, storeId, kind: "variant" as const, externalId: variant.externalId, entityId, variantId, syncHash: hash(variant), lastSyncedAt: now }];
+        }),
+      ])).onConflictDoNothing();
+    }
 
     const media = await this.importHeroes(orgId, createdItems, actor);
     const entityIds: string[] = [];
@@ -3486,6 +3607,8 @@ export class ChannelConnectorService {
     const failures: CatalogConvergenceFailure[] = [];
     const entityIds: string[] = [];
     const committed = new Set<string>();
+    // 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));
     for (const item of items) {
       consumed += 1;
       try {
@@ -3522,43 +3645,61 @@ export class ChannelConnectorService {
           existingEntity = entity;
         }
       }
+      let resolvedSlug = slugFor.get(item.slug) ?? { slug: item.slug, family: [item.slug] };
+      // A slug lost to a concurrent writer (another store onboarding the same handle) is transient:
+      // re-resolve once, and the winner being visible now moves this item to its qualified slug.
+      const reresolveSlug = async (): Promise<void> => {
+        resolvedSlug = (await this.resolveStoreSlugs(orgId, storeId, [item.slug])).get(item.slug) ?? resolvedSlug;
+        slugFor.set(item.slug, resolvedSlug);
+      };
       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),
-        ));
+          inArray(sellableEntities.slug, resolvedSlug.family),
+        )).limit(1);
         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;
+          const createEntity = (slug: string): Promise<string> => this.transact(async (tx) => {
+            const txContext = createTxContext(tx, { actor });
+            const created = await this.catalog.create({
+              type: "product",
+              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: [],
             });
-          } catch (error) {
-            failures.push({ externalId: item.externalId, error: error instanceof Error ? error.message : "Failed to create catalog entity." });
+            return created.value.id;
+          });
+          let createError: unknown;
+          for (let attempt = 0; attempt < 2 && entityId === undefined; attempt += 1) {
+            try {
+              entityId = await createEntity(resolvedSlug.slug);
+            } catch (error) {
+              createError = error;
+              if (attempt > 0 || !isSlugConflict(error)) break;
+              const before = resolvedSlug.slug;
+              await reresolveSlug();
+              if (resolvedSlug.slug === before) break;
+            }
+          }
+          if (entityId === undefined) {
+            failures.push({ externalId: item.externalId, error: createError instanceof Error ? createError.message : "Failed to create catalog entity." });
             continue;
           }
           isNew = true;
@@ -3618,8 +3759,9 @@ export class ChannelConnectorService {
           status?: string;
           isVisible?: boolean;
         } = {};
-        if (ownerAllows(owners, "entity.slug") && !blockedPaths.has("entity.slug") && existingEntity.slug !== writable.slug) {
-          updateInput.slug = writable.slug;
+        const keptSlug = this.slugToKeep(existingEntity.slug, resolvedSlug);
+        if (ownerAllows(owners, "entity.slug") && !blockedPaths.has("entity.slug") && existingEntity.slug !== keptSlug) {
+          updateInput.slug = keptSlug;
         }
         if (hash(remoteMetadata) !== hash(existingEntity.metadata ?? {})) updateInput.metadata = remoteMetadata;
         if (remoteStatus !== undefined && !blockedPaths.has("entity.status") && remoteStatus !== existingEntity.status) {
@@ -3630,10 +3772,25 @@ export class ChannelConnectorService {
           ? Object.keys(updateInput).length > 0
           : remoteChanged || existingEntity.status === "archived";
         if (shouldUpdate) {
-          converged += 1;
           if (Object.keys(updateInput).length > 0) {
-            const updated = await this.catalog.update(entityMapping.entityId, updateInput, actor, CHANNEL_CONVERGENCE_CTX);
-            if (!updated.ok) { failures.push({ externalId: item.externalId, error: updated.error.message }); continue; }
+            const mappedEntityId = entityMapping.entityId;
+            const update = async (): Promise<unknown> => {
+              try {
+                const updated = await this.catalog.update(mappedEntityId, updateInput, actor, CHANNEL_CONVERGENCE_CTX);
+                return updated.ok ? undefined : updated.error;
+              } catch (error) {
+                return error;
+              }
+            };
+            let updateError = await update();
+            if (updateError !== undefined && updateInput.slug !== undefined && isSlugConflict(updateError)) {
+              await reresolveSlug();
+              const retrySlug = this.slugToKeep(existingEntity.slug, resolvedSlug);
+              if (retrySlug === existingEntity.slug) delete updateInput.slug;
+              else updateInput.slug = retrySlug;
+              updateError = Object.keys(updateInput).length > 0 ? await update() : undefined;
+            }
+            if (updateError !== undefined) { failures.push({ externalId: item.externalId, error: errorMessage(updateError) }); continue; }
             entityTouched = true;
           }
         }
@@ -3654,7 +3811,9 @@ export class ChannelConnectorService {
         !heldSharedPaths.includes("options") && owners.get("options") !== "platform",
         item,
       );
-      if (!variantIds.ok) return variantIds;
+      // A variant the store's own data makes unwritable (a sku another of its products holds) is
+      // that item's failure, reported with its error — not a page error the caller would retry.
+      if (!variantIds.ok) { failures.push({ externalId: item.externalId, error: variantIds.error }); continue; }
       const taxonomy = await this.applyTaxonomy(orgId, entityId, writable, actor, warnings);
       if (!taxonomy.ok) return taxonomy;
       const media = await this.applyMedia(orgId, entityId, writable, variantIds.value.value, actor, warnings, owners);
@@ -3665,6 +3824,9 @@ export class ChannelConnectorService {
       skipped.push(...media.value.skipped.map((fieldPath) => ({ entityId, fieldPath })));
       entityTouched = entityTouched || optionAxes.value.changed || variantIds.value.changed || media.value.changed || attributes.value.changed;
       if (entityTouched) entitiesTouched += 1;
+      // Counted from what was written, not from the stored hash: a hash that moved while the
+      // product did not (a blanked map row, a change in how an item serialises) is not drift.
+      if (entityTouched && entityMapping && !isNew) converged += 1;
 
       if (entityTouched) {
         const revision = await this.catalog.recordEntityRevision(entityId, actor, "import");
@@ -3800,11 +3962,13 @@ export class ChannelConnectorService {
       const mapping = mappings.find((entry) => entry.externalId === level.externalId);
       if (!mapping) continue;
       const current = existingLevels.find((entry) => entry.entityId === mapping.entityId && entry.variantId === (mapping.variantId ?? null));
-      if (current?.quantityOnHand === level.available) continue;
+      // Stock cannot sit below zero here, so negative remote stock compares as the zero it is stored as.
+      const quantity = Math.max(0, level.available);
+      if (current?.quantityOnHand === quantity) continue;
       const result = await inventoryService.setAbsolute({
         entityId: mapping.entityId,
         ...(mapping.variantId ? { variantId: mapping.variantId } : {}),
-        quantity: level.available,
+        quantity,
         reason: `Inventory reconciliation from ${store.provider}`,
       }, actor);
       if (!result.ok) return PluginErr(result.error?.message ?? "Inventory reconciliation failed.");
@@ -4043,11 +4207,13 @@ export class ChannelConnectorService {
       const mapping = mappings.find((entry) => entry.externalId === level.externalId);
       if (!mapping) continue;
       const current = existingLevels.find((entry) => entry.entityId === mapping.entityId && entry.variantId === (mapping.variantId ?? null));
-      if (current?.quantityOnHand === level.available) continue;
+      // Stock cannot sit below zero here, so negative remote stock compares as the zero it is stored as.
+      const quantity = Math.max(0, level.available);
+      if (current?.quantityOnHand === quantity) continue;
       const result = await inventoryService.setAbsolute({
         entityId: mapping.entityId,
         ...(mapping.variantId ? { variantId: mapping.variantId } : {}),
-        quantity: level.available,
+        quantity,
         reason: `Inventory sync from ${store.provider}`,
       }, actor);
       if (!result.ok) return PluginErr(result.error?.message ?? "Inventory sync failed.");
@@ -4327,8 +4493,10 @@ export class ChannelConnectorService {
       status?: string;
       isVisible?: boolean;
     } = {};
-    if (fieldPaths.includes("entity.slug") && ownerAllows(owners, "entity.slug") && !blockedPaths.has("entity.slug") && entity.slug !== writable.slug) {
-      updateInput.slug = writable.slug;
+    if (fieldPaths.includes("entity.slug") && ownerAllows(owners, "entity.slug") && !blockedPaths.has("entity.slug") && typeof writable.slug === "string") {
+      const resolved = (await this.resolveStoreSlugs(orgId, storeId, [writable.slug])).get(writable.slug);
+      const slug = resolved ? this.slugToKeep(entity.slug, resolved) : writable.slug;
+      if (entity.slug !== slug) updateInput.slug = slug;
     }
     if (Object.keys(writable.metadata ?? {}).length > 0) {
       const remoteEntityMetadata = mergeMetadata(entity.metadata, writable.metadata ?? {});