@endora-commerce/contracts 0.108.0 → 0.110.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 (309) hide show
  1. package/dist/actor.d.ts +16 -0
  2. package/dist/actor.d.ts.map +1 -1
  3. package/dist/addresses.d.ts +35 -0
  4. package/dist/addresses.d.ts.map +1 -1
  5. package/dist/addresses.js +8 -1
  6. package/dist/addresses.js.map +1 -1
  7. package/dist/admin-actions.d.ts +12 -3
  8. package/dist/admin-actions.d.ts.map +1 -1
  9. package/dist/admin-actions.js +34 -3
  10. package/dist/admin-actions.js.map +1 -1
  11. package/dist/admin-contributions.d.ts +94 -10
  12. package/dist/admin-contributions.d.ts.map +1 -1
  13. package/dist/admin-contributions.js +65 -0
  14. package/dist/admin-contributions.js.map +1 -1
  15. package/dist/admin-notifications.d.ts +17 -1
  16. package/dist/admin-notifications.d.ts.map +1 -1
  17. package/dist/admin-preferences.d.ts +108 -0
  18. package/dist/admin-preferences.d.ts.map +1 -0
  19. package/dist/admin-preferences.js +133 -0
  20. package/dist/admin-preferences.js.map +1 -0
  21. package/dist/admin-roles.d.ts +8 -2
  22. package/dist/admin-roles.d.ts.map +1 -1
  23. package/dist/admin-roles.js.map +1 -1
  24. package/dist/admin-users.d.ts +9 -0
  25. package/dist/admin-users.d.ts.map +1 -1
  26. package/dist/admin.d.ts +92 -5
  27. package/dist/admin.d.ts.map +1 -1
  28. package/dist/admin.js +86 -3
  29. package/dist/admin.js.map +1 -1
  30. package/dist/assets-library.d.ts +123 -3
  31. package/dist/assets-library.d.ts.map +1 -1
  32. package/dist/assets-library.js +11 -3
  33. package/dist/assets-library.js.map +1 -1
  34. package/dist/audit-logs.d.ts +12 -0
  35. package/dist/audit-logs.d.ts.map +1 -1
  36. package/dist/audit-logs.js +12 -0
  37. package/dist/audit-logs.js.map +1 -1
  38. package/dist/blog.d.ts +431 -14
  39. package/dist/blog.d.ts.map +1 -1
  40. package/dist/blog.js +251 -7
  41. package/dist/blog.js.map +1 -1
  42. package/dist/carts.d.ts +507 -92
  43. package/dist/carts.d.ts.map +1 -1
  44. package/dist/carts.js +197 -21
  45. package/dist/carts.js.map +1 -1
  46. package/dist/catalog.d.ts +515 -144
  47. package/dist/catalog.d.ts.map +1 -1
  48. package/dist/catalog.js +356 -68
  49. package/dist/catalog.js.map +1 -1
  50. package/dist/cms-brand.d.ts +2233 -0
  51. package/dist/cms-brand.d.ts.map +1 -0
  52. package/dist/cms-brand.js +311 -0
  53. package/dist/cms-brand.js.map +1 -0
  54. package/dist/cms-contact-form.d.ts +55 -0
  55. package/dist/cms-contact-form.d.ts.map +1 -0
  56. package/dist/cms-contact-form.js +100 -0
  57. package/dist/cms-contact-form.js.map +1 -0
  58. package/dist/cms.d.ts +576 -17
  59. package/dist/cms.d.ts.map +1 -1
  60. package/dist/cms.js +251 -0
  61. package/dist/cms.js.map +1 -1
  62. package/dist/common.d.ts +23 -6
  63. package/dist/common.d.ts.map +1 -1
  64. package/dist/common.js +25 -2
  65. package/dist/common.js.map +1 -1
  66. package/dist/comparisons.d.ts +28 -21
  67. package/dist/comparisons.d.ts.map +1 -1
  68. package/dist/comparisons.js +2 -1
  69. package/dist/comparisons.js.map +1 -1
  70. package/dist/credit-limits.d.ts +1 -0
  71. package/dist/credit-limits.d.ts.map +1 -1
  72. package/dist/credit-limits.js +14 -0
  73. package/dist/credit-limits.js.map +1 -1
  74. package/dist/crm-rich-text.d.ts +10 -61
  75. package/dist/crm-rich-text.d.ts.map +1 -1
  76. package/dist/crm-rich-text.js +10 -300
  77. package/dist/crm-rich-text.js.map +1 -1
  78. package/dist/crm.d.ts +173 -115
  79. package/dist/crm.d.ts.map +1 -1
  80. package/dist/crm.js +35 -88
  81. package/dist/crm.js.map +1 -1
  82. package/dist/custom-fields.d.ts +54 -22
  83. package/dist/custom-fields.d.ts.map +1 -1
  84. package/dist/custom-fields.js +21 -1
  85. package/dist/custom-fields.js.map +1 -1
  86. package/dist/customer-accounts.d.ts +216 -22
  87. package/dist/customer-accounts.d.ts.map +1 -1
  88. package/dist/customer-accounts.js +70 -0
  89. package/dist/customer-accounts.js.map +1 -1
  90. package/dist/customers.d.ts +40 -73
  91. package/dist/customers.d.ts.map +1 -1
  92. package/dist/customers.js +45 -10
  93. package/dist/customers.js.map +1 -1
  94. package/dist/document-templates.d.ts +35 -23
  95. package/dist/document-templates.d.ts.map +1 -1
  96. package/dist/document-values.d.ts +8 -0
  97. package/dist/document-values.d.ts.map +1 -1
  98. package/dist/document-values.js +24 -6
  99. package/dist/document-values.js.map +1 -1
  100. package/dist/email.d.ts +5 -0
  101. package/dist/email.d.ts.map +1 -1
  102. package/dist/errors.d.ts +224 -1
  103. package/dist/errors.d.ts.map +1 -1
  104. package/dist/errors.js +269 -1
  105. package/dist/errors.js.map +1 -1
  106. package/dist/forms-logic.d.ts +79 -0
  107. package/dist/forms-logic.d.ts.map +1 -0
  108. package/dist/forms-logic.fixtures.d.ts +52 -0
  109. package/dist/forms-logic.fixtures.d.ts.map +1 -0
  110. package/dist/forms-logic.fixtures.js +610 -0
  111. package/dist/forms-logic.fixtures.js.map +1 -0
  112. package/dist/forms-logic.js +699 -0
  113. package/dist/forms-logic.js.map +1 -0
  114. package/dist/forms.d.ts +9833 -0
  115. package/dist/forms.d.ts.map +1 -0
  116. package/dist/forms.js +827 -0
  117. package/dist/forms.js.map +1 -0
  118. package/dist/import-export.d.ts +180 -0
  119. package/dist/import-export.d.ts.map +1 -1
  120. package/dist/import-export.js +60 -0
  121. package/dist/import-export.js.map +1 -1
  122. package/dist/index.d.ts +22 -1
  123. package/dist/index.d.ts.map +1 -1
  124. package/dist/index.js +45 -1
  125. package/dist/index.js.map +1 -1
  126. package/dist/inventory.d.ts +6 -6
  127. package/dist/invoice-ledger.d.ts +7 -7
  128. package/dist/invoices.d.ts +6 -2
  129. package/dist/invoices.d.ts.map +1 -1
  130. package/dist/invoices.js +7 -0
  131. package/dist/invoices.js.map +1 -1
  132. package/dist/megamenu.d.ts +674 -0
  133. package/dist/megamenu.d.ts.map +1 -1
  134. package/dist/megamenu.js +96 -3
  135. package/dist/megamenu.js.map +1 -1
  136. package/dist/mfa.d.ts +125 -4
  137. package/dist/mfa.d.ts.map +1 -1
  138. package/dist/mfa.js +54 -2
  139. package/dist/mfa.js.map +1 -1
  140. package/dist/modules.d.ts +44 -5
  141. package/dist/modules.d.ts.map +1 -1
  142. package/dist/modules.js +73 -0
  143. package/dist/modules.js.map +1 -1
  144. package/dist/money-decimal.d.ts +54 -0
  145. package/dist/money-decimal.d.ts.map +1 -1
  146. package/dist/money-decimal.js +95 -0
  147. package/dist/money-decimal.js.map +1 -1
  148. package/dist/newsletter.d.ts +7 -7
  149. package/dist/orders.d.ts +128 -10
  150. package/dist/orders.d.ts.map +1 -1
  151. package/dist/orders.js +74 -4
  152. package/dist/orders.js.map +1 -1
  153. package/dist/organization-registry-lookup.d.ts +362 -0
  154. package/dist/organization-registry-lookup.d.ts.map +1 -0
  155. package/dist/organization-registry-lookup.js +196 -0
  156. package/dist/organization-registry-lookup.js.map +1 -0
  157. package/dist/organization-roles.d.ts +340 -0
  158. package/dist/organization-roles.d.ts.map +1 -0
  159. package/dist/organization-roles.js +211 -0
  160. package/dist/organization-roles.js.map +1 -0
  161. package/dist/organizations.d.ts +123 -89
  162. package/dist/organizations.d.ts.map +1 -1
  163. package/dist/organizations.js +68 -24
  164. package/dist/organizations.js.map +1 -1
  165. package/dist/page-builder-props.d.ts +1401 -0
  166. package/dist/page-builder-props.d.ts.map +1 -0
  167. package/dist/page-builder-props.js +266 -0
  168. package/dist/page-builder-props.js.map +1 -0
  169. package/dist/page-builder-values.d.ts +95 -0
  170. package/dist/page-builder-values.d.ts.map +1 -0
  171. package/dist/page-builder-values.js +164 -0
  172. package/dist/page-builder-values.js.map +1 -0
  173. package/dist/pim-connector.d.ts +6 -2
  174. package/dist/pim-connector.d.ts.map +1 -1
  175. package/dist/pim-connector.js +6 -2
  176. package/dist/pim-connector.js.map +1 -1
  177. package/dist/pim-field-path.d.ts +5 -1
  178. package/dist/pim-field-path.d.ts.map +1 -1
  179. package/dist/pim-field-path.js +37 -81
  180. package/dist/pim-field-path.js.map +1 -1
  181. package/dist/pim-locale-mapping.d.ts +131 -0
  182. package/dist/pim-locale-mapping.d.ts.map +1 -0
  183. package/dist/pim-locale-mapping.js +193 -0
  184. package/dist/pim-locale-mapping.js.map +1 -0
  185. package/dist/platform-language.d.ts +9 -0
  186. package/dist/platform-language.d.ts.map +1 -1
  187. package/dist/platform-language.js +14 -0
  188. package/dist/platform-language.js.map +1 -1
  189. package/dist/price-books.d.ts +47 -43
  190. package/dist/price-books.d.ts.map +1 -1
  191. package/dist/price-books.js +6 -2
  192. package/dist/price-books.js.map +1 -1
  193. package/dist/price-lists.d.ts +48 -14
  194. package/dist/price-lists.d.ts.map +1 -1
  195. package/dist/price-lists.js +24 -1
  196. package/dist/price-lists.js.map +1 -1
  197. package/dist/product-feeds.d.ts +144 -84
  198. package/dist/product-feeds.d.ts.map +1 -1
  199. package/dist/product-feeds.js +23 -0
  200. package/dist/product-feeds.js.map +1 -1
  201. package/dist/product-scope-model.d.ts +161 -0
  202. package/dist/product-scope-model.d.ts.map +1 -0
  203. package/dist/product-scope-model.js +161 -0
  204. package/dist/product-scope-model.js.map +1 -0
  205. package/dist/product-scope-overrides.d.ts +0 -103
  206. package/dist/product-scope-overrides.d.ts.map +1 -1
  207. package/dist/product-scope-overrides.js +0 -54
  208. package/dist/product-scope-overrides.js.map +1 -1
  209. package/dist/product-scoped-values.d.ts +2610 -0
  210. package/dist/product-scoped-values.d.ts.map +1 -0
  211. package/dist/product-scoped-values.js +425 -0
  212. package/dist/product-scoped-values.js.map +1 -0
  213. package/dist/product-scopes.d.ts +746 -0
  214. package/dist/product-scopes.d.ts.map +1 -0
  215. package/dist/product-scopes.js +436 -0
  216. package/dist/product-scopes.js.map +1 -0
  217. package/dist/product-summary-text.d.ts +23 -0
  218. package/dist/product-summary-text.d.ts.map +1 -0
  219. package/dist/product-summary-text.js +64 -0
  220. package/dist/product-summary-text.js.map +1 -0
  221. package/dist/product-tax-rates.d.ts +38 -0
  222. package/dist/product-tax-rates.d.ts.map +1 -0
  223. package/dist/product-tax-rates.js +45 -0
  224. package/dist/product-tax-rates.js.map +1 -0
  225. package/dist/product-url-keys.d.ts +210 -0
  226. package/dist/product-url-keys.d.ts.map +1 -0
  227. package/dist/product-url-keys.js +200 -0
  228. package/dist/product-url-keys.js.map +1 -0
  229. package/dist/product-value-resolver.d.ts +37 -60
  230. package/dist/product-value-resolver.d.ts.map +1 -1
  231. package/dist/product-value-resolver.js +36 -96
  232. package/dist/product-value-resolver.js.map +1 -1
  233. package/dist/projects.d.ts +2370 -0
  234. package/dist/projects.d.ts.map +1 -0
  235. package/dist/projects.js +843 -0
  236. package/dist/projects.js.map +1 -0
  237. package/dist/promotions.d.ts +10 -10
  238. package/dist/prompt-actions.d.ts +19 -1
  239. package/dist/prompt-actions.d.ts.map +1 -1
  240. package/dist/prompt-actions.js +31 -2
  241. package/dist/prompt-actions.js.map +1 -1
  242. package/dist/pwa.d.ts +2 -2
  243. package/dist/quick-order.d.ts +150 -7
  244. package/dist/quick-order.d.ts.map +1 -1
  245. package/dist/quick-order.js +76 -2
  246. package/dist/quick-order.js.map +1 -1
  247. package/dist/quote-requests.d.ts +99 -13
  248. package/dist/quote-requests.d.ts.map +1 -1
  249. package/dist/quote-requests.js +66 -1
  250. package/dist/quote-requests.js.map +1 -1
  251. package/dist/record-references.d.ts +252 -0
  252. package/dist/record-references.d.ts.map +1 -0
  253. package/dist/record-references.js +178 -0
  254. package/dist/record-references.js.map +1 -0
  255. package/dist/record-rich-text.d.ts +66 -0
  256. package/dist/record-rich-text.d.ts.map +1 -0
  257. package/dist/record-rich-text.js +304 -0
  258. package/dist/record-rich-text.js.map +1 -0
  259. package/dist/returns.d.ts +234 -52
  260. package/dist/returns.d.ts.map +1 -1
  261. package/dist/returns.js +139 -26
  262. package/dist/returns.js.map +1 -1
  263. package/dist/sales-channels.d.ts +51 -7
  264. package/dist/sales-channels.d.ts.map +1 -1
  265. package/dist/sales-channels.js +38 -4
  266. package/dist/sales-channels.js.map +1 -1
  267. package/dist/saved-list-views.d.ts +56 -0
  268. package/dist/saved-list-views.d.ts.map +1 -1
  269. package/dist/saved-list-views.js +27 -1
  270. package/dist/saved-list-views.js.map +1 -1
  271. package/dist/scoped-write-encoding.d.ts +100 -0
  272. package/dist/scoped-write-encoding.d.ts.map +1 -0
  273. package/dist/scoped-write-encoding.js +135 -0
  274. package/dist/scoped-write-encoding.js.map +1 -0
  275. package/dist/search.d.ts +25 -15
  276. package/dist/search.d.ts.map +1 -1
  277. package/dist/seo.d.ts +127 -15
  278. package/dist/seo.d.ts.map +1 -1
  279. package/dist/seo.js +38 -4
  280. package/dist/seo.js.map +1 -1
  281. package/dist/settings.d.ts +161 -3
  282. package/dist/settings.d.ts.map +1 -1
  283. package/dist/settings.js +73 -3
  284. package/dist/settings.js.map +1 -1
  285. package/dist/shopping-lists.d.ts +24 -3
  286. package/dist/shopping-lists.d.ts.map +1 -1
  287. package/dist/shopping-lists.js +20 -0
  288. package/dist/shopping-lists.js.map +1 -1
  289. package/dist/storefront-cache-tags.d.ts +41 -0
  290. package/dist/storefront-cache-tags.d.ts.map +1 -1
  291. package/dist/storefront-cache-tags.js +36 -0
  292. package/dist/storefront-cache-tags.js.map +1 -1
  293. package/dist/storefront-language-path.d.ts +77 -0
  294. package/dist/storefront-language-path.d.ts.map +1 -0
  295. package/dist/storefront-language-path.js +123 -0
  296. package/dist/storefront-language-path.js.map +1 -0
  297. package/dist/storefront-value-overrides.d.ts +18 -56
  298. package/dist/storefront-value-overrides.d.ts.map +1 -1
  299. package/dist/storefront-value-overrides.js +11 -86
  300. package/dist/storefront-value-overrides.js.map +1 -1
  301. package/dist/tasks.d.ts +2842 -0
  302. package/dist/tasks.d.ts.map +1 -0
  303. package/dist/tasks.js +901 -0
  304. package/dist/tasks.js.map +1 -0
  305. package/dist/transactional-emails.d.ts +14 -11
  306. package/dist/transactional-emails.d.ts.map +1 -1
  307. package/dist/transactional-emails.js +13 -0
  308. package/dist/transactional-emails.js.map +1 -1
  309. package/package.json +3 -3
