@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.
@@ -0,0 +1,598 @@
1
+ /**
2
+ * Enums for the commerce library
3
+ */
4
+ declare enum EOrderStatus {
5
+ PENDING = "PENDING",
6
+ PROCESSING = "PROCESSING",
7
+ FULFILLED = "FULFILLED",
8
+ COMPLETED = "COMPLETED",
9
+ CANCELLED = "CANCELLED",
10
+ REFUNDED = "REFUNDED"
11
+ }
12
+ declare enum EProductSortKey {
13
+ TITLE = "TITLE",
14
+ PRICE = "PRICE",
15
+ CREATED_AT = "CREATED_AT",
16
+ UPDATED_AT = "UPDATED_AT",
17
+ BEST_SELLING = "BEST_SELLING",
18
+ MANUAL = "MANUAL"
19
+ }
20
+ declare enum ECollectionSortKey {
21
+ TITLE = "TITLE",
22
+ CREATED_AT = "CREATED_AT",
23
+ UPDATED_AT = "UPDATED_AT",
24
+ MANUAL = "MANUAL"
25
+ }
26
+ declare enum EOrderSortKey {
27
+ CREATED_AT = "CREATED_AT",
28
+ UPDATED_AT = "UPDATED_AT",
29
+ ORDER_NUMBER = "ORDER_NUMBER",
30
+ TOTAL_PRICE = "TOTAL_PRICE"
31
+ }
32
+ declare enum EAvailability {
33
+ IN_STOCK = "IN_STOCK",
34
+ OUT_OF_STOCK = "OUT_OF_STOCK",
35
+ PREORDER = "PREORDER"
36
+ }
37
+ declare enum EPaymentStatus {
38
+ PENDING = "PENDING",
39
+ AUTHORIZED = "AUTHORIZED",
40
+ PAID = "PAID",
41
+ PARTIALLY_PAID = "PARTIALLY_PAID",
42
+ REFUNDED = "REFUNDED",
43
+ VOIDED = "VOIDED"
44
+ }
45
+ declare enum EFulfillmentStatus {
46
+ UNFULFILLED = "UNFULFILLED",
47
+ PARTIAL = "PARTIAL",
48
+ FULFILLED = "FULFILLED",
49
+ RESTOCKED = "RESTOCKED"
50
+ }
51
+
52
+ /**
53
+ * Common data models for the commerce library
54
+ */
55
+ /**
56
+ * Represents a monetary value with currency
57
+ */
58
+ interface IMoney {
59
+ amount: number;
60
+ currencyCode: string;
61
+ }
62
+ /**
63
+ * Represents an image
64
+ */
65
+ interface IImage {
66
+ id: string;
67
+ url: string;
68
+ altText?: string;
69
+ width?: number;
70
+ height?: number;
71
+ }
72
+ /**
73
+ * Represents a physical address
74
+ */
75
+ interface IAddress {
76
+ id?: string;
77
+ firstName?: string;
78
+ lastName?: string;
79
+ company?: string;
80
+ address1: string;
81
+ address2?: string;
82
+ city: string;
83
+ province?: string;
84
+ country: string;
85
+ zip: string;
86
+ phone?: string;
87
+ }
88
+ /**
89
+ * Metafield interface for extensibility
90
+ */
91
+ interface IMetafield {
92
+ id: string;
93
+ key: string;
94
+ value: string;
95
+ type: string;
96
+ namespace: string;
97
+ }
98
+ /**
99
+ * SEO interface
100
+ */
101
+ interface ISeo {
102
+ title?: string;
103
+ description?: string;
104
+ }
105
+ /**
106
+ * Common pagination parameters for requests
107
+ */
108
+ interface IPaginationParams {
109
+ /** Cursor for pagination - points to the item after which to start returning results */
110
+ after?: string;
111
+ /** Cursor for pagination - points to the item before which to start returning results */
112
+ before?: string;
113
+ /** Number of items to return from the beginning (used with 'after') */
114
+ first?: number;
115
+ /** Number of items to return from the end (used with 'before') */
116
+ last?: number;
117
+ }
118
+
119
+ /**
120
+ * Standardized request options for all commerce operations
121
+ * Provides request metadata like headers, timeouts, and cancellation signals
122
+ */
123
+ interface IOptionsRequest {
124
+ /**
125
+ * API version to use for the request (e.g., "v1", "v2")
126
+ * If not provided, defaults to the adapter's default version
127
+ */
128
+ version?: string;
129
+ /**
130
+ * Custom headers to include with the request
131
+ */
132
+ headers?: Record<string, string>;
133
+ /**
134
+ * Query parameters for REST API requests
135
+ */
136
+ params?: Record<string, any>;
137
+ /**
138
+ * GraphQL query string (for GraphQL-based adapters like Shopify)
139
+ */
140
+ query?: string;
141
+ /**
142
+ * GraphQL variables (for GraphQL-based adapters like Shopify)
143
+ */
144
+ variables?: Record<string, any>;
145
+ /**
146
+ * Metadata hints to adapters (non-sent)
147
+ * Examples: { preferGraphQL: true, useCache: false, retryCount: 3 }
148
+ */
149
+ meta?: Record<string, any>;
150
+ /**
151
+ * Request timeout in milliseconds
152
+ */
153
+ timeoutMs?: number;
154
+ /**
155
+ * AbortSignal for request cancellation
156
+ */
157
+ signal?: AbortSignal;
158
+ }
159
+ interface IFetchOptionsRequest {
160
+ method?: "GET" | "POST" | "PUT" | "DELETE" | "PATCH";
161
+ headers?: HeadersInit;
162
+ body?: BodyInit | null;
163
+ signal?: AbortSignal;
164
+ credentials?: "omit" | "same-origin" | "include";
165
+ mode?: RequestMode;
166
+ cache?: RequestCache;
167
+ keepalive?: boolean;
168
+ [key: string]: any;
169
+ }
170
+
171
+ /**
172
+ * Standardized API response interface
173
+ * Provides consistent response format across all adapters
174
+ */
175
+ interface IResponseMeta {
176
+ /** Pagination information for list responses */
177
+ pagination?: Record<string, any>;
178
+ /** Additional adapter-specific metadata */
179
+ [key: string]: any;
180
+ }
181
+ interface IResponse<T = any> {
182
+ /** Indicates if the operation was successful */
183
+ success: boolean;
184
+ /** Human-readable message describing the result */
185
+ message: string;
186
+ /** The actual response data, null if error occurred */
187
+ data: T | null;
188
+ /** Error information if the operation failed */
189
+ error?: any;
190
+ /** Additional metadata about the response */
191
+ meta?: IResponseMeta;
192
+ }
193
+
194
+ /**
195
+ * Product and Collection data models for the commerce library
196
+ * Unified models combining both product and collection functionality
197
+ */
198
+
199
+ /**
200
+ * Common query parameters used by both products and collections
201
+ */
202
+ interface IBaseQueryParams extends IPaginationParams {
203
+ /**
204
+ * Search query string. Supports various formats:
205
+ * - Simple text: "Guitar"
206
+ * - Field-specific: "title:Guitar", "vendor:Fender"
207
+ * - Multiple terms: "title:Guitar vendor:Fender"
208
+ */
209
+ query?: string;
210
+ /** Whether to reverse the sort order (default: false) */
211
+ reverse?: boolean;
212
+ }
213
+ /**
214
+ * Product filter parameters that can be applied within collections
215
+ */
216
+ interface IProductFilters {
217
+ price?: {
218
+ min?: number;
219
+ max?: number;
220
+ };
221
+ available?: boolean;
222
+ productType?: string;
223
+ vendor?: string;
224
+ tags?: string[];
225
+ }
226
+ /**
227
+ * Parameters for querying products
228
+ *
229
+ * @example Custom Backend Usage:
230
+ * ```typescript
231
+ * {
232
+ * "sortKey": "CREATED_AT",
233
+ * "query": "title:Guitar",
234
+ * "first": 10,
235
+ * "last": 10,
236
+ * "reverse": false,
237
+ * "after": "1"
238
+ * }
239
+ * ```
240
+ */
241
+ interface IProductQueryReqest extends IBaseQueryParams {
242
+ /**
243
+ * Sort key for ordering results
244
+ * Common values: "CREATED_AT", "UPDATED_AT", "TITLE", "PRICE", "BEST_SELLING"
245
+ */
246
+ sortKey?: EProductSortKey;
247
+ /** Filter by product availability (true = only available products) */
248
+ availableForSale?: boolean;
249
+ /** Filter by product type (e.g., "T-Shirt", "Shoes") */
250
+ productType?: string;
251
+ /** Filter by vendor/brand name */
252
+ vendor?: string;
253
+ /** Filter by product tags */
254
+ tags?: string[];
255
+ /** Filter by price range */
256
+ priceRange?: {
257
+ /** Minimum price */
258
+ min?: number;
259
+ /** Maximum price */
260
+ max?: number;
261
+ };
262
+ [key: string]: any;
263
+ }
264
+ /**
265
+ * Payload for retrieving a single product
266
+ */
267
+ interface ISingleProductRequest {
268
+ id?: string | number;
269
+ handle?: string;
270
+ }
271
+ /**
272
+ * Parameters for querying collections
273
+ *
274
+ * @example Custom Backend Usage:
275
+ * ```typescript
276
+ * {
277
+ * "sortKey": "CREATED_AT",
278
+ * "query": "title:Featured",
279
+ * "first": 10,
280
+ * "reverse": false,
281
+ * "productLimit": 20,
282
+ * "filters": [{ "available": true }]
283
+ * }
284
+ * ```
285
+ */
286
+ interface ICollectionQueryRequest extends IBaseQueryParams {
287
+ /**
288
+ * Sort key for ordering collections
289
+ * Common values: "CREATED_AT", "UPDATED_AT", "TITLE"
290
+ */
291
+ sortKey?: ECollectionSortKey;
292
+ /** Maximum number of products to return within each collection */
293
+ productLimit?: number;
294
+ /** Sort key for products within collections */
295
+ productSortKey?: string;
296
+ /** Whether to reverse the product sort order within collections */
297
+ productReverse?: boolean;
298
+ /** Filters to apply to products within collections */
299
+ filters?: IProductFilters[];
300
+ }
301
+ /**
302
+ * Payload for retrieving a single collection
303
+ */
304
+ interface ISingleCollectionRequest extends ICollectionQueryRequest {
305
+ id?: string | number;
306
+ handle?: string;
307
+ }
308
+ /**
309
+ * Common interface for batch collection requests
310
+ * Supports both custom API and Shopify GraphQL with consistent parameters
311
+ *
312
+ * @example Custom Backend Usage:
313
+ * ```typescript
314
+ * {
315
+ * "handles": ["featured-products", "sale-items"],
316
+ * "first": 10,
317
+ * "productLimit": 20,
318
+ * "filters": [{ "available": true }]
319
+ * }
320
+ * ```
321
+ */
322
+ interface ICollectionsByhandlesRequest extends ICollectionQueryRequest {
323
+ /** Array of collection handles to retrieve */
324
+ handles: string[];
325
+ }
326
+ interface ICollectionFilterRequest {
327
+ handle: string;
328
+ }
329
+
330
+ /**
331
+ * Order data models for the commerce library
332
+ */
333
+
334
+ /**
335
+ * Parameters for querying orders
336
+ */
337
+ interface IOrderQueryRequest {
338
+ ids?: string[];
339
+ customerId?: string;
340
+ status?: EOrderStatus;
341
+ paymentStatus?: EPaymentStatus;
342
+ fulfillmentStatus?: EFulfillmentStatus;
343
+ email?: string;
344
+ query?: string;
345
+ after?: string;
346
+ before?: string;
347
+ first?: number;
348
+ last?: number;
349
+ reverse?: boolean;
350
+ sortKey?: EOrderSortKey;
351
+ createdAtMin?: string;
352
+ createdAtMax?: string;
353
+ updatedAtMin?: string;
354
+ updatedAtMax?: string;
355
+ }
356
+ /**
357
+ * Request to create or update an order
358
+ */
359
+ interface IOrderRequest {
360
+ customerId?: string;
361
+ email: string;
362
+ phone?: string;
363
+ items: {
364
+ productId: string;
365
+ variantId: string;
366
+ quantity: number;
367
+ }[];
368
+ shippingAddress?: IAddress;
369
+ billingAddress?: IAddress;
370
+ note?: string;
371
+ tags?: string[];
372
+ }
373
+ /**
374
+ * Request to get a single order by ID
375
+ */
376
+ interface ISingleOrderRequest {
377
+ id: string;
378
+ }
379
+ /**
380
+ * Request to update an existing order
381
+ */
382
+ interface IUpdateOrderRequest {
383
+ id: string;
384
+ data: Partial<IOrderRequest>;
385
+ }
386
+ /**
387
+ * Request to get order history for a customer
388
+ */
389
+ interface IOrderHistoryRequest {
390
+ customerAccessToken: string;
391
+ page?: number;
392
+ limit?: number;
393
+ }
394
+ /**
395
+ * Request to get a specific order for a customer
396
+ */
397
+ interface IOrderByIdRequest {
398
+ customerAccessToken: string;
399
+ orderId: string;
400
+ }
401
+
402
+ /**
403
+ * Customer data models for the commerce library
404
+ */
405
+
406
+ /**
407
+ * Parameters for querying customers
408
+ */
409
+ interface ICustomerQueryRequest {
410
+ ids?: string[];
411
+ email?: string;
412
+ phone?: string;
413
+ query?: string;
414
+ after?: string;
415
+ before?: string;
416
+ first?: number;
417
+ last?: number;
418
+ reverse?: boolean;
419
+ sortKey?: string;
420
+ }
421
+ /**
422
+ * Request to create or update a customer
423
+ */
424
+ interface ICustomerRequest {
425
+ email: string;
426
+ firstName?: string;
427
+ lastName?: string;
428
+ phone?: string;
429
+ password?: string;
430
+ addresses?: IAddress[];
431
+ acceptsMarketing?: boolean;
432
+ tags?: string[];
433
+ note?: string;
434
+ }
435
+ /**
436
+ * Request to get a single customer by ID
437
+ */
438
+ interface ISingleCustomerRequest {
439
+ id: string;
440
+ }
441
+ /**
442
+ * Request to update an existing customer
443
+ */
444
+ interface IUpdateCustomerRequest {
445
+ id: string;
446
+ data: Partial<ICustomerRequest>;
447
+ }
448
+
449
+ /**
450
+ * Request to add an item to a cart
451
+ */
452
+ interface ICartItemRequest {
453
+ productId?: string;
454
+ variantId: string;
455
+ quantity: number;
456
+ sellingPlanId?: string;
457
+ attributes?: Array<{
458
+ key: string;
459
+ value: string;
460
+ }>;
461
+ }
462
+ /**
463
+ * Request to get a cart by ID
464
+ */
465
+ interface ISingleCartRequest {
466
+ id: string;
467
+ }
468
+ /**
469
+ * Request to add items to a cart
470
+ */
471
+ interface IAddToCartRequest {
472
+ id: string;
473
+ items: ICartItemRequest[];
474
+ }
475
+ /**
476
+ * Request to remove items from a cart
477
+ */
478
+ interface IRemoveFromCartRequest {
479
+ id: string;
480
+ itemIds: string[];
481
+ }
482
+ /**
483
+ * Request to update a cart with ID
484
+ */
485
+ interface IUpdateCartRequest {
486
+ id: string;
487
+ items: ICartItemRequest[];
488
+ }
489
+
490
+ /**
491
+ * Checkout data models for the commerce library
492
+ */
493
+
494
+ /**
495
+ * Request to update a checkout
496
+ */
497
+ interface ICheckoutUpdateRequest {
498
+ email?: string;
499
+ phone?: string;
500
+ shippingAddress?: IAddress;
501
+ billingAddress?: IAddress;
502
+ shippingMethodId?: string;
503
+ paymentMethodId?: string;
504
+ discountCodes?: string[];
505
+ note?: string;
506
+ customAttributes?: Array<{
507
+ key: string;
508
+ value: string;
509
+ }>;
510
+ }
511
+ /**
512
+ * Payment data for different payment methods
513
+ */
514
+ interface IPaymentRequest {
515
+ creditCard?: {
516
+ number: string;
517
+ expiryMonth: string;
518
+ expiryYear: string;
519
+ cvv: string;
520
+ holderName: string;
521
+ };
522
+ paypal?: {
523
+ payerId: string;
524
+ paymentId: string;
525
+ };
526
+ applePay?: {
527
+ token: string;
528
+ };
529
+ googlePay?: {
530
+ token: string;
531
+ };
532
+ bankTransfer?: {
533
+ accountNumber: string;
534
+ routingNumber: string;
535
+ accountHolderName: string;
536
+ };
537
+ }
538
+ /**
539
+ * Request to process a payment
540
+ */
541
+ interface IPaymentRequest {
542
+ paymentMethodId: string;
543
+ paymentData?: IPaymentRequest;
544
+ billingAddress?: IAddress;
545
+ savePaymentMethod?: boolean;
546
+ }
547
+ /**
548
+ * Request to create a checkout
549
+ */
550
+ interface ICreateCheckoutRequest {
551
+ payload: {
552
+ cart_token: string;
553
+ checkout_id?: string;
554
+ attributes?: {
555
+ [key: string]: any;
556
+ };
557
+ };
558
+ }
559
+
560
+ /**
561
+ * Parameters for blog article queries
562
+ */
563
+ interface IBlogArticleRequest {
564
+ category?: string;
565
+ limit?: number;
566
+ after?: string;
567
+ before?: string;
568
+ query?: string;
569
+ sortKey?: string;
570
+ reverse?: boolean;
571
+ }
572
+ /**
573
+ * Parameters for trending articles queries
574
+ */
575
+ interface ITrendingArticleRequest {
576
+ category?: string;
577
+ limit?: number;
578
+ query?: string;
579
+ }
580
+ /**
581
+ * Parameters for article by handle queries
582
+ */
583
+ interface IArticleByHandleRequest {
584
+ category: string;
585
+ articleHandle: string;
586
+ }
587
+ /**
588
+ * Parameters for getting all articles from all blogs
589
+ */
590
+ interface IGetArticleRequest {
591
+ blogLimit?: number;
592
+ articleLimit?: number;
593
+ query?: string;
594
+ sortKey?: string;
595
+ reverse?: boolean;
596
+ }
597
+
598
+ export { EAvailability, ECollectionSortKey, EFulfillmentStatus, EOrderSortKey, EOrderStatus, EPaymentStatus, EProductSortKey, type IAddToCartRequest, type IAddress, type IArticleByHandleRequest, type IBaseQueryParams, type IBlogArticleRequest, type ICartItemRequest, type ICheckoutUpdateRequest, type ICollectionFilterRequest, type ICollectionQueryRequest, type ICollectionsByhandlesRequest, type ICreateCheckoutRequest, type ICustomerQueryRequest, type ICustomerRequest, type IFetchOptionsRequest, type IGetArticleRequest, type IImage, type IMetafield, type IMoney, type IOptionsRequest, type IOrderByIdRequest, type IOrderHistoryRequest, type IOrderQueryRequest, type IOrderRequest, type IPaginationParams, type IPaymentRequest, type IProductFilters, type IProductQueryReqest, type IRemoveFromCartRequest, type IResponse, type IResponseMeta, type ISeo, type ISingleCartRequest, type ISingleCollectionRequest, type ISingleCustomerRequest, type ISingleOrderRequest, type ISingleProductRequest, type ITrendingArticleRequest, type IUpdateCartRequest, type IUpdateCustomerRequest, type IUpdateOrderRequest };