@porulle/plugin-channel-connector 0.10.8 → 0.13.0

package/dist/catalog-field-mapping.d.ts

@@ -0,0 +1,32 @@
+import type { FieldPath } from "@porulle/core";
+export declare const catalogFieldTargets: readonly ["native", "attribute", "meta"];
+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;
+}>;
+export declare const providerCatalogFieldMappingDefaults: Record<string, CatalogFieldMapping>;
+export declare function matchFieldPath(pattern: string, path: string): boolean;
+export declare function isValidCatalogMappingFieldPath(value: string): boolean;
+export declare function validateCatalogMappingRow(input: Partial<CatalogFieldMappingRow> & {
+    fieldPath: string;
+    target: CatalogFieldTarget;
+    remoteKey: string;
+}, provider: string): CatalogFieldMappingRow;
+export declare function normalizeCatalogFieldMapping(input: unknown, provider: string): CatalogFieldMapping;
+export declare function mergeCatalogFieldMapping(provider: string, overrides: unknown, filterableCustomFields?: ReadonlySet<string> | Readonly<Record<string, boolean>>, warnings?: string[]): CatalogFieldMapping;
+export declare function compareCatalogFieldMappingSpecificity(left: CatalogFieldMappingRow, right: CatalogFieldMappingRow): number;
+export declare function selectCatalogFieldMapping(mapping: CatalogFieldMapping, path: string): CatalogFieldMappingRow | undefined;

package/dist/catalog-field-mapping.js

@@ -0,0 +1,178 @@
+export const catalogFieldTargets = ["native", "attribute", "meta"];
+const fieldSegment = /^[A-Za-z0-9_-]+$/;
+const forbiddenFieldPaths = ["variants.sku", "variants.barcode", "options", "prices", "entity.status"];
+export const providerCatalogFieldMappingDefaults = {
+    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, path) {
+    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) {
+    const segments = value.split(".");
+    return segments.length > 0 && segments.every((segment) => segment === "*" || fieldSegment.test(segment));
+}
+function couldCoverForbiddenSubtree(fieldPath, root) {
+    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) {
+    return forbiddenFieldPaths.some((root) => couldCoverForbiddenSubtree(fieldPath, root));
+}
+export function validateCatalogMappingRow(input, provider) {
+    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) {
+    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, fieldPath };
+    });
+}
+function normalizeCatalogMappingRow(row, provider) {
+    if (!row || typeof row !== "object" || Array.isArray(row))
+        throw new Error("Catalog mapping rows must be objects.");
+    const value = row;
+    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,
+        remoteKey: value.remoteKey,
+    }, provider);
+}
+export function normalizeCatalogFieldMapping(input, provider) {
+    return mappingEntries(input).map((row) => normalizeCatalogMappingRow(row, provider));
+}
+function normalizeStoredCatalogFieldMapping(input, provider, warnings) {
+    let entries;
+    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) {
+    if (hint instanceof Set)
+        return [...hint].map((path) => [path, true]);
+    return Object.entries(hint);
+}
+export function mergeCatalogFieldMapping(provider, overrides, filterableCustomFields, warnings = []) {
+    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" : "meta",
+        remoteKey: fieldPath.split(".")[1] ?? customFieldDefault.remoteKey,
+    }));
+    return [...merged.filter((row) => row.fieldPath !== customFieldPattern), ...expanded];
+}
+function wildcardCount(fieldPath) {
+    return fieldPath.split(".").filter((segment) => segment === "*").length;
+}
+function compareStrings(left, right) {
+    if (left < right)
+        return -1;
+    if (left > right)
+        return 1;
+    return 0;
+}
+export function compareCatalogFieldMappingSpecificity(left, right) {
+    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, path) {
+    return mapping.filter((row) => matchFieldPath(row.fieldPath, path)).sort(compareCatalogFieldMappingSpecificity)[0];
+}

package/dist/catalog-push-trigger.d.ts

@@ -0,0 +1,26 @@
+import type { HookContext } from "@porulle/core";
+type CatalogUpdateInput = {
+    slug?: string;
+    status?: string;
+    metadata?: Record<string, unknown>;
+    customFields?: Record<string, unknown | null>;
+};
+export declare const CHANNEL_CONVERGENCE_ORIGIN = "channel-convergence";
+export declare const CHANNEL_CONVERGENCE_CTX: {
+    hookContext: {
+        origin: string;
+    };
+};
+export declare function maybeEnqueueCatalogPush(args: {
+    entityId: string;
+    changedFieldPaths: string[];
+    context: HookContext;
+}): Promise<void>;
+export declare function recordUpdateFieldPaths(input: CatalogUpdateInput, context: HookContext): CatalogUpdateInput;
+export declare function handleCatalogAfterUpdate(args: {
+    result: {
+        id: string;
+    };
+    context: HookContext;
+}): Promise<void>;
+export {};

