@thorprovider/storefront 0.9.0 → 0.10.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.
Files changed (46) hide show
  1. package/assets/templates/app/lib/__STOREFRONT__/actions.ts +57 -1
  2. package/assets/templates/app/lib/__STOREFRONT__/commerce.ts +138 -7
  3. package/assets/templates/app/lib/__STOREFRONT__/fulfillment-evidence-port.ts +31 -0
  4. package/assets/templates/app/lib/__STOREFRONT__/handlers.core.ts +21 -4
  5. package/assets/templates/app/lib/__STOREFRONT__/mappers.ts +6 -2
  6. package/assets/templates/app/lib/__STOREFRONT__/order-detail-mapper.ts +642 -0
  7. package/assets/templates/app/lib/__STOREFRONT__/order-detail-port.ts +6 -7
  8. package/assets/templates/app/lib/__STOREFRONT__/ports.ts +13 -3
  9. package/assets/templates/views/account/assembly/assembly.json +0 -5
  10. package/assets/templates/views/account/assembly/index.skeleton.tsx +48 -0
  11. package/assets/templates/views/account/assembly/registry.skeleton.tsx +5 -64
  12. package/assets/templates/views/account/content.ts +7 -7
  13. package/assets/templates/views/account/fulfillment-evidence.client.tsx +34 -0
  14. package/assets/templates/views/account/fulfillment-evidence.defaults.ts +145 -0
  15. package/assets/templates/views/account/fulfillment-evidence.schema.ts +15 -0
  16. package/assets/templates/views/account/index.tsx +41 -3
  17. package/assets/templates/views/account/orders-advanced.client.tsx +10 -99
  18. package/assets/templates/views/account/orders-advanced.defaults.ts +7 -7
  19. package/assets/templates/views/account/registry.tsx +5 -65
  20. package/assets/templates/views/home/assembly/assembly.json +1 -1
  21. package/assets/templates/views/home/assembly/index.skeleton.tsx +3 -1
  22. package/assets/templates/views/home/assembly/registry.skeleton.tsx +1 -0
  23. package/assets/templates/views/home/assembly/slots/hero/UniversalBanner/binding.json +5 -0
  24. package/assets/templates/views/home/assembly/slots/hero/UniversalBanner/catalog.part +4 -0
  25. package/assets/templates/views/home/assembly/slots/hero/UniversalBanner/element.part +4 -0
  26. package/assets/templates/views/home/assembly/slots/hero/UniversalBanner/registry.part +10 -0
  27. package/assets/templates/views/home/content.ts +246 -2
  28. package/assets/templates/views/home/data.ts +10 -1
  29. package/assets/templates/views/home/index.tsx +7 -6
  30. package/assets/templates/views/home/props.ts +7 -1
  31. package/assets/templates/views/home/registry.tsx +11 -28
  32. package/assets/templates/views/home/schema.ts +163 -0
  33. package/bin/storefront.js +13 -14
  34. package/package.json +1 -1
  35. package/recipes/adapter-surface.json +1 -0
  36. package/recipes/archetypes.json +5 -1
  37. package/recipes/catalog.json +9 -1
  38. package/recipes/recipes.json +5 -4
  39. package/scripts/candidate.mjs +55 -14
  40. package/scripts/file-classes.mjs +4 -0
  41. package/skills/sf-view-gen/assets/recipes/archetypes.json +5 -1
  42. package/skills/sf-view-gen/assets/recipes/catalog.json +9 -1
  43. package/skills/sf-view-gen/assets/recipes/recipes.json +5 -4
  44. package/assets/templates/views/account/assembly/slots/boot/AccountBoot/catalog.part +0 -5
  45. package/assets/templates/views/account/assembly/slots/boot/AccountBoot/element.part +0 -5
  46. package/assets/templates/views/account/assembly/slots/boot/AccountBoot/registry.part +0 -1
@@ -32,7 +32,7 @@ import type {
32
32
  CheckoutSavedAddress,
33
33
  CheckoutShippingGroup,
34
34
  } from '@thorprovider/blocks'
