@endora-commerce/contracts 0.109.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 (241) 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-contributions.d.ts +62 -7
  8. package/dist/admin-contributions.d.ts.map +1 -1
  9. package/dist/admin-contributions.js +27 -8
  10. package/dist/admin-contributions.js.map +1 -1
  11. package/dist/admin-roles.d.ts +8 -2
  12. package/dist/admin-roles.d.ts.map +1 -1
  13. package/dist/admin-roles.js.map +1 -1
  14. package/dist/admin-users.d.ts +9 -0
  15. package/dist/admin-users.d.ts.map +1 -1
  16. package/dist/admin.d.ts +77 -4
  17. package/dist/admin.d.ts.map +1 -1
  18. package/dist/admin.js +79 -3
  19. package/dist/admin.js.map +1 -1
  20. package/dist/assets-library.d.ts +26 -0
  21. package/dist/assets-library.d.ts.map +1 -1
  22. package/dist/assets-library.js +6 -3
  23. package/dist/assets-library.js.map +1 -1
  24. package/dist/audit-logs.d.ts +12 -0
  25. package/dist/audit-logs.d.ts.map +1 -1
  26. package/dist/audit-logs.js +12 -0
  27. package/dist/audit-logs.js.map +1 -1
  28. package/dist/blog.d.ts +382 -22
  29. package/dist/blog.d.ts.map +1 -1
  30. package/dist/blog.js +199 -17
  31. package/dist/blog.js.map +1 -1
  32. package/dist/carts.d.ts +394 -36
  33. package/dist/carts.d.ts.map +1 -1
  34. package/dist/carts.js +131 -8
  35. package/dist/carts.js.map +1 -1
  36. package/dist/catalog.d.ts +351 -219
  37. package/dist/catalog.d.ts.map +1 -1
  38. package/dist/catalog.js +209 -157
  39. package/dist/catalog.js.map +1 -1
  40. package/dist/cms-brand.d.ts +14 -14
  41. package/dist/cms.d.ts +41 -16
  42. package/dist/cms.d.ts.map +1 -1
  43. package/dist/cms.js.map +1 -1
  44. package/dist/common.d.ts +23 -6
  45. package/dist/common.d.ts.map +1 -1
  46. package/dist/common.js +25 -2
  47. package/dist/common.js.map +1 -1
  48. package/dist/comparisons.d.ts +28 -21
  49. package/dist/comparisons.d.ts.map +1 -1
  50. package/dist/comparisons.js +2 -1
  51. package/dist/comparisons.js.map +1 -1
  52. package/dist/credit-limits.d.ts +1 -0
  53. package/dist/credit-limits.d.ts.map +1 -1
  54. package/dist/credit-limits.js +14 -0
  55. package/dist/credit-limits.js.map +1 -1
  56. package/dist/crm.d.ts +79 -49
  57. package/dist/crm.d.ts.map +1 -1
  58. package/dist/crm.js +6 -0
  59. package/dist/crm.js.map +1 -1
  60. package/dist/custom-fields.d.ts +27 -13
  61. package/dist/custom-fields.d.ts.map +1 -1
  62. package/dist/custom-fields.js +15 -1
  63. package/dist/custom-fields.js.map +1 -1
  64. package/dist/customer-accounts.d.ts +186 -22
  65. package/dist/customer-accounts.d.ts.map +1 -1
  66. package/dist/customer-accounts.js +39 -0
  67. package/dist/customer-accounts.js.map +1 -1
  68. package/dist/customers.d.ts +40 -73
  69. package/dist/customers.d.ts.map +1 -1
  70. package/dist/customers.js +45 -10
  71. package/dist/customers.js.map +1 -1
  72. package/dist/document-templates.d.ts +12 -12
  73. package/dist/errors.d.ts +119 -1
  74. package/dist/errors.d.ts.map +1 -1
  75. package/dist/errors.js +146 -1
  76. package/dist/errors.js.map +1 -1
  77. package/dist/forms-logic.d.ts +79 -0
  78. package/dist/forms-logic.d.ts.map +1 -0
  79. package/dist/forms-logic.fixtures.d.ts +52 -0
  80. package/dist/forms-logic.fixtures.d.ts.map +1 -0
  81. package/dist/forms-logic.fixtures.js +610 -0
  82. package/dist/forms-logic.fixtures.js.map +1 -0
  83. package/dist/forms-logic.js +699 -0
  84. package/dist/forms-logic.js.map +1 -0
  85. package/dist/forms.d.ts +9833 -0
  86. package/dist/forms.d.ts.map +1 -0
  87. package/dist/forms.js +827 -0
  88. package/dist/forms.js.map +1 -0
  89. package/dist/import-export.d.ts +180 -0
  90. package/dist/import-export.d.ts.map +1 -1
  91. package/dist/import-export.js +60 -0
  92. package/dist/import-export.js.map +1 -1
  93. package/dist/index.d.ts +10 -1
  94. package/dist/index.d.ts.map +1 -1
  95. package/dist/index.js +18 -0
  96. package/dist/index.js.map +1 -1
  97. package/dist/inventory.d.ts +9 -9
  98. package/dist/invoice-ledger.d.ts +7 -7
  99. package/dist/invoices.d.ts.map +1 -1
  100. package/dist/invoices.js +4 -0
  101. package/dist/invoices.js.map +1 -1
  102. package/dist/mfa.d.ts +124 -4
  103. package/dist/mfa.d.ts.map +1 -1
  104. package/dist/mfa.js +46 -0
  105. package/dist/mfa.js.map +1 -1
  106. package/dist/modules.d.ts +36 -4
  107. package/dist/modules.d.ts.map +1 -1
  108. package/dist/modules.js +68 -0
  109. package/dist/modules.js.map +1 -1
  110. package/dist/money-decimal.d.ts +54 -0
  111. package/dist/money-decimal.d.ts.map +1 -1
  112. package/dist/money-decimal.js +95 -0
  113. package/dist/money-decimal.js.map +1 -1
  114. package/dist/newsletter.d.ts +4 -4
  115. package/dist/orders.d.ts +105 -12
  116. package/dist/orders.d.ts.map +1 -1
  117. package/dist/orders.js +60 -4
  118. package/dist/orders.js.map +1 -1
  119. package/dist/organization-registry-lookup.d.ts +362 -0
  120. package/dist/organization-registry-lookup.d.ts.map +1 -0
  121. package/dist/organization-registry-lookup.js +196 -0
  122. package/dist/organization-registry-lookup.js.map +1 -0
  123. package/dist/organization-roles.d.ts +340 -0
  124. package/dist/organization-roles.d.ts.map +1 -0
  125. package/dist/organization-roles.js +211 -0
  126. package/dist/organization-roles.js.map +1 -0
  127. package/dist/organizations.d.ts +123 -89
  128. package/dist/organizations.d.ts.map +1 -1
  129. package/dist/organizations.js +68 -24
  130. package/dist/organizations.js.map +1 -1
  131. package/dist/page-builder-props.d.ts +56 -56
  132. package/dist/pim-connector.d.ts +7 -3
  133. package/dist/pim-connector.d.ts.map +1 -1
  134. package/dist/pim-connector.js +6 -2
  135. package/dist/pim-connector.js.map +1 -1
  136. package/dist/pim-field-path.d.ts +5 -1
  137. package/dist/pim-field-path.d.ts.map +1 -1
  138. package/dist/pim-field-path.js +37 -81
  139. package/dist/pim-field-path.js.map +1 -1
  140. package/dist/pim-locale-mapping.d.ts +131 -0
  141. package/dist/pim-locale-mapping.d.ts.map +1 -0
  142. package/dist/pim-locale-mapping.js +193 -0
  143. package/dist/pim-locale-mapping.js.map +1 -0
  144. package/dist/price-books.d.ts +67 -63
  145. package/dist/price-books.d.ts.map +1 -1
  146. package/dist/price-books.js +6 -2
  147. package/dist/price-books.js.map +1 -1
  148. package/dist/price-lists.d.ts +8 -8
  149. package/dist/product-feeds.d.ts +94 -94
  150. package/dist/product-feeds.d.ts.map +1 -1
  151. package/dist/product-feeds.js +5 -0
  152. package/dist/product-feeds.js.map +1 -1
  153. package/dist/product-scope-model.d.ts +161 -0
  154. package/dist/product-scope-model.d.ts.map +1 -0
  155. package/dist/product-scope-model.js +161 -0
  156. package/dist/product-scope-model.js.map +1 -0
  157. package/dist/product-scope-overrides.d.ts +0 -103
  158. package/dist/product-scope-overrides.d.ts.map +1 -1
  159. package/dist/product-scope-overrides.js +0 -54
  160. package/dist/product-scope-overrides.js.map +1 -1
  161. package/dist/product-scoped-values.d.ts +2610 -0
  162. package/dist/product-scoped-values.d.ts.map +1 -0
  163. package/dist/product-scoped-values.js +425 -0
  164. package/dist/product-scoped-values.js.map +1 -0
  165. package/dist/product-scopes.d.ts +182 -64
  166. package/dist/product-scopes.d.ts.map +1 -1
  167. package/dist/product-scopes.js +89 -18
  168. package/dist/product-scopes.js.map +1 -1
  169. package/dist/product-tax-rates.d.ts +38 -0
  170. package/dist/product-tax-rates.d.ts.map +1 -0
  171. package/dist/product-tax-rates.js +45 -0
  172. package/dist/product-tax-rates.js.map +1 -0
  173. package/dist/product-url-keys.d.ts +51 -45
  174. package/dist/product-url-keys.d.ts.map +1 -1
  175. package/dist/product-url-keys.js +73 -39
  176. package/dist/product-url-keys.js.map +1 -1
  177. package/dist/product-value-resolver.d.ts +37 -60
  178. package/dist/product-value-resolver.d.ts.map +1 -1
  179. package/dist/product-value-resolver.js +36 -96
  180. package/dist/product-value-resolver.js.map +1 -1
  181. package/dist/projects.d.ts +15 -0
  182. package/dist/projects.d.ts.map +1 -1
  183. package/dist/projects.js +6 -0
  184. package/dist/projects.js.map +1 -1
  185. package/dist/promotions.d.ts +10 -10
  186. package/dist/pwa.d.ts +2 -2
  187. package/dist/quick-order.d.ts +150 -6
  188. package/dist/quick-order.d.ts.map +1 -1
  189. package/dist/quick-order.js +75 -1
  190. package/dist/quick-order.js.map +1 -1
  191. package/dist/quote-requests.d.ts +63 -12
  192. package/dist/quote-requests.d.ts.map +1 -1
  193. package/dist/quote-requests.js +42 -1
  194. package/dist/quote-requests.js.map +1 -1
  195. package/dist/record-references.d.ts.map +1 -1
  196. package/dist/record-references.js +2 -3
  197. package/dist/record-references.js.map +1 -1
  198. package/dist/record-rich-text.d.ts.map +1 -1
  199. package/dist/record-rich-text.js +2 -1
  200. package/dist/record-rich-text.js.map +1 -1
  201. package/dist/returns.d.ts +208 -52
  202. package/dist/returns.d.ts.map +1 -1
  203. package/dist/returns.js +139 -26
  204. package/dist/returns.js.map +1 -1
  205. package/dist/saved-list-views.d.ts +28 -0
  206. package/dist/saved-list-views.d.ts.map +1 -1
  207. package/dist/saved-list-views.js +14 -1
  208. package/dist/saved-list-views.js.map +1 -1
  209. package/dist/scoped-write-encoding.d.ts +100 -0
  210. package/dist/scoped-write-encoding.d.ts.map +1 -0
  211. package/dist/scoped-write-encoding.js +135 -0
  212. package/dist/scoped-write-encoding.js.map +1 -0
  213. package/dist/search.d.ts +18 -16
  214. package/dist/search.d.ts.map +1 -1
  215. package/dist/seo.d.ts +81 -28
  216. package/dist/seo.d.ts.map +1 -1
  217. package/dist/seo.js +8 -1
  218. package/dist/seo.js.map +1 -1
  219. package/dist/settings.d.ts +129 -0
  220. package/dist/settings.d.ts.map +1 -1
  221. package/dist/settings.js +36 -0
  222. package/dist/settings.js.map +1 -1
  223. package/dist/shopping-lists.d.ts +24 -3
  224. package/dist/shopping-lists.d.ts.map +1 -1
  225. package/dist/shopping-lists.js +20 -0
  226. package/dist/shopping-lists.js.map +1 -1
  227. package/dist/storefront-cache-tags.d.ts +12 -0
  228. package/dist/storefront-cache-tags.d.ts.map +1 -1
  229. package/dist/storefront-cache-tags.js +12 -0
  230. package/dist/storefront-cache-tags.js.map +1 -1
  231. package/dist/storefront-value-overrides.d.ts +18 -56
  232. package/dist/storefront-value-overrides.d.ts.map +1 -1
  233. package/dist/storefront-value-overrides.js +11 -86
  234. package/dist/storefront-value-overrides.js.map +1 -1
  235. package/dist/tasks.d.ts +6 -6
  236. package/dist/transactional-emails.d.ts +9 -9
  237. package/package.json +2 -2
  238. package/dist/scoped-translations.d.ts +0 -48
  239. package/dist/scoped-translations.d.ts.map +0 -1
  240. package/dist/scoped-translations.js +0 -78
  241. package/dist/scoped-translations.js.map +0 -1