package/dist/catalog.js CHANGED
@@ -1,6 +1,8 @@
1
1
  import { z } from 'zod';
2
2
  import { isoDateTimeSchema, moneySchema, multilingualStringSchema, productVisibilitySchema, uuidSchema, } from './common.js';
3
3
  import { ORDER_MINIMUM_MAX } from './order-minimums.js';
4
+ import { productPagePathsSchema } from './product-url-keys.js';
5
+ import { scopeVersionTokenSchema } from './scoped-write-encoding.js';
4
6
  /**
5
7
  * Catalog module contracts — Source of truth per Principle V.
6
8
  * See specs/001-b2b-platform-foundation/contracts/catalog.contract.md.
@@ -20,7 +22,13 @@ export const productTypeSchema = z.enum([
20
22
  'bundle',
21
23
  'virtual',
22
24
  ]);
23
- export const productStatusSchema = z.enum(['draft', 'active', 'inactive']);
25
+ /**
26
+ * Feature 163, spec Session 2026-10-25 (FR-010, FR-112) — `active` | `inactive` at
27
+ * every scope; `inactive` is plain off. `draft` is gone and the legacy `archived`
28
+ * write alias is refused: archiving is the separate Archive / Restore action
29
+ * (`archivedAt`), never a status.
30
+ */
31
+ export const productStatusSchema = z.enum(['active', 'inactive']);
24
32
  /**
25
33
  * The most products one admin selection may carry: the cap of the admin product
26
34
  * browser (a session refuses to select a 201st row) and the `.max()` of every
@@ -28,11 +36,6 @@ export const productStatusSchema = z.enum(['draft', 'active', 'inactive']);
28
36
  * screen and the endpoint cannot disagree about it.
29
37
  */
