@porulle/adapter-shopify 0.72.0 → 0.73.1

package/dist/index.d.ts

@@ -24,6 +24,9 @@ export declare const ORDER_CREATE_MUTATION = "mutation PorulleOrderCreate($order
  * took the payment, so it refunds and it writes to the shopper.
  */
 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}";
+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}";
 export declare function shopifyConnector(options: ShopifyConnectorOptions): ChannelConnector;

package/dist/index.js

@@ -26,6 +26,13 @@ export const ORDER_CREATE_MUTATION = `mutation PorulleOrderCreate($order: OrderC
 export const ORDER_CANCEL_MUTATION = `mutation PorulleOrderCancel($orderId: ID!, $reason: OrderCancelReason!, $staffNote: String) {
   orderCancel(orderId: $orderId, reason: $reason, restock: true, notifyCustomer: false, staffNote: $staffNote) { orderCancelUserErrors { code message } }
 }`;
+/** The order's shipped lines: a return names what it takes back by fulfilment line, not order line. */
+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 } } } } } }
+}`;
+export const RETURN_REQUEST_MUTATION = `mutation PorulleReturnRequest($input: ReturnRequestInput!) {
+  returnRequest(input: $input) { return { id } userErrors { code message } }
+}`;
 export const ORDER_BY_SOURCE_QUERY = `query PorulleOrderBySource($query: String!) {
   orders(first: 1, query: $query) { nodes { legacyResourceId } }
 }`;
@@ -57,6 +64,16 @@ const CANCEL_REASON = {
     staff: "STAFF",
     other: "OTHER",
 };
+const fulfillmentLinesSchema = z.object({
+    order: z.object({
+        fulfillments: z.array(z.object({
+            fulfillmentLineItems: z.object({ nodes: z.array(z.object({ id: z.string(), quantity: z.number(), lineItem: z.object({ variant: z.object({ legacyResourceId: z.string() }).nullable() }) })) }),
+        })),
+    }).nullable(),
+});
+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() })) }),
+});
 const orderBySourceSchema = z.object({ orders: z.object({ nodes: z.array(z.object({ legacyResourceId: z.string() })) }) });
 const orderStatusSchema = z.object({
     order: z.object({ cancelledAt: z.string().nullable(), displayFinancialStatus: z.string().nullable(), displayFulfillmentStatus: z.string() }).nullable(),
@@ -295,6 +312,37 @@ export function shopifyConnector(options) {
                 return Ok(undefined);
             return Err({ code: CHANNEL_CANCEL_REFUSED, message: `Shopify refused to cancel the order: ${refusals.map((error) => error.message).join("; ")}.`, retriable: false });
         },
+        async requestReturn(store, remoteOrderId, input) {
+            const shop = target(store);
+            if (!shop)
+                return Err(credentialsRequired);
+            const shipped = await shopifyGraphql(shop, ORDER_FULFILLMENT_LINES_QUERY, { id: `gid://shopify/Order/${remoteOrderId}` }, fulfillmentLinesSchema);
+            if (!shipped.ok)
+                return shipped;
+            const fulfilmentLines = (shipped.value.order?.fulfillments ?? []).flatMap((fulfillment) => fulfillment.fulfillmentLineItems.nodes);
+            const returnLineItems = [];
+            const note = [input.reason, input.note].filter((part) => part !== undefined && part !== "").join(" — ").slice(0, 300);
+            for (const wanted of input.lines) {
+                let remaining = wanted.quantity;
+                for (const line of fulfilmentLines.filter((candidate) => candidate.lineItem.variant?.legacyResourceId === wanted.externalVariantId)) {
+                    if (remaining === 0)
+                        break;
+                    const take = Math.min(remaining, line.quantity);
+                    returnLineItems.push({ fulfillmentLineItemId: line.id, quantity: take, customerNote: note });
+                    remaining -= take;
+                }
+                if (remaining > 0)
+                    return Err({ code: "SHOPIFY_RETURN_NOT_SHIPPED", message: `Shopify has not shipped ${remaining} of variant ${wanted.externalVariantId}, so it cannot take them back.`, retriable: false });
+            }
+            const requested = await shopifyGraphql(shop, RETURN_REQUEST_MUTATION, { input: { orderId: `gid://shopify/Order/${remoteOrderId}`, returnLineItems } }, returnRequestSchema);
+            if (!requested.ok)
+                return requested;
+            const { return: created, userErrors } = requested.value.returnRequest;
+            if (userErrors.length > 0 || !created) {
+                return Err({ code: "SHOPIFY_RETURN_REFUSED", message: `Shopify refused the return: ${userErrors.map((error) => error.message).join("; ") || "no return created"}.`, retriable: false });
+            }
+            return Ok({ remoteReturnId: created.id.split("/").pop() ?? created.id });
+        },
         /**
          * Every Shopify delivery — catalogue, stock, orders, uninstall and the mandatory compliance topics —
          * arrives at ONE app-level address declared in `shopify.app.toml`, signed with the app's client

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({