@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
@@ -0,0 +1,135 @@
1
+ /**
2
+ * Feature 174 (`specs/174-product-editor-scope-switcher/contracts/write-encoding.md`; research R3;
3
+ * FR-110…FR-118) — the **one** write encoding of scoped product values, for JSON (the admin API,
4
+ * the connector port) and CSV (import and export).
5
+ *
6
+ * | Intent | JSON | CSV |
7
+ * | --- | --- | --- |
8
+ * | No change | absent, or `""` | empty cell |
9
+ * | Empty override (at Global: no value) | `null` | `NULL` |
10
+ * | Remove the own value, inherit | `{ "inherit": true }` | `INHERIT` |
11
+ * | A value | the value | the text (`\` escapes a token) |
12
+ *
13
+ * This differs from JSON Merge Patch (`null` = remove the member) and from Magento's
14
+ * `__EMPTY__VALUE__` (FR-115). Applies to scoped product values only (FR-117). Adding a token
15
+ * later is additive; changing a meaning is a breaking, versioned change (FR-111).
16
+ */
17
+ import { z } from 'zod';
18
+ export const INHERIT_TOKEN = 'INHERIT';
19
+ export const EMPTY_TOKEN = 'NULL';
20
+ /** The JSON marker that removes the own value. Strict: `{ inherit: true }` and nothing else. */
21
+ export const inheritMarkerSchema = z.object({ inherit: z.literal(true) }).strict();
22
+ /**
23
+ * The Zod schema of one scoped write: `null | { inherit: true } | valueSchema`, optional, with
24
+ * `""` read as absent (no change). `null` and the marker are tried before the value schema, so a
25
+ * permissive value schema never swallows them.
26
+ */
27
+ export function scopedWrite(valueSchema) {
28
+ return z.preprocess((raw) => (raw === '' ? undefined : raw), z
29
+ .union([z.null(), inheritMarkerSchema, valueSchema])
30
+ .optional()
31
+ // C1 review — an object naming `inherit` that is not exactly `{ inherit: true }` is a
32
+ // malformed marker, refused even when a permissive value schema would accept it as a value.
33
+ .refine((value) => !looksLikeMalformedMarker(value), { message: 'Malformed inherit marker.' }));
34
+ }
35
+ function looksLikeMalformedMarker(raw) {
36
+ return (typeof raw === 'object' &&
37
+ raw !== null &&
38
+ !Array.isArray(raw) &&
39
+ Object.prototype.hasOwnProperty.call(raw, 'inherit') &&
40
+ !isInheritMarker(raw));
41
+ }
42
+ function isInheritMarker(raw) {
43
+ return (typeof raw === 'object' &&
44
+ raw !== null &&
45
+ !Array.isArray(raw) &&
46
+ Object.keys(raw).length === 1 &&
47
+ raw.inherit === true);
48
+ }
49
+ /** The op a parsed {@link scopedWrite} value means; `undefined` = no change. */
50
+ export function toScopedWriteOp(raw) {
51
+ if (raw === undefined)
52
+ return undefined;
53
+ if (raw === null)
54
+ return { op: 'empty' };
55
+ if (isInheritMarker(raw))
56
+ return { op: 'inherit' };
57
+ return { op: 'set', value: raw };
58
+ }
59
+ /** The wire form of an op — the inverse of {@link toScopedWriteOp}. */
60
+ export function fromScopedWriteOp(op) {
61
+ if (op.op === 'empty')
62
+ return null;
63
+ if (op.op === 'inherit')
64
+ return { inherit: true };
65
+ return op.value;
66
+ }
67
+ const TOKEN_ESCAPED = /^\\+(NULL|INHERIT)$/;
68
+ const TOKEN_TO_ESCAPE = /^\\*(NULL|INHERIT)$/;
69
+ const FORMULA_LEAD = /^[=+\-@\t\r]/;
70
+ /**
71
+ * Decode one CSV cell (§3, §3a). Tokens are matched on the raw, whole cell; then, in a text
72
+ * column, one leading `'` is dropped; then a cell of backslashes before a token loses one
73
+ * backslash. Anything else is text, verbatim.
74
+ */
75
+ export function decodeCsvScopedCell(cell, options = { column: 'text' }) {
76
+ if (cell === '')
77
+ return { kind: 'no_change' };
78
+ if (cell === EMPTY_TOKEN)
79
+ return { kind: 'empty' };
80
+ if (cell === INHERIT_TOKEN)
81
+ return { kind: 'inherit' };
82
+ let text = cell;
83
+ if (options.column === 'text' && text.startsWith("'"))
84
+ text = text.slice(1);
85
+ if (TOKEN_ESCAPED.test(text))
86
+ text = text.slice(1);
87
+ return { kind: 'text', text };
88
+ }
89
+ /**
90
+ * Encode one CSV cell — the inverse of {@link decodeCsvScopedCell}: `decode(encode(x)) = x` for
91
+ * every non-empty text. An empty text has no CSV form (an empty cell means no change); write the
92
+ * empty override as `{ kind: 'empty' }` instead.
93
+ */
94
+ export function encodeCsvScopedCell(cell, options = { column: 'text' }) {
95
+ if (cell.kind === 'empty')
96
+ return EMPTY_TOKEN;
97
+ if (cell.kind === 'inherit')
98
+ return INHERIT_TOKEN;
99
+ const { text } = cell;
100
+ if (text === '')
101
+ throw new Error('An empty text has no CSV form: an empty cell means "no change".');
102
+ if (options.column === 'text' && (text.startsWith("'") || FORMULA_LEAD.test(text)))
103
+ return `'${text}`;
104
+ if (TOKEN_TO_ESCAPE.test(text))
105
+ return `\\${text}`;
106
+ return text;
107
+ }
108
+ /**
109
+ * The one place an op is refused for what it means (FR-062, FR-113): `inherit` at Global for
110
+ * every field; `empty` on a required field (name, URL key, required attribute), then on a field
111
+ * that takes no empty override (single selects, booleans). Value shapes and lengths are the
112
+ * value schema's; the scope set is the caller's `FIELD_NOT_AT_SCOPE` check.
113
+ */
114
+ export function validateScopedWrite(field, op, level) {
115
+ if (op.op === 'inherit')
116
+ return level === 'G' ? 'inherit_at_global' : null;
117
+ if (op.op === 'empty') {
118
+ if (field.required)
119
+ return 'required_empty';
120
+ if (!field.emptyable)
121
+ return 'not_emptyable';
122
+ }
123
+ return null;
124
+ }
125
+ /**
126
+ * `products.scope_version` as the client echoes it: digits within the bigint range, so an
127
+ * over-long token is a 400 and never a database overflow (C2/C3 security review). It lives in this leaf
128
+ * file so `catalog.ts` (the product `PATCH`) and `product-scoped-values.ts` both import it
129
+ * without an import cycle.
130
+ */
131
+ export const scopeVersionTokenSchema = z
132
+ .string()
133
+ .regex(/^\d{1,19}$/)
134
+ .refine((value) => BigInt(value) <= 9223372036854775807n, 'out of range');
135
+ //# sourceMappingURL=scoped-write-encoding.js.map
package/dist/search.d.ts CHANGED
@@ -71,19 +71,19 @@ export declare const searchSuggestItemSchema: z.ZodObject<{
71
71
  }, z.core.$strip>>>;
