@thorprovider/create-thor-app 4.0.0 → 4.0.1

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.
Files changed (48) hide show
  1. package/README.md +6 -55
  2. package/dist/index.js +154 -626
  3. package/package.json +1 -1
  4. package/templates/default/.agents/AGENTS.md +27 -0
  5. package/templates/default/.env.example +8 -30
  6. package/templates/default/.eslintrc.json +20 -27
  7. package/templates/default/README.md +52 -123
  8. package/templates/default/ai-validator.json +47 -29
  9. package/templates/default/app/api/revalidate/route.ts +27 -36
  10. package/templates/default/app/backend-unavailable/page.tsx +3 -7
  11. package/templates/default/app/error.tsx +1 -2
  12. package/templates/default/app/global-error.tsx +3 -3
  13. package/templates/default/app/globals.css +1 -71
  14. package/templates/default/app/layout.tsx +16 -38
  15. package/templates/default/app/not-found.tsx +1 -1
  16. package/templates/default/app/page.tsx +10 -119
  17. package/templates/default/components/providers/app-providers.tsx +19 -68
  18. package/templates/default/components/providers/cart-provider.tsx +143 -0
  19. package/templates/default/components/providers/commerce-provider.tsx +33 -0
  20. package/templates/default/components/providers/region-provider.tsx +105 -0
  21. package/templates/default/docs/README.md +46 -37
  22. package/templates/default/docs/commerce-api.md +58 -125
  23. package/templates/default/docs/patterns.md +128 -67
  24. package/templates/default/docs/project-structure.md +58 -50
  25. package/templates/default/docs/rules.md +43 -42
  26. package/templates/default/docs/types.md +105 -1024
  27. package/templates/default/lib/commerce.ts +33 -132
  28. package/templates/default/lib/env.ts +24 -94
  29. package/templates/default/lib/utils.ts +18 -0
  30. package/templates/default/next-env.d.ts +1 -1
  31. package/templates/default/next.config.ts +7 -0
  32. package/templates/default/package.json +2 -8
  33. package/templates/default/registry.json +6 -0
  34. package/templates/default/styles/tokens.css +81 -0
  35. package/templates/default/components/providers/navigation-provider.tsx +0 -37
  36. package/templates/default/config/site.config.ts +0 -156
  37. package/templates/default/docs/components.md +0 -282
  38. package/templates/default/docs/dependencies.md +0 -61
  39. package/templates/default/lib/auth-context.tsx +0 -213
  40. package/templates/default/lib/cart-provider.tsx +0 -53
  41. package/templates/default/lib/commerce-provider.tsx +0 -48
  42. package/templates/default/lib/region-detection.ts +0 -73
  43. package/templates/default/lib/region-provider.tsx +0 -53
  44. package/templates/default/lib/regions-config.ts +0 -48
  45. package/templates/default/lib/storefront-config.ts +0 -54
  46. package/templates/default/next.config.mjs +0 -51
  47. package/templates/default/proxy.ts +0 -155
  48. package/templates/default/scripts/generate-regions-config.ts +0 -498
@@ -1,697 +1,205 @@
1
- # Domain Types
1
+ ---
2
+ title: "Domain Types"
3
+ purpose: "All @thorprovider/types interfaces for V0 code generation"
4
+ lastReviewed: "2026-05-01"
5
+ ---
2
6
 
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
+ # Domain Types
7
8
 
8
- All types import from `@thorprovider/types`:
9
+ All types come from `@thorprovider/types`. Never redefine these locally.
9
10
 
10
11
  ```ts
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';
12
+ import type { Product, Cart, Order, Customer, Address, Money } from '@thorprovider/types';
40
13
  ```
41
14
 
42
-
43
15
  ---
44
16
 
45
17
  ## Core Primitives
46
18
 
47
- > ⚠️ `Money.amount` is **always a string** (e.g., `"45.00"`).
48
- > Use `parseFloat(money.amount)` before arithmetic or passing to display components.
49
-
50
19
  ```ts
51
- export interface Money {
52
- amount: string; // Decimal as string (e.g., "45.00")
53
- currencyCode: string; // ISO 4217 code (e.g., "USD", "EUR")
20
+ interface Money {
21
+ amount: string; // Decimal string: "45.00", "1499.99" — NOT cents, NOT a number
22
+ currencyCode: string; // ISO 4217: "USD", "EUR"
54
23
  }
55
- ```
56
24
 
