@porulle/adapter-woocommerce 0.75.0 → 0.76.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@porulle/adapter-woocommerce",
-  "version": "0.75.0",
+  "version": "0.76.0",
   "license": "MIT",
   "type": "module",
   "exports": {
@@ -16,7 +16,7 @@
   },
   "dependencies": {
     "zod": "^4.1.11",
-    "@porulle/core": "0.75.0"
+    "@porulle/core": "0.76.0"
   },
   "devDependencies": {
     "@types/node": "^24.5.2",
@@ -25,8 +25,8 @@
     "vitest": "^3.2.4",
     "esbuild": "0.25.12",
     "miniflare": "4.20260722.1",
-    "@porulle/typescript-config": "0.1.0",
-    "@porulle/eslint-config": "0.1.0"
+    "@porulle/eslint-config": "0.1.0",
+    "@porulle/typescript-config": "0.1.0"
   },
   "publishConfig": {
     "access": "public"

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;