@porulle/adapter-woocommerce 0.75.0 → 0.77.0

package/dist/webhooks.js

@@ -96,6 +96,8 @@ const refundSchema = z.object({
     /** What the merchant refunded, positive, in the store's currency: part of a line is less than the line. */
     amount: z.string().nullish(),
     line_items: z.array(z.object({ product_id: id, variation_id: id, quantity: z.number() })).default([]),
+    /** Delivery refunded: one entry per order shipping item, total negative. */
+    shipping_lines: z.array(z.object({ total: z.string().nullish() })).default([]),
 });
 function meta(entries, key) {
     return entries.find((entry) => entry.key === key)?.value;
@@ -180,6 +182,9 @@ export async function orderEvents(client, remoteOrderId) {
             return refund;
         const currency = order.currency ?? client.credentials.currency;
         const amount = currency ? toMinorUnits(refund.value.data.amount, currency) : undefined;
+        const shipping = currency
+            ? refund.value.data.shipping_lines.reduce((sum, line) => sum + Math.abs(toMinorUnits(line.total, currency) ?? 0), 0)
+            : 0;
         events.push({
             kind: "refund.created",
             remoteOrderId: order.id,
@@ -189,6 +194,7 @@ export async function orderEvents(client, remoteOrderId) {
                 return quantity > 0 ? [{ externalVariantId: line.variation_id !== "0" ? line.variation_id : line.product_id, quantity }] : [];
             }),
             ...(amount === undefined ? {} : { amount: Math.abs(amount) }),
+            ...(shipping > 0 ? { shippingAmount: shipping } : {}),
         });
     }
     return Ok(events);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@porulle/adapter-woocommerce",
