@pintahub/shopify-api 2.6.0 → 2.6.2

package/README.md

@@ -1,2 +1,231 @@
 # @pintahub/shopify-api
 
+TypeScript SDK wrapper for Shopify APIs. Supports Admin GraphQL, Storefront GraphQL, REST, and Shop.app APIs with full type safety.
+
+## Installation
+
+```bash
+yarn add @pintahub/shopify-api
+```
+
+## Quick Start
+
+### Admin API (GraphQL)
+
+```typescript
+import { AdminAPI } from '@pintahub/shopify-api'
+
+const admin = new AdminAPI({
+    shop: 'your-store.myshopify.com',
+    accessToken: 'shpat_xxx',
+    legacy: false, // set true to enable legacy v1 product/order APIs
+})
+
+// Search products
+const products = await admin.products.search({ query: 'title:T-Shirt' })
+
+// Get product with variants
+const product = await admin.products.get({ id: '123456' })
+
+// Create product
+const newProduct = await admin.products.create({
+    product: { title: 'New Product', productType: 'Apparel' }
+})
+
+// Update variants in bulk
+await admin.products.updateVariants({
+    productId: '123456',
+    variants: [
+        { id: '111', price: '29.99', compareAtPrice: '39.99' }
+    ]
+})
+```
+
+### Storefront API (GraphQL)
+
+```typescript
+import { StorefrontAPI } from '@pintahub/shopify-api'
+
+const storefront = new StorefrontAPI({
+    shop: 'your-store.myshopify.com',
+    accessToken: 'your_storefront_public_token',
+})
+
+// Get product
+const product = await storefront.product.get({ id: '123456' })
+
+// Create cart and add items
+const cart = await storefront.cart.create({})
+await storefront.cart.addItem({
+    cartId: cart.id,
+    lines: [{ merchandiseId: 'gid://shopify/ProductVariant/111', quantity: 1 }]
+})
+```
+
+### REST API
+
+```typescript
+import { RestAPI } from '@pintahub/shopify-api'
+
+const rest = new RestAPI({
+    shop: 'your-store.myshopify.com',
+    accessToken: 'shpat_xxx',
+})
+
+// Get order details
+const order = await rest.order.get({ id: '123456' })
+
+// Update tracking
+await rest.order.updateTracking({
+    fulfillment_id: '789',
+    tracking_info: {
+        company: 'DHL',
+        number: '1234567890',
+        url: 'https://tracking-url.com'
+    },
+    notify_customer: true
+})
+```
+
+### Shop.app API
+
+```typescript
+import { ShopAppAPI } from '@pintahub/shopify-api'
+
+const shopApp = new ShopAppAPI({
+    shop_id: 'your_shop_id',
+    cookies: 'your_session_cookies',
+})
+
+const reviews = await shopApp.getReviews()
+```
+
+## API Reference
+
+### AdminAPI
+
+| Module | Method | Description |
+|--------|--------|-------------|
+| **products** | `search(args)` | Search products |
+| | `get(args)` | Get product by ID |
+| | `create(args)` | Create product |
+| | `createV2(args)` | Create product (alternative) |
+| | `update(args)` | Update product |
+| | `delete(args)` | Delete product |
+| | `getVariants(args)` | Get product variants |
+| | `updateVariants(args)` | Bulk update variants |
+| | `getOptions(args)` | Get product options |
+| | `createOption(args)` | Add new option to product |
+| | `updateOption(args)` | Update existing option |
+| | `getMedia(args)` | Get product media |
+| | `appendMedia(args)` | Add media to product |
+| | `deleteMedia(args)` | Remove media |
+| | `reorderMedia(args)` | Reorder media |
+| | `publish(args)` | Publish product |
+| **orders** | `search(args?)` | Search orders |
+| | `get(args)` | Get order by ID |
+| | `getEvents(args)` | Get order timeline events |
+| **customers** | `create(args)` | Create customer |
+| **collections** | `search(args?)` | Search collections |
+| | `get(args)` | Get collection by ID |
+| | `update(args)` | Update collection |
+| **files** | `searchImages(args)` | Search images |
+| | `getImage(args)` | Get image by ID |
+| | `getVideo(args)` | Get video by ID |
+| | `update(args)` | Update file metadata |
+| | `delete(args)` | Delete file |
+| **menus** | `search(args)` | Search navigation menus |
+| | `get(args)` | Get menu by ID |
+| **metaobjects** | `search(args)` | Search metaobjects |
+| | `get(args)` | Get metaobject by ID |
+| | `listBanners(args)` | List banner metaobjects |
+| | `listFAQs(args)` | List FAQ metaobjects |
+| **payments** | `searchPayouts(args)` | Search payment payouts |
+
+**Legacy APIs** (when `legacy: true`): `product` and `order` modules provide v1 API access with similar methods.
+
+### StorefrontAPI
+
+| Module | Method | Description |
+|--------|--------|-------------|
+| **product** | `get(args)` | Get product with variants and pricing |
+| **cart** | `create(args)` | Create new cart |
+| | `get(args)` | Get cart contents |
+| | `addItem(args)` | Add items to cart |
+| | `removeItem(args)` | Remove items from cart |
+| | `updateItem(args)` | Update item quantity |
+| | `updateBuyer(args)` | Update buyer identity |
+| **pages** | `searchPages(args?)` | Search CMS pages |
+| | `getPage(args)` | Get page by ID |
+| **posts** | `search(args)` | Search blog posts |
+| | `get(args)` | Get blog post by ID |
+| **shop** | `get(args?)` | Get shop information |
+| | `getPolicyPage(args?)` | Get policy pages |
+| **customers** | `create(args)` | Create customer account |
+
+### RestAPI
+
+| Module | Method | Description |
+|--------|--------|-------------|
+| **order** | `get(args)` | Get order details |
+| | `getTransaction(args)` | Get payment transactions |
+| | `updateTracking(args)` | Update shipment tracking |
+
+### ShopAppAPI
+
+| Method | Description |
+|--------|-------------|
+| `getReviews()` | Fetch store reviews |
+
+## API Versions
+
+| Client | Version | Modules |
+|--------|---------|---------|
+| Admin GraphQL | 2025-01 | products, files |
+| Admin GraphQL | 2026-01 | orders, customers, collections, menus, metaobjects, payments |
+| Admin GraphQL | 2023-10 | legacy product, legacy order |
+| Storefront GraphQL | 2025-10 | all storefront modules |
+| REST | 2024-01 | order |
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `SHOPIFY_SHOP` | Store domain (e.g. `your-store.myshopify.com`) |
+| `SHOPIFY_ACCESS_TOKEN` | Admin API access token (`shpat_xxx`) |
+| `SHOPIFY_STOREFRONT_TOKEN` | Storefront API public access token |
+| `SHOPIFY_SHOP_APP_ID` | Shop.app shop ID |
+| `SHOPIFY_SHOP_APP_COOKIES` | Shop.app session cookies |
+
+## Architecture
+
+The SDK uses the **ActionBuilder** pattern:
+
+```
+AdminAPI / StorefrontAPI / RestAPI
+  -> Module (e.g. AdminProductsAPI)
+    -> ActionBuilder (e.g. CreateProduct, SearchProducts)
+      -> GraphQL/REST request
+```
+
+Each operation is a separate class extending `ActionBuilder<Client, Input, Output>`, providing type-safe inputs/outputs and centralized error handling with automatic retry on Shopify API throttling.
+
+## Development
+
+```bash
+# Install dependencies
+yarn install
+
+# Development mode (auto-compile on changes)
+yarn dev
+
+# Build
+npx tsc
+
+# Run a test
+node test/create-option.js
+```
+
+## License
+
+ISC

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pintahub/shopify-api",
-  "version": "2.6.0",
+  "version": "2.6.2",
   "description": "",
   "types": "dist/index.d.ts",
   "main": "dist/index.js",

package/.claude/settings.local.json

@@ -1,10 +0,0 @@
-{
-  "permissions": {
-    "allow": [
-      "Bash(git add:*)",
-      "Bash(git reset:*)",
-      "Bash(git commit:*)",
-      "Bash(git push:*)"
-    ]
-  }
-}