72
72
  priceVariesByVariant: z.ZodOptional<z.ZodBoolean>;
73
73
  stockIndicator: z.ZodNullable<z.ZodEnum<{
74
- available: "available";
75
74
  out_of_stock: "out_of_stock";
75
+ available: "available";
76
76
  to_order: "to_order";
77
77
  }>>;
78
78
  stockLevel: z.ZodNullable<z.ZodNumber>;
79
79
  priceUnavailable: z.ZodOptional<z.ZodBoolean>;
80
80
  availability: z.ZodOptional<z.ZodObject<{
81
81
  band: z.ZodEnum<{
82
- medium: "medium";
83
- available: "available";
84
- out_of_stock: "out_of_stock";
85
82
  high: "high";
83
+ medium: "medium";
86
84
  low: "low";
85
+ out_of_stock: "out_of_stock";
86
+ available: "available";
87
87
  }>;
88
88
  inStock: z.ZodBoolean;
89
89
  }, z.core.$strip>>;
@@ -98,16 +98,17 @@ export declare const searchSuggestItemSchema: z.ZodObject<{
98
98
  currency: z.ZodString;
99
99
  }, z.core.$strip>>;
100
100
  displayMode: z.ZodEnum<{
101
- none: "none";
102
- both: "both";
103
101
  gross_only: "gross_only";
104
102
  net_only: "net_only";
103
+ both: "both";
104
+ none: "none";
105
105
  }>;
