@porulle/adapter-woocommerce 0.74.5 → 0.76.0

package/dist/webhooks.js

@@ -1,5 +1,5 @@
 import { createHash, createHmac, timingSafeEqual } from "node:crypto";
-import { Err, Ok } from "@porulle/core";
+import { Err, Ok, toMinorUnits } from "@porulle/core";
 import { z } from "zod";
 import { wooProductSchema, wooVariationSchema } from "./catalog.js";
 import { available } from "./inventory.js";
@@ -93,6 +93,8 @@ const trackingItem = z.object({
 });
 const refundSchema = z.object({
     id,
+    /** 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([]),
 });
 function meta(entries, key) {
@@ -176,6 +178,8 @@ export async function orderEvents(client, remoteOrderId) {
         const refund = await client.get(`/wc/v3/orders/${encodeURIComponent(order.id)}/refunds/${encodeURIComponent(summary.id)}`, refundSchema);
         if (!refund.ok)
             return refund;
+        const currency = order.currency ?? client.credentials.currency;
+        const amount = currency ? toMinorUnits(refund.value.data.amount, currency) : undefined;
         events.push({
             kind: "refund.created",
             remoteOrderId: order.id,
@@ -184,6 +188,7 @@ export async function orderEvents(client, remoteOrderId) {
                 const quantity = Math.abs(line.quantity);
                 return quantity > 0 ? [{ externalVariantId: line.variation_id !== "0" ? line.variation_id : line.product_id, quantity }] : [];
             }),
+            ...(amount === undefined ? {} : { amount: Math.abs(amount) }),
         });
     }
     return Ok(events);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@porulle/adapter-woocommerce",
-  "version": "0.74.5",
+  "version": "0.76.0",
   "license": "MIT",
   "type": "module",
   "exports": {
@@ -16,7 +16,7 @@
   },
   "dependencies": {
     "zod": "^4.1.11",
-    "@porulle/core": "0.74.5"
+    "@porulle/core": "0.76.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";
@@ -200,6 +200,34 @@ 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) });
+  }
+  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

@@ -1,5 +1,5 @@
 import { createHash, createHmac, timingSafeEqual } from "node:crypto";
-import { Err, Ok } from "@porulle/core";
+import { Err, Ok, toMinorUnits } from "@porulle/core";
 import type { ChannelConnectorError, ChannelEvent, ChannelShipment, ChannelStore, ChannelWebhookEvent, ChannelWebhookHealth, Result } from "@porulle/core";
 import { z } from "zod";
 import { wooProductSchema, wooVariationSchema } from "./catalog.js";
@@ -94,6 +94,8 @@ const trackingItem = z.object({
 });
 const refundSchema = z.object({
   id,
+  /** 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([]),
 });
 
@@ -171,6 +173,8 @@ export async function orderEvents(client: WooClient, remoteOrderId: string): Pro
   for (const summary of order.refunds) {
     const refund = await client.get(`/wc/v3/orders/${encodeURIComponent(order.id)}/refunds/${encodeURIComponent(summary.id)}`, refundSchema);
     if (!refund.ok) return refund;
+    const currency = order.currency ?? client.credentials.currency;
+    const amount = currency ? toMinorUnits(refund.value.data.amount, currency) : undefined;
     events.push({
       kind: "refund.created",
       remoteOrderId: order.id,
@@ -179,6 +183,7 @@ export async function orderEvents(client: WooClient, remoteOrderId: string): Pro
         const quantity = Math.abs(line.quantity);
         return quantity > 0 ? [{ externalVariantId: line.variation_id !== "0" ? line.variation_id : line.product_id, quantity }] : [];
       }),
+      ...(amount === undefined ? {} : { amount: Math.abs(amount) }),
     });
   }
   return Ok(events);