package/dist/catalog.js CHANGED
@@ -2,7 +2,7 @@ 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
4
  import { productPagePathsSchema } from './product-url-keys.js';
5
- import { translationMapPatchSchema } from './scoped-translations.js';
5
+ import { scopeVersionTokenSchema } from './scoped-write-encoding.js';
6
6
  /**
7
7
  * Catalog module contracts — Source of truth per Principle V.
8
8
  * See specs/001-b2b-platform-foundation/contracts/catalog.contract.md.
@@ -57,6 +57,8 @@ export const attributeValueTypeSchema = z.enum([
57
57
  'multiselect',
58
58
  'price',
59
59
  'select',
60
+ // Feature 172 (research R-4) — a Page Builder document per language.
61
+ 'page_builder',
60
62
  ]);
61
63
  /**
62
64
  * API-facing attribute type form for feature 002 contracts. Maps onto
@@ -69,6 +71,8 @@ export const apiAttributeTypeSchema = z.enum([
69
71
  'multiselect',
70
72
  'price',
71
73
  'slider',
74
+ // Feature 172 (research R-4) — the same name in all three vocabularies.
75
+ 'page_builder',
72
76
  ]);
73
77
  /**
74
78
  * The API-form type of a stored attribute, derived from the pair the catalogue
@@ -99,6 +103,8 @@ export function apiAttributeTypeOf(valueType, displayAsSlider) {
99
103
  case 'boolean':
100
104
  case 'date':
101
105
  return 'input';
106
+ case 'page_builder':
107
+ return 'page_builder';
102
108
  }
103
109
  }
104
110
  export const assetKindSchema = z.enum(['image', 'video', 'pdf', 'certificate', 'other']);
@@ -256,6 +262,21 @@ export const productSummarySchema = z.object({
256
262
  * producer written before it still compiles).
257
263
  */