-  "version": "0.75.0",
+  "version": "0.77.0",
   "license": "MIT",
   "type": "module",
   "exports": {
@@ -16,7 +16,7 @@
   },
   "dependencies": {
     "zod": "^4.1.11",
-    "@porulle/core": "0.75.0"
+    "@porulle/core": "0.77.0"
   },
   "devDependencies": {
     "@types/node": "^24.5.2",

package/src/index.ts

@@ -6,7 +6,7 @@ import { pushCatalog, pushCaches } from "./catalog-push.js";
 import { discoverStore, normalizeStoreDomain, probeStore, refusedStoreUrl, wooClient, wooCredentialsSchema } from "./client.js";
 import type { WooClient, WooTransportOptions } from "./client.js";
 import { inventoryFor, inventoryPage } from "./inventory.js";
-import { cancelOrder, orderStatus, pushOrder } from "./orders.js";
+import { cancelOrder, orderStatus, pushOrder, recordRefund } from "./orders.js";
 import { decodeDelivery, orderEvents, registerWebhooks, unregisterWebhooks, verifyDelivery, webhookHealth, WOO_WEBHOOK_TOPICS } from "./webhooks.js";
 
 export { normalizeStoreDomain, probeStore, refusedStoreUrl, WOO_BLOCKED_BY_FIREWALL } from "./client.js";
@@ -164,6 +164,9 @@ export function wooConnector(options: WooConnectorOptions = {}): ChannelConnecto
     async cancelOrder(store, remoteId, input) {
       return withClient(store, (client) => cancelOrder(client, remoteId, input));
     },
+    async recordRefund(store, remoteId, input) {
+      return withClient(store, (client) => recordRefund(client, remoteId, input));
+    },
     async pushCatalog(store, items, opts) {
       return withClient(store, (client) => pushCatalog(client, store, items, opts, caches));
     },

package/src/orders.ts

@@ -1,5 +1,5 @@
 import { CHANNEL_CANCEL_REFUSED, CHANNEL_OUT_OF_STOCK, CHANNEL_TOTAL_MISMATCH, currencyExponent, Err, Ok, toMinorUnits } from "@porulle/core";
-import type { ChannelCancelOrderInput, ChannelConnectorError, ChannelOrderSlice, ChannelOrderStatus, ChannelPushOrderResult, Result } from "@porulle/core";
+import type { ChannelCancelOrderInput, ChannelConnectorError, ChannelRefundRecord, ChannelOrderSlice, ChannelOrderStatus, ChannelPushOrderResult, Result } from "@porulle/core";
 import { z } from "zod";
 import type { WooClient } from "./client.js";
 import { available } from "./inventory.js";
@@ -14,6 +14,7 @@ export const wooOrderSchema = z.object({
   date_created_gmt: z.string().nullish(),
   meta_data: z.array(z.object({ key: z.string(), value: z.unknown() })).default([]),
   line_items: z.array(z.object({ id, product_id: id, variation_id: id, quantity: z.number(), total: z.string().nullish() })).default([]),
+  shipping_lines: z.array(z.object({ id, total: z.string().nullish() })).default([]),
   refunds: z.array(z.object({ id, total: z.string().nullish() })).default([]),
 });
 export type WooOrder = z.infer<typeof wooOrderSchema>;
@@ -111,7 +112,12 @@ export async function pushOrder(client: WooClient, slice: ChannelOrderSlice, opt
 
   const currency = slice.currency;
   const decimals = client.credentials.priceDecimals;
-  const discounts = allocate(slice.lines.map((line) => line.totalPrice), slice.discount?.amount ?? 0);
+  // The platform's own per-line discount when it sends one, so the store's line totals are what the
+  // platform refunds a line at; otherwise the slice's discount split here.
+  const shares = slice.lines.map((line) => line.discountAmount ?? 0);
+  const discounts = slice.discount !== undefined && shares.reduce((sum, share) => sum + share, 0) === slice.discount.amount
+    ? shares
+    : allocate(slice.lines.map((line) => line.totalPrice), slice.discount?.amount ?? 0);
   const [firstName = "", ...rest] = slice.customer.name.trim().split(/\s+/);
   const source = slice.customer.shippingAddress;
   const address = {
@@ -200,6 +206,41 @@ export async function cancelOrder(client: WooClient, remoteId: string, input: Ch
   return cancelled.ok ? Ok(undefined) : cancelled;
 }
 
+/**
+ * Books at the store a refund the marketplace already paid the shopper: `api_refund: false` moves no
+ * money, `api_restock` puts the stock back, and each line is the store's own order line for the variant.
+ */
+export async function recordRefund(client: WooClient, remoteId: string, input: ChannelRefundRecord): Promise<Result<{ remoteRefundId: string }, ChannelConnectorError>> {
+  const read = await client.get(`/wc/v3/orders/${encodeURIComponent(remoteId)}`, wooOrderSchema);
+  if (!read.ok) return read;
+  const order = read.value.data;
+  const currency = order.currency ?? client.credentials.currency;
+  if (!currency) return Err({ code: "WOO_CURRENCY_UNKNOWN", message: `Order ${remoteId} names no currency.`, retriable: false });
+  const decimals = client.credentials.priceDecimals;
+  const lineItems: Array<{ id: string; quantity: number; refund_total: string }> = [];
+  for (const line of input.lines) {
+    const storeLine = order.line_items.find((candidate) => (candidate.variation_id !== "0" ? candidate.variation_id : candidate.product_id) === line.externalVariantId);
+    if (!storeLine) return Err({ code: "CHANNEL_MAPPING_MISSING", message: `Order ${remoteId} has no line for ${line.externalVariantId}.`, retriable: false });
+    lineItems.push({ id: storeLine.id, quantity: line.quantity, refund_total: moneyString(line.amount, currency, decimals) });
+  }
+  // Delivery is refunded against the order's shipping item, as wp-admin does it.
+  const shippingAmount = input.shippingAmount ?? 0;
+  if (shippingAmount > 0) {
+    const shippingLine = order.shipping_lines[0];
+    if (!shippingLine) return Err({ code: "CHANNEL_MAPPING_MISSING", message: `Order ${remoteId} has no delivery line to refund.`, retriable: false });
+    lineItems.push({ id: shippingLine.id, quantity: 0, refund_total: moneyString(shippingAmount, currency, decimals) });
+  }
+  const created = await client.send("POST", `/wc/v3/orders/${encodeURIComponent(remoteId)}/refunds`, {
+    amount: moneyString(input.amount, currency, decimals),
+    reason: input.reason,
+    api_refund: false,
+    api_restock: input.restock,
+    line_items: lineItems,
+  }, z.object({ id: z.union([z.number(), z.string()]).transform(String) }));
+  if (!created.ok) return Err({ code: created.error.code, message: `The store would not record the refund: ${created.error.message}`, retriable: created.error.retriable === true });
+  return Ok({ remoteRefundId: created.value.id });
+}
+
 export async function orderStatus(client: WooClient, remoteId: string): Promise<Result<ChannelOrderStatus, ChannelConnectorError>> {
   const read = await client.get(`/wc/v3/orders/${encodeURIComponent(remoteId)}`, wooOrderSchema);
   if (!read.ok) return read;

package/src/webhooks.ts

@@ -97,6 +97,8 @@ const refundSchema = z.object({
   /** What the merchant refunded, positive, in the store's currency: part of a line is less than the line. */
   amount: z.string().nullish(),
   line_items: z.array(z.object({ product_id: id, variation_id: id, quantity: z.number() })).default([]),
+  /** Delivery refunded: one entry per order shipping item, total negative. */
+  shipping_lines: z.array(z.object({ total: z.string().nullish() })).default([]),
 });
 
 function meta(entries: Array<{ key: string; value: unknown }>, key: string): unknown {
@@ -175,6 +177,9 @@ export async function orderEvents(client: WooClient, remoteOrderId: string): Pro
     if (!refund.ok) return refund;
     const currency = order.currency ?? client.credentials.currency;
     const amount = currency ? toMinorUnits(refund.value.data.amount, currency) : undefined;
+    const shipping = currency
+      ? refund.value.data.shipping_lines.reduce((sum, line) => sum + Math.abs(toMinorUnits(line.total, currency) ?? 0), 0)
+      : 0;
     events.push({
       kind: "refund.created",
       remoteOrderId: order.id,
@@ -184,6 +189,7 @@ export async function orderEvents(client: WooClient, remoteOrderId: string): Pro
         return quantity > 0 ? [{ externalVariantId: line.variation_id !== "0" ? line.variation_id : line.product_id, quantity }] : [];
       }),
       ...(amount === undefined ? {} : { amount: Math.abs(amount) }),
+      ...(shipping > 0 ? { shippingAmount: shipping } : {}),
     });
   }
   return Ok(events);