@endora-commerce/contracts 0.107.0 → 0.109.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 (273) hide show
  1. package/dist/admin-actions.d.ts +12 -3
  2. package/dist/admin-actions.d.ts.map +1 -1
  3. package/dist/admin-actions.js +34 -3
  4. package/dist/admin-actions.js.map +1 -1
  5. package/dist/admin-contributions.d.ts +35 -6
  6. package/dist/admin-contributions.d.ts.map +1 -1
  7. package/dist/admin-contributions.js +46 -0
  8. package/dist/admin-contributions.js.map +1 -1
  9. package/dist/admin-feedback.d.ts +61 -0
  10. package/dist/admin-feedback.d.ts.map +1 -0
  11. package/dist/admin-feedback.js +71 -0
  12. package/dist/admin-feedback.js.map +1 -0
  13. package/dist/admin-name.d.ts +21 -0
  14. package/dist/admin-name.d.ts.map +1 -0
  15. package/dist/admin-name.js +30 -0
  16. package/dist/admin-name.js.map +1 -0
  17. package/dist/admin-notifications.d.ts +17 -1
  18. package/dist/admin-notifications.d.ts.map +1 -1
  19. package/dist/admin-preferences.d.ts +108 -0
  20. package/dist/admin-preferences.d.ts.map +1 -0
  21. package/dist/admin-preferences.js +133 -0
  22. package/dist/admin-preferences.js.map +1 -0
  23. package/dist/admin.d.ts +15 -1
  24. package/dist/admin.d.ts.map +1 -1
  25. package/dist/admin.js +7 -0
  26. package/dist/admin.js.map +1 -1
  27. package/dist/assets-library.d.ts +97 -3
  28. package/dist/assets-library.d.ts.map +1 -1
  29. package/dist/assets-library.js +5 -0
  30. package/dist/assets-library.js.map +1 -1
  31. package/dist/blog.d.ts +57 -0
  32. package/dist/blog.d.ts.map +1 -1
  33. package/dist/blog.js +63 -1
  34. package/dist/blog.js.map +1 -1
  35. package/dist/carts.d.ts +303 -50
  36. package/dist/carts.d.ts.map +1 -1
  37. package/dist/carts.js +95 -13
  38. package/dist/carts.js.map +1 -1
  39. package/dist/catalog.d.ts +512 -40
  40. package/dist/catalog.d.ts.map +1 -1
  41. package/dist/catalog.js +362 -23
  42. package/dist/catalog.js.map +1 -1
  43. package/dist/cms-brand.d.ts +2233 -0
  44. package/dist/cms-brand.d.ts.map +1 -0
  45. package/dist/cms-brand.js +311 -0
  46. package/dist/cms-brand.js.map +1 -0
  47. package/dist/cms-contact-form.d.ts +55 -0
  48. package/dist/cms-contact-form.d.ts.map +1 -0
  49. package/dist/cms-contact-form.js +100 -0
  50. package/dist/cms-contact-form.js.map +1 -0
  51. package/dist/cms.d.ts +537 -3
  52. package/dist/cms.d.ts.map +1 -1
  53. package/dist/cms.js +251 -0
  54. package/dist/cms.js.map +1 -1
  55. package/dist/common.d.ts +4 -0
  56. package/dist/common.d.ts.map +1 -1
  57. package/dist/common.js +14 -0
  58. package/dist/common.js.map +1 -1
  59. package/dist/comparisons.d.ts +7 -0
  60. package/dist/comparisons.d.ts.map +1 -1
  61. package/dist/comparisons.js +2 -0
  62. package/dist/comparisons.js.map +1 -1
  63. package/dist/credit-limits.d.ts.map +1 -1
  64. package/dist/credit-limits.js +3 -2
  65. package/dist/credit-limits.js.map +1 -1
  66. package/dist/crm-rich-text.d.ts +13 -0
  67. package/dist/crm-rich-text.d.ts.map +1 -0
  68. package/dist/crm-rich-text.js +13 -0
  69. package/dist/crm-rich-text.js.map +1 -0
  70. package/dist/crm.d.ts +180 -62
  71. package/dist/crm.d.ts.map +1 -1
  72. package/dist/crm.js +63 -107
  73. package/dist/crm.js.map +1 -1
  74. package/dist/custom-fields.d.ts +436 -5
  75. package/dist/custom-fields.d.ts.map +1 -1
  76. package/dist/custom-fields.js +325 -10
  77. package/dist/custom-fields.js.map +1 -1
  78. package/dist/customer-accounts.d.ts +30 -0
  79. package/dist/customer-accounts.d.ts.map +1 -1
  80. package/dist/customer-accounts.js +31 -0
  81. package/dist/customer-accounts.js.map +1 -1
  82. package/dist/document-templates.d.ts +211 -23
  83. package/dist/document-templates.d.ts.map +1 -1
  84. package/dist/document-templates.js +98 -1
  85. package/dist/document-templates.js.map +1 -1
  86. package/dist/document-values.d.ts +12 -1
  87. package/dist/document-values.d.ts.map +1 -1
  88. package/dist/document-values.js +41 -11
  89. package/dist/document-values.js.map +1 -1
  90. package/dist/email.d.ts +5 -0
  91. package/dist/email.d.ts.map +1 -1
  92. package/dist/errors.d.ts +142 -8
  93. package/dist/errors.d.ts.map +1 -1
  94. package/dist/errors.js +189 -8
  95. package/dist/errors.js.map +1 -1
  96. package/dist/index.d.ts +24 -1
  97. package/dist/index.d.ts.map +1 -1
  98. package/dist/index.js +43 -1
  99. package/dist/index.js.map +1 -1
  100. package/dist/inventory.d.ts +3 -3
  101. package/dist/invoices.d.ts +6 -2
  102. package/dist/invoices.d.ts.map +1 -1
  103. package/dist/invoices.js +10 -4
  104. package/dist/invoices.js.map +1 -1
  105. package/dist/line-groups.d.ts +80 -0
  106. package/dist/line-groups.d.ts.map +1 -0
  107. package/dist/line-groups.js +130 -0
  108. package/dist/line-groups.js.map +1 -0
  109. package/dist/localized-name.d.ts +20 -0
  110. package/dist/localized-name.d.ts.map +1 -0
  111. package/dist/localized-name.js +45 -0
  112. package/dist/localized-name.js.map +1 -0
  113. package/dist/megamenu.d.ts +674 -0
  114. package/dist/megamenu.d.ts.map +1 -1
  115. package/dist/megamenu.js +96 -3
  116. package/dist/megamenu.js.map +1 -1
  117. package/dist/mfa.d.ts +1 -0
  118. package/dist/mfa.d.ts.map +1 -1
  119. package/dist/mfa.js +8 -2
  120. package/dist/mfa.js.map +1 -1
  121. package/dist/modules.d.ts +8 -1
  122. package/dist/modules.d.ts.map +1 -1
  123. package/dist/modules.js +5 -0
  124. package/dist/modules.js.map +1 -1
  125. package/dist/money-decimal.d.ts +162 -0
  126. package/dist/money-decimal.d.ts.map +1 -0
  127. package/dist/money-decimal.js +365 -0
  128. package/dist/money-decimal.js.map +1 -0
  129. package/dist/money-input.d.ts +64 -0
  130. package/dist/money-input.d.ts.map +1 -0
  131. package/dist/money-input.js +111 -0
  132. package/dist/money-input.js.map +1 -0
  133. package/dist/newsletter.d.ts +3 -3
  134. package/dist/order-minimums.d.ts +111 -0
  135. package/dist/order-minimums.d.ts.map +1 -0
  136. package/dist/order-minimums.js +196 -0
  137. package/dist/order-minimums.js.map +1 -0
  138. package/dist/orders.d.ts +206 -2
  139. package/dist/orders.d.ts.map +1 -1
  140. package/dist/orders.js +106 -5
  141. package/dist/orders.js.map +1 -1
  142. package/dist/page-builder-props.d.ts +1401 -0
  143. package/dist/page-builder-props.d.ts.map +1 -0
  144. package/dist/page-builder-props.js +266 -0
  145. package/dist/page-builder-props.js.map +1 -0
  146. package/dist/page-builder-values.d.ts +95 -0
  147. package/dist/page-builder-values.d.ts.map +1 -0
  148. package/dist/page-builder-values.js +164 -0
  149. package/dist/page-builder-values.js.map +1 -0
  150. package/dist/payment-methods.d.ts.map +1 -1
  151. package/dist/payment-methods.js +2 -1
  152. package/dist/payment-methods.js.map +1 -1
  153. package/dist/pim-connector.d.ts +1 -1
  154. package/dist/platform-language.d.ts +9 -0
  155. package/dist/platform-language.d.ts.map +1 -1
  156. package/dist/platform-language.js +14 -0
  157. package/dist/platform-language.js.map +1 -1
  158. package/dist/price-book-decimal.d.ts +84 -0
  159. package/dist/price-book-decimal.d.ts.map +1 -0
  160. package/dist/price-book-decimal.js +175 -0
  161. package/dist/price-book-decimal.js.map +1 -0
  162. package/dist/price-books.d.ts +2206 -0
  163. package/dist/price-books.d.ts.map +1 -0
  164. package/dist/price-books.js +777 -0
  165. package/dist/price-books.js.map +1 -0
  166. package/dist/price-lists.d.ts +309 -614
  167. package/dist/price-lists.d.ts.map +1 -1
  168. package/dist/price-lists.js +113 -453
  169. package/dist/price-lists.js.map +1 -1
  170. package/dist/product-feeds.d.ts +195 -54
  171. package/dist/product-feeds.d.ts.map +1 -1
  172. package/dist/product-feeds.js +36 -1
  173. package/dist/product-feeds.js.map +1 -1
  174. package/dist/product-scopes.d.ts +628 -0
  175. package/dist/product-scopes.d.ts.map +1 -0
  176. package/dist/product-scopes.js +365 -0
  177. package/dist/product-scopes.js.map +1 -0
  178. package/dist/product-summary-text.d.ts +23 -0
  179. package/dist/product-summary-text.d.ts.map +1 -0
  180. package/dist/product-summary-text.js +64 -0
  181. package/dist/product-summary-text.js.map +1 -0
  182. package/dist/product-url-keys.d.ts +204 -0
  183. package/dist/product-url-keys.d.ts.map +1 -0
  184. package/dist/product-url-keys.js +166 -0
  185. package/dist/product-url-keys.js.map +1 -0
  186. package/dist/product-value-resolver.d.ts +6 -0
  187. package/dist/product-value-resolver.d.ts.map +1 -1
  188. package/dist/product-value-resolver.js +6 -1
  189. package/dist/product-value-resolver.js.map +1 -1
  190. package/dist/projects.d.ts +2355 -0
  191. package/dist/projects.d.ts.map +1 -0
  192. package/dist/projects.js +837 -0
  193. package/dist/projects.js.map +1 -0
  194. package/dist/promotions.d.ts +2 -2
  195. package/dist/promotions.d.ts.map +1 -1
  196. package/dist/promotions.js +8 -2
  197. package/dist/promotions.js.map +1 -1
  198. package/dist/prompt-actions.d.ts +19 -1
  199. package/dist/prompt-actions.d.ts.map +1 -1
  200. package/dist/prompt-actions.js +31 -2
  201. package/dist/prompt-actions.js.map +1 -1
  202. package/dist/quick-order.d.ts +39 -1
  203. package/dist/quick-order.d.ts.map +1 -1
  204. package/dist/quick-order.js +44 -1
  205. package/dist/quick-order.js.map +1 -1
  206. package/dist/quote-requests.d.ts +305 -1
  207. package/dist/quote-requests.d.ts.map +1 -1
  208. package/dist/quote-requests.js +173 -5
  209. package/dist/quote-requests.js.map +1 -1
  210. package/dist/record-references.d.ts +252 -0
  211. package/dist/record-references.d.ts.map +1 -0
  212. package/dist/record-references.js +179 -0
  213. package/dist/record-references.js.map +1 -0
  214. package/dist/record-rich-text.d.ts +66 -0
  215. package/dist/record-rich-text.d.ts.map +1 -0
  216. package/dist/record-rich-text.js +303 -0
  217. package/dist/record-rich-text.js.map +1 -0
  218. package/dist/returns.d.ts +81 -2
  219. package/dist/returns.d.ts.map +1 -1
  220. package/dist/returns.js +39 -4
  221. package/dist/returns.js.map +1 -1
  222. package/dist/sales-channels.d.ts +53 -7
  223. package/dist/sales-channels.d.ts.map +1 -1
  224. package/dist/sales-channels.js +40 -4
  225. package/dist/sales-channels.js.map +1 -1
  226. package/dist/saved-list-views.d.ts +28 -0
  227. package/dist/saved-list-views.d.ts.map +1 -1
  228. package/dist/saved-list-views.js +14 -1
  229. package/dist/saved-list-views.js.map +1 -1
  230. package/dist/scoped-translations.d.ts +48 -0
  231. package/dist/scoped-translations.d.ts.map +1 -0
  232. package/dist/scoped-translations.js +78 -0
  233. package/dist/scoped-translations.js.map +1 -0
  234. package/dist/search.d.ts +73 -5
  235. package/dist/search.d.ts.map +1 -1
  236. package/dist/search.js +4 -0
  237. package/dist/search.js.map +1 -1
  238. package/dist/seo.d.ts +64 -5
  239. package/dist/seo.d.ts.map +1 -1
  240. package/dist/seo.js +31 -4
  241. package/dist/seo.js.map +1 -1
  242. package/dist/settings.d.ts +32 -3
  243. package/dist/settings.d.ts.map +1 -1
  244. package/dist/settings.js +37 -3
  245. package/dist/settings.js.map +1 -1
  246. package/dist/shipping-methods.d.ts.map +1 -1
  247. package/dist/shipping-methods.js +2 -1
  248. package/dist/shipping-methods.js.map +1 -1
  249. package/dist/shopping-lists.d.ts +24 -0
  250. package/dist/shopping-lists.d.ts.map +1 -1
  251. package/dist/shopping-lists.js +20 -1
  252. package/dist/shopping-lists.js.map +1 -1
  253. package/dist/storefront-cache-tags.d.ts +29 -0
  254. package/dist/storefront-cache-tags.d.ts.map +1 -1
  255. package/dist/storefront-cache-tags.js +24 -0
  256. package/dist/storefront-cache-tags.js.map +1 -1
  257. package/dist/storefront-language-path.d.ts +77 -0
  258. package/dist/storefront-language-path.d.ts.map +1 -0
  259. package/dist/storefront-language-path.js +123 -0
  260. package/dist/storefront-language-path.js.map +1 -0
  261. package/dist/storefront-value-overrides.d.ts +67 -0
  262. package/dist/storefront-value-overrides.d.ts.map +1 -0
  263. package/dist/storefront-value-overrides.js +93 -0
  264. package/dist/storefront-value-overrides.js.map +1 -0
  265. package/dist/tasks.d.ts +2842 -0
  266. package/dist/tasks.d.ts.map +1 -0
  267. package/dist/tasks.js +901 -0
  268. package/dist/tasks.js.map +1 -0
  269. package/dist/transactional-emails.d.ts +7 -4
  270. package/dist/transactional-emails.d.ts.map +1 -1
  271. package/dist/transactional-emails.js +13 -0
  272. package/dist/transactional-emails.js.map +1 -1
  273. package/package.json +2 -2