258
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(),
259
280
  });
260
281
  // --- Product variant --------------------------------------------------------
261
282
  export const productVariantSchema = z.object({
@@ -279,6 +300,28 @@ export const seoMetaSchema = z.object({
279
300
  * The exported `productLinkSummarySchema` below is the canonical name —
280
301
  * this `*Inline` alias exists only to avoid a circular import.
281
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
+ });
282
325
  const productLinkSummarySchemaInline = z.object({
283
326
  id: uuidSchema,
284
327
  kind: z.enum(['related', 'up_sell', 'cross_sell']),
@@ -339,9 +382,11 @@ export const productDetailSchema = productSummarySchema.extend({
339
382
  url: z.string(),
340
383
  }),
341
384
  /**
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.
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.
345
390
  */
346
391
  altText: z.string().nullable().optional(),
347
392
  }))
@@ -452,6 +497,14 @@ export const productDetailSchema = productSummarySchema.extend({
452
497
  valueRendered: z.string(),
453
498
  }))
454
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(),
455
508
  /**
456
509
  * Feature 043 — named packaging units (e.g. "Paleta" = 480 pieces) the
457
510
  * buyer can order by. Present only for eligible product types
@@ -549,14 +602,23 @@ export const filterDefinitionSchema = z.object({
549
602
  filterPosition: z.number().int().min(0).default(0),
550
603
  });
551
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;
552
609
  // Base shape (no cross-field refine) so updateProductRequestSchema can
553
610
  // `.partial()` it. The cross-field rule for virtual download fields is
554
611
  // applied as a separate refine on the create variant below.
555
612
  const baseProductRequestObject = z.object({
556
613
  sku: z.string().min(1).max(255),
557
614
  type: productTypeSchema,
558
- name: multilingualStringSchema,
559
- 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(),
560
622
  categoryIds: z.array(uuidSchema),
561
623
  attributeValues: z.record(z.string(), z.unknown()),
562
624
  stockMode: stockModeSchema.optional(),
@@ -641,6 +703,11 @@ export const updateProductRequestSchema = baseProductRequestObject
641
703
  */
