@pintahub/shopify-api 2.6.1 → 2.6.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +229 -0
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,2 +1,231 @@
|
|
|
1
1
|
# @pintahub/shopify-api
|
|
2
2
|
|
|
3
|
+
TypeScript SDK wrapper for Shopify APIs. Supports Admin GraphQL, Storefront GraphQL, REST, and Shop.app APIs with full type safety.
|
|
4
|
+
|
|
5
|
+
## Installation
|
|
6
|
+
|
|
7
|
+
```bash
|
|
8
|
+
yarn add @pintahub/shopify-api
|
|
9
|
+
```
|
|
10
|
+
|
|
11
|
+
## Quick Start
|
|
12
|
+
|
|
13
|
+
### Admin API (GraphQL)
|
|
14
|
+
|
|
15
|
+
```typescript
|
|
16
|
+
import { AdminAPI } from '@pintahub/shopify-api'
|
|
17
|
+
|
|
18
|
+
const admin = new AdminAPI({
|
|
19
|
+
shop: 'your-store.myshopify.com',
|
|
20
|
+
accessToken: 'shpat_xxx',
|
|
21
|
+
legacy: false, // set true to enable legacy v1 product/order APIs
|
|
22
|
+
})
|
|
23
|
+
|
|
24
|
+
// Search products
|
|
25
|
+
const products = await admin.products.search({ query: 'title:T-Shirt' })
|
|
26
|
+
|
|
27
|
+
// Get product with variants
|
|
28
|
+
const product = await admin.products.get({ id: '123456' })
|
|
29
|
+
|
|
30
|
+
// Create product
|
|
31
|
+
const newProduct = await admin.products.create({
|
|
32
|
+
product: { title: 'New Product', productType: 'Apparel' }
|
|
33
|
+
})
|
|
34
|
+
|
|
35
|
+
// Update variants in bulk
|
|
36
|
+
await admin.products.updateVariants({
|
|
37
|
+
productId: '123456',
|
|
38
|
+
variants: [
|
|
39
|
+
{ id: '111', price: '29.99', compareAtPrice: '39.99' }
|
|
40
|
+
]
|
|
41
|
+
})
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
### Storefront API (GraphQL)
|
|
45
|
+
|
|
46
|
+
```typescript
|
|
47
|
+
import { StorefrontAPI } from '@pintahub/shopify-api'
|
|
48
|
+
|
|
49
|
+
const storefront = new StorefrontAPI({
|
|
50
|
+
shop: 'your-store.myshopify.com',
|
|
51
|
+
accessToken: 'your_storefront_public_token',
|
|
52
|
+
})
|
|
53
|
+
|
|
54
|
+
// Get product
|
|
55
|
+
const product = await storefront.product.get({ id: '123456' })
|
|
56
|
+
|
|
57
|
+
// Create cart and add items
|
|
58
|
+
const cart = await storefront.cart.create({})
|
|
59
|
+
await storefront.cart.addItem({
|
|
60
|
+
cartId: cart.id,
|
|
61
|
+
lines: [{ merchandiseId: 'gid://shopify/ProductVariant/111', quantity: 1 }]
|
|
62
|
+
})
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
### REST API
|
|
66
|
+
|
|
67
|
+
```typescript
|
|
68
|
+
import { RestAPI } from '@pintahub/shopify-api'
|
|
69
|
+
|
|
70
|
+
const rest = new RestAPI({
|
|
71
|
+
shop: 'your-store.myshopify.com',
|
|
72
|
+
accessToken: 'shpat_xxx',
|
|
73
|
+
})
|
|
74
|
+
|
|
75
|
+
// Get order details
|
|
76
|
+
const order = await rest.order.get({ id: '123456' })
|
|
77
|
+
|
|
78
|
+
// Update tracking
|
|
79
|
+
await rest.order.updateTracking({
|
|
80
|
+
fulfillment_id: '789',
|
|
81
|
+
tracking_info: {
|
|
82
|
+
company: 'DHL',
|
|
83
|
+
number: '1234567890',
|
|
84
|
+
url: 'https://tracking-url.com'
|
|
85
|
+
},
|
|
86
|
+
notify_customer: true
|
|
87
|
+
})
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
### Shop.app API
|
|
91
|
+
|
|
92
|
+
```typescript
|
|
93
|
+
import { ShopAppAPI } from '@pintahub/shopify-api'
|
|
94
|
+
|
|
95
|
+
const shopApp = new ShopAppAPI({
|
|
96
|
+
shop_id: 'your_shop_id',
|
|
97
|
+
cookies: 'your_session_cookies',
|
|
98
|
+
})
|
|
99
|
+
|
|
100
|
+
const reviews = await shopApp.getReviews()
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
## API Reference
|
|
104
|
+
|
|
105
|
+
### AdminAPI
|
|
106
|
+
|
|
107
|
+
| Module | Method | Description |
|
|
108
|
+
|--------|--------|-------------|
|
|
109
|
+
| **products** | `search(args)` | Search products |
|
|
110
|
+
| | `get(args)` | Get product by ID |
|
|
111
|
+
| | `create(args)` | Create product |
|
|
112
|
+
| | `createV2(args)` | Create product (alternative) |
|
|
113
|
+
| | `update(args)` | Update product |
|
|
114
|
+
| | `delete(args)` | Delete product |
|
|
115
|
+
| | `getVariants(args)` | Get product variants |
|
|
116
|
+
| | `updateVariants(args)` | Bulk update variants |
|
|
117
|
+
| | `getOptions(args)` | Get product options |
|
|
118
|
+
| | `createOption(args)` | Add new option to product |
|
|
119
|
+
| | `updateOption(args)` | Update existing option |
|
|
120
|
+
| | `getMedia(args)` | Get product media |
|
|
121
|
+
| | `appendMedia(args)` | Add media to product |
|
|
122
|
+
| | `deleteMedia(args)` | Remove media |
|
|
123
|
+
| | `reorderMedia(args)` | Reorder media |
|
|
124
|
+
| | `publish(args)` | Publish product |
|
|
125
|
+
| **orders** | `search(args?)` | Search orders |
|
|
126
|
+
| | `get(args)` | Get order by ID |
|
|
127
|
+
| | `getEvents(args)` | Get order timeline events |
|
|
128
|
+
| **customers** | `create(args)` | Create customer |
|
|
129
|
+
| **collections** | `search(args?)` | Search collections |
|
|
130
|
+
| | `get(args)` | Get collection by ID |
|
|
131
|
+
| | `update(args)` | Update collection |
|
|
132
|
+
| **files** | `searchImages(args)` | Search images |
|
|
133
|
+
| | `getImage(args)` | Get image by ID |
|
|
134
|
+
| | `getVideo(args)` | Get video by ID |
|
|
135
|
+
| | `update(args)` | Update file metadata |
|
|
136
|
+
| | `delete(args)` | Delete file |
|
|
137
|
+
| **menus** | `search(args)` | Search navigation menus |
|
|
138
|
+
| | `get(args)` | Get menu by ID |
|
|
139
|
+
| **metaobjects** | `search(args)` | Search metaobjects |
|
|
140
|
+
| | `get(args)` | Get metaobject by ID |
|
|
141
|
+
| | `listBanners(args)` | List banner metaobjects |
|
|
142
|
+
| | `listFAQs(args)` | List FAQ metaobjects |
|
|
143
|
+
| **payments** | `searchPayouts(args)` | Search payment payouts |
|
|
144
|
+
|
|
145
|
+
**Legacy APIs** (when `legacy: true`): `product` and `order` modules provide v1 API access with similar methods.
|
|
146
|
+
|
|
147
|
+
### StorefrontAPI
|
|
148
|
+
|
|
149
|
+
| Module | Method | Description |
|
|
150
|
+
|--------|--------|-------------|
|
|
151
|
+
| **product** | `get(args)` | Get product with variants and pricing |
|
|
152
|
+
| **cart** | `create(args)` | Create new cart |
|
|
153
|
+
| | `get(args)` | Get cart contents |
|
|
154
|
+
| | `addItem(args)` | Add items to cart |
|
|
155
|
+
| | `removeItem(args)` | Remove items from cart |
|
|
156
|
+
| | `updateItem(args)` | Update item quantity |
|
|
157
|
+
| | `updateBuyer(args)` | Update buyer identity |
|
|
158
|
+
| **pages** | `searchPages(args?)` | Search CMS pages |
|
|
159
|
+
| | `getPage(args)` | Get page by ID |
|
|
160
|
+
| **posts** | `search(args)` | Search blog posts |
|
|
161
|
+
| | `get(args)` | Get blog post by ID |
|
|
162
|
+
| **shop** | `get(args?)` | Get shop information |
|
|
163
|
+
| | `getPolicyPage(args?)` | Get policy pages |
|
|
164
|
+
| **customers** | `create(args)` | Create customer account |
|
|
165
|
+
|
|
166
|
+
### RestAPI
|
|
167
|
+
|
|
168
|
+
| Module | Method | Description |
|
|
169
|
+
|--------|--------|-------------|
|
|
170
|
+
| **order** | `get(args)` | Get order details |
|
|
171
|
+
| | `getTransaction(args)` | Get payment transactions |
|
|
172
|
+
| | `updateTracking(args)` | Update shipment tracking |
|
|
173
|
+
|
|
174
|
+
### ShopAppAPI
|
|
175
|
+
|
|
176
|
+
| Method | Description |
|
|
177
|
+
|--------|-------------|
|
|
178
|
+
| `getReviews()` | Fetch store reviews |
|
|
179
|
+
|
|
180
|
+
## API Versions
|
|
181
|
+
|
|
182
|
+
| Client | Version | Modules |
|
|
183
|
+
|--------|---------|---------|
|
|
184
|
+
| Admin GraphQL | 2025-01 | products, files |
|
|
185
|
+
| Admin GraphQL | 2026-01 | orders, customers, collections, menus, metaobjects, payments |
|
|
186
|
+
| Admin GraphQL | 2023-10 | legacy product, legacy order |
|
|
187
|
+
| Storefront GraphQL | 2025-10 | all storefront modules |
|
|
188
|
+
| REST | 2024-01 | order |
|
|
189
|
+
|
|
190
|
+
## Environment Variables
|
|
191
|
+
|
|
192
|
+
| Variable | Description |
|
|
193
|
+
|----------|-------------|
|
|
194
|
+
| `SHOPIFY_SHOP` | Store domain (e.g. `your-store.myshopify.com`) |
|
|
195
|
+
| `SHOPIFY_ACCESS_TOKEN` | Admin API access token (`shpat_xxx`) |
|
|
196
|
+
| `SHOPIFY_STOREFRONT_TOKEN` | Storefront API public access token |
|
|
197
|
+
| `SHOPIFY_SHOP_APP_ID` | Shop.app shop ID |
|
|
198
|
+
| `SHOPIFY_SHOP_APP_COOKIES` | Shop.app session cookies |
|
|
199
|
+
|
|
200
|
+
## Architecture
|
|
201
|
+
|
|
202
|
+
The SDK uses the **ActionBuilder** pattern:
|
|
203
|
+
|
|
204
|
+
```
|
|
205
|
+
AdminAPI / StorefrontAPI / RestAPI
|
|
206
|
+
-> Module (e.g. AdminProductsAPI)
|
|
207
|
+
-> ActionBuilder (e.g. CreateProduct, SearchProducts)
|
|
208
|
+
-> GraphQL/REST request
|
|
209
|
+
```
|
|
210
|
+
|
|
211
|
+
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.
|
|
212
|
+
|
|
213
|
+
## Development
|
|
214
|
+
|
|
215
|
+
```bash
|
|
216
|
+
# Install dependencies
|
|
217
|
+
yarn install
|
|
218
|
+
|
|
219
|
+
# Development mode (auto-compile on changes)
|
|
220
|
+
yarn dev
|
|
221
|
+
|
|
222
|
+
# Build
|
|
223
|
+
npx tsc
|
|
224
|
+
|
|
225
|
+
# Run a test
|
|
226
|
+
node test/create-option.js
|
|
227
|
+
```
|
|
228
|
+
|
|
229
|
+
## License
|
|
230
|
+
|
|
231
|
+
ISC
|