30
38
  export const ADMIN_PRODUCT_SELECTION_MAX = 200;
31
- /** Maps legacy `archived` writes to `inactive` (feature 032). */
32
- export function coerceProductStatusWrite(value) {
33
- return value === 'archived' ? 'inactive' : value;
34
- }
35
- export const productStatusWriteSchema = z.preprocess(coerceProductStatusWrite, productStatusSchema);
36
39
  export const stockModeSchema = z.enum(['categorical', 'numeric']);
37
40
  export const stockIndicatorSchema = z.enum(['available', 'to_order', 'out_of_stock']);
38
41
  /**
@@ -54,6 +57,8 @@ export const attributeValueTypeSchema = z.enum([
54
57
  'multiselect',
55
58
  'price',
56
59
  'select',
60
+ // Feature 172 (research R-4) — a Page Builder document per language.
61
+ 'page_builder',
57
62
  ]);
58
63
  /**
59
64
  * API-facing attribute type form for feature 002 contracts. Maps onto
@@ -66,6 +71,8 @@ export const apiAttributeTypeSchema = z.enum([
66
71
  'multiselect',
67
72
  'price',
68
73
  'slider',
74
+ // Feature 172 (research R-4) — the same name in all three vocabularies.
75
+ 'page_builder',
69
76
  ]);
70
77
  /**
71
78
  * The API-form type of a stored attribute, derived from the pair the catalogue
@@ -96,6 +103,8 @@ export function apiAttributeTypeOf(valueType, displayAsSlider) {
96
103
  case 'boolean':
97
104
  case 'date':
98
105
  return 'input';
106
+ case 'page_builder':
107
+ return 'page_builder';
99
108
  }
100
109
  }
101
110
  export const assetKindSchema = z.enum(['image', 'video', 'pdf', 'certificate', 'other']);
@@ -180,7 +189,13 @@ export const productPriceTierSchema = z.object({
180
189
  * when that is what `price` came from; `salePrice` is set only when a sale list
181
190
  * priced the product (it is then also `price`). Both are `null` when nothing
182
191
  * prices the product; `displayMode` is still the viewer's, so a page can tell
183
- * "sold on request only" (`none`) from "no price". The display-mode values are
192
+ * "sold on request only" (`none`) from "no price".
193
+ *
194
+ * Issue #491 — under `displayMode: 'none'` the server sends **no amount**:
195
+ * `basePrice` and `salePrice` are `null`, `listPrice` is absent, and so are
196
+ * `ProductSummary.price`, `compareAtPrice` and `priceVariesByVariant` beside it,
197
+ * whatever the price books would charge. The storefront renders "price on
198
+ * request" from `displayMode`; there is no figure to hide. The display-mode values are
184
199
  * `displayModeSchema`'s (`price-lists.ts`, which imports this file and checks
185
200
  * the two agree at compile time).
186
201
  */
