shopify_storefront_sdk 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Paschal Elechi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the “Software”), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

package/README.md

@@ -0,0 +1,258 @@
+# 📦 Shopify Storefront SDK (Node.js + TypeScript)
+
+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.
+
+✔ Fully typed queries & responses  
+✔ Simple, intuitive API  
+✔ Pre-built operations (Products, Carts, Customers, Blogs, Articles…)  
+✔ Works with Node.js, Next.js, Remix, Cloudflare Workers & more  
+✔ Supports custom GraphQL queries  
+✔ Automatic code generation
+
+---
+
+## 🔧 Installation
+
+```bash
+npm install shopify-storefront-sdk
+# or
+yarn add shopify-storefront-sdk
+# or
+pnpm add shopify-storefront-sdk
+
+```
+
+## 🚀 Quick Start
+
+```ts
+import { ShopifyStorefront } from "shopify-storefront-sdk";
+
+const shopify = new ShopifyStorefront({
+  domain: process.env.SHOPIFY_STORE_DOMAIN!,
+  token: process.env.SHOPIFY_STOREFRONT_TOKEN!,
+});
+
+// Fetch a product
+const product = await shopify.getProductById(
+  "gid://shopify/Product/1234567890"
+);
+
+console.log(product.title);
+```
+
+---
+
+## 📘 Features
+
+- **Typed SDK methods**:
+
+  - Products (ID, handle, collections)
+  - Recommendations
+  - Blogs & articles
+  - Carts (create/get/update)
+  - Customers (create, login, recovery flow)
+
+- **GraphQL Codegen built in**
+- **Consistent error handling**
+- **Supports custom queries**
+- **Zero heavy dependencies**
+
+---
+
+## 🧩 SDK API Overview
+
+### Initialize Client
+
+```ts
+const shopify = new ShopifyStorefront({
+  domain: "yourstore.myshopify.com",
+  token: "your-storefront-access-token",
+});
+```
+
+---
+
+### Products
+
+#### Get product by ID
+
+```ts
+await shopify.getProductById(productId);
+```
+
+#### Get product by handle
+
+```ts
+await shopify.getProductByHandle("my-product");
+```
+
+#### Recommendations
+
+```ts
+await shopify.getProductRecommendations(productId);
+```
+
+---
+
+### Carts
+
+#### Create a cart
+
+```ts
+await shopify.createCart({
+  lines: [{ merchandiseId: "...", quantity: 1 }],
+});
+```
+
+#### Get cart
+
+```ts
+await shopify.getCart(cartId);
+```
+
+---
+
+### Customers
+
+```ts
+await shopify.createCustomer({ email, password });
+await shopify.sendResetEmail(email);
+await shopify.verifyToken(token);
+```
+
+---
+
+### Blogs & Articles
+
+```ts
+await shopify.getBlog("news", 10);
+```
+
+---
+
+## 📁 Project Structure
+
+```
+/src
+  /queries        → .graphql operations
+  /generated      → Auto-generated code
+  index.ts        → SDK export
+
+/codegen.yml       → Codegen config
+/schema.graphql    → Shopify schema
+```
+
+---
+
+## 🛠 Development Setup
+
+```bash
+git clone https://github.com/YOUR_USERNAME/shopify-storefront-sdk.git
+cd shopify-storefront-sdk
+npm install
+```
+
+Create a `.env` file:
+
+```
+SHOPIFY_STORE_DOMAIN=yourstore.myshopify.com
+SHOPIFY_STOREFRONT_TOKEN=xxxx
+```
+
+---
+
+## 🔨 Build
+
+```bash
+npm run build
+```
+
+Outputs:
+
+```
+dist/index.js
+dist/index.cjs
+dist/index.d.ts
+```
+
+---
+
+## 🧪 Testing
+
+```bash
+npm run dev
+# 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+
+- Storefront API token
+- Public or development Shopify store
+
+---
+
+## 🤝 Contributing
+
+Pull requests are welcome!
+
+1. Fork the repo
+2. Create a branch: `git checkout -b feature/my-feature`
+3. Commit & push
+4. Submit a PR
+
+---
+
+## 📜 License
+
+MIT License — free for commercial and personal use.
+
+---
+
+## ⭐ Support
+
+If this SDK saves you time, please star ⭐ the repository—
+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.d.ts

@@ -0,0 +1,9 @@
+import type { StoreConfig } from "../utils/config.js";
+declare class ShopifyClient {
+    private endpoint;
+    private token;
+    constructor({ storeUrl, storefrontToken }: StoreConfig);
+    query<T = any>(query: string, variables?: {}): Promise<T>;
+}
+export default ShopifyClient;
+//# sourceMappingURL=client.d.ts.map

package/dist/cjs/client/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../../src/client/client.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAGtD,cAAM,aAAa;IACjB,OAAO,CAAC,QAAQ,CAAC;IACjB,OAAO,CAAC,KAAK,CAAC;gBACF,EAAE,QAAQ,EAAE,eAAe,EAAE,EAAE,WAAW;IAQhD,KAAK,CAAC,CAAC,GAAG,GAAG,EAAE,KAAK,EAAE,MAAM,EAAE,SAAS,KAAK,GAAG,OAAO,CAAC,CAAC,CAAC;CAsBhE;AAED,eAAe,aAAa,CAAC"}

package/dist/cjs/client/client.js

@@ -0,0 +1,38 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const axios_1 = __importDefault(require("axios"));
+class ShopifyClient {
+    endpoint;
+    token;
+    constructor({ storeUrl, storefrontToken }) {
+        if (!storeUrl?.includes(".myshopify.com")) {
+            throw new Error(`The store url ${storeUrl} is not supported by shopify`);
+        }
+        (this.endpoint = `https://${storeUrl}/api/2025-04/graphql.json`),
+            (this.token = storefrontToken);
+    }
+    async query(query, variables = {}) {
+        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 (res.data?.errors)
+                throw new Error(JSON.stringify(res.data.errors, null, 2));
+            return res.data?.data;
+        }
+        catch (error) {
+            throw new Error(`Shopify Error: ${error.message}`);
+        }
+    }
+}
+exports.default = ShopifyClient;
+//# sourceMappingURL=client.js.map

package/dist/cjs/client/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../../../src/client/client.ts"],"names":[],"mappings":";;;;;AACA,kDAA0B;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,eAAK,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,kBAAe,aAAa,CAAC"}