642
704
  publishFrom: isoDateTimeSchema.nullable().optional(),
643
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(),
644
711
  });
645
712
  // Admin batch-by-id lookup. The body carries the id set (deduped server-
646
713
  // side) plus optional pagination so callers can stream large lookups
@@ -916,12 +983,23 @@ export const PRICE_FIELDS_REFUSED_ON_VARIANTS = ['priceOverride', 'defaultPrice'
916
983
  * underlying DB `valueType` is `number` or `price`.
917
984
  */
918
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
+ }
919
1001
  const baseCreateAttributeObject = z.object({
920
- key: z
921
- .string()
922
- .min(1)
923
- .max(64)
924
- .regex(/^[a-z][a-z0-9_]*$/, 'must be snake_case, start with a letter'),
1002
+ key: attributeKeyShapeSchema,
925
1003
  label: multilingualStringSchema,
926
1004
  /**
927
1005
  * Feature 002 — preferred API form. When `type` is present it wins over
@@ -976,20 +1054,11 @@ const baseCreateAttributeObject = z.object({
976
1054
  /** Feature 012 — gates inclusion in the storefront PDP "Parametry produktu" tab. */
977
1055
  isVisibleOnProductPage: z.boolean().optional(),
978
1056
  /**
979
- * Feature 023 — when `true` the attribute may carry per-Sales-Channel
980
- * overrides. Default `false` (global-only). Independent of
981
- * `languageScoped`; the two flags compose into one of four effective
982
- * 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.
983
1060
  */
984
- channelScoped: z.boolean().optional(),
985
- /**
986
- * Feature 023 — when `true` the attribute's value is keyed by
987
- * language at every slot. For user-defined attributes the baseline
988
- * is stored as `Record<lang, value>` in `products.attribute_values`;
989
- * for the system Name / Description attributes this flag is pinned
990
- * `true` by SYSTEM_ATTRIBUTE_SCOPES.
991
- */
992
- languageScoped: z.boolean().optional(),
1061
+ scopable: z.boolean().optional(),
993
1062
  /**
994
1063
  * Feature 022 (products bulk edit) — makes the attribute available in
995
1064
  * the Products Bulk Edit dialog's attribute field list. Default false;
@@ -1058,10 +1127,8 @@ export const updateAttributeRequestSchema = z
1058
1127
  filterPosition: z.number().int().min(0).max(10000).optional(),
1059
1128
  /** Feature 012 — gates inclusion in the storefront PDP "Parametry produktu" tab. */
1060
1129
  isVisibleOnProductPage: z.boolean().optional(),
1061
- /** Feature 023 — see `baseCreateAttributeObject.channelScoped`. */
1062
- channelScoped: z.boolean().optional(),
1063
- /** Feature 023 — see `baseCreateAttributeObject.languageScoped`. */
1064
- languageScoped: z.boolean().optional(),
1130
+ /** Feature 174 — see `baseCreateAttributeObject.scopable`. */
1131
+ scopable: z.boolean().optional(),
1065
1132
  /** Feature 022 (products bulk edit) — toggles bulk-editability. */
1066
1133
  massEditable: z.boolean().optional(),
1067
1134
  /** Feature 039 — values participate in Quick Order search. */
@@ -1107,12 +1174,12 @@ export const adminAttributeResponseSchema = z.object({
1107
1174
  /** Feature 061 (additive) — id of the backing product-host Custom Field definition. */
1108
1175
  customFieldDefinitionId: uuidSchema,
1109
1176
  /**
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`
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`
1112
1179
  * always emits both.
1113
1180
  */
1114
- channelScoped: z.boolean().optional(),
1115
- languageScoped: z.boolean().optional(),
1181
+ scopable: z.boolean().optional(),
1182
+ scopeLevels: z.array(z.enum(['G', 'C', 'CL'])).optional(),
1116
1183
  createdAt: isoDateTimeSchema,
1117
1184
  updatedAt: isoDateTimeSchema,
1118
1185
  });
@@ -1158,15 +1225,22 @@ export const updateCategoryRequestSchema = z
1158
1225
  .strict();
1159
1226
  // --- Category page content ---------------------------------------------------
1160
1227
  /**
1161
- * The ceiling on one category's stored content envelope, in UTF-8 bytes of its
1162
- * 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.
1163
1231
  *
1164
1232
  * One mebibyte, because that is what a CMS page is held to today: the CMS
1165
1233
  * declares no limit of its own and is bounded by the HTTP layer's default body
1166
1234
  * limit, which is this number. Stated here so the bound also holds for a
1167
1235
  * caller that does not arrive over HTTP.
1168
1236
  */
1169
- 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;
1170
1244
  /**
1171
1245
  * The UTF-8 length of a string, counted rather than encoded: this package
1172
1246
  * compiles for the admin, the storefront and the backend alike and declares
@@ -1195,8 +1269,6 @@ function utf8ByteLength(text) {
1195
1269
  }
1196
1270
  return bytes;
1197
1271
  }
1198
- /** One language's Page Builder document. Opaque beyond being a JSON object. */
1199
- const pageBuilderTreeSchema = z.record(z.string(), z.unknown());
1200
1272
  /**
1201
1273
  * The content an operator authors for a category's storefront page: one Page
1202
1274
  * Builder document per language, keyed like the category's `name`.
@@ -1239,6 +1311,63 @@ export const categoryPageContentSchema = z.object({
1239
1311
  language: z.string().nullable(),
1240
1312
  content: pageBuilderTreeSchema.nullable(),
1241
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
+ });
1242
1371
  // --- Storefront list/query ---------------------------------------------------
1243
1372
  /**
1244
1373
  * The orderings the storefront listing accepts.
@@ -1374,12 +1503,9 @@ export const attributeSetAssignedAttributeSchema = z.object({
1374
1503
  label: multilingualStringSchema,
1375
1504
  valueType: attributeValueTypeSchema,
1376
1505
  position: z.number().int().nonnegative(),
1377
- /**
1378
- * Feature 023 — the attribute's value is keyed by language, so the product
1379
- * editor renders it (and anything scoped to it, such as feature 068's
1380
- * overwrite protection) per language rather than once for the attribute.
1381
- */
1382
- 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'])),
1383
1509
  });
