@porulle/plugin-channel-connector 0.10.8 → 0.11.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@porulle/plugin-channel-connector",
-  "version": "0.10.8",
+  "version": "0.11.0",
   "license": "MIT",
   "type": "module",
   "exports": {
@@ -19,7 +19,7 @@
   "dependencies": {
     "@hono/zod-openapi": "^1.2.2",
     "hono": "^4.12.5",
-    "@porulle/core": "0.10.8"
+    "@porulle/core": "0.11.0"
   },
   "devDependencies": {
     "@types/node": "^24.5.2",

package/src/catalog-field-mapping.ts

@@ -0,0 +1,211 @@
+import type { FieldPath } from "@porulle/core";
+
+export const catalogFieldTargets = ["native", "attribute", "meta"] as const;
+export type CatalogFieldTarget = (typeof catalogFieldTargets)[number];
+
+export interface CatalogFieldMappingRow {
+  fieldPath: FieldPath;
+  provider: string;
+  target: CatalogFieldTarget;
+  remoteKey: string;
+}
+
+export type CatalogFieldMapping = CatalogFieldMappingRow[];
+
+export type CatalogFieldMappingInput =
+  | Array<{ fieldPath: string; provider?: string; target: CatalogFieldTarget; remoteKey: string }>
+  | Record<string, { provider?: string; target: CatalogFieldTarget; remoteKey: string }>;
+
+const fieldSegment = /^[A-Za-z0-9_-]+$/;
+const forbiddenFieldPaths = ["variants.sku", "variants.barcode", "options", "prices", "entity.status"];
+
+export const providerCatalogFieldMappingDefaults: Record<string, CatalogFieldMapping> = {
+  shopify: [
+    { fieldPath: "attributes.*.title", provider: "shopify", target: "native", remoteKey: "title" },
+    { fieldPath: "attributes.*.description", provider: "shopify", target: "native", remoteKey: "body_html" },
+    { fieldPath: "attributes.*.seoTitle", provider: "shopify", target: "meta", remoteKey: "seo_title" },
+    { fieldPath: "attributes.*.seoDescription", provider: "shopify", target: "meta", remoteKey: "seo_description" },
+    { fieldPath: "customFields.*.*", provider: "shopify", target: "meta", remoteKey: "metafields" },
+    { fieldPath: "media.*", provider: "shopify", target: "native", remoteKey: "images" },
+    { fieldPath: "entity.metadata.*", provider: "shopify", target: "meta", remoteKey: "metafields" },
+  ],
+  woocommerce: [
+    { fieldPath: "attributes.*.title", provider: "woocommerce", target: "native", remoteKey: "name" },
+    { fieldPath: "attributes.*.description", provider: "woocommerce", target: "native", remoteKey: "description" },
+    { fieldPath: "attributes.*.seoTitle", provider: "woocommerce", target: "meta", remoteKey: "yoast_wpseo_title" },
+    { fieldPath: "attributes.*.seoDescription", provider: "woocommerce", target: "meta", remoteKey: "yoast_wpseo_metadesc" },
+    { fieldPath: "customFields.*.*", provider: "woocommerce", target: "meta", remoteKey: "porulle_meta_data" },
+    { fieldPath: "media.*", provider: "woocommerce", target: "native", remoteKey: "images" },
+    { fieldPath: "entity.metadata.*", provider: "woocommerce", target: "meta", remoteKey: "porulle_meta_data" },
+  ],
+};
+
+export function matchFieldPath(pattern: string, path: string): boolean {
+  const patternSegments = pattern.split(".");
+  const pathSegments = path.split(".");
+  return patternSegments.length === pathSegments.length
+    && patternSegments.every((segment, index) => pathSegments[index] !== "" && (segment === "*" || segment === pathSegments[index]));
+}
+
+export function isValidCatalogMappingFieldPath(value: string): boolean {
+  const segments = value.split(".");
+  return segments.length > 0 && segments.every((segment) => segment === "*" || fieldSegment.test(segment));
+}
+
+function couldCoverForbiddenSubtree(fieldPath: string, root: string): boolean {
+  const fieldSegments = fieldPath.split(".");
+  const rootSegments = root.split(".");
+  return fieldSegments.length >= rootSegments.length
+    && rootSegments.every((segment, index) => fieldSegments[index] === "*" || fieldSegments[index] === segment);
+}
+
+function isForbiddenMappingFieldPath(fieldPath: string): boolean {
+  return forbiddenFieldPaths.some((root) => couldCoverForbiddenSubtree(fieldPath, root));
+}
+
+export function validateCatalogMappingRow(
+  input: Partial<CatalogFieldMappingRow> & { fieldPath: string; target: CatalogFieldTarget; remoteKey: string },
+  provider: string,
+): CatalogFieldMappingRow {
+  if (!isValidCatalogMappingFieldPath(input.fieldPath)) {
+    throw new Error("Catalog mapping field paths must contain dot-separated alphanumeric, underscore, hyphen, or wildcard segments.");
+  }
+  if (isForbiddenMappingFieldPath(input.fieldPath)) {
+    throw new Error(`Catalog mapping cannot write the forbidden field path "${input.fieldPath}".`);
+  }
+  if (!catalogFieldTargets.includes(input.target)) {
+    throw new Error(`Catalog mapping target "${input.target}" is invalid.`);
+  }
+  const remoteKey = input.remoteKey.trim();
+  if (remoteKey.length === 0) {
+    throw new Error("Catalog mapping remoteKey must not be empty.");
+  }
+  const rowProvider = input.provider ?? provider;
+  if (rowProvider !== provider) {
+    throw new Error(`Catalog mapping provider must be "${provider}" for this store.`);
+  }
+  if (rowProvider === "woocommerce" && input.target === "meta" && remoteKey.startsWith("_")) {
+    throw new Error("WooCommerce meta keys must not start with an underscore.");
+  }
+  return {
+    fieldPath: input.fieldPath,
+    provider: rowProvider,
+    target: input.target,
+    remoteKey,
+  };
+}
+
+function mappingEntries(input: unknown): unknown[] {
+  if (Array.isArray(input)) return input;
+  if (!input || typeof input !== "object") throw new Error("Catalog mapping must be an array or an object.");
+  return Object.entries(input).map(([fieldPath, value]) => {
+    if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("Catalog mapping values must be objects.");
+    return { ...(value as Record<string, unknown>), fieldPath };
+  });
+}
+
+function normalizeCatalogMappingRow(row: unknown, provider: string): CatalogFieldMappingRow {
+  if (!row || typeof row !== "object" || Array.isArray(row)) throw new Error("Catalog mapping rows must be objects.");
+  const value = row as Record<string, unknown>;
+  if (typeof value.fieldPath !== "string" || typeof value.target !== "string" || typeof value.remoteKey !== "string") {
+    throw new Error("Catalog mapping rows require fieldPath, target, and remoteKey.");
+  }
+  return validateCatalogMappingRow(
+    {
+      fieldPath: value.fieldPath,
+      ...(typeof value.provider === "string" ? { provider: value.provider } : {}),
+      target: value.target as CatalogFieldTarget,
+      remoteKey: value.remoteKey,
+    },
+    provider,
+  );
+}
+
+export function normalizeCatalogFieldMapping(input: unknown, provider: string): CatalogFieldMapping {
+  return mappingEntries(input).map((row) => normalizeCatalogMappingRow(row, provider));
+}
+
+function normalizeStoredCatalogFieldMapping(input: unknown, provider: string, warnings: string[]): CatalogFieldMapping {
+  let entries: unknown[];
+  try {
+    entries = mappingEntries(input ?? []);
+  } catch (error) {
+    warnings.push(error instanceof Error ? error.message : "Stored catalog mapping is invalid.");
+    return [];
+  }
+  return entries.flatMap((row, index) => {
+    try {
+      return [normalizeCatalogMappingRow(row, provider)];
+    } catch (error) {
+      const message = error instanceof Error ? error.message : "Stored catalog mapping row is invalid.";
+      warnings.push(`Skipped catalog mapping row ${index}: ${message}`);
+      return [];
+    }
+  });
+}
+
+function filterableEntries(hint: ReadonlySet<string> | Readonly<Record<string, boolean>>): Array<[string, boolean]> {
+  if (hint instanceof Set) return [...hint].map((path) => [path, true]);
+  return Object.entries(hint);
+}
+
+export function mergeCatalogFieldMapping(
+  provider: string,
+  overrides: unknown,
+  filterableCustomFields?: ReadonlySet<string> | Readonly<Record<string, boolean>>,
+  warnings: string[] = [],
+): CatalogFieldMapping {
+  const defaults = (providerCatalogFieldMappingDefaults[provider] ?? []).map((row) => ({ ...row }));
+  const rows = normalizeStoredCatalogFieldMapping(overrides, provider, warnings);
+  const merged = [...defaults];
+  for (const row of rows) {
+    const index = merged.findIndex((defaultRow) => defaultRow.fieldPath === row.fieldPath && defaultRow.provider === row.provider);
+    if (index === -1) merged.push(row);
+    else merged[index] = row;
+  }
+  if (!filterableCustomFields) return merged;
+  const hints = filterableEntries(filterableCustomFields).filter(([path]) => isValidCatalogMappingFieldPath(path));
+  if (hints.length === 0) return merged;
+  const customFieldPattern = "customFields.*.*";
+  const customFieldDefault = merged.find((row) => row.fieldPath === customFieldPattern);
+  if (!customFieldDefault) return merged;
+  const expanded = hints
+    .filter(([path]) => matchFieldPath(customFieldPattern, path))
+    .map(([fieldPath, filterable]) => ({
+      ...customFieldDefault,
+      fieldPath,
+      target: filterable ? "attribute" as const : "meta" as const,
+      remoteKey: fieldPath.split(".")[1] ?? customFieldDefault.remoteKey,
+    }));
+  return [...merged.filter((row) => row.fieldPath !== customFieldPattern), ...expanded];
+}
+
+function wildcardCount(fieldPath: string): number {
+  return fieldPath.split(".").filter((segment) => segment === "*").length;
+}
+
+function compareStrings(left: string, right: string): number {
+  if (left < right) return -1;
+  if (left > right) return 1;
+  return 0;
+}
+
+export function compareCatalogFieldMappingSpecificity(
+  left: CatalogFieldMappingRow,
+  right: CatalogFieldMappingRow,
+): number {
+  const wildcardDifference = wildcardCount(left.fieldPath) - wildcardCount(right.fieldPath);
+  if (wildcardDifference !== 0) return wildcardDifference;
+  const fieldPathDifference = compareStrings(left.fieldPath, right.fieldPath);
+  if (fieldPathDifference !== 0) return fieldPathDifference;
+  const providerDifference = compareStrings(left.provider, right.provider);
+  if (providerDifference !== 0) return providerDifference;
+  return compareStrings(left.remoteKey, right.remoteKey);
+}
+
+export function selectCatalogFieldMapping(
+  mapping: CatalogFieldMapping,
+  path: string,
+): CatalogFieldMappingRow | undefined {
+  return mapping.filter((row) => matchFieldPath(row.fieldPath, path)).sort(compareCatalogFieldMappingSpecificity)[0];
+}

package/src/index.ts

@@ -41,8 +41,33 @@ export {
   ChannelConnectorService,
   canExportTransition,
 } from "./service.js";
+export {
+  isValidCatalogMappingFieldPath,
+  matchFieldPath,
+  mergeCatalogFieldMapping,
+  normalizeCatalogFieldMapping,
+  compareCatalogFieldMappingSpecificity,
+  providerCatalogFieldMappingDefaults,
+  selectCatalogFieldMapping,
+  validateCatalogMappingRow,
+} from "./catalog-field-mapping.js";
+export type {
+  CatalogFieldMapping,
+  CatalogFieldMappingInput,
+  CatalogFieldMappingRow,
+  CatalogFieldTarget,
+} from "./catalog-field-mapping.js";
 export { signState, verifyState } from "./oauth-state.js";
 export type {
+  BackfillCatalogOptions,
+  BackfillCatalogReport,
+  BuildCatalogPushItemsOptions,
+  BuildCatalogPushItemsResult,
+  CatalogFieldConflict,
+  CatalogFieldSkip,
+  CatalogPushFieldSkip,
+  CatalogPushSkipReason,
+  CatalogWriteSettings,
   ChannelComplianceData,
   ChannelConnectorPluginOptions,
   ChannelStockLine,
@@ -138,7 +163,38 @@ export function channelConnectorPlugin(options: ChannelConnectorPluginOptions =
         const service = new ChannelConnectorService(ctx.db, ctx.services, options);
         const result = await service.importCatalog(String(input.orgId), String(input.storeId), createSystemActor(String(input.orgId)));
         if (!result.ok) throw new Error(result.error);
-        return { output: { imported: result.value.imported, cursor: result.value.cursor } };
+        return {
+          output: {
+            imported: result.value.imported,
+            cursor: result.value.cursor,
+            ...(result.value.warnings ? { warnings: result.value.warnings } : {}),
+          },
+        };
+      },
+    },
+    {
+      slug: "channel/backfill-catalog",
+      concurrency: { key: (input: Record<string, unknown>) => String(input.storeId) },
+      handler: async ({ input, ctx }: { input: Record<string, unknown>; ctx: import("@porulle/core").TaskContext }) => {
+        const service = new ChannelConnectorService(ctx.db, ctx.services, options);
+        const orgId = String(input.orgId);
+        const storeId = String(input.storeId);
+        const dryRun = input.dryRun === true;
+        const result = await service.backfillCatalog(orgId, storeId, createSystemActor(orgId), {
+          dryRun,
+          ...(input.restart === true ? { resume: false } : {}),
+          ...(!dryRun ? { maxPages: 1 } : {}),
+        });
+        if (!result.ok) throw new Error(result.error);
+        if (!result.value.complete && !dryRun) {
+          const jobs = ctx.services.jobs as JobsAdapter;
+          await jobs.enqueue("channel/backfill-catalog", { orgId, storeId, dryRun }, {
+            organizationId: orgId,
+            concurrencyKey: storeId,
+            supersedes: false,
+          });
+        }
+        return { output: result.value };
       },
     },
     {
@@ -378,11 +434,52 @@ export function channelConnectorPlugin(options: ChannelConnectorPluginOptions =
         .permission("channels:read")
         .handler(async ({ params, orgId }: ChannelRouteContext) => unwrap(await service.getStore(orgId, params.id!)));
 
+      channels.get("/stores/{storeId}/catalog-write")
+        .summary("Get catalog write settings for a channel store")
+        .permission("channels:manage")
+        .handler(async ({ params, orgId }: ChannelRouteContext) => unwrap(await service.getCatalogWriteSettings(orgId, params.storeId!)));
+
+      channels.put("/stores/{storeId}/catalog-write")
+        .summary("Update catalog write settings for a channel store")
+        .permission("channels:manage")
+        .input(z.object({
+          enabled: z.boolean().optional(),
+          overrides: z.unknown().optional(),
+        }).refine((value) => value.enabled !== undefined || value.overrides !== undefined))
+        .handler(async ({ params, orgId, input }: ChannelRouteContext) => {
+          const values = input as { enabled?: boolean; overrides?: unknown };
+          if (values.overrides !== undefined) unwrap(await service.updateCatalogFieldMapping(orgId, params.storeId!, values.overrides));
+          if (values.enabled !== undefined) unwrap(await service.updateCatalogWriteEnabled(orgId, params.storeId!, values.enabled));
+          return unwrap(await service.getCatalogWriteSettings(orgId, params.storeId!));
+        });
+
       channels.get("/stores/{storeId}/reconcile-status")
         .summary("Get channel reconciliation status")
         .permission("channels:read")
         .handler(async ({ params, orgId }: ChannelRouteContext) => unwrap(await service.getReconcileStatus(orgId, params.storeId!)));
 
+      channels.post("/stores/{storeId}/backfill")
+        .summary("Backfill a channel catalog into the PIM")
+        .permission("channels:manage")
+        .input(z.object({ dryRun: z.boolean().optional(), restart: z.boolean().optional() }))
+        .handler(async ({ params, orgId, input }: ChannelRouteContext) => {
+          const values = input as { dryRun?: boolean; restart?: boolean };
+          if (values.dryRun === true) {
+            return unwrap(await service.backfillCatalog(orgId, params.storeId!, createSystemActor(orgId), { dryRun: true }));
+          }
+          const jobs = ctx.services.jobs as JobsAdapter;
+          await jobs.enqueue("channel/backfill-catalog", {
+            orgId,
+            storeId: params.storeId!,
+            ...(values.restart === true ? { restart: true } : {}),
+          }, {
+            organizationId: orgId,
+            concurrencyKey: params.storeId!,
+            supersedes: false,
+          });
+          return { enqueued: true, storeId: params.storeId! };
+        });
+
       channels.post("/stores/{id}/disconnect")
         .summary("Disconnect a channel store")
         .permission("channels:manage")

package/src/mock-connector.ts

@@ -6,8 +6,12 @@ import {
 } from "@porulle/core";
 import type {
   ChannelCatalogItem,
+  ChannelConnectorError,
   ChannelInventoryLevel,
   ChannelOrderSlice,
+  ChannelPushCatalogItem,
+  ChannelPushCatalogPreviousField,
+  ChannelStore,
 } from "@porulle/core";
 
 export interface MockChannelConnectorOptions {
@@ -17,10 +21,64 @@ export interface MockChannelConnectorOptions {
   throwOnInventory?: boolean;
   inventoryDelayMs?: number;
   onFetchInventory?: (ids: string[]) => void;
+  pushCatalogFailures?: Record<string, ChannelConnectorError>;
+  pushCatalogTransportError?: ChannelConnectorError;
+  onPushCatalog?: (items: ChannelPushCatalogItem[]) => void;
 }
 
+const defaultCatalog: ChannelCatalogItem[] = [{
+  externalId: "mock-product-1",
+  slug: "mock-channel-product",
+  title: "Mock Channel Product",
+  description: "Imported through the mock connector.",
+  attributes: [{
+    locale: "en",
+    title: "Mock Channel Product",
+    subtitle: "A complete mock catalog item",
+    description: "Imported through the mock connector.",
+    richDescription: { blocks: [{ type: "paragraph", text: "Mock product details." }] },
+    seoTitle: "Mock Channel Product | Porulle",
+    seoDescription: "A mock product with the complete channel catalog shape.",
+  }],
+  images: [
+    {
+      externalId: "mock-image-primary",
+      url: "https://mock.channel.test/images/mock-product-1-primary.jpg",
+      alt: "Mock Channel Product",
+      role: "primary",
+      sortOrder: 0,
+    },
+    {
+      externalId: "mock-image-variant",
+      url: "https://mock.channel.test/images/mock-variant-1.jpg",
+      alt: "Mock Channel Product blue variant",
+      role: "gallery",
+      sortOrder: 1,
+      variantExternalIds: ["mock-variant-1"],
+    },
+  ],
+  options: [{
+    name: "color",
+    displayName: "Color",
+    sortOrder: 0,
+    values: [{ value: "blue", displayValue: "Blue", sortOrder: 0 }],
+  }],
+  tags: ["mock", "featured"],
+  brand: "Porulle",
+  categories: ["mock-products"],
+  status: "active",
+  variants: [{
+    externalId: "mock-variant-1",
+    sku: "MOCK-SKU-1",
+    barcode: "0123456789012",
+    optionValues: { color: "blue" },
+    prices: [{ currency: "USD", amount: 2500 }],
+  }],
+}];
+
 export function mockChannelConnector(options: MockChannelConnectorOptions = {}) {
   const orders = new Map<string, ChannelOrderSlice>();
+  const catalog = new Map<string, ChannelPushCatalogItem>();
 
   return defineChannelConnector({
     providerId: "mock",
@@ -28,10 +86,11 @@ export function mockChannelConnector(options: MockChannelConnectorOptions = {})
       importCatalog: true,
       importInventory: true,
       pushOrder: true,
+      pushCatalog: true,
       receiveWebhooks: true,
     },
-    async importCatalog() {
-      return Ok({ items: options.catalog ?? [], nextCursor: null });
+    async importCatalog(_store?: ChannelStore) {
+      return Ok({ items: options.catalog ?? defaultCatalog, nextCursor: null });
     },
     async fetchInventory(_store, ids) {
       const requestedIds = ids ?? [];
@@ -52,6 +111,26 @@ export function mockChannelConnector(options: MockChannelConnectorOptions = {})
         remoteUrl: `https://mock.channel.test/orders/${remoteOrderId}`,
       });
     },
+    async pushCatalog(_store, items, opts?: { dryRun?: boolean }) {
+      if (options.pushCatalogTransportError) return Err(options.pushCatalogTransportError);
+      const outcomes = items.map((item) => {
+        const error = options.pushCatalogFailures?.[item.externalId];
+        if (error) return { externalId: item.externalId, ok: false, error };
+        const previous = catalog.get(item.externalId);
+        const previousFields: ChannelPushCatalogPreviousField[] = previous
+          ? [...previous.fields, ...(previous.variants ?? []).flatMap((variant) => variant.fields)]
+            .map((field) => ({ fieldPath: field.fieldPath, value: structuredClone(field.value) }))
+          : [];
+        if (opts?.dryRun !== true) catalog.set(item.externalId, structuredClone(item));
+        return {
+          externalId: item.externalId,
+          ok: true,
+          ...(previousFields.length > 0 ? { previousFields } : {}),
+        };
+      });
+      if (opts?.dryRun !== true) options.onPushCatalog?.(structuredClone(items));
+      return Ok({ outcomes });
+    },
     async fetchOrderStatus(_store, remoteId) {
       if (!orders.has(remoteId)) {
         return Err(new CommerceValidationError(`Mock order "${remoteId}" was not found.`));

package/src/schema.ts

@@ -1,4 +1,5 @@
 import {
+  boolean,
   index,
   integer,
   jsonb,
@@ -8,6 +9,8 @@ import {
   uniqueIndex,
   uuid,
 } from "@porulle/core/drizzle";
+import type { FieldPath } from "@porulle/core";
+import type { CatalogFieldMapping } from "./catalog-field-mapping.js";
 
 export const connectedStores = pgTable(
   "connected_stores",
@@ -20,6 +23,8 @@ export const connectedStores = pgTable(
     status: text("status", { enum: ["connected", "disconnected", "error"] })
       .notNull()
       .default("connected"),
+    catalogWriteEnabled: boolean("catalog_write_enabled").notNull().default(false),
+    catalogFieldMapping: jsonb("catalog_field_mapping").$type<CatalogFieldMapping>().notNull().default([]),
     catalogCursor: text("catalog_cursor"),
     inventoryCursor: text("inventory_cursor"),
     lastSyncAt: timestamp("last_sync_at", { withTimezone: true }),
@@ -48,6 +53,7 @@ export const channelEntityMap = pgTable(
     variantId: uuid("variant_id"),
     lastSyncedAt: timestamp("last_synced_at", { withTimezone: true }).defaultNow().notNull(),
     syncHash: text("sync_hash").notNull(),
+    heldFieldPaths: jsonb("held_field_paths").$type<FieldPath[]>().notNull().default([]),
   },
   (table) => ({
     orgIdx: index("idx_channel_entity_map_org").on(table.organizationId),