@porulle/adapter-shopify 0.73.2 → 0.74.0

package/dist/webhooks.d.ts

@@ -0,0 +1,9 @@
+import type { ChannelConnectorError, ChannelEvent, ChannelWebhookEvent, Result } from "@porulle/core";
+import type { ShopifyGraphqlTarget } from "./graphql.js";
+/**
+ * A stock delivery names an INVENTORY ITEM and one location's count. The variant it belongs to and
+ * its stock summed over locations are read fresh, so the level applied is the store's, not the payload's.
+ */
+export declare const INVENTORY_ITEM_VARIANT_QUERY = "query PorulleInventoryItemVariant($id: ID!) {\n  inventoryItem(id: $id) { variant { legacyResourceId inventoryQuantity } }\n}";
+/** What one Shopify delivery means. `shop` is the store's Admin API, for the reads a nudge needs. */
+export declare function decodeShopifyWebhook(shop: ShopifyGraphqlTarget | undefined, event: ChannelWebhookEvent): Promise<Result<ChannelEvent[], ChannelConnectorError>>;

package/dist/webhooks.js

@@ -0,0 +1,131 @@
+import { Err, Ok } from "@porulle/core";
+import { z } from "zod";
+import { shopifyGid, shopifyGraphql } from "./graphql.js";
+/**
+ * A stock delivery names an INVENTORY ITEM and one location's count. The variant it belongs to and
+ * its stock summed over locations are read fresh, so the level applied is the store's, not the payload's.
+ */
+export const INVENTORY_ITEM_VARIANT_QUERY = `query PorulleInventoryItemVariant($id: ID!) {
+  inventoryItem(id: $id) { variant { legacyResourceId inventoryQuantity } }
+}`;
+const inventoryItemVariantSchema = z.object({
+    inventoryItem: z.object({ variant: z.object({ legacyResourceId: z.string(), inventoryQuantity: z.number().nullable() }).nullable() }).nullable(),
+});
+const id = z.union([z.string(), z.number()]).transform(String);
+const withId = z.object({ id });
+const inventoryLevelPayload = z.object({ inventory_item_id: id });
+const refundPayload = z.object({
+    id,
+    order_id: id,
+    refund_line_items: z.array(z.object({
+        quantity: z.number().int(),
+        line_item: z.object({ variant_id: id.nullish(), product_id: id.nullish() }),
+    })).default([]),
+});
+const fulfilledPayload = z.object({
+    id,
+    fulfillments: z.array(z.object({
+        id,
+        status: z.string().nullish(),
+        tracking_company: z.string().nullish(),
+        tracking_number: z.string().nullish(),
+        tracking_url: z.string().nullish(),
+        line_items: z.array(z.object({ variant_id: id.nullish(), quantity: z.number().int().positive() })).default([]),
+    })).default([]),
+});
+const RETURN_STATUS = {
+    "returns/approve": "approved",
+    "returns/decline": "declined",
+    "returns/close": "closed",
+    "returns/cancel": "cancelled",
+    "returns/reopen": "approved",
+};
+const COMPLIANCE = {
+    "customers/data_request": "customer_data",
+    "customers/redact": "customer_redact",
+    "shop/redact": "shop_redact",
+};
+function malformed(topic, error) {
+    return Err({ code: "SHOPIFY_WEBHOOK_MALFORMED", message: `A Shopify ${topic} delivery did not parse: ${error.message}`, retriable: false });
+}
+/** A parcel the store cancelled or failed is not a parcel. */
+function shipments(fulfillments) {
+    return fulfillments
+        .filter((parcel) => parcel.status !== "cancelled" && parcel.status !== "error" && parcel.status !== "failure")
+        .map((parcel) => ({
+        remoteId: parcel.id,
+        ...(parcel.tracking_company ? { carrier: parcel.tracking_company } : {}),
+        ...(parcel.tracking_number ? { trackingNumber: parcel.tracking_number } : {}),
+        ...(parcel.tracking_url ? { trackingUrl: parcel.tracking_url } : {}),
+        lines: parcel.line_items.flatMap((line) => (line.variant_id == null ? [] : [{ externalVariantId: line.variant_id, quantity: line.quantity }])),
+    }));
+}
+/** What one Shopify delivery means. `shop` is the store's Admin API, for the reads a nudge needs. */
+export async function decodeShopifyWebhook(shop, event) {
+    const topic = event.type;
+    const data = event.data;
+    if (topic === "products/create" || topic === "products/update" || topic === "products/delete") {
+        const parsed = withId.safeParse(data);
+        if (!parsed.success)
+            return malformed(topic, parsed.error);
+        return Ok([{ kind: topic === "products/delete" ? "product.deleted" : "product.changed", externalIds: [parsed.data.id] }]);
+    }
+    if (topic === "inventory_levels/update") {
+        const parsed = inventoryLevelPayload.safeParse(data);
+        if (!parsed.success)
+            return malformed(topic, parsed.error);
+        if (!shop)
+            return Err({ code: "SHOPIFY_CREDENTIALS_REQUIRED", message: "The store holds no Shopify access token; it must be reconnected.", retriable: false });
+        const read = await shopifyGraphql(shop, INVENTORY_ITEM_VARIANT_QUERY, { id: shopifyGid("InventoryItem", parsed.data.inventory_item_id) }, inventoryItemVariantSchema);
+        if (!read.ok)
+            return read;
+        const variant = read.value.inventoryItem?.variant;
+        // An item no variant carries (deleted between the delivery and the read) has no level to apply.
+        if (!variant)
+            return Ok([]);
+        return Ok([{ kind: "inventory.changed", levels: [{ externalId: variant.legacyResourceId, available: Math.max(0, variant.inventoryQuantity ?? 0) }] }]);
+    }
+    if (topic === "orders/cancelled") {
+        const parsed = withId.safeParse(data);
+        if (!parsed.success)
+            return malformed(topic, parsed.error);
+        return Ok([{ kind: "order.cancelled", remoteOrderId: parsed.data.id }]);
+    }
+    if (topic === "orders/fulfilled" || topic === "orders/partially_fulfilled") {
+        const parsed = fulfilledPayload.safeParse(data);
+        if (!parsed.success)
+            return malformed(topic, parsed.error);
+        return Ok([{ kind: "order.fulfilled", remoteOrderId: parsed.data.id, partial: topic === "orders/partially_fulfilled", shipments: shipments(parsed.data.fulfillments) }]);
+    }
+    if (topic === "refunds/create") {
+        const parsed = refundPayload.safeParse(data);
+        if (!parsed.success)
+            return malformed(topic, parsed.error);
+        return Ok([{
+                kind: "refund.created",
+                remoteOrderId: parsed.data.order_id,
+                remoteRefundId: parsed.data.id,
+                lines: parsed.data.refund_line_items.flatMap((entry) => {
+                    const externalVariantId = entry.line_item.variant_id ?? entry.line_item.product_id;
+                    return externalVariantId == null ? [] : [{ externalVariantId, quantity: entry.quantity }];
+                }),
+            }]);
+    }
+    const returnStatus = RETURN_STATUS[topic];
+    if (returnStatus !== undefined) {
+        const parsed = withId.safeParse(data);
+        if (!parsed.success)
+            return malformed(topic, parsed.error);
+        return Ok([{ kind: "return.updated", remoteReturnId: parsed.data.id, status: returnStatus }]);
+    }
+    if (topic === "app/uninstalled")
+        return Ok([{ kind: "connection.revoked" }]);
+    const compliance = COMPLIANCE[topic];
+    if (compliance !== undefined) {
+        const parsed = z.record(z.string(), z.unknown()).safeParse(data);
+        if (!parsed.success)
+            return malformed(topic, parsed.error);
+        return Ok([{ kind: "compliance.request", request: compliance, data: parsed.data }]);
+    }
+    return Ok([]);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@porulle/adapter-shopify",
-  "version": "0.73.2",
+  "version": "0.74.0",
   "license": "MIT",
   "type": "module",
   "exports": {
@@ -16,7 +16,7 @@
   },
   "dependencies": {
     "zod": "^4.1.11",
-    "@porulle/core": "0.73.2"
+    "@porulle/core": "0.74.0"
   },
   "devDependencies": {
     "@types/node": "^24.5.2",
@@ -26,8 +26,8 @@
     "miniflare": "4.20260722.1",
     "typescript": "5.9.2",
     "vitest": "^3.2.4",
-    "@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/graphql.ts

@@ -127,6 +127,6 @@ export async function shopifyGraphql<T>(
 }
 
 /** `gid://shopify/<Type>/<id>` for a numeric id; the adapter keys everything by the numeric id. */
-export function shopifyGid(type: "Product" | "ProductVariant", id: string): string {
+export function shopifyGid(type: "Product" | "ProductVariant" | "InventoryItem" | "Order", id: string): string {
   return `gid://shopify/${type}/${id}`;
 }

package/src/index.ts

@@ -13,6 +13,7 @@ import type {
 } from "@porulle/core";
 import { z } from "zod";
 import { readCatalogItems, readCatalogPage } from "./catalog.js";
+import { decodeShopifyWebhook } from "./webhooks.js";
 import { shopifyGid, shopifyGraphql } from "./graphql.js";
 import type { ShopifyGraphqlTarget } from "./graphql.js";
 import {
@@ -27,6 +28,7 @@ import {
 
 export { SHOPIFY_API_VERSION } from "./graphql.js";
 export { CATALOG_ITEMS_QUERY, CATALOG_PAGE_QUERY, VARIANTS_PAGE_QUERY } from "./catalog.js";
+export { INVENTORY_ITEM_VARIANT_QUERY } from "./webhooks.js";
 export { REQUIRED_SCOPES, normalizeShopDomain, parseShopifyCredentials } from "./oauth.js";
 export type { ShopifyCredentials } from "./oauth.js";
 
@@ -326,7 +328,9 @@ export function shopifyConnector(options: ShopifyConnectorOptions): ChannelConne
       }, orderCreateSchema);
       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) {
@@ -415,6 +419,9 @@ export function shopifyConnector(options: ShopifyConnectorOptions): ChannelConne
       }
       return Ok({ id, topic, shopDomain, data });
     },
+    async decodeWebhook(store, event) {
+      return decodeShopifyWebhook(target(store), event);
+    },
     async refundExecute() {
       return Err({ code: "NOT_IMPLEMENTED", message: "Refunds are issued by the platform, not executed in the Shopify store." });
     },

package/src/webhooks.ts

@@ -0,0 +1,130 @@
+import { Err, Ok } from "@porulle/core";
+import type { ChannelConnectorError, ChannelEvent, ChannelShipment, ChannelWebhookEvent, Result } from "@porulle/core";
+import { z } from "zod";
+import { shopifyGid, shopifyGraphql } from "./graphql.js";
+import type { ShopifyGraphqlTarget } from "./graphql.js";
+
+/**
+ * A stock delivery names an INVENTORY ITEM and one location's count. The variant it belongs to and
+ * its stock summed over locations are read fresh, so the level applied is the store's, not the payload's.
+ */
+export const INVENTORY_ITEM_VARIANT_QUERY = `query PorulleInventoryItemVariant($id: ID!) {
+  inventoryItem(id: $id) { variant { legacyResourceId inventoryQuantity } }
+}`;
+
+const inventoryItemVariantSchema = z.object({
+  inventoryItem: z.object({ variant: z.object({ legacyResourceId: z.string(), inventoryQuantity: z.number().nullable() }).nullable() }).nullable(),
+});
+
+const id = z.union([z.string(), z.number()]).transform(String);
+const withId = z.object({ id });
+const inventoryLevelPayload = z.object({ inventory_item_id: id });
+const refundPayload = z.object({
+  id,
+  order_id: id,
+  refund_line_items: z.array(z.object({
+    quantity: z.number().int(),
+    line_item: z.object({ variant_id: id.nullish(), product_id: id.nullish() }),
+  })).default([]),
+});
+const fulfilledPayload = z.object({
+  id,
+  fulfillments: z.array(z.object({
+    id,
+    status: z.string().nullish(),
+    tracking_company: z.string().nullish(),
+    tracking_number: z.string().nullish(),
+    tracking_url: z.string().nullish(),
+    line_items: z.array(z.object({ variant_id: id.nullish(), quantity: z.number().int().positive() })).default([]),
+  })).default([]),
+});
+
+const RETURN_STATUS: Record<string, Extract<ChannelEvent, { kind: "return.updated" }>["status"]> = {
+  "returns/approve": "approved",
+  "returns/decline": "declined",
+  "returns/close": "closed",
+  "returns/cancel": "cancelled",
+  "returns/reopen": "approved",
+};
+
+const COMPLIANCE: Record<string, Extract<ChannelEvent, { kind: "compliance.request" }>["request"]> = {
+  "customers/data_request": "customer_data",
+  "customers/redact": "customer_redact",
+  "shop/redact": "shop_redact",
+};
+
+function malformed(topic: string, error: z.ZodError): Result<never, ChannelConnectorError> {
+  return Err({ code: "SHOPIFY_WEBHOOK_MALFORMED", message: `A Shopify ${topic} delivery did not parse: ${error.message}`, retriable: false });
+}
+
+/** A parcel the store cancelled or failed is not a parcel. */
+function shipments(fulfillments: z.infer<typeof fulfilledPayload>["fulfillments"]): ChannelShipment[] {
+  return fulfillments
+    .filter((parcel) => parcel.status !== "cancelled" && parcel.status !== "error" && parcel.status !== "failure")
+    .map((parcel) => ({
+      remoteId: parcel.id,
+      ...(parcel.tracking_company ? { carrier: parcel.tracking_company } : {}),
+      ...(parcel.tracking_number ? { trackingNumber: parcel.tracking_number } : {}),
+      ...(parcel.tracking_url ? { trackingUrl: parcel.tracking_url } : {}),
+      lines: parcel.line_items.flatMap((line) => (line.variant_id == null ? [] : [{ externalVariantId: line.variant_id, quantity: line.quantity }])),
+    }));
+}
+
+/** What one Shopify delivery means. `shop` is the store's Admin API, for the reads a nudge needs. */
+export async function decodeShopifyWebhook(shop: ShopifyGraphqlTarget | undefined, event: ChannelWebhookEvent): Promise<Result<ChannelEvent[], ChannelConnectorError>> {
+  const topic = event.type;
+  const data = event.data;
+  if (topic === "products/create" || topic === "products/update" || topic === "products/delete") {
+    const parsed = withId.safeParse(data);
+    if (!parsed.success) return malformed(topic, parsed.error);
+    return Ok([{ kind: topic === "products/delete" ? "product.deleted" : "product.changed", externalIds: [parsed.data.id] }]);
+  }
+  if (topic === "inventory_levels/update") {
+    const parsed = inventoryLevelPayload.safeParse(data);
+    if (!parsed.success) return malformed(topic, parsed.error);
+    if (!shop) return Err({ code: "SHOPIFY_CREDENTIALS_REQUIRED", message: "The store holds no Shopify access token; it must be reconnected.", retriable: false });
+    const read = await shopifyGraphql(shop, INVENTORY_ITEM_VARIANT_QUERY, { id: shopifyGid("InventoryItem", parsed.data.inventory_item_id) }, inventoryItemVariantSchema);
+    if (!read.ok) return read;
+    const variant = read.value.inventoryItem?.variant;
+    // An item no variant carries (deleted between the delivery and the read) has no level to apply.
+    if (!variant) return Ok([]);
+    return Ok([{ kind: "inventory.changed", levels: [{ externalId: variant.legacyResourceId, available: Math.max(0, variant.inventoryQuantity ?? 0) }] }]);
+  }
+  if (topic === "orders/cancelled") {
+    const parsed = withId.safeParse(data);
+    if (!parsed.success) return malformed(topic, parsed.error);
+    return Ok([{ kind: "order.cancelled", remoteOrderId: parsed.data.id }]);
+  }
+  if (topic === "orders/fulfilled" || topic === "orders/partially_fulfilled") {
+    const parsed = fulfilledPayload.safeParse(data);
+    if (!parsed.success) return malformed(topic, parsed.error);
+    return Ok([{ kind: "order.fulfilled", remoteOrderId: parsed.data.id, partial: topic === "orders/partially_fulfilled", shipments: shipments(parsed.data.fulfillments) }]);
+  }
+  if (topic === "refunds/create") {
+    const parsed = refundPayload.safeParse(data);
+    if (!parsed.success) return malformed(topic, parsed.error);
+    return Ok([{
+      kind: "refund.created",
+      remoteOrderId: parsed.data.order_id,
+      remoteRefundId: parsed.data.id,
+      lines: parsed.data.refund_line_items.flatMap((entry) => {
+        const externalVariantId = entry.line_item.variant_id ?? entry.line_item.product_id;
+        return externalVariantId == null ? [] : [{ externalVariantId, quantity: entry.quantity }];
+      }),
+    }]);
+  }
+  const returnStatus = RETURN_STATUS[topic];
+  if (returnStatus !== undefined) {
+    const parsed = withId.safeParse(data);
+    if (!parsed.success) return malformed(topic, parsed.error);
+    return Ok([{ kind: "return.updated", remoteReturnId: parsed.data.id, status: returnStatus }]);
+  }
+  if (topic === "app/uninstalled") return Ok([{ kind: "connection.revoked" }]);
+  const compliance = COMPLIANCE[topic];
+  if (compliance !== undefined) {
+    const parsed = z.record(z.string(), z.unknown()).safeParse(data);
+    if (!parsed.success) return malformed(topic, parsed.error);
+    return Ok([{ kind: "compliance.request", request: compliance, data: parsed.data }]);
+  }
+  return Ok([]);
+}