1384
1510
  export const attributeSetDetailSchema = attributeSetSchema.extend({
1385
1511
  attributes: z.array(attributeSetAssignedAttributeSchema),
@@ -1411,10 +1537,8 @@ export const assignAttributesRequestSchema = z
1411
1537
  .strict();
1412
1538
  // --- Feature 002 — Gallery (US3) --------------------------------------------
1413
1539
  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. */
1540
+ /** Feature 163 / 174 — the longest alt text of one image at one scope. */
1415
1541
  export const GALLERY_ALT_TEXT_MAX = 255;
1416
- /** Feature 163 — the most channels one write names. */
1417
- export const SCOPED_CHANNELS_MAX = 256;
1418
1542
  export const galleryItemSchema = z.object({
1419
1543
  id: uuidSchema,
1420
1544
  productId: uuidSchema,
@@ -1422,13 +1546,13 @@ export const galleryItemSchema = z.object({
1422
1546
  position: z.number().int().nonnegative(),
1423
1547
  labels: z.array(galleryLabelSchema),
1424
1548
  /**
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.
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.
1428
1553
  */
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(),
1554
+ altText: z.string().nullable().optional(),
1555
+ hidden: z.boolean().optional(),
1432
1556
  createdAt: isoDateTimeSchema,
1433
1557
  updatedAt: isoDateTimeSchema,
1434
1558
  });
@@ -1439,52 +1563,21 @@ export const createGalleryItemRequestSchema = z
1439
1563
  labels: z.array(galleryLabelSchema).optional(),
1440
1564
  })
1441
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
+ */
1442
1571
  export const updateGalleryItemRequestSchema = z
1443
1572
  .object({
1444
1573
  position: z.number().int().nonnegative().optional(),
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
1574
  })
1454
1575
  .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.
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).
1475
1580
  */
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(),
1486
- })
1487
- .strict();
1488
1581
  export const reorderGalleryRequestSchema = z