package/dist/catalog.js CHANGED
@@ -1,5 +1,8 @@
1
1
  import { z } from 'zod';
2
2
  import { isoDateTimeSchema, moneySchema, multilingualStringSchema, productVisibilitySchema, uuidSchema, } from './common.js';
3
+ import { ORDER_MINIMUM_MAX } from './order-minimums.js';
4
+ import { productPagePathsSchema } from './product-url-keys.js';
5
+ import { translationMapPatchSchema } from './scoped-translations.js';
3
6
  /**
4
7
  * Catalog module contracts — Source of truth per Principle V.
5
8
  * See specs/001-b2b-platform-foundation/contracts/catalog.contract.md.
@@ -19,20 +22,20 @@ export const productTypeSchema = z.enum([
19
22
  'bundle',
20
23
  'virtual',
21
24
  ]);
22
- 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']);
23
32
  /**
24
33
  * The most products one admin selection may carry: the cap of the admin product
25
34
  * browser (a session refuses to select a 201st row) and the `.max()` of every
26
- * request that submits such a selection in one call, e.g.
27
- * `bulkAddPriceListProductsRequestSchema`. One home for the number, so the
35
+ * request that submits such a selection in one call. One home for the number, so the
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
  /**
@@ -164,15 +167,69 @@ export const productPriceTierSchema = z.object({
164
167
  isSale: z.boolean(),
165
168
  });
166
169
  // --- Product summary (list response) ----------------------------------------
170
+ /**
171
+ * D-287 P0 — the price a storefront surface renders, from the **same**
172
+ * resolution that produced `ProductSummary.price`: the regular (base) price,
173
+ * the sale price when a sale list priced the product, and the display mode.
174
+ *
175
+ * The product page used to fetch this separately from
176
+ * `GET /api/v1/storefront/products/:id/resolved-price` after the catalogue had
177
+ * already priced the product for `price`, so every product page resolved its
178
+ * product twice, and the home page's cards fanned out one such request per card
179
+ * (`specs/pricing/read-paths-and-performance.md` §2.1). Carrying it here makes
180
+ * a catalogue read the one resolution those surfaces need.
181
+ *
182
+ * `basePrice` is the base partition's figure, else the Product's own price
183
+ * when that is what `price` came from; `salePrice` is set only when a sale list
184
+ * priced the product (it is then also `price`). Both are `null` when nothing
185
+ * prices the product; `displayMode` is still the viewer's, so a page can tell
186
+ * "sold on request only" (`none`) from "no price".
187
+ *
188
+ * Issue #491 — under `displayMode: 'none'` the server sends **no amount**:
189
+ * `basePrice` and `salePrice` are `null`, `listPrice` is absent, and so are
190
+ * `ProductSummary.price`, `compareAtPrice` and `priceVariesByVariant` beside it,
191
+ * whatever the price books would charge. The storefront renders "price on
192
+ * request" from `displayMode`; there is no figure to hide. The display-mode values are
193
+ * `displayModeSchema`'s (`price-lists.ts`, which imports this file and checks
194
+ * the two agree at compile time).
195
+ */
196
+ export const productResolvedPriceSchema = z.object({
197
+ basePrice: z.object({ amount: z.string(), currency: z.string().length(3) }).nullable(),
198
+ salePrice: z.object({ amount: z.string(), currency: z.string().length(3) }).nullable(),
199
+ displayMode: z.enum(['gross_only', 'net_only', 'both', 'none']),
200
+ /**
201
+ * Feature 161 (G14) — the catalogue price to show beside a lower buyer price
202
+ * ("list price / your price"). Present only while `pricing.show_list_price`
203
+ * is on and the channel's everyone price is above the price charged; the
204
+ * decision is the pricing engine's (`ListingPriceDetail.listPrice`, G9).
205
+ */
206
+ listPrice: z.object({ amount: z.string(), currency: z.string().length(3) }).optional(),
207
+ });
167
208
  export const productSummarySchema = z.object({
168
209
  id: uuidSchema,
169
210
  sku: z.string().min(1).max(255),
170
211
  type: productTypeSchema,
171
212
  name: z.string(),
172
213
  slug: z.string(),
214
+ /**
215
+ * Feature 163 (R-16) — the description as plain text in the request
216
+ * language, at most 160 characters, cut at a word boundary; `null` without
217
+ * a description. Optional so every producer written before it still compiles.
218
+ */
219
+ summary: z.string().max(160).nullable().optional(),
173
220
  categorySlugs: z.array(z.string()),
174
221
  primaryAssetUrl: z.string().url().nullable(),
175
222
  price: moneySchema.nullable(),
223
+ /**
224
+ * Feature 160 (FR-025) — the buyer's own price, struck through, when `price`
225
+ * is a charged sale. Absent otherwise.
226
+ */
227
+ compareAtPrice: moneySchema.nullable().optional(),
228
+ /**
229
+ * Feature 160 (FR-024) — the product's variants resolve to different prices
230
+ * for this viewer, and `price` is the lowest ("from").
231
+ */
232
+ priceVariesByVariant: z.boolean().optional(),
176
233
  stockIndicator: stockIndicatorSchema.nullable(),
177
234
  stockLevel: z.number().int().nullable(),
178
235
  /**
@@ -186,13 +243,25 @@ export const productSummarySchema = z.object({
186
243
  * indication (band + in-stock flag), present for bound and unbound keys.
187
244
  */
188
245
  availability: productAvailabilitySchema.optional(),
246
+ /**
247
+ * Feature 155 — the product's pieces minimum; `null` = none. Emitted only for
248
+ * `simple` / `configurable` products (else `null`). Optional so every producer
249
+ * written before it still compiles.
250
+ */
251
+ minOrderQuantity: z.number().int().positive().nullable().optional(),
252
+ /**
253
+ * D-287 P0 — base + sale + display mode from the resolution behind `price`
254
+ * ({@link productResolvedPriceSchema}). `null` where the channel withholds
255
+ * prices; absent from producers that do not resolve one (optional so every
256
+ * producer written before it still compiles).
257
+ */
258
+ resolvedPrice: productResolvedPriceSchema.nullable().optional(),
189
259
  });
