@porulle/plugin-channel-connector 0.53.1 → 0.55.0

package/dist/deletion-policy.d.ts

@@ -0,0 +1,19 @@
+/**
+ * THE deletion policy for a store's mapped products that a fetch no longer lists — one home for
+ * the rule, shared by `reconcile()` and the app's import finalize barrier.
+ *
+ * A fetch that succeeded is not a fetch that was complete: a merchant API hiccup, pagination that
+ * stopped early, or an auth scope change returns fewer products than the store has, and archiving
+ * "everything absent" then wipes the store. Found on the sim, 2026-09-24. So the plan REFUSES:
+ *  - an empty fetch over a store that has mapped products;
+ *  - more absent products than max(ABSENT_ARCHIVE_FLOOR, floor(ABSENT_ARCHIVE_FRACTION × mapped)).
+ * A refusal archives nothing; the caller surfaces the reason for a person to look at.
+ */
+export declare const ABSENT_ARCHIVE_FLOOR = 5;
+export declare const ABSENT_ARCHIVE_FRACTION = 0.2;
+export type AbsentArchivePlan = {
+    archive: string[];
+} | {
+    refused: string;
+};
+export declare function planAbsentArchives(mappedExternalIds: Iterable<string>, presentExternalIds: Iterable<string>): AbsentArchivePlan;

package/dist/deletion-policy.js

@@ -0,0 +1,28 @@
+/**
+ * THE deletion policy for a store's mapped products that a fetch no longer lists — one home for
+ * the rule, shared by `reconcile()` and the app's import finalize barrier.
+ *
+ * A fetch that succeeded is not a fetch that was complete: a merchant API hiccup, pagination that
+ * stopped early, or an auth scope change returns fewer products than the store has, and archiving
+ * "everything absent" then wipes the store. Found on the sim, 2026-09-24. So the plan REFUSES:
+ *  - an empty fetch over a store that has mapped products;
+ *  - more absent products than max(ABSENT_ARCHIVE_FLOOR, floor(ABSENT_ARCHIVE_FRACTION × mapped)).
+ * A refusal archives nothing; the caller surfaces the reason for a person to look at.
+ */
+export const ABSENT_ARCHIVE_FLOOR = 5;
+export const ABSENT_ARCHIVE_FRACTION = 0.2;
+export function planAbsentArchives(mappedExternalIds, presentExternalIds) {
+    const mapped = [...new Set(mappedExternalIds)];
+    const present = new Set(presentExternalIds);
+    const absent = mapped.filter((externalId) => !present.has(externalId));
+    if (absent.length === 0)
+        return { archive: [] };
+    if (present.size === 0) {
+        return { refused: `The fetch listed no products while ${mapped.length} are mapped; refusing to archive them.` };
+    }
+    const bound = Math.max(ABSENT_ARCHIVE_FLOOR, Math.floor(ABSENT_ARCHIVE_FRACTION * mapped.length));
+    if (absent.length > bound) {
+        return { refused: `${absent.length} of ${mapped.length} mapped products are absent from the fetch, above the bound of ${bound}; refusing to archive them.` };
+    }
+    return { archive: absent };
+}

package/dist/index.d.ts

@@ -1,4 +1,6 @@
 import { type ChannelConnectorPluginOptions } from "./service.js";
+export { ABSENT_ARCHIVE_FLOOR, ABSENT_ARCHIVE_FRACTION, planAbsentArchives } from "./deletion-policy.js";
+export type { AbsentArchivePlan } from "./deletion-policy.js";
 export { mockChannelConnector } from "./mock-connector.js";
 export type { MockChannelConnectorOptions } 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";

package/dist/index.js