1489
1582
  .object({
1490
1583
  orderedGalleryItemIds: z.array(uuidSchema).min(1),
@@ -1527,9 +1620,9 @@ export const updateAttachmentTypeRequestSchema = z
1527
1620
  position: z.number().int().nonnegative().optional(),
1528
1621
  })
1529
1622
  .strict();
1530
- /** Feature 163 (FR-078) — the longest attachment description one language may carry. */
1623
+ /** Feature 163 / 174 — the longest attachment description at a Channel or Channel × language scope. */
1531
1624
  export const ATTACHMENT_DESCRIPTION_TRANSLATION_MAX = 4000;
1532
- /** Feature 163 (FR-078) — an attachment name per language, as long as the global one. */
1625
+ /** Feature 163 / 174 — an attachment name at any scope, as long as the Global one. */
1533
1626
  export const ATTACHMENT_NAME_MAX = 160;
1534
1627
  export const productAttachmentSchema = z.object({
1535
1628
  id: uuidSchema,
@@ -1540,14 +1633,11 @@ export const productAttachmentSchema = z.object({
1540
1633
  description: z.string().nullable(),
1541
1634
  position: z.number().int().nonnegative(),
1542
1635
  /**
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.
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.
1546
1639
  */
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(),
1640
+ hidden: z.boolean().optional(),
1551
1641
  createdAt: isoDateTimeSchema,
1552
1642
  updatedAt: isoDateTimeSchema,
1553
1643
  });
@@ -1558,34 +1648,21 @@ export const createAttachmentRequestSchema = z
1558
1648
  name: z.string().min(1).max(160),
1559
1649
  description: z.string().nullable().optional(),
1560
1650
  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(),
1569
1651
  })
