@thorprovider/create-thor-app 3.1.1 → 3.1.3

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.
@@ -1,190 +1,697 @@
1
1
  # Domain Types
2
2
 
3
- All types come from `@thorprovider/types`. Import with:
3
+ > **Source of truth**: `@thorprovider/types`
4
+ > **Auto-generated** by `scripts/generate-types-doc.ts` — do not edit manually.
5
+ > Run `pnpm generate:types-doc` to regenerate after updating `@thorprovider/types`.
6
+ > Last generated: 2026-04-29
7
+
8
+ All types import from `@thorprovider/types`:
4
9
 
5
10
  ```ts
6
- import type { Product, Cart, Order, Customer, Address, Money } from '@thorprovider/types';
11
+ import type {
12
+ // Core
13
+ Money, Image, SEO, Country,
14
+ // Product
15
+ Product, ProductVariant, ProductOption, PriceRange,
16
+ ProductPreview, FilterConfig, FilterOption, FilterSection,
17
+ ActiveFilter, SortOption, GetProductsOptions,
18
+ AdvancedSearchProductsOptions, SearchResultMeta,
19
+ AdminProduct, AdminProductVariant,
20
+ // Cart
21
+ Cart, CartItem, CartCost, CartLineInput, CartLineUpdate, DiscountCode,
22
+ // Order
23
+ Order, OrderItem, OrderStatus, PaymentStatus, FulfillmentStatus,
24
+ GetOrdersOptions,
25
+ // Customer & Auth
26
+ Customer, Address, GetCustomersOptions,
27
+ LoginCredentials, RegisterData, AuthResponse,
28
+ UpdateCustomerData, CreateAddressData,
29
+ // Catalog
30
+ Collection, ProductCategory, GetCategoriesOptions,
31
+ // Region
32
+ Region,
33
+ // Shipping & Payment
34
+ ShippingMethod, PaymentMethod, PaymentMethodType, PaymentMethodsOptions,
35
+ // Inventory
36
+ StockStatus, StockValidation, StockLocation, InventoryLevel, FulfillmentOption,
37
+ // Capabilities
38
+ BackendCapabilities,
39
+ } from '@thorprovider/types';
7
40
  ```
8
41
 
42
+
9
43
  ---
10
44
 
11
45
  ## Core Primitives
12
46
 
47
+ > ⚠️ `Money.amount` is **always a string** (e.g., `"45.00"`).
48
+ > Use `parseFloat(money.amount)` before arithmetic or passing to display components.
49
+
13
50
  ```ts
14
- interface Money {
15
- amount: string; // Decimal as string: "45.00"
16
- currencyCode: string; // ISO 4217: "USD", "EUR"
51
+ export interface Money {
52
+ amount: string; // Decimal as string (e.g., "45.00")
53
+ currencyCode: string; // ISO 4217 code (e.g., "USD", "EUR")
17
54
  }
55
+ ```
18
56
 