190
260
  // --- Product variant --------------------------------------------------------
191
261
  export const productVariantSchema = z.object({
192
262
  id: uuidSchema,
193
263
  sku: z.string().min(1).max(255),
194
264
  variantAttributeValues: z.record(z.string(), z.unknown()),
195
- priceOverride: z.number().finite().nullable(),
196
265
  stockLevel: z.number().int().nullable(),
197
266
  });
198
267
  // --- Product detail (PDP response) ------------------------------------------
@@ -234,6 +303,11 @@ export const productDetailSchema = productSummarySchema.extend({
234
303
  slug: z.string(),
235
304
  })),
236
305
  seo: seoMetaSchema,
306
+ /**
307
+ * Feature 163 (FR-074) — the page's canonical and its alternate-language paths,
308
+ * built by catalog with `productPath()` (`contracts/url-keys-and-redirects.md` §6).
309
+ */
310
+ paths: productPagePathsSchema,
237
311
  structuredDataJsonLd: z.record(z.string(), z.unknown()),
238
312
  /**
239
313
  * Feature 002 — the AttributeSet wired to this Product. Optional so
@@ -264,6 +338,12 @@ export const productDetailSchema = productSummarySchema.extend({
264
338
  kind: z.string(),
265
339
  url: z.string(),
266
340
  }),
341
+ /**
342
+ * Feature 163 (FR-077) — the image's alt text at the request's scope language:
343
+ * the product's own, else the asset's; `null` = none. Optional so other
344
+ * builders of the DTO keep compiling; `catalog` always emits it.
345
+ */
346
+ altText: z.string().nullable().optional(),
267
347
  }))
