@porulle/plugin-channel-connector 0.48.1 → 0.50.0

package/dist/index.d.ts

@@ -1,8 +1,9 @@
 import { type ChannelConnectorPluginOptions } from "./service.js";
 export { mockChannelConnector } from "./mock-connector.js";
 export type { MockChannelConnectorOptions } from "./mock-connector.js";
-export { ChannelConnectorService, 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 { 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";
+export type { CatalogDeferredMedia, CatalogMediaFailure, CatalogMediaFailureReason, CatalogPageConvergence, ImportImageSelection, } from "./service.js";
 export type { CatalogFieldMapping, CatalogFieldMappingInput, CatalogFieldMappingRow, CatalogFieldTarget, } from "./catalog-field-mapping.js";
 /** ~320 Neon HTTP subrequests per product against a 10,000 per-invocation cap → hard ceiling near 31; 20 leaves margin for heavier products. */
 export declare const CHANNEL_IMPORT_MAX_ITEMS_PER_INVOCATION = 20;

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 { mockChannelConnector } from "./mock-connector.js";
-export { ChannelConnectorService, 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 { 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";
 /** ~320 Neon HTTP subrequests per product against a 10,000 per-invocation cap → hard ceiling near 31; 20 leaves margin for heavier products. */
 export const CHANNEL_IMPORT_MAX_ITEMS_PER_INVOCATION = 20;

package/dist/service.d.ts

@@ -1,4 +1,5 @@
-import type { Actor, ChannelConnector, ChannelOrderSlice, ChannelPushCatalogField, ChannelPushCatalogImage, ChannelPushCatalogItem, ChannelPushCatalogItemOutcome, ChannelPushCatalogResult, PluginDb, PluginResult, PluginTxFn } from "@porulle/core";
+import type { Actor, ChannelCatalogItem, ChannelConnector, ChannelOrderSlice, ChannelPushCatalogField, ChannelPushCatalogImage, ChannelPushCatalogItem, ChannelPushCatalogItemOutcome, ChannelPushCatalogResult, PluginDb, PluginResult, PluginTxFn } from "@porulle/core";
+import type { ChannelCatalogImage } from "@porulle/core";
 import type { FieldOwner, FieldPath } from "@porulle/core";
 import type { JobsAdapter } from "@porulle/core";
 import { type ChannelCatalogPush, type ChannelCatalogConflict, type ChannelOrderExport, type ChannelRefundRequest, type ConnectedStore } from "./schema.js";
@@ -230,7 +231,61 @@ 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
+ * uploaded by mistake must not buffer into a 128 MiB isolate. Anything larger is reported, not
+ * stored, and the product still lands — the index reads text first and media later.
+ */
+export declare const HERO_IMAGE_BYTE_CAP: number;
+export type CatalogMediaFailureReason = "too-large" | "download-failed" | "unsupported" | "storage";
+export interface CatalogMediaFailure {
+    externalId: string;
+    imageExternalId?: string;
+    url: string;
+    reason: CatalogMediaFailureReason;
+    detail: string;
+}
+/** Media the page did NOT fetch: the first photo of each variant the hero does not show. */
+export interface CatalogDeferredMedia {
+    externalId: string;
+    entityId: string;
+    images: ChannelCatalogImage[];
+}
+export interface CatalogPageConvergence extends Record<string, unknown> {
+    created: number;
+    unchanged: number;
+    updated: number;
+    /** Input order, failures excluded, no duplicates — the page message is rebuilt from this. */
+    entityIds: string[];
+    failures: CatalogConvergenceFailure[];
+    heroesImported: number;
+    mediaFailures: CatalogMediaFailure[];
+    deferredMedia: CatalogDeferredMedia[];
+    warnings: string[];
+}
+export interface ImportImageSelection {
+    hero: ChannelCatalogImage | null;
+    /** In variant order; one image per variant the hero does not cover; no url twice. */
+    perVariant: ChannelCatalogImage[];
+}
+/**
+ * Ruling 2026-09-22: import the hero plus the FIRST photo of each other variant, nothing more.
+ * A "blue long dress" query must be able to show the blue variant, and a fourth photo of the red
+ * one adds nothing the index can use. Variants are read off the images' own variant references,
+ * so a connector that lists images against variants it does not enumerate still gets one each.
+ */
+export declare function selectImportImages(item: ChannelCatalogItem): ImportImageSelection;
 export declare class ChannelConnectorService {
     private readonly db;
     private readonly services;
@@ -256,9 +311,48 @@ export declare class ChannelConnectorService {
     private setCatalogAttributesIfWritable;
     private upsertOptionAxes;
     private upsertVariants;
+    /**
+     * The organization's categories, brands and tags, read ONCE per converge run instead of once per
+     * product.
+     *
+     * `applyTaxonomy` takes an `entityId` and is called unconditionally for every item, and each of
+     * its three lookups was a whole-table read filtered by `organization_id`. Measured on the deployed
+     * Worker: 1.0 call per product per class, three classes, every product — an organization's whole
+     * category list re-read for each of twenty products in a batch that cannot have changed it.
+     *
+     * Rows created DURING the run are appended by the callers below, exactly as they were appended to
+     * the per-product arrays before, so an item that introduces a category is still seen by the next
+     * item. The cache is cleared at the top of `convergeCatalogItems`, so its lifetime is one converge
+     * rather than the lifetime of the service.
+     *
+     * The staleness window widens from one product to one batch: a category created by ANOTHER process
+     * mid-batch is not seen here. That was already true within a product — these lists were always a
+     * snapshot — and the create paths below go through `this.catalog`, which refuses a duplicate slug
+     * rather than writing one. So the failure mode is unchanged in kind and wider in window, which is
+     * the trade this comment exists to state rather than hide.
+     */
+    private taxonomyCache;
+    private taxonomyFor;
     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;
@@ -281,6 +375,27 @@ export declare class ChannelConnectorService {
     getStore(orgId: string, id: string): Promise<PluginResult<PublicConnectedStore>>;
     listStores(orgId: string, context?: StoreReadContext): Promise<PluginResult<PublicConnectedStore[]>>;
     validateLineStock(orgId: string, lines: ChannelStockLine[], timeoutMs?: number): Promise<void>;
+    /**
+     * One page from the connector, nothing written. The host lands the page durably (R2 + its
+     * ledger) and hands it to `convergeCatalogPage` from a queue consumer; the two halves are
+     * separate so a consumer retry never re-fetches the merchant's API.
+     */
+    fetchCatalogPage(orgId: string, storeId: string, cursor: string | null): Promise<PluginResult<{
+        items: ChannelCatalogItem[];
+        nextCursor: string | null;
+    }>>;
+    /**
+     * Converges a page: items this store has never mapped take the import fast path
+     * (`catalog.importProducts`, one transaction, multi-row writes); items already mapped and
+     * unchanged cost nothing; items mapped-but-changed, and orphans (an entity of this store with
+     * the item's slug but no map row), take the editor path, which owns ownership and conflicts.
+     *
+     * Media: only each new item's hero is fetched here, streamed under `HERO_IMAGE_BYTE_CAP`, and
+     * 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>>;
+    private importHeroes;
     importCatalog(orgId: string, storeId: string, actor: Actor, options: {
         maxItems: number;
     }): Promise<PluginResult<{