package/dist/catalog-push-trigger.js

@@ -0,0 +1,70 @@
+import { resolveOrgIdForCommerce, isValidFieldPath } from "@porulle/core";
+import { and, eq } from "@porulle/core/drizzle";
+import { catalogPushConcurrencyKey } from "./service.js";
+import { channelEntityMap } from "./schema.js";
+export const CHANNEL_CONVERGENCE_ORIGIN = "channel-convergence";
+export const CHANNEL_CONVERGENCE_CTX = {
+    hookContext: { origin: CHANNEL_CONVERGENCE_ORIGIN },
+};
+function updateInputFieldPaths(input) {
+    const paths = [];
+    if (input.slug !== undefined)
+        paths.push("entity.slug");
+    if (input.status !== undefined)
+        paths.push("entity.status");
+    if (input.metadata) {
+        for (const key of Object.keys(input.metadata))
+            paths.push(`entity.metadata.${key}`);
+    }
+    if (input.customFields) {
+        for (const name of Object.keys(input.customFields))
+            paths.push(`customFields.${name}.en`);
+    }
+    return paths.filter(isValidFieldPath);
+}
+export async function maybeEnqueueCatalogPush(args) {
+    if (args.context.context.origin === CHANNEL_CONVERGENCE_ORIGIN)
+        return;
+    if (args.changedFieldPaths.length === 0)
+        return;
+    const orgId = resolveOrgIdForCommerce(args.context.actor, args.context.commerceConfig);
+    const catalog = args.context.services.catalog;
+    const mappings = await args.context.db
+        .select({ storeId: channelEntityMap.storeId })
+        .from(channelEntityMap)
+        .where(and(eq(channelEntityMap.organizationId, orgId), eq(channelEntityMap.entityId, args.entityId), eq(channelEntityMap.kind, "entity")));
+    const forceFieldPathsByStore = new Map();
+    for (const mapping of mappings) {
+        const owners = await catalog.resolveFieldOwners(args.entityId, mapping.storeId);
+        const changedPaths = args.changedFieldPaths.filter((path) => {
+            const owner = owners.get(path);
+            return owner === "platform" || owner === "shared";
+        });
+        if (changedPaths.length > 0)
+            forceFieldPathsByStore.set(mapping.storeId, changedPaths);
+    }
+    await Promise.all([...forceFieldPathsByStore].map(([storeId, forceFieldPaths]) => args.context.jobs.enqueue("channel/push-catalog", {
+        organizationId: orgId,
+        storeId,
+        entityIds: [args.entityId],
+        forceFieldPaths: { [args.entityId]: forceFieldPaths },
+    }, {
+        organizationId: orgId,
+        concurrencyKey: catalogPushConcurrencyKey({ storeId, entityIds: [args.entityId] }),
+        supersedes: true,
+    })));
+}
+export function recordUpdateFieldPaths(input, context) {
+    context.context.changedFieldPaths = updateInputFieldPaths(input);
+    return input;
+}
+export async function handleCatalogAfterUpdate(args) {
+    const changedFieldPaths = Array.isArray(args.context.context.changedFieldPaths)
+        ? args.context.context.changedFieldPaths.map(String)
+        : [];
+    await maybeEnqueueCatalogPush({
+        entityId: args.result.id,
+        changedFieldPaths,
+        context: args.context,
+    });
+}

package/dist/hooks.js

@@ -1,24 +1,39 @@
-import { resolveOrgId } from "@porulle/core";
+import { resolveOrgIdForCommerce } from "@porulle/core";
 import { and, eq, inArray } from "@porulle/core/drizzle";
 import { sellableEntities } from "@porulle/core/schema";
 import { ChannelConnectorService, } from "./service.js";