268
348
  .optional(),
269
349
  /**
@@ -384,6 +464,8 @@ export const productDetailSchema = productSummarySchema.extend({
384
464
  baseQuantity: z.number().int().positive(),
385
465
  position: z.number().int().nonnegative(),
386
466
  isDefault: z.boolean(),
467
+ /** Feature 155 — minimum units of this unit per order of the product; `null` = none. */
468
+ minOrderUnits: z.number().int().positive().nullable().optional(),
387
469
  }))
388
470
  .optional(),
389
471
  /**
@@ -480,10 +562,9 @@ const baseProductRequestObject = z.object({
480
562
  stockMode: stockModeSchema.optional(),
481
563
  visibility: productVisibilitySchema,
482
564
  // Feature 022 — accepted by the single-product PATCH and the bulk
483
- // update endpoint. Cross-field rule on `archivedAt` is enforced in
484
- // the service layer (CatalogAdminService.updateProduct).
485
- // Feature 032 — `archived` write alias → `inactive`.
486
- status: productStatusWriteSchema.optional(),
565
+ // update endpoint. Feature 163 — a status write never touches
566
+ // `archivedAt` (FR-010); `draft` / `archived` are refused (FR-112).
567
+ status: productStatusSchema.optional(),
487
568
  allowedOrganizationIds: z.array(uuidSchema).optional(),
488
569
  assetIds: z.array(uuidSchema).optional(),
489
570
  initialStock: z.number().int().nonnegative().optional(),
@@ -526,6 +607,13 @@ const baseProductRequestObject = z.object({
526
607
  .nullable()
527
608
  .optional(),
528
609
  fulfilmentStrategyWarehouseOrder: z.array(uuidSchema).nullable().optional(),
610
+ /**
611
+ * Feature 155 — pieces minimum; `null` clears. Simple / configurable only (else
612
+ * 422 VALIDATION_FAILED, `details.field`, from the service).
613
+ */
614
+ minOrderQuantity: z.number().int().min(1).max(ORDER_MINIMUM_MAX).nullable().optional(),
615
+ /** Feature 155 — may `return`-kind cases include this product? Every type. */
616
+ returnable: z.boolean().optional(),
529
617
  });