19
- interface Image {
57
+ ```ts
58
+ export interface Image {
59
+ id?: string; // Optional platform-specific ID
20
60
  url: string;
21
61
  altText: string;
22
- width?: number;
62
+ width?: number; // Optional for platforms without dimensions
23
63
  height?: number;
24
64
  }
65
+ ```
66
+
67
+ ```ts
68
+ export interface SEO {
69
+ title: string;
70
+ description: string;
71
+ }
72
+ ```
25
73
 
26
- interface Country {
27
- code: string; // ISO 3166-1 alpha-2: "US", "ES"
28
- name: string; // "United States"
74
+ ```ts
75
+ export interface Country {
76
+
77
+ code: string;
78
+
79
+
80
+ name: string;
81
+
82
+
83
+ iso3?: string;
84
+
85
+
86
+ numCode?: string;
29
87
  }
30
88
  ```
31
89
 
90
+
32
91
  ---
33
92
 
34
93
  ## Product
35
94
 
95
+ > ⚠️ Use `product.handle` (not `product.id`) in URLs: `/products/${product.handle}`
96
+ > ⚠️ `product.title` (not `product.name`)
97
+
36
98
  ```ts
37
- interface Product {
99
+ export interface Product {
38
100
  id: string;
39
- handle: string; // URL slug
40
- title: string;
101
+ handle: string; // Shopify/Medusa: handle, WooCommerce: slug, Magento: url_key
102
+ title: string; // Shopify/Medusa: title, WooCommerce/Magento: name
41
103
  description: string;
42
104
  descriptionHtml?: string;
43
- availableForSale: boolean;
105
+ availableForSale: boolean; // Computed from platform-specific status/stock fields
106
+
107
+ // Options and variants
44
108
  options: ProductOption[];
45
109
  variants: ProductVariant[];
46
- featuredImage?: Image;
110
+
111
+ // Media
112
+ featuredImage?: Image; // Shopify: featuredImage, Medusa: thumbnail, WooCommerce: images[0]
47
113
  images: Image[];
114
+
115
+ // Pricing
48
116
  priceRange: PriceRange;
49
- collections?: Array<{ id: string; title: string; handle: string }>;
50
- productType?: string;
117
+
118
+ // Organization (optional, platform-dependent)
119
+ collections?: Array<{ id: string; title: string; handle: string }>; // Shopify/Medusa: collections, WooCommerce/Magento: categories
120
+ productType?: string; // Shopify: productType, Medusa: type, WooCommerce: type (simple/variable)
121
+ vendor?: string; // Shopify-specific, stored in metadata for others
51
122
  tags?: string[];
52
- seo?: { title: string; description: string };
53
- createdAt: string;
123
+
124
+ // SEO
125
+ seo?: SEO;
126
+
127
+ // Dates
128
+ createdAt: string; // ISO 8601 timestamp
54
129
  updatedAt: string;
130
+
131
+ // Platform-specific extensions
132
+ metadata?: Record<string, unknown>; // Store platform-specific fields here
55
133
  }
134
+ ```
56
135
 
57
- interface ProductVariant {
136
+ ```ts
137
+ export interface ProductVariant {
58
138
  id: string;
59
139
  title: string;
60
140
  sku?: string;
61
141
  availableForSale: boolean;
62
- selectedOptions: Array<{ name: string; value: string }>;
142
+ selectedOptions: SelectedOption[];
143
+
144
+ // Pricing
63
145
  price: Money;
64
- compareAtPrice?: Money; // original price (for sale display)
65
- quantityAvailable?: number;
66
- image?: Image;
146
+ compareAtPrice?: Money; // Original price before discount (Shopify: compareAtPrice, WooCommerce: regular_price)
147
+
148
+ // Inventory
149
+ quantityAvailable?: number; // Available stock quantity
150
+ stockStatus?: StockStatus;
151
+ inventoryLevels?: InventoryLevel[];
152
+
153
+ // Media
154
+ image?: Image; // Variant-specific image
67
155
  }
156
+ ```
68
157
 
69
- interface ProductOption {
158
+ ```ts
159
+ export interface ProductOption {
70
160
  id: string;
71
- name: string; // "Size", "Color"
72
- values: string[]; // ["S", "M", "L"]
161
+ name: string;
162
+ values: string[];
73
163
  }
164
+ ```
74
165
 
75
- interface PriceRange {
166
+ ```ts
167
+ export interface SelectedOption {
168
+ name: string;
169
+ value: string;
170
+ }
171
+ ```
172
+
173
+ ```ts
174
+ export interface PriceRange {
76
175
  minVariantPrice: Money;
77
176
  maxVariantPrice: Money;
78
177
  }
79
178
  ```
80
179
 
180
+ ```ts
181
+ export interface GetProductsOptions {
182
+ query?: string;
183
+ sortKey?: string;
184
+ reverse?: boolean;
185
+ first?: number;
186
+ skip?: number;
187
+
188
+ after?: string | number;
189
+ regionId?: string;
190
+
191
+ categoryIds?: string[];
192
+
193
+ collectionIds?: string[];
194
+ }
195
+ ```
196
+
197
+ > `ProductPreview` is the **simplified type for card components** — use it instead of `Product`
198
+ > when you only need display data.
199
+ > ⚠️ `name` (not `title`), `price` is already a `number` — do **not** call `parseFloat()`.
200
+
201
+ ```ts
202
+ export interface ProductPreview {
203
+ id: string;
204
+ name: string;
205
+ price: number;
206
+ originalPrice?: number;
207
+ image: string;
208
+ rating: number;
209
+ reviewCount: number;
210
+ isNew?: boolean;
211
+ isOnSale?: boolean;
212
+ isOutOfStock?: boolean;
213
+ discountPercent?: number;
214
+ stock?: number;
215
+ category?: string;
216
+ description?: string;
217
+ }
218
+ ```
219
+
220
+ ```ts
221
+ export interface FilterOption {
222
+
223
+ value: string;
224
+
225
+ label: string;
226
+
227
+ id?: string;
228
+
229
+ count?: number;
230
+ }
231
+ ```
232
+
233
+ ```ts
234
+ export interface FilterSection {
235
+ id: string;
236
+ label: string;
237
+ type: 'checkbox' | 'range' | 'radio' | 'select';
238
+ options?: FilterOption[];
239
+ min?: number;
240
+ max?: number;
241
+ defaultExpanded?: boolean;
242
+ }
243
+ ```
244
+
245
+ > Returned by `commerce.getAvailableFilters()`.
246
+ > Check `capabilities.facetedFilters` before calling that method.
247
+
248
+ ```ts
249
+ export interface FilterConfig {
250
+
251
+ id: string;
252
+
253
+ label: string;
254
+
255
+ type: 'checkbox' | 'multi' | 'select' | 'single' | 'range' | 'boolean';
256
+
257
+ options?: FilterOption[];
258
+
259
+ min?: number;
260
+
261
+ max?: number;
262
+
263
+ isActive?: boolean;
264
+
265
+ ranking?: number;
266
+ }
267
+ ```
268
+
269
+ ```ts
270
+ export interface ActiveFilter {
271
+
272
+ id: string;
273
+
274
+ category: string;
275
+
276
+ label: string;
277
+
278
+ value: string | string[];
279
+ }
280
+ ```
281
+
282
+ ```ts
283
+ export type SortOption =
284
+ | 'featured'
285
+ | 'price-asc'
286
+ | 'price-desc'
287
+ | 'name'
288
+ | 'newest'
289
+ | 'rating';
290
+ ```
291
+
292
+ ```ts
293
+ export interface Review {
294
+ id: string;
295
+ author: string;
296
+ rating: number;
297
+ date: string;
298
+ title: string;
299
+ body: string;
300
+ verified?: boolean;
301
+ }
302
+ ```
303
+
304
+ ```ts
305
+ export interface AdminProduct {
306
+ id: string;
307
+ handle: string;
308
+ title: string;
309
+
310
+ description?: string;
311
+
312
+ status: string;
313
+ variants: AdminProductVariant[];
314
+
315
+ thumbnail?: string;
316
+
317
+ images?: string[];
318
+ }
319
+ ```
320
+
321
+ ```ts
322
+ export interface AdminProductVariant {
323
+ id: string;
324
+ title: string;
325
+ sku?: string;
326
+
327
+ quantityAvailable?: number;
328
+
329
+ prices?: Array<{ amount: number; currencyCode: string }>;
330
+ }
331
+ ```
332
+
333
+ ```ts
334
+ export interface AdvancedSearchProductsOptions extends GetProductsOptions {
335
+
336
+ categoryIds?: string[];
337
+
338
+ collectionIds?: string[];
339
+
340
+ tagIds?: string[];
341
+
342
+ priceMin?: number;
343
+
344
+ priceMax?: number;
345
+
346
+ currencyCode?: string;
347
+
348
+ inStockOnly?: boolean;
349
+
350
+ attributes?: Array<{ id: string; values: string[] }>;
351
+
352
+ includeVariants?: boolean;
353
+ }
354
+ ```
355
+
356
+ ```ts
357
+ export interface SearchResultMeta {
358
+
359
+ total?: number;
360
+
361
+ limit?: number;
362
+
363
+ offset?: number;
364
+
365
+ processingTimeMs?: number;
366
+
367
+ hybridSearchUsed?: boolean;
368
+
369
+ appliedFilters?: Record<string, unknown>;
370
+
371
+ priceContext?: {
372
+ currencyCode: string;
373
+ regionId?: string;
374
+ };
375
+ }
376
+ ```
377
+
378
+
81
379
  ---
82
380
 
83
381
  ## Cart
84
382
 
383
+ > ⚠️ `cart.lines` (not `cart.items`)
384
+ > ⚠️ `cart.cost.totalAmount` (not `cart.total`)
385
+
85
386
  ```ts
86
- interface Cart {
387
+ export interface Cart {
87
388
  id: string | undefined;
88
389
  checkoutUrl: string;
89
- cost: {
90
- subtotalAmount: Money;
91
- totalAmount: Money;
92
- totalTaxAmount?: Money;
93
- };
390
+ cost: CartCost;
94
391
  lines: CartItem[];
95
392
  totalQuantity: number;
393
+ fulfillmentOptions?: FulfillmentOption[];
394
+ stockValidation?: StockValidation;
395
+
396
+ completedAt?: string;
96
397
  }
398
+ ```
97
399
 
98
- interface CartItem {
400
+ ```ts
401
+ export interface CartCost {
402
+ subtotalAmount: Money;
403
+ totalAmount: Money;
404
+ totalTaxAmount?: Money;
405
+ }
406
+ ```
407
+
408
+ ```ts
409
+ export interface CartItem {
99
410
  id: string | undefined;
100
411
  quantity: number;
101
- cost: { totalAmount: Money };
412
+ stockStatus?: StockStatus;
413
+ cost: {
414
+ totalAmount: Money;
415
+ };
102
416
  merchandise: {
103
- id: string; // variant ID
417
+ id: string;
104
418
  title: string;
105
- selectedOptions: Array<{ name: string; value: string }>;
106
- product: {
107
- id: string;
108
- handle: string;
109
- title: string;
110
- featuredImage: Image;
111
- };
419
+ selectedOptions: SelectedOption[];
420
+ product: CartProduct;
112
421
  };
113
422
  }
423
+ ```
424
+
425
+ ```ts
426
+ export interface CartProduct {
427
+ id: string;
428
+ handle: string;
429
+ title: string;
430
+ featuredImage: Image;
431
+ }
432
+ ```
433
+
434
+ ```ts
435
+ export interface CartLineInput {
436
+ merchandiseId: string;
437
+ quantity: number;
438
+ }
439
+ ```
114
440
 
115
- // For addToCart:
116
- interface CartLineInput { merchandiseId: string; quantity: number; }
441
+ ```ts
442
+ export interface CartLineUpdate {
443
+ id: string;
444
+ merchandiseId: string;
445
+ quantity: number;
446
+ }
447
+ ```
117
448
 
118
- // For updateCart:
119
- interface CartLineUpdate { id: string; merchandiseId: string; quantity: number; }
449
+ ```ts
450
+ export interface DiscountCode {
451
+
452
+ code: string;
453
+
454
+
455
+ value: number;
456
+
457
+
458
+ isPercentage: boolean;
459
+
460
+
461
+ description?: string;
462
+
463
+
464
+ minimumAmount?: Money;
465
+
466
+
467
+ expiresAt?: Date;
468
+
469
+
470
+ maxUses?: number;
471
+
472
+
473
+ usageCount?: number;
474
+ }
120
475
  ```
121
476
 
477
+
122
478
  ---
123
479
 
124
480
  ## Order
125
481
 
126
482
  ```ts
127
- type OrderStatus = 'pending' | 'processing' | 'completed' | 'cancelled' | 'refunded';
128
- type PaymentStatus = 'pending' | 'authorized' | 'paid' | 'partially_refunded' | 'refunded';
129
- type FulfillmentStatus = 'unfulfilled' | 'partially_fulfilled' | 'fulfilled' | 'returned';
483
+ export type OrderStatus =
484
+ | 'pending'
485
+ | 'processing'
486
+ | 'completed'
487
+ | 'cancelled'
488
+ | 'refunded';
489
+ ```
130
490
 
131
- interface Order {
491
+ ```ts
492
+ export type PaymentStatus =
493
+ | 'pending'
494
+ | 'authorized'
495
+ | 'paid'
496
+ | 'partially_refunded'
497
+ | 'refunded';
498
+ ```
499
+
500
+ ```ts
501
+ export type FulfillmentStatus =
502
+ | 'unfulfilled'
503
+ | 'partially_fulfilled'
504
+ | 'fulfilled'
505
+ | 'returned';
506
+ ```
507
+
508
+ ```ts
509
+ export interface Order {
132
510
  id: string;
133
- orderNumber: string;
511
+ orderNumber: string; // Human-readable order number (e.g., "#1000", "727")
134
512
  email: string;
513
+
514
+ // Status (3 separate statuses for granular control)
135
515
  status: OrderStatus;
136
516
  paymentStatus: PaymentStatus;
137
517
  fulfillmentStatus: FulfillmentStatus;
518
+
519
+ // Customer
138
520
  customerId?: string;
139
521
  customer?: Customer;
522
+
523
+ // Items
140
524
  items: OrderItem[];
525
+
526
+ // Pricing
141
527
  subtotal: Money;
142
528
  total: Money;
143
529
  tax?: Money;
144
530
  shipping?: Money;
145
- discount?: Money;
531
+ discount?: Money; // Total discount applied
532
+
533
+ // Addresses
146
534
  shippingAddress?: Address;
147
535
  billingAddress?: Address;
148
- createdAt: string;
536
+
537
+ // Dates
538
+ createdAt: string; // ISO 8601 timestamp
149
539
  updatedAt: string;
150
- isDraft?: boolean;
540
+ completedAt?: string; // When order was completed/fulfilled
541
+ cancelledAt?: string; // When order was cancelled
542
+
543
+ // Draft status
544
+ isDraft?: boolean; // True if this is a draft order (not yet completed or placed)
545
+
546
+ // Platform-specific extensions
547
+ metadata?: Record<string, unknown>;
151
548
  }
549
+ ```
152
550
 
153
- interface OrderItem {
551
+ ```ts
552
+ export interface OrderItem {
154
553
  id: string;
155
- title: string;
156
- variantTitle?: string;
554
+ title: string; // Product title
555
+ variantTitle?: string; // Variant title (e.g., "Large / Red")
157
556
  quantity: number;
158
- price: Money;
159
- total: Money;
557
+ price: Money; // Unit price
558
+ total: Money; // Line total (quantity * price)
160
559
  sku?: string;
161
560
  image?: Image;
561
+
562
+ // Product references
563
+ productId?: string;
564
+ variantId?: string;
162
565
  }
163
566
  ```
164
567
 
568
+ ```ts
569
+ export interface GetOrdersOptions {
570
+
571
+ customerId?: string;
572
+
573
+ limit?: number;
574
+
575
+ offset?: number;
576
+
577
+ salesChannelId?: string;
578
+
579
+ customFetcher?: GetOrdersCallback;
580
+ }
581
+ ```
582
+
583
+
165
584
  ---
166
585
 
167
- ## Customer
586
+ ## Customer & Address
168
587
 
169
588
  ```ts
170
- interface Customer {
589
+ export interface Customer {
171
590
  id: string;
172
591
  email: string;
173
- firstName: string | null;
174
- lastName: string | null;
592
+ firstName: string | null; // Platform adapters transform first_name → firstName
593
+ lastName: string | null; // Platform adapters transform last_name → lastName
175
594
  phone?: string | null;
176
- hasAccount?: boolean;
177
- createdAt?: string;
595
+ hasAccount?: boolean; // Whether customer has a registered account
596
+ createdAt?: string; // ISO 8601 timestamp
597
+ updatedAt?: string;
598
+
599
+ metadata?: Record<string, unknown>;
178
600
  }
179
601
  ```
180
602
 
603
+ ```ts
604
+ export interface Address {
605
+ id?: string;
606
+ firstName: string; // Shopify: firstName, Medusa: first_name, WooCommerce: first_name
607
+ lastName: string; // Shopify: lastName, Medusa: last_name, WooCommerce: last_name
608
+ company?: string;
609
+ address1: string; // Shopify: address1, Medusa: address_1, WooCommerce: address_1
610
+ address2?: string; // Optional second address line
611
+ city: string;
612
+ province?: string; // State/province (Shopify: province, WooCommerce: state, Magento: region)
613
+ postalCode: string; // Shopify: zip, Medusa: postal_code, WooCommerce: postcode
614
+ countryCode: string; // ISO 3166-1 alpha-2 code (e.g., "US", "CA", "GB")
615
+ phone?: string;
616
+ isDefault?: boolean; // Whether this is the default/primary address for the customer
617
+ metadata?: Record<string, unknown>; // Flexible storage for platform-specific extras (label, etc.)
618
+ }
619
+ ```
620
+
621
+ ```ts
622
+ export interface GetCustomersOptions {
623
+
624
+ search?: string;
625
+
626
+ limit?: number;
627
+
628
+ offset?: number;
629
+
630
+ sortBy?: 'createdAt' | 'email' | 'firstName';
631
+
632
+ salesChannelId?: string;
633
+
634
+ customFetcher?: GetCustomersCallback;
635
+ }
636
+ ```
637
+
638
+
181
639
  ---
182
640
 
183
- ## Address
641
+ ## Auth Types
184
642
 
185
643
  ```ts
186
- interface Address {
187
- id?: string;
644
+ export interface LoginCredentials {
645
+ email: string;
646
+ password: string;
647
+ }
648
+ ```
649
+
650
+ > ⚠️ `first_name` / `last_name` are **snake_case** — this is intentional.
651
+ > The adapter normalizes to camelCase for `Customer`, but auth input stays snake_case.
652
+
653
+ ```ts
654
+ export interface RegisterData {
655
+ email: string;
656
+ password: string;
657
+ first_name: string;
658
+ last_name: string;
659
+ phone?: string;
660
+ }
661
+ ```
662
+
663
+ ```ts
664
+ export interface AuthResponse {
665
+
666
+ token?: string;
667
+
668
+
669
+ customer?: Customer;
670
+
671
+
672
+ requiresAction?: boolean;
673
+
674
+
675
+ redirectUrl?: string;
676
+ }
677
+ ```
678
+
679
+ > ⚠️ `first_name` / `last_name` are **snake_case** — same as `RegisterData`.
680
+ > Do NOT pass `{ firstName, lastName }` here.
681
+
682
+ ```ts
683
+ export interface UpdateCustomerData {
684
+ first_name?: string;
685
+ last_name?: string;
686
+ phone?: string | null;
687
+ email?: string;
688
+ password?: string;
689
+ metadata?: Record<string, unknown>;
690
+ }
691
+ ```
692
+
693
+ ```ts
694
+ export interface CreateAddressData {
188
695
  firstName: string;
189
696
  lastName: string;
190
697
  company?: string;
@@ -193,131 +700,345 @@ interface Address {
193
700
  city: string;
194
701
  province?: string;
195
702
  postalCode: string;
196
- countryCode: string; // ISO 3166-1 alpha-2
703
+ countryCode: string;
197
704
  phone?: string;
198
- isDefault?: boolean;
705
+ metadata?: Record<string, unknown>;
706
+ }
707
+ ```
708
+
709
+ > Access via `commerce.auth` — the auth sub-provider.
710
+ > Import hooks from `@/lib/auth-context` (not directly from `@thorprovider/providers`).
711
+
712
+ ```ts
713
+ export interface AuthProvider {
714
+ // ========================================
715
+ // Authentication Methods
716
+ // ========================================
717
+
718
+
719
+ login(credentials: LoginCredentials): Promise<AuthResponse>;
720
+
721
+
722
+ register(data: RegisterData): Promise<AuthResponse>;
723
+
724
+
725
+ logout(): Promise<void>;
726
+
727
+ // ========================================
728
+ // Password Management
729
+ // ========================================
730
+
731
+
732
+ requestPasswordReset(email: string): Promise<void>;
733
+
734
+
735
+ resetPassword(token: string, password: string, metadata?: Record<string, unknown>): Promise<void>;
736
+
737
+ // ========================================
738
+ // Session Management
739
+ // ========================================
740
+
741
+
742
+ getCurrentCustomer(): Promise<Customer | null>;
743
+
744
+
745
+ updateCustomer(data: UpdateCustomerData): Promise<Customer>;
746
+
747
+
748
+ isAuthenticated(): Promise<boolean>;
749
+
750
+
751
+ getAuthToken(): string | null;
752
+
753
+
754
+ deleteCustomerAccount(): Promise<void>;
755
+
756
+ // ========================================
757
+ // Address Management
758
+ // ========================================
759
+
760
+
761
+ getAddresses(): Promise<Address[]>;
762
+
763
+
764
+ createAddress(data: CreateAddressData): Promise<Address>;
765
+
766
+
767
+ updateAddress(addressId: string, data: Partial<CreateAddressData>): Promise<Address>;
768
+
769
+
770
+ deleteAddress(addressId: string): Promise<void>;
199
771
  }
200
772
  ```
201
773
 
774
+
202
775
  ---
203
776
 
204
- ## Collection & Category
777
+ ## Collection
205
778
 
206
779
  ```ts
207
- interface Collection {
780
+ export interface Collection {
208
781
  id: string;
209
782
  handle: string;
210
783
  title: string;
211
784
  description: string;
785
+ seo?: SEO;
212
786
  path: string;
213
- seo?: { title: string; description: string };
787
+ updatedAt: string;
214
788
  }
789
+ ```
215
790
 
216
- interface ProductCategory {
217
- id: string;
218
- name: string;
219
- handle: string;
220
- description?: string;
221
- parentCategoryId?: string;
222
- productCount?: number;
791
+ ```ts
792
+ export interface GetCollectionsOptions {
793
+
794
+ limit?: number;
795
+
796
+ query?: string;
223
797
  }
224
798
  ```
225
799
 
800
+ ```ts
801
+ export interface CollectionProductsOptions {
802
+ sortKey?: string;
803
+ reverse?: boolean;
804
+ first?: number;
805
+ after?: string;
806
+ }
807
+ ```
808
+
809
+
226
810
  ---
227
811
 
228
- ## Shipping & Payment
812
+ ## Category
229
813
 
230
814
  ```ts
231
- interface ShippingMethod {
815
+ export interface ProductCategory {
816
+
232
817
  id: string;
818
+
233
819
  name: string;
234
- price: Money;
820
+
821
+ handle: string;
822
+
235
823
  description?: string;
236
- estimatedDays?: string;
824
+
825
+ parentCategoryId?: string;
826
+
827
+ productCount?: number;
828
+
829
+ image?: string;
830
+
831
+ metadata?: Record<string, any>;
237
832
  }
833
+ ```
238
834
 
239
- type PaymentMethodType = 'card' | 'wallet' | 'bank_transfer' | 'buy_now_pay_later' | 'cash_on_delivery' | 'crypto' | 'other';
240
-
241
- interface PaymentMethod {
242
- id: string;
243
- name: string;
244
- type: PaymentMethodType;
245
- isEnabled: boolean;
246
- description?: string;
247
- logo?: string;
835
+ ```ts
836
+ export interface GetCategoriesOptions {
837
+
838
+ includeDescendants?: boolean;
839
+
840
+ parentCategoryId?: string;
841
+
842
+ limit?: number;
843
+
844
+ query?: string;
845
+
846
+ salesChannelId?: string;
847
+
848
+ customFetcher?: GetCategoriesCallback;
248
849
  }
249
850
  ```
250
851
 
852
+
251
853
  ---
252
854
 
253
855
  ## Region
254
856
 
255
857
  ```ts
256
- interface Region {
858
+ export interface Region {
859
+
257
860
  id: string;
861
+
862
+
258
863
  name: string;
864
+
865
+
259
866
  countryCodes: string[];
260
- currency: string; // ISO 4217
867
+
868
+
869
+ currency: string;
870
+
871
+
872
+ paymentProviders?: string[];
873
+
874
+
261
875
  taxRate?: number;
876
+
877
+
878
+ isEnabled?: boolean;
879
+
880
+
881
+ metadata?: Record<string, unknown>;
262
882
  }
263
883
  ```
264
884
 
885
+
265
886
  ---
266
887
 
267
- ## Auth Types
888
+ ## Shipping
268
889
 
269
890
  ```ts
270
- interface LoginCredentials { email: string; password: string; }
891
+ export interface ShippingMethod {
892
+
893
+ id: string;
894
+
895
+
896
+ name: string;
897
+
898
+
899
+ price: Money;
900
+
901
+
902
+ description?: string;
903
+
904
+
905
+ estimatedDays?: string;
906
+ }
907
+ ```
271
908
 
272
- interface RegisterData {
273
- email: string;
274
- password: string;
275
- first_name: string;
276
- last_name: string;
277
- phone?: string;
909
+
910
+ ---
911
+
912
+ ## Payment
913
+
914
+ ```ts
915
+ export type PaymentMethodType =
916
+ | 'card' // Credit/debit cards (Visa, Mastercard, Amex, etc.)
917
+ | 'wallet' // Digital wallets (Apple Pay, Google Pay, PayPal)
918
+ | 'bank_transfer' // Bank transfers (ACH, SEPA, wire transfer)
919
+ | 'buy_now_pay_later' // BNPL services (Klarna, Affirm, Afterpay)
920
+ | 'cash_on_delivery' // Cash on delivery / Manual payment
921
+ | 'crypto' // Cryptocurrency payments
922
+ | 'other';
923
+ ```
924
+
925
+ ```ts
926
+ export interface PaymentMethod {
927
+
928
+ id: string;
929
+
930
+
931
+ name: string;
932
+
933
+
934
+ type: PaymentMethodType;
935
+
936
+
937
+ isEnabled: boolean;
938
+
939
+
940
+ requiresSetup: boolean;
941
+
942
+
943
+ description?: string;
944
+
945
+
946
+ metadata?: Record<string, unknown>;
947
+
948
+
949
+ features?: PaymentMethodFeatures;
950
+
951
+
952
+ logo?: string;
278
953
  }
954
+ ```
279
955
 
280
- interface AuthResponse {
281
- token?: string;
282
- customer?: Customer;
956
+ ```ts
957
+ export interface PaymentMethodsOptions {
958
+
959
+ regionId?: string;
960
+
961
+
962
+ cartId?: string;
963
+
964
+
965
+ currencyCode?: string;
966
+
967
+
968
+ enabledOnly?: boolean;
969
+
970
+
971
+ forceRefresh?: boolean;
283
972
  }
973
+ ```
284
974
 
285
- interface CreateAddressData {
286
- firstName: string;
287
- lastName: string;
288
- company?: string;
289
- address1: string;
290
- address2?: string;
291
- city: string;
292
- province?: string;
293
- postalCode: string;
294
- countryCode: string;
295
- phone?: string;
975
+ ```ts
976
+ export interface PaymentMethodFeatures {
977
+
978
+ saveForLater?: boolean;
979
+
980
+
981
+ requires3DS?: boolean;
982
+
983
+
984
+ supportsRefunds?: boolean;
985
+
986
+
987
+ minAmount?: number;
988
+
989
+
990
+ maxAmount?: number;
991
+
992
+
993
+ supportedCurrencies?: string[];
994
+
995
+
996
+ requiresVerification?: boolean;
296
997
  }
297
998
  ```
298
999
 
1000
+
299
1001
  ---
300
1002
 
301
- ## Inventory (Admin)
1003
+ ## Inventory & Stock
302
1004
 
303
1005
  ```ts
304
- type StockStatus = 'in_stock' | 'out_of_stock' | 'low_stock';
1006
+ export type StockStatus = 'in_stock' | 'out_of_stock' | 'low_stock';
1007
+ ```
305
1008
 
306
- interface StockLocation {
1009
+ ```ts
1010
+ export interface StockLocation {
307
1011
  id: string;
308
1012
  name: string;
309
- address?: { address1: string; city: string; countryCode: string; postalCode: string };
1013
+ address?: {
1014
+ address1: string;
1015
+ address2?: string;
1016
+ city: string;
1017
+ countryCode: string;
1018
+ postalCode: string;
1019
+ province?: string;
1020
+ };
1021
+ metadata?: {
1022
+ lat?: number;
1023
+ lng?: number;
1024
+ timezone?: string;
1025
+ };
310
1026
  }
1027
+ ```
311
1028
 
312
- interface InventoryLevel {
1029
+ ```ts
1030
+ export interface InventoryLevel {
313
1031
  locationId: string;
314
1032
  locationName: string;
315
1033
  availableQuantity: number;
316
1034
  reservedQuantity: number;
1035
+ incomingQuantity?: number;
317
1036
  stockedQuantity: number;
318
1037
  }
1038
+ ```
319
1039
 
320
- interface StockValidation {
1040
+ ```ts
1041
+ export interface StockValidation {
321
1042
  allAvailable: boolean;
322
1043
  unavailableItems: Array<{
323
1044
  variantId: string;
@@ -327,3 +1048,157 @@ interface StockValidation {
327
1048
  }>;
328
1049
  }
329
1050
  ```
1051
+
1052
+ ```ts
1053
+ export interface FulfillmentOption {
1054
+ id: string;
1055
+ providerId: string;
1056
+ name: string;
1057
+ description?: string;
1058
+ price: Money;
1059
+ estimatedDays?: string;
1060
+ stockLocation: StockLocation;
1061
+ fulfillmentSet?: FulfillmentSet;
1062
+ distance?: number;
1063
+ }
1064
+ ```
1065
+
1066
+
1067
+ ---
1068
+
1069
+ ## BackendCapabilities
1070
+
1071
+ > Always check capabilities before rendering features that depend on backend support.
1072
+ > Access via `useCommerce()`:
1073
+ >
1074
+ > ```tsx
1075
+ > 'use client';
1076
+ > import { useCommerce } from '@/lib/commerce-provider';
1077
+ >
1078
+ > export function AccountActions() {
1079
+ > const { provider } = useCommerce();
1080
+ > const caps = provider.capabilities;
1081
+ > return (
1082
+ > <div>
1083
+ > {caps.updateEmail && <EmailField />}
1084
+ > {caps.wishlist && <WishlistButton />}
1085
+ > {caps.fetchOrders && <OrderHistory />}
1086
+ > </div>
1087
+ > );
1088
+ > }
1089
+ > ```
1090
+
1091
+ ```ts
1092
+ export interface BackendCapabilities {
1093
+
1094
+
1095
+
1096
+ updateProfile: boolean;
1097
+
1098
+
1099
+ updateEmail: boolean;
1100
+
1101
+
1102
+ changePasswordDirect: boolean;
1103
+
1104
+
1105
+ changePasswordViaEmail: boolean;
1106
+
1107
+
1108
+ deleteAccount: boolean;
1109
+
1110
+
1111
+
1112
+
1113
+ uploadAvatar: boolean;
1114
+
1115
+
1116
+ avatarViaMetadata: boolean;
1117
+
1118
+
1119
+
1120
+
1121
+ customAttributes: boolean;
1122
+
1123
+
1124
+
1125
+
1126
+ fetchOrders: boolean;
1127
+
1128
+
1129
+ cancelOrder: boolean;
1130
+
1131
+
1132
+
1133
+
1134
+ manageAddresses: boolean;
1135
+
1136
+
1137
+ defaultAddress: boolean;
1138
+
1139
+
1140
+
1141
+
1142
+ applyDiscounts: boolean;
1143
+
1144
+
1145
+ shippingCalculation: boolean;
1146
+
1147
+
1148
+
1149
+
1150
+ guestCheckout: boolean;
1151
+
1152
+
1153
+ savedPaymentMethods: boolean;
1154
+
1155
+
1156
+ listPaymentProviders: boolean;
1157
+
1158
+
1159
+ regionSpecificPayments: boolean;
1160
+
1161
+
1162
+
1163
+
1164
+ wishlist: boolean;
1165
+
1166
+
1167
+
1168
+
1169
+ advancedSearch: boolean;
1170
+
1171
+
1172
+ facetedFilters: boolean;
1173
+
1174
+
1175
+
1176
+
1177
+ productReviews: boolean;
1178
+
1179
+
1180
+
1181
+
1182
+ loyaltyProgram: boolean;
1183
+ }
1184
+ ```
1185
+
1186
+
1187
+ ---
1188
+
1189
+ ## Common Field Mistakes (Quick Reference)
1190
+
1191
+ | ❌ Wrong | ✅ Correct | Type |
1192
+ |----------|-----------|------|
1193
+ | `product.name` | `product.title` | `Product` |
1194
+ | `product.slug` | `product.handle` | `Product` |
1195
+ | `product.price` | `product.priceRange.minVariantPrice.amount` | `Product` |
1196
+ | `cart.items` | `cart.lines` | `Cart` |
1197
+ | `cart.total` | `cart.cost.totalAmount.amount` | `Cart` |
1198
+ | `cart.subtotal` | `cart.cost.subtotalAmount.amount` | `Cart` |
1199
+ | `/products/${product.id}` | `/products/${product.handle}` | URL |
1200
+ | `Money.amount` as number | `parseFloat(Money.amount)` | `Money` |
1201
+ | `register({ firstName })` | `register({ first_name })` | `RegisterData` |
1202
+ | `updateCustomer({ firstName })` | `updateCustomer({ first_name })` | `UpdateCustomerData` |
1203
+ | `preview.title` | `preview.name` | `ProductPreview` |
1204
+ | `parseFloat(preview.price)` | `preview.price` (already number) | `ProductPreview` |