@porulle/plugin-channel-connector 0.74.5 → 0.75.0

package/dist/mock-connector.d.ts

@@ -73,6 +73,7 @@ export declare function mockChannelConnector(options?: MockChannelConnectorOptio
                 externalVariantId: string;
                 quantity: number;
             }[];
+            amount?: number;
         } | {
             kind: "return.updated";
             remoteReturnId: string;

package/dist/mock-connector.js

@@ -65,7 +65,7 @@ const channelEventSchema = z.discriminatedUnion("kind", [
     z.object({ kind: z.literal("inventory.changed"), levels: z.array(level) }),
     z.object({ kind: z.literal("order.cancelled"), remoteOrderId: z.string() }),
     z.object({ kind: z.literal("order.fulfilled"), remoteOrderId: z.string(), partial: z.boolean(), shipments: z.array(shipment) }),
-    z.object({ kind: z.literal("refund.created"), remoteOrderId: z.string(), remoteRefundId: z.string(), lines: z.array(z.object({ externalVariantId: z.string(), quantity: z.number().int() })) }),
+    z.object({ kind: z.literal("refund.created"), remoteOrderId: z.string(), remoteRefundId: z.string(), lines: z.array(z.object({ externalVariantId: z.string(), quantity: z.number().int() })), amount: z.number().int().exactOptional() }),
     z.object({ kind: z.literal("return.updated"), remoteReturnId: z.string(), status: z.enum(["approved", "declined", "closed", "cancelled"]) }),
     z.object({ kind: z.literal("connection.revoked") }),
     z.object({ kind: z.literal("compliance.request"), request: z.enum(["customer_data", "customer_redact", "shop_redact"]), data: z.record(z.string(), z.unknown()) }),

package/dist/schema.d.ts

@@ -2106,6 +2106,31 @@ export declare const channelRefundRequests: import("drizzle-orm/pg-core/table").
             identity: undefined;
             generated: undefined;
         }, {}, {}>;
+        lines: import("@porulle/core/drizzle").PgColumn<{
+            name: "lines";
+            tableName: "channel_refund_requests";
+            dataType: "json";
+            columnType: "PgJsonb";
+            data: {
+                lineItemId: string;
+                quantity: number;
+            }[];
+            driverParam: unknown;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            $type: {
+                lineItemId: string;
+                quantity: number;
+            }[];
+        }>;
         state: import("@porulle/core/drizzle").PgColumn<{
             name: "state";
             tableName: "channel_refund_requests";

package/dist/schema.js

@@ -199,6 +199,8 @@ export const channelRefundRequests = pgTable("channel_refund_requests", {
     orderId: uuid("order_id").notNull(),
     remoteRefundId: text("remote_refund_id").notNull(),
     amount: integer("amount").notNull(),
+    /** The order lines the store refunded. Null on requests made before it was kept. */
+    lines: jsonb("lines").$type(),
     state: text("state", { enum: ["requested", "approved", "rejected", "executed"] }).notNull().default("requested"),
     approvedBy: text("approved_by"),
     createdAt: timestamp("created_at", { withTimezone: true }).defaultNow().notNull(),

package/dist/service.js

@@ -4185,17 +4185,21 @@ export class ChannelConnectorService {
             else
                 refundLines.push({ lineItemId: orderLine.id, quantity });
         }
-        const amount = refundLines.reduce((sum, line) => {
+        const priced = refundLines.reduce((sum, line) => {
             const item = orderLines.find((candidate) => candidate.id === line.lineItemId);
             return sum + Math.round((item.totalPrice + item.taxAmount - item.discountAmount) * line.quantity / item.quantity);
         }, 0);
+        // What the store refunded, when it says, and never more than the platform's own price for the lines:
+        // a store can refund part of a line, or a line it discounted, but cannot claim more than it sold.
+        const amount = event.amount === undefined ? priced : Math.min(Math.max(0, event.amount), priced);
         const [order] = await this.db.select().from(orders).where(and(eq(orders.organizationId, orgId), eq(orders.id, orderId)));
         if (!order)
             return PluginErr("Order not found.", "NOT_FOUND");
         const max = this.options.refundAutoMax ?? order.amountCaptured ?? order.grandTotal;
         const ageOk = Date.now() - store.createdAt.getTime() >= (this.options.newStoreDays ?? 7) * 86_400_000;
-        const auto = clean && amount > 0 && ageOk && amount <= max;
-        const rows = await this.db.insert(channelRefundRequests).values({ organizationId: orgId, storeId: store.id, orderId, remoteRefundId, amount, state: auto ? "approved" : "requested", approvedBy: auto ? requireUserId(actor) : null }).returning();
+        // Only a whole-line refund is automatic; any other amount is a person's call.
+        const auto = clean && amount > 0 && amount === priced && ageOk && amount <= max;
+        const rows = await this.db.insert(channelRefundRequests).values({ organizationId: orgId, storeId: store.id, orderId, remoteRefundId, amount, lines: clean ? refundLines : null, state: auto ? "approved" : "requested", approvedBy: auto ? requireUserId(actor) : null }).returning();
         const request = rows[0];
         await this.db.insert(channelRefundEvents).values({ organizationId: orgId, requestId: request.id, fromState: null, toState: request.state, reason: auto ? "Automatic guarded refund" : "Operator approval required", changedBy: requireUserId(actor) });
         if (auto) {
@@ -4211,7 +4215,8 @@ export class ChannelConnectorService {
     }
     async executeRefund(request, lines, actor) {
         const ordersService = this.services.orders;
-        const result = await ordersService.refundLines(request.orderId, { lines, reason: `Channel refund ${request.remoteRefundId}` }, actor);
+        // A request that kept its lines pays back its own amount; an older one is priced from the lines rebuilt for it.
+        const result = await ordersService.refundLines(request.orderId, { lines, reason: `Channel refund ${request.remoteRefundId}`, ...(request.lines ? { amount: request.amount } : {}) }, actor);
         if (!result.ok)
             return PluginErr(result.error?.message ?? "Refund execution failed.");
         const [updated] = await this.db.update(channelRefundRequests).set({ state: "executed", updatedAt: new Date() }).where(and(eq(channelRefundRequests.organizationId, request.organizationId), eq(channelRefundRequests.id, request.id), eq(channelRefundRequests.state, "approved"))).returning();
@@ -4225,7 +4230,7 @@ export class ChannelConnectorService {
         const [request] = await this.db.update(channelRefundRequests).set({ state: "approved", approvedBy: actor.userId, updatedAt: new Date() }).where(and(eq(channelRefundRequests.organizationId, orgId), eq(channelRefundRequests.id, id), eq(channelRefundRequests.state, "requested"))).returning();
         if (!request)
             return PluginErr("Refund request not found or already handled.", "NOT_FOUND");
-        const lines = await this.refundLinesForRequest(request);
+        const lines = request.lines ?? await this.refundLinesForRequest(request);
         const executed = await this.executeRefund(request, lines, createSystemActor(orgId));
         if (!executed.ok) {
             // Nothing moved: back to `requested`, so the operator can approve again once the cause is fixed.

package/package.json

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

package/src/mock-connector.ts

@@ -94,7 +94,7 @@ const channelEventSchema = z.discriminatedUnion("kind", [
   z.object({ kind: z.literal("inventory.changed"), levels: z.array(level) }),
   z.object({ kind: z.literal("order.cancelled"), remoteOrderId: z.string() }),
   z.object({ kind: z.literal("order.fulfilled"), remoteOrderId: z.string(), partial: z.boolean(), shipments: z.array(shipment) }),
-  z.object({ kind: z.literal("refund.created"), remoteOrderId: z.string(), remoteRefundId: z.string(), lines: z.array(z.object({ externalVariantId: z.string(), quantity: z.number().int() })) }),
+  z.object({ kind: z.literal("refund.created"), remoteOrderId: z.string(), remoteRefundId: z.string(), lines: z.array(z.object({ externalVariantId: z.string(), quantity: z.number().int() })), amount: z.number().int().exactOptional() }),
   z.object({ kind: z.literal("return.updated"), remoteReturnId: z.string(), status: z.enum(["approved", "declined", "closed", "cancelled"]) }),
   z.object({ kind: z.literal("connection.revoked") }),
   z.object({ kind: z.literal("compliance.request"), request: z.enum(["customer_data", "customer_redact", "shop_redact"]), data: z.record(z.string(), z.unknown()) }),

package/src/schema.ts

@@ -287,6 +287,8 @@ export const channelRefundRequests = pgTable(
     orderId: uuid("order_id").notNull(),
     remoteRefundId: text("remote_refund_id").notNull(),
     amount: integer("amount").notNull(),
+    /** The order lines the store refunded. Null on requests made before it was kept. */
+    lines: jsonb("lines").$type<Array<{ lineItemId: string; quantity: number }>>(),
     state: text("state", { enum: ["requested", "approved", "rejected", "executed"] }).notNull().default("requested"),
     approvedBy: text("approved_by"),
     createdAt: timestamp("created_at", { withTimezone: true }).defaultNow().notNull(),

package/src/service.ts

@@ -5327,16 +5327,20 @@ export class ChannelConnectorService {
       if (!orderLine || !Number.isInteger(quantity) || quantity < 1 || quantity > orderLine.quantity - orderLine.refundedQuantity) clean = false;
       else refundLines.push({ lineItemId: orderLine.id, quantity });
     }
-    const amount = refundLines.reduce((sum, line) => {
+    const priced = refundLines.reduce((sum, line) => {
       const item = orderLines.find((candidate) => candidate.id === line.lineItemId)!;
       return sum + Math.round((item.totalPrice + item.taxAmount - item.discountAmount) * line.quantity / item.quantity);
     }, 0);
+    // What the store refunded, when it says, and never more than the platform's own price for the lines:
+    // a store can refund part of a line, or a line it discounted, but cannot claim more than it sold.
+    const amount = event.amount === undefined ? priced : Math.min(Math.max(0, event.amount), priced);
     const [order] = await this.db.select().from(orders).where(and(eq(orders.organizationId, orgId), eq(orders.id, orderId)));
     if (!order) return PluginErr("Order not found.", "NOT_FOUND");
     const max = this.options.refundAutoMax ?? order.amountCaptured ?? order.grandTotal;
     const ageOk = Date.now() - store.createdAt.getTime() >= (this.options.newStoreDays ?? 7) * 86_400_000;
-    const auto = clean && amount > 0 && ageOk && amount <= max;
-    const rows = await this.db.insert(channelRefundRequests).values({ organizationId: orgId, storeId: store.id, orderId, remoteRefundId, amount, state: auto ? "approved" : "requested", approvedBy: auto ? requireUserId(actor) : null }).returning();
+    // Only a whole-line refund is automatic; any other amount is a person's call.
+    const auto = clean && amount > 0 && amount === priced && ageOk && amount <= max;
+    const rows = await this.db.insert(channelRefundRequests).values({ organizationId: orgId, storeId: store.id, orderId, remoteRefundId, amount, lines: clean ? refundLines : null, state: auto ? "approved" : "requested", approvedBy: auto ? requireUserId(actor) : null }).returning();
     const request = rows[0] as ChannelRefundRequest;
     await this.db.insert(channelRefundEvents).values({ organizationId: orgId, requestId: request.id, fromState: null, toState: request.state, reason: auto ? "Automatic guarded refund" : "Operator approval required", changedBy: requireUserId(actor) });
     if (auto) {
@@ -5352,8 +5356,9 @@ export class ChannelConnectorService {
   }
 
   private async executeRefund(request: ChannelRefundRequest, lines: Array<{ lineItemId: string; quantity: number }>, actor: Actor): Promise<PluginResult<ChannelRefundRequest>> {
-    const ordersService = this.services.orders as { refundLines(orderId: string, input: { lines: Array<{ lineItemId: string; quantity: number }>; reason?: string }, actor: Actor): Promise<{ ok: boolean; error?: { message: string } }> };
-    const result = await ordersService.refundLines(request.orderId, { lines, reason: `Channel refund ${request.remoteRefundId}` }, actor);
+    const ordersService = this.services.orders as { refundLines(orderId: string, input: { lines: Array<{ lineItemId: string; quantity: number }>; reason?: string; amount?: number }, actor: Actor): Promise<{ ok: boolean; error?: { message: string } }> };
+    // A request that kept its lines pays back its own amount; an older one is priced from the lines rebuilt for it.
+    const result = await ordersService.refundLines(request.orderId, { lines, reason: `Channel refund ${request.remoteRefundId}`, ...(request.lines ? { amount: request.amount } : {}) }, actor);
     if (!result.ok) return PluginErr(result.error?.message ?? "Refund execution failed.");
     const [updated] = await this.db.update(channelRefundRequests).set({ state: "executed", updatedAt: new Date() }).where(and(eq(channelRefundRequests.organizationId, request.organizationId), eq(channelRefundRequests.id, request.id), eq(channelRefundRequests.state, "approved"))).returning();
     await this.db.insert(channelRefundEvents).values({ organizationId: request.organizationId, requestId: request.id, fromState: "approved", toState: "executed", reason: "Platform refund executed", changedBy: requireUserId(actor) });
@@ -5367,7 +5372,7 @@ export class ChannelConnectorService {
   async approveRefund(orgId: string, id: string, actor: { userId: string }): Promise<PluginResult<ChannelRefundRequest>> {
     const [request] = await this.db.update(channelRefundRequests).set({ state: "approved", approvedBy: actor.userId, updatedAt: new Date() }).where(and(eq(channelRefundRequests.organizationId, orgId), eq(channelRefundRequests.id, id), eq(channelRefundRequests.state, "requested"))).returning();
     if (!request) return PluginErr("Refund request not found or already handled.", "NOT_FOUND");
-    const lines = await this.refundLinesForRequest(request as ChannelRefundRequest);
+    const lines = request.lines ?? await this.refundLinesForRequest(request as ChannelRefundRequest);
     const executed = await this.executeRefund(request as ChannelRefundRequest, lines, createSystemActor(orgId));
     if (!executed.ok) {
       // Nothing moved: back to `requested`, so the operator can approve again once the cause is fixed.