@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 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.