57
- ```ts
58
- export interface Image {
59
- id?: string; // Optional platform-specific ID
25
+ interface Image {
60
26
  url: string;
61
27
  altText: string;
62
- width?: number; // Optional for platforms without dimensions
28
+ width?: number;
63
29
  height?: number;
64
30
  }
65
- ```
66
31
 
67
- ```ts
68
- export interface SEO {
69
- title: string;
70
- description: string;
32
+ interface Country {
33
+ code: string; // ISO 3166-1 alpha-2: "US", "ES"
34
+ name: string; // "United States"
71
35
  }
72
36
  ```
73
37
 
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;
87
- }
88
- ```
89
-
90
-
91
38
  ---
92
39
 
93
40
  ## Product
94
41
 
95
- > ⚠️ Use `product.handle` (not `product.id`) in URLs: `/products/${product.handle}`
96
- > ⚠️ `product.title` (not `product.name`)
97
-
98
42
  ```ts
99
- export interface Product {
43
+ interface Product {
100
44
  id: string;
101
- handle: string; // Shopify/Medusa: handle, WooCommerce: slug, Magento: url_key
102
- title: string; // Shopify/Medusa: title, WooCommerce/Magento: name
45
+ handle: string; // URL slug — use in routes
46
+ title: string; // Display name (NOT "name")
103
47
  description: string;
104
48
  descriptionHtml?: string;
105
- availableForSale: boolean; // Computed from platform-specific status/stock fields
106
-
107
- // Options and variants
49
+ availableForSale: boolean;
108
50
  options: ProductOption[];
109
51
  variants: ProductVariant[];
110
-
111
- // Media
112
- featuredImage?: Image; // Shopify: featuredImage, Medusa: thumbnail, WooCommerce: images[0]
52
+ featuredImage?: Image; // NOT "thumbnail"
113
53
  images: Image[];
114
-
115
- // Pricing
116
54
  priceRange: PriceRange;
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
55
+ collections?: Array<{ id: string; title: string; handle: string }>;
56
+ productType?: string;
122
57
  tags?: string[];
123
-
124
- // SEO
125
- seo?: SEO;
126
-
127
- // Dates
128
- createdAt: string; // ISO 8601 timestamp
58
+ seo?: { title: string; description: string };
59
+ createdAt: string;
129
60
  updatedAt: string;
130
-
131
- // Platform-specific extensions
132
- metadata?: Record<string, unknown>; // Store platform-specific fields here
133
61
  }
134
- ```
135
62
 
136
- ```ts
137
- export interface ProductVariant {
63
+ interface ProductVariant {
138
64
  id: string;
139
65
  title: string;
140
66
  sku?: string;
141
67
  availableForSale: boolean;
142
- selectedOptions: SelectedOption[];
143
-
144
- // Pricing
145
- price: Money;
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
68
+ selectedOptions: Array<{ name: string; value: string }>;
69
+ price: Money; // SINGULAR Money — NOT an array
70
+ compareAtPrice?: Money; // Original price (for sale display)
71
+ quantityAvailable?: number;
72
+ image?: Image;
155
73
  }
156
- ```
157
74
 
158
- ```ts
159
- export interface ProductOption {
75
+ interface ProductOption {
160
76
  id: string;
161
- name: string;
162
- values: string[];
77
+ name: string; // "Size", "Color"
78
+ values: string[]; // ["S", "M", "L"]
163
79
  }
164
- ```
165
80
 
166
- ```ts
167
- export interface SelectedOption {
168
- name: string;
169
- value: string;
170
- }
171
- ```
172
-
173
- ```ts
174
- export interface PriceRange {
81
+ interface PriceRange {
175
82
  minVariantPrice: Money;
176
83
  maxVariantPrice: Money;
177
84
  }
178
85
  ```
179
86
 
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
- ```
87
+ ### Common Mistakes
377
88
 
89
+ | Wrong | Correct |
90
+ |-------|---------|
91
+ | `product.name` | `product.title` |
92
+ | `product.thumbnail` | `product.featuredImage?.url` |
93
+ | `variant.prices[0]` | `variant.price` (singular Money) |
94
+ | `variant.price.amount` rendered directly | `formatPrice(variant.price)` |
95
+ | `/products/${product.id}` | `/products/${product.handle}` |
378
96
 
379
97
  ---
380
98
 
381
99
  ## Cart
382
100
 
383
- > ⚠️ `cart.lines` (not `cart.items`)
384
- > ⚠️ `cart.cost.totalAmount` (not `cart.total`)
385
-
386
101
  ```ts
387
- export interface Cart {
102
+ interface Cart {
388
103
  id: string | undefined;
389
104
  checkoutUrl: string;
390
- cost: CartCost;
105
+ cost: {
106
+ subtotalAmount: Money;
107
+ totalAmount: Money;
108
+ totalTaxAmount?: Money;
109
+ };
391
110
  lines: CartItem[];
392
111
  totalQuantity: number;
393
- fulfillmentOptions?: FulfillmentOption[];
394
- stockValidation?: StockValidation;
395
-
396
- completedAt?: string;
397
112
  }
398
- ```
399
113
 
400
- ```ts
401
- export interface CartCost {
402
- subtotalAmount: Money;
403
- totalAmount: Money;
404
- totalTaxAmount?: Money;
405
- }
406
- ```
407
-
408
- ```ts
409
- export interface CartItem {
114
+ interface CartItem {
410
115
  id: string | undefined;
411
116
  quantity: number;
412
- stockStatus?: StockStatus;
413
- cost: {
414
- totalAmount: Money;
415
- };
117
+ cost: { totalAmount: Money };
416
118
  merchandise: {
417
- id: string;
119
+ id: string; // variant ID
418
120
  title: string;
419
- selectedOptions: SelectedOption[];
420
- product: CartProduct;
121
+ selectedOptions: Array<{ name: string; value: string }>;
122
+ product: {
123
+ id: string;
124
+ handle: string;
125
+ title: string;
126
+ featuredImage: Image;
127
+ };
421
128
  };
422
129
  }
423
- ```
424
130
 
425
- ```ts
426
- export interface CartProduct {
427
- id: string;
428
- handle: string;
429
- title: string;
430
- featuredImage: Image;
431
- }
432
- ```
131
+ // For addToCart:
132
+ interface CartLineInput { merchandiseId: string; quantity: number; }
433
133
 
434
- ```ts
435
- export interface CartLineInput {
436
- merchandiseId: string;
437
- quantity: number;
438
- }
439
- ```
440
-
441
- ```ts
442
- export interface CartLineUpdate {
443
- id: string;
444
- merchandiseId: string;
445
- quantity: number;
446
- }
134
+ // For updateCart:
135
+ interface CartLineUpdate { id: string; merchandiseId: string; quantity: number; }
447
136
  ```
448
137
 
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
- }
475
- ```
476
-
477
-
478
138
  ---
479
139
 
480
140
  ## Order
481
141
 
482
142
  ```ts
483
- export type OrderStatus =
484
- | 'pending'
485
- | 'processing'
486
- | 'completed'
487
- | 'cancelled'
488
- | 'refunded';
489
- ```
490
-
491
- ```ts
492
- export type PaymentStatus =
493
- | 'pending'
494
- | 'authorized'
495
- | 'paid'
496
- | 'partially_refunded'
497
- | 'refunded';
498
- ```
143
+ type OrderStatus = 'pending' | 'processing' | 'completed' | 'cancelled' | 'refunded';
144
+ type PaymentStatus = 'pending' | 'authorized' | 'paid' | 'partially_refunded' | 'refunded';
145
+ type FulfillmentStatus = 'unfulfilled' | 'partially_fulfilled' | 'fulfilled' | 'returned';
499
146
 
500
- ```ts
501
- export type FulfillmentStatus =
502
- | 'unfulfilled'
503
- | 'partially_fulfilled'
504
- | 'fulfilled'
505
- | 'returned';
506
- ```
507
-
508
- ```ts
509
- export interface Order {
147
+ interface Order {
510
148
  id: string;
511
- orderNumber: string; // Human-readable order number (e.g., "#1000", "727")
149
+ orderNumber: string;
512
150
  email: string;
513
-
514
- // Status (3 separate statuses for granular control)
515
151
  status: OrderStatus;
516
152
  paymentStatus: PaymentStatus;
517
153
  fulfillmentStatus: FulfillmentStatus;
518
-
519
- // Customer
520
154
  customerId?: string;
521
155
  customer?: Customer;
522
-
523
- // Items
524
156
  items: OrderItem[];
525
-
526
- // Pricing
527
157
  subtotal: Money;
528
158
  total: Money;
529
159
  tax?: Money;
530
160
  shipping?: Money;
531
- discount?: Money; // Total discount applied
532
-
533
- // Addresses
161
+ discount?: Money;
534
162
  shippingAddress?: Address;
535
163
  billingAddress?: Address;
536
-
537
- // Dates
538
- createdAt: string; // ISO 8601 timestamp
164
+ createdAt: string;
539
165
  updatedAt: string;
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>;
548
166
  }
549
- ```
550
167
 
551
- ```ts
552
- export interface OrderItem {
168
+ interface OrderItem {
553
169
  id: string;
554
- title: string; // Product title
555
- variantTitle?: string; // Variant title (e.g., "Large / Red")
170
+ title: string;
171
+ variantTitle?: string;
556
172
  quantity: number;
557
- price: Money; // Unit price
558
- total: Money; // Line total (quantity * price)
173
+ price: Money;
174
+ total: Money;
559
175
  sku?: string;
560
176
  image?: Image;
561
-
562
- // Product references
563
- productId?: string;
564
- variantId?: string;
565
- }
566
- ```
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
177
  }
581
178
  ```
582
179
 
583
-
584
180
  ---
585
181
 
586
- ## Customer & Address
182
+ ## Customer
587
183
 
588
184
  ```ts
589
- export interface Customer {
185
+ interface Customer {
590
186
  id: string;
591
187
  email: string;
592
- firstName: string | null; // Platform adapters transform first_name → firstName
593
- lastName: string | null; // Platform adapters transform last_name → lastName
188
+ firstName: string | null;
189
+ lastName: string | null;
594
190
  phone?: string | null;
595
- hasAccount?: boolean; // Whether customer has a registered account
596
- createdAt?: string; // ISO 8601 timestamp
597
- updatedAt?: string;
598
-
599
- metadata?: Record<string, unknown>;
600
- }
601
- ```
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;
191
+ hasAccount?: boolean;
192
+ createdAt?: string;
635
193
  }
636
194
  ```
637
195
 
638
-
639
196
  ---
640
197
 
641
- ## Auth Types
642
-
643
- ```ts
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.
198
+ ## Address
681
199
 
682
200
  ```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 {
201
+ interface Address {
202
+ id?: string;
695
203
  firstName: string;
696
204
  lastName: string;
697
205
  company?: string;
@@ -700,505 +208,78 @@ export interface CreateAddressData {
700
208
  city: string;
701
209
  province?: string;
702
210
  postalCode: string;
703
- countryCode: string;
211
+ countryCode: string; // ISO 3166-1 alpha-2
704
212
  phone?: string;
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>;
213
+ isDefault?: boolean;
771
214
  }
772
215
  ```
773
216
 
774
-
775
217
  ---
776
218
 
777
- ## Collection
219
+ ## Collection & Category
778
220
 
779
221
  ```ts
780
- export interface Collection {
222
+ interface Collection {
781
223
  id: string;
782
224
  handle: string;
783
225
  title: string;
784
226
  description: string;
785
- seo?: SEO;
786
227
  path: string;
787
- updatedAt: string;
788
- }
789
- ```
790
-
791
- ```ts
792
- export interface GetCollectionsOptions {
793
-
794
- limit?: number;
795
-
796
- query?: string;
797
- }
798
- ```
799
-
800
- ```ts
801
- export interface CollectionProductsOptions {
802
- sortKey?: string;
803
- reverse?: boolean;
804
- first?: number;
805
- after?: string;
228
+ seo?: { title: string; description: string };
806
229
  }
807
- ```
808
-
809
-
810
- ---
811
230
 
812
- ## Category
813
-
814
- ```ts
815
- export interface ProductCategory {
816
-
231
+ interface ProductCategory {
817
232
  id: string;
818
-
819
233
  name: string;
820
-
821
234
  handle: string;
822
-
823
235
  description?: string;
824
-
825
236
  parentCategoryId?: string;
826
-
827
237
  productCount?: number;
828
-
829
- image?: string;
830
-
831
- metadata?: Record<string, any>;
832
- }
833
- ```
834
-
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;
849
238
  }
850
239
  ```
851
240
 
852
-
853
241
  ---
854
242
 
855
- ## Region
243
+ ## Shipping & Payment
856
244
 
857
245
  ```ts
858
- export interface Region {
859
-
246
+ interface ShippingMethod {
860
247
  id: string;
861
-
862
-
863
248
  name: string;
864
-
865
-
866
- countryCodes: string[];
867
-
868
-
869
- currency: string;
870
-
871
-
872
- paymentProviders?: string[];
873
-
874
-
875
- taxRate?: number;
876
-
877
-
878
- isEnabled?: boolean;
879
-
880
-
881
- metadata?: Record<string, unknown>;
882
- }
883
- ```
884
-
885
-
886
- ---
887
-
888
- ## Shipping
889
-
890
- ```ts
891
- export interface ShippingMethod {
892
-
893
- id: string;
894
-
895
-
896
- name: string;
897
-
898
-
899
249
  price: Money;
900
-
901
-
902
250
  description?: string;
903
-
904
-
905
251
  estimatedDays?: string;
906
252
  }
907
- ```
908
253
 
254
+ type PaymentMethodType = 'card' | 'wallet' | 'bank_transfer' | 'buy_now_pay_later' | 'cash_on_delivery' | 'crypto' | 'other';
909
255
 
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
-
256
+ interface PaymentMethod {
928
257
  id: string;
929
-
930
-
931
258
  name: string;
932
-
933
-
934
259
  type: PaymentMethodType;
935
-
936
-
937
260
  isEnabled: boolean;
938
-
939
-
940
- requiresSetup: boolean;
941
-
942
-
943
261
  description?: string;
944
-
945
-
946
- metadata?: Record<string, unknown>;
947
-
948
-
949
- features?: PaymentMethodFeatures;
950
-
951
-
952
262
  logo?: string;
953
263
  }
954
264
  ```
955
265
 
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;
972
- }
973
- ```
974
-
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;
997
- }
998
- ```
999
-
1000
-
1001
266
  ---
1002
267
 
1003
- ## Inventory & Stock
1004
-
1005
- ```ts
1006
- export type StockStatus = 'in_stock' | 'out_of_stock' | 'low_stock';
1007
- ```
1008
-
1009
- ```ts
1010
- export interface StockLocation {
1011
- id: string;
1012
- name: 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
- };
1026
- }
1027
- ```
1028
-
1029
- ```ts
1030
- export interface InventoryLevel {
1031
- locationId: string;
1032
- locationName: string;
1033
- availableQuantity: number;
1034
- reservedQuantity: number;
1035
- incomingQuantity?: number;
1036
- stockedQuantity: number;
1037
- }
1038
- ```
268
+ ## Auth Types
1039
269
 
1040
270
  ```ts
1041
- export interface StockValidation {
1042
- allAvailable: boolean;
1043
- unavailableItems: Array<{
1044
- variantId: string;
1045
- productName: string;
1046
- requestedQuantity: number;
1047
- availableQuantity: number;
1048
- }>;
1049
- }
1050
- ```
271
+ interface LoginCredentials { email: string; password: string; }
1051
272
 
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;
273
+ interface RegisterData {
274
+ email: string;
275
+ password: string;
276
+ first_name: string;
277
+ last_name: string;
278
+ phone?: string;
1063
279
  }
1064
- ```
1065
-
1066
-
1067
- ---
1068
-
1069
- ## BackendCapabilities
1070
280
 
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;
281
+ interface AuthResponse {
282
+ token?: string;
283
+ customer?: Customer;
1183
284
  }
1184
285
  ```
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` |