@@ -7,6 +7,7 @@ import { channelCatalogPushEvents, channelCatalogPushes, channelCatalogConflicts
 import { ChannelConnectorService, catalogPushConcurrencyKey, CHANNEL_INVENTORY_MAX_ITEMS_PER_INVOCATION, } from "./service.js";
 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 { 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

@@ -39,6 +39,8 @@ export interface ReconcileReport extends Record<string, unknown> {
     inventoryUpdated: number;
     openConflicts: number;
     driftAlert: boolean;
+    /** Why this reconcile archived nothing although mapped products were absent (`planAbsentArchives`). */
+    refused?: string;
     skipped?: CatalogFieldSkip[];
     conflicts?: CatalogFieldConflict[];
     warnings?: string[];
@@ -357,6 +359,17 @@ export declare class ChannelConnectorService {
      */
     private createTaxonomyOrAdopt;
     private applyTaxonomy;
+    /**
+     * Writes one item's planned links and versions the entity for them, in ONE transaction: the
+     * entity's `updated_at` moves with the links or not at all, and `catalog.afterUpdate` fires once
+     * for the item with every link path that really changed (`["categories","tags"]`), not once per
+     * link. Returns those paths; empty means nothing changed.
+     *
+     * An entity CREATED by this converge is not versioned for its links: its creation already put it
+     * in front of every consumer, so a bump here would re-project a product in the same breath as its
+     * first projection — the cold-import cost this rule exists to avoid.
+     */
+    private commitEntityLinks;
     private applyMedia;
     private getStoreRecord;
     /**

package/dist/service.js

@@ -1,9 +1,10 @@
 import { createHash } from "node:crypto";
-import { CommerceInvalidTransitionError, CommerceValidationError, Ok, PluginErr, createTxContext, createSystemActor, } from "@porulle/core";
+import { CommerceInvalidTransitionError, CommerceValidationError, Ok, PluginErr, createTxContext, createSystemActor, linkFieldPaths, writeEntityLinks, } from "@porulle/core";
 import { isValidFieldPath, requireUserId } from "@porulle/core";
 import { CHANNEL_CONVERGENCE_CTX } from "./catalog-push-trigger.js";
 import { and, desc, eq, inArray, isNull, lte, or, sql } from "@porulle/core/drizzle";
-import { brands, categories, customerAddresses, customers, entityMedia, entityBrands, entityCategories, entityTags, inventoryLevels, mediaAssets, optionTypes, optionValues, orderLineItems, orders, prices, sellableAttributes, sellableCustomFields, sellableEntities, sellableEntityRevisions, entityFieldDefinitions, tags, variants, variantOptionValues, } from "@porulle/core/schema";
+import { brands, categories, customerAddresses, customers, entityMedia, inventoryLevels, mediaAssets, optionTypes, optionValues, orderLineItems, orders, prices, sellableAttributes, sellableCustomFields, sellableEntities, sellableEntityRevisions, entityFieldDefinitions, tags, variants, variantOptionValues, } from "@porulle/core/schema";
+import { planAbsentArchives } from "./deletion-policy.js";
 import { channelCatalogPushEvents, channelCatalogPushes, channelCatalogConflicts, channelCatalogConflictEvents, channelEntityMap, channelExportEvents, channelOrderExports, connectedStores, channelRefundEvents, channelRefundRequests, } from "./schema.js";
 import { mergeCatalogFieldMapping, normalizeCatalogFieldMapping, selectCatalogFieldMapping, } from "./catalog-field-mapping.js";
 export const CATALOG_PUSH_BATCH_SIZES = {
@@ -1333,14 +1334,11 @@ export class ChannelConnectorService {
         return existing !== undefined ? Ok(existing) : PluginErr(`${label}: ${errorMessage(failure)}`);
     }
     async applyTaxonomy(orgId, entityId, item, actor, warnings) {
+        // Resolves (creating where missing) the category, brand and tag rows the item names, and PLANS
+        // the entity's links to them. The links are written by `commitEntityLinks`, in one transaction
+        // with the entity's version bump; a link that already exists writes nothing there.
         const taxonomy = await this.taxonomyFor(orgId);
-        // The links this entity already has, read only for the classes the item names. A link already
-        // there is not re-written, and a link that is added is what reports the taxonomy as changed.
-        const linkedCategories = new Set((item.categories ?? []).length === 0 ? [] : (await this.db
-            .select({ id: entityCategories.categoryId }).from(entityCategories).where(eq(entityCategories.entityId, entityId))).map((row) => row.id));
-        const linkedBrands = new Set(!item.brand ? [] : (await this.db
-            .select({ id: entityBrands.brandId }).from(entityBrands).where(eq(entityBrands.entityId, entityId))).map((row) => row.id));
-        let changed = false;
+        const links = { categories: [], brands: [], tags: [] };
         const categoryRows = taxonomy.categories;
         for (const slug of new Set(item.categories ?? [])) {
             let category = categoryRows.find((row) => row.slug === slug);
@@ -1355,12 +1353,7 @@ export class ChannelConnectorService {
                 category = created.value;
                 categoryRows.push(category);
             }
-            if (linkedCategories.has(category.id))
-                continue;
-            const linked = await this.catalog.addToCategory(entityId, category.id, actor);
-            if (!linked.ok)
-                return PluginErr(linked.error.message);
-            changed = true;
+            links.categories.push({ entityId, categoryId: category.id, sortOrder: 0 });
         }
         const brandRows = taxonomy.brands;
         if (item.brand) {
@@ -1373,12 +1366,7 @@ export class ChannelConnectorService {
                 brand = created.value;
                 brandRows.push(brand);
             }
-            if (!linkedBrands.has(brand.id)) {
-                const linked = await this.catalog.addToBrand(entityId, brand.id, actor);
-                if (!linked.ok)
-                    return PluginErr(linked.error.message);
-                changed = true;
-            }
+            links.brands.push({ entityId, brandId: brand.id, sortOrder: 0 });
         }
         const tagRows = taxonomy.tags;
         for (const slug of new Set(item.tags ?? [])) {
@@ -1390,13 +1378,43 @@ export class ChannelConnectorService {
                     return PluginErr(`Tag "${slug}" was not persisted.`);
                 tagRows.push(tag);
             }
-            const added = await this.db.insert(entityTags).values({ entityId, tagId: tag.id }).onConflictDoNothing().returning({ tagId: entityTags.tagId });
-            if (added.length > 0)
-                changed = true;
+            links.tags.push({ entityId, tagId: tag.id });
+        }
+        return Ok(links);
+    }
+    /**
+     * Writes one item's planned links and versions the entity for them, in ONE transaction: the
+     * entity's `updated_at` moves with the links or not at all, and `catalog.afterUpdate` fires once
+     * for the item with every link path that really changed (`["categories","tags"]`), not once per
+     * link. Returns those paths; empty means nothing changed.
+     *
+     * An entity CREATED by this converge is not versioned for its links: its creation already put it
+     * in front of every consumer, so a bump here would re-project a product in the same breath as its
+     * first projection — the cold-import cost this rule exists to avoid.
+     */
+    async commitEntityLinks(orgId, entityId, planned, previousRoles, isNew, actor) {
+        try {
+            return Ok(await this.transact(async (tx) => {
+                const written = await writeEntityLinks(tx, orgId, planned);
+                const paths = new Set(linkFieldPaths(written).get(entityId));
+                for (const row of written.placed) {
+                    const previous = previousRoles.get(`${row.mediaAssetId}:${row.variantId}`);
+                    if (previous !== undefined)
+                        paths.add(`media.${previous}`);
+                }
+                const changed = [...paths].sort();
+                if (changed.length > 0 && !isNew) {
+                    await this.catalog.notifyEntityChanged(entityId, changed, actor, createTxContext(tx, { actor }));
+                }
+                return changed;
+            }));
+        }
+        catch (error) {
+            return PluginErr(error instanceof Error ? error.message : "Failed to write the entity's links.");
         }
-        return Ok({ changed });
     }
     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 ?? [];
         const externalIds = [...new Set(images.map((image) => image.externalId).filter((id) => id != null))];
         const urlHashes = [...new Set(images.map((image) => hash(image.url)))];
@@ -1412,8 +1430,10 @@ export class ChannelConnectorService {
             : await this.db.select().from(mediaAssets).where(and(eq(mediaAssets.organizationId, orgId), or(...keyPredicates)));
         const links = await this.db.select().from(entityMedia).where(eq(entityMedia.entityId, entityId));
         let imported = 0;
-        let changed = false;
+        let uploaded = false;
         const skipped = [];
+        const planned = { media: [], mediaPlacements: [] };
+        const previousRoles = new Map();
         // A Cloudflare Worker may hold at most six simultaneous outbound connections per
         // invocation, and one image costs two of them — the download and the storage put — so
         // 6 / 2 = 3 images may be in flight. A fourth would queue behind the platform limit
@@ -1526,7 +1546,7 @@ export class ChannelConnectorService {
             warnings.push(...resolved.imageWarnings);
             imported += resolved.imported;
             if (resolved.imageChanged)
-                changed = true;
+                uploaded = true;
         }
         for (const [imageIndex, image] of images.entries()) {
             const mediaAssetId = resolvedImages[imageIndex]?.mediaAssetId;
@@ -1554,21 +1574,12 @@ export class ChannelConnectorService {
                             continue;
                     }
                     if (existingLink.role !== image.role || existingLink.sortOrder !== (image.sortOrder ?? 0)) {
-                        await this.db.update(entityMedia).set({ role: image.role, sortOrder: image.sortOrder ?? 0 }).where(and(eq(entityMedia.entityId, entityId), eq(entityMedia.mediaAssetId, mediaAssetId), target.variantId === undefined ? isNull(entityMedia.variantId) : eq(entityMedia.variantId, target.variantId)));
-                        changed = true;
+                        planned.mediaPlacements.push({ entityId, variantId: target.variantId ?? null, mediaAssetId, role: image.role, sortOrder: image.sortOrder ?? 0 });
+                        previousRoles.set(`${mediaAssetId}:${target.variantId ?? null}`, existingLink.role);
                     }
                     continue;
                 }
-                const attached = await this.media.attachToEntity({
-                    entityId,
-                    mediaAssetId,
-                    role: image.role,
-                    sortOrder: image.sortOrder ?? 0,
-                    ...(target.variantId !== undefined ? { variantId: target.variantId } : {}),
-                }, actor);
-                if (!attached.ok)
-                    return PluginErr(attached.error.message);
-                changed = true;
+                planned.media.push({ entityId, variantId: target.variantId ?? null, mediaAssetId, role: image.role, sortOrder: image.sortOrder ?? 0 });
                 links.push({
                     entityId,
                     mediaAssetId,
@@ -1579,7 +1590,7 @@ export class ChannelConnectorService {
                 });
             }
         }
-        return Ok({ imported, changed, skipped });
+        return Ok({ imported, uploaded, skipped, links: planned, previousRoles });
     }
     async getStoreRecord(orgId, id) {
         const rows = await this.db
@@ -2452,13 +2463,13 @@ export class ChannelConnectorService {
             }
         }));
         if (outcomes.length > 0) {
-            await this.db.insert(entityMedia).values(outcomes.flatMap(({ entityId, mediaAssetId, hero, variantIds }) => [
-                { entityId, mediaAssetId, role: "primary", sortOrder: hero.sortOrder ?? 0 },
-                ...(hero.variantExternalIds ?? []).flatMap((externalId) => {
-                    const variantId = variantIds[externalId];
-                    return variantId === undefined ? [] : [{ entityId, variantId, mediaAssetId, role: hero.role, sortOrder: hero.sortOrder ?? 0 }];
-                }),
-            ])).onConflictDoNothing();
+            await writeEntityLinks(this.db, orgId, { media: outcomes.flatMap(({ entityId, mediaAssetId, hero, variantIds }) => [
+                    { entityId, variantId: null, mediaAssetId, role: "primary", sortOrder: hero.sortOrder ?? 0 },
+                    ...(hero.variantExternalIds ?? []).flatMap((externalId) => {
+                        const variantId = variantIds[externalId];
+                        return variantId === undefined ? [] : [{ entityId, variantId, mediaAssetId, role: hero.role, sortOrder: hero.sortOrder ?? 0 }];
+                    }),
+                ]) });
         }
         return { heroesImported: outcomes.filter((outcome) => outcome.imported).length, mediaFailures, deferredMedia };
     }
