@endora-commerce/contracts 0.109.0 → 0.111.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 (385) hide show
  1. package/dist/accept-language.d.ts +31 -0
  2. package/dist/accept-language.js +64 -0
  3. package/dist/actor.d.ts +16 -0
  4. package/dist/addresses.d.ts +35 -0
  5. package/dist/addresses.js +8 -1
  6. package/dist/admin-actions.d.ts +2 -0
  7. package/dist/admin-actions.js +18 -0
  8. package/dist/admin-contributions.d.ts +99 -12
  9. package/dist/admin-contributions.js +36 -10
  10. package/dist/admin-roles.d.ts +17 -2
  11. package/dist/admin-users.d.ts +9 -0
  12. package/dist/admin.d.ts +114 -4
  13. package/dist/admin.js +98 -3
  14. package/dist/api-keys.d.ts +22 -0
  15. package/dist/api-keys.js +4 -0
  16. package/dist/assets-library.d.ts +45 -0
  17. package/dist/assets-library.js +20 -3
  18. package/dist/audit-logs.d.ts +12 -0
  19. package/dist/audit-logs.js +12 -0
  20. package/dist/auth.d.ts +9 -0
  21. package/dist/auth.js +9 -0
  22. package/dist/blog.d.ts +382 -22
  23. package/dist/blog.js +199 -17
  24. package/dist/carts.d.ts +423 -36
  25. package/dist/carts.js +150 -12
  26. package/dist/catalog.d.ts +379 -208
  27. package/dist/catalog.js +241 -163
  28. package/dist/cms-brand.d.ts +14 -14
  29. package/dist/cms.d.ts +71 -16
  30. package/dist/cms.js +15 -0
  31. package/dist/command-hooks.d.ts +301 -0
  32. package/dist/command-hooks.js +248 -0
  33. package/dist/common.d.ts +23 -6
  34. package/dist/common.js +25 -2
  35. package/dist/comparisons.d.ts +21 -14
  36. package/dist/comparisons.js +2 -1
  37. package/dist/credit-limits.d.ts +22 -0
  38. package/dist/credit-limits.js +35 -0
  39. package/dist/crm.d.ts +134 -78
  40. package/dist/crm.js +21 -5
  41. package/dist/custom-fields.d.ts +417 -49
  42. package/dist/custom-fields.js +142 -1
  43. package/dist/customer-accounts.d.ts +324 -22
  44. package/dist/customer-accounts.js +43 -0
  45. package/dist/customer-notifications.d.ts +143 -0
  46. package/dist/customer-notifications.js +41 -0
  47. package/dist/customers.d.ts +92 -73
  48. package/dist/customers.js +98 -10
  49. package/dist/dictionary.d.ts +53 -0
  50. package/dist/dictionary.js +25 -0
  51. package/dist/document-templates.d.ts +12 -12
  52. package/dist/email.d.ts +34 -0
  53. package/dist/email.js +6 -0
  54. package/dist/errors.d.ts +431 -3
  55. package/dist/errors.js +523 -3
  56. package/dist/forms-logic.d.ts +79 -0
  57. package/dist/forms-logic.fixtures.d.ts +52 -0
  58. package/dist/forms-logic.fixtures.js +610 -0
  59. package/dist/forms-logic.js +699 -0
  60. package/dist/forms.d.ts +9833 -0
  61. package/dist/forms.js +827 -0
  62. package/dist/i18n.d.ts +34 -0
  63. package/dist/i18n.js +15 -0
  64. package/dist/import-export.d.ts +180 -0
  65. package/dist/import-export.js +60 -0
  66. package/dist/index.d.ts +16 -1
  67. package/dist/index.js +30 -1
  68. package/dist/inventory.d.ts +9 -9
  69. package/dist/invoice-ledger.d.ts +13 -13
  70. package/dist/invoices.d.ts +126 -0
  71. package/dist/invoices.js +53 -0
  72. package/dist/line-bounds.d.ts +53 -0
  73. package/dist/line-bounds.js +65 -0
  74. package/dist/megamenu.d.ts +27 -27
  75. package/dist/mfa.d.ts +210 -4
  76. package/dist/mfa.js +136 -0
  77. package/dist/modules.d.ts +56 -8
  78. package/dist/modules.js +128 -3
  79. package/dist/money-decimal.d.ts +54 -0
  80. package/dist/money-decimal.js +95 -0
  81. package/dist/newsletter.d.ts +4 -4
  82. package/dist/orders.d.ts +246 -12
  83. package/dist/orders.js +140 -7
  84. package/dist/organization-hooks.d.ts +99 -0
  85. package/dist/organization-hooks.js +22 -0
  86. package/dist/organization-registry-lookup.d.ts +362 -0
  87. package/dist/organization-registry-lookup.js +196 -0
  88. package/dist/organization-roles.d.ts +341 -0
  89. package/dist/organization-roles.js +218 -0
  90. package/dist/organizations.d.ts +1074 -103
  91. package/dist/organizations.js +293 -28
  92. package/dist/page-builder-props.d.ts +56 -56
  93. package/dist/pim-connector.d.ts +7 -3
  94. package/dist/pim-connector.js +6 -2
  95. package/dist/pim-field-path.d.ts +5 -1
  96. package/dist/pim-field-path.js +37 -81
  97. package/dist/pim-locale-mapping.d.ts +131 -0
  98. package/dist/pim-locale-mapping.js +193 -0
  99. package/dist/price-books.d.ts +215 -63
  100. package/dist/price-books.js +47 -2
  101. package/dist/price-lists.d.ts +13 -10
  102. package/dist/product-feeds.d.ts +249 -100
  103. package/dist/product-feeds.js +46 -2
  104. package/dist/product-scope-model.d.ts +161 -0
  105. package/dist/product-scope-model.js +161 -0
  106. package/dist/product-scope-overrides.d.ts +0 -103
  107. package/dist/product-scope-overrides.js +0 -54
  108. package/dist/product-scoped-values.d.ts +2610 -0
  109. package/dist/product-scoped-values.js +425 -0
  110. package/dist/product-scopes.d.ts +199 -64
  111. package/dist/product-scopes.js +120 -23
  112. package/dist/product-tax-rates.d.ts +38 -0
  113. package/dist/product-tax-rates.js +45 -0
  114. package/dist/product-url-keys.d.ts +51 -45
  115. package/dist/product-url-keys.js +73 -39
  116. package/dist/product-value-resolver.d.ts +37 -60
  117. package/dist/product-value-resolver.js +36 -96
  118. package/dist/projects.d.ts +76 -28
  119. package/dist/projects.js +53 -9
  120. package/dist/promotions.d.ts +163 -11
  121. package/dist/promotions.js +23 -1
  122. package/dist/pwa.d.ts +41 -2
  123. package/dist/quick-order.d.ts +159 -9
  124. package/dist/quick-order.js +79 -4
  125. package/dist/quote-requests.d.ts +231 -17
  126. package/dist/quote-requests.js +111 -9
  127. package/dist/record-references.d.ts +15 -15
  128. package/dist/record-references.js +2 -3
  129. package/dist/record-rich-text.js +2 -1
  130. package/dist/returns.d.ts +214 -52
  131. package/dist/returns.js +143 -28
  132. package/dist/sales-channels.d.ts +34 -3
  133. package/dist/sales-channels.js +16 -1
  134. package/dist/saved-list-views.d.ts +28 -0
  135. package/dist/saved-list-views.js +14 -1
  136. package/dist/schema-extensions.d.ts +36 -0
  137. package/dist/schema-extensions.js +29 -0
  138. package/dist/scoped-write-encoding.d.ts +100 -0
  139. package/dist/scoped-write-encoding.js +135 -0
  140. package/dist/search.d.ts +18 -16
  141. package/dist/seo.d.ts +83 -30
  142. package/dist/seo.js +8 -1
  143. package/dist/settings.d.ts +173 -2
  144. package/dist/settings.js +53 -2
  145. package/dist/shopping-lists.d.ts +63 -4
  146. package/dist/shopping-lists.js +57 -3
  147. package/dist/storefront-cache-tags.d.ts +22 -0
  148. package/dist/storefront-cache-tags.js +12 -0
  149. package/dist/storefront-value-overrides.d.ts +18 -56
  150. package/dist/storefront-value-overrides.js +11 -86
  151. package/dist/tasks.d.ts +27 -27
  152. package/dist/taxes.d.ts +27 -0
  153. package/dist/taxes.js +4 -0
  154. package/dist/transactional-emails.d.ts +48 -22
  155. package/dist/webhooks.d.ts +75 -0
  156. package/dist/webhooks.js +24 -0
  157. package/package.json +5 -3
  158. package/dist/actor.d.ts.map +0 -1
  159. package/dist/actor.js.map +0 -1
  160. package/dist/addresses.d.ts.map +0 -1
  161. package/dist/addresses.js.map +0 -1
  162. package/dist/admin-actions.d.ts.map +0 -1
  163. package/dist/admin-actions.js.map +0 -1
  164. package/dist/admin-contributions.d.ts.map +0 -1
  165. package/dist/admin-contributions.js.map +0 -1
  166. package/dist/admin-feedback.d.ts.map +0 -1
  167. package/dist/admin-feedback.js.map +0 -1
  168. package/dist/admin-i18n.d.ts.map +0 -1
  169. package/dist/admin-i18n.js.map +0 -1
  170. package/dist/admin-name.d.ts.map +0 -1
  171. package/dist/admin-name.js.map +0 -1
  172. package/dist/admin-notifications.d.ts.map +0 -1
  173. package/dist/admin-notifications.js.map +0 -1
  174. package/dist/admin-preferences.d.ts.map +0 -1
  175. package/dist/admin-preferences.js.map +0 -1
  176. package/dist/admin-roles.d.ts.map +0 -1
  177. package/dist/admin-roles.js.map +0 -1
  178. package/dist/admin-search.d.ts.map +0 -1
  179. package/dist/admin-search.js.map +0 -1
  180. package/dist/admin-users.d.ts.map +0 -1
  181. package/dist/admin-users.js.map +0 -1
  182. package/dist/admin.d.ts.map +0 -1
  183. package/dist/admin.js.map +0 -1
  184. package/dist/analytics.d.ts.map +0 -1
  185. package/dist/analytics.js.map +0 -1
  186. package/dist/api-keys.d.ts.map +0 -1
  187. package/dist/api-keys.js.map +0 -1
  188. package/dist/assets-library.d.ts.map +0 -1
  189. package/dist/assets-library.js.map +0 -1
  190. package/dist/audit-logs.d.ts.map +0 -1
  191. package/dist/audit-logs.js.map +0 -1
  192. package/dist/auth.d.ts.map +0 -1
  193. package/dist/auth.js.map +0 -1
  194. package/dist/blog.d.ts.map +0 -1
  195. package/dist/blog.js.map +0 -1
  196. package/dist/capabilities.d.ts.map +0 -1
  197. package/dist/capabilities.js.map +0 -1
  198. package/dist/carts.d.ts.map +0 -1
  199. package/dist/carts.js.map +0 -1
  200. package/dist/catalog.d.ts.map +0 -1
  201. package/dist/catalog.js.map +0 -1
  202. package/dist/cms-brand.d.ts.map +0 -1
  203. package/dist/cms-brand.js.map +0 -1
  204. package/dist/cms-contact-form.d.ts.map +0 -1
  205. package/dist/cms-contact-form.js.map +0 -1
  206. package/dist/cms.d.ts.map +0 -1
  207. package/dist/cms.js.map +0 -1
  208. package/dist/common.d.ts.map +0 -1
  209. package/dist/common.js.map +0 -1
  210. package/dist/comparisons.d.ts.map +0 -1
  211. package/dist/comparisons.js.map +0 -1
  212. package/dist/credentials.d.ts.map +0 -1
  213. package/dist/credentials.js.map +0 -1
  214. package/dist/credit-limits.d.ts.map +0 -1
  215. package/dist/credit-limits.js.map +0 -1
  216. package/dist/crm-rich-text.d.ts.map +0 -1
  217. package/dist/crm-rich-text.js.map +0 -1
  218. package/dist/crm.d.ts.map +0 -1
  219. package/dist/crm.js.map +0 -1
  220. package/dist/currencies.d.ts.map +0 -1
  221. package/dist/currencies.js.map +0 -1
  222. package/dist/custom-fields.d.ts.map +0 -1
  223. package/dist/custom-fields.js.map +0 -1
  224. package/dist/customer-accounts.d.ts.map +0 -1
  225. package/dist/customer-accounts.js.map +0 -1
  226. package/dist/customers.d.ts.map +0 -1
  227. package/dist/customers.js.map +0 -1
  228. package/dist/dictionary.d.ts.map +0 -1
  229. package/dist/dictionary.js.map +0 -1
  230. package/dist/document-templates.d.ts.map +0 -1
  231. package/dist/document-templates.js.map +0 -1
  232. package/dist/document-values.d.ts.map +0 -1
  233. package/dist/document-values.js.map +0 -1
  234. package/dist/email-address.d.ts.map +0 -1
  235. package/dist/email-address.js.map +0 -1
  236. package/dist/email.d.ts.map +0 -1
  237. package/dist/email.js.map +0 -1
  238. package/dist/envelopes.d.ts.map +0 -1
  239. package/dist/envelopes.js.map +0 -1
  240. package/dist/environment-inputs.d.ts.map +0 -1
  241. package/dist/environment-inputs.js.map +0 -1
  242. package/dist/erp-connector.d.ts.map +0 -1
  243. package/dist/erp-connector.js.map +0 -1
  244. package/dist/errors.d.ts.map +0 -1
  245. package/dist/errors.js.map +0 -1
  246. package/dist/google-analytics.d.ts.map +0 -1
  247. package/dist/google-analytics.js.map +0 -1
  248. package/dist/google-tag-manager.d.ts.map +0 -1
  249. package/dist/google-tag-manager.js.map +0 -1
  250. package/dist/i18n.d.ts.map +0 -1
  251. package/dist/i18n.js.map +0 -1
  252. package/dist/import-export.d.ts.map +0 -1
  253. package/dist/import-export.js.map +0 -1
  254. package/dist/index.d.ts.map +0 -1
  255. package/dist/index.js.map +0 -1
  256. package/dist/inventory.d.ts.map +0 -1
  257. package/dist/inventory.js.map +0 -1
  258. package/dist/invoice-ledger.d.ts.map +0 -1
  259. package/dist/invoice-ledger.js.map +0 -1
  260. package/dist/invoices.d.ts.map +0 -1
  261. package/dist/invoices.js.map +0 -1
  262. package/dist/kernel.d.ts.map +0 -1
  263. package/dist/kernel.js.map +0 -1
  264. package/dist/languages.d.ts.map +0 -1
  265. package/dist/languages.js.map +0 -1
  266. package/dist/line-groups.d.ts.map +0 -1
  267. package/dist/line-groups.js.map +0 -1
  268. package/dist/linkedin-ads.d.ts.map +0 -1
  269. package/dist/linkedin-ads.js.map +0 -1
  270. package/dist/localized-name.d.ts.map +0 -1
  271. package/dist/localized-name.js.map +0 -1
  272. package/dist/megamenu.d.ts.map +0 -1
  273. package/dist/megamenu.js.map +0 -1
  274. package/dist/meta-ads.d.ts.map +0 -1
  275. package/dist/meta-ads.js.map +0 -1
  276. package/dist/mfa.d.ts.map +0 -1
  277. package/dist/mfa.js.map +0 -1
  278. package/dist/modules.d.ts.map +0 -1
  279. package/dist/modules.js.map +0 -1
  280. package/dist/money-decimal.d.ts.map +0 -1
  281. package/dist/money-decimal.js.map +0 -1
  282. package/dist/money-input.d.ts.map +0 -1
  283. package/dist/money-input.js.map +0 -1
  284. package/dist/newsletter.d.ts.map +0 -1
  285. package/dist/newsletter.js.map +0 -1
  286. package/dist/order-minimums.d.ts.map +0 -1
  287. package/dist/order-minimums.js.map +0 -1
  288. package/dist/orders.d.ts.map +0 -1
  289. package/dist/orders.js.map +0 -1
  290. package/dist/organizations.d.ts.map +0 -1
  291. package/dist/organizations.js.map +0 -1
  292. package/dist/page-builder-props.d.ts.map +0 -1
  293. package/dist/page-builder-props.js.map +0 -1
  294. package/dist/page-builder-values.d.ts.map +0 -1
  295. package/dist/page-builder-values.js.map +0 -1
  296. package/dist/pagination.d.ts.map +0 -1
  297. package/dist/pagination.js.map +0 -1
  298. package/dist/payment-methods.d.ts.map +0 -1
  299. package/dist/payment-methods.js.map +0 -1
  300. package/dist/payment-return-url.d.ts.map +0 -1
  301. package/dist/payment-return-url.js.map +0 -1
  302. package/dist/payments.d.ts.map +0 -1
  303. package/dist/payments.js.map +0 -1
  304. package/dist/pim-connector.d.ts.map +0 -1
  305. package/dist/pim-connector.js.map +0 -1
  306. package/dist/pim-field-path.d.ts.map +0 -1
  307. package/dist/pim-field-path.js.map +0 -1
  308. package/dist/platform-info.d.ts.map +0 -1
  309. package/dist/platform-info.js.map +0 -1
  310. package/dist/platform-language.d.ts.map +0 -1
  311. package/dist/platform-language.js.map +0 -1
  312. package/dist/price-book-decimal.d.ts.map +0 -1
  313. package/dist/price-book-decimal.js.map +0 -1
  314. package/dist/price-books.d.ts.map +0 -1
  315. package/dist/price-books.js.map +0 -1
  316. package/dist/price-lists.d.ts.map +0 -1
  317. package/dist/price-lists.js.map +0 -1
  318. package/dist/product-feeds.d.ts.map +0 -1
  319. package/dist/product-feeds.js.map +0 -1
  320. package/dist/product-scope-overrides.d.ts.map +0 -1
  321. package/dist/product-scope-overrides.js.map +0 -1
  322. package/dist/product-scopes.d.ts.map +0 -1
  323. package/dist/product-scopes.js.map +0 -1
  324. package/dist/product-summary-text.d.ts.map +0 -1
  325. package/dist/product-summary-text.js.map +0 -1
  326. package/dist/product-url-keys.d.ts.map +0 -1
  327. package/dist/product-url-keys.js.map +0 -1
  328. package/dist/product-value-resolver.d.ts.map +0 -1
  329. package/dist/product-value-resolver.js.map +0 -1
  330. package/dist/projects.d.ts.map +0 -1
  331. package/dist/projects.js.map +0 -1
  332. package/dist/promotions.d.ts.map +0 -1
  333. package/dist/promotions.js.map +0 -1
  334. package/dist/prompt-actions.d.ts.map +0 -1
  335. package/dist/prompt-actions.js.map +0 -1
  336. package/dist/pwa.d.ts.map +0 -1
  337. package/dist/pwa.js.map +0 -1
  338. package/dist/quick-order.d.ts.map +0 -1
  339. package/dist/quick-order.js.map +0 -1
  340. package/dist/quote-requests.d.ts.map +0 -1
  341. package/dist/quote-requests.js.map +0 -1
  342. package/dist/record-references.d.ts.map +0 -1
  343. package/dist/record-references.js.map +0 -1
  344. package/dist/record-rich-text.d.ts.map +0 -1
  345. package/dist/record-rich-text.js.map +0 -1
  346. package/dist/returns.d.ts.map +0 -1
  347. package/dist/returns.js.map +0 -1
  348. package/dist/sales-channels.d.ts.map +0 -1
  349. package/dist/sales-channels.js.map +0 -1
  350. package/dist/saved-list-views.d.ts.map +0 -1
  351. package/dist/saved-list-views.js.map +0 -1
  352. package/dist/scope-notice.d.ts.map +0 -1
  353. package/dist/scope-notice.js.map +0 -1
  354. package/dist/scoped-translations.d.ts +0 -48
  355. package/dist/scoped-translations.d.ts.map +0 -1
  356. package/dist/scoped-translations.js +0 -78
  357. package/dist/scoped-translations.js.map +0 -1
  358. package/dist/search.d.ts.map +0 -1
  359. package/dist/search.js.map +0 -1
  360. package/dist/seo.d.ts.map +0 -1
  361. package/dist/seo.js.map +0 -1
  362. package/dist/settings.d.ts.map +0 -1
  363. package/dist/settings.js.map +0 -1
  364. package/dist/shipments.d.ts.map +0 -1
  365. package/dist/shipments.js.map +0 -1
  366. package/dist/shipping-methods.d.ts.map +0 -1
  367. package/dist/shipping-methods.js.map +0 -1
  368. package/dist/shopping-lists.d.ts.map +0 -1
  369. package/dist/shopping-lists.js.map +0 -1
  370. package/dist/storefront-cache-tags.d.ts.map +0 -1
  371. package/dist/storefront-cache-tags.js.map +0 -1
  372. package/dist/storefront-language-path.d.ts.map +0 -1
  373. package/dist/storefront-language-path.js.map +0 -1
  374. package/dist/storefront-value-overrides.d.ts.map +0 -1
  375. package/dist/storefront-value-overrides.js.map +0 -1
  376. package/dist/tasks.d.ts.map +0 -1
  377. package/dist/tasks.js.map +0 -1
  378. package/dist/taxes.d.ts.map +0 -1
  379. package/dist/taxes.js.map +0 -1
  380. package/dist/text-normalization.d.ts.map +0 -1
  381. package/dist/text-normalization.js.map +0 -1
  382. package/dist/transactional-emails.d.ts.map +0 -1
  383. package/dist/transactional-emails.js.map +0 -1
  384. package/dist/webhooks.d.ts.map +0 -1
  385. package/dist/webhooks.js.map +0 -1