+import { handleCatalogAfterUpdate, recordUpdateFieldPaths, } from "./catalog-push-trigger.js";
 export function buildHooks(options) {
     return [{
             key: "checkout.beforePayment",
             async handler(args) {
                 const { data, context } = args;
+                if (data.lineItems.length === 0)
+                    return data;
                 const service = new ChannelConnectorService(context.db, context.services, options);
-                await service.validateLineStock(resolveOrgId(context.actor), data.lineItems, options.inventoryTimeoutMs);
+                await service.validateLineStock(resolveOrgIdForCommerce(context.actor, context.commerceConfig), data.lineItems, options.inventoryTimeoutMs);
                 return data;
             },
         }, {
             key: "orders.afterCreate",
             async handler(args) {
                 const { result, context } = args;
-                const orgId = resolveOrgId(context.actor);
+                const orgId = resolveOrgIdForCommerce(context.actor, context.commerceConfig);
                 const entities = await context.db.select({ id: sellableEntities.id, sourceStoreId: sellableEntities.sourceStoreId }).from(sellableEntities).where(and(eq(sellableEntities.organizationId, orgId), inArray(sellableEntities.id, (result.lineItems ?? []).map((line) => line.entityId))));
                 const stores = new Set(entities.map((entity) => entity.sourceStoreId).filter((storeId) => storeId !== null));
                 await Promise.all([...stores].map((storeId) => context.jobs.enqueue("channel/push-order", { orgId, storeId, orderId: result.id }, { organizationId: orgId, concurrencyKey: `push:${result.id}:${storeId}`, supersedes: true })));
             },
+        }, {
+            key: "catalog.beforeUpdate",
+            handler(args) {
+                const { data, context } = args;
+                return recordUpdateFieldPaths(data, context);
+            },
+        }, {
+            key: "catalog.afterUpdate",
+            async handler(args) {
+                const { result, context } = args;
+                await handleCatalogAfterUpdate({ result, context });
+            },
         }];
 }

package/dist/index.d.ts

@@ -1,9 +1,11 @@
 import { type ChannelConnectorPluginOptions } from "./service.js";
 export { mockChannelConnector } from "./mock-connector.js";
 export type { MockChannelConnectorOptions } from "./mock-connector.js";
-export { ChannelConnectorService, canExportTransition, } from "./service.js";
+export { ChannelConnectorService, CATALOG_OUTBOUND_SUPPRESSION_WINDOW_MS, CATALOG_PUSH_BATCH_SIZES, CATALOG_PUSH_MAX_ATTEMPTS, canCatalogPushTransition, canExportTransition, catalogPushConcurrencyKey, catalogPushRetryDelayMs, isCatalogPushBreakerOpen, } 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 { ChannelComplianceData, ChannelConnectorPluginOptions, ChannelStockLine, ExportState, PublicConnectedStore, ReconcileReport, } from "./service.js";
+export type { BackfillCatalogOptions, BackfillCatalogReport, BuildCatalogPushItemsOptions, BuildCatalogPushItemsResult, CatalogPushAssemblyField, CatalogPushAssemblyImage, CatalogPushAssemblyItem, CatalogPushPreviewBefore, CatalogPushPreviewBeforeStatus, CatalogPushPreviewDiff, CatalogPushPreviewItem, CatalogPushPreviewResult, CatalogPushPreviewUnavailable, PushCatalogToStoreResult, CatalogPushJobResult, CatalogFieldConflict, CatalogFieldSkip, CatalogPushFieldSkip, CatalogPushSkipReason, CatalogConflictState, CatalogWriteSettings, ChannelComplianceData, ChannelConnectorPluginOptions, ChannelStockLine, ExportState, PublicConnectedStore, ReconcileReport, } from "./service.js";
 export type { OAuthStatePayload, OAuthStateResult } from "./oauth-state.js";
-export type { ChannelEntityMapEntry, ChannelExportEvent, ChannelOrderExport, ChannelRefundEvent, ChannelRefundRequest, ConnectedStore, } from "./schema.js";
+export type { ChannelCatalogPush, ChannelCatalogPushEvent, ChannelCatalogConflict, ChannelCatalogConflictEvent, ChannelEntityMapEntry, ChannelExportEvent, ChannelOrderExport, ChannelRefundEvent, ChannelRefundRequest, ConnectedStore, } from "./schema.js";
 export declare function channelConnectorPlugin(options?: ChannelConnectorPluginOptions): import("@porulle/core").CommercePlugin;

package/dist/index.js

@@ -1,14 +1,15 @@
 import { createHash } from "node:crypto";
