@endora-commerce/contracts 0.108.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 (199) 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-notifications.d.ts +17 -1
  10. package/dist/admin-notifications.d.ts.map +1 -1
  11. package/dist/admin-preferences.d.ts +108 -0
  12. package/dist/admin-preferences.d.ts.map +1 -0
  13. package/dist/admin-preferences.js +133 -0
  14. package/dist/admin-preferences.js.map +1 -0
  15. package/dist/admin.d.ts +15 -1
  16. package/dist/admin.d.ts.map +1 -1
  17. package/dist/admin.js +7 -0
  18. package/dist/admin.js.map +1 -1
  19. package/dist/assets-library.d.ts +97 -3
  20. package/dist/assets-library.d.ts.map +1 -1
  21. package/dist/assets-library.js +5 -0
  22. package/dist/assets-library.js.map +1 -1
  23. package/dist/blog.d.ts +57 -0
  24. package/dist/blog.d.ts.map +1 -1
  25. package/dist/blog.js +63 -1
  26. package/dist/blog.js.map +1 -1
  27. package/dist/carts.d.ts +113 -56
  28. package/dist/carts.d.ts.map +1 -1
  29. package/dist/carts.js +66 -13
  30. package/dist/carts.js.map +1 -1
  31. package/dist/catalog.d.ts +273 -34
  32. package/dist/catalog.d.ts.map +1 -1
  33. package/dist/catalog.js +256 -20
  34. package/dist/catalog.js.map +1 -1
  35. package/dist/cms-brand.d.ts +2233 -0
  36. package/dist/cms-brand.d.ts.map +1 -0
  37. package/dist/cms-brand.js +311 -0
  38. package/dist/cms-brand.js.map +1 -0
  39. package/dist/cms-contact-form.d.ts +55 -0
  40. package/dist/cms-contact-form.d.ts.map +1 -0
  41. package/dist/cms-contact-form.js +100 -0
  42. package/dist/cms-contact-form.js.map +1 -0
  43. package/dist/cms.d.ts +537 -3
  44. package/dist/cms.d.ts.map +1 -1
  45. package/dist/cms.js +251 -0
  46. package/dist/cms.js.map +1 -1
  47. package/dist/crm-rich-text.d.ts +10 -61
  48. package/dist/crm-rich-text.d.ts.map +1 -1
  49. package/dist/crm-rich-text.js +10 -300
  50. package/dist/crm-rich-text.js.map +1 -1
  51. package/dist/crm.d.ts +110 -82
  52. package/dist/crm.d.ts.map +1 -1
  53. package/dist/crm.js +29 -88
  54. package/dist/crm.js.map +1 -1
  55. package/dist/custom-fields.d.ts +27 -9
  56. package/dist/custom-fields.d.ts.map +1 -1
  57. package/dist/custom-fields.js +6 -0
  58. package/dist/custom-fields.js.map +1 -1
  59. package/dist/customer-accounts.d.ts +30 -0
  60. package/dist/customer-accounts.d.ts.map +1 -1
  61. package/dist/customer-accounts.js +31 -0
  62. package/dist/customer-accounts.js.map +1 -1
  63. package/dist/document-templates.d.ts +27 -15
  64. package/dist/document-templates.d.ts.map +1 -1
  65. package/dist/document-values.d.ts +8 -0
  66. package/dist/document-values.d.ts.map +1 -1
  67. package/dist/document-values.js +24 -6
  68. package/dist/document-values.js.map +1 -1
  69. package/dist/email.d.ts +5 -0
  70. package/dist/email.d.ts.map +1 -1
  71. package/dist/errors.d.ts +105 -0
  72. package/dist/errors.d.ts.map +1 -1
  73. package/dist/errors.js +123 -0
  74. package/dist/errors.js.map +1 -1
  75. package/dist/index.d.ts +13 -1
  76. package/dist/index.d.ts.map +1 -1
  77. package/dist/index.js +27 -1
  78. package/dist/index.js.map +1 -1
  79. package/dist/inventory.d.ts +3 -3
  80. package/dist/invoices.d.ts +6 -2
  81. package/dist/invoices.d.ts.map +1 -1
  82. package/dist/invoices.js +3 -0
  83. package/dist/invoices.js.map +1 -1
  84. package/dist/megamenu.d.ts +674 -0
  85. package/dist/megamenu.d.ts.map +1 -1
  86. package/dist/megamenu.js +96 -3
  87. package/dist/megamenu.js.map +1 -1
  88. package/dist/mfa.d.ts +1 -0
  89. package/dist/mfa.d.ts.map +1 -1
  90. package/dist/mfa.js +8 -2
  91. package/dist/mfa.js.map +1 -1
  92. package/dist/modules.d.ts +8 -1
  93. package/dist/modules.d.ts.map +1 -1
  94. package/dist/modules.js +5 -0
  95. package/dist/modules.js.map +1 -1
  96. package/dist/newsletter.d.ts +3 -3
  97. package/dist/orders.d.ts +25 -0
  98. package/dist/orders.d.ts.map +1 -1
  99. package/dist/orders.js +14 -0
  100. package/dist/orders.js.map +1 -1
  101. package/dist/page-builder-props.d.ts +1401 -0
  102. package/dist/page-builder-props.d.ts.map +1 -0
  103. package/dist/page-builder-props.js +266 -0
  104. package/dist/page-builder-props.js.map +1 -0
  105. package/dist/page-builder-values.d.ts +95 -0
  106. package/dist/page-builder-values.d.ts.map +1 -0
  107. package/dist/page-builder-values.js +164 -0
  108. package/dist/page-builder-values.js.map +1 -0
  109. package/dist/pim-connector.d.ts +1 -1
  110. package/dist/platform-language.d.ts +9 -0
  111. package/dist/platform-language.d.ts.map +1 -1
  112. package/dist/platform-language.js +14 -0
  113. package/dist/platform-language.js.map +1 -1
  114. package/dist/price-books.d.ts +60 -60
  115. package/dist/price-lists.d.ts +44 -10
  116. package/dist/price-lists.d.ts.map +1 -1
  117. package/dist/price-lists.js +24 -1
  118. package/dist/price-lists.js.map +1 -1
  119. package/dist/product-feeds.d.ts +115 -55
  120. package/dist/product-feeds.d.ts.map +1 -1
  121. package/dist/product-feeds.js +18 -0
  122. package/dist/product-feeds.js.map +1 -1
  123. package/dist/product-scopes.d.ts +628 -0
  124. package/dist/product-scopes.d.ts.map +1 -0
  125. package/dist/product-scopes.js +365 -0
  126. package/dist/product-scopes.js.map +1 -0
  127. package/dist/product-summary-text.d.ts +23 -0
  128. package/dist/product-summary-text.d.ts.map +1 -0
  129. package/dist/product-summary-text.js +64 -0
  130. package/dist/product-summary-text.js.map +1 -0
  131. package/dist/product-url-keys.d.ts +204 -0
  132. package/dist/product-url-keys.d.ts.map +1 -0
  133. package/dist/product-url-keys.js +166 -0
  134. package/dist/product-url-keys.js.map +1 -0
  135. package/dist/projects.d.ts +2355 -0
  136. package/dist/projects.d.ts.map +1 -0
  137. package/dist/projects.js +837 -0
  138. package/dist/projects.js.map +1 -0
  139. package/dist/prompt-actions.d.ts +19 -1
  140. package/dist/prompt-actions.d.ts.map +1 -1
  141. package/dist/prompt-actions.js +31 -2
  142. package/dist/prompt-actions.js.map +1 -1
  143. package/dist/quick-order.d.ts +0 -1
  144. package/dist/quick-order.d.ts.map +1 -1
  145. package/dist/quick-order.js +1 -1
  146. package/dist/quick-order.js.map +1 -1
  147. package/dist/quote-requests.d.ts +36 -1
  148. package/dist/quote-requests.d.ts.map +1 -1
  149. package/dist/quote-requests.js +24 -0
  150. package/dist/quote-requests.js.map +1 -1
  151. package/dist/record-references.d.ts +252 -0
  152. package/dist/record-references.d.ts.map +1 -0
  153. package/dist/record-references.js +179 -0
  154. package/dist/record-references.js.map +1 -0
  155. package/dist/record-rich-text.d.ts +66 -0
  156. package/dist/record-rich-text.d.ts.map +1 -0
  157. package/dist/record-rich-text.js +303 -0
  158. package/dist/record-rich-text.js.map +1 -0
  159. package/dist/returns.d.ts +26 -0
  160. package/dist/returns.d.ts.map +1 -1
  161. package/dist/sales-channels.d.ts +51 -7
  162. package/dist/sales-channels.d.ts.map +1 -1
  163. package/dist/sales-channels.js +38 -4
  164. package/dist/sales-channels.js.map +1 -1
  165. package/dist/saved-list-views.d.ts +28 -0
  166. package/dist/saved-list-views.d.ts.map +1 -1
  167. package/dist/saved-list-views.js +14 -1
  168. package/dist/saved-list-views.js.map +1 -1
  169. package/dist/scoped-translations.d.ts +48 -0
  170. package/dist/scoped-translations.d.ts.map +1 -0
  171. package/dist/scoped-translations.js +78 -0
  172. package/dist/scoped-translations.js.map +1 -0
  173. package/dist/search.d.ts +15 -7
  174. package/dist/search.d.ts.map +1 -1
  175. package/dist/seo.d.ts +64 -5
  176. package/dist/seo.d.ts.map +1 -1
  177. package/dist/seo.js +31 -4
  178. package/dist/seo.js.map +1 -1
  179. package/dist/settings.d.ts +32 -3
  180. package/dist/settings.d.ts.map +1 -1
  181. package/dist/settings.js +37 -3
  182. package/dist/settings.js.map +1 -1
  183. package/dist/storefront-cache-tags.d.ts +29 -0
  184. package/dist/storefront-cache-tags.d.ts.map +1 -1
  185. package/dist/storefront-cache-tags.js +24 -0
  186. package/dist/storefront-cache-tags.js.map +1 -1
  187. package/dist/storefront-language-path.d.ts +77 -0
  188. package/dist/storefront-language-path.d.ts.map +1 -0
  189. package/dist/storefront-language-path.js +123 -0
  190. package/dist/storefront-language-path.js.map +1 -0
  191. package/dist/tasks.d.ts +2842 -0
  192. package/dist/tasks.d.ts.map +1 -0
  193. package/dist/tasks.js +901 -0
  194. package/dist/tasks.js.map +1 -0
  195. package/dist/transactional-emails.d.ts +7 -4
  196. package/dist/transactional-emails.d.ts.map +1 -1
  197. package/dist/transactional-emails.js +13 -0
  198. package/dist/transactional-emails.js.map +1 -1
  199. package/package.json +2 -2
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 { translationMapPatchSchema } from './scoped-translations.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
  /**
@@ -180,7 +183,13 @@ export const productPriceTierSchema = z.object({
180
183
  * when that is what `price` came from; `salePrice` is set only when a sale list
181
184
  * priced the product (it is then also `price`). Both are `null` when nothing
182
185
  * 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
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
184
193
  * `displayModeSchema`'s (`price-lists.ts`, which imports this file and checks
185
194
  * the two agree at compile time).
186
195
  */