@@ -1,7 +1,9 @@
1
1
  import { z } from 'zod';
2
2
  import { type ProductVisibility } from './common.js';
3
3
  import { type ProductAudience } from './catalog.js';
4
- import type { ProductUrlKeyWrite, UrlKeyWriteOutcome } from './product-url-keys.js';
4
+ import type { UrlKeyWriteOutcome } from './product-url-keys.js';
5
+ import { type FieldPath, type ScopeRef } from './product-scope-model.js';
6
+ import { type ScopedWriteOp } from './scoped-write-encoding.js';
5
7
  /**
6
8
  * Feature 163 (`specs/163-product-data-scopes/`) — product data scopes per sales
7
9
  * channel and language: the one rule of effective availability, its admin shapes and
@@ -38,7 +40,10 @@ export interface AudienceRule {
38
40
  visibility: ProductVisibility;
39
41
  allowedOrganizationIds: string[];
40
42
  }
41
- /** A `product_channel_scopes` row. Every `null` inherits the global value. */
43
+ /**
44
+ * A `product_channel_scopes` row. Every `null` inherits the global value, except the
45
+ * minimum order quantity, whose override is the flag (feature 174, data-model §4).
46
+ */
42
47
  export interface ProductChannelScopeRecord {
43
48
  productId: string;
44
49
  channelId: string;
@@ -48,7 +53,12 @@ export interface ProductChannelScopeRecord {
48
53
  window: PublicationWindow | null;
49
54
  /** `null` = inherit the whole global rule. */
50
55
  audience: AudienceRule | null;
51
- /** `null` = inherit; `1` = no minimum in this channel. */
56
+ /**
57
+ * Feature 174 (data-model §4) — whether the channel overrides the global minimum. When
58
+ * it does, {@link minOrderQuantity} `null` = **no minimum in this channel**.
59
+ */
60
+ minOrderQuantityOverridden: boolean;
61
+ /** Meaningful only when {@link minOrderQuantityOverridden}; `null` = no minimum here. */
52
62
  minOrderQuantity: number | null;
53
63
  /** `null` = inherit. */
54
64
  returnable: boolean | null;
@@ -94,7 +104,7 @@ export declare function isInsideWindow(window: PublicationWindow, now: Date): bo
94
104
  /** The channel's rule when it overrides one, else the global rule — replaced whole, never merged (C4). */
95
105
  export declare function effectiveAudience(global: Pick<ProductGlobalScopeFields, 'visibility' | 'allowedOrganizationIds'>, channelRow: Pick<ProductChannelScopeRecord, 'audience'> | undefined): AudienceRule;
96
106
  /** Minimum order quantity and the returnable flag in a channel (FR-100). */
97
- export declare function effectiveOrderRules(global: Pick<ProductGlobalScopeFields, 'minOrderQuantity' | 'returnable'>, channelRow: Pick<ProductChannelScopeRecord, 'minOrderQuantity' | 'returnable'> | undefined): {
107
+ export declare function effectiveOrderRules(global: Pick<ProductGlobalScopeFields, 'minOrderQuantity' | 'returnable'>, channelRow: Pick<ProductChannelScopeRecord, 'minOrderQuantity' | 'minOrderQuantityOverridden' | 'returnable'> | undefined): {
98
108
  minOrderQuantity: number | null;
99
109
  returnable: boolean;
100
110
  };
@@ -167,7 +177,7 @@ export declare function pairsTurningOn(before: ScopeSnapshot, after: ScopeSnapsh
167
177
  * BCP-47 codes, while the prose resolver normalises to the platform's UI languages.
168
178
  */
169
179
  export declare function resolveScopeLanguage(channel: ScopeChannel, requestedTag: string | null | undefined): string;
170
- export { applyTranslationPatch, effectivePackagingUnitName, sameLanguage, translationAt, translationMapPatchSchema, TRANSLATION_MAP_MAX_LANGUAGES, type TranslationMap, } from './scoped-translations.js';
180
+ export { sameLanguage } from './product-scope-model.js';
171
181
  /**
172
182
  * A channel record as the scope rule reads it. The default language is always
173
183
  * one of the languages: a channel whose list is empty, or omits its own
@@ -190,6 +200,23 @@ export declare function scopeLanguageOf(channel: {
190
200
  languages?: readonly string[] | undefined;
191
201
  defaultLanguage: string;
192
202
  }, requestedTag: string | null | undefined): string;
203
+ /**
204
+ * The scope language L of a buyer request on `channel` from its whole
205
+ * `Accept-Language` header (issue #397): the tags in descending `q`
206
+ * ({@link parseAcceptLanguage}), each matched against the channel's languages as
207
+ * {@link resolveScopeLanguage} matches one — exactly, then by base language
208
+ * (`pl` → `pl-PL`) — and the first tag the channel serves wins; with none served,
209
+ * the channel's default. Always spelled as the channel spells it.
210
+ *
211
+ * The header form of {@link scopeLanguageOf}; prefer it to
212
+ * `scopeLanguageOf(channel, firstLanguageTag(header))`, which ignores the weights
213
+ * and stops at the first tag whether or not the channel serves it.
214
+ */
215
+ export declare function requestScopeLanguage(channel: {
216
+ id: string;
217
+ languages?: readonly string[] | undefined;
218
+ defaultLanguage: string;
219
+ }, header: string | readonly string[] | undefined): string;
193
220
  /**
194
221
  * The first tag of an `Accept-Language` header, without its quality parameter,
195
222
  * or `undefined` when the header is absent or empty.
@@ -228,14 +255,24 @@ export interface CatalogProductAvailabilityPort {
228
255
  /** Projection for whole-channel consumers (search documents, sitemap, feeds). Non-members are absent. */
229
256
  describeChannelAvailability(productIds: readonly string[], channelId: string): Promise<Map<string, ChannelAvailability>>;
230
257
  /**
231
- * FR-017 — the effective name per id at (channel, language): #384's walk over
232
- * the channel's overrides, else the storefront's baseline pick. `languageCode`
233
- * `null` = the channel's default language (an operator, N2).
258
+ * Feature 174 (FR-030, `contracts/readers.md` §2) — the effective name and description
259
+ * per id at (channel, language) along C×L → C → G; an empty description override
260
+ * answers `null`. `languageCode` `null` = the channel's default language (an
261
+ * operator, N2). Applies no availability: an id not found is absent.
234
262
  */
235
- effectiveNames(productIds: readonly string[], scope: {
263
+ effectiveTexts(productIds: readonly string[], scope: {
236
264
  channelId: string;
237
265
  languageCode: string | null;
238
- }): Promise<Map<string, string>>;
266
+ }): Promise<Map<string, EffectiveProductTexts>>;
267
+ /**
268
+ * Feature 174 — the effective packaging-unit name per unit id at (channel, language);
269
+ * `null` = an empty override (nothing shown). Basket and quote snapshots take it at
270
+ * the line's scope and never re-resolve it.
271
+ */
272
+ effectivePackagingUnitNames(unitIds: readonly string[], scope: {
273
+ channelId: string;
274
+ languageCode: string | null;
275
+ }): Promise<Map<string, string | null>>;
239
276
  /**
240
277
  * FR-100 — the effective minimum order quantity and returnable flag in the channel.
241
278
  *
@@ -249,47 +286,131 @@ export interface CatalogProductAvailabilityPort {
249
286
  returnable: boolean;
250
287
  }>>;
251
288
  }
252
- /** What an integration writes through {@link CatalogProductScopeWritePort}; only named scopes are touched. */
253
- export interface ProductScopeWriteInput {
254
- /** `languageCode: null` = the channel row; `value: null` = use inherited. */
255
- status?: Array<{
256
- channelId: string;
257
- languageCode: string | null;
258
- value: ProductScopeStatus | null;
259
- }>;
260
- /** `channelId: null` = the global window; `value: null` on a channel = use inherited. */
261
- window?: Array<{
262
- channelId: string | null;
263
- value: PublicationWindow | null;
264
- }>;
265
- /** `value: null` = use inherited. */
266
- audience?: Array<{
267
- channelId: string;
268
- value: AudienceRule | null;
269
- }>;
270
- /** Each field: absent = untouched, `null` = use inherited. */
271
- orderRules?: Array<{
272
- channelId: string;
273
- minOrderQuantity?: number | null;
274
- returnable?: boolean | null;
275
- }>;
276
- urlKeys?: ProductUrlKeyWrite[];
289
+ /** {@link CatalogProductAvailabilityPort.effectiveTexts}' answer for one product. */
290
+ export interface EffectiveProductTexts {
291
+ name: string;
292
+ /** `null` = no description at this scope (none anywhere, or an empty override). */
293
+ description: string | null;
294
+ }
295
+ /** One cell of a connector or import write: one field at one scope (`pim-locale-mapping.md` §4). */
296
+ export interface ProductScopedWriteCell {
297
+ scope: ScopeRef;
298
+ field: FieldPath;
299
+ op: ScopedWriteOp<unknown>;
277
300
  }
278
- export interface ProductScopeWriteResult {
279
- /** One outcome per entry of `urlKeys`, in order. */
301
+ /**
302
+ * Feature 174 — what an integration writes through {@link CatalogProductScopeWritePort} (v2):
303
+ * only the named (field, scope) cells are touched (FR-044), so writing Global values removes
304
+ * no operator override.
305
+ */
306
+ export interface ProductScopedWriteInput {
307
+ cells: ProductScopedWriteCell[];
308
+ }
309
+ /** The most cells one call of the scope write port carries (R13a). */
310
+ export declare const PRODUCT_SCOPED_WRITE_CELLS_MAX = 2000;
311
+ /**
312
+ * The field paths of data-model §9, as a grammar: a family, a subject uuid where the family has
313
+ * one, an attribute key. Global-only fields are not paths.
314
+ */
315
+ export declare const fieldPathSchema: z.ZodPipe<z.ZodString, z.ZodTransform<"description" | "name" | "status" | "window" | "audience" | "minOrderQuantity" | "returnable" | "urlKey" | "seo:description" | "seo:title" | "seo:ogTitle" | "seo:ogDescription" | "seo:ogImageUrl" | `attribute:${string}` | `gallery:${string}:altText` | `gallery:${string}:hidden` | "galleryRole:base_image" | "galleryRole:small_image" | "galleryRole:thumbnail" | `attachment:${string}:description` | `attachment:${string}:name` | `attachment:${string}:hidden` | `packagingUnit:${string}:name`, string>>;
316
+ /** A scope as a request names it (`scoped-values-api.md` §1): neither → G, channel → C, both → C×L. */
317
+ export declare const scopeRequestSchema: z.ZodObject<{
318
+ channelId: z.ZodOptional<z.ZodString>;
319
+ languageCode: z.ZodOptional<z.ZodString>;
320
+ }, z.core.$strict>;
321
+ /** The wire form of {@link ProductScopedWriteInput}: `value` in the write encoding. */
322
+ export declare const productScopedWriteInputSchema: z.ZodPipe<z.ZodObject<{
323
+ cells: z.ZodArray<z.ZodObject<{
324
+ scope: z.ZodObject<{
325
+ channelId: z.ZodOptional<z.ZodString>;
326
+ languageCode: z.ZodOptional<z.ZodString>;
327
+ }, z.core.$strict>;
328
+ field: z.ZodPipe<z.ZodString, z.ZodTransform<"description" | "name" | "status" | "window" | "audience" | "minOrderQuantity" | "returnable" | "urlKey" | "seo:description" | "seo:title" | "seo:ogTitle" | "seo:ogDescription" | "seo:ogImageUrl" | `attribute:${string}` | `gallery:${string}:altText` | `gallery:${string}:hidden` | "galleryRole:base_image" | "galleryRole:small_image" | "galleryRole:thumbnail" | `attachment:${string}:description` | `attachment:${string}:name` | `attachment:${string}:hidden` | `packagingUnit:${string}:name`, string>>;
329
+ value: z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodOptional<z.ZodUnion<readonly [z.ZodNull, z.ZodObject<{
330
+ inherit: z.ZodLiteral<true>;
331
+ }, z.core.$strict>, z.ZodUnknown & z.ZodType<{} | null, unknown, z.core.$ZodTypeInternals<{} | null, unknown>>]>>>;
332
+ }, z.core.$strict>>;
333
+ }, z.core.$strict>, z.ZodTransform<{
334
+ cells: {
335
+ scope: ScopeRef;
336
+ field: "description" | "name" | "status" | "window" | "audience" | "minOrderQuantity" | "returnable" | "urlKey" | "seo:description" | "seo:title" | "seo:ogTitle" | "seo:ogDescription" | "seo:ogImageUrl" | `attribute:${string}` | `gallery:${string}:altText` | `gallery:${string}:hidden` | "galleryRole:base_image" | "galleryRole:small_image" | "galleryRole:thumbnail" | `attachment:${string}:description` | `attachment:${string}:name` | `attachment:${string}:hidden` | `packagingUnit:${string}:name`;
337
+ op: ScopedWriteOp<{}> | undefined;
338
+ }[];
339
+ }, {
340
+ cells: {
341
+ scope: {
342
+ channelId?: string | undefined;
343
+ languageCode?: string | undefined;
344
+ };
345
+ field: "description" | "name" | "status" | "window" | "audience" | "minOrderQuantity" | "returnable" | "urlKey" | "seo:description" | "seo:title" | "seo:ogTitle" | "seo:ogDescription" | "seo:ogImageUrl" | `attribute:${string}` | `gallery:${string}:altText` | `gallery:${string}:hidden` | "galleryRole:base_image" | "galleryRole:small_image" | "galleryRole:thumbnail" | `attachment:${string}:description` | `attachment:${string}:name` | `attachment:${string}:hidden` | `packagingUnit:${string}:name`;
346
+ value?: {} | {
347
+ inherit: true;
348
+ } | null | undefined;
349
+ }[];
350
+ }>>;
351
+ /**
352
+ * Feature 174 (`pim-locale-mapping.md` §4, R13a, R21) — why one cell of an integration write was
353
+ * not applied. The rest of the call still applies (per-cell tolerant):
354
+ *
355
+ * - `not_supported` — the field family is outside the integration allowlist
356
+ * ({@link integrationWritableField});
357
+ * - `SCOPE_INVALID` — a channel the product is not a member of, or a language it does not offer;
358
+ * - `FIELD_NOT_AT_SCOPE` — the field has no value at the scope's level (data-model §9);
359
+ * - `required_empty`, `not_emptyable`, `inherit_at_global` — `validateScopedWrite`'s refusals;
360
+ * - `subject_not_found` — a gallery item, attachment or packaging unit that is not the product's;
361
+ * - `invalid` — a value its field's own schema refuses (type, length, an attribute outside the
362
+ * product's set, an option the attribute does not have).
363
+ *
364
+ * A `urlKey` cell another product holds is not a refusal: it is reported in `urlKeys`.
365
+ */
366
+ export type ProductScopedWriteRefusalCode = 'not_supported' | 'SCOPE_INVALID' | 'FIELD_NOT_AT_SCOPE' | 'required_empty' | 'not_emptyable' | 'inherit_at_global' | 'subject_not_found' | 'invalid';
367
+ export interface ProductScopedWriteResult {
368
+ /** Cells written. */
369
+ applied: number;
370
+ /** Cells refused; `index` is the cell's position in `input.cells`. */
371
+ refused: Array<{
372
+ index: number;
373
+ scope: ScopeRef;
374
+ field: FieldPath;
375
+ code: ProductScopedWriteRefusalCode;
376
+ }>;
377
+ /** One outcome per `urlKey` cell, in order. */
280
378
  urlKeys: UrlKeyWriteOutcome[];
281
379
  }
282
380
  /**
283
- * Container name: `catalogProductScopeWritePort`. Owner: `catalog` (R17).
381
+ * R13a (plan decision Q6) — whether an integration (a PIM connector, the products import) may
382
+ * write `field` at all: `name`, `description`, `attribute:<key>`, `gallery:<id>:altText`,
383
+ * `attachment:<id>:name|description`, `packagingUnit:<id>:name`, `urlKey`, `status`, `window`.
384
+ * Every other family — `audience`, `product.*`, `seo:*`, `galleryRole:*`, `*:hidden`,
385
+ * `minOrderQuantity`, `returnable` — is `not_supported`. Pure; the port applies it per cell.
386
+ */
387
+ export declare function integrationWritableField(field: string): boolean;
388
+ /**
389
+ * Container name: `catalogProductScopeWritePort`. Owner: `catalog` (R17, feature 174 v2,
390
+ * `contracts/pim-locale-mapping.md` §4).
391
+ *
392
+ * Scoped writes for connectors: one Command `product.scoped_values.import` per call (one audit
393
+ * entry, `source` in it, `product.updated.v1` after commit, `products.scope_version` bumped),
394
+ * per-cell tolerant (each refused cell is reported with a {@link ProductScopedWriteRefusalCode},
395
+ * the rest applied; a call where every cell is refused writes, audits and bumps nothing). Each
396
+ * value is checked against its field's own schema (the save's — lengths `PRODUCT_NAME_MAX`,
397
+ * `PRODUCT_DESCRIPTION_MAX`, attribute value types and options) and `validateScopedWrite`
398
+ * (`required_empty`, `not_emptyable`, `inherit_at_global`); every subject id must be the
399
+ * product's. Never the completeness gate (A-6); URL keys through the URL-key service in
400
+ * `integration` mode — a key another product holds is reported in `urlKeys`, a redirect is never
401
+ * taken over (FR-093). Allowlist: {@link integrationWritableField}.
284
402
  *
285
- * Scoped writes for imports and connectors. Writes only the scopes named, so writing
286
- * global values removes no operator override (FR-091); never runs the completeness
287
- * gate (A-6); never takes over a redirect (FR-093).
403
+ * The call itself is refused — nothing written — with:
404
+ * - `404 PRODUCT_NOT_FOUND` for an unknown or deleted product;
405
+ * - `422 VALIDATION_FAILED` `details.field = 'source'` when `options.source` is not a module id
406
+ * (`^[a-z][a-z0-9_]{1,63}$`) present in the module registry;
407
+ * - `422 VALIDATION_FAILED` `details.field = 'cells'` for more than
408
+ * {@link PRODUCT_SCOPED_WRITE_CELLS_MAX} cells or the same (field, scope) twice.
288
409
  */
289
410
  export interface CatalogProductScopeWritePort {
290
- applyScopes(productId: string, input: ProductScopeWriteInput, options: {
411
+ applyScopes(productId: string, input: ProductScopedWriteInput, options: {
291
412
  source: string;
292
- }): Promise<ProductScopeWriteResult>;
413
+ }): Promise<ProductScopedWriteResult>;
293
414
  }
294
415
  /**
295
416
  * What the completeness gate reports missing at a (channel, language) — one
@@ -337,6 +458,7 @@ export declare const productScopesSchema: z.ZodObject<{
337
458
  allowedOrganizationIds: z.ZodArray<z.ZodString>;
338
459
  nonMemberOrganizationIds: z.ZodArray<z.ZodString>;
339
460
  }, z.core.$strip>>;
461
+ minOrderQuantityOverridden: z.ZodBoolean;
340
462
  minOrderQuantity: z.ZodNullable<z.ZodNumber>;
341
463
  returnable: z.ZodNullable<z.ZodBoolean>;
342
464
  languageStatuses: z.ZodArray<z.ZodObject<{
@@ -394,6 +516,7 @@ export declare const productScopesResponseSchema: z.ZodObject<{
394
516
  allowedOrganizationIds: z.ZodArray<z.ZodString>;
395
517
  nonMemberOrganizationIds: z.ZodArray<z.ZodString>;
396
518
  }, z.core.$strip>>;
519
+ minOrderQuantityOverridden: z.ZodBoolean;
397
520
  minOrderQuantity: z.ZodNullable<z.ZodNumber>;
398
521
  returnable: z.ZodNullable<z.ZodBoolean>;
399
522
  languageStatuses: z.ZodArray<z.ZodObject<{
@@ -414,38 +537,54 @@ export declare const productScopesResponseSchema: z.ZodObject<{
414
537
  }, z.core.$strip>;
415
538
  export type ProductScopesResponse = z.infer<typeof productScopesResponseSchema>;
416
539
  /**
417
- * §2 — `PATCH /api/v1/admin/catalog/products/:id/scopes`. An absent key leaves the
418
- * value untouched; `null` = use inherited (deletes the override, FR-012). A window
419
- * whose `from` is not before its `until` passes the schema and is refused by the
420
- * service with `VALIDATION_FAILED`, `details.field = 'window'`.
540
+ * §2 — `PATCH /api/v1/admin/catalog/products/:id/scopes`, in the one write encoding
541
+ * (feature 174, `contracts/write-encoding.md` §5, FR-116): absent or `""` = no change,
542
+ * `{ inherit: true }` = use inherited (deletes the override), `null` = the empty override
543
+ * where the field takes one — `minOrderQuantity: null` = no minimum in this channel,
544
+ * `window: null` = an open window override; `status`, `audience` and `returnable` refuse
545
+ * `null` (`SCOPED_VALUE_INVALID`, `not_emptyable`, from the service). A window whose
546
+ * `from` is not before its `until` is refused with `VALIDATION_FAILED`,
547
+ * `details.field = 'window'`.
421
548
  */
422
549
  export declare const patchProductScopesRequestSchema: z.ZodObject<{
423
550
  channels: z.ZodArray<z.ZodObject<{
424
551
  channelId: z.ZodString;
425
- status: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
552
+ status: z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodOptional<z.ZodUnion<readonly [z.ZodNull, z.ZodObject<{
553
+ inherit: z.ZodLiteral<true>;
554
+ }, z.core.$strict>, z.ZodEnum<{
426
555
  active: "active";
427
556
  inactive: "inactive";
428
- }>>>;
429
- window: z.ZodOptional<z.ZodNullable<z.ZodObject<{
557
+ }>]>>>;
558
+ window: z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodOptional<z.ZodUnion<readonly [z.ZodNull, z.ZodObject<{
559
+ inherit: z.ZodLiteral<true>;
560
+ }, z.core.$strict>, z.ZodObject<{
430
561
  from: z.ZodNullable<z.ZodString>;
431
562
  until: z.ZodNullable<z.ZodString>;
432
- }, z.core.$strip>>>;
433
- audience: z.ZodOptional<z.ZodNullable<z.ZodObject<{
563
+ }, z.core.$strict>]>>>;
564
+ audience: z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodOptional<z.ZodUnion<readonly [z.ZodNull, z.ZodObject<{
565
+ inherit: z.ZodLiteral<true>;
566
+ }, z.core.$strict>, z.ZodObject<{
434
567
  visibility: z.ZodEnum<{
435
568
  public: "public";
436
569
  logged_in_only: "logged_in_only";
437
570
  organization_restricted: "organization_restricted";
438
571
  }>;
439
572
  allowedOrganizationIds: z.ZodArray<z.ZodString>;
440
- }, z.core.$strip>>>;
441
- minOrderQuantity: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
442
- returnable: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
573
+ }, z.core.$strict>]>>>;
574
+ minOrderQuantity: z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodOptional<z.ZodUnion<readonly [z.ZodNull, z.ZodObject<{
575
+ inherit: z.ZodLiteral<true>;
576
+ }, z.core.$strict>, z.ZodNumber]>>>;
577
+ returnable: z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodOptional<z.ZodUnion<readonly [z.ZodNull, z.ZodObject<{
578
+ inherit: z.ZodLiteral<true>;
579
+ }, z.core.$strict>, z.ZodBoolean]>>>;
443
580
  languageStatuses: z.ZodOptional<z.ZodArray<z.ZodObject<{
444
581
  languageCode: z.ZodString;
445
- status: z.ZodNullable<z.ZodEnum<{
582
+ status: z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodOptional<z.ZodUnion<readonly [z.ZodNull, z.ZodObject<{
583
+ inherit: z.ZodLiteral<true>;
584
+ }, z.core.$strict>, z.ZodEnum<{
446
585
  active: "active";
447
586
  inactive: "inactive";
448
- }>>;
587
+ }>]>>>;
449
588
  }, z.core.$strip>>>;
450
589
  }, z.core.$strip>>;
451
590
  global: z.ZodOptional<z.ZodObject<{
@@ -504,6 +643,7 @@ export declare const patchProductScopesResponseSchema: z.ZodObject<{
504
643
  allowedOrganizationIds: z.ZodArray<z.ZodString>;
505
644
  nonMemberOrganizationIds: z.ZodArray<z.ZodString>;
506
645
  }, z.core.$strip>>;
646
+ minOrderQuantityOverridden: z.ZodBoolean;
507
647
  minOrderQuantity: z.ZodNullable<z.ZodNumber>;
508
648
  returnable: z.ZodNullable<z.ZodBoolean>;
509
649
  languageStatuses: z.ZodArray<z.ZodObject<{
@@ -552,8 +692,8 @@ export declare const scopeIncompleteDetailsSchema: z.ZodObject<{
552
692
  }, z.core.$strip>>;
553
693
  }, z.core.$strip>;
554
694
  export type ScopeIncompleteDetails = z.infer<typeof scopeIncompleteDetailsSchema>;
695
+ /** Feature 174 (FR-010) — there is no Language scope: an override sits at C or C×L. */
555
696
  export declare const scopeLevelSchema: z.ZodEnum<{
556
- language: "language";
557
697
  channel: "channel";
558
698
  channel_language: "channel_language";
559
699
  }>;
@@ -576,14 +716,13 @@ export declare const scopeOverviewResponseSchema: z.ZodObject<{
576
716
  inactive: "inactive";
577
717
  }>;
578
718
  statusSource: z.ZodEnum<{
579
- channel: "channel";
580
719
  global: "global";
720
+ channel: "channel";
581
721
  channel_language: "channel_language";
582
722
  }>;
583
723
  overriddenFields: z.ZodArray<z.ZodObject<{
584
724
  field: z.ZodString;
585
725
  level: z.ZodEnum<{
586
- language: "language";
587
726
  channel: "channel";
588
727
  channel_language: "channel_language";
589
728
  }>;
@@ -594,10 +733,6 @@ export declare const scopeOverviewResponseSchema: z.ZodObject<{
594
733
  channelId: z.ZodString;
595
734
  overriddenFields: z.ZodArray<z.ZodString>;
596
735
  }, z.core.$strip>>;
597
- languageColumns: z.ZodArray<z.ZodObject<{
598
- languageCode: z.ZodString;
599
- overriddenFields: z.ZodArray<z.ZodString>;
600
- }, z.core.$strip>>;
601
736
  orphans: z.ZodArray<z.ZodObject<{
602
737
  field: z.ZodString;
603
738
  channelId: z.ZodNullable<z.ZodString>;
@@ -1,7 +1,10 @@
1
1
  import { z } from 'zod';
2
- import { isoDateTimeSchema, multilingualStringSchema, productVisibilitySchema, uuidSchema, } from './common.js';
2
+ import { isoDateTimeSchema, multilingualStringSchema, productVisibilitySchema, UUID_SHAPE_PATTERN, uuidSchema, } from './common.js';
3
+ import { parseAcceptLanguage } from './accept-language.js';
3
4
  import { isProductVisibleTo, productStatusSchema } from './catalog.js';
4
5
  import { ORDER_MINIMUM_MAX } from './order-minimums.js';
6
+ import { scopeFromRequest } from './product-scope-model.js';
7
+ import { scopedWrite, toScopedWriteOp } from './scoped-write-encoding.js';
5
8
  /**
6
9
  * Feature 163 (`specs/163-product-data-scopes/`) — product data scopes per sales
7
10
  * channel and language: the one rule of effective availability, its admin shapes and
@@ -57,7 +60,7 @@ export function effectiveAudience(global, channelRow) {
57
60
  /** Minimum order quantity and the returnable flag in a channel (FR-100). */
58
61
  export function effectiveOrderRules(global, channelRow) {
59
62
  return {
60
- minOrderQuantity: channelRow?.minOrderQuantity ?? global.minOrderQuantity,
63
+ minOrderQuantity: channelRow?.minOrderQuantityOverridden ? channelRow.minOrderQuantity : global.minOrderQuantity,
61
64
  returnable: channelRow?.returnable ?? global.returnable,
62
65
  };
63
66
  }
@@ -147,17 +150,21 @@ function statusOnAt(snapshot, channelId, languageCode) {
147
150
  */
148
151
  export function resolveScopeLanguage(channel, requestedTag) {
149
152
  // An `Accept-Language` pick may carry its quality parameter (`de;q=0.9`).
150
- const tag = requestedTag?.split(';')[0]?.trim().toLowerCase() ?? '';
153
+ const tag = requestedTag?.split(';')[0]?.trim() ?? '';
154
+ return matchChannelLanguage(channel.languages, tag) ?? channel.defaultLanguage;
155
+ }
156
+ /** The channel language `tag` names — exactly, else by base language — or `undefined`. */
157
+ function matchChannelLanguage(languages, requestedTag) {
158
+ const tag = requestedTag.toLowerCase();
151
159
  if (tag === '')
152
- return channel.defaultLanguage;
153
- const exact = channel.languages.find((language) => language.toLowerCase() === tag);
160
+ return undefined;
161
+ const exact = languages.find((language) => language.toLowerCase() === tag);
154
162
  if (exact !== undefined)
155
163
  return exact;
156
164
  const base = baseLanguage(tag);
157
- const sameBase = channel.languages.find((language) => baseLanguage(language.toLowerCase()) === base);
158
- return sameBase ?? channel.defaultLanguage;
165
+ return languages.find((language) => baseLanguage(language.toLowerCase()) === base);
159
166
  }
160
- export { applyTranslationPatch, effectivePackagingUnitName, sameLanguage, translationAt, translationMapPatchSchema, TRANSLATION_MAP_MAX_LANGUAGES, } from './scoped-translations.js';
167
+ export { sameLanguage } from './product-scope-model.js';
161
168
  /**
162
169
  * A channel record as the scope rule reads it. The default language is always
163
170
  * one of the languages: a channel whose list is empty, or omits its own
@@ -179,6 +186,27 @@ export function toScopeChannel(channel) {
179
186
  export function scopeLanguageOf(channel, requestedTag) {
180
187
  return resolveScopeLanguage(toScopeChannel(channel), requestedTag);
181
188
  }
189
+ /**
190
+ * The scope language L of a buyer request on `channel` from its whole
191
+ * `Accept-Language` header (issue #397): the tags in descending `q`
192
+ * ({@link parseAcceptLanguage}), each matched against the channel's languages as
193
+ * {@link resolveScopeLanguage} matches one — exactly, then by base language
194
+ * (`pl` → `pl-PL`) — and the first tag the channel serves wins; with none served,
195
+ * the channel's default. Always spelled as the channel spells it.
196
+ *
197
+ * The header form of {@link scopeLanguageOf}; prefer it to
198
+ * `scopeLanguageOf(channel, firstLanguageTag(header))`, which ignores the weights
199
+ * and stops at the first tag whether or not the channel serves it.
200
+ */
201
+ export function requestScopeLanguage(channel, header) {
202
+ const { languages, defaultLanguage } = toScopeChannel(channel);
203
+ for (const tag of parseAcceptLanguage(header)) {
204
+ const match = matchChannelLanguage(languages, tag);
205
+ if (match !== undefined)
206
+ return match;
207
+ }
208
+ return defaultLanguage;
209
+ }
182
210
  /**
183
211
  * The first tag of an `Accept-Language` header, without its quality parameter,
184
212
  * or `undefined` when the header is absent or empty.
@@ -194,6 +222,72 @@ function baseLanguage(tag) {
194
222
  const dash = tag.indexOf('-');
195
223
  return dash === -1 ? tag : tag.slice(0, dash);
196
224
  }
225
+ /** The most cells one call of the scope write port carries (R13a). */
226
+ export const PRODUCT_SCOPED_WRITE_CELLS_MAX = 2000;
227
+ /** The subject uuid of a field path: the shared shape, lowercase only (issue #781). */
228
+ const LOWERCASE_UUID = UUID_SHAPE_PATTERN.replaceAll('a-fA-F', 'a-f');
229
+ /**
230
+ * The field paths of data-model §9, as a grammar: a family, a subject uuid where the family has
231
+ * one, an attribute key. Global-only fields are not paths.
232
+ */
233
+ export const fieldPathSchema = z
234
+ .string()
235
+ .max(128)
236
+ .regex(new RegExp(`^(name|description|status|window|audience|minOrderQuantity|returnable|urlKey|seo:(title|description|ogTitle|ogDescription|ogImageUrl)|attribute:[a-z0-9_]{1,64}|gallery:${LOWERCASE_UUID}:(altText|hidden)|galleryRole:(base_image|small_image|thumbnail)|attachment:${LOWERCASE_UUID}:(name|description|hidden)|packagingUnit:${LOWERCASE_UUID}:name)$`), 'field path')
237
+ .transform((path) => path);
238
+ /** A scope as a request names it (`scoped-values-api.md` §1): neither → G, channel → C, both → C×L. */
239
+ export const scopeRequestSchema = z
240
+ .object({
241
+ channelId: uuidSchema.optional(),
242
+ languageCode: z.string().max(16).regex(/^[a-z]{2,3}(-[a-z]{2})?$/i, 'BCP-47 language tag').optional(),
243
+ })
244
+ .strict();
245
+ /** The wire form of {@link ProductScopedWriteInput}: `value` in the write encoding. */
246
+ export const productScopedWriteInputSchema = z
247
+ .object({
248
+ cells: z
249
+ .array(z
250
+ .object({
251
+ scope: scopeRequestSchema,
252
+ field: fieldPathSchema,
253
+ value: scopedWrite(z.unknown().refine((value) => value !== undefined)),
254
+ })
255
+ .strict())
256
+ .max(PRODUCT_SCOPED_WRITE_CELLS_MAX),
257
+ })
258
+ .strict()
259
+ .superRefine((input, ctx) => {
260
+ const seen = new Set();
261
+ input.cells.forEach((cell, index) => {
262
+ if (!scopeFromRequest(cell.scope).ok) {
263
+ ctx.addIssue({ code: 'custom', path: ['cells', index, 'scope'], message: 'A language needs a channel.' });
264
+ }
265
+ const key = `${cell.field}@${cell.scope.channelId ?? ''}/${cell.scope.languageCode?.toLowerCase() ?? ''}`;
266
+ if (seen.has(key))
267
+ ctx.addIssue({ code: 'custom', path: ['cells', index], message: 'Duplicate (field, scope) cell.' });
268
+ seen.add(key);
269
+ });
270
+ })
271
+ .transform((input) => ({
272
+ cells: input.cells.map((cell) => {
273
+ const resolved = scopeFromRequest(cell.scope);
274
+ return {
275
+ scope: resolved.ok ? resolved.scope : { level: 'global' },
276
+ field: cell.field,
277
+ op: toScopedWriteOp(cell.value),
278
+ };
279
+ }),
280
+ }));
281
+ /**
282
+ * R13a (plan decision Q6) — whether an integration (a PIM connector, the products import) may
283
+ * write `field` at all: `name`, `description`, `attribute:<key>`, `gallery:<id>:altText`,
284
+ * `attachment:<id>:name|description`, `packagingUnit:<id>:name`, `urlKey`, `status`, `window`.
285
+ * Every other family — `audience`, `product.*`, `seo:*`, `galleryRole:*`, `*:hidden`,
286
+ * `minOrderQuantity`, `returnable` — is `not_supported`. Pure; the port applies it per cell.
287
+ */
288
+ export function integrationWritableField(field) {
289
+ return /^(name|description|urlKey|status|window|attribute:[a-z0-9_]{1,64}|gallery:[0-9a-f-]{36}:altText|attachment:[0-9a-f-]{36}:(name|description)|packagingUnit:[0-9a-f-]{36}:name)$/.test(field);
290
+ }
197
291
  // --- 4. Admin shapes (admin-scopes-api.md) -----------------------------------------
198
292
  /**
199
293
  * A channel content language as a request names it: the BCP-47 shape the dictionary
@@ -253,6 +347,8 @@ export const productScopesSchema = z.object({
253
347
  nonMemberOrganizationIds: z.array(uuidSchema),
254
348
  })
255
349
  .nullable(),
350
+ /** Feature 174 — whether the channel overrides the minimum; then `minOrderQuantity` `null` = none here. */
351
+ minOrderQuantityOverridden: z.boolean(),
256
352
  minOrderQuantity: z.number().int().nullable(),
257
353
  returnable: z.boolean().nullable(),
258
354
  languageStatuses: z.array(z.object({ languageCode: z.string(), status: productScopeStatusSchema, orphaned: z.boolean() })),
@@ -269,25 +365,26 @@ export const productScopesSchema = z.object({
269
365
  });
270
366
  export const productScopesResponseSchema = z.object({ data: productScopesSchema });
271
367
  /**
272
- * §2 — `PATCH /api/v1/admin/catalog/products/:id/scopes`. An absent key leaves the
273
- * value untouched; `null` = use inherited (deletes the override, FR-012). A window
274
- * whose `from` is not before its `until` passes the schema and is refused by the
275
- * service with `VALIDATION_FAILED`, `details.field = 'window'`.
368
+ * §2 — `PATCH /api/v1/admin/catalog/products/:id/scopes`, in the one write encoding
369
+ * (feature 174, `contracts/write-encoding.md` §5, FR-116): absent or `""` = no change,
370
+ * `{ inherit: true }` = use inherited (deletes the override), `null` = the empty override
371
+ * where the field takes one — `minOrderQuantity: null` = no minimum in this channel,
372
+ * `window: null` = an open window override; `status`, `audience` and `returnable` refuse
373
+ * `null` (`SCOPED_VALUE_INVALID`, `not_emptyable`, from the service). A window whose
374
+ * `from` is not before its `until` is refused with `VALIDATION_FAILED`,
375
+ * `details.field = 'window'`.
276
376
  */
277
377
  export const patchProductScopesRequestSchema = z.object({
278
378
  channels: z
279
379
  .array(z.object({
280
380
  channelId: uuidSchema,
281
- status: productScopeStatusSchema.nullable().optional(),
282
- window: z
283
- .object({ from: isoDateTimeSchema.nullable(), until: isoDateTimeSchema.nullable() })
284
- .nullable()
285
- .optional(),
286
- audience: audienceRuleSchema.nullable().optional(),
287
- minOrderQuantity: orderMinimumSchema.nullable().optional(),
288
- returnable: z.boolean().nullable().optional(),
381
+ status: scopedWrite(productScopeStatusSchema),
382
+ window: scopedWrite(z.object({ from: isoDateTimeSchema.nullable(), until: isoDateTimeSchema.nullable() }).strict()),
383
+ audience: scopedWrite(audienceRuleSchema.strict()),
384
+ minOrderQuantity: scopedWrite(orderMinimumSchema),
385
+ returnable: scopedWrite(z.boolean()),
289
386
  languageStatuses: z
290
- .array(z.object({ languageCode: languageCodeSchema, status: productScopeStatusSchema.nullable() }))
387
+ .array(z.object({ languageCode: languageCodeSchema, status: scopedWrite(productScopeStatusSchema) }))
291
388
  .max(SCOPE_LANGUAGE_STATUSES_MAX)
292
389
  .optional(),
293
390
  }))
@@ -320,7 +417,8 @@ export const scopeInvalidDetailsSchema = z.object({
320
417
  export const scopeIncompleteDetailsSchema = z.object({
321
418
  pairs: z.array(z.object({ channelId: uuidSchema, languageCode: z.string(), missing: z.array(scopeMissingValueSchema) })),
322
419
  });
323
- export const scopeLevelSchema = z.enum(['channel_language', 'channel', 'language']);
420
+ /** Feature 174 (FR-010) — there is no Language scope: an override sits at C or C×L. */
421
+ export const scopeLevelSchema = z.enum(['channel_language', 'channel']);
324
422
  /** §3 — `GET /api/v1/admin/catalog/products/:id/scope-overview`. */
325
423
  export const scopeOverviewResponseSchema = z.object({
326
424
  data: z.object({
@@ -344,7 +442,6 @@ export const scopeOverviewResponseSchema = z.object({
344
442
  missing: z.array(scopeMissingValueSchema).optional(),
345
443
  })),
346
444
  channelRows: z.array(z.object({ channelId: uuidSchema, overriddenFields: z.array(z.string()) })),
347
- languageColumns: z.array(z.object({ languageCode: z.string(), overriddenFields: z.array(z.string()) })),
348
445
  orphans: z.array(z.object({
349
446
  field: z.string(),
350
447
  channelId: uuidSchema.nullable(),