@porulle/plugin-channel-connector 0.9.0

package/dist/schema.js

@@ -0,0 +1,104 @@
+import { index, integer, jsonb, pgTable, text, timestamp, uniqueIndex, uuid, } from "@porulle/core/drizzle";
+export const connectedStores = pgTable("connected_stores", {
+    id: uuid("id").defaultRandom().primaryKey(),
+    organizationId: text("organization_id").notNull(),
+    provider: text("provider").notNull(),
+    credentials: jsonb("credentials").$type().notNull(),
+    storeDomain: text("store_domain").notNull(),
+    status: text("status", { enum: ["connected", "disconnected", "error"] })
+        .notNull()
+        .default("connected"),
+    catalogCursor: text("catalog_cursor"),
+    inventoryCursor: text("inventory_cursor"),
+    lastSyncAt: timestamp("last_sync_at", { withTimezone: true }),
+    lastReconcileAt: timestamp("last_reconcile_at", { withTimezone: true }),
+    lastReconcileReport: jsonb("last_reconcile_report").$type(),
+    webhookSecret: text("webhook_secret"),
+    breakerState: jsonb("breaker_state").$type().notNull().default({}),
+    createdAt: timestamp("created_at", { withTimezone: true }).defaultNow().notNull(),
+    updatedAt: timestamp("updated_at", { withTimezone: true }).defaultNow().notNull(),
+}, (table) => ({
+    orgIdx: index("idx_connected_stores_org").on(table.organizationId),
+    orgProviderIdx: index("idx_connected_stores_org_provider").on(table.organizationId, table.provider),
+}));
+export const channelEntityMap = pgTable("channel_entity_map", {
+    id: uuid("id").defaultRandom().primaryKey(),
+    organizationId: text("organization_id").notNull(),
+    storeId: uuid("store_id").references(() => connectedStores.id, { onDelete: "cascade" }).notNull(),
+    kind: text("kind", { enum: ["entity", "variant"] }).notNull(),
+    externalId: text("external_id").notNull(),
+    entityId: uuid("entity_id").notNull(),
+    variantId: uuid("variant_id"),
+    lastSyncedAt: timestamp("last_synced_at", { withTimezone: true }).defaultNow().notNull(),
+    syncHash: text("sync_hash").notNull(),
+}, (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 channelOrderExports = pgTable("channel_order_exports", {
+    id: uuid("id").defaultRandom().primaryKey(),
+    organizationId: text("organization_id").notNull(),
+    storeId: uuid("store_id").references(() => connectedStores.id, { onDelete: "cascade" }).notNull(),
+    orderId: uuid("order_id").notNull(),
+    customerData: jsonb("customer_data").$type(),
+    state: text("state", { enum: ["pending", "exported", "confirmed", "failed", "abandoned"] })
+        .notNull()
+        .default("pending"),
+    failureKind: text("failure_kind", { enum: ["definitive", "transient"] }),
+    remoteOrderId: text("remote_order_id"),
+    remoteUrl: text("remote_url"),
+    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_order_exports_org").on(table.organizationId),
+    storeIdx: index("idx_channel_order_exports_store").on(table.storeId),
+    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 channelExportEvents = pgTable("channel_export_events", {
+    id: uuid("id").defaultRandom().primaryKey(),
+    organizationId: text("organization_id").notNull(),
+    exportId: uuid("export_id")
+        .references(() => channelOrderExports.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_export_events_org").on(table.organizationId),
+    exportIdx: index("idx_channel_export_events_export").on(table.exportId),
+}));
+export const channelRefundRequests = pgTable("channel_refund_requests", {
+    id: uuid("id").defaultRandom().primaryKey(),
+    organizationId: text("organization_id").notNull(),
+    storeId: uuid("store_id").references(() => connectedStores.id, { onDelete: "cascade" }).notNull(),
+    orderId: uuid("order_id").notNull(),
+    remoteRefundId: text("remote_refund_id").notNull(),
+    amount: integer("amount").notNull(),
+    state: text("state", { enum: ["requested", "approved", "rejected", "executed"] }).notNull().default("requested"),
+    approvedBy: text("approved_by"),
+    createdAt: timestamp("created_at", { withTimezone: true }).defaultNow().notNull(),
+    updatedAt: timestamp("updated_at", { withTimezone: true }).defaultNow().notNull(),
+}, (table) => ({
+    orgIdx: index("idx_channel_refund_requests_org").on(table.organizationId),
+    pendingIdx: index("idx_channel_refund_requests_pending").on(table.organizationId, table.state),
+    remoteUnique: uniqueIndex("channel_refund_requests_store_remote_unique").on(table.storeId, table.remoteRefundId),
+}));
+export const channelRefundEvents = pgTable("channel_refund_events", {
+    id: uuid("id").defaultRandom().primaryKey(),
+    organizationId: text("organization_id").notNull(),
+    requestId: uuid("request_id").references(() => channelRefundRequests.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_refund_events_org").on(table.organizationId),
+    requestIdx: index("idx_channel_refund_events_request").on(table.requestId),
+}));

package/dist/service.d.ts

@@ -0,0 +1,132 @@
+import type { Actor, ChannelConnector, ChannelOrderSlice, PluginDb, PluginResult, PluginTxFn } from "@porulle/core";
+import type { JobsAdapter } from "@porulle/core";
+import { type ChannelOrderExport, type ChannelRefundRequest, type ConnectedStore } from "./schema.js";
+export type ExportState = ChannelOrderExport["state"];
+export interface ReconcileReport extends Record<string, unknown> {
+    imported: number;
+    converged: number;
+    archived: number;
+    inventoryUpdated: number;
+    driftAlert: boolean;
+}
+export type PublicConnectedStore = Omit<ConnectedStore, "credentials" | "webhookSecret"> & {
+    credentials: "[REDACTED]";
+    webhookSecret: "[REDACTED]";
+};
+export interface ChannelComplianceData {
+    customer: {
+        id?: string;
+        email?: string;
+    };
+    exports: Array<{
+        exportId: string;
+        orderId: string;
+        customerData: NonNullable<ChannelOrderExport["customerData"]>;
+    }>;
+}
+export interface ChannelConnectorPluginOptions {
+    connectors?: ChannelConnector[];
+    oauth?: {
+        stateSecret: string;
+        postConnectRedirect: string;
+    };
+    inventoryTimeoutMs?: number;
+    jobs?: JobsAdapter;
+    exportSla?: {
+        definitiveMs?: number;
+        transientMs?: number;
+    };
+    refundAutoMax?: number;
+    newStoreDays?: number;
+    driftAlertThreshold?: number;
+    reconcileJitterWindowMs?: number;
+}
+export interface ChannelStockLine {
+    entityId: string;
+    variantId?: string;
+    title?: string;
+    quantity: number;
+}
+export declare function canExportTransition(from: ExportState, to: ExportState): boolean;
+export declare class ChannelConnectorService {
+    private readonly db;
+    private readonly services;
+    private readonly connectors;
+    private readonly transact;
+    private readonly jobs;
+    private readonly options;
+    constructor(db: PluginDb, services: Record<string, unknown>, options?: ChannelConnectorPluginOptions, transaction?: PluginTxFn);
+    getConnector(providerId: string): ChannelConnector | undefined;
+    private get catalog();
+    private getStoreRecord;
+    getStoreByDomain(shopDomain: string): Promise<ConnectedStore | undefined>;
+    getStoresByDomain(shopDomain: string): Promise<ConnectedStore[]>;
+    connectStore(orgId: string, input: {
+        provider: string;
+        credentials: Record<string, unknown>;
+        storeDomain: string;
+        webhookSecret?: string;
+    }): Promise<PluginResult<PublicConnectedStore>>;
+    private get optionsJobs();
+    disconnectStore(orgId: string, id: string): Promise<PluginResult<PublicConnectedStore>>;
+    disconnectStoreSystem(orgId: string, id: string, redactDomain?: boolean): Promise<PluginResult<PublicConnectedStore>>;
+    getStore(orgId: string, id: string): Promise<PluginResult<PublicConnectedStore>>;
+    listStores(orgId: string): Promise<PluginResult<PublicConnectedStore[]>>;
+    validateLineStock(orgId: string, lines: ChannelStockLine[], timeoutMs?: number): Promise<void>;
+    importCatalog(orgId: string, storeId: string, actor: Actor): Promise<PluginResult<{
+        imported: number;
+        cursor: string | null;
+    }>>;
+    private convergeCatalogItems;
+    reconcile(orgId: string, storeId: string, actor: Actor): Promise<PluginResult<ReconcileReport>>;
+    getReconcileStatus(orgId: string, storeId: string): Promise<PluginResult<{
+        lastReconcileAt: Date | null;
+        report: ReconcileReport | null;
+        driftAlert: boolean;
+    }>>;
+    syncInventory(orgId: string, storeId: string, actor: Actor): Promise<PluginResult<{
+        synced: number;
+    }>>;
+    handleWebhook(orgId: string, storeId: string, event: {
+        id: string;
+        type: string;
+        data: unknown;
+    }): Promise<PluginResult<{
+        processed: true;
+        data?: ChannelComplianceData;
+        redacted?: number;
+    }>>;
+    private complianceEmail;
+    private channelCustomerExports;
+    private channelCustomerDataRequest;
+    private redactCustomerData;
+    private redactShopData;
+    private resolveOrderId;
+    private setMappedInventory;
+    private convergeCatalogItem;
+    private createRefundRequest;
+    private executeRefund;
+    listRefundRequests(orgId: string): Promise<PluginResult<ChannelRefundRequest[]>>;
+    approveRefund(orgId: string, id: string, actor: {
+        userId: string;
+    }): Promise<PluginResult<ChannelRefundRequest>>;
+    rejectRefund(orgId: string, id: string, actor: {
+        userId: string;
+    }): Promise<PluginResult<ChannelRefundRequest>>;
+    private refundLinesForRequest;
+    createExport(orgId: string, storeId: string, orderId: string): Promise<PluginResult<ChannelOrderExport>>;
+    transitionExport(orgId: string, exportId: string, toState: ExportState, changedBy: string, reason?: string, failureKind?: "definitive" | "transient"): Promise<PluginResult<ChannelOrderExport>>;
+    exportOrder(orgId: string, storeId: string, slice: ChannelOrderSlice, actor: Actor): Promise<PluginResult<ChannelOrderExport>>;
+    buildOrderSlice(orgId: string, storeId: string, orderId: string): Promise<PluginResult<ChannelOrderSlice>>;
+    reapExports(input: {
+        definitiveMs: number;
+        transientMs: number;
+    }): Promise<{
+        abandonedCount: number;
+        refundedOrderIds: string[];
+    }>;
+    getExport(orgId: string, id: string): Promise<PluginResult<ChannelOrderExport>>;
+    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>>;
+}