@porulle/plugin-channel-connector 0.10.8 → 0.13.0

package/dist/schema.js

@@ -1,4 +1,4 @@
-import { index, integer, jsonb, pgTable, text, timestamp, uniqueIndex, uuid, } from "@porulle/core/drizzle";
+import { boolean, index, integer, jsonb, pgTable, text, timestamp, uniqueIndex, uuid, sql, } from "@porulle/core/drizzle";
 export const connectedStores = pgTable("connected_stores", {
     id: uuid("id").defaultRandom().primaryKey(),
     organizationId: text("organization_id").notNull(),
@@ -8,6 +8,8 @@ export const connectedStores = pgTable("connected_stores", {
     status: text("status", { enum: ["connected", "disconnected", "error"] })
         .notNull()
         .default("connected"),
+    catalogWriteEnabled: boolean("catalog_write_enabled").notNull().default(false),
+    catalogFieldMapping: jsonb("catalog_field_mapping").$type().notNull().default([]),
     catalogCursor: text("catalog_cursor"),
     inventoryCursor: text("inventory_cursor"),
     lastSyncAt: timestamp("last_sync_at", { withTimezone: true }),
@@ -31,11 +33,48 @@ export const channelEntityMap = pgTable("channel_entity_map", {
     variantId: uuid("variant_id"),
     lastSyncedAt: timestamp("last_synced_at", { withTimezone: true }).defaultNow().notNull(),
     syncHash: text("sync_hash").notNull(),
+    outboundHash: text("outbound_hash"),
+    outboundPushedAt: timestamp("outbound_pushed_at", { withTimezone: true }),
+    outboundFieldPaths: jsonb("outbound_field_paths").$type().notNull().default([]),
+    heldFieldPaths: jsonb("held_field_paths").$type().notNull().default([]),
+    forcedPushFieldPaths: jsonb("forced_push_field_paths").$type().notNull().default([]),
 }, (table) => ({
     orgIdx: index("idx_channel_entity_map_org").on(table.organizationId),
     storeIdx: index("idx_channel_entity_map_store").on(table.storeId),
     externalUnique: uniqueIndex("channel_entity_map_store_kind_external_unique").on(table.storeId, table.kind, table.externalId),
 }));
+export const channelCatalogConflicts = pgTable("channel_catalog_conflicts", {
+    id: uuid("id").defaultRandom().primaryKey(),
+    organizationId: text("organization_id").notNull(),
+    storeId: uuid("store_id").references(() => connectedStores.id, { onDelete: "cascade" }).notNull(),
+    entityId: uuid("entity_id").notNull(),
+    fieldPath: text("field_path").notNull(),
+    platformValue: jsonb("platform_value").$type().notNull(),
+    storeValue: jsonb("store_value").$type().notNull(),
+    state: text("state", { enum: ["open", "resolved"] }).notNull().default("open"),
+    resolvedBy: text("resolved_by"),
+    createdAt: timestamp("created_at", { withTimezone: true }).defaultNow().notNull(),
+    updatedAt: timestamp("updated_at", { withTimezone: true }).defaultNow().notNull(),
+}, (table) => ({
+    orgIdx: index("idx_channel_catalog_conflicts_org").on(table.organizationId),
+    stateIdx: index("idx_channel_catalog_conflicts_org_state").on(table.organizationId, table.state),
+    openUnique: uniqueIndex("channel_catalog_conflicts_open_unique")
+        .on(table.storeId, table.entityId, table.fieldPath)
+        .where(sql `${table.state} = 'open'`),
+}));
+export const channelCatalogConflictEvents = pgTable("channel_catalog_conflict_events", {
+    id: uuid("id").defaultRandom().primaryKey(),
+    organizationId: text("organization_id").notNull(),
+    conflictId: uuid("conflict_id").references(() => channelCatalogConflicts.id, { onDelete: "cascade" }).notNull(),
+    fromState: text("from_state"),
+    toState: text("to_state").notNull(),
+    reason: text("reason"),
+    changedBy: text("changed_by").notNull(),
+    changedAt: timestamp("changed_at", { withTimezone: true }).defaultNow().notNull(),
+}, (table) => ({
+    orgIdx: index("idx_channel_catalog_conflict_events_org").on(table.organizationId),
+    conflictIdx: index("idx_channel_catalog_conflict_events_conflict").on(table.conflictId),
+}));
 export const channelOrderExports = pgTable("channel_order_exports", {
     id: uuid("id").defaultRandom().primaryKey(),
     organizationId: text("organization_id").notNull(),
@@ -58,6 +97,42 @@ export const channelOrderExports = pgTable("channel_order_exports", {
     stateIdx: index("idx_channel_order_exports_state").on(table.organizationId, table.state),
     orderIdx: index("idx_channel_order_exports_order").on(table.organizationId, table.orderId),
 }));
+export const channelCatalogPushes = pgTable("channel_catalog_pushes", {
+    id: uuid("id").defaultRandom().primaryKey(),
+    organizationId: text("organization_id").notNull(),
+    storeId: uuid("store_id").references(() => connectedStores.id, { onDelete: "cascade" }).notNull(),
+    entityId: uuid("entity_id").notNull(),
+    payloadSnapshot: jsonb("payload_snapshot").$type(),
+    state: text("state", { enum: ["pending", "exported", "confirmed", "failed", "abandoned"] })
+        .notNull()
+        .default("pending"),
+    failureKind: text("failure_kind", { enum: ["definitive", "transient"] }),
+    attempts: integer("attempts").notNull().default(0),
+    lastError: text("last_error"),
+    createdAt: timestamp("created_at", { withTimezone: true }).defaultNow().notNull(),
+    updatedAt: timestamp("updated_at", { withTimezone: true }).defaultNow().notNull(),
+}, (table) => ({
+    orgIdx: index("idx_channel_catalog_pushes_org").on(table.organizationId),
+    storeIdx: index("idx_channel_catalog_pushes_store").on(table.storeId),
+    stateIdx: index("idx_channel_catalog_pushes_state").on(table.organizationId, table.state),
+    entityIdx: index("idx_channel_catalog_pushes_entity").on(table.organizationId, table.entityId),
+    storeEntityUnique: uniqueIndex("channel_catalog_pushes_store_entity_unique").on(table.storeId, table.entityId),
+}));
+export const channelCatalogPushEvents = pgTable("channel_catalog_push_events", {
+    id: uuid("id").defaultRandom().primaryKey(),
+    organizationId: text("organization_id").notNull(),
+    pushId: uuid("push_id")
+        .references(() => channelCatalogPushes.id, { onDelete: "cascade" })
+        .notNull(),
+    fromState: text("from_state").notNull(),
+    toState: text("to_state").notNull(),
+    reason: text("reason"),
+    changedBy: text("changed_by").notNull(),
+    changedAt: timestamp("changed_at", { withTimezone: true }).defaultNow().notNull(),
+}, (table) => ({
+    orgIdx: index("idx_channel_catalog_push_events_org").on(table.organizationId),
+    pushIdx: index("idx_channel_catalog_push_events_push").on(table.pushId),
+}));
 export const channelExportEvents = pgTable("channel_export_events", {
     id: uuid("id").defaultRandom().primaryKey(),
     organizationId: text("organization_id").notNull(),

package/dist/service.d.ts

@@ -1,18 +1,66 @@
-import type { Actor, ChannelConnector, ChannelOrderSlice, PluginDb, PluginResult, PluginTxFn } from "@porulle/core";
+import type { Actor, ChannelConnector, ChannelOrderSlice, ChannelPushCatalogField, ChannelPushCatalogImage, ChannelPushCatalogItem, ChannelPushCatalogItemOutcome, ChannelPushCatalogResult, PluginDb, PluginResult, PluginTxFn } from "@porulle/core";
+import type { FieldOwner, FieldPath } from "@porulle/core";
 import type { JobsAdapter } from "@porulle/core";
-import { type ChannelOrderExport, type ChannelRefundRequest, type ConnectedStore } from "./schema.js";
+import { type ChannelCatalogPush, type ChannelCatalogConflict, type ChannelOrderExport, type ChannelRefundRequest, type ConnectedStore } from "./schema.js";
+import { type CatalogFieldMapping, type CatalogFieldTarget } from "./catalog-field-mapping.js";
 export type ExportState = ChannelOrderExport["state"];
+export type CatalogPushState = ChannelCatalogPush["state"];
+export type CatalogConflictState = ChannelCatalogConflict["state"];
+export declare const CATALOG_PUSH_BATCH_SIZES: Record<string, number>;
+export declare const CATALOG_PUSH_MAX_ATTEMPTS = 8;
+export declare function catalogPushRetryDelayMs(attempts: number): number;
+export interface CatalogPushJobResult extends Record<string, unknown> {
+    noop?: boolean;
+    rescheduled?: boolean;
+    complete?: boolean;
+    cursor?: string;
+    pushed?: number;
+    failed?: number;
+}
+export declare function catalogPushConcurrencyKey(input: Record<string, unknown>): string;
+export declare function isCatalogPushBreakerOpen(breakerState: Record<string, unknown>): boolean;
 export interface ReconcileReport extends Record<string, unknown> {
     imported: number;
     converged: number;
     archived: number;
     inventoryUpdated: number;
+    openConflicts: number;
     driftAlert: boolean;
+    skipped?: CatalogFieldSkip[];
+    conflicts?: CatalogFieldConflict[];
+    warnings?: string[];
+}
+export interface CatalogFieldConflict {
+    entityId: string;
+    storeId: string;
+    fieldPath: FieldPath;
+    localValueSummary: string;
+    remoteValueSummary: string;
+}
+export interface CatalogFieldSkip {
+    entityId: string;
+    fieldPath: FieldPath;
+}
+export type CatalogPushSkipReason = "no_mapping" | "held" | "store_owned" | "entity_not_active" | "unmapped_entity";
+export interface CatalogPushFieldSkip {
+    entityId: string;
+    fieldPath: FieldPath;
+    reason: CatalogPushSkipReason;
+    value?: unknown;
+    owner?: FieldOwner;
+    target?: CatalogFieldTarget;
+    remoteKey?: string;
 }
 export type PublicConnectedStore = Omit<ConnectedStore, "credentials" | "webhookSecret"> & {
     credentials: "[REDACTED]";
     webhookSecret: "[REDACTED]";
 };
+export interface CatalogWriteSettings {
+    enabled: boolean;
+    overrides: CatalogFieldMapping;
+    merged: CatalogFieldMapping;
+    warnings?: string[];
+}
 export interface ChannelComplianceData {
     customer: {
         id?: string;
@@ -47,7 +95,77 @@ export interface ChannelStockLine {
     title?: string;
     quantity: number;
 }
+interface BackfillCounts {
+    entitiesTouched: number;
+    attributesCreated: number;
+    mediaImported: number;
+    variantsGivenOptionValues: number;
+}
+export interface BackfillCatalogReport extends BackfillCounts, Record<string, unknown> {
+    cursor: string | null;
+    complete: boolean;
+    skipped?: CatalogFieldSkip[];
+    conflicts?: CatalogFieldConflict[];
+    warnings?: string[];
+}
+export interface BackfillCatalogOptions {
+    dryRun?: boolean;
+    resume?: boolean;
+    maxPages?: number;
+}
+export interface BuildCatalogPushItemsOptions {
+    recordRevision?: boolean;
+    forceFieldPaths?: Record<string, FieldPath[]>;
+}
+export interface CatalogPushAssemblyField extends ChannelPushCatalogField {
+    target: CatalogFieldTarget;
+}
+export interface CatalogPushAssemblyImage extends ChannelPushCatalogImage {
+    fieldPath: FieldPath;
+    target: CatalogFieldTarget;
+    remoteKey: string;
+}
+export interface CatalogPushAssemblyItem extends Omit<ChannelPushCatalogItem, "fields" | "images"> {
+    fields: CatalogPushAssemblyField[];
+    images?: CatalogPushAssemblyImage[];
+}
+export interface BuildCatalogPushItemsResult {
+    items: CatalogPushAssemblyItem[];
+    skipped: CatalogPushFieldSkip[];
+    warnings: string[];
+}
+export interface PushCatalogToStoreResult extends ChannelPushCatalogResult {
+    skipped: CatalogPushFieldSkip[];
+    warnings: string[];
+}
+export interface CatalogPushPreviewUnavailable {
+    status: "unavailable";
+}
+export type CatalogPushPreviewBefore = unknown | CatalogPushPreviewUnavailable;
+export type CatalogPushPreviewBeforeStatus = "value" | "missing" | "unavailable";
+export interface CatalogPushPreviewDiff {
+    fieldPath: FieldPath;
+    target: CatalogFieldTarget | null;
+    remoteKey: string | null;
+    before: CatalogPushPreviewBefore;
+    beforeStatus: CatalogPushPreviewBeforeStatus;
+    after: unknown;
+    owner: FieldOwner;
+    willWrite: boolean;
+    reason?: CatalogPushSkipReason;
+}
+export interface CatalogPushPreviewItem {
+    externalId: string;
+    diffs: CatalogPushPreviewDiff[];
+}
+export interface CatalogPushPreviewResult {
+    items: CatalogPushPreviewItem[];
+    skipped: CatalogPushFieldSkip[];
+    warnings: string[];
+}
 export declare function canExportTransition(from: ExportState, to: ExportState): boolean;
+export declare function canCatalogPushTransition(from: CatalogPushState, to: CatalogPushState): boolean;
+export declare const CATALOG_OUTBOUND_SUPPRESSION_WINDOW_MS: number;
 export declare class ChannelConnectorService {
     private readonly db;
     private readonly services;
@@ -58,9 +176,34 @@ export declare class ChannelConnectorService {
     constructor(db: PluginDb, services: Record<string, unknown>, options?: ChannelConnectorPluginOptions, transaction?: PluginTxFn);
     getConnector(providerId: string): ChannelConnector | undefined;
     private get catalog();
+    private get media();
+    private get pricing();
+    private filterOwnedFields;
+    private filterOwnedFieldsAtPaths;
+    private filterConflictingFields;
+    private remoteFieldValue;
+    private isOutboundEcho;
+    private localFieldValue;
+    private lastSyncedSnapshot;
+    private detectSharedConflicts;
+    private persistCatalogConflicts;
+    private setCatalogAttributes;
+    private setCatalogAttributesIfWritable;
+    private upsertOptionAxes;
+    private upsertVariants;
+    private applyTaxonomy;
+    private applyMedia;
     private getStoreRecord;
     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;
+    buildCatalogPushItems(orgId: string, storeId: string, entityIds: string[], options?: BuildCatalogPushItemsOptions): Promise<PluginResult<BuildCatalogPushItemsResult>>;
+    recordOutboundPush(orgId: string, storeId: string, outcomes: ChannelPushCatalogItemOutcome[], items: ChannelPushCatalogItem[], phase?: "write-ahead" | "settle"): Promise<PluginResult<void>>;
+    pushCatalogToStore(orgId: string, storeId: string, entityIds: string[]): Promise<PluginResult<PushCatalogToStoreResult>>;
+    previewCatalogPush(orgId: string, storeId: string, entityIds?: string[]): Promise<PluginResult<CatalogPushPreviewResult>>;
+    getCatalogWriteSettings(orgId: string, storeId: string): Promise<PluginResult<CatalogWriteSettings>>;
+    updateCatalogWriteEnabled(orgId: string, storeId: string, enabled: boolean): Promise<PluginResult<CatalogWriteSettings>>;
+    updateCatalogFieldMapping(orgId: string, storeId: string, mapping: unknown): Promise<PluginResult<CatalogWriteSettings>>;
     connectStore(orgId: string, input: {
         provider: string;
         credentials: Record<string, unknown>;
@@ -76,7 +219,14 @@ export declare class ChannelConnectorService {
     importCatalog(orgId: string, storeId: string, actor: Actor): Promise<PluginResult<{
         imported: number;
         cursor: string | null;
+        skipped?: CatalogFieldSkip[];
+        conflicts?: CatalogFieldConflict[];
+        warnings?: string[];
     }>>;
+    private promoteLegacyAttributes;
+    private saveBackfillState;
+    backfillCatalog(orgId: string, storeId: string, actor: Actor, options?: BackfillCatalogOptions): Promise<PluginResult<BackfillCatalogReport>>;
+    private estimateCatalogItems;
     private convergeCatalogItems;
     reconcile(orgId: string, storeId: string, actor: Actor): Promise<PluginResult<ReconcileReport>>;
     getReconcileStatus(orgId: string, storeId: string): Promise<PluginResult<{
@@ -84,6 +234,9 @@ export declare class ChannelConnectorService {
         report: ReconcileReport | null;
         driftAlert: boolean;
     }>>;
+    listCatalogConflicts(orgId: string, storeId?: string, state?: ChannelCatalogConflict["state"]): Promise<PluginResult<ChannelCatalogConflict[]>>;
+    resolveCatalogConflict(orgId: string, id: string, choose: "platform" | "store", actor: Pick<Actor, "userId">): Promise<PluginResult<ChannelCatalogConflict>>;
+    private applyStoreConflictValue;
     syncInventory(orgId: string, storeId: string, actor: Actor): Promise<PluginResult<{
         synced: number;
     }>>;
@@ -129,4 +282,16 @@ export declare class ChannelConnectorService {
     listFailedExports(orgId: string): Promise<PluginResult<ChannelOrderExport[]>>;
     retryExport(orgId: string, exportId: string, changedBy: string): Promise<PluginResult<ChannelOrderExport>>;
     abandonExport(orgId: string, exportId: string, changedBy: string, reason?: string): Promise<PluginResult<ChannelOrderExport>>;
+    resolveCatalogPushEntityIds(orgId: string, storeId: string, entityIds?: string[]): Promise<string[]>;
+    createCatalogPush(orgId: string, storeId: string, entityId: string): Promise<PluginResult<ChannelCatalogPush>>;
+    transitionCatalogPush(orgId: string, pushId: string, toState: CatalogPushState, changedBy: string, reason?: string, failureKind?: "definitive" | "transient", payloadSnapshot?: ChannelPushCatalogItem | null): Promise<PluginResult<ChannelCatalogPush>>;
+    private recordCatalogPushRevisions;
+    executeCatalogPushJob(orgId: string, storeId: string, options: {
+        entityIds?: string[];
+        cursor?: string;
+        forceFieldPaths?: Record<string, FieldPath[]>;
+    }, actor: Actor, runtime: {
+        jobs: JobsAdapter;
+    }): Promise<PluginResult<CatalogPushJobResult>>;
 }
+export {};