-import { CommerceConflictError, CommerceInvalidTransitionError, CommerceNotFoundError, CommerceValidationError, defineCommercePlugin, router, createSystemActor, } from "@porulle/core";
+import { CommerceConflictError, CommerceInvalidTransitionError, CommerceNotFoundError, CommerceValidationError, defineCommercePlugin, router, createSystemActor, isValidFieldPath, requireUserId, } from "@porulle/core";
 import { z } from "@hono/zod-openapi";
 import { and, eq } from "@porulle/core/drizzle";
 import { processedWebhookEvents } from "@porulle/core/schema";
-import { channelEntityMap, channelExportEvents, channelOrderExports, channelRefundEvents, channelRefundRequests, connectedStores, } from "./schema.js";
-import { ChannelConnectorService, } from "./service.js";
+import { channelCatalogPushEvents, channelCatalogPushes, channelCatalogConflicts, channelCatalogConflictEvents, channelEntityMap, channelExportEvents, channelOrderExports, channelRefundEvents, channelRefundRequests, connectedStores, } from "./schema.js";
+import { ChannelConnectorService, catalogPushConcurrencyKey, } from "./service.js";
 import { buildHooks } from "./hooks.js";
 import { oauthStateEventId, signState, verifyState } from "./oauth-state.js";
 export { mockChannelConnector } from "./mock-connector.js";
-export { ChannelConnectorService, canExportTransition, } from "./service.js";
+export { ChannelConnectorService, CATALOG_OUTBOUND_SUPPRESSION_WINDOW_MS, CATALOG_PUSH_BATCH_SIZES, CATALOG_PUSH_MAX_ATTEMPTS, canCatalogPushTransition, canExportTransition, catalogPushConcurrencyKey, catalogPushRetryDelayMs, isCatalogPushBreakerOpen, } from "./service.js";
+export { isValidCatalogMappingFieldPath, matchFieldPath, mergeCatalogFieldMapping, normalizeCatalogFieldMapping, compareCatalogFieldMappingSpecificity, providerCatalogFieldMappingDefaults, selectCatalogFieldMapping, validateCatalogMappingRow, } from "./catalog-field-mapping.js";
 export { signState, verifyState } from "./oauth-state.js";
 function unwrap(result) {
     if (result.ok)
@@ -90,7 +91,39 @@ export function channelConnectorPlugin(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) => String(input.storeId) },
+            handler: async ({ input, ctx }) => {
+                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;
+                    await jobs.enqueue("channel/backfill-catalog", { orgId, storeId, dryRun }, {
+                        organizationId: orgId,
+                        concurrencyKey: storeId,
+                        supersedes: false,
+                    });
+                }
+                return { output: result.value };
             },
         },
         {
@@ -128,6 +161,32 @@ export function channelConnectorPlugin(options = {}) {
                 return { output: { exportId: result.value.id, state: result.value.state } };
             },
         },