@@ -202,6 +211,12 @@ export const productSummarySchema = z.object({
202
211
  type: productTypeSchema,
203
212
  name: z.string(),
204
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(),
205
220
  categorySlugs: z.array(z.string()),
206
221
  primaryAssetUrl: z.string().url().nullable(),
207
222
  price: moneySchema.nullable(),
@@ -288,6 +303,11 @@ export const productDetailSchema = productSummarySchema.extend({
288
303
  slug: z.string(),
289
304
  })),
290
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,
291
311
  structuredDataJsonLd: z.record(z.string(), z.unknown()),
292
312
  /**
293
313
  * Feature 002 — the AttributeSet wired to this Product. Optional so
@@ -318,6 +338,12 @@ export const productDetailSchema = productSummarySchema.extend({
318
338
  kind: z.string(),
319
339
  url: z.string(),
320
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(),
321
347
  }))
322
348
  .optional(),
323
349
  /**
@@ -536,10 +562,9 @@ const baseProductRequestObject = z.object({
536
562
  stockMode: stockModeSchema.optional(),
537
563
  visibility: productVisibilitySchema,
538
564
  // 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(),
565
+ // update endpoint. Feature 163 — a status write never touches
566
+ // `archivedAt` (FR-010); `draft` / `archived` are refused (FR-112).
567
+ status: productStatusSchema.optional(),
543
568
  allowedOrganizationIds: z.array(uuidSchema).optional(),
544
569
  assetIds: z.array(uuidSchema).optional(),
545
570
  initialStock: z.number().int().nonnegative().optional(),
@@ -607,7 +632,16 @@ export const createProductRequestSchema = baseProductRequestObject.refine((v) =>
607
632
  // frozen at snapshot time.
608
633
  export const updateProductRequestSchema = baseProductRequestObject
609
634
  .partial()
610
- .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
+ });
611
645
  // Admin batch-by-id lookup. The body carries the id set (deduped server-
612
646
  // side) plus optional pagination so callers can stream large lookups
613
647
  // across multiple requests. Hard cap of 500 ids per call mirrors the
@@ -621,11 +655,20 @@ export const batchByIdProductsRequestSchema = z.object({
621
655
  // Feature 033 — Resolve product IDs by list filters (collection selection)
622
656
  // ---------------------------------------------------------------------------
623
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']);
624
664
  export const resolveProductIdsRequestSchema = z.object({
625
665
  status: productStatusSchema.optional(),
626
666
  type: productTypeSchema.optional(),
627
667
  q: z.string().trim().min(1).optional(),
668
+ /** Legacy: `true` means `archived: 'include'`. `archived` wins when both are sent. */
628
669
  includeArchived: z.boolean().optional(),
670
+ /** Feature 163 (R30.4) — absent: `includeArchived`, else `include`, as before. */
671
+ archived: productArchivedModeSchema.optional(),
629
672
  });