35
- import type { OrdersPage, OrdersQuery } from '@thorprovider/blocks/ports'
35
+ import type { OrderDetailSnapshot, OrdersPage, OrdersQuery } from '@thorprovider/blocks/ports'
36
36
  import {
37
37
  EMPTY_CART_STATE,
38
38
  addVariant,
@@ -51,6 +51,7 @@ import {
51
51
  loadCheckoutShippingGroups,
52
52
  loadCustomer,
53
53
  loadCustomerAddresses,
54
+ loadCustomerOrderDetail,
54
55
  loadGeoCities,
55
56
  loadGeoProvinces,
56
57
  loadOrderHistoryPage,
@@ -92,6 +93,7 @@ import {
92
93
  writeAuthToken,
93
94
  } from './session'
94
95
  import type { AccountProfileMetadataPatch, AccountProfilePayload } from './account-profile'
96
+ import { toOrderDetailSnapshot } from './order-detail-mapper'
95
97
 
96
98
  // A `'use server'` module may export ONLY async functions. Next/Turbopack's
97
99
  // server-actions transform registers every export as a runtime server
@@ -191,6 +193,16 @@ type OrdersQueryPageActionResult =
191
193
  | { ok: true; page: OrdersPage }
192
194
  | { ok: false; error: string }
193
195
 
196
+ /**
197
+ * Structured result for the order-detail route. The code is the contract the
198
+ * host port maps to a `PortError`: `forbidden` (no session), `not_found`
199
+ * (unknown or foreign order) and `unavailable` (no detail read configured or a
200
+ * provider failure). It never carries a fabricated order.
201
+ */
202
+ type OrderDetailActionResult =
203
+ | { ok: true; snapshot: OrderDetailSnapshot }
204
+ | { ok: false; code: 'forbidden' | 'not_found' | 'unavailable'; error: string }
205
+
194
206
  /** Basic email shape check; a boundary guard, not a full RFC validation. */
195
207
  const EMAIL_PATTERN = /\S+@\S+\.\S+/
196
208
 
@@ -1487,6 +1499,50 @@ export async function listOrdersQueryPageAction(
1487
1499
  }
1488
1500
  }
1489
1501
 
1502
+ /**
1503
+ * Load ONE order for the authenticated customer and project it into the
1504
+ * order-detail snapshot. It touches ONLY the auth cookie — never the guest cart
1505
+ * — and no token is logged or returned. No token yields `forbidden` without a
1506
+ * backend call; an unknown or foreign order yields `not_found` without
1507
+ * revealing whether it exists. A provider without a customer detail read fails
1508
+ * closed as `unavailable`; the detail is never assembled from the list.
1509
+ */
1510
+ export async function loadOrderDetailAction(input: {
1511
+ id: string
1512
+ }): Promise<OrderDetailActionResult> {
1513
+ const id = typeof input?.id === 'string' ? input.id.trim() : ''
1514
+ if (!id) {
1515
+ return { ok: false, code: 'not_found', error: 'Pedido no encontrado.' }
1516
+ }
1517
+ const context = getStoreContext()
1518
+ const token = await readAuthToken(context)
1519
+ if (!token) {
1520
+ return {
1521
+ ok: false,
1522
+ code: 'forbidden',
1523
+ error: 'Inicia sesión con una cuenta autorizada para consultar el pedido.',
1524
+ }
1525
+ }
1526
+ try {
1527
+ const order = await loadCustomerOrderDetail(token, id, context)
1528
+ return { ok: true, snapshot: toOrderDetailSnapshot(order) }
1529
+ } catch (error) {
1530
+ const code = errorCode(error)
1531
+ if (code === 'ORDER_DETAIL_NOT_FOUND' || code === 'RESOURCE_NOT_FOUND') {
1532
+ return { ok: false, code: 'not_found', error: 'Pedido no encontrado.' }
1533
+ }
1534
+ if (code === 'ORDER_DETAIL_FORBIDDEN' || code === 'AUTH_UNAUTHENTICATED') {
1535
+ return {
1536
+ ok: false,
1537
+ code: 'forbidden',
1538
+ error: 'Inicia sesión con una cuenta autorizada para consultar el pedido.',
1539
+ }
1540
+ }
1541
+ logServerError('loadOrderDetailAction', error)
1542
+ return { ok: false, code: 'unavailable', error: 'No se pudo cargar el pedido.' }
1543
+ }
1544
+ }
1545
+
1490
1546
  // ---------------------------------------------------------------------------
1491
1547
  // Account modules (change: storefront-customer-view, task 4.4)
1492
1548
  // ---------------------------------------------------------------------------
@@ -59,6 +59,7 @@ import {
59
59
  getGeoCities,
60
60
  getGeoProvinces,
61
61
  getCustomerOrdersPage,
62
+ getCustomerOrderDetail,
62
63
  getEligibleShippingMethods,
63
64
  getPaymentMethodsByRegion,
64
65
  getProductDetailByHandle,
@@ -97,7 +98,10 @@ import type {
97
98
  StorefrontOrderLineView,
98
99
  } from './state.core'
99
100
  import { assertBackendConfigured, getDataSource, getStoreContext, type StoreDataSource } from './store-context'
100
- import { queryOrderHistoryPage } from '@thorprovider/blocks'
101
+ // The query engine is imported through its server-safe subpath: the package
102
+ // root is a client entry (`'use client'`), so a Server Action cannot call a
103
+ // function exported from it (React refuses a client function on the server).
104
+ import { queryOrderHistoryPage } from '@thorprovider/blocks/order-history-engine'
101
105
  import type { OrderHistoryAdvancedRecord } from '@thorprovider/blocks'
102
106
  import type { OrdersPage, OrdersQuery } from '@thorprovider/blocks/ports'
103
107
 
@@ -970,6 +974,100 @@ function toOrderHistoryFulfilmentStatus(
970
974
  }
971
975
  }
972
976
 
977
+ type OrderHistoryFulfilmentStage =
978
+ | 'shipped'
979
+ | 'delayed'
980
+ | 'ready_for_pickup'
981
+ | 'partially_delivered'
982
+
983
+ type OrderHistoryLifecycleHint = {
984
+ fulfilment?: OrderHistoryFulfilmentStage
985
+ returns?: OrderHistoryAdvancedRecord['returns']
986
+ payment?: 'partially_paid'
987
+ creditTerms?: boolean
988
+ partiallyCancelled?: boolean
989
+ }
990
+
991
+ const FULFILMENT_STAGES: readonly string[] = [
992
+ 'shipped',
993
+ 'delayed',
994
+ 'ready_for_pickup',
995
+ 'partially_delivered',
996
+ ]
997
+ const RETURN_STAGES: readonly string[] = ['none', 'requested', 'in_progress', 'completed']
998
+
999
+ /**
1000
+ * Optional lifecycle detail the universal order envelope cannot express yet
1001
+ * (a delayed shipment, an open return, a partial payment). A backend or a demo
1002
+ * fixture may publish it under `metadata.orderHistory`; the mapper validates
1003
+ * every value and falls back to the truthful aggregate status otherwise.
1004
+ */
1005
+ function readOrderHistoryHint(order: Order): OrderHistoryLifecycleHint {
1006
+ const raw = order.metadata?.orderHistory
1007
+ if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return {}
1008
+ const candidate = raw as Record<string, unknown>
1009
+ const hint: OrderHistoryLifecycleHint = {}
1010
+ if (typeof candidate.fulfilment === 'string' && FULFILMENT_STAGES.includes(candidate.fulfilment)) {
1011
+ hint.fulfilment = candidate.fulfilment as OrderHistoryFulfilmentStage
1012
+ }
1013
+ if (typeof candidate.returns === 'string' && RETURN_STAGES.includes(candidate.returns)) {
1014
+ hint.returns = candidate.returns as OrderHistoryAdvancedRecord['returns']
1015
+ }
1016
+ if (candidate.payment === 'partially_paid') hint.payment = 'partially_paid'
1017
+ if (typeof candidate.creditTerms === 'boolean') hint.creditTerms = candidate.creditTerms
1018
+ if (typeof candidate.partiallyCancelled === 'boolean') {
1019
+ hint.partiallyCancelled = candidate.partiallyCancelled
1020
+ }
1021
+ return hint
1022
+ }
1023
+
1024
+ /**
1025
+ * The action menu is a function of the order's truthful state: a delivered
1026
+ * order can be repeated, returned or invoiced; an open one can be cancelled or
1027
+ * paid. Capabilities still gate what the store offers, and the block intersects
1028
+ * both lists before rendering an action.
1029
+ */
1030
+ function deriveOrderHistoryActions(input: {
1031
+ commercial: OrderHistoryAdvancedRecord['commercial']
1032
+ paymentStatus: OrderHistoryAdvancedRecord['payment']['status']
1033
+ fulfilmentStatus: OrderHistoryAdvancedRecord['fulfilment']['status']
1034
+ returns: OrderHistoryAdvancedRecord['returns']
1035
+ }): OrderHistoryAdvancedRecord['availableActions'] {
1036
+ const actions: OrderHistoryAdvancedRecord['availableActions'] = ['view']
1037
+ switch (input.commercial) {
1038
+ case 'completed':
1039
+ actions.push('reorder', 'invoice')
1040
+ break
1041
+ case 'cancelled':
1042
+ actions.push('invoice')
1043
+ break
1044
+ case 'processing':
1045
+ if (input.paymentStatus === 'paid') actions.push('invoice')
1046
+ if (input.fulfilmentStatus === 'unfulfilled') actions.push('cancel')
1047
+ break
1048
+ case 'pending':
1049
+ actions.push('cancel')
1050
+ break
1051
+ }
1052
+ if (input.paymentStatus === 'unpaid' || input.paymentStatus === 'partially_paid') {
1053
+ actions.push('pay-balance')
1054
+ }
1055
+ if (
1056
+ input.fulfilmentStatus === 'shipped' ||
1057
+ input.fulfilmentStatus === 'partially_delivered' ||
1058
+ input.fulfilmentStatus === 'ready_for_pickup' ||
1059
+ input.fulfilmentStatus === 'delayed'
1060
+ ) {
1061
+ actions.push('track')
1062
+ }
1063
+ if (input.fulfilmentStatus === 'delivered' && input.returns === 'none') {
1064
+ actions.push('return', 'exchange')
1065
+ }
1066
+ if (input.returns === 'requested' || input.returns === 'in_progress') actions.push('problem')
1067
+ actions.push('support')
1068
+ return actions
1069
+ }
1070
+
973
1071
  function toOrderHistoryDeliveryMode(
974
1072
  order: Order,
975
1073
  ): OrderHistoryAdvancedRecord['deliveryMode'] {
@@ -1005,8 +1103,15 @@ export function toOrderHistoryItem(
1005
1103
 
1006
1104
  /** Map one backend order to the advanced block's normalised record. */
1007
1105
  export function toOrderHistoryRecord(order: Order): OrderHistoryAdvancedRecord {
1106
+ const hint = readOrderHistoryHint(order)
1008
1107
  const items = order.items.map(toOrderHistoryItem)
1009
- return {
1108
+ const commercial = toOrderHistoryCommercial(order.status)
1109
+ const paymentStatus = hint.payment ?? toOrderHistoryPaymentStatus(order.paymentStatus)
1110
+ const fulfilmentStatus =
1111
+ hint.fulfilment ?? toOrderHistoryFulfilmentStatus(order.fulfillmentStatus)
1112
+ const returns =
1113
+ hint.returns ?? (order.fulfillmentStatus === 'returned' ? 'completed' : 'none')
1114
+ const record: OrderHistoryAdvancedRecord = {
1010
1115
  id: order.id,
1011
1116
  number: order.orderNumber,
1012
1117
  placedAt: toOrderHistoryDate(order.createdAt),
@@ -1014,19 +1119,26 @@ export function toOrderHistoryRecord(order: Order): OrderHistoryAdvancedRecord {
1014
1119
  total: toOrderHistoryMoney(order.total),
1015
1120
  items,
1016
1121
  itemCount: items.reduce((sum, item) => sum + item.quantity, 0),
1017
- commercial: toOrderHistoryCommercial(order.status),
1018
- payment: { status: toOrderHistoryPaymentStatus(order.paymentStatus), creditTerms: false },
1122
+ commercial,
1123
+ payment: { status: paymentStatus, creditTerms: hint.creditTerms ?? false },
1019
1124
  refund: toOrderHistoryRefund(order.paymentStatus),
1020
1125
  // The order envelope carries no per-shipment records, so the host reports
1021
1126
  // the aggregate fulfilment status and no fabricated shipment list.
1022
1127
  fulfilment: {
1023
- status: toOrderHistoryFulfilmentStatus(order.fulfillmentStatus),
1128
+ status: fulfilmentStatus,
1024
1129
  shipments: [],
1025
1130
  },
1026
1131
  deliveryMode: toOrderHistoryDeliveryMode(order),
1027
- returns: order.fulfillmentStatus === 'returned' ? 'completed' : 'none',
1028
- availableActions: ['view'],
1132
+ returns,
1133
+ availableActions: deriveOrderHistoryActions({
1134
+ commercial,
1135
+ paymentStatus,
1136
+ fulfilmentStatus,
1137
+ returns,
1138
+ }),
1029
1139
  }
1140
+ if (hint.partiallyCancelled) record.partiallyCancelled = true
1141
+ return record
1030
1142
  }
1031
1143
 
1032
1144
  // The query ids the block renders. Validated here because a Server Action is a
@@ -1081,4 +1193,23 @@ export async function loadOrderHistoryPage(
1081
1193
  return queryOrderHistoryPage(orders.map(toOrderHistoryRecord), normalized)
1082
1194
  }
1083
1195
 
1196
+ /**
1197
+ * Resolve ONE order for the authenticated customer. It is a separate,
1198
+ * ownership-scoped read: the provider resolves the token to a customer and the
1199
+ * order must belong to that customer and the store's channel. In mock mode the
1200
+ * bundled provider serves the same seeded order store as the history; a live
1201
+ * provider that has not shipped the detail endpoint fails closed, and the
1202
+ * detail is never assembled from the list payload.
1203
+ */
1204
+ export async function loadCustomerOrderDetail(
1205
+ token: string | null,
1206
+ id: string,
1207
+ context: StoreContext = getStoreContext(),
1208
+ ): Promise<Order> {
1209
+ return getCustomerOrderDetail(
1210
+ { token, id, salesChannelId: context.salesChannelId },
1211
+ getCommerceClientWithToken,
1212
+ )
1213
+ }
1214
+
1084
1215
  export type { Money }
@@ -0,0 +1,31 @@
1
+ import { PortError } from '@thorprovider/blocks/ports'
2
+ import type { FulfillmentEvidencePort } from '@thorprovider/blocks/ports'
3
+
4
+ export type FulfillmentEvidenceRunner = FulfillmentEvidencePort
5
+
6
+ /**
7
+ * Host seam for the fulfillment-evidence route. Until the evidence backend and
8
+ * signed asset resolution exist, both reads fail closed with a typed
9
+ * `unavailable` error; the landed gallery renders its own error state and never
10
+ * falls back to demo data. The backend owner supplies the runner and the route
11
+ * binding does not change.
12
+ */
13
+ export function createFulfillmentEvidencePort(
14
+ runner?: FulfillmentEvidenceRunner,
15
+ ): FulfillmentEvidencePort {
16
+ if (runner) return runner
17
+ return {
18
+ async getEvidence(fulfillmentId) {
19
+ throw new PortError(
20
+ 'unavailable',
21
+ `Fulfillment evidence is not connected to the backend yet (requested ${fulfillmentId}).`,
22
+ )
23
+ },
24
+ async resolveAssetUrl(assetId) {
25
+ throw new PortError(
26
+ 'unavailable',
27
+ `Evidence asset resolution is not connected to the backend yet (requested ${assetId}).`,
28
+ )
29
+ },
30
+ }
31
+ }
@@ -87,9 +87,18 @@ export function useCoreHandlers() {
87
87
  // A confirmed cart transition — observed only after the mutation
88
88
  // succeeded, and only when a section origin exists (default: off).
89
89
  recordConfirmedTransition('cart_add_confirmed')
90
- } else fail(result.error)
90
+ } else {
91
+ // A refused add (out of stock, no purchasable variant) must be
92
+ // visible: open the sheet so its error label renders instead of
93
+ // failing silently — which read as "the previous item replaced".
94
+ set('/cartOpen', true)
95
+ fail(result.error)
96
+ }
97
+ })
98
+ .catch((error) => {
99
+ set('/cartOpen', true)
100
+ onError('addToCart')(error)
91
101
  })
92
- .catch(onError('addToCart'))
93
102
  },
94
103
  addClickedToCart: () => {
95
104
  // Product-card shortcut: add the clicked product's first purchasable
@@ -104,9 +113,17 @@ export function useCoreHandlers() {
104
113
  applyCart(result.cart)
105
114
  set('/cartOpen', true)
106
115
  recordConfirmedTransition('cart_add_confirmed')
107
- } else fail(result.error)
116
+ } else {
117
+ // Same visibility contract as the explicit add: a refused add
118
+ // opens the sheet so the error is seen, never silent.
119
+ set('/cartOpen', true)
120
+ fail(result.error)
121
+ }
122
+ })
123
+ .catch((error) => {
124
+ set('/cartOpen', true)
125
+ onError('addClickedToCart')(error)
108
126
  })
109
- .catch(onError('addClickedToCart'))
110
127
  },
111
128
  ensureCart: () => {
112
129
  begin()
@@ -21,11 +21,15 @@ export function toFeaturedProduct(card: CardProduct): FeaturedProduct {
21
21
  price: card.price,
22
22
  // Only a real compare-at price is forwarded: the block renders a discount
23
23
  // treatment solely from an `originalPrice > price` pair, and never from a
24
- // fabricated one. Popularity/review/stock fields are omitted — the block
25
- // renders nothing for them instead of claiming `rating: 0` or `inStock`.
24
+ // fabricated one. Popularity/review fields are omitted — the block renders
25
+ // nothing for them instead of claiming `rating: 0`. Availability is
26
+ // forwarded only from real backend evidence (`inStock` on the card): an
27
+ // explicit `false` disables the hero's purchase buttons; absence makes no
28
+ // stock claim (never invented).
26
29
  originalPrice: card.originalPrice,
27
30
  image: card.image ?? '',
28
31
  tag: card.badge,
32
+ ...(card.inStock !== undefined ? { inStock: card.inStock } : {}),
29
33
  }
30
34
  }
31
35