@porulle/plugin-channel-connector 0.11.0 → 0.14.0

package/dist/schema.js

@@ -1,4 +1,4 @@
-import { boolean, 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(),
@@ -33,12 +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(),
@@ -61,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,14 +1,30 @@
-import type { Actor, ChannelConnector, ChannelOrderSlice, ChannelPushCatalogItem, PluginDb, PluginResult, PluginTxFn } from "@porulle/core";
-import type { FieldPath } 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 CatalogFieldMapping } from "./catalog-field-mapping.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[];
@@ -25,11 +41,15 @@ export interface CatalogFieldSkip {
     entityId: string;
     fieldPath: FieldPath;
 }
-export type CatalogPushSkipReason = "no_mapping" | "held" | "entity_not_active" | "unmapped_entity";
+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]";
@@ -95,13 +115,57 @@ export interface BackfillCatalogOptions {
 }
 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: ChannelPushCatalogItem[];
+    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;
@@ -118,9 +182,13 @@ export declare class ChannelConnectorService {
     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;
@@ -130,6 +198,9 @@ export declare class ChannelConnectorService {
     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>>;
@@ -163,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;
     }>>;
@@ -208,5 +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 {};