630
673
  export const resolveProductIdsResponseSchema = z.object({
631
674
  data: z.object({
@@ -641,7 +684,7 @@ const bulkEditModeSchema = z.enum(['add', 'replace']);
641
684
  // product's current memberships); sales channels keep the two-mode enum.
642
685
  const bulkEditCategoryModeSchema = z.enum(['add', 'replace', 'remove']);
643
686
  const bulkUpdateFieldsObject = z.object({
644
- status: productStatusWriteSchema.optional(),
687
+ status: productStatusSchema.optional(),
645
688
  visibility: productVisibilitySchema.optional(),
646
689
  salesChannels: z
647
690
  .object({
@@ -661,6 +704,23 @@ const bulkUpdateFieldsObject = z.object({
661
704
  attributeValues: z.record(z.string(), z.unknown()).optional(),
662
705
  /** Feature 155 — set (or unset) the returnable flag on every selected product. */
663
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(),
664
724
  });
665
725
  export const bulkUpdateProductsRequestSchema = z.object({
666
726
  // The non-empty constraint is part of the schema (a Zod-level
@@ -676,7 +736,13 @@ export const bulkUpdateProductsRequestSchema = z.object({
676
736
  f.categories !== undefined ||
677
737
  f.attributeSetId !== undefined ||
678
738
  f.returnable !== undefined ||
679
- (f.attributeValues !== undefined && Object.keys(f.attributeValues).length > 0), { message: 'at least one field must be present' }),
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'] }),
680
746
  });
681
747
  export const bulkUpdateProductResultSchema = z.object({
682
748
  productId: z.string().uuid(),
@@ -688,6 +754,10 @@ export const bulkUpdateProductResultSchema = z.object({
688
754
  'permission_denied',
689
755
  'concurrent_modification',
690
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',
691
761
  ])
692
762
  .optional(),
693
763
  details: z
@@ -735,11 +805,23 @@ export const bulkOperationStatusSchema = z.enum([
735
805
  /**
736
806
  * One timestamped lifecycle event in a bulk operation's log trail, surfaced
737
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`.
738
814
  */
739
815
  export const bulkOperationLogEntrySchema = z.object({
740
816
  ts: z.string(),
741
817
  level: z.enum(['info', 'warn', 'error']),
742
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(),
743
825
  });
744
826
  /**
745
827
  * Known bulk-operation kinds. `type` on the record is an open string (the
@@ -1005,8 +1087,8 @@ export const adminAttributeResponseSchema = z.object({
1005
1087
  labelDefault: z.string(),
1006
1088
  /** API-form type (feature 002) — emitted alongside the legacy `valueType`. */
1007
1089
  type: apiAttributeTypeSchema,
1008
- /** Present only when `type === 'slider'`. */
1009
- numericKind: numericKindSchema.optional(),
1090
+ /** A kind only when `type === 'slider'`; `null` (or absent) otherwise. */
1091
+ numericKind: numericKindSchema.nullable().optional(),
1010
1092
  valueType: attributeValueTypeSchema,
1011
1093
  /** Legacy projection of the option values; `null` when not fetched or absent. */
1012
1094
  enumValues: z.array(z.string()).nullable(),
@@ -1024,6 +1106,13 @@ export const adminAttributeResponseSchema = z.object({
1024
1106
  quickSearchable: z.boolean(),
1025
1107
  /** Feature 061 (additive) — id of the backing product-host Custom Field definition. */
1026
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(),
1027
1116
  createdAt: isoDateTimeSchema,
1028
1117
  updatedAt: isoDateTimeSchema,
1029
1118
  });
@@ -1172,9 +1261,43 @@ export const productListSortSchema = z.enum([
1172
1261
  export function isPriceSort(sort) {
1173
1262
  return sort === 'price' || sort === '-price';
1174
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));
1175
1296
  export const productListQuerySchema = z
1176
1297
  .object({
1177
1298
  q: z.string().optional(),
1299
+ /** Issue #590 — restrict the listing to these products ({@link productListIdsSchema}). */
1300
+ ids: productListIdsSchema.optional(),
1178
1301
  limit: z.coerce.number().int().positive().max(200).default(50),
1179
1302
  cursor: z.string().optional(),
1180
1303
  sort: productListSortSchema.optional(),
@@ -1205,8 +1328,8 @@ export const productListQuerySchema = z
1205
1328
  *
1206
1329
  * It rides on the listing response because the storefront has to decide whether
1207
1330
  * 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
1331
+ * channel: `pricing.unauthenticated_display_mode = none` hides prices until
1332
+ * login, on one channel or on all of them. A
1210
1333
  * storefront that guessed would guess wrong on exactly the deployments that
1211
1334
  * care, and a control that offers an ordering the API refuses is a worse defect
1212
1335
  * than no control.
@@ -1288,12 +1411,24 @@ export const assignAttributesRequestSchema = z
1288
1411
  .strict();
1289
1412
  // --- Feature 002 — Gallery (US3) --------------------------------------------
1290
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;
1291
1418
  export const galleryItemSchema = z.object({
1292
1419
  id: uuidSchema,
1293
1420
  productId: uuidSchema,
1294
1421
  assetId: uuidSchema,
1295
1422
  position: z.number().int().nonnegative(),
1296
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(),
1297
1432
  createdAt: isoDateTimeSchema,
1298
1433
  updatedAt: isoDateTimeSchema,
1299
1434
  });
@@ -1308,6 +1443,46 @@ export const updateGalleryItemRequestSchema = z
1308
1443
  .object({
1309
1444
  position: z.number().int().nonnegative().optional(),
1310
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(),
1311
1486
  })
1312
1487
  .strict();
1313
1488
  export const reorderGalleryRequestSchema = z
@@ -1352,6 +1527,10 @@ export const updateAttachmentTypeRequestSchema = z
1352
1527
  position: z.number().int().nonnegative().optional(),
1353
1528
  })
1354
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;
1355
1534
  export const productAttachmentSchema = z.object({
1356
1535
  id: uuidSchema,
1357
1536
  productId: uuidSchema,
@@ -1360,6 +1539,15 @@ export const productAttachmentSchema = z.object({
1360
1539
  name: z.string().min(1).max(160),
1361
1540
  description: z.string().nullable(),
1362
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(),
1363
1551
  createdAt: isoDateTimeSchema,
1364
1552
  updatedAt: isoDateTimeSchema,
1365
1553
  });
@@ -1370,6 +1558,14 @@ export const createAttachmentRequestSchema = z
1370
1558
  name: z.string().min(1).max(160),
1371
1559
  description: z.string().nullable().optional(),
1372
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(),
1373
1569
  })
1374
1570
  .strict();
1375
1571
  export const updateAttachmentRequestSchema = z
@@ -1378,9 +1574,19 @@ export const updateAttachmentRequestSchema = z
1378
1574
  name: z.string().min(1).max(160).optional(),
1379
1575
  description: z.string().nullable().optional(),
1380
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(),
1381
1585
  })
1382
1586
  .strict();
1383
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;
1384
1590
  /**
1385
1591
  * A named ordering unit attached to a product (e.g. "Paleta" = 480 pieces).
1386
1592
  * Managed in the Inventory section of the admin product card; surfaced on the
@@ -1390,6 +1596,12 @@ export const packagingUnitSchema = z.object({
1390
1596
  id: uuidSchema,
1391
1597
  productId: uuidSchema,
1392
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(),
1393
1605
  baseQuantity: z.number().int().positive(),
1394
1606
  position: z.number().int().nonnegative(),
1395
1607
  isDefault: z.boolean(),
@@ -1409,6 +1621,11 @@ export const createPackagingUnitRequestSchema = z
1409
1621
  position: z.number().int().nonnegative().optional(),
1410
1622
  /** Feature 155 — minimum number of this unit per order of the product; `null` clears. */
1411
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(),
1412
1629
  })
1413
1630
  .strict();
1414
1631
  export const updatePackagingUnitRequestSchema = z
@@ -1419,6 +1636,11 @@ export const updatePackagingUnitRequestSchema = z
1419
1636
  position: z.number().int().nonnegative().optional(),
1420
1637
  /** Feature 155 — minimum number of this unit per order of the product; `null` clears. */
1421
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(),
1422
1644
  })
1423
1645
  .strict();
1424
1646
  export const reorderPackagingUnitsRequestSchema = z
@@ -1724,6 +1946,18 @@ export function isProductVisibleTo(product, audience) {
1724
1946
  return audience.authenticated;
1725
1947
  return true;
1726
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
+ }
1727
1961
  /**
1728
1962
  * Scope flags for the **system** product attributes — the ones that are not
1729
1963
  * rows in `product_attributes` and therefore carry no DB-stored scope flags.
@@ -1818,8 +2052,10 @@ export const ProductUpdatedEventV1Schema = z
1818
2052
  })
1819
2053
  .strict();
1820
2054
  /**
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.
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.
1823
2059
  */
1824
2060
  export const ProductArchivedEventV1Schema = z
1825
2061
  .object({