+        {
+            slug: "channel/push-catalog",
+            concurrency: { key: catalogPushConcurrencyKey, supersedes: true },
+            handler: async ({ input, ctx }) => {
+                const service = new ChannelConnectorService(ctx.db, ctx.services, options);
+                const orgId = String(input.organizationId ?? input.orgId);
+                const storeId = String(input.storeId);
+                const entityIds = Array.isArray(input.entityIds)
+                    ? input.entityIds.map(String)
+                    : undefined;
+                const forceFieldPaths = typeof input.forceFieldPaths === "object" && input.forceFieldPaths !== null
+                    ? Object.fromEntries(Object.entries(input.forceFieldPaths).flatMap(([entityId, paths]) => [
+                        [entityId, Array.isArray(paths) ? paths.filter((path) => typeof path === "string" && isValidFieldPath(path)) : []],
+                    ]))
+                    : undefined;
+                const cursor = typeof input.cursor === "string" ? input.cursor : undefined;
+                const result = await service.executeCatalogPushJob(orgId, storeId, {
+                    ...(entityIds ? { entityIds } : {}),
+                    ...(forceFieldPaths ? { forceFieldPaths } : {}),
+                    ...(cursor ? { cursor } : {}),
+                }, createSystemActor(orgId), { jobs: ctx.services.jobs });
+                if (!result.ok)
+                    throw new Error(result.error);
+                return { output: result.value };
+            },
+        },
         {
             slug: "channel/reap-exports",
             handler: async ({ input, ctx }) => {
@@ -150,6 +209,10 @@ export function channelConnectorPlugin(options = {}) {
         schema: () => ({
             connectedStores,
             channelEntityMap,
+            channelCatalogPushes,
+            channelCatalogPushEvents,
+            channelCatalogConflicts,
+            channelCatalogConflictEvents,
             channelOrderExports,
             channelExportEvents,
             channelRefundRequests,
@@ -341,10 +404,98 @@ export function channelConnectorPlugin(options = {}) {
                 .summary("Get a connected channel store")
                 .permission("channels:read")
                 .handler(async ({ params, orgId }) => 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 }) => 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 }) => {
+                const values = input;
+                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 }) => unwrap(await service.getReconcileStatus(orgId, params.storeId)));
+            channels.get("/conflicts")
+                .summary("List channel catalog conflicts")
+                .permission("channels:read")
+                .query(z.object({ storeId: z.string().min(1).optional(), state: z.enum(["open", "resolved"]).optional() }))
+                .handler(async ({ query, orgId }) => {
+                const values = query;
+                return unwrap(await service.listCatalogConflicts(orgId, values.storeId, values.state));
+            });
+            channels.post("/conflicts/{id}/resolve")
+                .summary("Resolve a channel catalog conflict")
+                .permission("channels:manage")
+                .params(z.object({ id: z.string().min(1) }))
+                .input(z.object({ choose: z.enum(["platform", "store"]) }))
+                .handler(async ({ params, orgId, input, actor }) => {
+                const values = input;
+                return unwrap(await service.resolveCatalogConflict(orgId, params.id, values.choose, actor));
+            });
+            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 }) => {
+                const values = input;
+                if (values.dryRun === true) {
+                    return unwrap(await service.backfillCatalog(orgId, params.storeId, createSystemActor(orgId), { dryRun: true }));
+                }
+                const jobs = ctx.services.jobs;
+                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/{storeId}/push-catalog")
+                .summary("Enqueue a catalog push for a connected store")
+                .permission("channels:manage")
+                .input(z.object({ entityIds: z.array(z.string()).optional() }))
+                .handler(async ({ params, orgId, input }) => {
+                unwrap(await service.getStore(orgId, params.storeId));
+                const values = input;
+                const jobs = ctx.services.jobs;
+                await jobs.enqueue("channel/push-catalog", {
+                    organizationId: orgId,
+                    storeId: params.storeId,
+                    ...(values.entityIds ? { entityIds: values.entityIds } : {}),
+                }, {
+                    organizationId: orgId,
+                    concurrencyKey: catalogPushConcurrencyKey({
+                        storeId: params.storeId,
+                        ...(values.entityIds ? { entityIds: values.entityIds } : {}),
+                    }),
+                    supersedes: true,
+                });
+                return { enqueued: true, storeId: params.storeId };
+            });
+            channels.post("/stores/{storeId}/push-catalog/preview")
+                .summary("Preview a catalog push for a connected store")
+                .permission("channels:manage")
+                .input(z.object({ entityIds: z.array(z.string()).optional() }))
+                .handler(async ({ params, orgId, input }) => {
+                unwrap(await service.getStore(orgId, params.storeId));
+                const values = input;
+                return unwrap(await service.previewCatalogPush(orgId, params.storeId, values.entityIds));
+            });
             channels.post("/stores/{id}/disconnect")
                 .summary("Disconnect a channel store")
                 .permission("channels:manage")
@@ -360,15 +511,15 @@ export function channelConnectorPlugin(options = {}) {
             channels.post("/refund-requests/{id}/approve")
                 .summary("Approve a channel refund request")
                 .permission("channels:manage")
-                .handler(async ({ params, orgId, actor }) => unwrap(await service.approveRefund(orgId, params.id, actor)));
+                .handler(async ({ params, orgId, actor }) => unwrap(await service.approveRefund(orgId, params.id, { userId: requireUserId(actor) })));
             channels.post("/refund-requests/{id}/reject")
                 .summary("Reject a channel refund request")
                 .permission("channels:manage")
-                .handler(async ({ params, orgId, actor }) => unwrap(await service.rejectRefund(orgId, params.id, actor)));
+                .handler(async ({ params, orgId, actor }) => unwrap(await service.rejectRefund(orgId, params.id, { userId: requireUserId(actor) })));
             channels.post("/exports/{id}/retry")
                 .summary("Retry a failed channel order export")
                 .permission("channels:manage")
-                .handler(async ({ params, orgId, actor }) => unwrap(await service.retryExport(orgId, params.id, actor.userId)));
+                .handler(async ({ params, orgId, actor }) => unwrap(await service.retryExport(orgId, params.id, requireUserId(actor))));
             return channels.routes();
         },
     });