@porulle/plugin-channel-connector 0.72.0 → 0.73.0

package/dist/index.js

@@ -3,7 +3,7 @@ import { CommerceConflictError, CommerceInvalidTransitionError, CommerceNotFound
 import { z } from "@hono/zod-openapi";
 import { and, eq } from "@porulle/core/drizzle";
 import { processedWebhookEvents } from "@porulle/core/schema";
-import { channelCatalogPushEvents, channelCatalogPushes, channelCatalogConflicts, channelCatalogConflictEvents, channelEntityLinks, channelEntityMap, channelExportEvents, channelOrderExports, channelRefundEvents, channelRefundRequests, connectedStores, } from "./schema.js";
+import { channelCatalogPushEvents, channelCatalogPushes, channelCatalogConflicts, channelCatalogConflictEvents, channelEntityLinks, channelEntityMap, channelExportEvents, channelOrderExports, channelRefundEvents, channelRefundRequests, channelReturns, connectedStores, } from "./schema.js";
 import { ChannelConnectorService, catalogPushConcurrencyKey, CHANNEL_INVENTORY_MAX_ITEMS_PER_INVOCATION, } from "./service.js";
 import { buildHooks } from "./hooks.js";
 import { oauthStateEventId, signState, verifyState } from "./oauth-state.js";
@@ -334,6 +334,7 @@ export function channelConnectorPlugin(options = {}) {
             channelOrderExports,
             channelExportEvents,
             channelRefundRequests,
+            channelReturns,
             channelRefundEvents,
         }),
         hooks: () => buildHooks(options),

package/dist/schema.d.ts

@@ -1714,6 +1714,212 @@ export declare const channelExportEvents: import("drizzle-orm/pg-core/table").Pg
     };
     dialect: "pg";
 }>;
