@porulle/plugin-channel-connector 0.49.0 → 0.50.0

package/dist/service.d.ts

@@ -231,6 +231,16 @@ export interface CatalogPushPreviewResult {
 }
 export declare function canExportTransition(from: ExportState, to: ExportState): boolean;
 export declare function canCatalogPushTransition(from: CatalogPushState, to: CatalogPushState): boolean;
+/**
+ * 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 declare function storeSlugSuffix(storeDomain: string): string;
+/**
+ * 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 declare function isSlugConflict(error: unknown): boolean;
 export declare const CATALOG_OUTBOUND_SUPPRESSION_WINDOW_MS: number;
 /**
  * A hero is streamed inside the page's own invocation, so it is bounded: a 30 MB TIFF a merchant
@@ -326,6 +336,23 @@ export declare class ChannelConnectorService {
     private applyTaxonomy;
     private applyMedia;
     private getStoreRecord;
+    /**
+     * 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 resolveStoreSlugs;
+    private readonly slugSuffixByStore;
+    private storeSlugSuffixFor;
+    /** 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;
     getStoreByDomain(shopDomain: string): Promise<ConnectedStore | undefined>;
     getStoresByDomain(shopDomain: string): Promise<ConnectedStore[]>;
     resolveCatalogFieldMapping(store: Pick<ConnectedStore, "provider" | "catalogFieldMapping">, filterableCustomFields?: ReadonlySet<string> | Readonly<Record<string, boolean>>, warnings?: string[]): CatalogFieldMapping;

package/dist/service.js

@@ -125,6 +125,41 @@ export function canCatalogPushTransition(from, to) {
 function hash(value) {
     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) {
+    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) {
+    let cursor = 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) {
+    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 = "";
 export const CATALOG_OUTBOUND_SUPPRESSION_WINDOW_MS = 15 * 60 * 1000;
@@ -1350,6 +1385,59 @@ export class ChannelConnectorService {
             .where(and(eq(connectedStores.organizationId, orgId), eq(connectedStores.id, id)));
         return rows[0];
     }
+    /**
+     * 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.
+     */
+    async resolveStoreSlugs(orgId, storeId, handles) {
+        const wanted = [...new Set(handles)];
+        const resolved = new Map();
+        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) => 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.
+    slugSuffixByStore = new Map();
+    async storeSlugSuffixFor(orgId, storeId) {
+        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. */
+    slugToKeep(currentSlug, resolved) {
+        return resolved.family.includes(currentSlug) ? currentSlug : resolved.slug;
+    }
     async getStoreByDomain(shopDomain) {
         const rows = await this.db
             .select()
@@ -1986,9 +2074,11 @@ export class ChannelConnectorService {
         const externalIds = [...new Set(items.map((item) => item.externalId))];
         const mappings = externalIds.length === 0 ? [] : await this.db.select().from(channelEntityMap).where(and(eq(channelEntityMap.organizationId, orgId), eq(channelEntityMap.storeId, storeId), eq(channelEntityMap.kind, "entity"), 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) => (slugFor.get(handle)?.family ?? [handle]).some((slug) => orphanSlugs.has(slug));
         const fresh = [];
         const editor = [];
         const seen = new Set();
@@ -2003,7 +2093,7 @@ export class ChannelConnectorService {
                 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 {
@@ -2026,33 +2116,61 @@ export class ChannelConnectorService {
             updated += survivors.length;
         }
         const createdItems = [];
-        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 = [];
             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", 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", 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", 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", externalId: variant.externalId, entityId, variantId, syncHash: hash(variant), lastSyncedAt: now }];
+                }),
+            ])).onConflictDoNothing();
+        }
         const media = await this.importHeroes(orgId, createdItems, actor);
         const entityIds = [];
         const emitted = new Set();
@@ -2568,6 +2686,8 @@ export class ChannelConnectorService {
         const failures = [];
         const entityIds = [];
         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));
         for (const item of items) {
             consumed += 1;
             try {
@@ -2593,8 +2713,15 @@ 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 () => {
+                    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)));
+                    const [orphan] = await this.db.select().from(sellableEntities).where(and(eq(sellableEntities.organizationId, orgId), eq(sellableEntities.sourceStoreId, storeId), inArray(sellableEntities.slug, resolvedSlug.family))).limit(1);
                     if (orphan) {
                         entityId = orphan.id;
                         existingEntity = orphan;
@@ -2602,33 +2729,46 @@ export class ChannelConnectorService {
                     }
                     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) => 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: [],
                             });
+                            return created.value.id;
+                        });
+                        let createError;
+                        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;
+                            }
                         }
-                        catch (error) {
-                            failures.push({ externalId: item.externalId, error: error instanceof Error ? error.message : "Failed to create catalog entity." });
+                        if (entityId === undefined) {
+                            failures.push({ externalId: item.externalId, error: createError instanceof Error ? createError.message : "Failed to create catalog entity." });
                             continue;
                         }
                         isNew = true;
@@ -2680,8 +2820,9 @@ export class ChannelConnectorService {
                         ? writable.status ?? (existingEntity.status === "archived" ? "active" : undefined)
                         : undefined;
                     const updateInput = {};
-                    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;
@@ -2693,11 +2834,29 @@ 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 });
+                            const mappedEntityId = entityMapping.entityId;
+                            const update = async () => {
+                                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;
@@ -2711,8 +2870,12 @@ export class ChannelConnectorService {
                 if (!attributes.ok)
                     return attributes;
                 const variantIds = await this.upsertVariants(orgId, storeId, entityId, writable, optionAxes.value.value, actor, warnings, !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;
@@ -2726,6 +2889,10 @@ export class ChannelConnectorService {
                 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");
                     if (!revision.ok) {
@@ -2848,12 +3015,14 @@ export class ChannelConnectorService {
             if (!mapping)
                 continue;
             const current = existingLevels.find((entry) => entry.entityId === mapping.entityId && entry.variantId === (mapping.variantId ?? null));
-            if (current?.quantityOnHand === level.available)
+            // 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)
@@ -3060,12 +3229,14 @@ export class ChannelConnectorService {
             if (!mapping)
                 continue;
             const current = existingLevels.find((entry) => entry.entityId === mapping.entityId && entry.variantId === (mapping.variantId ?? null));
-            if (current?.quantityOnHand === level.available)
+            // 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)
@@ -3332,8 +3503,11 @@ export class ChannelConnectorService {
         const warnings = conflicts.map((conflict) => `Held shared field conflict for entity "${conflict.entityId}", store "${conflict.storeId}", field "${conflict.fieldPath}" (local ${conflict.localValueSummary}, remote ${conflict.remoteValueSummary}).`);
         const writable = held.writable;
         const updateInput = {};
-        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 ?? {});