530
618
  export const createProductRequestSchema = baseProductRequestObject.refine((v) => {
531
619
  const hasAsset = v.downloadAssetId != null;
@@ -544,7 +632,16 @@ export const createProductRequestSchema = baseProductRequestObject.refine((v) =>
544
632
  // frozen at snapshot time.
545
633
  export const updateProductRequestSchema = baseProductRequestObject
546
634
  .partial()
547
- .omit({ type: true });
635
+ .omit({ type: true })
636
+ .extend({
637
+ /**
638
+ * Feature 163 (FR-023) — the global publication window, inclusive at both
639
+ * ends; `null` opens that side. A start not before the end is refused by the
640
+ * service (`422 VALIDATION_FAILED`, `details.field = 'window'`).
641
+ */
642
+ publishFrom: isoDateTimeSchema.nullable().optional(),
643
+ publishUntil: isoDateTimeSchema.nullable().optional(),
644
+ });
548
645
  // Admin batch-by-id lookup. The body carries the id set (deduped server-
549
646
  // side) plus optional pagination so callers can stream large lookups
550
647
  // across multiple requests. Hard cap of 500 ids per call mirrors the
@@ -558,11 +655,20 @@ export const batchByIdProductsRequestSchema = z.object({
558
655
  // Feature 033 — Resolve product IDs by list filters (collection selection)
559
656
  // ---------------------------------------------------------------------------
560
657
  export const MAX_RESOLVE_SELECTION_SIZE = 10_000;
658
+ /**
659
+ * Feature 163 (FR-113, research R30.4) — which archived products a list or a
660
+ * selection shows, independently of the status: `exclude` hides them, `include`
661
+ * shows them beside the rest, `only` shows nothing else.
662
+ */
663
+ export const productArchivedModeSchema = z.enum(['exclude', 'include', 'only']);
561
664
  export const resolveProductIdsRequestSchema = z.object({
562
665
  status: productStatusSchema.optional(),
563
666
  type: productTypeSchema.optional(),
564
667
  q: z.string().trim().min(1).optional(),
668
+ /** Legacy: `true` means `archived: 'include'`. `archived` wins when both are sent. */
565
669
  includeArchived: z.boolean().optional(),
670
+ /** Feature 163 (R30.4) — absent: `includeArchived`, else `include`, as before. */
671
+ archived: productArchivedModeSchema.optional(),
566
672
  });
567
673
  export const resolveProductIdsResponseSchema = z.object({
568
674
  data: z.object({
@@ -578,7 +684,7 @@ const bulkEditModeSchema = z.enum(['add', 'replace']);
578
684
  // product's current memberships); sales channels keep the two-mode enum.
579
685
  const bulkEditCategoryModeSchema = z.enum(['add', 'replace', 'remove']);
580
686
  const bulkUpdateFieldsObject = z.object({
581
- status: productStatusWriteSchema.optional(),
687
+ status: productStatusSchema.optional(),
582
688
  visibility: productVisibilitySchema.optional(),
583
689
  salesChannels: z
584
690
  .object({
@@ -596,6 +702,25 @@ const bulkUpdateFieldsObject = z.object({
596
702
  // selected product.
597
703
  attributeSetId: uuidSchema.nullable().optional(),
598
704
  attributeValues: z.record(z.string(), z.unknown()).optional(),
705
+ /** Feature 155 — set (or unset) the returnable flag on every selected product. */
706
+ returnable: z.boolean().optional(),
707
+ /**
708
+ * Feature 163 (FR-050) — the status at one channel (`languageCode: null`) or one
709
+ * channel × language; `inherit` removes the override. Never combined with `status`.
710
+ */
711
+ scopedStatus: z
712
+ .object({
713
+ channelId: uuidSchema,
714
+ languageCode: z.string().min(1).max(16).nullable(),
715
+ value: z.enum([...productStatusSchema.options, 'inherit']),
716
+ })
717
+ .optional(),
718
+ /**
719
+ * Feature 163 (FR-053, research R30.3) — Archive (`true`) or Restore (`false`)
720
+ * every selected product, through the single-product Commands. Alone in its
721
+ * request: one meaning per bulk action.
722
+ */
723
+ archived: z.boolean().optional(),
599
724
  });
600
725
  export const bulkUpdateProductsRequestSchema = z.object({
601
726
  // The non-empty constraint is part of the schema (a Zod-level
@@ -610,7 +735,14 @@ export const bulkUpdateProductsRequestSchema = z.object({
610
735
  f.salesChannels !== undefined ||
611
736
  f.categories !== undefined ||
612
737
  f.attributeSetId !== undefined ||
613
- (f.attributeValues !== undefined && Object.keys(f.attributeValues).length > 0), { message: 'at least one field must be present' }),
738
+ f.returnable !== undefined ||
739
+ f.scopedStatus !== undefined ||
740
+ f.archived !== undefined ||
741
+ (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, {
742
+ message: 'scopedStatus cannot be combined with status',
743
+ path: ['scopedStatus'],
744
+ }).refine((f) => f.archived === undefined ||
745
+ Object.entries(f).every(([key, value]) => key === 'archived' || value === undefined), { message: 'archived cannot be combined with any other field', path: ['archived'] }),
614
746
  });
615
747
  export const bulkUpdateProductResultSchema = z.object({
616
748
  productId: z.string().uuid(),
@@ -622,6 +754,10 @@ export const bulkUpdateProductResultSchema = z.object({
622
754
  'permission_denied',
623
755
  'concurrent_modification',
624
756
  'product_not_found',
757
+ // Feature 163 — a scope the product cannot hold (FR-051), and the
758
+ // completeness gate in `refuse` mode (FR-061).
759
+ 'scope_invalid',
760
+ 'completeness_gate',
625
761
  ])
626
762
  .optional(),
627
763
  details: z
@@ -669,11 +805,23 @@ export const bulkOperationStatusSchema = z.enum([
669
805
  /**
670
806
  * One timestamped lifecycle event in a bulk operation's log trail, surfaced
671
807
  * in the bulk-operations detail view next to the per-element results.
808
+ *
809
+ * The trail is stored and read later by administrators in languages of their
810
+ * own, so an entry carries `messageKey` — a key in `catalog`'s bundle and the
811
+ * params that fill it — for its reader to translate, and `message`, the
812
+ * finished English sentence, for a reader that cannot resolve the key. Entries
813
+ * written before `messageKey` existed carry only `message`.
672
814
  */
673
815
  export const bulkOperationLogEntrySchema = z.object({
674
816
  ts: z.string(),
675
817
  level: z.enum(['info', 'warn', 'error']),
676
818
  message: z.string(),
819
+ messageKey: z
820
+ .object({
821
+ key: z.string().min(1),
822
+ params: z.record(z.string(), z.union([z.string(), z.number()])).optional(),
823
+ })
824
+ .optional(),
677
825
  });
678
826
  /**
679
827
  * Known bulk-operation kinds. `type` on the record is an open string (the
@@ -725,15 +873,43 @@ export const bulkOperationsListResponseSchema = z.object({
725
873
  }),
726
874
  });
727
875
  export const bulkOperationResponseSchema = z.object({ data: bulkOperationSchema });
876
+ /**
877
+ * A variant's price is a row of a price book (feature 160, D-287 §5.8), not a
878
+ * field of the variant: a `priceOverride` in the body is refused with
879
+ * `400 PRICE_SET_IN_PRICE_BOOKS` by the route, before this schema strips it
880
+ * (FR-043; {@link PRICE_FIELDS_REFUSED_ON_VARIANTS}).
881
+ */
882
+ /**
883
+ * A variant as the admin reads it (`serializeAdminVariant`) — the answer of
884
+ * `GET /api/v1/admin/catalog/products/:productId/variants` (feature 161):
885
+ * every variant of the product, whatever its channels, status or audience.
886
+ */
887
+ export const adminProductVariantSchema = z.object({
888
+ id: z.string().uuid(),
889
+ parentProductId: z.string().uuid(),
890
+ sku: z.string(),
891
+ variantAttributeValues: z.record(z.string(), z.unknown()),
892
+ stockLevel: z.number().nullable(),
893
+ createdAt: z.string(),
894
+ updatedAt: z.string(),
895
+ });
896
+ export const adminProductVariantsResponseSchema = z.object({ data: z.array(adminProductVariantSchema) });
728
897
  export const createVariantRequestSchema = z.object({
729
898
  sku: z.string().min(1).max(255),
730
899
  variantAttributeValues: z.record(z.string(), z.unknown()),
731
- priceOverride: z.number().finite().optional(),
732
900
  stockLevel: z.number().int().nonnegative().optional(),
733
901
  });
734
902
  export const updateVariantRequestSchema = createVariantRequestSchema
735
903
  .partial()
736
904
  .omit({ sku: true });
905
+ /**
906
+ * Feature 160 (FR-043) — the old price fields a product or variant write
907
+ * refuses with `400 PRICE_SET_IN_PRICE_BOOKS`: prices are set in price books.
908
+ * On a product they are keys of `attributeValues` (the old *default price*) or,
909
+ * from an old client, of the body itself; on a variant, the old price override.
910
+ */
911
+ export const PRICE_FIELDS_REFUSED_ON_PRODUCTS = ['defaultPrice', 'price'];
912
+ export const PRICE_FIELDS_REFUSED_ON_VARIANTS = ['priceOverride', 'defaultPrice', 'price'];
737
913
  /**
738
914
  * Slider-numeric-kind discriminant (feature 002 T013/T021/T022). The API
739
915
  * `type=slider` form needs an extra hint so the service knows whether the
@@ -911,8 +1087,8 @@ export const adminAttributeResponseSchema = z.object({
911
1087
  labelDefault: z.string(),
912
1088
  /** API-form type (feature 002) — emitted alongside the legacy `valueType`. */
913
1089
  type: apiAttributeTypeSchema,
914
- /** Present only when `type === 'slider'`. */
915
- numericKind: numericKindSchema.optional(),
1090
+ /** A kind only when `type === 'slider'`; `null` (or absent) otherwise. */
1091
+ numericKind: numericKindSchema.nullable().optional(),
916
1092
  valueType: attributeValueTypeSchema,
917
1093
  /** Legacy projection of the option values; `null` when not fetched or absent. */
918
1094
  enumValues: z.array(z.string()).nullable(),
@@ -930,6 +1106,13 @@ export const adminAttributeResponseSchema = z.object({
930
1106
  quickSearchable: z.boolean(),
931
1107
  /** Feature 061 (additive) — id of the backing product-host Custom Field definition. */
932
1108
  customFieldDefinitionId: uuidSchema,
1109
+ /**
1110
+ * Feature 023 / 163 (T095b) — whether the attribute's value is set per sales channel
1111
+ * and per language. Optional so other builders of the DTO keep compiling; `catalog`
1112
+ * always emits both.
1113
+ */
1114
+ channelScoped: z.boolean().optional(),
1115
+ languageScoped: z.boolean().optional(),
933
1116
  createdAt: isoDateTimeSchema,
934
1117
  updatedAt: isoDateTimeSchema,
935
1118
  });
@@ -1078,9 +1261,43 @@ export const productListSortSchema = z.enum([
1078
1261
  export function isPriceSort(sort) {
1079
1262
  return sort === 'price' || sort === '-price';
1080
1263
  }
1264
+ /**
1265
+ * Issue #590 — the most products one `GET /api/v1/catalog/products?ids=` names.
1266
+ * A hand-picked set (a blog post's related products) is a strip, not a
1267
+ * catalogue: two dozen is twice the widest strip any surface renders, and it
1268
+ * keeps the one batched price resolution behind the read small.
1269
+ */
1270
+ export const PRODUCT_LIST_MAX_IDS = 24;
1271
+ /**
1272
+ * Issue #590 — `?ids=` on the public listing: a comma-separated list of product
1273
+ * ids, trimmed and de-duplicated (first occurrence wins), at least one and at
1274
+ * most {@link PRODUCT_LIST_MAX_IDS}. A value that is not a uuid is refused
1275
+ * (`400 VALIDATION_FAILED`) rather than dropped, because a caller naming
1276
+ * products by id is a program, and silently answering fewer products than it
1277
+ * asked for would hide its bug.
1278
+ *
1279
+ * The listing answers **the subset of those products this viewer may see** —
1280
+ * channel membership, status, window and audience are the listing's own
1281
+ * availability condition — each priced exactly as any listing card is: one
1282
+ * batched resolution for the viewer (`resolveListingPriceDetails`). An id that
1283
+ * is unknown, deleted, out of channel or hidden from the viewer is simply not
1284
+ * in the answer. The order is the listing's, not the list's; a caller that
1285
+ * cares about its own order re-orders by id.
1286
+ */
1287
+ export const productListIdsSchema = z
1288
+ .string()
1289
+ .transform((raw) => [
1290
+ ...new Set(raw
1291
+ .split(',')
1292
+ .map((id) => id.trim())
1293
+ .filter((id) => id.length > 0)),
1294
+ ])
1295
+ .pipe(z.array(uuidSchema).min(1).max(PRODUCT_LIST_MAX_IDS));
1081
1296
  export const productListQuerySchema = z
1082
1297
  .object({
1083
1298
  q: z.string().optional(),
1299
+ /** Issue #590 — restrict the listing to these products ({@link productListIdsSchema}). */
1300
+ ids: productListIdsSchema.optional(),
1084
1301
  limit: z.coerce.number().int().positive().max(200).default(50),
1085
1302
  cursor: z.string().optional(),
1086
1303
  sort: productListSortSchema.optional(),
@@ -1111,8 +1328,8 @@ export const productListQuerySchema = z
1111
1328
  *
1112
1329
  * It rides on the listing response because the storefront has to decide whether
1113
1330
  * to *render* the price controls, and the answer depends on the viewer and the
1114
- * channel: a non-public channel publishes no prices, and
1115
- * `pricing.unauthenticated_display_mode = none` hides them until login. A
1331
+ * channel: `pricing.unauthenticated_display_mode = none` hides prices until
1332
+ * login, on one channel or on all of them. A
1116
1333
  * storefront that guessed would guess wrong on exactly the deployments that
1117
1334
  * care, and a control that offers an ordering the API refuses is a worse defect
1118
1335
  * than no control.
@@ -1194,12 +1411,24 @@ export const assignAttributesRequestSchema = z
1194
1411
  .strict();
1195
1412
  // --- Feature 002 — Gallery (US3) --------------------------------------------
1196
1413
  export const galleryLabelSchema = z.enum(['base_image', 'small_image', 'thumbnail']);
1414
+ /** Feature 163 (FR-077) — the longest alt text of one image in one language. */
1415
+ export const GALLERY_ALT_TEXT_MAX = 255;
1416
+ /** Feature 163 — the most channels one write names. */
1417
+ export const SCOPED_CHANNELS_MAX = 256;
1197
1418
  export const galleryItemSchema = z.object({
1198
1419
  id: uuidSchema,
1199
1420
  productId: uuidSchema,
1200
1421
  assetId: uuidSchema,
1201
1422
  position: z.number().int().nonnegative(),
1202
1423
  labels: z.array(galleryLabelSchema),
1424
+ /**
1425
+ * Feature 163 (FR-077, R15) — the product's own alt text of the image per language;
1426
+ * a language absent here shows the asset's alt text. Optional so other builders of
1427
+ * the DTO keep compiling; `catalog` always emits it.
1428
+ */
1429
+ altText: z.record(z.string(), z.string()).optional(),
1430
+ /** Feature 163 (FR-076, R14) — the channels the image is hidden in, sorted. Always emitted by `catalog`. */
1431
+ hiddenInChannels: z.array(uuidSchema).optional(),
1203
1432
  createdAt: isoDateTimeSchema,
1204
1433
  updatedAt: isoDateTimeSchema,
1205
1434
  });
@@ -1214,6 +1443,46 @@ export const updateGalleryItemRequestSchema = z
1214
1443
  .object({
1215
1444
  position: z.number().int().nonnegative().optional(),
1216
1445
  labels: z.array(galleryLabelSchema).optional(),
1446
+ /**
1447
+ * Feature 163 (FR-077) — per-language alt text: the named languages are set, an
1448
+ * empty string removes one, an unnamed one is left as it is.
1449
+ */
1450
+ altText: translationMapPatchSchema(GALLERY_ALT_TEXT_MAX).optional(),
1451
+ /** Feature 163 (FR-076) — the channels the image is hidden in; replaces the set. */
1452
+ hiddenInChannels: z.array(uuidSchema).max(SCOPED_CHANNELS_MAX).optional(),
1453
+ })
1454
+ .strict();
1455
+ /**
1456
+ * Feature 163 (FR-076, R14) — a channel's own holders of the gallery roles. `null` =
1457
+ * the global holder applies there. Read with `GET …/gallery/channel-roles`.
1458
+ *
1459
+ * The keys are the camelCase names of the gallery labels (`baseImage` = the
1460
+ * `base_image` label, `smallImage` = `small_image`, `thumbnail` = `thumbnail`); the
1461
+ * label spelling stays a value (`galleryLabelSchema`), never an API key.
1462
+ */
1463
+ export const galleryChannelRolesSchema = z.object({
1464
+ channelId: uuidSchema,
1465
+ roles: z.object({
1466
+ baseImage: uuidSchema.nullable(),
1467
+ smallImage: uuidSchema.nullable(),
1468
+ thumbnail: uuidSchema.nullable(),
1469
+ }),
1470
+ });
1471
+ /**
1472
+ * `PUT …/gallery/channel-roles` — a role named with an item id moves to that item in
1473
+ * the channel, `null` = use inherited (the global holder), an absent role is left as
1474
+ * it is.
1475
+ */
1476
+ export const putGalleryChannelRolesRequestSchema = z
1477
+ .object({
1478
+ channelId: uuidSchema,
1479
+ roles: z
1480
+ .object({
1481
+ baseImage: uuidSchema.nullable().optional(),
1482
+ smallImage: uuidSchema.nullable().optional(),
1483
+ thumbnail: uuidSchema.nullable().optional(),
1484
+ })
1485
+ .strict(),
1217
1486
  })
1218
1487
  .strict();
1219
1488
  export const reorderGalleryRequestSchema = z
@@ -1258,6 +1527,10 @@ export const updateAttachmentTypeRequestSchema = z
1258
1527
  position: z.number().int().nonnegative().optional(),
1259
1528
  })
1260
1529
  .strict();
1530
+ /** Feature 163 (FR-078) — the longest attachment description one language may carry. */
1531
+ export const ATTACHMENT_DESCRIPTION_TRANSLATION_MAX = 4000;
1532
+ /** Feature 163 (FR-078) — an attachment name per language, as long as the global one. */
1533
+ export const ATTACHMENT_NAME_MAX = 160;
1261
1534
  export const productAttachmentSchema = z.object({
1262
1535
  id: uuidSchema,
1263
1536
  productId: uuidSchema,
@@ -1266,6 +1539,15 @@ export const productAttachmentSchema = z.object({
1266
1539
  name: z.string().min(1).max(160),
1267
1540
  description: z.string().nullable(),
1268
1541
  position: z.number().int().nonnegative(),
1542
+ /**
1543
+ * Feature 163 (FR-078, R16) — the name and description per language; a language
1544
+ * absent here shows the global `name` / `description`. Optional so other builders of
1545
+ * the DTO keep compiling; `catalog` always emits them.
1546
+ */
1547
+ nameTranslations: z.record(z.string(), z.string()).optional(),
1548
+ descriptionTranslations: z.record(z.string(), z.string()).optional(),
1549
+ /** Feature 163 (FR-078) — the channels the attachment is hidden in, sorted. Always emitted by `catalog`. */
1550
+ hiddenInChannels: z.array(uuidSchema).optional(),
1269
1551
  createdAt: isoDateTimeSchema,
1270
1552
  updatedAt: isoDateTimeSchema,
1271
1553
  });
@@ -1276,6 +1558,14 @@ export const createAttachmentRequestSchema = z
1276
1558
  name: z.string().min(1).max(160),
1277
1559
  description: z.string().nullable().optional(),
1278
1560
  position: z.number().int().nonnegative().optional(),
1561
+ /**
1562
+ * Feature 163 (FR-078) — the name and description per language: the named
1563
+ * languages are set, an empty string removes one, an unnamed one is left as it is.
1564
+ */
1565
+ nameTranslations: translationMapPatchSchema(ATTACHMENT_NAME_MAX).optional(),
1566
+ descriptionTranslations: translationMapPatchSchema(ATTACHMENT_DESCRIPTION_TRANSLATION_MAX).optional(),
1567
+ /** Feature 163 (FR-078) — the channels the attachment is hidden in; replaces the set. */
1568
+ hiddenInChannels: z.array(uuidSchema).max(SCOPED_CHANNELS_MAX).optional(),
1279
1569
  })
1280
1570
  .strict();
1281
1571
  export const updateAttachmentRequestSchema = z
@@ -1284,9 +1574,19 @@ export const updateAttachmentRequestSchema = z
1284
1574
  name: z.string().min(1).max(160).optional(),
1285
1575
  description: z.string().nullable().optional(),
1286
1576
  position: z.number().int().nonnegative().optional(),
1577
+ /**
1578
+ * Feature 163 (FR-078) — the name and description per language: the named
1579
+ * languages are set, an empty string removes one, an unnamed one is left as it is.
1580
+ */
1581
+ nameTranslations: translationMapPatchSchema(ATTACHMENT_NAME_MAX).optional(),
1582
+ descriptionTranslations: translationMapPatchSchema(ATTACHMENT_DESCRIPTION_TRANSLATION_MAX).optional(),
1583
+ /** Feature 163 (FR-078) — the channels the attachment is hidden in; replaces the set. */
1584
+ hiddenInChannels: z.array(uuidSchema).max(SCOPED_CHANNELS_MAX).optional(),
1287
1585
  })
1288
1586
  .strict();
1289
1587
  // --- Packaging Units (Feature 043) ------------------------------------------
1588
+ /** The longest packaging-unit name, global or (feature 163, FR-079) per language. */
1589
+ export const PACKAGING_UNIT_NAME_MAX = 160;
1290
1590
  /**
1291
1591
  * A named ordering unit attached to a product (e.g. "Paleta" = 480 pieces).
1292
1592
  * Managed in the Inventory section of the admin product card; surfaced on the
@@ -1296,9 +1596,20 @@ export const packagingUnitSchema = z.object({
1296
1596
  id: uuidSchema,
1297
1597
  productId: uuidSchema,
1298
1598
  name: z.string().min(1).max(160),
1599
+ /**
1600
+ * Feature 163 (FR-079, R16) — the name per language; a language absent here shows
1601
+ * `name`. Optional so other builders of the DTO keep compiling; `catalog` always
1602
+ * emits it.
1603
+ */
1604
+ nameTranslations: z.record(z.string(), z.string()).optional(),
1299
1605
  baseQuantity: z.number().int().positive(),
1300
1606
  position: z.number().int().nonnegative(),
1301
1607
  isDefault: z.boolean(),
1608
+ /**
1609
+ * Feature 155 — minimum units of this unit per order of the product; `null` = none.
1610
+ * Always emitted by `catalog`; optional so other builders of the DTO keep compiling.
1611
+ */
1612
+ minOrderUnits: z.number().int().positive().nullable().optional(),
1302
1613
  createdAt: z.string(),
1303
1614
  updatedAt: z.string(),
1304
1615
  });
@@ -1308,6 +1619,13 @@ export const createPackagingUnitRequestSchema = z
1308
1619
  baseQuantity: z.number().int().positive(),
1309
1620
  isDefault: z.boolean().optional(),
1310
1621
  position: z.number().int().nonnegative().optional(),
1622
+ /** Feature 155 — minimum number of this unit per order of the product; `null` clears. */
1623
+ minOrderUnits: z.number().int().min(1).max(ORDER_MINIMUM_MAX).nullable().optional(),
1624
+ /**
1625
+ * Feature 163 (FR-079) — the name per language: the named languages are set, an
1626
+ * empty string removes one, an unnamed one is left as it is.
1627
+ */
1628
+ nameTranslations: translationMapPatchSchema(PACKAGING_UNIT_NAME_MAX).optional(),
1311
1629
  })
1312
1630
  .strict();
1313
1631
  export const updatePackagingUnitRequestSchema = z
@@ -1316,6 +1634,13 @@ export const updatePackagingUnitRequestSchema = z
1316
1634
  baseQuantity: z.number().int().positive().optional(),
1317
1635
  isDefault: z.boolean().optional(),
1318
1636
  position: z.number().int().nonnegative().optional(),
1637
+ /** Feature 155 — minimum number of this unit per order of the product; `null` clears. */
1638
+ minOrderUnits: z.number().int().min(1).max(ORDER_MINIMUM_MAX).nullable().optional(),
1639
+ /**
1640
+ * Feature 163 (FR-079) — the name per language: the named languages are set, an
1641
+ * empty string removes one, an unnamed one is left as it is.
1642
+ */
1643
+ nameTranslations: translationMapPatchSchema(PACKAGING_UNIT_NAME_MAX).optional(),
1319
1644
  })
1320
1645
  .strict();
1321
1646
  export const reorderPackagingUnitsRequestSchema = z
@@ -1621,6 +1946,18 @@ export function isProductVisibleTo(product, audience) {
1621
1946
  return audience.authenticated;
1622
1947
  return true;
1623
1948
  }
1949
+ const SCOPED_STATUS_COLUMN = /^status@([^/]+)(?:\/(.+))?$/;
1950
+ /** The products-file column of a scope: `status@<channel code>` or `status@<channel code>/<language>`. */
1951
+ export function scopedStatusColumn(channelCode, languageCode) {
1952
+ return languageCode === null ? `status@${channelCode}` : `status@${channelCode}/${languageCode}`;
1953
+ }
1954
+ /** The scope a products-file column names, or `null` when it is not a scoped-status column. */
1955
+ export function parseScopedStatusColumn(column) {
1956
+ const match = SCOPED_STATUS_COLUMN.exec(column.trim());
1957
+ if (!match)
1958
+ return null;
1959
+ return { channelCode: match[1], languageCode: match[2] ?? null };
1960
+ }
1624
1961
  /**
1625
1962
  * Scope flags for the **system** product attributes — the ones that are not
1626
1963
  * rows in `product_attributes` and therefore carry no DB-stored scope flags.
@@ -1715,8 +2052,10 @@ export const ProductUpdatedEventV1Schema = z
1715
2052
  })
1716
2053
  .strict();
1717
2054
  /**
1718
- * Payload of `product.archived.v1` — a product's status moved to `inactive`.
1719
- * Emitted beside the `product.updated.v1` of the same write, after it.
2055
+ * Payload of `product.archived.v1` — the product was archived by the Archive action
2056
+ * (feature 163, FR-019; `POST …/products/:id/archive` or bulk `fields.archived`).
2057
+ * Emitted after the `product.updated.v1` `['archivedAt']` of the same action. A
2058
+ * status write never emits it: `inactive` is plain off.
1720
2059
  */
1721
2060
  export const ProductArchivedEventV1Schema = z
1722
2061
  .object({