+/**
+ * A return the marketplace asked a store to take, and the store's answer so far. The refund for it
+ * arrives separately, on the store's own refund webhook.
+ */
+export declare const channelReturns: import("drizzle-orm/pg-core/table").PgTableWithColumns<{
+    name: "channel_returns";
+    schema: undefined;
+    columns: {
+        id: import("@porulle/core/drizzle").PgColumn<{
+            name: "id";
+            tableName: "channel_returns";
+            dataType: "string";
+            columnType: "PgUUID";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: true;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        organizationId: import("@porulle/core/drizzle").PgColumn<{
+            name: "organization_id";
+            tableName: "channel_returns";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        storeId: import("@porulle/core/drizzle").PgColumn<{
+            name: "store_id";
+            tableName: "channel_returns";
+            dataType: "string";
+            columnType: "PgUUID";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        orderId: import("@porulle/core/drizzle").PgColumn<{
+            name: "order_id";
+            tableName: "channel_returns";
+            dataType: "string";
+            columnType: "PgUUID";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        remoteReturnId: import("@porulle/core/drizzle").PgColumn<{
+            name: "remote_return_id";
+            tableName: "channel_returns";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        status: import("@porulle/core/drizzle").PgColumn<{
+            name: "status";
+            tableName: "channel_returns";
+            dataType: "string";
+            columnType: "PgText";
+            data: "cancelled" | "approved" | "requested" | "declined" | "closed";
+            driverParam: string;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: ["requested", "approved", "declined", "closed", "cancelled"];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        lines: import("@porulle/core/drizzle").PgColumn<{
+            name: "lines";
+            tableName: "channel_returns";
+            dataType: "json";
+            columnType: "PgJsonb";
+            data: {
+                orderLineItemId: string;
+                quantity: number;
+            }[];
+            driverParam: unknown;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            $type: {
+                orderLineItemId: string;
+                quantity: number;
+            }[];
+        }>;
+        reason: import("@porulle/core/drizzle").PgColumn<{
+            name: "reason";
+            tableName: "channel_returns";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        note: import("@porulle/core/drizzle").PgColumn<{
+            name: "note";
+            tableName: "channel_returns";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        createdAt: import("@porulle/core/drizzle").PgColumn<{
+            name: "created_at";
+            tableName: "channel_returns";
+            dataType: "date";
+            columnType: "PgTimestamp";
+            data: Date;
+            driverParam: string;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        updatedAt: import("@porulle/core/drizzle").PgColumn<{
+            name: "updated_at";
+            tableName: "channel_returns";
+            dataType: "date";
+            columnType: "PgTimestamp";
+            data: Date;
+            driverParam: string;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+    };
+    dialect: "pg";
+}>;
 export declare const channelRefundRequests: import("drizzle-orm/pg-core/table").PgTableWithColumns<{
     name: "channel_refund_requests";
     schema: undefined;

package/dist/schema.js

@@ -164,6 +164,26 @@ export const channelExportEvents = pgTable("channel_export_events", {
     orgIdx: index("idx_channel_export_events_org").on(table.organizationId),
     exportIdx: index("idx_channel_export_events_export").on(table.exportId),
 }));
+/**
+ * A return the marketplace asked a store to take, and the store's answer so far. The refund for it
+ * arrives separately, on the store's own refund webhook.
+ */
+export const channelReturns = pgTable("channel_returns", {
+    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(),
+    remoteReturnId: text("remote_return_id").notNull(),
+    status: text("status", { enum: ["requested", "approved", "declined", "closed", "cancelled"] }).notNull().default("requested"),
+    lines: jsonb("lines").$type().notNull(),
+    reason: text("reason").notNull(),
+    note: text("note"),
+    createdAt: timestamp("created_at", { withTimezone: true }).defaultNow().notNull(),
+    updatedAt: timestamp("updated_at", { withTimezone: true }).defaultNow().notNull(),
+}, (table) => ({
+    orderIdx: index("idx_channel_returns_order").on(table.organizationId, table.orderId),
+    remoteUnique: uniqueIndex("channel_returns_store_remote_unique").on(table.storeId, table.remoteReturnId),
+}));
 export const channelRefundRequests = pgTable("channel_refund_requests", {
     id: uuid("id").defaultRandom().primaryKey(),
     organizationId: text("organization_id").notNull(),

package/dist/service.d.ts

@@ -673,6 +673,23 @@ export declare class ChannelConnectorService {
     private recordChannelFulfillments;
     /** Every line with quantity still to ship, for a parcel whose own lines could not be matched. */
     private unfulfilledLines;
+    /**
+     * Asks the store this order was pushed to to take lines back. Each line is named to the store by its
+     * own variant id; a line the store has no record of is refused before the store is asked anything.
+     * The return is recorded as `requested`; the store's `returns/*` webhooks move it from there.
+     */
+    requestReturn(orgId: string, orderId: string, input: {
+        lines: Array<{
+            orderLineItemId: string;
+            quantity: number;
+        }>;
+        reason: string;
+        note?: string;
+    }): Promise<PluginResult<{
+        id: string;
+        remoteReturnId: string;
+        status: string;
+    }>>;
     /** A cancelled or refunded order: nothing to push to a store, ever again. */
     isOrderClosed(orgId: string, orderId: string): Promise<boolean>;
     exportOrder(orgId: string, storeId: string, slice: ChannelOrderSlice, actor: Actor): Promise<PluginResult<ChannelOrderExport>>;

package/dist/service.js

@@ -7,7 +7,7 @@ import { resolveLiveCredentials, withLiveCredentials } from "./live-credentials.
 import { and, desc, eq, inArray, isNull, lte, or, sql } from "@porulle/core/drizzle";
 import { brands, categories, customerAddresses, customers, entityBrands, entityCategories, entityMedia, entityTags, inventoryLevels, mediaAssets, optionTypes, optionValues, fulfillmentLineItems, fulfillmentRecords, orderLineItems, orders, prices, sellableAttributes, sellableCustomFields, sellableEntities, sellableEntityRevisions, entityFieldDefinitions, tags, variants, variantOptionValues, } from "@porulle/core/schema";
 import { planAbsentArchives } from "./deletion-policy.js";
-import { channelCatalogPushEvents, channelCatalogPushes, channelCatalogConflicts, channelCatalogConflictEvents, channelEntityLinks, channelEntityMap, channelExportEvents, channelOrderExports, connectedStores, channelRefundEvents, channelRefundRequests, } from "./schema.js";
+import { channelCatalogPushEvents, channelCatalogPushes, channelCatalogConflicts, channelCatalogConflictEvents, channelEntityLinks, channelEntityMap, channelExportEvents, channelOrderExports, connectedStores, channelRefundEvents, channelRefundRequests, channelReturns, } from "./schema.js";
 import { mergeCatalogFieldMapping, normalizeCatalogFieldMapping, selectCatalogFieldMapping, } from "./catalog-field-mapping.js";
 export const CATALOG_PUSH_BATCH_SIZES = {
     mock: 100,
@@ -34,6 +34,14 @@ export const CHANNEL_INVENTORY_MAX_ITEMS_PER_INVOCATION = 20;
  * cancelling at the store for exactly this reason, so the two directions cannot loop.
  */
 export const CHANNEL_ORDER_CANCELLED_REASON = "channel_order_cancelled";
+/** What each store return webhook says about the return. */
+const RETURN_WEBHOOK_STATUS = {
+    "returns/approve": "approved",
+    "returns/decline": "declined",
+    "returns/close": "closed",
+    "returns/cancel": "cancelled",
+    "returns/reopen": "approved",
+};
 /** The slice of a store order body's `fulfillments` (Shopify's REST spelling) a parcel is read from. */
 const channelFulfillmentsSchema = z.array(z.object({
     id: z.union([z.string(), z.number()]),
@@ -2286,6 +2294,10 @@ export class ChannelConnectorService {
                 "orders/partially_fulfilled",
                 "orders/cancelled",
                 "refunds/create",
+                "returns/approve",
+                "returns/decline",
+                "returns/close",
+                "returns/cancel",
                 "app/uninstalled",
             ], callbackUrl);
             if (!registration.ok) {
@@ -3923,6 +3935,14 @@ export class ChannelConnectorService {
                 }
             }
         }
+        else if (RETURN_WEBHOOK_STATUS[event.type] !== undefined) {
+            // The store's answer to a return the marketplace asked for. A return it never asked for is ignored.
+            const status = RETURN_WEBHOOK_STATUS[event.type];
+            const remoteReturnId = String(data.id ?? "");
+            if (status !== undefined && remoteReturnId !== "") {
+                await this.db.update(channelReturns).set({ status, updatedAt: new Date() }).where(and(eq(channelReturns.organizationId, orgId), eq(channelReturns.storeId, storeId), eq(channelReturns.remoteReturnId, remoteReturnId)));
+            }
+        }
         else if (event.type === "refunds/create") {
             const refund = await this.createRefundRequest(orgId, store, data, actor);
             if (!refund.ok)
@@ -4423,6 +4443,61 @@ export class ChannelConnectorService {
             return remaining > 0 ? [{ orderLineItemId: line.id, quantity: remaining }] : [];
         });
     }
+    /**
+     * Asks the store this order was pushed to to take lines back. Each line is named to the store by its
+     * own variant id; a line the store has no record of is refused before the store is asked anything.
+     * The return is recorded as `requested`; the store's `returns/*` webhooks move it from there.
+     */
+    async requestReturn(orgId, orderId, input) {
+        if (input.lines.length === 0)
+            return PluginErr("Name at least one line to return.", "VALIDATION_FAILED");
+        const [exported] = await this.db
+            .select({ storeId: channelOrderExports.storeId, remoteOrderId: channelOrderExports.remoteOrderId })
+            .from(channelOrderExports)
+            .where(and(eq(channelOrderExports.organizationId, orgId), eq(channelOrderExports.orderId, orderId)));
+        if (!exported || exported.remoteOrderId === null)
+            return PluginErr("This order never reached a store, so there is nothing to return there.", "NOT_FOUND");
+        const store = await this.getStoreRecord(orgId, exported.storeId);
+        if (!store || store.status !== "connected")
+            return PluginErr("The store this order went to is not connected.", "NOT_FOUND");
+        const connector = this.connectors.get(store.provider);
+        if (!connector?.requestReturn)
+            return PluginErr(`Returns are not available for ${store.provider} stores.`, "NOT_IMPLEMENTED");
+        const lines = await this.db.select({ id: orderLineItems.id, variantId: orderLineItems.variantId, quantity: orderLineItems.quantity }).from(orderLineItems).where(eq(orderLineItems.orderId, orderId));
+        const variantIds = lines.flatMap((line) => (line.variantId === null ? [] : [line.variantId]));
+        const mapped = variantIds.length === 0 ? [] : await this.db
+            .select({ variantId: channelEntityMap.variantId, externalId: channelEntityMap.externalId })
+            .from(channelEntityMap)
+            .where(and(eq(channelEntityMap.organizationId, orgId), eq(channelEntityMap.storeId, store.id), eq(channelEntityMap.kind, "variant"), inArray(channelEntityMap.variantId, variantIds)));
+        const remote = [];
+        for (const wanted of input.lines) {
+            const line = lines.find((candidate) => candidate.id === wanted.orderLineItemId);
+            if (!line)
+                return PluginErr(`Line ${wanted.orderLineItemId} is not on this order.`, "VALIDATION_FAILED");
+            if (!Number.isInteger(wanted.quantity) || wanted.quantity < 1 || wanted.quantity > line.quantity)
+                return PluginErr(`Line ${wanted.orderLineItemId} has ${line.quantity} to return; asked for ${wanted.quantity}.`, "VALIDATION_FAILED");
+            const externalId = mapped.find((entry) => entry.variantId === line.variantId)?.externalId;
+            if (!externalId)
+                return PluginErr(`The store has no record of line ${wanted.orderLineItemId}, so it cannot take it back.`, "CHANNEL_MAPPING_MISSING");
+            remote.push({ externalVariantId: externalId, quantity: wanted.quantity });
+        }
+        const asked = await connector.requestReturn(store, exported.remoteOrderId, { lines: remote, reason: input.reason, ...(input.note ? { note: input.note } : {}) });
+        if (!asked.ok)
+            return PluginErr(asked.error.message, asked.error.code);
+        const [row] = await this.db.insert(channelReturns).values({
+            organizationId: orgId,
+            storeId: store.id,
+            orderId,
+            remoteReturnId: asked.value.remoteReturnId,
+            status: "requested",
+            lines: input.lines,
+            reason: input.reason,
+            note: input.note ?? null,
+        }).returning({ id: channelReturns.id, remoteReturnId: channelReturns.remoteReturnId, status: channelReturns.status });
+        if (!row)
+            return PluginErr("The return could not be recorded.");
+        return Ok(row);
+    }
     /** A cancelled or refunded order: nothing to push to a store, ever again. */
     async isOrderClosed(orgId, orderId) {
         const [order] = await this.db.select({ status: orders.status }).from(orders).where(and(eq(orders.organizationId, orgId), eq(orders.id, orderId)));

package/package.json

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

package/src/index.ts

@@ -26,6 +26,7 @@ import {
   channelOrderExports,
   channelRefundEvents,
   channelRefundRequests,
+  channelReturns,
   connectedStores,
 } from "./schema.js";
 import {
@@ -503,6 +504,7 @@ export function channelConnectorPlugin(options: ChannelConnectorPluginOptions =
       channelOrderExports,
       channelExportEvents,
       channelRefundRequests,
+      channelReturns,
       channelRefundEvents,
     }),
     hooks: () => buildHooks(options),

package/src/schema.ts

@@ -234,6 +234,31 @@ export const channelExportEvents = pgTable(
   }),
 );
 
+/**
+ * A return the marketplace asked a store to take, and the store's answer so far. The refund for it
+ * arrives separately, on the store's own refund webhook.
+ */
+export const channelReturns = pgTable(
+  "channel_returns",
+  {
+    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(),
+    remoteReturnId: text("remote_return_id").notNull(),
+    status: text("status", { enum: ["requested", "approved", "declined", "closed", "cancelled"] }).notNull().default("requested"),
+    lines: jsonb("lines").$type<Array<{ orderLineItemId: string; quantity: number }>>().notNull(),
+    reason: text("reason").notNull(),
+    note: text("note"),
+    createdAt: timestamp("created_at", { withTimezone: true }).defaultNow().notNull(),
+    updatedAt: timestamp("updated_at", { withTimezone: true }).defaultNow().notNull(),
+  },
+  (table) => ({
+    orderIdx: index("idx_channel_returns_order").on(table.organizationId, table.orderId),
+    remoteUnique: uniqueIndex("channel_returns_store_remote_unique").on(table.storeId, table.remoteReturnId),
+  }),
+);
+
 export const channelRefundRequests = pgTable(
   "channel_refund_requests",
   {

package/src/service.ts

@@ -85,6 +85,7 @@ import {
   connectedStores,
   channelRefundEvents,
   channelRefundRequests,
+  channelReturns,
   type ChannelCatalogPush,
   type ChannelCatalogConflict,
   type ChannelOrderExport,
@@ -133,6 +134,15 @@ export const CHANNEL_INVENTORY_MAX_ITEMS_PER_INVOCATION = 20;
  */
 export const CHANNEL_ORDER_CANCELLED_REASON = "channel_order_cancelled";
 
+/** What each store return webhook says about the return. */
+const RETURN_WEBHOOK_STATUS: Partial<Record<string, "approved" | "declined" | "closed" | "cancelled" | "requested">> = {
+  "returns/approve": "approved",
+  "returns/decline": "declined",
+  "returns/close": "closed",
+  "returns/cancel": "cancelled",
+  "returns/reopen": "approved",
+};
+
 /** The slice of a store order body's `fulfillments` (Shopify's REST spelling) a parcel is read from. */
 const channelFulfillmentsSchema = z.array(z.object({
   id: z.union([z.string(), z.number()]),
@@ -3205,6 +3215,10 @@ export class ChannelConnectorService {
         "orders/partially_fulfilled",
         "orders/cancelled",
         "refunds/create",
+        "returns/approve",
+        "returns/decline",
+        "returns/close",
+        "returns/cancel",
         "app/uninstalled",
       ], callbackUrl);
       if (!registration.ok) {
@@ -5028,6 +5042,13 @@ export class ChannelConnectorService {
           }
         }
       }
+    } else if (RETURN_WEBHOOK_STATUS[event.type] !== undefined) {
+      // The store's answer to a return the marketplace asked for. A return it never asked for is ignored.
+      const status = RETURN_WEBHOOK_STATUS[event.type];
+      const remoteReturnId = String(data.id ?? "");
+      if (status !== undefined && remoteReturnId !== "") {
+        await this.db.update(channelReturns).set({ status, updatedAt: new Date() }).where(and(eq(channelReturns.organizationId, orgId), eq(channelReturns.storeId, storeId), eq(channelReturns.remoteReturnId, remoteReturnId)));
+      }
     } else if (event.type === "refunds/create") {
       const refund = await this.createRefundRequest(orgId, store, data, actor);
       if (!refund.ok) return refund;
@@ -5571,6 +5592,59 @@ export class ChannelConnectorService {
     });
   }
 
+  /**
+   * Asks the store this order was pushed to to take lines back. Each line is named to the store by its
+   * own variant id; a line the store has no record of is refused before the store is asked anything.
+   * The return is recorded as `requested`; the store's `returns/*` webhooks move it from there.
+   */
+  async requestReturn(
+    orgId: string,
+    orderId: string,
+    input: { lines: Array<{ orderLineItemId: string; quantity: number }>; reason: string; note?: string },
+  ): Promise<PluginResult<{ id: string; remoteReturnId: string; status: string }>> {
+    if (input.lines.length === 0) return PluginErr("Name at least one line to return.", "VALIDATION_FAILED");
+    const [exported] = await this.db
+      .select({ storeId: channelOrderExports.storeId, remoteOrderId: channelOrderExports.remoteOrderId })
+      .from(channelOrderExports)
+      .where(and(eq(channelOrderExports.organizationId, orgId), eq(channelOrderExports.orderId, orderId)));
+    if (!exported || exported.remoteOrderId === null) return PluginErr("This order never reached a store, so there is nothing to return there.", "NOT_FOUND");
+    const store = await this.getStoreRecord(orgId, exported.storeId);
+    if (!store || store.status !== "connected") return PluginErr("The store this order went to is not connected.", "NOT_FOUND");
+    const connector = this.connectors.get(store.provider);
+    if (!connector?.requestReturn) return PluginErr(`Returns are not available for ${store.provider} stores.`, "NOT_IMPLEMENTED");
+
+    const lines = await this.db.select({ id: orderLineItems.id, variantId: orderLineItems.variantId, quantity: orderLineItems.quantity }).from(orderLineItems).where(eq(orderLineItems.orderId, orderId));
+    const variantIds = lines.flatMap((line) => (line.variantId === null ? [] : [line.variantId]));
+    const mapped = variantIds.length === 0 ? [] : await this.db
+      .select({ variantId: channelEntityMap.variantId, externalId: channelEntityMap.externalId })
+      .from(channelEntityMap)
+      .where(and(eq(channelEntityMap.organizationId, orgId), eq(channelEntityMap.storeId, store.id), eq(channelEntityMap.kind, "variant"), inArray(channelEntityMap.variantId, variantIds)));
+    const remote: Array<{ externalVariantId: string; quantity: number }> = [];
+    for (const wanted of input.lines) {
+      const line = lines.find((candidate) => candidate.id === wanted.orderLineItemId);
+      if (!line) return PluginErr(`Line ${wanted.orderLineItemId} is not on this order.`, "VALIDATION_FAILED");
+      if (!Number.isInteger(wanted.quantity) || wanted.quantity < 1 || wanted.quantity > line.quantity) return PluginErr(`Line ${wanted.orderLineItemId} has ${line.quantity} to return; asked for ${wanted.quantity}.`, "VALIDATION_FAILED");
+      const externalId = mapped.find((entry) => entry.variantId === line.variantId)?.externalId;
+      if (!externalId) return PluginErr(`The store has no record of line ${wanted.orderLineItemId}, so it cannot take it back.`, "CHANNEL_MAPPING_MISSING");
+      remote.push({ externalVariantId: externalId, quantity: wanted.quantity });
+    }
+
+    const asked = await connector.requestReturn(store as ChannelStore, exported.remoteOrderId, { lines: remote, reason: input.reason, ...(input.note ? { note: input.note } : {}) });
+    if (!asked.ok) return PluginErr(asked.error.message, asked.error.code);
+    const [row] = await this.db.insert(channelReturns).values({
+      organizationId: orgId,
+      storeId: store.id,
+      orderId,
+      remoteReturnId: asked.value.remoteReturnId,
+      status: "requested",
+      lines: input.lines,
+      reason: input.reason,
+      note: input.note ?? null,
+    }).returning({ id: channelReturns.id, remoteReturnId: channelReturns.remoteReturnId, status: channelReturns.status });
+    if (!row) return PluginErr("The return could not be recorded.");
+    return Ok(row);
+  }
+
   /** A cancelled or refunded order: nothing to push to a store, ever again. */
   async isOrderClosed(orgId: string, orderId: string): Promise<boolean> {
     const [order] = await this.db.select({ status: orders.status }).from(orders).where(and(eq(orders.organizationId, orgId), eq(orders.id, orderId)));