@shopkit/data-layer 1.0.0
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 +857 -0
- package/dist/adapters/index.d.mts +22 -0
- package/dist/adapters/index.d.ts +22 -0
- package/dist/adapters/index.js +5315 -0
- package/dist/adapters/index.js.map +1 -0
- package/dist/adapters/index.mjs +5312 -0
- package/dist/adapters/index.mjs.map +1 -0
- package/dist/index.d.mts +40 -0
- package/dist/index.d.ts +40 -0
- package/dist/index.js +5387 -0
- package/dist/index.js.map +1 -0
- package/dist/index.mjs +5376 -0
- package/dist/index.mjs.map +1 -0
- package/dist/models/index.d.mts +598 -0
- package/dist/models/index.d.ts +598 -0
- package/dist/models/index.js +67 -0
- package/dist/models/index.js.map +1 -0
- package/dist/models/index.mjs +59 -0
- package/dist/models/index.mjs.map +1 -0
- package/dist/service-NPmqCNGb.d.mts +750 -0
- package/dist/service-Q7zlmyFk.d.ts +750 -0
- package/package.json +120 -0
package/README.md
ADDED
|
@@ -0,0 +1,857 @@
|
|
|
1
|
+
# @shopkit/data-layer
|
|
2
|
+
|
|
3
|
+
A comprehensive, production-ready data layer package for e-commerce applications, providing unified APIs for both Shopify and custom backend integrations.
|
|
4
|
+
|
|
5
|
+
## Table of Contents
|
|
6
|
+
|
|
7
|
+
- [Features](#features)
|
|
8
|
+
- [Installation](#installation)
|
|
9
|
+
- [Quick Start](#quick-start)
|
|
10
|
+
- [Configuration](#configuration)
|
|
11
|
+
- [API Reference](#api-reference)
|
|
12
|
+
- [Usage Examples](#usage-examples)
|
|
13
|
+
- [Platform Support](#platform-support)
|
|
14
|
+
- [Error Handling](#error-handling)
|
|
15
|
+
- [Best Practices](#best-practices)
|
|
16
|
+
- [Examples](#examples)
|
|
17
|
+
- [License](#license)
|
|
18
|
+
|
|
19
|
+
## Features
|
|
20
|
+
|
|
21
|
+
- **🌐 Multi-Platform Support**: Seamlessly works with both Shopify and custom backend APIs
|
|
22
|
+
- **⚙️ Configurable Architecture**: Zero environment variable dependencies - fully configurable through parameters
|
|
23
|
+
- **🔷 TypeScript First**: Built with TypeScript for complete type safety
|
|
24
|
+
- **📦 Modular Design**: Tree-shakable imports - use only what you need
|
|
25
|
+
- **🔧 Flexible Options**: Support for custom queries and variables in all API methods
|
|
26
|
+
- **📋 Consistent Response Format**: Standardized `IResponse` format across all operations
|
|
27
|
+
- **🪵 Advanced Logging**: Built-in logging with configurable levels and formatting
|
|
28
|
+
- **🎯 Standardized Interface**: All methods follow consistent signature patterns
|
|
29
|
+
|
|
30
|
+
## Installation
|
|
31
|
+
|
|
32
|
+
```bash
|
|
33
|
+
npm install @shopkit/data-layer
|
|
34
|
+
# or
|
|
35
|
+
yarn add @shopkit/data-layer
|
|
36
|
+
# or
|
|
37
|
+
pnpm add @shopkit/data-layer
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
## Quick Start
|
|
41
|
+
|
|
42
|
+
### 1. Create a Commerce Client
|
|
43
|
+
|
|
44
|
+
```typescript
|
|
45
|
+
import { createCommerceClient, IClientConfig } from '@shopkit/data-layer';
|
|
46
|
+
|
|
47
|
+
// Shopify Client Configuration
|
|
48
|
+
const shopifyConfig: IClientConfig = {
|
|
49
|
+
type: "shopify",
|
|
50
|
+
config: {
|
|
51
|
+
domain: "your-store.myshopify.com",
|
|
52
|
+
storefrontAccessToken: "your-storefront-access-token",
|
|
53
|
+
apiVersion: "2025-04" as const,
|
|
54
|
+
},
|
|
55
|
+
logging: {
|
|
56
|
+
enabled: true,
|
|
57
|
+
level: "info",
|
|
58
|
+
prettyPrint: true,
|
|
59
|
+
name: "Shopify Data Layer"
|
|
60
|
+
}
|
|
61
|
+
};
|
|
62
|
+
|
|
63
|
+
// Custom Backend Client Configuration
|
|
64
|
+
const customConfig: IClientConfig = {
|
|
65
|
+
type: "custom",
|
|
66
|
+
config: {
|
|
67
|
+
merchantId: "your-merchant-id",
|
|
68
|
+
storeId: "your-store-id",
|
|
69
|
+
services: {
|
|
70
|
+
product: {
|
|
71
|
+
apiBaseUrl: "https://api.yourstore.com/products",
|
|
72
|
+
},
|
|
73
|
+
order: {
|
|
74
|
+
apiBaseUrl: "https://api.yourstore.com/orders",
|
|
75
|
+
},
|
|
76
|
+
cart: {
|
|
77
|
+
apiBaseUrl: "https://api.yourstore.com/cart",
|
|
78
|
+
},
|
|
79
|
+
},
|
|
80
|
+
},
|
|
81
|
+
logging: {
|
|
82
|
+
enabled: true,
|
|
83
|
+
level: "info",
|
|
84
|
+
prettyPrint: true,
|
|
85
|
+
name: "Custom Backend Data Layer"
|
|
86
|
+
}
|
|
87
|
+
};
|
|
88
|
+
|
|
89
|
+
// Create the client
|
|
90
|
+
const commerceClient = createCommerceClient(shopifyConfig);
|
|
91
|
+
// or
|
|
92
|
+
const commerceClient = createCommerceClient(customConfig);
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
### 2. Basic Usage
|
|
96
|
+
|
|
97
|
+
```typescript
|
|
98
|
+
// Get a product
|
|
99
|
+
const product = await client.getProduct({ handle: "product-handle" });
|
|
100
|
+
|
|
101
|
+
if (product.success) {
|
|
102
|
+
console.log(product.data);
|
|
103
|
+
} else {
|
|
104
|
+
console.error(product.error?.message);
|
|
105
|
+
}
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
## Configuration
|
|
109
|
+
|
|
110
|
+
### Client Configuration Interfaces
|
|
111
|
+
|
|
112
|
+
```typescript
|
|
113
|
+
// Shopify Configuration
|
|
114
|
+
interface IShopifyConfig {
|
|
115
|
+
domain: string;
|
|
116
|
+
storefrontAccessToken: string;
|
|
117
|
+
apiVersion: string;
|
|
118
|
+
}
|
|
119
|
+
|
|
120
|
+
// Custom Backend Configuration
|
|
121
|
+
interface ICustomConfig {
|
|
122
|
+
merchantId: string;
|
|
123
|
+
storeId: string;
|
|
124
|
+
services: {
|
|
125
|
+
product: { apiBaseUrl: string };
|
|
126
|
+
order: { apiBaseUrl: string };
|
|
127
|
+
cart: { apiBaseUrl: string };
|
|
128
|
+
};
|
|
129
|
+
}
|
|
130
|
+
|
|
131
|
+
// Client Configuration Union Type
|
|
132
|
+
type IClientConfig =
|
|
133
|
+
| { type: "shopify"; config: IShopifyConfig; logging?: LoggerConfig }
|
|
134
|
+
| { type: "custom"; config: ICustomConfig; logging?: LoggerConfig };
|
|
135
|
+
```
|
|
136
|
+
|
|
137
|
+
### Logging Configuration
|
|
138
|
+
|
|
139
|
+
```typescript
|
|
140
|
+
interface LoggerConfig {
|
|
141
|
+
enabled: boolean;
|
|
142
|
+
level: "trace" | "debug" | "info" | "warn" | "error" | "fatal";
|
|
143
|
+
prettyPrint: boolean;
|
|
144
|
+
name: string;
|
|
145
|
+
redact?: string[];
|
|
146
|
+
}
|
|
147
|
+
```
|
|
148
|
+
|
|
149
|
+
### Request Options
|
|
150
|
+
|
|
151
|
+
All API methods support optional configuration:
|
|
152
|
+
|
|
153
|
+
```typescript
|
|
154
|
+
interface IOptionsRequest {
|
|
155
|
+
query?: string; // Custom GraphQL query
|
|
156
|
+
variables?: Record<string, any>; // Custom variables
|
|
157
|
+
headers?: Record<string, string>; // Custom headers
|
|
158
|
+
params?: Record<string, string>; // URL parameters
|
|
159
|
+
}
|
|
160
|
+
```
|
|
161
|
+
|
|
162
|
+
## API Reference
|
|
163
|
+
|
|
164
|
+
### Method Signature Pattern
|
|
165
|
+
|
|
166
|
+
All methods follow this consistent pattern:
|
|
167
|
+
```typescript
|
|
168
|
+
methodName(params: ISpecificRequest, options?: IOptionsRequest): Promise<IResponse>
|
|
169
|
+
```
|
|
170
|
+
|
|
171
|
+
### Standardized Response Format
|
|
172
|
+
|
|
173
|
+
```typescript
|
|
174
|
+
interface IResponse<T = any> {
|
|
175
|
+
success: boolean;
|
|
176
|
+
message: string;
|
|
177
|
+
data?: T;
|
|
178
|
+
error?: {
|
|
179
|
+
message: string;
|
|
180
|
+
details?: any;
|
|
181
|
+
};
|
|
182
|
+
meta?: IResponseMeta;
|
|
183
|
+
}
|
|
184
|
+
```
|
|
185
|
+
|
|
186
|
+
### Product Operations
|
|
187
|
+
|
|
188
|
+
```typescript
|
|
189
|
+
// Get single product by ID or handle
|
|
190
|
+
getProduct(params: ISingleProductRequest, options?: IOptionsRequest): Promise<IResponse>
|
|
191
|
+
|
|
192
|
+
interface ISingleProductRequest {
|
|
193
|
+
id?: string;
|
|
194
|
+
handle?: string;
|
|
195
|
+
}
|
|
196
|
+
|
|
197
|
+
// Get multiple products with filtering and pagination
|
|
198
|
+
getProducts(params: IProductQueryRequest, options?: IOptionsRequest): Promise<IResponse>
|
|
199
|
+
|
|
200
|
+
interface IProductQueryRequest {
|
|
201
|
+
first?: number;
|
|
202
|
+
last?: number;
|
|
203
|
+
after?: string;
|
|
204
|
+
before?: string;
|
|
205
|
+
query?: string;
|
|
206
|
+
sortKey?: string;
|
|
207
|
+
reverse?: boolean;
|
|
208
|
+
filters?: Array<{
|
|
209
|
+
available?: boolean;
|
|
210
|
+
price?: { min?: number; max?: number };
|
|
211
|
+
productType?: string;
|
|
212
|
+
vendor?: string;
|
|
213
|
+
tag?: string;
|
|
214
|
+
}>;
|
|
215
|
+
}
|
|
216
|
+
|
|
217
|
+
// Get multiple products by handles
|
|
218
|
+
getProductsByHandles(params: IProductsByHandlesRequest, options?: IOptionsRequest): Promise<IResponse>
|
|
219
|
+
|
|
220
|
+
interface IProductsByHandlesRequest {
|
|
221
|
+
handles: string[];
|
|
222
|
+
}
|
|
223
|
+
```
|
|
224
|
+
|
|
225
|
+
### Collection Operations
|
|
226
|
+
|
|
227
|
+
```typescript
|
|
228
|
+
// Get single collection by ID or handle
|
|
229
|
+
getCollection(params: ISingleCollectionRequest, options?: IOptionsRequest): Promise<IResponse>
|
|
230
|
+
|
|
231
|
+
interface ISingleCollectionRequest {
|
|
232
|
+
id?: string;
|
|
233
|
+
handle?: string;
|
|
234
|
+
productLimit?: number;
|
|
235
|
+
productSortKey?: string;
|
|
236
|
+
productReverse?: boolean;
|
|
237
|
+
filters?: Array<{
|
|
238
|
+
available?: boolean;
|
|
239
|
+
price?: { min?: number; max?: number };
|
|
240
|
+
productType?: string;
|
|
241
|
+
vendor?: string;
|
|
242
|
+
tag?: string;
|
|
243
|
+
}>;
|
|
244
|
+
}
|
|
245
|
+
|
|
246
|
+
// Get multiple collections with filtering and pagination
|
|
247
|
+
getCollections(params: ICollectionQueryRequest, options?: IOptionsRequest): Promise<IResponse>
|
|
248
|
+
|
|
249
|
+
interface ICollectionQueryRequest {
|
|
250
|
+
first?: number;
|
|
251
|
+
last?: number;
|
|
252
|
+
after?: string;
|
|
253
|
+
before?: string;
|
|
254
|
+
query?: string;
|
|
255
|
+
sortKey?: string;
|
|
256
|
+
reverse?: boolean;
|
|
257
|
+
}
|
|
258
|
+
|
|
259
|
+
// Get multiple collections by handles with individual query parameters
|
|
260
|
+
getCollectionsByHandels(params: ICollectionsByhandlesRequest, options?: IOptionsRequest): Promise<IResponse>
|
|
261
|
+
|
|
262
|
+
interface ICollectionsByhandlesRequest {
|
|
263
|
+
handles: string[];
|
|
264
|
+
first?: number;
|
|
265
|
+
last?: number;
|
|
266
|
+
after?: string;
|
|
267
|
+
before?: string;
|
|
268
|
+
query?: string;
|
|
269
|
+
reverse?: boolean;
|
|
270
|
+
sortKey?: string;
|
|
271
|
+
productLimit?: number;
|
|
272
|
+
productSortKey?: string;
|
|
273
|
+
productReverse?: boolean;
|
|
274
|
+
filters?: Array<{
|
|
275
|
+
available?: boolean;
|
|
276
|
+
price?: { min?: number; max?: number };
|
|
277
|
+
productType?: string;
|
|
278
|
+
vendor?: string;
|
|
279
|
+
tag?: string;
|
|
280
|
+
}>;
|
|
281
|
+
}
|
|
282
|
+
```
|
|
283
|
+
|
|
284
|
+
### Cart Operations
|
|
285
|
+
|
|
286
|
+
```typescript
|
|
287
|
+
// Create a new cart
|
|
288
|
+
createCart(options?: IOptionsRequest): Promise<IResponse>
|
|
289
|
+
|
|
290
|
+
// Get cart by ID
|
|
291
|
+
getCart(params: ISingleCartRequest, options?: IOptionsRequest): Promise<IResponse>
|
|
292
|
+
|
|
293
|
+
interface ISingleCartRequest {
|
|
294
|
+
id: string;
|
|
295
|
+
}
|
|
296
|
+
|
|
297
|
+
// Update cart
|
|
298
|
+
updateCart(params: IUpdateCartRequest, options?: IOptionsRequest): Promise<IResponse>
|
|
299
|
+
|
|
300
|
+
interface IUpdateCartRequest {
|
|
301
|
+
id: string;
|
|
302
|
+
items: ICartItemRequest;
|
|
303
|
+
}
|
|
304
|
+
|
|
305
|
+
interface ICartItemRequest {
|
|
306
|
+
productId: string;
|
|
307
|
+
variantId: string;
|
|
308
|
+
quantity: number;
|
|
309
|
+
sellingPlanId?: string;
|
|
310
|
+
attributes?: Array<{
|
|
311
|
+
key: string;
|
|
312
|
+
value: string;
|
|
313
|
+
}>;
|
|
314
|
+
}
|
|
315
|
+
|
|
316
|
+
// Add items to cart
|
|
317
|
+
addToCart(params: IAddToCartRequest, options?: IOptionsRequest): Promise<IResponse>
|
|
318
|
+
|
|
319
|
+
interface IAddToCartRequest {
|
|
320
|
+
id: string;
|
|
321
|
+
items: ICartItemRequest[];
|
|
322
|
+
}
|
|
323
|
+
|
|
324
|
+
// Remove items from cart
|
|
325
|
+
removeFromCart(params: IRemoveFromCartRequest, options?: IOptionsRequest): Promise<IResponse>
|
|
326
|
+
|
|
327
|
+
interface IRemoveFromCartRequest {
|
|
328
|
+
id: string;
|
|
329
|
+
itemIds: string[];
|
|
330
|
+
}
|
|
331
|
+
```
|
|
332
|
+
|
|
333
|
+
### Order Operations
|
|
334
|
+
|
|
335
|
+
```typescript
|
|
336
|
+
// Get single order by ID (Admin only)
|
|
337
|
+
getOrder(params: ISingleOrderRequest, options?: IOptionsRequest): Promise<IResponse>
|
|
338
|
+
|
|
339
|
+
interface ISingleOrderRequest {
|
|
340
|
+
id: string;
|
|
341
|
+
}
|
|
342
|
+
|
|
343
|
+
// Get multiple orders with filtering (Admin only)
|
|
344
|
+
getOrders(params: IOrderQueryRequest, options?: IOptionsRequest): Promise<IResponse>
|
|
345
|
+
|
|
346
|
+
interface IOrderQueryRequest {
|
|
347
|
+
first?: number;
|
|
348
|
+
last?: number;
|
|
349
|
+
after?: string;
|
|
350
|
+
before?: string;
|
|
351
|
+
query?: string;
|
|
352
|
+
sortKey?: string;
|
|
353
|
+
reverse?: boolean;
|
|
354
|
+
}
|
|
355
|
+
|
|
356
|
+
// Create new order (Admin only)
|
|
357
|
+
createOrder(params: IOrderRequest, options?: IOptionsRequest): Promise<IResponse>
|
|
358
|
+
|
|
359
|
+
interface IOrderRequest {
|
|
360
|
+
lineItems: Array<{
|
|
361
|
+
variantId: string;
|
|
362
|
+
quantity: number;
|
|
363
|
+
}>;
|
|
364
|
+
customer?: {
|
|
365
|
+
email: string;
|
|
366
|
+
firstName?: string;
|
|
367
|
+
lastName?: string;
|
|
368
|
+
};
|
|
369
|
+
shippingAddress?: {
|
|
370
|
+
address1: string;
|
|
371
|
+
city: string;
|
|
372
|
+
province: string;
|
|
373
|
+
country: string;
|
|
374
|
+
zip: string;
|
|
375
|
+
};
|
|
376
|
+
}
|
|
377
|
+
|
|
378
|
+
// Update existing order (Admin only)
|
|
379
|
+
updateOrder(params: IUpdateOrderRequest, options?: IOptionsRequest): Promise<IResponse>
|
|
380
|
+
|
|
381
|
+
interface IUpdateOrderRequest {
|
|
382
|
+
id: string;
|
|
383
|
+
data: Partial<IOrderRequest>;
|
|
384
|
+
}
|
|
385
|
+
|
|
386
|
+
// Get customer order history
|
|
387
|
+
getOrderHistory(params: IOrderHistoryRequest, options?: IOptionsRequest): Promise<IResponse>
|
|
388
|
+
|
|
389
|
+
interface IOrderHistoryRequest {
|
|
390
|
+
customerAccessToken: string;
|
|
391
|
+
page?: number;
|
|
392
|
+
limit?: number;
|
|
393
|
+
}
|
|
394
|
+
|
|
395
|
+
// Get specific customer order
|
|
396
|
+
getOrderById(params: IOrderByIdRequest, options?: IOptionsRequest): Promise<IResponse>
|
|
397
|
+
|
|
398
|
+
interface IOrderByIdRequest {
|
|
399
|
+
customerAccessToken: string;
|
|
400
|
+
orderId: string;
|
|
401
|
+
}
|
|
402
|
+
```
|
|
403
|
+
|
|
404
|
+
### Customer Operations
|
|
405
|
+
|
|
406
|
+
```typescript
|
|
407
|
+
// Get single customer by ID (Admin only)
|
|
408
|
+
getCustomer(params: ISingleCustomerRequest, options?: IOptionsRequest): Promise<IResponse>
|
|
409
|
+
|
|
410
|
+
interface ISingleCustomerRequest {
|
|
411
|
+
id: string;
|
|
412
|
+
}
|
|
413
|
+
|
|
414
|
+
// Get multiple customers (Admin only)
|
|
415
|
+
getCustomers(params: ICustomerQueryRequest, options?: IOptionsRequest): Promise<IResponse>
|
|
416
|
+
|
|
417
|
+
// Create new customer
|
|
418
|
+
createCustomer(params: ICustomerRequest, options?: IOptionsRequest): Promise<IResponse>
|
|
419
|
+
|
|
420
|
+
interface ICustomerRequest {
|
|
421
|
+
email: string;
|
|
422
|
+
firstName?: string;
|
|
423
|
+
lastName?: string;
|
|
424
|
+
phone?: string;
|
|
425
|
+
password?: string;
|
|
426
|
+
acceptsMarketing?: boolean;
|
|
427
|
+
}
|
|
428
|
+
|
|
429
|
+
// Update existing customer
|
|
430
|
+
updateCustomer(params: IUpdateCustomerRequest, options?: IOptionsRequest): Promise<IResponse>
|
|
431
|
+
|
|
432
|
+
interface IUpdateCustomerRequest {
|
|
433
|
+
id: string;
|
|
434
|
+
data: Partial<ICustomerRequest>;
|
|
435
|
+
}
|
|
436
|
+
|
|
437
|
+
// Get customer profile (Shopify only)
|
|
438
|
+
getCustomerProfile(params: ICustomerProfileRequest, options?: IOptionsRequest): Promise<IResponse>
|
|
439
|
+
|
|
440
|
+
interface ICustomerProfileRequest {
|
|
441
|
+
customerAccessToken: string;
|
|
442
|
+
}
|
|
443
|
+
```
|
|
444
|
+
|
|
445
|
+
### Checkout Operations
|
|
446
|
+
|
|
447
|
+
```typescript
|
|
448
|
+
// Create checkout
|
|
449
|
+
createCheckout(params: ICreateCheckoutRequest, options?: IOptionsRequest): Promise<IResponse>
|
|
450
|
+
|
|
451
|
+
interface ICreateCheckoutRequest {
|
|
452
|
+
lineItems?: Array<{
|
|
453
|
+
variantId: string;
|
|
454
|
+
quantity: number;
|
|
455
|
+
}>;
|
|
456
|
+
email?: string;
|
|
457
|
+
shippingAddress?: {
|
|
458
|
+
address1: string;
|
|
459
|
+
city: string;
|
|
460
|
+
province: string;
|
|
461
|
+
country: string;
|
|
462
|
+
zip: string;
|
|
463
|
+
};
|
|
464
|
+
}
|
|
465
|
+
```
|
|
466
|
+
|
|
467
|
+
### Blog/Article Operations (Shopify only)
|
|
468
|
+
|
|
469
|
+
```typescript
|
|
470
|
+
// Get single article
|
|
471
|
+
getArticle(params?: IGetArticleRequest, options?: IOptionsRequest): Promise<IResponse>
|
|
472
|
+
|
|
473
|
+
interface IGetArticleRequest {
|
|
474
|
+
blogHandle?: string;
|
|
475
|
+
articleHandle?: string;
|
|
476
|
+
first?: number;
|
|
477
|
+
}
|
|
478
|
+
|
|
479
|
+
// Get blog articles
|
|
480
|
+
getBlogArticles(params: IBlogArticleRequest, options?: IOptionsRequest): Promise<IResponse>
|
|
481
|
+
|
|
482
|
+
interface IBlogArticleRequest {
|
|
483
|
+
blogHandle: string;
|
|
484
|
+
first?: number;
|
|
485
|
+
after?: string;
|
|
486
|
+
}
|
|
487
|
+
|
|
488
|
+
// Get trending articles
|
|
489
|
+
getTrendingArticles(params: ITrendingArticleRequest, options?: IOptionsRequest): Promise<IResponse>
|
|
490
|
+
|
|
491
|
+
interface ITrendingArticleRequest {
|
|
492
|
+
first?: number;
|
|
493
|
+
sortBy?: string;
|
|
494
|
+
}
|
|
495
|
+
|
|
496
|
+
// Get article by handle
|
|
497
|
+
getArticleByHandle(params: IArticleByHandleRequest, options?: IOptionsRequest): Promise<IResponse>
|
|
498
|
+
|
|
499
|
+
interface IArticleByHandleRequest {
|
|
500
|
+
blogHandle: string;
|
|
501
|
+
articleHandle: string;
|
|
502
|
+
}
|
|
503
|
+
```
|
|
504
|
+
|
|
505
|
+
### Utility Operations
|
|
506
|
+
|
|
507
|
+
```typescript
|
|
508
|
+
// Custom GraphQL request (Shopify only)
|
|
509
|
+
graphqlRequest(query: string, variables?: Record<string, any>): Promise<IResponse>
|
|
510
|
+
|
|
511
|
+
// Custom HTTP fetch request
|
|
512
|
+
fetchRequest(url: string, options?: IFetchOptionsRequest): Promise<IResponse>
|
|
513
|
+
|
|
514
|
+
interface IFetchOptionsRequest {
|
|
515
|
+
method?: string;
|
|
516
|
+
headers?: Record<string, string>;
|
|
517
|
+
body?: string;
|
|
518
|
+
params?: Record<string, string>;
|
|
519
|
+
}
|
|
520
|
+
```
|
|
521
|
+
|
|
522
|
+
## Usage Examples
|
|
523
|
+
|
|
524
|
+
### Product Operations
|
|
525
|
+
|
|
526
|
+
```typescript
|
|
527
|
+
// Get single product
|
|
528
|
+
const product = await client.getProduct({ handle: "product-handle" });
|
|
529
|
+
|
|
530
|
+
// Get single product with custom headers
|
|
531
|
+
const product = await client.getProduct(
|
|
532
|
+
{ handle: "product-handle" },
|
|
533
|
+
{ headers: { "X-Custom-Header": "value" } }
|
|
534
|
+
);
|
|
535
|
+
|
|
536
|
+
// Get multiple products
|
|
537
|
+
const products = await client.getProducts({
|
|
538
|
+
first: 20,
|
|
539
|
+
query: "shirt",
|
|
540
|
+
sortKey: "TITLE"
|
|
541
|
+
});
|
|
542
|
+
|
|
543
|
+
// Get products by handles
|
|
544
|
+
const products = await client.getProductsByHandles({
|
|
545
|
+
handles: ["handle1", "handle2"]
|
|
546
|
+
});
|
|
547
|
+
```
|
|
548
|
+
|
|
549
|
+
### Collection Operations
|
|
550
|
+
|
|
551
|
+
```typescript
|
|
552
|
+
// Get single collection
|
|
553
|
+
const collection = await client.getCollection({ handle: "collection-handle" });
|
|
554
|
+
|
|
555
|
+
// Get multiple collections
|
|
556
|
+
const collections = await client.getCollections({ first: 10 });
|
|
557
|
+
|
|
558
|
+
// Get collections by handles with shared parameters
|
|
559
|
+
const collections = await client.getCollectionsByHandels({
|
|
560
|
+
handles: ["featured-products", "sale-items", "new-arrivals"],
|
|
561
|
+
first: 10,
|
|
562
|
+
productLimit: 20,
|
|
563
|
+
filters: [{ available: true }]
|
|
564
|
+
});
|
|
565
|
+
```
|
|
566
|
+
|
|
567
|
+
### Cart Operations
|
|
568
|
+
|
|
569
|
+
```typescript
|
|
570
|
+
// Create cart
|
|
571
|
+
const cart = await client.createCart();
|
|
572
|
+
|
|
573
|
+
// Get cart
|
|
574
|
+
const cart = await client.getCart({ id: "cart-id" });
|
|
575
|
+
|
|
576
|
+
// Add items to cart
|
|
577
|
+
const updatedCart = await client.addToCart({
|
|
578
|
+
id: "cart-id",
|
|
579
|
+
items: [
|
|
580
|
+
{
|
|
581
|
+
productId: "product-id",
|
|
582
|
+
variantId: "variant-id",
|
|
583
|
+
quantity: 1
|
|
584
|
+
}
|
|
585
|
+
]
|
|
586
|
+
});
|
|
587
|
+
|
|
588
|
+
// Update cart
|
|
589
|
+
const updatedCart = await client.updateCart({
|
|
590
|
+
id: "cart-id",
|
|
591
|
+
data: {
|
|
592
|
+
items: [
|
|
593
|
+
{
|
|
594
|
+
productId: "product-id",
|
|
595
|
+
variantId: "variant-id",
|
|
596
|
+
quantity: 2
|
|
597
|
+
}
|
|
598
|
+
]
|
|
599
|
+
}
|
|
600
|
+
});
|
|
601
|
+
|
|
602
|
+
// Remove items from cart
|
|
603
|
+
const updatedCart = await client.removeFromCart({
|
|
604
|
+
id: "cart-id",
|
|
605
|
+
itemIds: ["line-id"]
|
|
606
|
+
});
|
|
607
|
+
```
|
|
608
|
+
|
|
609
|
+
### Order Operations
|
|
610
|
+
|
|
611
|
+
```typescript
|
|
612
|
+
// Get order history
|
|
613
|
+
const orders = await client.getOrderHistory({
|
|
614
|
+
customerAccessToken: "customer-access-token",
|
|
615
|
+
page: 1,
|
|
616
|
+
limit: 10
|
|
617
|
+
});
|
|
618
|
+
|
|
619
|
+
// Get specific order
|
|
620
|
+
const order = await client.getOrderById({
|
|
621
|
+
customerAccessToken: "customer-access-token",
|
|
622
|
+
orderId: "order-id"
|
|
623
|
+
});
|
|
624
|
+
```
|
|
625
|
+
|
|
626
|
+
### Framework Integration Examples
|
|
627
|
+
|
|
628
|
+
#### Next.js App Router (Server-Side)
|
|
629
|
+
|
|
630
|
+
```typescript
|
|
631
|
+
// app/products/[handle]/page.tsx
|
|
632
|
+
import { createCommerceClient } from '@shopkit/data-layer';
|
|
633
|
+
|
|
634
|
+
export default async function ProductPage({ params }: { params: { handle: string } }) {
|
|
635
|
+
const client = createCommerceClient(shopifyConfig);
|
|
636
|
+
|
|
637
|
+
const response = await client.getProduct({ handle: params.handle });
|
|
638
|
+
|
|
639
|
+
if (!response.success) {
|
|
640
|
+
return <div>Error: {response.error?.message}</div>;
|
|
641
|
+
}
|
|
642
|
+
|
|
643
|
+
const product = response.data;
|
|
644
|
+
|
|
645
|
+
return (
|
|
646
|
+
<div>
|
|
647
|
+
<h1>{product.title}</h1>
|
|
648
|
+
<p>{product.description}</p>
|
|
649
|
+
<div>Price: {product.priceRange.minVariantPrice.amount} {product.priceRange.minVariantPrice.currencyCode}</div>
|
|
650
|
+
</div>
|
|
651
|
+
);
|
|
652
|
+
}
|
|
653
|
+
```
|
|
654
|
+
|
|
655
|
+
#### API Route Usage
|
|
656
|
+
|
|
657
|
+
```typescript
|
|
658
|
+
// app/api/products/route.ts
|
|
659
|
+
import { NextRequest } from 'next/server';
|
|
660
|
+
import { createCommerceClient } from '@shopkit/data-layer';
|
|
661
|
+
|
|
662
|
+
export async function GET(request: NextRequest) {
|
|
663
|
+
const { searchParams } = new URL(request.url);
|
|
664
|
+
const client = createCommerceClient(shopifyConfig);
|
|
665
|
+
|
|
666
|
+
const response = await client.getProducts({
|
|
667
|
+
first: 10,
|
|
668
|
+
query: searchParams.get('query') || undefined
|
|
669
|
+
});
|
|
670
|
+
|
|
671
|
+
return Response.json(response);
|
|
672
|
+
}
|
|
673
|
+
```
|
|
674
|
+
|
|
675
|
+
#### Client-Side Usage
|
|
676
|
+
|
|
677
|
+
```typescript
|
|
678
|
+
'use client';
|
|
679
|
+
|
|
680
|
+
import { useState, useEffect } from 'react';
|
|
681
|
+
import { IResponse } from '@shopkit/data-layer';
|
|
682
|
+
|
|
683
|
+
export function useProducts(query?: string) {
|
|
684
|
+
const [response, setResponse] = useState<IResponse | null>(null);
|
|
685
|
+
const [loading, setLoading] = useState(true);
|
|
686
|
+
|
|
687
|
+
useEffect(() => {
|
|
688
|
+
async function fetchProducts() {
|
|
689
|
+
try {
|
|
690
|
+
const res = await fetch(`/api/products?query=${query || ''}`);
|
|
691
|
+
const data = await res.json();
|
|
692
|
+
setResponse(data);
|
|
693
|
+
} catch (error) {
|
|
694
|
+
setResponse({
|
|
695
|
+
success: false,
|
|
696
|
+
message: 'Failed to fetch products',
|
|
697
|
+
error: { message: error instanceof Error ? error.message : 'Unknown error' }
|
|
698
|
+
});
|
|
699
|
+
} finally {
|
|
700
|
+
setLoading(false);
|
|
701
|
+
}
|
|
702
|
+
}
|
|
703
|
+
|
|
704
|
+
fetchProducts();
|
|
705
|
+
}, [query]);
|
|
706
|
+
|
|
707
|
+
return { response, loading };
|
|
708
|
+
}
|
|
709
|
+
```
|
|
710
|
+
|
|
711
|
+
## Platform Support
|
|
712
|
+
|
|
713
|
+
### Shopify Adapter
|
|
714
|
+
- ✅ **Products**: Full support for product operations
|
|
715
|
+
- ✅ **Collections**: Full support for collection operations
|
|
716
|
+
- ✅ **Cart**: Full cart management
|
|
717
|
+
- ✅ **Orders**: Customer order history and details
|
|
718
|
+
- ✅ **Blog**: Article and blog operations
|
|
719
|
+
- ✅ **GraphQL**: Custom GraphQL queries
|
|
720
|
+
- ✅ **Customer**: Customer profile access
|
|
721
|
+
|
|
722
|
+
### Custom Backend Adapter
|
|
723
|
+
- ✅ **Products**: Full support for product operations
|
|
724
|
+
- ✅ **Collections**: Full support for collection operations
|
|
725
|
+
- ✅ **Cart**: Full cart management
|
|
726
|
+
- ✅ **Orders**: Customer order history and details
|
|
727
|
+
- ✅ **Checkout**: Basic checkout creation
|
|
728
|
+
- ❌ **Blog**: Not implemented
|
|
729
|
+
- ❌ **GraphQL**: Not available
|
|
730
|
+
|
|
731
|
+
### Method Support Matrix
|
|
732
|
+
|
|
733
|
+
| Method | Custom Adapter | Shopify Adapter | Notes |
|
|
734
|
+
|--------|----------------|-----------------|-------|
|
|
735
|
+
| **Product Operations** |
|
|
736
|
+
| `getProduct` | ✅ Implemented | ✅ Implemented | Core product retrieval |
|
|
737
|
+
| `getProducts` | ✅ Implemented | ✅ Implemented | Product listing with filters |
|
|
738
|
+
| `getProductsByHandles` | ✅ Implemented | ✅ Implemented | Batch product retrieval |
|
|
739
|
+
| **Collection Operations** |
|
|
740
|
+
| `getCollection` | ✅ Implemented | ✅ Implemented | Single collection retrieval |
|
|
741
|
+
| `getCollections` | ✅ Implemented | ✅ Implemented | Collection listing |
|
|
742
|
+
| `getCollectionsByHandels` | ✅ Implemented | ✅ Implemented | Batch collection retrieval |
|
|
743
|
+
| **Order Operations** |
|
|
744
|
+
| `getOrder` | ❌ (Error thrown) | ❌ (NotImplemented) | Single order retrieval |
|
|
745
|
+
| `getOrders` | ❌ (Error thrown) | ❌ (NotImplemented) | Order listing |
|
|
746
|
+
| `createOrder` | ❌ (Error thrown) | ❌ (NotImplemented) | Order creation |
|
|
747
|
+
| `updateOrder` | ❌ (Error thrown) | ❌ (NotImplemented) | Order updates |
|
|
748
|
+
| `getOrderHistory` | ✅ Implemented | ✅ Implemented | Customer order history |
|
|
749
|
+
| `getOrderById` | ✅ Implemented | ✅ Implemented | Customer specific order |
|
|
750
|
+
| **Customer Operations** |
|
|
751
|
+
| `getCustomer` | ❌ (Error thrown) | ❌ (NotImplemented) | Single customer retrieval |
|
|
752
|
+
| `getCustomers` | ❌ (Error thrown) | ❌ (NotImplemented) | Customer listing |
|
|
753
|
+
| `createCustomer` | ❌ (Error thrown) | ❌ (NotImplemented) | Customer creation |
|
|
754
|
+
| `updateCustomer` | ❌ (Error thrown) | ❌ (NotImplemented) | Customer updates |
|
|
755
|
+
| `getCustomerProfile` | ❌ (Not available) | ✅ Implemented | Shopify-specific method |
|
|
756
|
+
| **Cart Operations** |
|
|
757
|
+
| `getCart` | ✅ Implemented | ✅ Implemented | Cart retrieval |
|
|
758
|
+
| `createCart` | ✅ Implemented | ✅ Implemented | Cart creation |
|
|
759
|
+
| `updateCart` | ✅ Implemented | ✅ Implemented | Cart updates |
|
|
760
|
+
| `addToCart` | ✅ Implemented | ✅ Implemented | Add items to cart |
|
|
761
|
+
| `removeFromCart` | ✅ Implemented | ✅ Implemented | Remove items from cart |
|
|
762
|
+
| **Checkout Operations** |
|
|
763
|
+
| `createCheckout` | ✅ Implemented | ❌ (NotImplemented) | Checkout creation |
|
|
764
|
+
| **Article/Blog Operations** |
|
|
765
|
+
| `getArticle` | ❌ (NotImplemented) | ✅ Implemented | Single article retrieval |
|
|
766
|
+
| `getBlogArticles` | ❌ (NotImplemented) | ✅ Implemented | Blog article listing |
|
|
767
|
+
| `getTrendingArticles` | ❌ (NotImplemented) | ✅ Implemented | Trending articles |
|
|
768
|
+
| `getArticleByHandle` | ❌ (NotImplemented) | ✅ Implemented | Article by handle |
|
|
769
|
+
| **Utility Operations** |
|
|
770
|
+
| `graphqlRequest` | ❌ (NotImplemented) | ✅ Implemented | GraphQL utility |
|
|
771
|
+
| `fetchRequest` | ✅ Inherited | ✅ Inherited | HTTP fetch utility |
|
|
772
|
+
|
|
773
|
+
## Error Handling
|
|
774
|
+
|
|
775
|
+
The data layer provides comprehensive error handling:
|
|
776
|
+
|
|
777
|
+
```typescript
|
|
778
|
+
const response = await client.getProduct({ handle: "invalid-handle" });
|
|
779
|
+
|
|
780
|
+
if (!response.success) {
|
|
781
|
+
console.error("Error:", response.error?.message);
|
|
782
|
+
|
|
783
|
+
// Handle specific error types
|
|
784
|
+
if (response.error?.details?.name === "NotFoundError") {
|
|
785
|
+
// Handle product not found
|
|
786
|
+
}
|
|
787
|
+
}
|
|
788
|
+
```
|
|
789
|
+
|
|
790
|
+
## Best Practices
|
|
791
|
+
|
|
792
|
+
1. **Always check `response.success`** before accessing `data`
|
|
793
|
+
2. **Use TypeScript** for full type safety and better developer experience
|
|
794
|
+
3. **Enable logging** during development for better debugging
|
|
795
|
+
4. **Handle errors gracefully** with proper fallbacks
|
|
796
|
+
5. **Use environment variables** for sensitive configuration data
|
|
797
|
+
6. **Implement proper caching** for frequently accessed data
|
|
798
|
+
7. **Use custom queries** sparingly and only when standard methods are insufficient
|
|
799
|
+
8. **Follow the standardized method signature pattern** for consistency
|
|
800
|
+
|
|
801
|
+
## Examples
|
|
802
|
+
|
|
803
|
+
For complete examples and usage patterns, see the [data layer example app](../../apps/data-layer-example).
|
|
804
|
+
|
|
805
|
+
### Data Layer Example App Features
|
|
806
|
+
|
|
807
|
+
The example application includes several user experience improvements:
|
|
808
|
+
|
|
809
|
+
#### Enhanced JSON Input Fields
|
|
810
|
+
|
|
811
|
+
The example app provides improved textarea formatting for complex JSON payloads:
|
|
812
|
+
|
|
813
|
+
- **Add to Cart**: Multi-line textarea with formatted JSON structure for items array
|
|
814
|
+
- **Update Cart**: Enhanced textarea for cart item modifications with proper formatting
|
|
815
|
+
- **Create Checkout**: Improved textarea for checkout payload with correct interface structure
|
|
816
|
+
|
|
817
|
+
**Example Add to Cart Payload Format:**
|
|
818
|
+
```json
|
|
819
|
+
[
|
|
820
|
+
{
|
|
821
|
+
"productId": "gid://shopify/Product/123",
|
|
822
|
+
"variantId": "gid://shopify/ProductVariant/123",
|
|
823
|
+
"quantity": 1,
|
|
824
|
+
"sellingPlanId": "selling-plan-id",
|
|
825
|
+
"attributes": [
|
|
826
|
+
{
|
|
827
|
+
"key": "gift-wrap",
|
|
828
|
+
"value": "true"
|
|
829
|
+
}
|
|
830
|
+
]
|
|
831
|
+
}
|
|
832
|
+
]
|
|
833
|
+
```
|
|
834
|
+
|
|
835
|
+
**Example Create Checkout Payload Format:**
|
|
836
|
+
```json
|
|
837
|
+
{
|
|
838
|
+
"cart_token": "cart-token-here",
|
|
839
|
+
"checkout_id": "checkout-id-here",
|
|
840
|
+
"attributes": {
|
|
841
|
+
"email": "customer@example.com",
|
|
842
|
+
"note": "Special instructions",
|
|
843
|
+
"phone": "+1234567890",
|
|
844
|
+
"custom_field": "custom_value"
|
|
845
|
+
}
|
|
846
|
+
}
|
|
847
|
+
```
|
|
848
|
+
|
|
849
|
+
These improvements provide:
|
|
850
|
+
- **Better Readability**: Multi-line JSON with proper indentation
|
|
851
|
+
- **Larger Input Areas**: Textarea fields instead of single-line inputs
|
|
852
|
+
- **Complete Examples**: Shows all available fields and proper structure
|
|
853
|
+
- **Error Prevention**: Properly formatted examples reduce JSON syntax errors
|
|
854
|
+
|
|
855
|
+
## License
|
|
856
|
+
|
|
857
|
+
MIT License - see the [LICENSE](LICENSE) file for details.
|