106
106
  listPrice: z.ZodOptional<z.ZodObject<{
107
107
  amount: z.ZodString;
108
108
  currency: z.ZodString;
109
109
  }, z.core.$strip>>;
110
110
  }, z.core.$strip>>>;
111
+ vatRate: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
111
112
  basePrice: z.ZodOptional<z.ZodNullable<z.ZodObject<{
112
113
  amount: z.ZodString;
113
114
  currency: z.ZodString;
@@ -117,10 +118,10 @@ export declare const searchSuggestItemSchema: z.ZodObject<{
117
118
  currency: z.ZodString;
118
119
  }, z.core.$strip>>>;
119
120
  priceDisplayMode: z.ZodOptional<z.ZodEnum<{
120
- none: "none";
121
- both: "both";
122
121
  gross_only: "gross_only";
123
122
  net_only: "net_only";
123
+ both: "both";
124
+ none: "none";
124
125
  }>>;
125
126
  listPrice: z.ZodOptional<z.ZodObject<{
126
127
  amount: z.ZodString;
@@ -154,19 +155,19 @@ export declare const SearchSuggestResponseSchema: z.ZodObject<{
154
155
  }, z.core.$strip>>>;
155
156
  priceVariesByVariant: z.ZodOptional<z.ZodBoolean>;
156
157
  stockIndicator: z.ZodNullable<z.ZodEnum<{
157
- available: "available";
158
158
  out_of_stock: "out_of_stock";
159
+ available: "available";
159
160
  to_order: "to_order";
160
161
  }>>;
161
162
  stockLevel: z.ZodNullable<z.ZodNumber>;
162
163
  priceUnavailable: z.ZodOptional<z.ZodBoolean>;
163
164
  availability: z.ZodOptional<z.ZodObject<{
164
165
  band: z.ZodEnum<{
165
- medium: "medium";
166
- available: "available";
167
- out_of_stock: "out_of_stock";
168
166
  high: "high";
167
+ medium: "medium";
169
168
  low: "low";
169
+ out_of_stock: "out_of_stock";
170
+ available: "available";
170
171
  }>;
171
172
  inStock: z.ZodBoolean;
172
173
  }, z.core.$strip>>;
@@ -181,16 +182,17 @@ export declare const SearchSuggestResponseSchema: z.ZodObject<{
181
182
  currency: z.ZodString;
182
183
  }, z.core.$strip>>;
183
184
  displayMode: z.ZodEnum<{
184
- none: "none";
185
- both: "both";
186
185
  gross_only: "gross_only";
187
186
  net_only: "net_only";
187
+ both: "both";
188
+ none: "none";
188
189
  }>;
189
190
  listPrice: z.ZodOptional<z.ZodObject<{
190
191
  amount: z.ZodString;
191
192
  currency: z.ZodString;
192
193
  }, z.core.$strip>>;
193
194
  }, z.core.$strip>>>;
195
+ vatRate: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
194
196
  basePrice: z.ZodOptional<z.ZodNullable<z.ZodObject<{
195
197
  amount: z.ZodString;
196
198
  currency: z.ZodString;
@@ -200,10 +202,10 @@ export declare const SearchSuggestResponseSchema: z.ZodObject<{
200
202
  currency: z.ZodString;
201
203
  }, z.core.$strip>>>;
202
204
  priceDisplayMode: z.ZodOptional<z.ZodEnum<{
203
- none: "none";
204
- both: "both";
205
205
  gross_only: "gross_only";
206
206
  net_only: "net_only";
207
+ both: "both";
208
+ none: "none";
207
209
  }>>;
208
210
  listPrice: z.ZodOptional<z.ZodObject<{
209
211
  amount: z.ZodString;
package/dist/seo.d.ts CHANGED
@@ -1,4 +1,7 @@
1
1
  import { z } from 'zod';
2
+ import type { ScopeRef, ScopedSource, SeoProductMetaField } from './product-scope-model.js';
3
+ import type { ScopedFieldView } from './product-scoped-values.js';
4
+ import type { ScopedWriteOp } from './scoped-write-encoding.js';
2
5
  /**
3
6
  * SEO meta + sitemap contracts (T235 / FR-101, FR-102).
4
7
  *
@@ -6,8 +9,8 @@ import { z } from 'zod';
6
9
  * renders public pages for can carry meta overrides.
7
10
  */
8
11
  export declare const seoEntityTypeSchema: z.ZodEnum<{
9
- product: "product";
10
12
  category: "category";
13
+ product: "product";
11
14
  cms_page: "cms_page";
12
15
  }>;
13
16
  export type SeoEntityType = z.infer<typeof seoEntityTypeSchema>;
@@ -29,8 +32,8 @@ export type ResolvedMeta = z.infer<typeof resolvedMetaSchema>;
29
32
  export declare const seoMetaOverrideSchema: z.ZodObject<{
30
33
  id: z.ZodString;
31
34
  entityType: z.ZodEnum<{
32
- product: "product";
33
35
  category: "category";
36
+ product: "product";
34
37
  cms_page: "cms_page";
35
38
  }>;
36
39
  entityId: z.ZodString;
@@ -383,8 +386,8 @@ export declare const adminCrawlerFilePreviewSchema: z.ZodObject<{
383
386
  savedExtra: z.ZodString;
384
387
  savedExtraSource: z.ZodEnum<{
385
388
  default: "default";
386
- channel: "channel";
387
389
  global: "global";
390
+ channel: "channel";
388
391
  }>;
389
392
  channelsWithOwnValue: z.ZodArray<z.ZodString>;
390
393
  policy: z.ZodObject<{
@@ -419,8 +422,8 @@ export declare const adminCrawlerFilePreviewResponseSchema: z.ZodObject<{
419
422
  savedExtra: z.ZodString;
420
423
  savedExtraSource: z.ZodEnum<{
421
424
  default: "default";
422
- channel: "channel";
423
425
  global: "global";
426
+ channel: "channel";
424
427
  }>;
425
428
  channelsWithOwnValue: z.ZodArray<z.ZodString>;
426
429
  policy: z.ZodObject<{
@@ -439,27 +442,13 @@ export declare const adminCrawlerFilePreviewResponseSchema: z.ZodObject<{
439
442
  }, z.core.$strip>;
440
443
  export type AdminCrawlerFilePreviewResponse = z.infer<typeof adminCrawlerFilePreviewResponseSchema>;
441
444
  /**
442
- * Container name: `seoMetaWritePort`. Owner: `seo`.
443
- *
444
- * Narrow write surface for PIM importers (feature 089 / FR-029): upsert product
445
- * meta overrides by locale — the language rows. Feature 163 added channel and
446
- * channel × language rows; this port writes none of them, so an import never
447
- * touches an operator's channel override (FR-091).
448
- *
449
- * **Owner off:** resolving this port throws `ModuleDisabledError` (503).
445
+ * Feature 174 (`specs/174-product-editor-scope-switcher/contracts/seo-ports.md`; research R9,
446
+ * R21) — product metadata at the three product scopes: Global (no channel, no locale),
447
+ * Channel (channel, no locale) and Channel × language. There is no locale-only product row any
448
+ * more (FR-010). `SeoProductMetaField` is declared once, in `product-scope-model.ts`.
450
449
  */
451
- export interface SeoMetaWritePort {
452
- upsertProductMeta(input: {
453
- productId: string;
454
- locale: string;
455
- title?: string | null;
456
- description?: string | null;
457
- }): Promise<void>;
458
- }
459
- /** The product-page metadata fields an SEO override can set (feature 163, FR-075). */
460
- export type SeoProductMetaField = 'title' | 'description' | 'ogTitle' | 'ogDescription' | 'ogImageUrl';
461
450
  /** Where an effective metadata value came from; `derived` = the product page's own fallback. */
462
- export type SeoProductMetaSource = 'channel_language' | 'channel' | 'language' | 'derived';
451
+ export type SeoProductMetaSource = ScopedSource | 'derived';
463
452
  export interface SeoProductMetaValues {
464
453
  title: string;
465
454
  description: string;
@@ -468,16 +457,29 @@ export interface SeoProductMetaValues {
468
457
  ogImageUrl: string | null;
469
458
  }
470
459
  /**
471
- * Container name: `seoProductMetaPort`. Owner: `seo` (feature 163, R13).
460
+ * `GET /api/v1/admin/seo/meta/product/:entityId` query — `catalog:read` (FR-093). The scope
461
+ * request every scoped read takes (`scopeRequestSchema`, resolved with `scopeFromRequest`): no
462
+ * locale-only scope.
463
+ */
464
+ export declare const seoProductMetaQuerySchema: z.ZodObject<{
465
+ channelId: z.ZodOptional<z.ZodString>;
466
+ languageCode: z.ZodOptional<z.ZodString>;
467
+ }, z.core.$strict>;
468
+ export type SeoProductMetaQuery = z.infer<typeof seoProductMetaQuerySchema>;
469
+ /**
470
+ * Container name: `seoProductMetaPort`. Owner: `seo` (feature 163 R13, rewritten by 174).
472
471
  *
473
- * Product metadata per sales channel × language. Each field resolves channel ×
474
- * language → channel → language → the caller's derived fallback (FR-075).
475
- * `catalog` declares the edge as degrades-without and probes `seo`'s presence before
476
- * resolving it.
472
+ * `catalog` declares the edge as degrades-without and probes `seo`'s presence before resolving
473
+ * it; with `seo` off the product editor shows no SEO section (FR-092).
477
474
  *
478
475
  * **Owner off:** resolving this port throws `ModuleDisabledError` (503).
479
476
  */
480
477
  export interface SeoProductMetaPort {
478
+ /**
479
+ * Storefront: effective values at (C, L) along C×L → C → G, then the caller's derived
480
+ * fallback. A field whose effective source is an empty override (`set_empty`) also takes the
481
+ * derived value (owner round 6).
482
+ */
481
483
  resolveForProduct(input: {
482
484
  productId: string;
483
485
  channelId: string;
@@ -486,11 +488,62 @@ export interface SeoProductMetaPort {
486
488
  }): Promise<SeoProductMetaValues & {
487
489
  sources: Record<SeoProductMetaField, SeoProductMetaSource>;
488
490
  }>;
489
- /** Every scope holding an override for the product, for the scope overview. */
491
+ /** Admin: each field's view at one scope; an invalid scope → `422 SCOPE_INVALID`, never an empty view. */
492
+ readScoped(productId: string, scope: ScopeRef): Promise<Record<SeoProductMetaField, ScopedFieldView<string>>>;
493
+ /** Overview: every scope holding a product row. */
490
494
  listScopesForProduct(productId: string): Promise<Array<{
491
495
  channelId: string | null;
492
- locale: string | null;
496
+ languageCode: string | null;
493
497
  fields: SeoProductMetaField[];
494
498
  }>>;
495
499
  }
500
+ /** A field's own value at a scope for an audit before-state: a text, an empty override, or none. */
501
+ export type SeoProductMetaOwnValue = {
502
+ own: string | {
503
+ empty: true;
504
+ };
505
+ } | {
506
+ inherited: true;
507
+ };
508
+ /**
509
+ * Container name: `seoProductMetaWritePort`. Owner: `seo` (feature 174, FR-091), registered by T121.
510
+ *
511
+ * Writes product metadata **on the caller's EntityManager**: no fork, no flush, no audit entry,
512
+ * no event — `catalog`'s save Command commits or rolls the rows back with its own. `catalog`
513
+ * resolves it with `lazyPort` inside the Command only when the save changes SEO, and declares the
514
+ * edge `refuses-without`.
515
+ *
516
+ * Row mapping: G = (no channel, no locale); C = (channel, no locale); C×L = (channel, locale).
517
+ * `set` → the column holds the value; `empty` → `''`; `inherit` → `NULL`, and a row whose every
518
+ * column is `NULL` is deleted. Refuses (`422 SCOPED_VALUE_INVALID`) `inherit` at Global, an
519
+ * over-long value (title 160, description 400, OG title 160, OG description 400, image URL 2048)
520
+ * and an image URL that is not `http:` / `https:` or carries credentials (`unsafe_url`).
521
+ *
522
+ * **No scope check:** it writes any scope it is given — membership and the channel's languages are
523
+ * the caller's to check (`catalog`'s save resolves the scope first; a duplicate writes the copy's
524
+ * scopes in the same transaction).
525
+ *
526
+ * **Owner off:** resolving this port throws `ModuleDisabledError` (503).
527
+ */
528
+ export interface SeoProductMetaWritePort<EM = unknown> {
529
+ /**
530
+ * The current own values of the named fields at `scope`, for the caller's audit before-state:
531
+ * one entry per named field — `{ own: text }`, `{ own: { empty: true } }` for an empty override,
532
+ * `{ inherited: true }` for no own value there; `own` is never `null`
533
+ * (`contracts/seo-ports.md` §2).
534
+ */
535
+ readWithin(em: EM, input: {
536
+ productId: string;
537
+ scope: ScopeRef;
538
+ fields: SeoProductMetaField[];
539
+ }): Promise<Partial<Record<SeoProductMetaField, SeoProductMetaOwnValue>>>;
540
+ applyWithin(em: EM, input: {
541
+ productId: string;
542
+ scope: ScopeRef;
543
+ changes: Partial<Record<SeoProductMetaField, ScopedWriteOp<string>>>;
544
+ }): Promise<{
545
+ before: Record<string, unknown>;
546
+ after: Record<string, unknown>;
547
+ }>;
548
+ }
496
549
  //# sourceMappingURL=seo.d.ts.map
package/dist/seo.js CHANGED
@@ -1,6 +1,7 @@
1
1
  import { z } from 'zod';
2
2
  import { isoDateTimeSchema, uuidSchema } from './common.js';
3
3
  import { SalesChannelCodeSchema } from './sales-channels.js';
4
+ import { scopeRequestSchema } from './product-scopes.js';
4
5
  /**
5
6
  * SEO meta + sitemap contracts (T235 / FR-101, FR-102).
6
7
  *
@@ -56,7 +57,7 @@ export const seoMetaScopeQuerySchema = z.object({
56
57
  export const ogImageUrlSchema = z
57
58
  .string()
58
59
  .max(2048)
59
- .refine((value) => /^https?:\/\/[^\s/?#\\]+[^\s\\]*$/i.test(value) || /^\/(?![/\\])[^\s\\]*$/.test(value), { message: 'an http(s) URL or a path starting with a single /' });
60
+ .refine((value) => /^https?:\/\/[^\s/?#\\@]+(?:[/?#][^\s\\]*)?$/i.test(value) || /^\/(?![/\\])[^\s\\]*$/.test(value), { message: 'an http(s) URL or a path starting with a single /' });
60
61
  export const upsertSeoMetaOverrideRequestSchema = z.object({
61
62
  /** Optional since feature 163 — see {@link seoMetaScopeQuerySchema} for the addressing rule. */
62
63
  locale: z.string().min(2).max(10).optional(),
@@ -390,4 +391,10 @@ export const adminCrawlerFilePreviewSchema = z
390
391
  export const adminCrawlerFilePreviewResponseSchema = z.object({
391
392
  data: adminCrawlerFilePreviewSchema,
392
393
  });
394
+ /**
395
+ * `GET /api/v1/admin/seo/meta/product/:entityId` query — `catalog:read` (FR-093). The scope
396
+ * request every scoped read takes (`scopeRequestSchema`, resolved with `scopeFromRequest`): no
397
+ * locale-only scope.
398
+ */
399
+ export const seoProductMetaQuerySchema = scopeRequestSchema;
393
400
  //# sourceMappingURL=seo.js.map