shopify_storefront_sdk 1.0.4 → 2.0.0

package/dist/client/client.js

@@ -1,31 +1,121 @@
-import axios from "axios";
+import * as crypto from "node:crypto";
+import { ShopifyNetworkError, ShopifyGraphQLError, ShopifyInvalidRequestError, ShopifyUserError } from "../utils/errors.js";
 class ShopifyClient {
     endpoint;
     token;
-    constructor({ storeUrl, storefrontToken }) {
-        if (!storeUrl?.includes(".myshopify.com")) {
-            throw new Error(`The store url ${storeUrl} is not supported by shopify`);
+    maxRetries;
+    cache;
+    cacheTtl;
+    constructor({ storeUrl, storefrontToken, apiVersion = "2025-01", maxRetries = 3, cache, defaultCacheTtl = 60 }) {
+        if (!storeUrl || !storeUrl.includes(".myshopify.com")) {
+            throw new ShopifyInvalidRequestError(`The store URL "${storeUrl}" is invalid or not supported by Shopify.`);
         }
-        (this.endpoint = `https://${storeUrl}/api/2025-04/graphql.json`),
-            (this.token = storefrontToken);
+        if (!storefrontToken) {
+            throw new ShopifyInvalidRequestError("A valid storefront access token must be provided.");
+        }
+        this.endpoint = `https://${storeUrl}/api/${apiVersion}/graphql.json`;
+        this.token = storefrontToken;
+        this.maxRetries = maxRetries;
+        this.cache = cache;
+        this.cacheTtl = defaultCacheTtl;
+    }
+    /**
+     * Generates a deterministic hash for a GraphQL query and its variables.
+     */
+    generateCacheKey(query, variables) {
+        return crypto.createHash("sha256").update(query + JSON.stringify(variables || {})).digest("hex");
     }
     async query(query, variables = {}) {
-        try {
-            const res = await axios.post(this.endpoint, {
-                query,
-                variables,
-            }, {
-                headers: {
-                    "X-Shopify-Storefront-Access-Token": this.token,
-                    "Content-Type": "application/json",
-                },
-            });
-            if (res.data?.errors)
-                throw new Error(JSON.stringify(res.data.errors, null, 2));
-            return res.data?.data;
+        const isMutation = query.trim().startsWith("mutation");
+        let cacheKey = "";
+        // 1. Check Cache (Only for Queries, never Mutations)
+        if (this.cache && !isMutation) {
+            cacheKey = this.generateCacheKey(query, variables);
+            const cachedResponse = await this.cache.get(cacheKey);
+            if (cachedResponse) {
+                return cachedResponse;
+            }
         }
-        catch (error) {
-            throw new Error(`Shopify Error: ${error.message}`);
+        let attempt = 0;
+        while (attempt <= this.maxRetries) {
+            try {
+                const res = await fetch(this.endpoint, {
+                    method: "POST",
+                    headers: {
+                        "X-Shopify-Storefront-Access-Token": this.token,
+                        "Content-Type": "application/json",
+                    },
+                    body: JSON.stringify({
+                        query,
+                        variables,
+                    })
+                });
+                if (!res.ok) {
+                    // Handle Rate Limits (429) or Server Errors (503) by throwing so we can retry
+                    if (res.status === 429 || res.status === 503) {
+                        throw new ShopifyNetworkError(`Shopify returned HTTP ${res.status}: Rate Limited or Service Unavailable`);
+                    }
+                    // Handle other HTTP errors
+                    if (res.status >= 400 && res.status < 500) {
+                        throw new ShopifyInvalidRequestError(`Shopify returned a client error: HTTP ${res.status}`);
+                    }
+                    throw new ShopifyNetworkError(`Shopify Server Error: HTTP ${res.status}`);
+                }
+                const data = await res.json();
+                // 2. Handle top-level GraphQL Errors
+                if (data?.errors && data.errors.length > 0) {
+                    throw new ShopifyGraphQLError(data.errors[0]?.message || "GraphQL API returned errors", data.errors);
+                }
+                // 3. Scan for nested User Errors (commonly found in mutations)
+                if (data?.data) {
+                    this.checkForUserErrors(data.data);
+                }
+                // 4. Save to Cache
+                if (this.cache && !isMutation && data?.data) {
+                    await this.cache.set(cacheKey, data.data, this.cacheTtl);
+                }
+                return data?.data;
+            }
+            catch (error) {
+                // If it's a structural/GraphQL/User error, or a 4xx error (except 429), re-throw immediately.
+                if (error instanceof ShopifyGraphQLError ||
+                    error instanceof ShopifyInvalidRequestError ||
+                    error instanceof ShopifyUserError) {
+                    throw error;
+                }
+                // If it's a network error or 429/503 and we have retries left, wait and retry.
+                if (attempt < this.maxRetries) {
+                    attempt++;
+                    // Exponential backoff: 500ms, 1000ms, 2000ms...
+                    const backoff = Math.pow(2, attempt) * 500;
+                    await new Promise(r => setTimeout(r, backoff));
+                    continue;
+                }
+                // Out of retries or unexpected error
+                throw new ShopifyNetworkError(`Network Error: ${error.message}`);
+            }
+        }
+        throw new ShopifyNetworkError("Maximum retries exceeded");
+    }
+    /**
+     * Helper function to recursively check for `userErrors` inside the GraphQL response data.
+     */
+    checkForUserErrors(data) {
+        if (!data || typeof data !== "object")
+            return;
+        for (const key of Object.keys(data)) {
+            const value = data[key];
+            if (value && typeof value === "object") {
+                if ("userErrors" in value && Array.isArray(value.userErrors) && value.userErrors.length > 0) {
+                    throw new ShopifyUserError(value.userErrors[0]?.message || "A user error occurred during the mutation", value.userErrors);
+                }
+                else if ("customerUserErrors" in value && Array.isArray(value.customerUserErrors) && value.customerUserErrors.length > 0) {
+                    throw new ShopifyUserError(value.customerUserErrors[0]?.message || "A customer user error occurred", value.customerUserErrors);
+                }
+                else {
+                    this.checkForUserErrors(value);
+                }
+            }
         }
     }
 }

package/dist/client/client.js.map

@@ -1 +1 @@
-{"version":3,"file":"client.js","sourceRoot":"","sources":["../../src/client/client.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,MAAM,OAAO,CAAC;AAE1B,MAAM,aAAa;IACT,QAAQ,CAAC;IACT,KAAK,CAAC;IACd,YAAY,EAAE,QAAQ,EAAE,eAAe,EAAe;QACpD,IAAI,CAAC,QAAQ,EAAE,QAAQ,CAAC,gBAAgB,CAAC,EAAE,CAAC;YAC1C,MAAM,IAAI,KAAK,CAAC,iBAAiB,QAAQ,8BAA8B,CAAC,CAAC;QAC3E,CAAC;QACD,CAAC,IAAI,CAAC,QAAQ,GAAG,WAAW,QAAQ,2BAA2B,CAAC;YAC9D,CAAC,IAAI,CAAC,KAAK,GAAG,eAAe,CAAC,CAAC;IACnC,CAAC;IAED,KAAK,CAAC,KAAK,CAAU,KAAa,EAAE,SAAS,GAAG,EAAE;QAChD,IAAI,CAAC;YACH,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,IAAI,CAC1B,IAAI,CAAC,QAAQ,EACb;gBACE,KAAK;gBACL,SAAS;aACV,EACD;gBACE,OAAO,EAAE;oBACP,mCAAmC,EAAE,IAAI,CAAC,KAAK;oBAC/C,cAAc,EAAE,kBAAkB;iBACnC;aACF,CACF,CAAC;YACF,IAAI,GAAG,CAAC,IAAI,EAAE,MAAM;gBAClB,MAAM,IAAI,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;YAC5D,OAAO,GAAG,CAAC,IAAI,EAAE,IAAI,CAAC;QACxB,CAAC;QAAC,OAAO,KAAU,EAAE,CAAC;YACpB,MAAM,IAAI,KAAK,CAAC,kBAAkB,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC;QACrD,CAAC;IACH,CAAC;CACF;AAED,eAAe,aAAa,CAAC"}
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../../src/client/client.ts"],"names":[],"mappings":"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"}