@@ -3085,11 +3096,16 @@ export class ChannelConnectorService {
                 const media = await this.applyMedia(orgId, entityId, writable, variantIds.value.value, actor, warnings, owners);
                 if (!media.ok)
                     return media;
+                const links = await this.commitEntityLinks(orgId, entityId, { ...taxonomy.value, ...media.value.links }, media.value.previousRoles, isNew, actor);
+                if (!links.ok) {
+                    failures.push({ externalId: item.externalId, error: links.error });
+                    continue;
+                }
                 attributesCreated += attributes.value.created;
                 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 || links.value.length > 0 || media.value.uploaded || attributes.value.changed
                     || identity.written.has(item.externalId);
                 const skuClashes = identity.clashes.get(item.externalId);
                 if (skuClashes) {
@@ -3214,11 +3230,14 @@ export class ChannelConnectorService {
         const converged = await this.convergeCatalogItems(orgId, storeId, items, actor);
         if (!converged.ok)
             return converged;
-        const present = new Set(items.map((item) => item.externalId));
+        // Planned BEFORE anything is archived: an empty or truncated fetch is refused whole (see
+        // `planAbsentArchives`), and the refusal is reported, never half-applied.
+        const plan = planAbsentArchives(entityMappings.map((mapping) => mapping.externalId), items.map((item) => item.externalId));
+        const toArchive = new Set("archive" in plan ? plan.archive : []);
         let archived = 0;
         const skipped = [...converged.value.skipped];
         for (const mapping of entityMappings) {
-            if (present.has(mapping.externalId))
+            if (!toArchive.has(mapping.externalId))
                 continue;
             const [entity] = await this.db.select({ status: sellableEntities.status }).from(sellableEntities).where(and(eq(sellableEntities.organizationId, orgId), eq(sellableEntities.id, mapping.entityId)));
             if (entity?.status !== "archived") {
@@ -3266,7 +3285,8 @@ export class ChannelConnectorService {
             archived,
             inventoryUpdated,
             openConflicts: openConflictRows.length,
-            driftAlert: converged.value.imported + converged.value.converged + archived > threshold,
+            driftAlert: "refused" in plan || converged.value.imported + converged.value.converged + archived > threshold,
+            ...("refused" in plan ? { refused: plan.refused } : {}),
             ...(skipped.length > 0 ? { skipped: uniqueSkipped(skipped) } : {}),
             ...(converged.value.conflicts.length > 0 ? { conflicts: converged.value.conflicts } : {}),
             ...(converged.value.warnings.length > 0 ? { warnings: converged.value.warnings } : {}),