1570
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
+ */
1571
1658
  export const updateAttachmentRequestSchema = z
1572
1659
  .object({
1573
1660
  attachmentTypeId: uuidSchema.optional(),
1574
- name: z.string().min(1).max(160).optional(),
1575
- description: z.string().nullable().optional(),
1576
1661
  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(),
1585
1662
  })
1586
1663
  .strict();
1587
1664
  // --- Packaging Units (Feature 043) ------------------------------------------
1588
- /** The longest packaging-unit name, global or (feature 163, FR-079) per language. */
1665
+ /** The longest packaging-unit name at any scope. */
1589
1666
  export const PACKAGING_UNIT_NAME_MAX = 160;
1590
1667
  /**
1591
1668
  * A named ordering unit attached to a product (e.g. "Paleta" = 480 pieces).
@@ -1595,13 +1672,8 @@ export const PACKAGING_UNIT_NAME_MAX = 160;
1595
1672
  export const packagingUnitSchema = z.object({
1596
1673
  id: uuidSchema,
1597
1674
  productId: uuidSchema,
1675
+ /** The Global name; Channel and Channel × language names go through `…/scoped-values` (feature 174). */
1598
1676
  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(),
1605
1677
  baseQuantity: z.number().int().positive(),
1606
1678
  position: z.number().int().nonnegative(),
