shopify_storefront_sdk 1.0.4 → 2.0.0

package/README.md

@@ -1,7 +1,9 @@
 # 📦 Shopify Storefront SDK (Node.js + TypeScript)
 
+[![CI](https://github.com/kiddo9/shopify_storefront_sdk/actions/workflows/ci.yml/badge.svg)](https://github.com/kiddo9/shopify_storefront_sdk/actions/workflows/ci.yml)
+
 A fully typed, lightweight, and developer-friendly **Node.js SDK for the Shopify Storefront GraphQL API**.  
-Built with TypeScript, GraphQL Codegen, and graphql-request — designed to help developers move faster when building Shopify headless storefronts.
+Built with TypeScript, designed to help developers move faster when building Shopify headless storefronts.
 
 ✔ Fully typed queries & responses  
 ✔ Simple, intuitive API  
@@ -15,18 +17,20 @@ Built with TypeScript, GraphQL Codegen, and graphql-request — designed to help
 ## 🔧 Installation
 
 ```bash
-npm install shopify-storefront-sdk
+npm install shopify_storefront_sdk
 # or
-yarn add shopify-storefront-sdk
+yarn add shopify_storefront_sdk
 # or
-pnpm add shopify-storefront-sdk
+pnpm add shopify_storefront_sdk
 
 ```
 
 ## 🚀 Quick Start
 
 ```ts
-import { ShopifyStorefront } from "shopify-storefront-sdk";
+import ShopifyStorefront from "shopify-storefront-sdk";
+// or
+const { default: ShopifyStorefront } = require("shopify_storefront_sdk");
 
 const shopify = new ShopifyStorefront({
   domain: process.env.SHOPIFY_STORE_DOMAIN!,
@@ -34,9 +38,10 @@ const shopify = new ShopifyStorefront({
 });
 
 // Fetch a product
-const product = await shopify.getProductById(
-  "gid://shopify/Product/1234567890"
-);
+const product = await client.getProductById({
+  id: "id",
+  metafields: [],
+});
 
 console.log(product.title);
 ```
@@ -53,10 +58,8 @@ console.log(product.title);
   - Carts (create/get/update)
   - Customers (create, login, recovery flow)
 
-- **GraphQL Codegen built in**
 - **Consistent error handling**
 - **Supports custom queries**
-- **Zero heavy dependencies**
 
 ---
 
@@ -68,65 +71,165 @@ console.log(product.title);
 const shopify = new ShopifyStorefront({
   domain: "yourstore.myshopify.com",
   token: "your-storefront-access-token",
+  apiVersion: "2025-01", // Optional: defaults to 2025-01. Can be set to "unstable" or future versions.
+  maxRetries: 3,         // Optional: Automatically retries on rate limits (429/503). Defaults to 3.
 });
 ```
 
 ---
 
+### Verify Webhooks
+
+Easily verify incoming Shopify Webhooks using our static helper method (useful for API routes):
+
+```ts
+const isValid = ShopifyStorefront.verifyWebhook(
+  rawBodyBuffer, 
+  req.headers['x-shopify-hmac-sha256'], 
+  process.env.SHOPIFY_WEBHOOK_SECRET
+);
+
+if (!isValid) throw new Error("Unauthorized");
+```
+
+---
+
+### Pagination
+
+Automatically fetch all pages of a GraphQL connection without manually managing cursors:
+
+```ts
+const allProducts = await shopify.autoPaginate(
+  (cursor) => shopify.getProducts({ first: 250, after: cursor }),
+  (response) => response.products
+);
+
+// allProducts is now a flat array of Product nodes!
+```
+
+### Shop Info
+
+Retrieve general store configuration such as name, description, and currency settings:
+
+```ts
+const shop = await shopify.getShopInfo();
+console.log(shop.shop.name);
+```
+
+---
+
 ### Products
 
 #### Get product by ID
 
 ```ts
-await shopify.getProductById(productId);
+await shopify.getProductById({
+  id: "id",
+  metafields: [],
+});
 ```
 
 #### Get product by handle
 
 ```ts
-await shopify.getProductByHandle("my-product");
+await shopify.getProductByHandle({
+  handle: "",
+});
 ```
 
 #### Recommendations
 
 ```ts
-await shopify.getProductRecommendations(productId);
+await shopify.getProductRecommendations({
+  productId: "",
+});
 ```
 
 ---
 
-### Carts
+### ⚡ Advanced Caching
 
-#### Create a cart
+Repeatedly fetching the same data (like Store Info or Product details) can waste network time and hit Shopify rate limits. The SDK comes with a powerful, flexible caching layer.
 
 ```ts
-await shopify.createCart({
-  lines: [{ merchandiseId: "...", quantity: 1 }],
+import { ShopifyStorefront, InMemoryCache } from 'shopify_storefront_sdk';
+
+const shopify = new ShopifyStorefront({
+  domain: "yourstore.myshopify.com",
+  token: "your-storefront-access-token",
+  cache: new InMemoryCache(), // Automatically caches GraphQL Queries
+  defaultCacheTtl: 60         // Cache duration in seconds (default is 60)
 });
+
+// 1st Call: Hits the network (~200ms)
+const shopInfo1 = await shopify.getShopInfo(); 
+
+// 2nd Call: Instantly returns from memory (~0ms)
+const shopInfo2 = await shopify.getShopInfo(); 
 ```
 
-#### Get cart
+**Note:** The SDK intelligently ignores mutations. `createCart` or `addCartLines` will *never* be cached.
+
+You can also use your own cache (like Redis) by passing an object that matches the `ShopifyCache` interface (`get(key)`, `set(key, value, ttl)`).
+
+---
+
+### 🛒 Cart Manager (Recommended)
+
+Managing a Cart manually can be tedious. The SDK includes a stateful `CartManager` that automatically handles cart creation in the background:
 
 ```ts
-await shopify.getCart(cartId);
+// Initialize with no ID to lazily create a cart, or pass an existing ID.
+const cart = shopify.cart();
+
+// Will automatically call createCart() in the background!
+await cart.addLines([{ merchandiseId: "gid://...", quantity: 1 }]);
+
+// The newly created cart ID is safely stored
+console.log(cart.id); 
+
+// Easily fetch the latest state
+const state = await cart.get();
 ```
 
 ---
 
-### Customers
+### Manual Cart Operations
+
+#### Create a cart
 
 ```ts
-await shopify.createCustomer({ email, password });
-await shopify.sendResetEmail(email);
-await shopify.verifyToken(token);
+await shopify.createCart({
+  input: {
+    lines: [
+      {
+        quantity: 1,
+        merchandiseId: "",
+      },
+    ],
+  },
+  first: 20,
+});
 ```
 
 ---
 
-### Blogs & Articles
+### 👤 Customer Session Manager
+
+Passing the `customerAccessToken` into every method manually can be repetitive. Use the stateful `CustomerSession` to automatically bind the token to all operations for that user:
 
 ```ts
-await shopify.getBlog("news", 10);
+// 1. Log the customer in
+const auth = await shopify.loginCustomer({ email: "...", password: "..." });
+const token = auth.customerAccessTokenCreate.customerAccessToken.accessToken;
+
+// 2. Initialize a Customer Session for that user
+const session = shopify.customer(token);
+
+// 3. Effortlessly manage their account!
+const isValid = await session.verify();
+const orders = await session.getOrders({ first: 10 });
+await session.update({ customer: { firstName: "John" } });
 ```
 
 ---
@@ -135,12 +238,11 @@ await shopify.getBlog("news", 10);
 
 ```
 /src
-  /queries        → .graphql operations
+  /client
+  /utils
+  /graphql       → .graphql operations
   /generated      → Auto-generated code
   index.ts        → SDK export
-
-/codegen.yml       → Codegen config
-/schema.graphql    → Shopify schema
 ```
 
 ---
@@ -148,8 +250,8 @@ await shopify.getBlog("news", 10);
 ## 🛠 Development Setup
 
 ```bash
-git clone https://github.com/YOUR_USERNAME/shopify-storefront-sdk.git
-cd shopify-storefront-sdk
+git clone https://github.com/kiddo9/shopify_storefront_sdk.git
+cd shopify_storefront_sdk
 npm install
 ```
 
@@ -165,14 +267,14 @@ SHOPIFY_STOREFRONT_TOKEN=xxxx
 ## 🔨 Build
 
 ```bash
-npm run build
+npm run prepare
 ```
 
 Outputs:
 
 ```
+dist/cjs/index.js
 dist/index.js
-dist/index.cjs
 dist/index.d.ts
 ```
 
@@ -181,36 +283,13 @@ dist/index.d.ts
 ## 🧪 Testing
 
 ```bash
-npm run dev
+npm run dev:test
 # after build:
 npm run test
 ```
 
 ---
 
-## 🧬 Code Generation
-
-Regenerate types & operations:
-
-```bash
-npm run generate
-```
-
-Scans:
-
-```
-src/queries/*.graphql
-schema.graphql
-```
-
-Generates:
-
-```
-src/generated/
-```
-
----
-
 ## 🌐 Requirements
 
 - Node.js 18+
@@ -243,16 +322,3 @@ it helps others discover it and motivates future improvements!
 
 ---
 
-```
-
-If you want, I can also generate:
-
-✅ Better badges (npm version, downloads, license, TypeScript)
-✅ CONTRIBUTING.md
-✅ API documentation table
-✅ Full GitHub project template (issues, PR templates, workflows)
-```
-
-```
-
-```

package/dist/cjs/client/client.js

@@ -1,32 +1,120 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-const axios_1 = require("axios");
+const crypto = require("node:crypto");
+const errors_js_1 = require("../utils/errors.js");
 class ShopifyClient {
-    constructor({ storeUrl, storefrontToken }) {
-        if (!(storeUrl === null || storeUrl === void 0 ? void 0 : storeUrl.includes(".myshopify.com"))) {
-            throw new Error(`The store url ${storeUrl} is not supported by shopify`);
+    constructor({ storeUrl, storefrontToken, apiVersion = "2025-01", maxRetries = 3, cache, defaultCacheTtl = 60 }) {
+        if (!storeUrl || !storeUrl.includes(".myshopify.com")) {
+            throw new errors_js_1.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 errors_js_1.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 = {}) {
-        var _a, _b;
-        try {
-            const res = await axios_1.default.post(this.endpoint, {
-                query,
-                variables,
-            }, {
-                headers: {
-                    "X-Shopify-Storefront-Access-Token": this.token,
-                    "Content-Type": "application/json",
-                },
-            });
-            if ((_a = res.data) === null || _a === void 0 ? void 0 : _a.errors)
-                throw new Error(JSON.stringify(res.data.errors, null, 2));
-            return (_b = res.data) === null || _b === void 0 ? void 0 : _b.data;
+        var _a;
+        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 errors_js_1.ShopifyNetworkError(`Shopify returned HTTP ${res.status}: Rate Limited or Service Unavailable`);
+                    }
+                    // Handle other HTTP errors
+                    if (res.status >= 400 && res.status < 500) {
+                        throw new errors_js_1.ShopifyInvalidRequestError(`Shopify returned a client error: HTTP ${res.status}`);
+                    }
+                    throw new errors_js_1.ShopifyNetworkError(`Shopify Server Error: HTTP ${res.status}`);
+                }
+                const data = await res.json();
+                // 2. Handle top-level GraphQL Errors
+                if ((data === null || data === void 0 ? void 0 : data.errors) && data.errors.length > 0) {
+                    throw new errors_js_1.ShopifyGraphQLError(((_a = data.errors[0]) === null || _a === void 0 ? void 0 : _a.message) || "GraphQL API returned errors", data.errors);
+                }
+                // 3. Scan for nested User Errors (commonly found in mutations)
+                if (data === null || data === void 0 ? void 0 : data.data) {
+                    this.checkForUserErrors(data.data);
+                }
+                // 4. Save to Cache
+                if (this.cache && !isMutation && (data === null || data === void 0 ? void 0 : data.data)) {
+                    await this.cache.set(cacheKey, data.data, this.cacheTtl);
+                }
+                return data === null || data === void 0 ? void 0 : data.data;
+            }
+            catch (error) {
+                // If it's a structural/GraphQL/User error, or a 4xx error (except 429), re-throw immediately.
+                if (error instanceof errors_js_1.ShopifyGraphQLError ||
+                    error instanceof errors_js_1.ShopifyInvalidRequestError ||
+                    error instanceof errors_js_1.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 errors_js_1.ShopifyNetworkError(`Network Error: ${error.message}`);
+            }
+        }
+        throw new errors_js_1.ShopifyNetworkError("Maximum retries exceeded");
+    }
+    /**
+     * Helper function to recursively check for `userErrors` inside the GraphQL response data.
+     */
+    checkForUserErrors(data) {
+        var _a, _b;
+        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 errors_js_1.ShopifyUserError(((_a = value.userErrors[0]) === null || _a === void 0 ? void 0 : _a.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 errors_js_1.ShopifyUserError(((_b = value.customerUserErrors[0]) === null || _b === void 0 ? void 0 : _b.message) || "A customer user error occurred", value.customerUserErrors);
+                }
+                else {
+                    this.checkForUserErrors(value);
+                }
+            }
         }
     }
 }

package/dist/cjs/generated/shopify.js

@@ -903,100 +903,76 @@ const defaultWrapper = (action, _operationName, _operationType, _variables) => a
 function getSdk(client, withWrapper = defaultWrapper) {
     return {
         getProducts(variables, requestHeaders) {
-            return withWrapper((wrappedRequestHeaders) => client.rawRequest(exports.GetProductsDocument, variables, {
-                ...requestHeaders,
-                ...wrappedRequestHeaders,
-            }), "getProducts", "query", variables);
+            return withWrapper((wrappedRequestHeaders) => client.rawRequest(exports.GetProductsDocument, variables, { ...requestHeaders, ...wrappedRequestHeaders }), 'getProducts', 'query', variables);
         },
         getProductById(variables, requestHeaders) {
-            return withWrapper((wrappedRequestHeaders) => client.rawRequest(exports.GetProductByIdDocument, variables, { ...requestHeaders, ...wrappedRequestHeaders }), "getProductById", "query", variables);
+            return withWrapper((wrappedRequestHeaders) => client.rawRequest(exports.GetProductByIdDocument, variables, { ...requestHeaders, ...wrappedRequestHeaders }), 'getProductById', 'query', variables);
         },
         GetProductRecommendations(variables, requestHeaders) {
-            return withWrapper((wrappedRequestHeaders) => client.rawRequest(exports.GetProductRecommendationsDocument, variables, { ...requestHeaders, ...wrappedRequestHeaders }), "GetProductRecommendations", "query", variables);
+            return withWrapper((wrappedRequestHeaders) => client.rawRequest(exports.GetProductRecommendationsDocument, variables, { ...requestHeaders, ...wrappedRequestHeaders }), 'GetProductRecommendations', 'query', variables);
         },
         GetProductByHandle(variables, requestHeaders) {
-            return withWrapper((wrappedRequestHeaders) => client.rawRequest(exports.GetProductByHandleDocument, variables, { ...requestHeaders, ...wrappedRequestHeaders }), "GetProductByHandle", "query", variables);
+            return withWrapper((wrappedRequestHeaders) => client.rawRequest(exports.GetProductByHandleDocument, variables, { ...requestHeaders, ...wrappedRequestHeaders }), 'GetProductByHandle', 'query', variables);
         },
         GetAllProductTypes(variables, requestHeaders) {
-            return withWrapper((wrappedRequestHeaders) => client.rawRequest(exports.GetAllProductTypesDocument, variables, { ...requestHeaders, ...wrappedRequestHeaders }), "GetAllProductTypes", "query", variables);
+            return withWrapper((wrappedRequestHeaders) => client.rawRequest(exports.GetAllProductTypesDocument, variables, { ...requestHeaders, ...wrappedRequestHeaders }), 'GetAllProductTypes', 'query', variables);
         },
         getCollections(variables, requestHeaders) {
-            return withWrapper((wrappedRequestHeaders) => client.rawRequest(exports.GetCollectionsDocument, variables, { ...requestHeaders, ...wrappedRequestHeaders }), "getCollections", "query", variables);
+            return withWrapper((wrappedRequestHeaders) => client.rawRequest(exports.GetCollectionsDocument, variables, { ...requestHeaders, ...wrappedRequestHeaders }), 'getCollections', 'query', variables);
         },
         getShopInfo(variables, requestHeaders) {
-            return withWrapper((wrappedRequestHeaders) => client.rawRequest(exports.GetShopInfoDocument, variables, {
-                ...requestHeaders,
-                ...wrappedRequestHeaders,
-            }), "getShopInfo", "query", variables);
+            return withWrapper((wrappedRequestHeaders) => client.rawRequest(exports.GetShopInfoDocument, variables, { ...requestHeaders, ...wrappedRequestHeaders }), 'getShopInfo', 'query', variables);
         },
         GetCart(variables, requestHeaders) {
-            return withWrapper((wrappedRequestHeaders) => client.rawRequest(exports.GetCartDocument, variables, {
-                ...requestHeaders,
-                ...wrappedRequestHeaders,
-            }), "GetCart", "query", variables);
+            return withWrapper((wrappedRequestHeaders) => client.rawRequest(exports.GetCartDocument, variables, { ...requestHeaders, ...wrappedRequestHeaders }), 'GetCart', 'query', variables);
         },
         cartCreate(variables, requestHeaders) {
-            return withWrapper((wrappedRequestHeaders) => client.rawRequest(exports.CartCreateDocument, variables, {
-                ...requestHeaders,
-                ...wrappedRequestHeaders,
-            }), "cartCreate", "mutation", variables);
+            return withWrapper((wrappedRequestHeaders) => client.rawRequest(exports.CartCreateDocument, variables, { ...requestHeaders, ...wrappedRequestHeaders }), 'cartCreate', 'mutation', variables);
         },
         cartLinesUpdate(variables, requestHeaders) {
-            return withWrapper((wrappedRequestHeaders) => client.rawRequest(exports.CartLinesUpdateDocument, variables, { ...requestHeaders, ...wrappedRequestHeaders }), "cartLinesUpdate", "mutation", variables);
+            return withWrapper((wrappedRequestHeaders) => client.rawRequest(exports.CartLinesUpdateDocument, variables, { ...requestHeaders, ...wrappedRequestHeaders }), 'cartLinesUpdate', 'mutation', variables);
         },
         cartBuyerIdentityUpdate(variables, requestHeaders) {
-            return withWrapper((wrappedRequestHeaders) => client.rawRequest(exports.CartBuyerIdentityUpdateDocument, variables, { ...requestHeaders, ...wrappedRequestHeaders }), "cartBuyerIdentityUpdate", "mutation", variables);
+            return withWrapper((wrappedRequestHeaders) => client.rawRequest(exports.CartBuyerIdentityUpdateDocument, variables, { ...requestHeaders, ...wrappedRequestHeaders }), 'cartBuyerIdentityUpdate', 'mutation', variables);
         },
         cartMetafieldsSet(variables, requestHeaders) {
-            return withWrapper((wrappedRequestHeaders) => client.rawRequest(exports.CartMetafieldsSetDocument, variables, { ...requestHeaders, ...wrappedRequestHeaders }), "cartMetafieldsSet", "mutation", variables);
+            return withWrapper((wrappedRequestHeaders) => client.rawRequest(exports.CartMetafieldsSetDocument, variables, { ...requestHeaders, ...wrappedRequestHeaders }), 'cartMetafieldsSet', 'mutation', variables);
         },
         cartLinesAdd(variables, requestHeaders) {
-            return withWrapper((wrappedRequestHeaders) => client.rawRequest(exports.CartLinesAddDocument, variables, { ...requestHeaders, ...wrappedRequestHeaders }), "cartLinesAdd", "mutation", variables);
+            return withWrapper((wrappedRequestHeaders) => client.rawRequest(exports.CartLinesAddDocument, variables, { ...requestHeaders, ...wrappedRequestHeaders }), 'cartLinesAdd', 'mutation', variables);
         },
         cartLinesRemove(variables, requestHeaders) {
-            return withWrapper((wrappedRequestHeaders) => client.rawRequest(exports.CartLinesRemoveDocument, variables, { ...requestHeaders, ...wrappedRequestHeaders }), "cartLinesRemove", "mutation", variables);
+            return withWrapper((wrappedRequestHeaders) => client.rawRequest(exports.CartLinesRemoveDocument, variables, { ...requestHeaders, ...wrappedRequestHeaders }), 'cartLinesRemove', 'mutation', variables);
         },
         customerCreate(variables, requestHeaders) {
-            return withWrapper((wrappedRequestHeaders) => client.rawRequest(exports.CustomerCreateDocument, variables, { ...requestHeaders, ...wrappedRequestHeaders }), "customerCreate", "mutation", variables);
+            return withWrapper((wrappedRequestHeaders) => client.rawRequest(exports.CustomerCreateDocument, variables, { ...requestHeaders, ...wrappedRequestHeaders }), 'customerCreate', 'mutation', variables);
         },
         customerAccessTokenCreate(variables, requestHeaders) {
-            return withWrapper((wrappedRequestHeaders) => client.rawRequest(exports.CustomerAccessTokenCreateDocument, variables, { ...requestHeaders, ...wrappedRequestHeaders }), "customerAccessTokenCreate", "mutation", variables);
+            return withWrapper((wrappedRequestHeaders) => client.rawRequest(exports.CustomerAccessTokenCreateDocument, variables, { ...requestHeaders, ...wrappedRequestHeaders }), 'customerAccessTokenCreate', 'mutation', variables);
         },
         customerUpdate(variables, requestHeaders) {
-            return withWrapper((wrappedRequestHeaders) => client.rawRequest(exports.CustomerUpdateDocument, variables, { ...requestHeaders, ...wrappedRequestHeaders }), "customerUpdate", "mutation", variables);
+            return withWrapper((wrappedRequestHeaders) => client.rawRequest(exports.CustomerUpdateDocument, variables, { ...requestHeaders, ...wrappedRequestHeaders }), 'customerUpdate', 'mutation', variables);
         },
         getCustomer(variables, requestHeaders) {
-            return withWrapper((wrappedRequestHeaders) => client.rawRequest(exports.GetCustomerDocument, variables, {
-                ...requestHeaders,
-                ...wrappedRequestHeaders,
-            }), "getCustomer", "query", variables);
+            return withWrapper((wrappedRequestHeaders) => client.rawRequest(exports.GetCustomerDocument, variables, { ...requestHeaders, ...wrappedRequestHeaders }), 'getCustomer', 'query', variables);
         },
         customerRecover(variables, requestHeaders) {
-            return withWrapper((wrappedRequestHeaders) => client.rawRequest(exports.CustomerRecoverDocument, variables, { ...requestHeaders, ...wrappedRequestHeaders }), "customerRecover", "mutation", variables);
+            return withWrapper((wrappedRequestHeaders) => client.rawRequest(exports.CustomerRecoverDocument, variables, { ...requestHeaders, ...wrappedRequestHeaders }), 'customerRecover', 'mutation', variables);
         },
         GetBlogs(variables, requestHeaders) {
-            return withWrapper((wrappedRequestHeaders) => client.rawRequest(exports.GetBlogsDocument, variables, {
-                ...requestHeaders,
-                ...wrappedRequestHeaders,
-            }), "GetBlogs", "query", variables);
+            return withWrapper((wrappedRequestHeaders) => client.rawRequest(exports.GetBlogsDocument, variables, { ...requestHeaders, ...wrappedRequestHeaders }), 'GetBlogs', 'query', variables);
         },
         GetBlog(variables, requestHeaders) {
-            return withWrapper((wrappedRequestHeaders) => client.rawRequest(exports.GetBlogDocument, variables, {
-                ...requestHeaders,
-                ...wrappedRequestHeaders,
-            }), "GetBlog", "query", variables);
+            return withWrapper((wrappedRequestHeaders) => client.rawRequest(exports.GetBlogDocument, variables, { ...requestHeaders, ...wrappedRequestHeaders }), 'GetBlog', 'query', variables);
         },
         GetArticles(variables, requestHeaders) {
-            return withWrapper((wrappedRequestHeaders) => client.rawRequest(exports.GetArticlesDocument, variables, {
-                ...requestHeaders,
-                ...wrappedRequestHeaders,
-            }), "GetArticles", "query", variables);
+            return withWrapper((wrappedRequestHeaders) => client.rawRequest(exports.GetArticlesDocument, variables, { ...requestHeaders, ...wrappedRequestHeaders }), 'GetArticles', 'query', variables);
         },
         getSingleArticle(variables, requestHeaders) {
-            return withWrapper((wrappedRequestHeaders) => client.rawRequest(exports.GetSingleArticleDocument, variables, { ...requestHeaders, ...wrappedRequestHeaders }), "getSingleArticle", "query", variables);
+            return withWrapper((wrappedRequestHeaders) => client.rawRequest(exports.GetSingleArticleDocument, variables, { ...requestHeaders, ...wrappedRequestHeaders }), 'getSingleArticle', 'query', variables);
         },
         getCustomerOrders(variables, requestHeaders) {
-            return withWrapper((wrappedRequestHeaders) => client.rawRequest(exports.GetCustomerOrdersDocument, variables, { ...requestHeaders, ...wrappedRequestHeaders }), "getCustomerOrders", "query", variables);
-        },
+            return withWrapper((wrappedRequestHeaders) => client.rawRequest(exports.GetCustomerOrdersDocument, variables, { ...requestHeaders, ...wrappedRequestHeaders }), 'getCustomerOrders', 'query', variables);
+        }
     };
 }

package/dist/cjs/helpers/CartManager.js

@@ -0,0 +1,55 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CartManager = void 0;
+/**
+ * A stateful high-level manager for a Shopify Cart.
+ * Automatically handles lazy creation of the cart if an ID is not provided.
+ */
+class CartManager {
+    constructor(sdk, cartId) {
+        this.sdk = sdk;
+        this.id = cartId || null;
+    }
+    /**
+     * Ensures a cart exists. If not, it creates one and stores the ID.
+     */
+    async ensureCart() {
+        var _a, _b;
+        if (!this.id) {
+            const res = await this.sdk.createCart({ input: {}, first: 250 });
+            this.id = ((_b = (_a = res.cartCreate) === null || _a === void 0 ? void 0 : _a.cart) === null || _b === void 0 ? void 0 : _b.id) || null;
+            if (!this.id) {
+                throw new Error("Failed to create cart during lazy initialization.");
+            }
+        }
+    }
+    /**
+     * Fetches the latest cart details.
+     */
+    async get(first = 250) {
+        await this.ensureCart();
+        return this.sdk.getCart({ cartId: this.id, first });
+    }
+    /**
+     * Adds line items to the cart. Creates the cart if it doesn't exist.
+     */
+    async addLines(lines) {
+        await this.ensureCart();
+        return this.sdk.addCartLines({ cartId: this.id, lines });
+    }
+    /**
+     * Removes line items from the cart. Creates the cart if it doesn't exist.
+     */
+    async removeLines(lineIds) {
+        await this.ensureCart();
+        return this.sdk.removeCartLines({ cartId: this.id, lineIds });
+    }
+    /**
+     * Updates line items in the cart (e.g. modifying quantity).
+     */
+    async updateLines(lines, first = 250) {
+        await this.ensureCart();
+        return this.sdk.updateCartLines({ cartId: this.id, lines, first });
+    }
+}
+exports.CartManager = CartManager;