@porulle/adapter-shopify 0.73.1 → 0.73.3

package/dist/index.d.ts

@@ -26,6 +26,11 @@ export declare const ORDER_CREATE_MUTATION = "mutation PorulleOrderCreate($order
 export declare const ORDER_CANCEL_MUTATION = "mutation PorulleOrderCancel($orderId: ID!, $reason: OrderCancelReason!, $staffNote: String) {\n  orderCancel(orderId: $orderId, reason: $reason, restock: true, notifyCustomer: false, staffNote: $staffNote) { orderCancelUserErrors { code message } }\n}";
 /** The order's shipped lines: a return names what it takes back by fulfilment line, not order line. */
 export declare const ORDER_FULFILLMENT_LINES_QUERY = "query PorulleOrderFulfillmentLines($id: ID!) {\n  order(id: $id) { fulfillments(first: 20) { fulfillmentLineItems(first: 50) { nodes { id quantity lineItem { variant { legacyResourceId } } } } } }\n}";
+/**
+ * Shopify's reason library, by handle. Live Shopify refuses a return line with no reason ("Return reason
+ * can't be blank") although the schema marks both reason fields optional.
+ */
+export declare const RETURN_REASON_QUERY = "query PorulleReturnReasons($handles: [String!]) {\n  returnReasonDefinitions(first: 2, handles: $handles) { nodes { id handle } }\n}";
 export declare const RETURN_REQUEST_MUTATION = "mutation PorulleReturnRequest($input: ReturnRequestInput!) {\n  returnRequest(input: $input) { return { id } userErrors { code message } }\n}";
 export declare const ORDER_BY_SOURCE_QUERY = "query PorulleOrderBySource($query: String!) {\n  orders(first: 1, query: $query) { nodes { legacyResourceId } }\n}";
 export declare const ORDER_STATUS_QUERY = "query PorulleOrderStatus($id: ID!) {\n  order(id: $id) { cancelledAt displayFinancialStatus displayFulfillmentStatus }\n}";

package/dist/index.js

@@ -30,6 +30,19 @@ export const ORDER_CANCEL_MUTATION = `mutation PorulleOrderCancel($orderId: ID!,
 export const ORDER_FULFILLMENT_LINES_QUERY = `query PorulleOrderFulfillmentLines($id: ID!) {
   order(id: $id) { fulfillments(first: 20) { fulfillmentLineItems(first: 50) { nodes { id quantity lineItem { variant { legacyResourceId } } } } } }
 }`;
+/**
+ * Shopify's reason library, by handle. Live Shopify refuses a return line with no reason ("Return reason
+ * can't be blank") although the schema marks both reason fields optional.
+ */
+export const RETURN_REASON_QUERY = `query PorulleReturnReasons($handles: [String!]) {
+  returnReasonDefinitions(first: 2, handles: $handles) { nodes { id handle } }
+}`;
+/** Shopify's catch-all, for a reason its library has no handle for. */
+const OTHER_RETURN_REASON = "other-reason";
+/** "Too small" → "too-small": Shopify's handles are its reason names, lower-cased and hyphenated. */
+function returnReasonHandle(reason) {
+    return reason.trim().toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
+}
 export const RETURN_REQUEST_MUTATION = `mutation PorulleReturnRequest($input: ReturnRequestInput!) {
   returnRequest(input: $input) { return { id } userErrors { code message } }
 }`;
@@ -71,6 +84,9 @@ const fulfillmentLinesSchema = z.object({
         })),
     }).nullable(),
 });
+const returnReasonSchema = z.object({
+    returnReasonDefinitions: z.object({ nodes: z.array(z.object({ id: z.string(), handle: z.string() })) }),
+});
 const returnRequestSchema = z.object({
     returnRequest: z.object({ return: z.object({ id: z.string() }).nullable(), userErrors: z.array(z.object({ code: z.string().nullable(), message: z.string() })) }),
 });
@@ -272,7 +288,9 @@ export function shopifyConnector(options) {
             if (!created.ok)
                 return created;
             const { order, userErrors } = created.value.orderCreate;
-            if (userErrors.some((error) => error.code === "INVENTORY_CLAIM_FAILED")) {
+            // Live Shopify (2026-10, measured) refuses stock as `INVALID` on `["order","lineItems"]` with "Line items
+            // Unable to reserve inventory", not the documented `INVENTORY_CLAIM_FAILED`; both are read as out of stock.
+            if (userErrors.some((error) => error.code === "INVENTORY_CLAIM_FAILED" || /unable to reserve inventory/i.test(error.message))) {
                 return Err({ code: CHANNEL_OUT_OF_STOCK, message: `The store does not have the stock: ${userErrors.map((error) => error.message).join("; ")}.`, retriable: false });
             }
             if (userErrors.length > 0 || !order) {
@@ -320,6 +338,14 @@ export function shopifyConnector(options) {
             if (!shipped.ok)
                 return shipped;
             const fulfilmentLines = (shipped.value.order?.fulfillments ?? []).flatMap((fulfillment) => fulfillment.fulfillmentLineItems.nodes);
+            const handle = returnReasonHandle(input.reason);
+            const reasons = await shopifyGraphql(shop, RETURN_REASON_QUERY, { handles: [handle, OTHER_RETURN_REASON] }, returnReasonSchema);
+            if (!reasons.ok)
+                return reasons;
+            const definitions = reasons.value.returnReasonDefinitions.nodes;
+            const reason = definitions.find((definition) => definition.handle === handle) ?? definitions.find((definition) => definition.handle === OTHER_RETURN_REASON);
+            if (!reason)
+                return Err({ code: "SHOPIFY_RETURN_REASON_MISSING", message: `Shopify has no return reason "${handle}" and no "${OTHER_RETURN_REASON}".`, retriable: false });
             const returnLineItems = [];
             const note = [input.reason, input.note].filter((part) => part !== undefined && part !== "").join(" — ").slice(0, 300);
             for (const wanted of input.lines) {
@@ -328,7 +354,7 @@ export function shopifyConnector(options) {
                     if (remaining === 0)
                         break;
                     const take = Math.min(remaining, line.quantity);
-                    returnLineItems.push({ fulfillmentLineItemId: line.id, quantity: take, customerNote: note });
+                    returnLineItems.push({ fulfillmentLineItemId: line.id, quantity: take, customerNote: note, returnReasonDefinitionId: reason.id });
                     remaining -= take;
                 }
                 if (remaining > 0)