1607
1679
  isDefault: z.boolean(),
@@ -1621,26 +1693,20 @@ export const createPackagingUnitRequestSchema = z
1621
1693
  position: z.number().int().nonnegative().optional(),
1622
1694
  /** Feature 155 — minimum number of this unit per order of the product; `null` clears. */
1623
1695
  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(),
1629
1696
  })
1630
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
+ */
1631
1703
  export const updatePackagingUnitRequestSchema = z
1632
1704
  .object({
1633
- name: z.string().trim().min(1).max(160).optional(),
1634
1705
  baseQuantity: z.number().int().positive().optional(),
1635
1706
  isDefault: z.boolean().optional(),
1636
1707
  position: z.number().int().nonnegative().optional(),
1637
1708
  /** Feature 155 — minimum number of this unit per order of the product; `null` clears. */
1638
1709
  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(),
1644
1710
  })
1645
1711
  .strict();
1646
1712
  export const reorderPackagingUnitsRequestSchema = z
@@ -1946,17 +2012,9 @@ export function isProductVisibleTo(product, audience) {
1946
2012
  return audience.authenticated;
1947
2013
  return true;
1948
2014
  }
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 };
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}`;
1960
2018
  }
1961
2019
  /**
1962
2020
  * Scope flags for the **system** product attributes — the ones that are not
@@ -1973,8 +2031,8 @@ export function parseScopedStatusColumn(column) {
1973
2031
  * — enforced at write time by the override-service validator.
1974
2032
  */
1975
2033
  export const SYSTEM_ATTRIBUTE_SCOPES = {
1976
- name: { channelScoped: true, languageScoped: true },
1977
- description: { channelScoped: true, languageScoped: true },
2034
+ name: { scopable: true },
2035
+ description: { scopable: true },
1978
2036
  };
1979
2037
  export function isSystemAttributeKey(key) {
1980
2038
  return Object.prototype.hasOwnProperty.call(SYSTEM_ATTRIBUTE_SCOPES, key);
@@ -1992,13 +2050,7 @@ export function getAttributeScope(attributeKey, productAttributeRow) {
1992
2050
  // index signature still widens under `noUncheckedIndexedAccess`.
1993
2051
  return SYSTEM_ATTRIBUTE_SCOPES[attributeKey];
1994
2052
  }
1995
- if (productAttributeRow) {
1996
- return {
1997
- channelScoped: productAttributeRow.channelScoped,
1998
- languageScoped: productAttributeRow.languageScoped,
1999
- };
2000
- }
2001
- return { channelScoped: false, languageScoped: false };
2053
+ return { scopable: productAttributeRow?.scopable ?? false };
2002
2054
  }
2003
2055
  // ---------------------------------------------------------------------------
2004
2056
  // Events offered to outbound webhooks