@@ -202,6 +217,12 @@ export const productSummarySchema = z.object({
202
217
  type: productTypeSchema,
203
218
  name: z.string(),
204
219
  slug: z.string(),
220
+ /**
221
+ * Feature 163 (R-16) — the description as plain text in the request
222
+ * language, at most 160 characters, cut at a word boundary; `null` without
223
+ * a description. Optional so every producer written before it still compiles.
224
+ */
225
+ summary: z.string().max(160).nullable().optional(),
205
226
  categorySlugs: z.array(z.string()),
206
227
  primaryAssetUrl: z.string().url().nullable(),
207
228
  price: moneySchema.nullable(),
@@ -241,6 +262,21 @@ export const productSummarySchema = z.object({
241
262
  * producer written before it still compiles).
242
263
  */
243
264
  resolvedPrice: productResolvedPriceSchema.nullable().optional(),
265
+ /**
266
+ * Issue #852 — the VAT rate this buyer is charged for this product, as a
267
+ * fraction (`0.08` = 8 %), resolved by the rule the cart and the order use
268
+ * (`createProductTaxRateResolver`): the product's tax class against the
269
+ * Organization's VAT status and registered country; `0` for a VAT-exempt or
270
+ * reverse-charge Organization; a buyer with no Organization is a VAT payer in
271
+ * PL. A storefront derives a single product's gross price from it.
272
+ *
273
+ * `null` where the resolution failed; absent from producers that do not
274
+ * resolve one (an older backend, the external namespace). Either way a
275
+ * consumer derives **no** gross and shows the net, labelled net — never a
276
+ * gross at an assumed rate. A variant shares its product's tax class, and so
277
+ * its rate.
278
+ */
279
+ vatRate: z.number().finite().nonnegative().nullable().optional(),
244
280
  });
245
281
  // --- Product variant --------------------------------------------------------
246
282
  export const productVariantSchema = z.object({
@@ -264,6 +300,28 @@ export const seoMetaSchema = z.object({
264
300
  * The exported `productLinkSummarySchema` below is the canonical name —
265
301
  * this `*Inline` alias exists only to avoid a circular import.
266
302
  */
303
+ /** One language's Page Builder document. Opaque beyond being a JSON object. */
304
+ const pageBuilderTreeSchema = z.record(z.string(), z.unknown());
305
+ /**
306
+ * Feature 172 — one content attribute as the product page renders it: the
307
+ * attribute's key, the language its document was resolved to (FR-033), and
308
+ * that one document. No label: the storefront prints no heading of its own
309
+ * (OR-4, FR-037).
310
+ */
311
+ export const productPageContentAttributeSchema = z.object({
312
+ key: z.string(),
313
+ language: z.string(),
314
+ content: pageBuilderTreeSchema,
315
+ });
316
+ /**
317
+ * Feature 172 (research R-11) — the query of `GET /api/v1/catalog/products/:idOrSlug`.
318
+ * `include=content` asks for `contentAttributes`; without it the response is
319
+ * what it was before content attributes existed. Not strict: the route's
320
+ * other query parameters are not this schema's to judge.
321
+ */
322
+ export const productDetailQuerySchema = z.object({
323
+ include: z.enum(['content']).optional(),
324
+ });
267
325
  const productLinkSummarySchemaInline = z.object({
268
326
  id: uuidSchema,
269
327
  kind: z.enum(['related', 'up_sell', 'cross_sell']),
@@ -288,6 +346,11 @@ export const productDetailSchema = productSummarySchema.extend({
288
346
  slug: z.string(),
289
347
  })),
290
348
  seo: seoMetaSchema,
349
+ /**
350
+ * Feature 163 (FR-074) — the page's canonical and its alternate-language paths,
351
+ * built by catalog with `productPath()` (`contracts/url-keys-and-redirects.md` §6).
352
+ */
353
+ paths: productPagePathsSchema,
291
354
  structuredDataJsonLd: z.record(z.string(), z.unknown()),
292
355
  /**
293
356
  * Feature 002 — the AttributeSet wired to this Product. Optional so
@@ -318,6 +381,14 @@ export const productDetailSchema = productSummarySchema.extend({
318
381
  kind: z.string(),
319
382
  url: z.string(),
320
383
  }),
384
+ /**
385
+ * Feature 163 (FR-077), feature 174 (`data-model.md` §6, T035) — the image's alt text
386
+ * at the request's (channel, language): its override there, else its Global alt text,
387
+ * else the asset's. `''` = an empty override — a decorative image, rendered `alt=""`;
388
+ * `null` = none at all. Optional so other builders of the DTO keep compiling;
389
+ * `catalog` always emits it.
390
+ */
391
+ altText: z.string().nullable().optional(),
321
392
  }))
322
393
  .optional(),
323
394
  /**
@@ -426,6 +497,14 @@ export const productDetailSchema = productSummarySchema.extend({
426
497
  valueRendered: z.string(),
427
498
  }))
428
499
  .optional(),
500
+ /**
501
+ * Feature 172 (FR-030, FR-036) — the product's Page Builder content
502
+ * attributes, each already resolved to one language, in attribute-set
503
+ * position order. Present **only** when the request asked for it with
504
+ * `?include=content`; `[]` when asked and nothing renders. No label is
505
+ * carried (FR-037).
506
+ */
507
+ contentAttributes: z.array(productPageContentAttributeSchema).optional(),
429
508
  /**
430
509
  * Feature 043 — named packaging units (e.g. "Paleta" = 480 pieces) the
431
510
  * buyer can order by. Present only for eligible product types
@@ -523,23 +602,31 @@ export const filterDefinitionSchema = z.object({
523
602
  filterPosition: z.number().int().min(0).default(0),
524
603
  });
525
604
  // --- Admin write-surface requests -------------------------------------------
605
+ /** Feature 174 (R21) — the longest product name at any scope. */
606
+ export const PRODUCT_NAME_MAX = 255;
607
+ /** Feature 174 (R21) — the longest product description at any scope. */
608
+ export const PRODUCT_DESCRIPTION_MAX = 20_000;
526
609
  // Base shape (no cross-field refine) so updateProductRequestSchema can
527
610
  // `.partial()` it. The cross-field rule for virtual download fields is
528
611
  // applied as a separate refine on the create variant below.
529
612
  const baseProductRequestObject = z.object({
530
613
  sku: z.string().min(1).max(255),
531
614
  type: productTypeSchema,
532
- name: multilingualStringSchema,
533
- description: multilingualStringSchema,
615
+ /**
616
+ * Feature 174 (FR-014) — the Global name, one string. Channel and Channel × language
617
+ * values are written through `PUT …/products/:id/scoped-values`.
618
+ */
619
+ name: z.string().min(1).max(PRODUCT_NAME_MAX),
620
+ /** Feature 174 (FR-014) — the Global description; `null` = none. */
621
+ description: z.string().max(PRODUCT_DESCRIPTION_MAX).nullable(),
534
622
  categoryIds: z.array(uuidSchema),
535
623
  attributeValues: z.record(z.string(), z.unknown()),
536
624
  stockMode: stockModeSchema.optional(),
537
625
  visibility: productVisibilitySchema,
538
626
  // Feature 022 — accepted by the single-product PATCH and the bulk
539
- // update endpoint. Cross-field rule on `archivedAt` is enforced in
540
- // the service layer (CatalogAdminService.updateProduct).
541
- // Feature 032 — `archived` write alias → `inactive`.
542
- status: productStatusWriteSchema.optional(),
627
+ // update endpoint. Feature 163 — a status write never touches
628
+ // `archivedAt` (FR-010); `draft` / `archived` are refused (FR-112).
629
+ status: productStatusSchema.optional(),
543
630
  allowedOrganizationIds: z.array(uuidSchema).optional(),
544
631
  assetIds: z.array(uuidSchema).optional(),
545
632
  initialStock: z.number().int().nonnegative().optional(),
@@ -607,7 +694,21 @@ export const createProductRequestSchema = baseProductRequestObject.refine((v) =>
607
694
  // frozen at snapshot time.
608
695
  export const updateProductRequestSchema = baseProductRequestObject
609
696
  .partial()
610
- .omit({ type: true });
697
+ .omit({ type: true })
698
+ .extend({
699
+ /**
700
+ * Feature 163 (FR-023) — the global publication window, inclusive at both
701
+ * ends; `null` opens that side. A start not before the end is refused by the
702
+ * service (`422 VALIDATION_FAILED`, `details.field = 'window'`).
703
+ */
704
+ publishFrom: isoDateTimeSchema.nullable().optional(),
705
+ publishUntil: isoDateTimeSchema.nullable().optional(),
706
+ /**
707
+ * Feature 174 (R7) — optional precondition: the `products.scope_version` the caller read
708
+ * (`GET …/scoped-values`, opaque). When sent and stale → `409 VERSION_CONFLICT`.
709
+ */
710
+ version: scopeVersionTokenSchema.optional(),
711
+ });
611
712
  // Admin batch-by-id lookup. The body carries the id set (deduped server-
612
713
  // side) plus optional pagination so callers can stream large lookups
613
714
  // across multiple requests. Hard cap of 500 ids per call mirrors the
@@ -621,11 +722,20 @@ export const batchByIdProductsRequestSchema = z.object({
621
722
  // Feature 033 — Resolve product IDs by list filters (collection selection)
622
723
  // ---------------------------------------------------------------------------
623
724
  export const MAX_RESOLVE_SELECTION_SIZE = 10_000;
725
+ /**
726
+ * Feature 163 (FR-113, research R30.4) — which archived products a list or a
727
+ * selection shows, independently of the status: `exclude` hides them, `include`
728
+ * shows them beside the rest, `only` shows nothing else.
729
+ */
730
+ export const productArchivedModeSchema = z.enum(['exclude', 'include', 'only']);
624
731
  export const resolveProductIdsRequestSchema = z.object({
625
732
  status: productStatusSchema.optional(),
626
733
  type: productTypeSchema.optional(),
627
734
  q: z.string().trim().min(1).optional(),
735
+ /** Legacy: `true` means `archived: 'include'`. `archived` wins when both are sent. */
628
736
  includeArchived: z.boolean().optional(),
737
+ /** Feature 163 (R30.4) — absent: `includeArchived`, else `include`, as before. */
738
+ archived: productArchivedModeSchema.optional(),
629
739
  });
630
740
  export const resolveProductIdsResponseSchema = z.object({
631
741
  data: z.object({
@@ -641,7 +751,7 @@ const bulkEditModeSchema = z.enum(['add', 'replace']);
641
751
  // product's current memberships); sales channels keep the two-mode enum.
642
752
  const bulkEditCategoryModeSchema = z.enum(['add', 'replace', 'remove']);
643
753
  const bulkUpdateFieldsObject = z.object({
644
- status: productStatusWriteSchema.optional(),
754
+ status: productStatusSchema.optional(),
645
755
  visibility: productVisibilitySchema.optional(),
646
756
  salesChannels: z
647
757
  .object({
@@ -661,6 +771,23 @@ const bulkUpdateFieldsObject = z.object({
661
771
  attributeValues: z.record(z.string(), z.unknown()).optional(),
662
772
  /** Feature 155 — set (or unset) the returnable flag on every selected product. */
663
773
  returnable: z.boolean().optional(),
774
+ /**
775
+ * Feature 163 (FR-050) — the status at one channel (`languageCode: null`) or one
776
+ * channel × language; `inherit` removes the override. Never combined with `status`.
777
+ */
778
+ scopedStatus: z
779
+ .object({
780
+ channelId: uuidSchema,
781
+ languageCode: z.string().min(1).max(16).nullable(),
782
+ value: z.enum([...productStatusSchema.options, 'inherit']),
783
+ })
784
+ .optional(),
785
+ /**
786
+ * Feature 163 (FR-053, research R30.3) — Archive (`true`) or Restore (`false`)
787
+ * every selected product, through the single-product Commands. Alone in its
788
+ * request: one meaning per bulk action.
789
+ */
790
+ archived: z.boolean().optional(),
664
791
  });
665
792
  export const bulkUpdateProductsRequestSchema = z.object({
666
793
  // The non-empty constraint is part of the schema (a Zod-level
@@ -676,7 +803,13 @@ export const bulkUpdateProductsRequestSchema = z.object({
676
803
  f.categories !== undefined ||
677
804
  f.attributeSetId !== undefined ||
678
805
  f.returnable !== undefined ||
679
- (f.attributeValues !== undefined && Object.keys(f.attributeValues).length > 0), { message: 'at least one field must be present' }),
806
+ f.scopedStatus !== undefined ||
807
+ f.archived !== undefined ||
808
+ (f.attributeValues !== undefined && Object.keys(f.attributeValues).length > 0), { message: 'at least one field must be present' }).refine((f) => f.scopedStatus === undefined || f.status === undefined, {
809
+ message: 'scopedStatus cannot be combined with status',
810
+ path: ['scopedStatus'],
811
+ }).refine((f) => f.archived === undefined ||
812
+ Object.entries(f).every(([key, value]) => key === 'archived' || value === undefined), { message: 'archived cannot be combined with any other field', path: ['archived'] }),
680
813
  });
681
814
  export const bulkUpdateProductResultSchema = z.object({
682
815
  productId: z.string().uuid(),
@@ -688,6 +821,10 @@ export const bulkUpdateProductResultSchema = z.object({
688
821
  'permission_denied',
689
822
  'concurrent_modification',
690
823
  'product_not_found',
824
+ // Feature 163 — a scope the product cannot hold (FR-051), and the
825
+ // completeness gate in `refuse` mode (FR-061).
826
+ 'scope_invalid',
827
+ 'completeness_gate',
691
828
  ])
692
829
  .optional(),
693
830
  details: z
@@ -735,11 +872,23 @@ export const bulkOperationStatusSchema = z.enum([
735
872
  /**
736
873
  * One timestamped lifecycle event in a bulk operation's log trail, surfaced
737
874
  * in the bulk-operations detail view next to the per-element results.
875
+ *
876
+ * The trail is stored and read later by administrators in languages of their
877
+ * own, so an entry carries `messageKey` — a key in `catalog`'s bundle and the
878
+ * params that fill it — for its reader to translate, and `message`, the
879
+ * finished English sentence, for a reader that cannot resolve the key. Entries
880
+ * written before `messageKey` existed carry only `message`.
738
881
  */
739
882
  export const bulkOperationLogEntrySchema = z.object({
740
883
  ts: z.string(),
741
884
  level: z.enum(['info', 'warn', 'error']),
742
885
  message: z.string(),
886
+ messageKey: z
887
+ .object({
888
+ key: z.string().min(1),
889
+ params: z.record(z.string(), z.union([z.string(), z.number()])).optional(),
890
+ })
891
+ .optional(),
743
892
  });
744
893
  /**
745
894
  * Known bulk-operation kinds. `type` on the record is an open string (the
@@ -834,12 +983,23 @@ export const PRICE_FIELDS_REFUSED_ON_VARIANTS = ['priceOverride', 'defaultPrice'
834
983
  * underlying DB `valueType` is `number` or `price`.
835
984
  */
836
985
  export const numericKindSchema = z.enum(['number', 'price']);
986
+ /**
987
+ * The shape of an attribute key — the one rule an attribute is created with,
988
+ * and the one a listing's `filter[attr.<key>]` is held to (issue #687): the
989
+ * key is interpolated into the Meilisearch filter expression, so a key no
990
+ * attribute could have is refused before either listing backend sees it.
991
+ */
992
+ export const attributeKeyShapeSchema = z
993
+ .string()
994
+ .min(1)
995
+ .max(64)
996
+ .regex(/^[a-z][a-z0-9_]*$/, 'must be snake_case, start with a letter');
997
+ /** Whether `key` has the shape of an attribute key ({@link attributeKeyShapeSchema}). */
998
+ export function isAttributeKey(key) {
999
+ return attributeKeyShapeSchema.safeParse(key).success;
1000
+ }
837
1001
  const baseCreateAttributeObject = z.object({
838
- key: z
839
- .string()
840
- .min(1)
841
- .max(64)
842
- .regex(/^[a-z][a-z0-9_]*$/, 'must be snake_case, start with a letter'),
1002
+ key: attributeKeyShapeSchema,
843
1003
  label: multilingualStringSchema,
844
1004
  /**
845
1005
  * Feature 002 — preferred API form. When `type` is present it wins over
@@ -894,20 +1054,11 @@ const baseCreateAttributeObject = z.object({
894
1054
  /** Feature 012 — gates inclusion in the storefront PDP "Parametry produktu" tab. */
895
1055
  isVisibleOnProductPage: z.boolean().optional(),
896
1056
  /**
897
- * Feature 023 — when `true` the attribute may carry per-Sales-Channel
898
- * overrides. Default `false` (global-only). Independent of
899
- * `languageScoped`; the two flags compose into one of four effective
900
- * scopes (`global` / `language` / `channel` / `channel+language`).
1057
+ * Feature 174 (FR-012, R15) — the attribute may carry Channel overrides and, for a text
1058
+ * (`string`) attribute, Channel × language overrides. Default `false` (Global only). The
1059
+ * Global value is always one value, never a language map.
901
1060
  */
902
- channelScoped: z.boolean().optional(),
903
- /**
904
- * Feature 023 — when `true` the attribute's value is keyed by
905
- * language at every slot. For user-defined attributes the baseline
906
- * is stored as `Record<lang, value>` in `products.attribute_values`;
907
- * for the system Name / Description attributes this flag is pinned
908
- * `true` by SYSTEM_ATTRIBUTE_SCOPES.
909
- */
910
- languageScoped: z.boolean().optional(),
1061
+ scopable: z.boolean().optional(),
911
1062
  /**
912
1063
  * Feature 022 (products bulk edit) — makes the attribute available in
913
1064
  * the Products Bulk Edit dialog's attribute field list. Default false;
@@ -976,10 +1127,8 @@ export const updateAttributeRequestSchema = z
976
1127
  filterPosition: z.number().int().min(0).max(10000).optional(),
977
1128
  /** Feature 012 — gates inclusion in the storefront PDP "Parametry produktu" tab. */
978
1129
  isVisibleOnProductPage: z.boolean().optional(),
979
- /** Feature 023 — see `baseCreateAttributeObject.channelScoped`. */
980
- channelScoped: z.boolean().optional(),
981
- /** Feature 023 — see `baseCreateAttributeObject.languageScoped`. */
982
- languageScoped: z.boolean().optional(),
1130
+ /** Feature 174 — see `baseCreateAttributeObject.scopable`. */
1131
+ scopable: z.boolean().optional(),
983
1132
  /** Feature 022 (products bulk edit) — toggles bulk-editability. */
984
1133
  massEditable: z.boolean().optional(),
985
1134
  /** Feature 039 — values participate in Quick Order search. */
@@ -1005,8 +1154,8 @@ export const adminAttributeResponseSchema = z.object({
1005
1154
  labelDefault: z.string(),
1006
1155
  /** API-form type (feature 002) — emitted alongside the legacy `valueType`. */
1007
1156
  type: apiAttributeTypeSchema,
1008
- /** Present only when `type === 'slider'`. */
1009
- numericKind: numericKindSchema.optional(),
1157
+ /** A kind only when `type === 'slider'`; `null` (or absent) otherwise. */
1158
+ numericKind: numericKindSchema.nullable().optional(),
1010
1159
  valueType: attributeValueTypeSchema,
1011
1160
  /** Legacy projection of the option values; `null` when not fetched or absent. */
1012
1161
  enumValues: z.array(z.string()).nullable(),
@@ -1024,6 +1173,13 @@ export const adminAttributeResponseSchema = z.object({
1024
1173
  quickSearchable: z.boolean(),
1025
1174
  /** Feature 061 (additive) — id of the backing product-host Custom Field definition. */
1026
1175
  customFieldDefinitionId: uuidSchema,
1176
+ /**
1177
+ * Feature 174 (R15) — the scope flag and the levels it derives with the value type
1178
+ * (`attributeScopeSet`). Optional so other builders of the DTO keep compiling; `catalog`
1179
+ * always emits both.
1180
+ */
1181
+ scopable: z.boolean().optional(),
1182
+ scopeLevels: z.array(z.enum(['G', 'C', 'CL'])).optional(),
1027
1183
  createdAt: isoDateTimeSchema,
1028
1184
  updatedAt: isoDateTimeSchema,
1029
1185
  });
@@ -1069,15 +1225,22 @@ export const updateCategoryRequestSchema = z
1069
1225
  .strict();
1070
1226
  // --- Category page content ---------------------------------------------------
1071
1227
  /**
1072
- * The ceiling on one category's stored content envelope, in UTF-8 bytes of its
1073
- * JSON serialisation — every language together.
1228
+ * The ceiling on one stored Page Builder content envelope — a category's
1229
+ * content, or one product × content attribute value — in UTF-8 bytes of its
1230
+ * JSON serialisation, every language together.
1074
1231
  *
1075
1232
  * One mebibyte, because that is what a CMS page is held to today: the CMS
1076
1233
  * declares no limit of its own and is bounded by the HTTP layer's default body
1077
1234
  * limit, which is this number. Stated here so the bound also holds for a
1078
1235
  * caller that does not arrive over HTTP.
1079
1236
  */
1080
- export const CATEGORY_CONTENT_MAX_BYTES = 1_048_576;
1237
+ export const PAGE_BUILDER_CONTENT_MAX_BYTES = 1_048_576;
1238
+ /**
1239
+ * The category content ceiling — {@link PAGE_BUILDER_CONTENT_MAX_BYTES}, kept
1240
+ * under its own name for its existing readers. Product content (feature 172)
1241
+ * is held to the same number.
1242
+ */
1243
+ export const CATEGORY_CONTENT_MAX_BYTES = PAGE_BUILDER_CONTENT_MAX_BYTES;
1081
1244
  /**
1082
1245
  * The UTF-8 length of a string, counted rather than encoded: this package
1083
1246
  * compiles for the admin, the storefront and the backend alike and declares
@@ -1106,8 +1269,6 @@ function utf8ByteLength(text) {
1106
1269
  }
1107
1270
  return bytes;
1108
1271
  }
1109
- /** One language's Page Builder document. Opaque beyond being a JSON object. */
1110
- const pageBuilderTreeSchema = z.record(z.string(), z.unknown());
1111
1272
  /**
1112
1273
  * The content an operator authors for a category's storefront page: one Page
1113
1274
  * Builder document per language, keyed like the category's `name`.
@@ -1150,6 +1311,63 @@ export const categoryPageContentSchema = z.object({
1150
1311
  language: z.string().nullable(),
1151
1312
  content: pageBuilderTreeSchema.nullable(),
1152
1313
  });
1314
+ // --- Product content attributes (feature 172) -------------------------------
1315
+ /**
1316
+ * One product × content attribute value: a Page Builder document per
1317
+ * language, the category envelope under the same ceiling. `null` means no
1318
+ * value. The writer drops a language with no block and stores nothing when
1319
+ * none remains (FR-013), so a stored envelope always holds a block.
1320
+ */
1321
+ export const productContentEnvelopeSchema = z
1322
+ .object({
1323
+ languages: z.record(z.string().min(2).max(35), pageBuilderTreeSchema),
1324
+ })
1325
+ .strict()
1326
+ .refine((envelope) => utf8ByteLength(JSON.stringify(envelope)) <= PAGE_BUILDER_CONTENT_MAX_BYTES, { message: `Product content must not exceed ${PAGE_BUILDER_CONTENT_MAX_BYTES} bytes.` })
1327
+ .nullable();
1328
+ /** `PUT /api/v1/admin/catalog/products/:id/content/:attributeKey` — replaces the value. */
1329
+ export const putProductContentRequestSchema = z
1330
+ .object({ content: productContentEnvelopeSchema })
1331
+ .strict();
1332
+ /** The single read and the write's answer: the whole stored (normalised) envelope. */
1333
+ export const adminProductContentSchema = z.object({
1334
+ productId: uuidSchema,
1335
+ attributeKey: z.string(),
1336
+ content: productContentEnvelopeSchema,
1337
+ });
1338
+ /** One stored language of a content value, as the product form's card shows it — never the document. */
1339
+ export const adminProductContentLanguageStatusSchema = z.object({
1340
+ language: z.string(),
1341
+ filled: z.boolean(),
1342
+ blocks: z.number().int().nonnegative(),
1343
+ excerpt: z.string().nullable(),
1344
+ });
1345
+ /** One content attribute of the product's saved attribute set, with its stored languages. */
1346
+ export const adminProductContentAttributeSchema = z.object({
1347
+ /** `product_attributes.id`. */
1348
+ attributeId: uuidSchema,
1349
+ key: z.string(),
1350
+ label: z.record(z.string(), z.string()),
1351
+ labelDefault: z.string(),
1352
+ position: z.number().int().nonnegative(),
1353
+ languages: z.array(adminProductContentLanguageStatusSchema),
1354
+ });
1355
+ /** `GET /api/v1/admin/catalog/products/:id/content` — the cards, by position then key. */
1356
+ export const adminProductContentListSchema = z.object({
1357
+ productId: uuidSchema,
1358
+ attributeSetId: uuidSchema.nullable(),
1359
+ attributes: z.array(adminProductContentAttributeSchema),
1360
+ });
1361
+ /**
1362
+ * `GET /api/v1/admin/catalog/attributes/:idOrKey/usage` — what deleting an
1363
+ * attribute of any type would meet (feature 172, FR-007). `productValueCount`
1364
+ * is the count the delete guard refuses on, from the same query.
1365
+ */
1366
+ export const adminAttributeUsageSchema = z.object({
1367
+ attributeSetCount: z.number().int().nonnegative(),
1368
+ productValueCount: z.number().int().nonnegative(),
1369
+ productContentCount: z.number().int().nonnegative(),
1370
+ });
1153
1371
  // --- Storefront list/query ---------------------------------------------------
1154
1372
  /**
1155
1373
  * The orderings the storefront listing accepts.
@@ -1172,9 +1390,43 @@ export const productListSortSchema = z.enum([
1172
1390
  export function isPriceSort(sort) {
1173
1391
  return sort === 'price' || sort === '-price';
1174
1392
  }
1393
+ /**
1394
+ * Issue #590 — the most products one `GET /api/v1/catalog/products?ids=` names.
1395
+ * A hand-picked set (a blog post's related products) is a strip, not a
1396
+ * catalogue: two dozen is twice the widest strip any surface renders, and it
1397
+ * keeps the one batched price resolution behind the read small.
1398
+ */
1399
+ export const PRODUCT_LIST_MAX_IDS = 24;
1400
+ /**
1401
+ * Issue #590 — `?ids=` on the public listing: a comma-separated list of product
1402
+ * ids, trimmed and de-duplicated (first occurrence wins), at least one and at
1403
+ * most {@link PRODUCT_LIST_MAX_IDS}. A value that is not a uuid is refused
1404
+ * (`400 VALIDATION_FAILED`) rather than dropped, because a caller naming
1405
+ * products by id is a program, and silently answering fewer products than it
1406
+ * asked for would hide its bug.
1407
+ *
1408
+ * The listing answers **the subset of those products this viewer may see** —
1409
+ * channel membership, status, window and audience are the listing's own
1410
+ * availability condition — each priced exactly as any listing card is: one
1411
+ * batched resolution for the viewer (`resolveListingPriceDetails`). An id that
1412
+ * is unknown, deleted, out of channel or hidden from the viewer is simply not
1413
+ * in the answer. The order is the listing's, not the list's; a caller that
1414
+ * cares about its own order re-orders by id.
1415
+ */
1416
+ export const productListIdsSchema = z
1417
+ .string()
1418
+ .transform((raw) => [
1419
+ ...new Set(raw
1420
+ .split(',')
1421
+ .map((id) => id.trim())
1422
+ .filter((id) => id.length > 0)),
1423
+ ])
1424
+ .pipe(z.array(uuidSchema).min(1).max(PRODUCT_LIST_MAX_IDS));
1175
1425
  export const productListQuerySchema = z
1176
1426
  .object({
1177
1427
  q: z.string().optional(),
1428
+ /** Issue #590 — restrict the listing to these products ({@link productListIdsSchema}). */
1429
+ ids: productListIdsSchema.optional(),
1178
1430
  limit: z.coerce.number().int().positive().max(200).default(50),
1179
1431
  cursor: z.string().optional(),
1180
1432
  sort: productListSortSchema.optional(),
@@ -1205,8 +1457,8 @@ export const productListQuerySchema = z
1205
1457
  *
1206
1458
  * It rides on the listing response because the storefront has to decide whether
1207
1459
  * to *render* the price controls, and the answer depends on the viewer and the
1208
- * channel: a non-public channel publishes no prices, and
1209
- * `pricing.unauthenticated_display_mode = none` hides them until login. A
1460
+ * channel: `pricing.unauthenticated_display_mode = none` hides prices until
1461
+ * login, on one channel or on all of them. A
1210
1462
  * storefront that guessed would guess wrong on exactly the deployments that
1211
1463
  * care, and a control that offers an ordering the API refuses is a worse defect
1212
1464
  * than no control.
@@ -1251,12 +1503,9 @@ export const attributeSetAssignedAttributeSchema = z.object({
1251
1503
  label: multilingualStringSchema,
1252
1504
  valueType: attributeValueTypeSchema,
1253
1505
  position: z.number().int().nonnegative(),
1254
- /**
1255
- * Feature 023 — the attribute's value is keyed by language, so the product
1256
- * editor renders it (and anything scoped to it, such as feature 068's
1257
- * overwrite protection) per language rather than once for the attribute.
1258
- */
1259
- languageScoped: z.boolean(),
1506
+ /** Feature 174 (R15) — the attribute's scope flag and the levels it derives. */
1507
+ scopable: z.boolean(),
1508
+ scopeLevels: z.array(z.enum(['G', 'C', 'CL'])),
1260
1509
  });
1261
1510
  export const attributeSetDetailSchema = attributeSetSchema.extend({
1262
1511
  attributes: z.array(attributeSetAssignedAttributeSchema),
@@ -1288,12 +1537,22 @@ export const assignAttributesRequestSchema = z
1288
1537
  .strict();
1289
1538
  // --- Feature 002 — Gallery (US3) --------------------------------------------
1290
1539
  export const galleryLabelSchema = z.enum(['base_image', 'small_image', 'thumbnail']);
1540
+ /** Feature 163 / 174 — the longest alt text of one image at one scope. */
1541
+ export const GALLERY_ALT_TEXT_MAX = 255;
1291
1542
  export const galleryItemSchema = z.object({
1292
1543
  id: uuidSchema,
1293
1544
  productId: uuidSchema,
1294
1545
  assetId: uuidSchema,
1295
1546
  position: z.number().int().nonnegative(),
1296
1547
  labels: z.array(galleryLabelSchema),
1548
+ /**
1549
+ * Feature 174 (data-model §6) — the Global alt text (`null` = none: the asset's own alt text
1550
+ * is the derived fallback) and the Global hidden flag. Read-only here: every scope of both is
1551
+ * written through `PUT …/products/:id/scoped-values`. Optional so other builders of the DTO
1552
+ * keep compiling; `catalog` always emits both.
1553
+ */
1554
+ altText: z.string().nullable().optional(),
1555
+ hidden: z.boolean().optional(),
1297
1556
  createdAt: isoDateTimeSchema,
1298
1557
  updatedAt: isoDateTimeSchema,
1299
1558
  });
@@ -1304,12 +1563,21 @@ export const createGalleryItemRequestSchema = z
1304
1563
  labels: z.array(galleryLabelSchema).optional(),
1305
1564
  })
1306
1565
  .strict();
1566
+ /**
1567
+ * Feature 174 (`contracts/scoped-values-api.md` §6) — a collection operation only: the item's
1568
+ * position. Its roles (`galleryRole:<label>`), alt text and hidden flag are scoped fields, written
1569
+ * at every scope, Global included, through `PUT …/products/:id/scoped-values`.
1570
+ */
1307
1571
  export const updateGalleryItemRequestSchema = z
1308
1572
  .object({
1309
1573
  position: z.number().int().nonnegative().optional(),
1310
- labels: z.array(galleryLabelSchema).optional(),
1311
1574
  })
1312
1575
  .strict();
1576
+ /*
1577
+ * Feature 174 (`contracts/scoped-values-api.md` §6) — 163's `GET` / `PUT …/gallery/channel-roles`
1578
+ * are retired: a gallery role at G, C or C×L is the scoped field `galleryRole:<label>`, written
1579
+ * through `PUT …/products/:id/scoped-values` (`null` = no image holds the role at the scope).
1580
+ */
1313
1581
  export const reorderGalleryRequestSchema = z
1314
1582
  .object({
1315
1583
  orderedGalleryItemIds: z.array(uuidSchema).min(1),
@@ -1352,6 +1620,10 @@ export const updateAttachmentTypeRequestSchema = z
1352
1620
  position: z.number().int().nonnegative().optional(),
1353
1621
  })
1354
1622
  .strict();
1623
+ /** Feature 163 / 174 — the longest attachment description at a Channel or Channel × language scope. */
1624
+ export const ATTACHMENT_DESCRIPTION_TRANSLATION_MAX = 4000;
1625
+ /** Feature 163 / 174 — an attachment name at any scope, as long as the Global one. */
1626
+ export const ATTACHMENT_NAME_MAX = 160;
1355
1627
  export const productAttachmentSchema = z.object({
1356
1628
  id: uuidSchema,
1357
1629
  productId: uuidSchema,
@@ -1360,6 +1632,12 @@ export const productAttachmentSchema = z.object({
1360
1632
  name: z.string().min(1).max(160),
1361
1633
  description: z.string().nullable(),
1362
1634
  position: z.number().int().nonnegative(),
1635
+ /**
1636
+ * Feature 174 (data-model §7) — hidden at Global. Channel and Channel × language values of the
1637
+ * name, description and hidden flag are written through `PUT …/products/:id/scoped-values`.
1638
+ * Optional so other builders of the DTO keep compiling; `catalog` always emits it.
1639
+ */
1640
+ hidden: z.boolean().optional(),
1363
1641
  createdAt: isoDateTimeSchema,
1364
1642
  updatedAt: isoDateTimeSchema,
1365
1643
  });
@@ -1372,15 +1650,20 @@ export const createAttachmentRequestSchema = z
1372
1650
  position: z.number().int().nonnegative().optional(),
1373
1651
  })
1374
1652
  .strict();
1653
+ /**
1654
+ * Feature 174 (`contracts/scoped-values-api.md` §6) — the attachment's type and position. Its
1655
+ * name, description and hidden flag are scoped fields, written at every scope, Global included,
1656
+ * through `PUT …/products/:id/scoped-values`.
1657
+ */
1375
1658
  export const updateAttachmentRequestSchema = z
1376
1659
  .object({
1377
1660
  attachmentTypeId: uuidSchema.optional(),
1378
- name: z.string().min(1).max(160).optional(),
1379
- description: z.string().nullable().optional(),
1380
1661
  position: z.number().int().nonnegative().optional(),
1381
1662
  })
1382
1663
  .strict();
1383
1664
  // --- Packaging Units (Feature 043) ------------------------------------------
1665
+ /** The longest packaging-unit name at any scope. */
1666
+ export const PACKAGING_UNIT_NAME_MAX = 160;
1384
1667
  /**
1385
1668
  * A named ordering unit attached to a product (e.g. "Paleta" = 480 pieces).
1386
1669
  * Managed in the Inventory section of the admin product card; surfaced on the
@@ -1389,6 +1672,7 @@ export const updateAttachmentRequestSchema = z
1389
1672
  export const packagingUnitSchema = z.object({
1390
1673
  id: uuidSchema,
1391
1674
  productId: uuidSchema,
1675
+ /** The Global name; Channel and Channel × language names go through `…/scoped-values` (feature 174). */
1392
1676
  name: z.string().min(1).max(160),
1393
1677
  baseQuantity: z.number().int().positive(),
1394
1678
  position: z.number().int().nonnegative(),
@@ -1411,9 +1695,13 @@ export const createPackagingUnitRequestSchema = z
1411
1695
  minOrderUnits: z.number().int().min(1).max(ORDER_MINIMUM_MAX).nullable().optional(),
1412
1696
  })
1413
1697
  .strict();
1698
+ /**
1699
+ * Feature 174 (`contracts/scoped-values-api.md` §6) — base quantity, default flag, position and
1700
+ * minimum. The unit's name is a scoped field, written at every scope, Global included, through
1701
+ * `PUT …/products/:id/scoped-values`.
1702
+ */
1414
1703
  export const updatePackagingUnitRequestSchema = z
1415
1704
  .object({
1416
- name: z.string().trim().min(1).max(160).optional(),
1417
1705
  baseQuantity: z.number().int().positive().optional(),
1418
1706
  isDefault: z.boolean().optional(),
1419
1707
  position: z.number().int().nonnegative().optional(),
@@ -1724,6 +2012,10 @@ export function isProductVisibleTo(product, audience) {
1724
2012
  return audience.authenticated;
1725
2013
  return true;
1726
2014
  }
2015
+ /** The products-file column of a scope: `<field>@<channel code>` or `<field>@<channel code>/<language>`. */
2016
+ export function scopedColumn(field, channelCode, languageCode) {
2017
+ return languageCode === null ? `${field}@${channelCode}` : `${field}@${channelCode}/${languageCode}`;
2018
+ }
1727
2019
  /**
1728
2020
  * Scope flags for the **system** product attributes — the ones that are not
1729
2021
  * rows in `product_attributes` and therefore carry no DB-stored scope flags.
@@ -1739,8 +2031,8 @@ export function isProductVisibleTo(product, audience) {
1739
2031
  * — enforced at write time by the override-service validator.
1740
2032
  */
1741
2033
  export const SYSTEM_ATTRIBUTE_SCOPES = {
1742
- name: { channelScoped: true, languageScoped: true },
1743
- description: { channelScoped: true, languageScoped: true },
2034
+ name: { scopable: true },
2035
+ description: { scopable: true },
1744
2036
  };
1745
2037
  export function isSystemAttributeKey(key) {
1746
2038
  return Object.prototype.hasOwnProperty.call(SYSTEM_ATTRIBUTE_SCOPES, key);
@@ -1758,13 +2050,7 @@ export function getAttributeScope(attributeKey, productAttributeRow) {
1758
2050
  // index signature still widens under `noUncheckedIndexedAccess`.
1759
2051
  return SYSTEM_ATTRIBUTE_SCOPES[attributeKey];
1760
2052
  }
1761
- if (productAttributeRow) {
1762
- return {
1763
- channelScoped: productAttributeRow.channelScoped,
1764
- languageScoped: productAttributeRow.languageScoped,
1765
- };
1766
- }
1767
- return { channelScoped: false, languageScoped: false };
2053
+ return { scopable: productAttributeRow?.scopable ?? false };
1768
2054
  }
1769
2055
  // ---------------------------------------------------------------------------
1770
2056
  // Events offered to outbound webhooks
@@ -1818,8 +2104,10 @@ export const ProductUpdatedEventV1Schema = z
1818
2104
  })
1819
2105
  .strict();
1820
2106
  /**
1821
- * Payload of `product.archived.v1` — a product's status moved to `inactive`.
1822
- * Emitted beside the `product.updated.v1` of the same write, after it.
2107
+ * Payload of `product.archived.v1` — the product was archived by the Archive action
2108
+ * (feature 163, FR-019; `POST …/products/:id/archive` or bulk `fields.archived`).
2109
+ * Emitted after the `product.updated.v1` `['archivedAt']` of the same action. A
2110
+ * status write never emits it: `inactive` is plain off.
1823
2111
  */
1824
2112
  export const ProductArchivedEventV1Schema = z
1825
2113
  .object({