@porulle/adapter-shopify 0.73.0 → 0.73.2

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() })) }),
 });
@@ -320,6 +336,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 +352,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)

package/dist/oauth.d.ts

@@ -12,8 +12,10 @@ import type { ChannelConnectorError, Result } from "@porulle/core";
  * - `read_inventory`: variant stock and the inventory item behind a stock webhook.
  * - `write_orders`: a paid platform order is created in the store (`orderCreate`). A write scope
  *   includes its read scope, which `orders/fulfilled` and `orders/cancelled` need.
+ * - `read_returns`, `write_returns`: a shopper's return is asked of the store (`returnRequest`) and
+ *   its `returns/*` webhooks say how the store answered.
  */
-export declare const REQUIRED_SCOPES: readonly ["read_products", "write_products", "read_inventory", "write_orders"];
+export declare const REQUIRED_SCOPES: readonly ["read_products", "write_products", "read_inventory", "write_orders", "read_returns", "write_returns"];
 /** Refresh this long before Shopify's stated expiry, so a call never starts on a token about to lapse. */
 export declare const ACCESS_TOKEN_REFRESH_MARGIN_MS: number;
 /** What the store row holds. Read back with {@link parseShopifyCredentials}; never cast. */

package/dist/oauth.js

@@ -14,8 +14,10 @@ import { z } from "zod";
  * - `read_inventory`: variant stock and the inventory item behind a stock webhook.
  * - `write_orders`: a paid platform order is created in the store (`orderCreate`). A write scope
  *   includes its read scope, which `orders/fulfilled` and `orders/cancelled` need.
+ * - `read_returns`, `write_returns`: a shopper's return is asked of the store (`returnRequest`) and
+ *   its `returns/*` webhooks say how the store answered.
  */
-export const REQUIRED_SCOPES = ["read_products", "write_products", "read_inventory", "write_orders"];
+export const REQUIRED_SCOPES = ["read_products", "write_products", "read_inventory", "write_orders", "read_returns", "write_returns"];
 /** Refresh this long before Shopify's stated expiry, so a call never starts on a token about to lapse. */
 export const ACCESS_TOKEN_REFRESH_MARGIN_MS = 5 * 60 * 1000;
 const credentialsSchema = z.object({