@epistola.app/epistola-client 2.0.0-alpha.3 → 2.0.0-alpha.4

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 (496) hide show
  1. package/CHANGELOG.md +4 -0
  2. package/README.md +13 -2
  3. package/dist/error/problemDetailException.d.ts +34 -1
  4. package/dist/error/problemDetailException.d.ts.map +1 -1
  5. package/dist/error/problemDetailException.js +52 -0
  6. package/dist/error/problemDetailException.js.map +1 -1
  7. package/dist/generated/api/apis/AttributesApi.d.ts +4 -25
  8. package/dist/generated/api/apis/AttributesApi.d.ts.map +1 -1
  9. package/dist/generated/api/apis/AttributesApi.js +4 -17
  10. package/dist/generated/api/apis/AttributesApi.js.map +1 -1
  11. package/dist/generated/api/apis/CatalogsApi.d.ts +2 -23
  12. package/dist/generated/api/apis/CatalogsApi.d.ts.map +1 -1
  13. package/dist/generated/api/apis/CatalogsApi.js +3 -15
  14. package/dist/generated/api/apis/CatalogsApi.js.map +1 -1
  15. package/dist/generated/api/apis/CodeListsApi.d.ts +12 -25
  16. package/dist/generated/api/apis/CodeListsApi.d.ts.map +1 -1
  17. package/dist/generated/api/apis/CodeListsApi.js +10 -17
  18. package/dist/generated/api/apis/CodeListsApi.js.map +1 -1
  19. package/dist/generated/api/apis/ConsumersApi.d.ts +2 -2
  20. package/dist/generated/api/apis/ConsumersApi.js +2 -2
  21. package/dist/generated/api/apis/EnvironmentsApi.d.ts +4 -25
  22. package/dist/generated/api/apis/EnvironmentsApi.d.ts.map +1 -1
  23. package/dist/generated/api/apis/EnvironmentsApi.js +4 -17
  24. package/dist/generated/api/apis/EnvironmentsApi.js.map +1 -1
  25. package/dist/generated/api/apis/FontsApi.d.ts +2 -23
  26. package/dist/generated/api/apis/FontsApi.d.ts.map +1 -1
  27. package/dist/generated/api/apis/FontsApi.js +2 -15
  28. package/dist/generated/api/apis/FontsApi.js.map +1 -1
  29. package/dist/generated/api/apis/GenerationApi.d.ts +45 -7
  30. package/dist/generated/api/apis/GenerationApi.d.ts.map +1 -1
  31. package/dist/generated/api/apis/GenerationApi.js +67 -6
  32. package/dist/generated/api/apis/GenerationApi.js.map +1 -1
  33. package/dist/generated/api/apis/ImagesApi.d.ts +3 -3
  34. package/dist/generated/api/apis/ImagesApi.d.ts.map +1 -1
  35. package/dist/generated/api/apis/ImagesApi.js +4 -4
  36. package/dist/generated/api/apis/ImagesApi.js.map +1 -1
  37. package/dist/generated/api/apis/StencilsApi.d.ts +2 -23
  38. package/dist/generated/api/apis/StencilsApi.d.ts.map +1 -1
  39. package/dist/generated/api/apis/StencilsApi.js +2 -15
  40. package/dist/generated/api/apis/StencilsApi.js.map +1 -1
  41. package/dist/generated/api/apis/SystemApi.d.ts +2 -2
  42. package/dist/generated/api/apis/SystemApi.js +2 -2
  43. package/dist/generated/api/apis/TemplatesApi.d.ts +17 -10
  44. package/dist/generated/api/apis/TemplatesApi.d.ts.map +1 -1
  45. package/dist/generated/api/apis/TemplatesApi.js +14 -6
  46. package/dist/generated/api/apis/TemplatesApi.js.map +1 -1
  47. package/dist/generated/api/apis/TenantsApi.d.ts +6 -27
  48. package/dist/generated/api/apis/TenantsApi.d.ts.map +1 -1
  49. package/dist/generated/api/apis/TenantsApi.js +6 -19
  50. package/dist/generated/api/apis/TenantsApi.js.map +1 -1
  51. package/dist/generated/api/apis/ThemesApi.d.ts +2 -23
  52. package/dist/generated/api/apis/ThemesApi.d.ts.map +1 -1
  53. package/dist/generated/api/apis/ThemesApi.js +2 -15
  54. package/dist/generated/api/apis/ThemesApi.js.map +1 -1
  55. package/dist/generated/api/apis/VariantsApi.d.ts +6 -27
  56. package/dist/generated/api/apis/VariantsApi.d.ts.map +1 -1
  57. package/dist/generated/api/apis/VariantsApi.js +6 -19
  58. package/dist/generated/api/apis/VariantsApi.js.map +1 -1
  59. package/dist/generated/api/models/AmbiguousVariantProblemDetail.d.ts +55 -0
  60. package/dist/generated/api/models/AmbiguousVariantProblemDetail.d.ts.map +1 -0
  61. package/dist/generated/api/models/AmbiguousVariantProblemDetail.js +61 -0
  62. package/dist/generated/api/models/AmbiguousVariantProblemDetail.js.map +1 -0
  63. package/dist/generated/api/models/ApproveConsumerRequest.d.ts +2 -2
  64. package/dist/generated/api/models/ApproveConsumerRequest.js +2 -2
  65. package/dist/generated/api/models/AttributeDto.d.ts +10 -9
  66. package/dist/generated/api/models/AttributeDto.d.ts.map +1 -1
  67. package/dist/generated/api/models/AttributeDto.js +8 -10
  68. package/dist/generated/api/models/AttributeDto.js.map +1 -1
  69. package/dist/generated/api/models/AttributeListResponse.d.ts +2 -2
  70. package/dist/generated/api/models/AttributeListResponse.js +2 -2
  71. package/dist/generated/api/models/AvailableCatalogReleases.d.ts +2 -2
  72. package/dist/generated/api/models/AvailableCatalogReleases.js +2 -2
  73. package/dist/generated/api/models/AvailableReleaseDependencyDto.d.ts +2 -2
  74. package/dist/generated/api/models/AvailableReleaseDependencyDto.js +2 -2
  75. package/dist/generated/api/models/AvailableReleaseDto.d.ts +2 -2
  76. package/dist/generated/api/models/AvailableReleaseDto.js +2 -2
  77. package/dist/generated/api/models/BatchGenerationItem.d.ts +3 -3
  78. package/dist/generated/api/models/BatchGenerationItem.js +2 -2
  79. package/dist/generated/api/models/BehindReleaseDto.d.ts +2 -2
  80. package/dist/generated/api/models/BehindReleaseDto.js +2 -2
  81. package/dist/generated/api/models/BlockStylePreset.d.ts +2 -2
  82. package/dist/generated/api/models/BlockStylePreset.js +2 -2
  83. package/dist/generated/api/models/CatalogChangesDto.d.ts +2 -2
  84. package/dist/generated/api/models/CatalogChangesDto.js +2 -2
  85. package/dist/generated/api/models/CatalogDependencyDto.d.ts +2 -2
  86. package/dist/generated/api/models/CatalogDependencyDto.js +2 -2
  87. package/dist/generated/api/models/CatalogDependencyListResponse.d.ts +2 -2
  88. package/dist/generated/api/models/CatalogDependencyListResponse.js +2 -2
  89. package/dist/generated/api/models/CatalogDependencyRequirement.d.ts +2 -2
  90. package/dist/generated/api/models/CatalogDependencyRequirement.js +2 -2
  91. package/dist/generated/api/models/CatalogDraftMergePreview.d.ts +2 -2
  92. package/dist/generated/api/models/CatalogDraftMergePreview.js +2 -2
  93. package/dist/generated/api/models/CatalogDraftMergeResource.d.ts +2 -2
  94. package/dist/generated/api/models/CatalogDraftMergeResource.js +2 -2
  95. package/dist/generated/api/models/CatalogDraftMergeSides.d.ts +2 -2
  96. package/dist/generated/api/models/CatalogDraftMergeSides.js +2 -2
  97. package/dist/generated/api/models/CatalogDraftReleasePreview.d.ts +2 -2
  98. package/dist/generated/api/models/CatalogDraftReleasePreview.js +2 -2
  99. package/dist/generated/api/models/CatalogDto.d.ts +2 -2
  100. package/dist/generated/api/models/CatalogDto.js +2 -2
  101. package/dist/generated/api/models/CatalogLevelChangeDto.d.ts +2 -2
  102. package/dist/generated/api/models/CatalogLevelChangeDto.js +2 -2
  103. package/dist/generated/api/models/CatalogListResponse.d.ts +2 -2
  104. package/dist/generated/api/models/CatalogListResponse.js +2 -2
  105. package/dist/generated/api/models/CatalogMergeBaseRef.d.ts +2 -2
  106. package/dist/generated/api/models/CatalogMergeBaseRef.js +2 -2
  107. package/dist/generated/api/models/CatalogMergeOutcome.d.ts +2 -2
  108. package/dist/generated/api/models/CatalogMergeOutcome.js +2 -2
  109. package/dist/generated/api/models/CatalogMergeSide.d.ts +2 -2
  110. package/dist/generated/api/models/CatalogMergeSide.js +2 -2
  111. package/dist/generated/api/models/CatalogPresetDto.d.ts +2 -2
  112. package/dist/generated/api/models/CatalogPresetDto.js +2 -2
  113. package/dist/generated/api/models/CatalogReadOnlyProblemDetail.d.ts +2 -2
  114. package/dist/generated/api/models/CatalogReadOnlyProblemDetail.js +2 -2
  115. package/dist/generated/api/models/CatalogReadOnlyReason.d.ts +2 -2
  116. package/dist/generated/api/models/CatalogReadOnlyReason.js +2 -2
  117. package/dist/generated/api/models/CatalogReleaseDto.d.ts +2 -2
  118. package/dist/generated/api/models/CatalogReleaseDto.js +2 -2
  119. package/dist/generated/api/models/CatalogReleaseListResponse.d.ts +2 -2
  120. package/dist/generated/api/models/CatalogReleaseListResponse.js +2 -2
  121. package/dist/generated/api/models/CatalogReleaseRefDto.d.ts +51 -0
  122. package/dist/generated/api/models/CatalogReleaseRefDto.d.ts.map +1 -0
  123. package/dist/generated/api/models/CatalogReleaseRefDto.js +61 -0
  124. package/dist/generated/api/models/CatalogReleaseRefDto.js.map +1 -0
  125. package/dist/generated/api/models/CatalogReleaseStatus.d.ts +2 -2
  126. package/dist/generated/api/models/CatalogReleaseStatus.js +2 -2
  127. package/dist/generated/api/models/CatalogRenderingDefaultsTooNewProblemDetail.d.ts +2 -2
  128. package/dist/generated/api/models/CatalogRenderingDefaultsTooNewProblemDetail.js +2 -2
  129. package/dist/generated/api/models/CatalogThemeReference.d.ts +2 -2
  130. package/dist/generated/api/models/CatalogThemeReference.js +2 -2
  131. package/dist/generated/api/models/CatalogVersionBehindProblemDetail.d.ts +55 -0
  132. package/dist/generated/api/models/CatalogVersionBehindProblemDetail.d.ts.map +1 -0
  133. package/dist/generated/api/models/CatalogVersionBehindProblemDetail.js +61 -0
  134. package/dist/generated/api/models/CatalogVersionBehindProblemDetail.js.map +1 -0
  135. package/dist/generated/api/models/{AttributeDtoCodeListBinding.js → CodeListAuthType.d.ts} +16 -38
  136. package/dist/generated/api/models/CodeListAuthType.d.ts.map +1 -0
  137. package/dist/generated/api/models/CodeListAuthType.js +45 -0
  138. package/dist/generated/api/models/CodeListAuthType.js.map +1 -0
  139. package/dist/generated/api/models/{UpdateAttributeRequestCodeListBinding.d.ts → CodeListBindingRef.d.ts} +15 -20
  140. package/dist/generated/api/models/CodeListBindingRef.d.ts.map +1 -0
  141. package/dist/generated/api/models/{UpdateAttributeRequestCodeListBinding.js → CodeListBindingRef.js} +11 -11
  142. package/dist/generated/api/models/CodeListBindingRef.js.map +1 -0
  143. package/dist/generated/api/models/CodeListDto.d.ts +8 -23
  144. package/dist/generated/api/models/CodeListDto.d.ts.map +1 -1
  145. package/dist/generated/api/models/CodeListDto.js +11 -24
  146. package/dist/generated/api/models/CodeListDto.js.map +1 -1
  147. package/dist/generated/api/models/CodeListEntriesResponse.d.ts +8 -3
  148. package/dist/generated/api/models/CodeListEntriesResponse.d.ts.map +1 -1
  149. package/dist/generated/api/models/CodeListEntriesResponse.js +7 -2
  150. package/dist/generated/api/models/CodeListEntriesResponse.js.map +1 -1
  151. package/dist/generated/api/models/CodeListEntryDto.d.ts +2 -2
  152. package/dist/generated/api/models/CodeListEntryDto.js +2 -2
  153. package/dist/generated/api/models/CodeListListResponse.d.ts +2 -2
  154. package/dist/generated/api/models/CodeListListResponse.js +2 -2
  155. package/dist/generated/api/models/CodeListSourceType.d.ts +26 -0
  156. package/dist/generated/api/models/CodeListSourceType.d.ts.map +1 -0
  157. package/dist/generated/api/models/CodeListSourceType.js +44 -0
  158. package/dist/generated/api/models/CodeListSourceType.js.map +1 -0
  159. package/dist/generated/api/models/CollectMeta.d.ts +2 -2
  160. package/dist/generated/api/models/CollectMeta.js +2 -2
  161. package/dist/generated/api/models/CollectRequest.d.ts +2 -2
  162. package/dist/generated/api/models/CollectRequest.js +2 -2
  163. package/dist/generated/api/models/ConsumerDto.d.ts +2 -2
  164. package/dist/generated/api/models/ConsumerDto.js +2 -2
  165. package/dist/generated/api/models/ConsumerListResponse.d.ts +2 -2
  166. package/dist/generated/api/models/ConsumerListResponse.js +2 -2
  167. package/dist/generated/api/models/ConsumerNodeDto.d.ts +2 -2
  168. package/dist/generated/api/models/ConsumerNodeDto.js +2 -2
  169. package/dist/generated/api/models/ConsumerPermissions.d.ts +2 -2
  170. package/dist/generated/api/models/ConsumerPermissions.js +2 -2
  171. package/dist/generated/api/models/CreateAttributeRequest.d.ts +8 -9
  172. package/dist/generated/api/models/CreateAttributeRequest.d.ts.map +1 -1
  173. package/dist/generated/api/models/CreateAttributeRequest.js +8 -10
  174. package/dist/generated/api/models/CreateAttributeRequest.js.map +1 -1
  175. package/dist/generated/api/models/CreateCatalogReleaseRequest.d.ts +2 -2
  176. package/dist/generated/api/models/CreateCatalogReleaseRequest.js +2 -2
  177. package/dist/generated/api/models/CreateCodeListRequest.d.ts +9 -25
  178. package/dist/generated/api/models/CreateCodeListRequest.d.ts.map +1 -1
  179. package/dist/generated/api/models/CreateCodeListRequest.js +11 -24
  180. package/dist/generated/api/models/CreateCodeListRequest.js.map +1 -1
  181. package/dist/generated/api/models/CreateEnvironmentRequest.d.ts +2 -2
  182. package/dist/generated/api/models/CreateEnvironmentRequest.js +2 -2
  183. package/dist/generated/api/models/CreateStencilRequest.d.ts +2 -2
  184. package/dist/generated/api/models/CreateStencilRequest.js +2 -2
  185. package/dist/generated/api/models/CreateTemplateRequest.d.ts +12 -4
  186. package/dist/generated/api/models/CreateTemplateRequest.d.ts.map +1 -1
  187. package/dist/generated/api/models/CreateTemplateRequest.js +7 -4
  188. package/dist/generated/api/models/CreateTemplateRequest.js.map +1 -1
  189. package/dist/generated/api/models/CreateTenantRequest.d.ts +2 -2
  190. package/dist/generated/api/models/CreateTenantRequest.js +2 -2
  191. package/dist/generated/api/models/CreateThemeRequest.d.ts +2 -2
  192. package/dist/generated/api/models/CreateThemeRequest.js +2 -2
  193. package/dist/generated/api/models/CreateVariantRequest.d.ts +4 -4
  194. package/dist/generated/api/models/CreateVariantRequest.d.ts.map +1 -1
  195. package/dist/generated/api/models/CreateVariantRequest.js +5 -5
  196. package/dist/generated/api/models/CreateVariantRequest.js.map +1 -1
  197. package/dist/generated/api/models/DataExampleDto.d.ts +2 -2
  198. package/dist/generated/api/models/DataExampleDto.js +2 -2
  199. package/dist/generated/api/models/DataModelValidationError.d.ts +2 -2
  200. package/dist/generated/api/models/DataModelValidationError.js +2 -2
  201. package/dist/generated/api/models/DataModelValidationProblemDetail.d.ts +3 -3
  202. package/dist/generated/api/models/DataModelValidationProblemDetail.js +2 -2
  203. package/dist/generated/api/models/DeploymentDto.d.ts +2 -2
  204. package/dist/generated/api/models/DeploymentDto.js +2 -2
  205. package/dist/generated/api/models/DeploymentEventDto.d.ts +2 -2
  206. package/dist/generated/api/models/DeploymentEventDto.js +2 -2
  207. package/dist/generated/api/models/DeploymentHistoryResponse.d.ts +2 -2
  208. package/dist/generated/api/models/DeploymentHistoryResponse.js +2 -2
  209. package/dist/generated/api/models/DeploymentListResponse.d.ts +2 -2
  210. package/dist/generated/api/models/DeploymentListResponse.js +2 -2
  211. package/dist/generated/api/models/DocumentDto.d.ts +7 -5
  212. package/dist/generated/api/models/DocumentDto.d.ts.map +1 -1
  213. package/dist/generated/api/models/DocumentDto.js +7 -7
  214. package/dist/generated/api/models/DocumentDto.js.map +1 -1
  215. package/dist/generated/api/models/DocumentGenerationItemDto.d.ts +9 -20
  216. package/dist/generated/api/models/DocumentGenerationItemDto.d.ts.map +1 -1
  217. package/dist/generated/api/models/DocumentGenerationItemDto.js +10 -22
  218. package/dist/generated/api/models/DocumentGenerationItemDto.js.map +1 -1
  219. package/dist/generated/api/models/DocumentGenerationJobDto.d.ts +8 -25
  220. package/dist/generated/api/models/DocumentGenerationJobDto.d.ts.map +1 -1
  221. package/dist/generated/api/models/DocumentGenerationJobDto.js +11 -26
  222. package/dist/generated/api/models/DocumentGenerationJobDto.js.map +1 -1
  223. package/dist/generated/api/models/DocumentListResponse.d.ts +2 -2
  224. package/dist/generated/api/models/DocumentListResponse.js +2 -2
  225. package/dist/generated/api/models/EnvironmentDto.d.ts +2 -2
  226. package/dist/generated/api/models/EnvironmentDto.js +2 -2
  227. package/dist/generated/api/models/EnvironmentListResponse.d.ts +2 -2
  228. package/dist/generated/api/models/EnvironmentListResponse.js +2 -2
  229. package/dist/generated/api/models/FontDto.d.ts +2 -2
  230. package/dist/generated/api/models/FontDto.js +2 -2
  231. package/dist/generated/api/models/FontListResponse.d.ts +2 -2
  232. package/dist/generated/api/models/FontListResponse.js +2 -2
  233. package/dist/generated/api/models/FontVariantDto.d.ts +2 -2
  234. package/dist/generated/api/models/FontVariantDto.js +2 -2
  235. package/dist/generated/api/models/GenerateBatchRequest.d.ts +7 -3
  236. package/dist/generated/api/models/GenerateBatchRequest.d.ts.map +1 -1
  237. package/dist/generated/api/models/GenerateBatchRequest.js +2 -2
  238. package/dist/generated/api/models/GenerateBatchRequest.js.map +1 -1
  239. package/dist/generated/api/models/GenerateDocumentRequest.d.ts +3 -3
  240. package/dist/generated/api/models/GenerateDocumentRequest.js +2 -2
  241. package/dist/generated/api/models/{AttributeDtoCodeListBinding.d.ts → GenerationItemStatus.d.ts} +18 -29
  242. package/dist/generated/api/models/GenerationItemStatus.d.ts.map +1 -0
  243. package/dist/generated/api/models/GenerationItemStatus.js +49 -0
  244. package/dist/generated/api/models/GenerationItemStatus.js.map +1 -0
  245. package/dist/generated/api/models/GenerationJobItemListResponse.d.ts +37 -0
  246. package/dist/generated/api/models/GenerationJobItemListResponse.d.ts.map +1 -0
  247. package/dist/generated/api/models/{GenerationJobDetail.js → GenerationJobItemListResponse.js} +16 -16
  248. package/dist/generated/api/models/GenerationJobItemListResponse.js.map +1 -0
  249. package/dist/generated/api/models/GenerationJobListResponse.d.ts +2 -2
  250. package/dist/generated/api/models/GenerationJobListResponse.js +2 -2
  251. package/dist/generated/api/models/GenerationJobResponse.d.ts +6 -23
  252. package/dist/generated/api/models/GenerationJobResponse.d.ts.map +1 -1
  253. package/dist/generated/api/models/GenerationJobResponse.js +8 -23
  254. package/dist/generated/api/models/GenerationJobResponse.js.map +1 -1
  255. package/dist/generated/api/models/{CreateAttributeRequestCodeListBinding.d.ts → GenerationJobStatus.d.ts} +19 -28
  256. package/dist/generated/api/models/GenerationJobStatus.d.ts.map +1 -0
  257. package/dist/generated/api/models/GenerationJobStatus.js +50 -0
  258. package/dist/generated/api/models/GenerationJobStatus.js.map +1 -0
  259. package/dist/generated/api/models/{GenerationJobDetail.d.ts → GenerationJobType.d.ts} +14 -25
  260. package/dist/generated/api/models/GenerationJobType.d.ts.map +1 -0
  261. package/dist/generated/api/models/{CreateAttributeRequestCodeListBinding.js → GenerationJobType.js} +26 -29
  262. package/dist/generated/api/models/GenerationJobType.js.map +1 -0
  263. package/dist/generated/api/models/GenerationResult.d.ts +6 -4
  264. package/dist/generated/api/models/GenerationResult.d.ts.map +1 -1
  265. package/dist/generated/api/models/GenerationResult.js +4 -4
  266. package/dist/generated/api/models/GenerationResult.js.map +1 -1
  267. package/dist/generated/api/models/ImageDto.d.ts +2 -2
  268. package/dist/generated/api/models/ImageDto.js +2 -2
  269. package/dist/generated/api/models/ImageListResponse.d.ts +2 -2
  270. package/dist/generated/api/models/ImageListResponse.js +2 -2
  271. package/dist/generated/api/models/ImportCatalogResponse.d.ts +8 -7
  272. package/dist/generated/api/models/ImportCatalogResponse.d.ts.map +1 -1
  273. package/dist/generated/api/models/ImportCatalogResponse.js +7 -6
  274. package/dist/generated/api/models/ImportCatalogResponse.js.map +1 -1
  275. package/dist/generated/api/models/InstallCatalogReleaseResponse.d.ts +7 -7
  276. package/dist/generated/api/models/InstallCatalogReleaseResponse.d.ts.map +1 -1
  277. package/dist/generated/api/models/InstallCatalogReleaseResponse.js +7 -6
  278. package/dist/generated/api/models/InstallCatalogReleaseResponse.js.map +1 -1
  279. package/dist/generated/api/models/InvalidDataField.d.ts +2 -2
  280. package/dist/generated/api/models/InvalidDataField.js +2 -2
  281. package/dist/generated/api/models/Margins.d.ts +2 -2
  282. package/dist/generated/api/models/Margins.js +2 -2
  283. package/dist/generated/api/models/MarkStencilReadyResponse.d.ts +2 -2
  284. package/dist/generated/api/models/MarkStencilReadyResponse.js +2 -2
  285. package/dist/generated/api/models/MergeBaseMissingProblemDetail.d.ts +2 -2
  286. package/dist/generated/api/models/MergeBaseMissingProblemDetail.js +2 -2
  287. package/dist/generated/api/models/MergeConflictsUnresolvedProblemDetail.d.ts +2 -2
  288. package/dist/generated/api/models/MergeConflictsUnresolvedProblemDetail.js +2 -2
  289. package/dist/generated/api/models/MergeIntoCatalogDraftRequest.d.ts +2 -2
  290. package/dist/generated/api/models/MergeIntoCatalogDraftRequest.js +2 -2
  291. package/dist/generated/api/models/MergeIntoCatalogDraftResponse.d.ts +2 -2
  292. package/dist/generated/api/models/MergeIntoCatalogDraftResponse.js +2 -2
  293. package/dist/generated/api/models/MissingDataField.d.ts +2 -2
  294. package/dist/generated/api/models/MissingDataField.js +2 -2
  295. package/dist/generated/api/models/MissingReleaseDependency.d.ts +2 -2
  296. package/dist/generated/api/models/MissingReleaseDependency.js +2 -2
  297. package/dist/generated/api/models/MissingReleaseDependencyReason.d.ts +2 -2
  298. package/dist/generated/api/models/MissingReleaseDependencyReason.js +2 -2
  299. package/dist/generated/api/models/Node.d.ts +2 -2
  300. package/dist/generated/api/models/Node.js +2 -2
  301. package/dist/generated/api/models/Orientation.d.ts +2 -2
  302. package/dist/generated/api/models/Orientation.js +2 -2
  303. package/dist/generated/api/models/PageFormat.d.ts +2 -2
  304. package/dist/generated/api/models/PageFormat.js +2 -2
  305. package/dist/generated/api/models/PageMeta.d.ts +2 -2
  306. package/dist/generated/api/models/PageMeta.js +2 -2
  307. package/dist/generated/api/models/PageSettings.d.ts +2 -2
  308. package/dist/generated/api/models/PageSettings.js +2 -2
  309. package/dist/generated/api/models/PartitionAssignment.d.ts +2 -2
  310. package/dist/generated/api/models/PartitionAssignment.js +2 -2
  311. package/dist/generated/api/models/PingRequest.d.ts +2 -2
  312. package/dist/generated/api/models/PingRequest.js +2 -2
  313. package/dist/generated/api/models/PongDetailsDto.d.ts +2 -2
  314. package/dist/generated/api/models/PongDetailsDto.js +2 -2
  315. package/dist/generated/api/models/PongResponse.d.ts +2 -2
  316. package/dist/generated/api/models/PongResponse.js +2 -2
  317. package/dist/generated/api/models/PreviewDocumentRequest.d.ts +3 -3
  318. package/dist/generated/api/models/PreviewDocumentRequest.js +2 -2
  319. package/dist/generated/api/models/ProblemDetail.d.ts +2 -2
  320. package/dist/generated/api/models/ProblemDetail.js +2 -2
  321. package/dist/generated/api/models/PublishReleaseToRegistryRequest.d.ts +2 -2
  322. package/dist/generated/api/models/PublishReleaseToRegistryRequest.js +2 -2
  323. package/dist/generated/api/models/RegisterConsumerRequest.d.ts +2 -2
  324. package/dist/generated/api/models/RegisterConsumerRequest.js +2 -2
  325. package/dist/generated/api/models/RegistryReleaseDto.d.ts +2 -2
  326. package/dist/generated/api/models/RegistryReleaseDto.js +2 -2
  327. package/dist/generated/api/models/RegistryReleaseListResponse.d.ts +2 -2
  328. package/dist/generated/api/models/RegistryReleaseListResponse.js +2 -2
  329. package/dist/generated/api/models/RejectConsumerRequest.d.ts +2 -2
  330. package/dist/generated/api/models/RejectConsumerRequest.js +2 -2
  331. package/dist/generated/api/models/ReleaseCatalogDraftRequest.d.ts +2 -2
  332. package/dist/generated/api/models/ReleaseCatalogDraftRequest.js +2 -2
  333. package/dist/generated/api/models/ReleaseCatalogDraftResponse.d.ts +2 -2
  334. package/dist/generated/api/models/ReleaseCatalogDraftResponse.js +2 -2
  335. package/dist/generated/api/models/ReleaseDependenciesMissingProblemDetail.d.ts +2 -2
  336. package/dist/generated/api/models/ReleaseDependenciesMissingProblemDetail.js +2 -2
  337. package/dist/generated/api/models/ReleaseDependenciesUnreleasedProblemDetail.d.ts +2 -2
  338. package/dist/generated/api/models/ReleaseDependenciesUnreleasedProblemDetail.js +2 -2
  339. package/dist/generated/api/models/ReleaseDependencyDto.d.ts +2 -2
  340. package/dist/generated/api/models/ReleaseDependencyDto.js +2 -2
  341. package/dist/generated/api/models/ReleaseInUseProblemDetail.d.ts +60 -0
  342. package/dist/generated/api/models/ReleaseInUseProblemDetail.d.ts.map +1 -0
  343. package/dist/generated/api/models/ReleaseInUseProblemDetail.js +62 -0
  344. package/dist/generated/api/models/ReleaseInUseProblemDetail.js.map +1 -0
  345. package/dist/generated/api/models/ReleasePublicationDto.d.ts +2 -2
  346. package/dist/generated/api/models/ReleasePublicationDto.js +2 -2
  347. package/dist/generated/api/models/ReleasePublicationStatus.d.ts +2 -2
  348. package/dist/generated/api/models/ReleasePublicationStatus.js +2 -2
  349. package/dist/generated/api/models/ReleaseRegistryDto.d.ts +2 -2
  350. package/dist/generated/api/models/ReleaseRegistryDto.js +2 -2
  351. package/dist/generated/api/models/ReleaseRegistryKind.d.ts +2 -2
  352. package/dist/generated/api/models/ReleaseRegistryKind.js +2 -2
  353. package/dist/generated/api/models/ReleaseRegistryListResponse.d.ts +2 -2
  354. package/dist/generated/api/models/ReleaseRegistryListResponse.js +2 -2
  355. package/dist/generated/api/models/ReleasedChangeDto.d.ts +2 -2
  356. package/dist/generated/api/models/ReleasedChangeDto.js +2 -2
  357. package/dist/generated/api/models/ReleasedDependencyDto.d.ts +2 -2
  358. package/dist/generated/api/models/ReleasedDependencyDto.js +2 -2
  359. package/dist/generated/api/models/ResourceChangeDto.d.ts +2 -2
  360. package/dist/generated/api/models/ResourceChangeDto.js +2 -2
  361. package/dist/generated/api/models/ResourceStatus.d.ts +2 -2
  362. package/dist/generated/api/models/ResourceStatus.js +2 -2
  363. package/dist/generated/api/models/RotatePublicKeyRequest.d.ts +2 -2
  364. package/dist/generated/api/models/RotatePublicKeyRequest.js +2 -2
  365. package/dist/generated/api/models/Slot.d.ts +2 -2
  366. package/dist/generated/api/models/Slot.js +2 -2
  367. package/dist/generated/api/models/StencilContentDto.d.ts +2 -2
  368. package/dist/generated/api/models/StencilContentDto.js +2 -2
  369. package/dist/generated/api/models/StencilDto.d.ts +2 -2
  370. package/dist/generated/api/models/StencilDto.js +2 -2
  371. package/dist/generated/api/models/StencilListResponse.d.ts +2 -2
  372. package/dist/generated/api/models/StencilListResponse.js +2 -2
  373. package/dist/generated/api/models/StencilSummaryDto.d.ts +2 -2
  374. package/dist/generated/api/models/StencilSummaryDto.js +2 -2
  375. package/dist/generated/api/models/StencilUsageDto.d.ts +2 -2
  376. package/dist/generated/api/models/StencilUsageDto.js +2 -2
  377. package/dist/generated/api/models/StencilUsageListResponse.d.ts +2 -2
  378. package/dist/generated/api/models/StencilUsageListResponse.js +2 -2
  379. package/dist/generated/api/models/TemplateDataValidationError.d.ts +2 -2
  380. package/dist/generated/api/models/TemplateDataValidationError.js +2 -2
  381. package/dist/generated/api/models/TemplateDataValidationProblemDetail.d.ts +2 -2
  382. package/dist/generated/api/models/TemplateDataValidationProblemDetail.js +2 -2
  383. package/dist/generated/api/models/TemplateDataValidationResult.d.ts +2 -2
  384. package/dist/generated/api/models/TemplateDataValidationResult.js +2 -2
  385. package/dist/generated/api/models/TemplateDocument.d.ts +2 -2
  386. package/dist/generated/api/models/TemplateDocument.js +2 -2
  387. package/dist/generated/api/models/TemplateDto.d.ts +6 -8
  388. package/dist/generated/api/models/TemplateDto.d.ts.map +1 -1
  389. package/dist/generated/api/models/TemplateDto.js +5 -5
  390. package/dist/generated/api/models/TemplateDto.js.map +1 -1
  391. package/dist/generated/api/models/TemplateListResponse.d.ts +2 -2
  392. package/dist/generated/api/models/TemplateListResponse.js +2 -2
  393. package/dist/generated/api/models/TemplateSummaryDto.d.ts +2 -2
  394. package/dist/generated/api/models/TemplateSummaryDto.js +2 -2
  395. package/dist/generated/api/models/TenantDto.d.ts +2 -2
  396. package/dist/generated/api/models/TenantDto.js +2 -2
  397. package/dist/generated/api/models/TenantListResponse.d.ts +2 -2
  398. package/dist/generated/api/models/TenantListResponse.js +2 -2
  399. package/dist/generated/api/models/ThemeDto.d.ts +5 -6
  400. package/dist/generated/api/models/ThemeDto.d.ts.map +1 -1
  401. package/dist/generated/api/models/ThemeDto.js +2 -2
  402. package/dist/generated/api/models/ThemeDto.js.map +1 -1
  403. package/dist/generated/api/models/ThemeListResponse.d.ts +2 -2
  404. package/dist/generated/api/models/ThemeListResponse.js +2 -2
  405. package/dist/generated/api/models/ThemeRef.d.ts +3 -3
  406. package/dist/generated/api/models/ThemeRef.js +2 -2
  407. package/dist/generated/api/models/UnreleasedCatalogDependency.d.ts +2 -2
  408. package/dist/generated/api/models/UnreleasedCatalogDependency.js +2 -2
  409. package/dist/generated/api/models/UpdateAttributeRequest.d.ts +9 -9
  410. package/dist/generated/api/models/UpdateAttributeRequest.d.ts.map +1 -1
  411. package/dist/generated/api/models/UpdateAttributeRequest.js +7 -9
  412. package/dist/generated/api/models/UpdateAttributeRequest.js.map +1 -1
  413. package/dist/generated/api/models/UpdateCatalogDependenciesRequest.d.ts +2 -2
  414. package/dist/generated/api/models/UpdateCatalogDependenciesRequest.js +2 -2
  415. package/dist/generated/api/models/UpdateCatalogReleaseRequest.d.ts +2 -2
  416. package/dist/generated/api/models/UpdateCatalogReleaseRequest.js +2 -2
  417. package/dist/generated/api/models/UpdateCodeListEntryHiddenRequest.d.ts +2 -2
  418. package/dist/generated/api/models/UpdateCodeListEntryHiddenRequest.js +2 -2
  419. package/dist/generated/api/models/UpdateCodeListRequest.d.ts +5 -13
  420. package/dist/generated/api/models/UpdateCodeListRequest.d.ts.map +1 -1
  421. package/dist/generated/api/models/UpdateCodeListRequest.js +7 -14
  422. package/dist/generated/api/models/UpdateCodeListRequest.js.map +1 -1
  423. package/dist/generated/api/models/UpdateConsumerRequest.d.ts +2 -2
  424. package/dist/generated/api/models/UpdateConsumerRequest.js +2 -2
  425. package/dist/generated/api/models/UpdateEnvironmentRequest.d.ts +2 -2
  426. package/dist/generated/api/models/UpdateEnvironmentRequest.js +2 -2
  427. package/dist/generated/api/models/UpdateStencilContentRequest.d.ts +2 -2
  428. package/dist/generated/api/models/UpdateStencilContentRequest.js +2 -2
  429. package/dist/generated/api/models/UpdateStencilRequest.d.ts +2 -2
  430. package/dist/generated/api/models/UpdateStencilRequest.js +2 -2
  431. package/dist/generated/api/models/UpdateTemplateRequest.d.ts +3 -9
  432. package/dist/generated/api/models/UpdateTemplateRequest.d.ts.map +1 -1
  433. package/dist/generated/api/models/UpdateTemplateRequest.js +2 -4
  434. package/dist/generated/api/models/UpdateTemplateRequest.js.map +1 -1
  435. package/dist/generated/api/models/UpdateTenantRequest.d.ts +2 -2
  436. package/dist/generated/api/models/UpdateTenantRequest.js +2 -2
  437. package/dist/generated/api/models/UpdateThemeRequest.d.ts +2 -2
  438. package/dist/generated/api/models/UpdateThemeRequest.js +2 -2
  439. package/dist/generated/api/models/UpdateVariantContentRequest.d.ts +2 -2
  440. package/dist/generated/api/models/UpdateVariantContentRequest.js +2 -2
  441. package/dist/generated/api/models/UpdateVariantRequest.d.ts +13 -7
  442. package/dist/generated/api/models/UpdateVariantRequest.d.ts.map +1 -1
  443. package/dist/generated/api/models/UpdateVariantRequest.js +4 -6
  444. package/dist/generated/api/models/UpdateVariantRequest.js.map +1 -1
  445. package/dist/generated/api/models/ValidateTemplateDataRequest.d.ts +2 -2
  446. package/dist/generated/api/models/ValidateTemplateDataRequest.js +2 -2
  447. package/dist/generated/api/models/ValidationError.d.ts +2 -2
  448. package/dist/generated/api/models/ValidationError.js +2 -2
  449. package/dist/generated/api/models/ValidationProblemDetail.d.ts +2 -2
  450. package/dist/generated/api/models/ValidationProblemDetail.js +2 -2
  451. package/dist/generated/api/models/VariantContentDto.d.ts +2 -2
  452. package/dist/generated/api/models/VariantContentDto.js +2 -2
  453. package/dist/generated/api/models/VariantDto.d.ts +9 -5
  454. package/dist/generated/api/models/VariantDto.d.ts.map +1 -1
  455. package/dist/generated/api/models/VariantDto.js +5 -5
  456. package/dist/generated/api/models/VariantDto.js.map +1 -1
  457. package/dist/generated/api/models/VariantListResponse.d.ts +2 -2
  458. package/dist/generated/api/models/VariantListResponse.js +2 -2
  459. package/dist/generated/api/models/VariantSelectionAttribute.d.ts +2 -2
  460. package/dist/generated/api/models/VariantSelectionAttribute.js +2 -2
  461. package/dist/generated/api/models/VariantSummaryDto.d.ts +4 -4
  462. package/dist/generated/api/models/VariantSummaryDto.d.ts.map +1 -1
  463. package/dist/generated/api/models/VariantSummaryDto.js +5 -5
  464. package/dist/generated/api/models/VariantSummaryDto.js.map +1 -1
  465. package/dist/generated/api/models/index.d.ts +11 -4
  466. package/dist/generated/api/models/index.d.ts.map +1 -1
  467. package/dist/generated/api/models/index.js +11 -4
  468. package/dist/generated/api/models/index.js.map +1 -1
  469. package/dist/generated/api/runtime.d.ts +2 -2
  470. package/dist/generated/api/runtime.js +2 -2
  471. package/dist/generated/contractOperations.d.ts.map +1 -1
  472. package/dist/generated/contractOperations.js +1 -0
  473. package/dist/generated/contractOperations.js.map +1 -1
  474. package/dist/generated/contractVersion.d.ts +1 -1
  475. package/dist/generated/contractVersion.js +1 -1
  476. package/dist/generated/knownProblemSlugs.d.ts +29 -1
  477. package/dist/generated/knownProblemSlugs.d.ts.map +1 -1
  478. package/dist/generated/knownProblemSlugs.js +29 -1
  479. package/dist/generated/knownProblemSlugs.js.map +1 -1
  480. package/dist/generated/modelValidation.d.ts +12 -2
  481. package/dist/generated/modelValidation.d.ts.map +1 -1
  482. package/dist/generated/modelValidation.js +72 -7
  483. package/dist/generated/modelValidation.js.map +1 -1
  484. package/dist/index.d.ts +1 -1
  485. package/dist/index.d.ts.map +1 -1
  486. package/dist/index.js +1 -1
  487. package/dist/index.js.map +1 -1
  488. package/package.json +1 -1
  489. package/dist/generated/api/models/AttributeDtoCodeListBinding.d.ts.map +0 -1
  490. package/dist/generated/api/models/AttributeDtoCodeListBinding.js.map +0 -1
  491. package/dist/generated/api/models/CreateAttributeRequestCodeListBinding.d.ts.map +0 -1
  492. package/dist/generated/api/models/CreateAttributeRequestCodeListBinding.js.map +0 -1
  493. package/dist/generated/api/models/GenerationJobDetail.d.ts.map +0 -1
  494. package/dist/generated/api/models/GenerationJobDetail.js.map +0 -1
  495. package/dist/generated/api/models/UpdateAttributeRequestCodeListBinding.d.ts.map +0 -1
  496. package/dist/generated/api/models/UpdateAttributeRequestCodeListBinding.js.map +0 -1
package/CHANGELOG.md CHANGED
@@ -11,6 +11,10 @@ records contract changes; this file records changes to the hand-written library
11
11
 
12
12
  ### Added
13
13
 
14
+ - `ProblemDetailException.behind` and `isCatalogVersionBehindProblem` (a `catalog-version-behind`
15
+ problem's versions to acknowledge), `environments`, `pinnedBy` (each a `CatalogReleaseRef`) and
16
+ `isReleaseInUseProblem` (what a `release-in-use` problem says uses the release), and
17
+ `tiedVariants` and `isAmbiguousVariantProblem` (an `ambiguous-variant` problem's variants).
14
18
  - `ProblemDetailException.missingBaseVersion`, `missingBaseFingerprint` and
15
19
  `isMergeBaseMissingProblem` surface the `version` and `fingerprint` members of a
16
20
  `merge-base-missing` problem (409, from `mergeIntoCatalogDraft`, alpha): the release to install
package/README.md CHANGED
@@ -166,6 +166,16 @@ try {
166
166
  // the merge base is not installed here: install it first, then merge again
167
167
  log.warn(`install ${e.missingBaseVersion} (${e.missingBaseFingerprint}) first`)
168
168
  break
169
+ case KnownProblemSlugs.CATALOG_VERSION_BEHIND:
170
+ log.warn(`the draft is behind ${e.behind.join(', ')}`) // releaseCatalogDraft: name them in acknowledgedBehind
171
+ break
172
+ case KnownProblemSlugs.RELEASE_IN_USE:
173
+ // deleteCatalogRelease: undeploy it, and release the catalogs that pin it without it
174
+ log.warn(`deployed to ${e.environments.join(', ')}; pinned by ${e.pinnedBy.map((r) => `${r.catalogKey}@${r.version}`).join(', ')}`)
175
+ break
176
+ case KnownProblemSlugs.AMBIGUOUS_VARIANT:
177
+ log.warn(`several variants match: ${e.tiedVariants.join(', ')}`) // generateDocument, previewDocument: name one by variantKey
178
+ break
169
179
  case KnownProblemSlugs.CATALOG_RENDERING_DEFAULTS_TOO_NEW:
170
180
  // importCatalog / installCatalogRelease: the release renders with rendering defaults this
171
181
  // installation does not have
@@ -183,7 +193,7 @@ try {
183
193
  log.warn(`catalog source unavailable (${e.problemStatus}): ${e.detail}`)
184
194
  break
185
195
  default:
186
- throw e // unknown / framework error — fall back to e.statusCode
196
+ throw e // a type this client does not know: handle it by e.problemStatus
187
197
  }
188
198
  } else if (e instanceof ResponseError) {
189
199
  // an error response without a problem document
@@ -196,7 +206,8 @@ ResponseError` sites keep working. It exposes `type`, `typeSlug`, `title`, `prob
196
206
  `detail`, `instance`, `errors`, `validationErrors`, `missingFields`, `invalidFields`,
197
207
  `missingDependencies`, `unreleasedDependencies`, `readOnlyReason`, `unresolvedConflicts`,
198
208
  `isMergeConflictsUnresolvedProblem`, `missingBaseVersion`, `missingBaseFingerprint`,
199
- `isMergeBaseMissingProblem`, `extensions` (every member
209
+ `isMergeBaseMissingProblem`, `behind`, `isCatalogVersionBehindProblem`, `environments`,
210
+ `pinnedBy`, `isReleaseInUseProblem`, `tiedVariants`, `isAmbiguousVariantProblem`, `extensions` (every member
200
211
  outside the RFC 9457 base five), `statusCode`, `rawBody`, `isValidationProblem`,
201
212
  `isDataModelValidationProblem`, `isTemplateDataProblem`, `isReleaseDependenciesMissingProblem`,
202
213
  `isReleaseDependenciesUnreleasedProblem`, and `isCatalogReadOnlyProblem`.
@@ -1,4 +1,4 @@
1
- import type { CatalogReadOnlyReason, DataModelValidationError, InvalidDataField, MissingDataField, MissingReleaseDependency, MissingReleaseDependencyReason, ProblemDetail, UnreleasedCatalogDependency, ValidationError } from '../generated/api/models/index.js';
1
+ import type { CatalogReadOnlyReason, CatalogReleaseRefDto, DataModelValidationError, InvalidDataField, MissingDataField, MissingReleaseDependency, MissingReleaseDependencyReason, ProblemDetail, UnreleasedCatalogDependency, ValidationError } from '../generated/api/models/index.js';
2
2
  import { ResponseError } from '../generated/api/runtime.js';
3
3
  /**
4
4
  * A {@link ResponseError} carrying a parsed [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457)
@@ -154,6 +154,34 @@ export declare class ProblemDetailException extends ResponseError {
154
154
  get missingBaseFingerprint(): string | undefined;
155
155
  /** True when this problem named a merge base this installation does not have. */
156
156
  get isMergeBaseMissingProblem(): boolean;
157
+ /**
158
+ * The versions of the releases a `catalog-version-behind` problem (409, from
159
+ * `releaseCatalogDraft`) says the draft is behind and the request did not acknowledge: name each
160
+ * in `acknowledgedBehind` to release it anyway. Empty for any other problem.
161
+ */
162
+ get behind(): readonly string[];
163
+ /** True when this problem said the draft is behind releases the request did not acknowledge. */
164
+ get isCatalogVersionBehindProblem(): boolean;
165
+ /**
166
+ * The environments a `release-in-use` problem (409, from `deleteCatalogRelease`) says deploy the
167
+ * release; empty for any other problem, and when none does.
168
+ */
169
+ get environments(): readonly string[];
170
+ /**
171
+ * The releases of other catalogs a `release-in-use` problem says pin the release, and render with
172
+ * it; empty for any other problem. An entry of an unexpected shape is dropped.
173
+ */
174
+ get pinnedBy(): readonly CatalogReleaseRef[];
175
+ /** True when this problem said the release cannot be deleted while something uses it. */
176
+ get isReleaseInUseProblem(): boolean;
177
+ /**
178
+ * The keys of the variants an `ambiguous-variant` problem (409, from generating or previewing a
179
+ * document) says match the request's attributes equally well: name one by `variantKey`, or send
180
+ * attributes that tell them apart. Empty for any other problem.
181
+ */
182
+ get tiedVariants(): readonly string[];
183
+ /** True when this problem said several variants match equally well. */
184
+ get isAmbiguousVariantProblem(): boolean;
157
185
  private mergeBaseMissingMember;
158
186
  }
159
187
  /**
@@ -170,4 +198,9 @@ export interface MissingDependency extends Omit<MissingReleaseDependency, 'reaso
170
198
  * `unreleasedDependencies` member: the generated `UnreleasedCatalogDependency`.
171
199
  */
172
200
  export type UnreleasedDependency = Readonly<UnreleasedCatalogDependency>;
201
+ /**
202
+ * One release a problem names in full, such as each entry of a `release-in-use` problem's
203
+ * `pinnedBy` member: the generated `CatalogReleaseRefDto`.
204
+ */
205
+ export type CatalogReleaseRef = Readonly<CatalogReleaseRefDto>;
173
206
  //# sourceMappingURL=problemDetailException.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"problemDetailException.d.ts","sourceRoot":"","sources":["../../src/error/problemDetailException.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"problemDetailException.d.ts","sourceRoot":"","sources":["../../src/error/problemDetailException.ts"],"names":[],"mappings":"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"}
@@ -199,6 +199,48 @@ export class ProblemDetailException extends ResponseError {
199
199
  get isMergeBaseMissingProblem() {
200
200
  return this.missingBaseVersion !== undefined;
201
201
  }
202
+ /**
203
+ * The versions of the releases a `catalog-version-behind` problem (409, from
204
+ * `releaseCatalogDraft`) says the draft is behind and the request did not acknowledge: name each
205
+ * in `acknowledgedBehind` to release it anyway. Empty for any other problem.
206
+ */
207
+ get behind() {
208
+ return stringsAt(this.extensions, ProblemExtensionMembers.BEHIND);
209
+ }
210
+ /** True when this problem said the draft is behind releases the request did not acknowledge. */
211
+ get isCatalogVersionBehindProblem() {
212
+ return this.typeSlug === KnownProblemSlugs.CATALOG_VERSION_BEHIND;
213
+ }
214
+ /**
215
+ * The environments a `release-in-use` problem (409, from `deleteCatalogRelease`) says deploy the
216
+ * release; empty for any other problem, and when none does.
217
+ */
218
+ get environments() {
219
+ return stringsAt(this.extensions, ProblemExtensionMembers.ENVIRONMENTS);
220
+ }
221
+ /**
222
+ * The releases of other catalogs a `release-in-use` problem says pin the release, and render with
223
+ * it; empty for any other problem. An entry of an unexpected shape is dropped.
224
+ */
225
+ get pinnedBy() {
226
+ return objectsAt(this.extensions, ProblemExtensionMembers.PINNED_BY).filter(isCatalogReleaseRef);
227
+ }
228
+ /** True when this problem said the release cannot be deleted while something uses it. */
229
+ get isReleaseInUseProblem() {
230
+ return this.typeSlug === KnownProblemSlugs.RELEASE_IN_USE;
231
+ }
232
+ /**
233
+ * The keys of the variants an `ambiguous-variant` problem (409, from generating or previewing a
234
+ * document) says match the request's attributes equally well: name one by `variantKey`, or send
235
+ * attributes that tell them apart. Empty for any other problem.
236
+ */
237
+ get tiedVariants() {
238
+ return stringsAt(this.extensions, ProblemExtensionMembers.TIED_VARIANTS);
239
+ }
240
+ /** True when this problem said several variants match equally well. */
241
+ get isAmbiguousVariantProblem() {
242
+ return this.typeSlug === KnownProblemSlugs.AMBIGUOUS_VARIANT;
243
+ }
202
244
  mergeBaseMissingMember(member) {
203
245
  if (this.typeSlug !== KnownProblemSlugs.MERGE_BASE_MISSING)
204
246
  return undefined;
@@ -216,6 +258,16 @@ function isUnreleasedDependency(entry) {
216
258
  const record = entry;
217
259
  return UNRELEASED_DEPENDENCY_MEMBERS.every((member) => typeof record[member] === 'string');
218
260
  }
261
+ const CATALOG_RELEASE_REF_MEMBERS = ['registry', 'namespace', 'catalogKey', 'version', 'releaseId'];
262
+ function isCatalogReleaseRef(entry) {
263
+ const record = entry;
264
+ return CATALOG_RELEASE_REF_MEMBERS.every((member) => typeof record[member] === 'string');
265
+ }
266
+ /** One extension member's array of strings, or empty when absent; entries that are not strings are dropped. */
267
+ function stringsAt(extensions, member) {
268
+ const value = extensions[member];
269
+ return Array.isArray(value) ? value.filter((entry) => typeof entry === 'string') : [];
270
+ }
219
271
  /**
220
272
  * One extension member's array of objects, or empty when absent or malformed. Entries of an
221
273
  * unexpected shape are dropped rather than guessed at: a malformed problem body should not become a
@@ -1 +1 @@
1
- {"version":3,"file":"problemDetailException.js","sourceRoot":"","sources":["../../src/error/problemDetailException.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"problemDetailException.js","sourceRoot":"","sources":["../../src/error/problemDetailException.ts"],"names":[],"mappings":"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"}
@@ -1,8 +1,8 @@
1
1
  /**
2
2
  * Epistola API
3
- * Epistola generates documents, PDFs, from templates. Authors design the templates; applications send data and get documents back. This API manages templates and the catalogs that hold them, and generates documents from them, asynchronously and at volume. ## Glossary - **Tenant**: an organisation, isolated from every other. Everything else lives in one, under `/tenants/{tenantKey}`. - **Catalog**: a set of templates and everything they use, released as a whole. A catalog is named by three parts together: a **registry**, the DNS name of where it is published (`exchange.epistola.app`, or a domain that publishes its own, `acme.com`); a **namespace**, its publisher within that registry (`acme-corp`); and its key (`letters`). In a path, `~` stands for the server\'s default registry. The registry `local` names catalogs that never leave the organisation: valid within its own installations, refused by an Exchange. - **Release**: the catalog as a whole at one point, in one of two statuses. A **draft release**, or **draft**, is editable and has no version; a **released** release is immutable and has a version. \"Release `1.4.0`\" means the released one. - **Version**: the number of a released release, its `version` (`1.4.0`), a SemVer core version, or a patch release number (`1.3.1-gemeente-x.1`, see \"Versions and version ranges\"). A **version range**, `versionRange` (`^1.4.0`), selects the highest release that satisfies it, for a request that renders; it never matches a draft. - **Content hash**: what identifies a released release, its `contentHash` (`v6:…`), a hash of its content alone, not of its name or number: two releases with one content hash are the same release, whatever they are called. Names and numbers point at content hashes. - **Releasing**: turning a draft into a released release, as a version. A release keeps its id, its `releaseId`, assigned by the server, and its name when it is released, so a draft released as `1.4.1` is the same release, addressed by its `releaseId` or by `1.4.1`. - **Publishing**: making a catalog available in a registry, for other tenants and installations to install from. Only released releases are ever published; releasing is not publishing. - **Base**: the release a draft started from; its changes are measured against it. A draft is **behind** a release whose changes it may lack (see \"Releases\"). A changed resource is **ready** once someone marks it reviewed; a draft is released only when it changed something and all its changes are (`getCatalogChanges`). - **Editable** catalogs: every catalog has releases and drafts, wherever its releases come from (its **source**: an exchange, a registry, a file, or the server itself). Whether a catalog can be changed depends on the installation, which may only receive and run releases, and on whether the server supplies the catalog itself (`CatalogDto.editable`, `readOnlyReason`). - **Environment**: where documents are generated for a purpose, such as `staging` or `production`. A **deployment** makes an environment serve a release of a catalog; a request through the environment renders what it serves. - **Template**: one kind of document, with its data contract (the JSON Schema its data must meet) and data examples. A **variant** is one rendering of a template, for a language or a brand, chosen by its key or by **attributes** (such as `locale`); an attribute\'s values may come from a **code list** of `{code, label}` entries. A **stencil** is reusable template content, a **theme** a reusable set of styles, and a **preset** a named block style a catalog declares and its themes style. - **Consumer** (experimental): an application registered in a tenant, with its own permissions. ## Getting started 1. **Get an API key** from a tenant manager. A key belongs to one tenant and carries the roles it was issued with: `CONTENT_VIEWER` to find templates and read jobs and documents, and `DOCUMENT_GENERATOR` to generate. 2. **Send these headers** on every request (the client libraries set all but the key): ``` Authorization: ApiKey <key> Accept: application/vnd.epistola.v2+json Content-Type: application/vnd.epistola.v2+json (with a request body) User-Agent: epistola-contract/2.0.0 your-app/1.0 X-EP-Node-Id: <this host or pod> ``` 3. **Find your template.** `GET /tenants/{tenantKey}/catalogs` lists the catalogs, each with its `registry`, `namespace`, `catalogKey` and `highestVersion`. `GET /tenants/{tenantKey}/catalogs/{registry}/{namespace}/{catalogKey}/releases/{release}/templates`, with that version as `{release}`, lists that release\'s templates, and `getTemplate` shows a template\'s data contract. 4. **Generate.** `POST /tenants/{tenantKey}/documents/generate` with the template and its data: ```json {\"namespace\": \"acme-corp\", \"catalogKey\": \"letters\", \"templateKey\": \"invoice\", \"variantKey\": \"english\", \"data\": {\"customer\": {\"name\": \"Jane Smith\"}}} ``` It answers `202` with a `requestId` and, in `Location`, the job\'s address. Without a `versionRange` or an `environmentKey`, the catalog\'s highest release renders. 5. **Poll the job**, `GET /tenants/{tenantKey}/documents/jobs/{requestId}`, until `request.status` is `completed` (or `failed` or `cancelled`). Each item names its `documentId`. 6. **Download** the PDF: `GET /tenants/{tenantKey}/documents/{documentId}`. `validateTemplateData` checks data against a template\'s contract before you submit it, and `previewDocument` renders one document synchronously, for previews only. For high volume, poll no jobs: collect finished results as a stream instead (`collectGenerationResults`), each delivered to the node that asked for it and acknowledged when handled. That is the advanced path; the client libraries\' result collectors implement it. ## Template model A variant\'s content (`getVariantContent`, `updateVariantContent`) and a stencil\'s are a template document: a flat graph of nodes and slots, linked by id. A node is one block, of a component type such as `text`, `table` or `conditional`; a slot is a named place in a node that holds child nodes, such as a table\'s `cell-0-1` or a conditional\'s `body` and `else`. The catalog contract\'s [component registry](https://github.com/epistola-app/epistola-contract/blob/main/contracts/catalog/registry/component-registry.json) and [style registry](https://github.com/epistola-app/epistola-contract/blob/main/contracts/catalog/registry/style-registry.json) define every component and style, with examples, and the [template model guide](https://github.com/epistola-app/epistola-contract/blob/main/contracts/api/docs/template-model.md) walks through a complete letter: the example `updateVariantContent` shows. ## Media types The media type carries the API\'s major version. Contract 2.x uses `application/vnd.epistola.v2+json`, and `application/vnd.epistola.v2+ndjson` for the result stream, in `Accept` and in `Content-Type`. Problems are `application/problem+json`. ## Client identity Every request identifies the client with two headers: - **`User-Agent`** (required): [RFC 9110](https://www.rfc-editor.org/rfc/rfc9110#name-user-agent) product tokens, the first of which **must** be `epistola-contract/{version}`, the contract version the client was built against. Further tokens describe the rest of the stack: `epistola-contract/x.y.z valtimo-epistola-plugin/1.2.0 gzac/5.0.0`. - **`X-EP-Node-Id`** (required): the client node, such as its Kubernetes pod name, container id or hostname. The client libraries set both, the contract version and the hostname; an application can append its own product tokens and override the node id. ## Releases A catalog consists of releases, addressed as `/catalogs/{registry}/{namespace}/{catalogKey}/releases/{release}`, with the catalog\'s resources below each. A draft is addressed by its `releaseId`; a released release by its `releaseId` or its version, which address the same release. Every write to a released release is refused with 409. - A catalog that can be changed has **any number of drafts**, each named, each started from a released release (its base) or from another draft (`createCatalogRelease`). The base never moves. `listCatalogReleases` lists a catalog\'s releases, drafts included, each with its `status` (`?status=draft` for the drafts only) and, once released, its `contentHash` (`?contentHash=` for the releases with that content); a catalog (`CatalogDto`) does not list them. - **Any draft can be released.** Its version follows from the kind of change against its base: fixes raise the patch, additions the minor, anything that breaks callers the major (`previewCatalogDraftRelease`). The author may choose a higher version, never a lower one or one another release has. A fix to an older line is a draft from a release of that line: from `1.4.0`, while `1.5.0` and `2.0.0` exist, it is released as `1.4.1`. - **Drafts are independent copies**: releasing one changes no other. A draft is **behind** each release whose version is between its base and the version it would get, and each release released after it was started whose version is below that one; it lacks their changes unless an author applied them by hand. `getCatalogRelease` lists them, and releasing a draft that is behind must acknowledge them. - **Merging a release into a draft** (alpha, `x-experimental`): `previewCatalogDraftMerge` shows, per resource, per catalog setting (default theme and presets, entries of type `catalog`) and per catalog used (entries of type `catalogDependency`), each with the entries it goes with (`needs`), against the merge base (the closest release both descend from), what only the draft changed (`ours`), what only the release changed (`theirs`) and what both changed differently (`conflict`); `mergeIntoCatalogDraft` takes theirs and applies a resolution, `ours` or `theirs`, per conflict. The draft then contains the release and is no longer behind it; its base does not move. The preview\'s `token`, sent back as `expectedToken`, makes the merge apply what the preview showed or nothing (`merge-preview-outdated`). A conflict can also be resolved to content combined from its sides (`getCatalogDraftMergeSides`, then `mergedContent`), reviewed before the draft is released. The merge needs the merge base installed; the preview names one that is not (`missingBase`), and the merge is refused with `merge-base-missing`. - **Release registries** (alpha, `x-experimental`, ADR 0008) move releases between installations: an Epistola Exchange the installation is connected to, or a container registry it is configured with (`listReleaseRegistries`). A released release is published to one (`publishReleaseToRegistry`), and another installation lists the releases of a catalog there (`listRegistryReleases`) and installs one (`installRegistryRelease`) as an import does. A release registry is named by the installation; it is not the `{registry}` of a catalog\'s name. Documents are rendered from releases, and a version range never matches a draft. A draft renders only in a preview that names its `releaseId`, and in an environment it is deployed to. Importing a catalog archive (`importCatalog`) installs the release the archive carries, at its version, beside the releases the tenant already has; it never creates or changes a draft. A catalog with a source (`CatalogDto.source`) installs releases from it the same way (`installCatalogRelease`), and `listAvailableCatalogReleases` lists those the tenant does not have yet, older lines included. Nothing is updated in place or removed: deploying decides what an environment serves. A release keeps its id and number wherever it moves, so it is the same release in every installation. There are no catalog types: receiving releases works whether or not the catalog can be changed, and every write to one that cannot is refused with 409 `catalog-read-only`. ## Deploying An environment serves releases of catalogs (`deployCatalogRelease`): released ones, several of one catalog if need be, and at most one draft per catalog, rendered live. A request through the environment (`environmentKey`) renders: - with **no `versionRange`**: the catalog\'s deployed draft if there is one, else the highest release the environment serves; - with a **range or an exact version**: the highest served release that satisfies it. A draft never matches: it has no version. Rollback is undeploying the newer release. Deploying a draft replaces the draft the environment served for that catalog, and an environment marked **production** (`EnvironmentDto.production`) serves no draft. A document rendered from a draft carries the draft\'s `releaseId` and its name at render time (`draftLabel`), with a null `version`, and its PDF a preview watermark. Releasing a deployed draft keeps its `releaseId`, so the environment then serves it as released; discarding the draft ends the deployment. ## Versions and version ranges A version (`ReleaseVersion`) is a SemVer core version, `MAJOR.MINOR.PATCH` without leading zeros, as the holder of the catalog\'s namespace issues it, or a **patch release** number, `MAJOR.MINOR.PATCH-<namespace>.<N>`, at most 128 characters. Wherever the contract names one exact version it has that form, and is called `version`; every member called `version` is one. A patch release is how someone who does not hold a catalog\'s namespace fixes a release of it (a municipality fixing a supplier\'s catalog): it is labelled with a namespace they hold, and numbered from 1, `1.3.1-gemeente-x.1`. As a SemVer pre-release it sorts below its core and above every release below that, `1.3.0` < `1.3.1-gemeente-x.1` < `1.3.1`, so the holder\'s next release supersedes it, and the two never collide: the holder never uses a label, the patcher never issues a plain number (contract ADR 0003). Which namespaces a tenant holds is the installation\'s to know; the contract checks the shape. \"Highest\" always means by this order, a patch release included. A request that selects a release to render or check (generation, preview, validation) takes a version range, `versionRange`, in the npm SemVer range grammar: an exact version (`1.4.0`), a caret (`^1.4.0`), a tilde (`~1.4.0`), comparators (`>=1.0.0 <2.0.0`), a hyphen range (`1.0.0 - 2.0.0`), or a `||` union of these. The highest release that satisfies it renders, and responses name the exact release used. A range is at most 256 characters, so an exact release number (at most 128) always fits, and a comparator pair of patch release numbers usually does. A range matches a patch release as npm matches a pre-release: only when one of its comparators names a pre-release of the same `MAJOR.MINOR.PATCH`, such as the exact number (`1.3.1-gemeente-x.1`) or `>=1.3.1-gemeente-x.1 <1.4.0`; `^1.3.0` never selects one. ## Catalog dependencies A catalog that uses another catalog\'s resources declares that catalog once, with the exact release of it that it renders with (`version`), never a range. References into the other catalog name the catalog but no version, so a release renders with exactly the releases its declarations pin. In a draft, a declaration may name a draft of the other catalog instead (`releaseId`), to build on work that is not released yet. A released release pins only released releases: releasing such a draft is refused (`release-dependencies-unreleased`) unless the request releases those drafts along with it (`releaseDependencies`), in one transaction. ## Catalog identity A catalog\'s key alone is not unique: two publishers can each publish `letters`. The registry and the namespace complete its name, and the same namespace in two registries is two namespaces. Which registry is a server\'s default is configuration; in a path, `/catalogs/~/acme-corp/letters/…` and `/catalogs/exchange.epistola.app/acme-corp/letters/…` address the same catalog when `exchange.epistola.app` is the default, and `~` may be sent percent-encoded as `%7E`. In a body, a catalog is named by separate `registry`, `namespace` and `catalogKey` members, and a reference into another catalog by an alias: 1. **A request that names a catalog** (a generation or preview target, a dependency declaration) may omit `registry`, or send null, for the default registry. (An import\'s `registry` defaults to the one the archive names.) 2. **A reference from one catalog\'s release to a resource of another** names that catalog by the **alias** the release\'s dependency declarations give it (`CatalogAlias`, in the member `catalogKey`), never by registry or namespace: a template model\'s `themeRef`, its stencil and image nodes, a `fontFamily` (catalog content, portable catalog wire v8, contract ADR 0003), and the references this API reads and writes beside it, a release\'s default theme (`CatalogThemeReference`), an attribute\'s code-list binding and an attribute criterion in variant selection (`VariantSelectionAttribute`, resolved through the release that renders). Omitted or null, or the catalog\'s own key, is the catalog itself. A declaration (`CatalogDependencyDto`, `listCatalogDependencies`) maps each alias to the catalog\'s full name and the release it pins; that is where a client finds the name. Because content names the alias, it means the same in every installation and under any name, and pinning another release changes no content. An alias is by default the catalog\'s key (`CatalogDependencyRequirement.alias`). Responses write every registry in full, by its name, never `~`, so a value read from one installation means the same catalog on another. Content documents are returned as stored. ## Concurrency Updates can be made conditional. Templates, variants, themes, stencils, code lists, attributes, releases, environments, tenants and consumers carry a revision, which reading or updating one returns as a strong `ETag` header: a quoted decimal integer such as `\"7\"`. Send it back as `If-Match` on an update: if the resource changed since you read it, the update is refused with 412 `resource-modified` and nothing changes; read it again, reapply your change and retry. Without `If-Match` an update applies unconditionally, and the last write wins. What a revision covers: - a template: its own properties, data contract and data examples; - a variant: its title, description, attributes and template model, so `getVariant` and `getVariantContent` return the same `ETag`, and `updateVariant` and `updateVariantContent` take either; - a release: its name, default theme, presets and dependency declarations, so `getCatalogRelease` and `listCatalogDependencies` return the same `ETag`, and `updateCatalogRelease` and `updateCatalogDependencies` take either; - a code list: its properties and entries, whether each is hidden included, so `updateCodeListEntryHidden` takes the code list\'s `ETag`; - an environment: its name and production mark, not what it serves. ## Authentication Credentials go in the `Authorization` header: - **API key**, `Authorization: ApiKey <key>`: the supported method. A tenant manager issues each key for one tenant, with a set of tenant roles. The scheme name is case-insensitive. - **Bearer JWT** (**experimental**), `Authorization: Bearer <jwt>`: issued by an OAuth 2.0 identity provider, or self-signed with a key pair registered through the Consumers API. The [authentication guide](https://github.com/epistola-app/epistola-contract/blob/main/contracts/api/docs/auth.md) has the details. ## Authorization Each operation names the permissions it requires (`x-required-permissions`), such as `TEMPLATE_VIEW`, `TEMPLATE_EDIT`, `DOCUMENT_GENERATE` and `CATALOG_MANAGE`. A caller has them through its tenant roles (`CONTENT_VIEWER`, `CONTENT_AUTHOR`, `DOCUMENT_GENERATOR`, `CONTENT_PUBLISHER`, `TENANT_ADMINISTRATOR`), the roles stored on its API key. Managing tenants needs the platform role `TENANT_MANAGER`. ## Errors Errors are [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457) problem details, with `Content-Type: application/problem+json`: - `type` (URI): what went wrong, the stable value to switch on. It is `https://epistola.app/errors/{slug}`, which documents the problem type; - `title`: a short summary; - `status`: the HTTP status code; - `detail` (optional): what happened this time; - `instance` (optional): this occurrence. A problem may add members of its own, such as the field-level `errors` of a `validation-error`; ignore members you do not recognize. The problem types are listed, machine-readably, in this document\'s `x-problem-types` extension, and in the [error type registry](https://github.com/epistola-app/epistola-contract/blob/main/contracts/api/docs/error-types.md). New types may be added in a minor version, so keep a fallback when switching on them. ## Experimental parts and server support Operations and members marked `x-experimental: true`, the consumer model (Bearer JWT and the Consumers API) among them, may still change. Epistola Suite, the server that implements this contract, may not implement them yet, nor every part of the rest: deploying a draft, installing missing dependency releases when deploying, and recording who requested a document among them.
3
+ * Epistola generates documents, PDFs, from templates. Authors design the templates; applications send data and get documents back. This API manages templates and the catalogs that hold them, and generates documents from them, asynchronously and at volume. ## Glossary - **Tenant**: an organisation, isolated from every other. Everything else lives in one, under `/tenants/{tenantKey}`. - **Catalog**: a set of templates and everything they use, released as a whole. A catalog is named by three parts together: a **registry**, the DNS name of where it is published (`exchange.epistola.app`, or a domain that publishes its own, `acme.com`); a **namespace**, its publisher within that registry (`acme-corp`); and its key (`letters`). In a path, `~` stands for the server\'s default registry. The registry `local` names catalogs that never leave the organisation: valid within its own installations, refused by an Exchange. - **Release**: the catalog as a whole at one point, in one of two statuses. A **draft release**, or **draft**, is editable and has no version; a **released** release is immutable and has a version. \"Release `1.4.0`\" means the released one. - **Version**: the number of a released release, its `version` (`1.4.0`), a SemVer core version, or a patch release number (`1.3.1-gemeente-x.1`, see \"Versions and version ranges\"). A **version range**, `versionRange` (`^1.4.0`), selects the highest release that satisfies it, for a request that renders; it never matches a draft. - **Content hash**: what identifies a released release, its `contentHash` (`v6:…`), a hash of its content alone, not of its name or number: two releases with one content hash are the same release, whatever they are called. Names and numbers point at content hashes. - **Releasing**: turning a draft into a released release, as a version. A release keeps its id, its `releaseId`, assigned by the server, and its name when it is released, so a draft released as `1.4.1` is the same release, addressed by its `releaseId` or by `1.4.1`. - **Publishing**: making a catalog available in a registry, for other tenants and installations to install from. Only released releases are ever published; releasing is not publishing. - **Base**: the release a draft started from; its changes are measured against it. A draft is **behind** a release whose changes it may lack (see \"Releases\"). A changed resource is **ready** once someone marks it reviewed; a draft is released only when it changed something and all its changes are (`getCatalogChanges`). - **Editable** catalogs: every catalog has releases and drafts, wherever its releases come from (its **source**: an exchange, a registry, a file, or the server itself). Whether a catalog can be changed depends on the installation, which may only receive and run releases, and on whether the server supplies the catalog itself (`CatalogDto.editable`, `readOnlyReason`). - **Environment**: where documents are generated for a purpose, such as `staging` or `production`. A **deployment** makes an environment serve a release of a catalog; a request through the environment renders what it serves. - **Template**: one kind of document, with its data contract (the JSON Schema its data must meet) and data examples. A **variant** is one rendering of a template, for a language or a brand, chosen by its key or by **attributes** (such as `locale`); an attribute\'s values may come from a **code list** of `{code, label}` entries. A **stencil** is reusable template content, a **theme** a reusable set of styles, and a **preset** a named block style a catalog declares and its themes style. - **Consumer** (experimental): an application registered in a tenant, with its own permissions. ## Getting started 1. **Get an API key** from a tenant manager. A key belongs to one tenant and carries the roles it was issued with: `CONTENT_VIEWER` to find templates and read jobs and documents, and `DOCUMENT_GENERATOR` to generate. 2. **Send these headers** on every request (the client libraries set all but the key): ``` Authorization: ApiKey <key> Accept: application/vnd.epistola.v2+json Content-Type: application/vnd.epistola.v2+json (with a request body) User-Agent: epistola-contract/2.0.0 your-app/1.0 X-EP-Node-Id: <this host or pod> ``` 3. **Find your template.** `GET /tenants/{tenantKey}/catalogs` lists the catalogs, each with its `registry`, `namespace`, `catalogKey` and `highestVersion`. `GET /tenants/{tenantKey}/catalogs/{registry}/{namespace}/{catalogKey}/releases/{release}/templates`, with that version as `{release}`, lists that release\'s templates, and `getTemplate` shows a template\'s data contract. 4. **Generate.** `POST /tenants/{tenantKey}/documents/generate` with the template and its data: ```json {\"namespace\": \"acme-corp\", \"catalogKey\": \"letters\", \"templateKey\": \"invoice\", \"variantKey\": \"english\", \"data\": {\"customer\": {\"name\": \"Jane Smith\"}}} ``` It answers `202` with a `requestId` and, in `Location`, the job\'s address. Without a `versionRange` or an `environmentKey`, the catalog\'s highest release renders. 5. **Poll the job**, `GET /tenants/{tenantKey}/documents/jobs/{requestId}`, until `request.status` is `completed` (or `failed` or `cancelled`). Each item names its `documentId`. 6. **Download** the PDF: `GET /tenants/{tenantKey}/documents/{documentId}`. `validateTemplateData` checks data against a template\'s contract before you submit it, and `previewDocument` renders one document synchronously, for previews only. For high volume, poll no jobs: collect finished results as a stream instead (`collectGenerationResults`), each delivered to the node that asked for it and acknowledged when handled. That is the advanced path; the client libraries\' result collectors implement it. ## Template model A variant\'s content (`getVariantContent`, `updateVariantContent`) and a stencil\'s are a template document: a flat graph of nodes and slots, linked by id. A node is one block, of a component type such as `text`, `table` or `conditional`; a slot is a named place in a node that holds child nodes, such as a table\'s `cell-0-1` or a conditional\'s `body` and `else`. The catalog contract\'s [component registry](https://github.com/epistola-app/epistola-contract/blob/main/contracts/catalog/registry/component-registry.json) and [style registry](https://github.com/epistola-app/epistola-contract/blob/main/contracts/catalog/registry/style-registry.json) define every component and style, with examples, and the [template model guide](https://github.com/epistola-app/epistola-contract/blob/main/contracts/api/docs/template-model.md) walks through a complete letter: the example `updateVariantContent` shows. ## Media types The media type carries the API\'s major version. Contract 2.x uses `application/vnd.epistola.v2+json`, and `application/vnd.epistola.v2+ndjson` for the result stream, in `Accept` and in `Content-Type`. Problems are `application/problem+json`. ## Client identity Every request identifies the client with two headers: - **`User-Agent`** (required): [RFC 9110](https://www.rfc-editor.org/rfc/rfc9110#name-user-agent) product tokens, the first of which **must** be `epistola-contract/{version}`, the contract version the client was built against. Further tokens describe the rest of the stack: `epistola-contract/x.y.z valtimo-epistola-plugin/1.2.0 gzac/5.0.0`. - **`X-EP-Node-Id`** (required): the client node, such as its Kubernetes pod name, container id or hostname. The client libraries set both, the contract version and the hostname; an application can append its own product tokens and override the node id. ## Releases A catalog consists of releases, addressed as `/catalogs/{registry}/{namespace}/{catalogKey}/releases/{release}`, with the catalog\'s resources below each. A draft is addressed by its `releaseId`; a released release by its `releaseId` or its version, which address the same release. Every write to a released release is refused with 409. - A catalog that can be changed has **any number of drafts**, each named, each started from a released release (its base) or from another draft (`createCatalogRelease`). The base never moves. `listCatalogReleases` lists a catalog\'s releases, drafts included, each with its `status` (`?status=draft` for the drafts only) and, once released, its `contentHash` (`?contentHash=` for the releases with that content); a catalog (`CatalogDto`) does not list them. - **Any draft can be released.** Its version follows from the kind of change against its base: fixes raise the patch, additions the minor, anything that breaks callers the major (`previewCatalogDraftRelease`). The author may choose a higher version, never a lower one or one another release has. A fix to an older line is a draft from a release of that line: from `1.4.0`, while `1.5.0` and `2.0.0` exist, it is released as `1.4.1`. - **Drafts are independent copies**: releasing one changes no other. A draft is **behind** each release whose version is between its base and the version it would get, and each release released after it was started whose version is below that one; it lacks their changes unless an author applied them by hand. `getCatalogRelease` lists them, and releasing a draft that is behind must acknowledge them. - **Merging a release into a draft** (alpha, `x-experimental`): `previewCatalogDraftMerge` shows, per resource, per catalog setting (default theme and presets, entries of type `catalog`) and per catalog used (entries of type `catalogDependency`), each with the entries it goes with (`needs`), against the merge base (the closest release both descend from), what only the draft changed (`ours`), what only the release changed (`theirs`) and what both changed differently (`conflict`); `mergeIntoCatalogDraft` takes theirs and applies a resolution, `ours` or `theirs`, per conflict. The draft then contains the release and is no longer behind it; its base does not move. The preview\'s `token`, sent back as `expectedToken`, makes the merge apply what the preview showed or nothing (`merge-preview-outdated`). A conflict can also be resolved to content combined from its sides (`getCatalogDraftMergeSides`, then `mergedContent`), reviewed before the draft is released. The merge needs the merge base installed; the preview names one that is not (`missingBase`), and the merge is refused with `merge-base-missing`. - **Release registries** (alpha, `x-experimental`, ADR 0008) move releases between installations: an Epistola Exchange the installation is connected to, or a container registry it is configured with (`listReleaseRegistries`). A released release is published to one (`publishReleaseToRegistry`), and another installation lists the releases of a catalog there (`listRegistryReleases`) and installs one (`installRegistryRelease`) as an import does. A release registry is named by the installation; it is not the `{registry}` of a catalog\'s name. Documents are rendered from releases, and a version range never matches a draft. A draft renders only in a preview that names its `releaseId`, and in an environment it is deployed to. Importing a catalog archive (`importCatalog`) installs the release the archive carries, at its version, beside the releases the tenant already has; it never creates or changes a draft. A catalog with a source (`CatalogDto.source`) installs releases from it the same way (`installCatalogRelease`), and `listAvailableCatalogReleases` lists those the tenant does not have yet, older lines included. Nothing is updated in place or removed: deploying decides what an environment serves. A release keeps its id and number wherever it moves, so it is the same release in every installation. There are no catalog types: receiving releases works whether or not the catalog can be changed, and every write to one that cannot is refused with 409 `catalog-read-only`. ## Deploying An environment serves releases of catalogs (`deployCatalogRelease`): released ones, several of one catalog if need be, and at most one draft per catalog, rendered live. A request through the environment (`environmentKey`) renders: - with **no `versionRange`**: the catalog\'s deployed draft if there is one, else the highest release the environment serves; - with a **range or an exact version**: the highest served release that satisfies it. A draft never matches: it has no version. Rollback is undeploying the newer release. Deploying a draft replaces the draft the environment served for that catalog, and an environment marked **production** (`EnvironmentDto.production`) serves no draft. A document rendered from a draft carries the draft\'s `releaseId` and its name at render time (`releaseName`), with a null `version`, and its PDF a preview watermark. Releasing a deployed draft keeps its `releaseId`, so the environment then serves it as released; discarding the draft ends the deployment. ## Versions and version ranges A version (`ReleaseVersion`) is a SemVer core version, `MAJOR.MINOR.PATCH` without leading zeros, as the holder of the catalog\'s namespace issues it, or a **patch release** number, `MAJOR.MINOR.PATCH-<namespace>.<N>`, at most 128 characters. Wherever the contract names one exact version it has that form, and is called `version`; every member called `version` is one. A patch release is how someone who does not hold a catalog\'s namespace fixes a release of it (a municipality fixing a supplier\'s catalog): it is labelled with a namespace they hold, and numbered from 1, `1.3.1-gemeente-x.1`. As a SemVer pre-release it sorts below its core and above every release below that, `1.3.0` < `1.3.1-gemeente-x.1` < `1.3.1`, so the holder\'s next release supersedes it, and the two never collide: the holder never uses a label, the patcher never issues a plain number (contract ADR 0003). Which namespaces a tenant holds is the installation\'s to know; the contract checks the shape. \"Highest\" always means by this order, a patch release included. A request that selects a release to render or check (generation, preview, validation) takes a version range, `versionRange`, in the npm SemVer range grammar: an exact version (`1.4.0`), a caret (`^1.4.0`), a tilde (`~1.4.0`), comparators (`>=1.0.0 <2.0.0`), a hyphen range (`1.0.0 - 2.0.0`), or a `||` union of these. The highest release that satisfies it renders, and responses name the exact release used. A range is at most 256 characters, so an exact release number (at most 128) always fits, and a comparator pair of patch release numbers usually does. A range matches a patch release as npm matches a pre-release: only when one of its comparators names a pre-release of the same `MAJOR.MINOR.PATCH`, such as the exact number (`1.3.1-gemeente-x.1`) or `>=1.3.1-gemeente-x.1 <1.4.0`; `^1.3.0` never selects one. ## Catalog dependencies A catalog that uses another catalog\'s resources declares that catalog once, with the exact release of it that it renders with (`version`), never a range. References into the other catalog name the catalog but no version, so a release renders with exactly the releases its declarations pin. In a draft, a declaration may name a draft of the other catalog instead (`releaseId`), to build on work that is not released yet. A released release pins only released releases: releasing such a draft is refused (`release-dependencies-unreleased`) unless the request releases those drafts along with it (`releaseDependencies`), in one transaction. ## Catalog identity A catalog\'s key alone is not unique: two publishers can each publish `letters`. The registry and the namespace complete its name, and the same namespace in two registries is two namespaces. Which registry is a server\'s default is configuration; in a path, `/catalogs/~/acme-corp/letters/…` and `/catalogs/exchange.epistola.app/acme-corp/letters/…` address the same catalog when `exchange.epistola.app` is the default, and `~` may be sent percent-encoded as `%7E`. In a body, a catalog is named by separate `registry`, `namespace` and `catalogKey` members, and a reference into another catalog by an alias: 1. **A request that names a catalog** (a generation or preview target, a dependency declaration) may omit `registry`, or send null, for the default registry. (An import\'s `registry` defaults to the one the archive names.) 2. **A reference from one catalog\'s release to a resource of another** names that catalog by the **alias** the release\'s dependency declarations give it (`CatalogAlias`, in the member `catalogKey`), never by registry or namespace: a template model\'s `themeRef`, its stencil and image nodes, a `fontFamily` (catalog content, portable catalog wire v8, contract ADR 0003), and the references this API reads and writes beside it, a release\'s default theme (`CatalogThemeReference`), an attribute\'s code-list binding and an attribute criterion in variant selection (`VariantSelectionAttribute`, resolved through the release that renders). Omitted or null, or the catalog\'s own key, is the catalog itself. A declaration (`CatalogDependencyDto`, `listCatalogDependencies`) maps each alias to the catalog\'s full name and the release it pins; that is where a client finds the name. Because content names the alias, it means the same in every installation and under any name, and pinning another release changes no content. An alias is by default the catalog\'s key (`CatalogDependencyRequirement.alias`). Responses write every registry in full, by its name, never `~`, so a value read from one installation means the same catalog on another. Content documents are returned as stored. ## Concurrency Updates can be made conditional. Templates, variants, themes, stencils, code lists, attributes, releases, environments, tenants and consumers carry a revision, which reading or updating one returns as a strong `ETag` header: a quoted decimal integer such as `\"7\"`. Send it back as `If-Match` on an update: if the resource changed since you read it, the update is refused with 412 `resource-modified` and nothing changes; read it again, reapply your change and retry. Without `If-Match` an update applies unconditionally, and the last write wins. What a revision covers: - a template: its own properties, data contract and data examples; - a variant: its title, description, attributes and template model, so `getVariant` and `getVariantContent` return the same `ETag`, and `updateVariant` and `updateVariantContent` take either; - a release: its name, default theme, presets and dependency declarations, so `getCatalogRelease` and `listCatalogDependencies` return the same `ETag`, and `updateCatalogRelease` and `updateCatalogDependencies` take either; - a code list: its properties and entries, whether each is hidden included, so `updateCodeListEntryHidden` takes the code list\'s `ETag`; - an environment: its name and production mark, not what it serves. ## Authentication Credentials go in the `Authorization` header: - **API key**, `Authorization: ApiKey <key>`: the supported method. A tenant manager issues each key for one tenant, with a set of tenant roles. The scheme name is case-insensitive. - **Bearer JWT** (**experimental**), `Authorization: Bearer <jwt>`: issued by an OAuth 2.0 identity provider, or self-signed with a key pair registered through the Consumers API. The [authentication guide](https://github.com/epistola-app/epistola-contract/blob/main/contracts/api/docs/auth.md) has the details. ## Authorization Each operation names the permissions it requires (`x-required-permissions`), such as `TEMPLATE_VIEW`, `TEMPLATE_EDIT`, `DOCUMENT_GENERATE` and `CATALOG_MANAGE`. A caller has them through its tenant roles (`CONTENT_VIEWER`, `CONTENT_AUTHOR`, `DOCUMENT_GENERATOR`, `CONTENT_PUBLISHER`, `TENANT_ADMINISTRATOR`), the roles stored on its API key. Managing tenants needs the platform role `TENANT_MANAGER`. ## Errors Errors are [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457) problem details, with `Content-Type: application/problem+json`: - `type` (URI): what went wrong, the stable value to switch on. It is `https://epistola.app/errors/{slug}`, which documents the problem type; - `title`: a short summary; - `status`: the HTTP status code; - `detail` (optional): what happened this time; - `instance` (optional): this occurrence. A problem may add members of its own, such as the field-level `errors` of a `validation-error`; ignore members you do not recognize. The problem types are listed, machine-readably, in this document\'s `x-problem-types` extension, and in the [error type registry](https://github.com/epistola-app/epistola-contract/blob/main/contracts/api/docs/error-types.md). A server answers only with the types registered there. A type names a problem a caller can act on differently; anything else is the generic type of its status, so a missing resource is `not-found` whichever resource it is, and a refused authorization `forbidden`. New types may be added in a minor version: handle a type you do not recognize by its `status`, as the generic type of that status, and keep a fallback when switching on them. ## Experimental parts and server support Operations and members marked `x-experimental: true`, the consumer model (Bearer JWT and the Consumers API) among them, may still change. Epistola Suite, the server that implements this contract, may not implement them yet, nor every part of the rest: installing missing dependency releases when deploying, recording who requested a document, an attribute\'s `description`, listing a stencil\'s usage in a released release, and a dependency alias other than the catalog\'s key among them. An operation a server does not implement yet answers 501 `operation-not-implemented`.
4
4
  *
5
- * The version of the OpenAPI document: 2.0.0-alpha.3
5
+ * The version of the OpenAPI document: 2.0.0-alpha.4
6
6
  *
7
7
  *
8
8
  * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).
@@ -177,19 +177,6 @@ export interface ListAttributesRequest {
177
177
  * Number of items per page
178
178
  */
179
179
  size?: number;
180
- /**
181
- * Field to sort by. The set of allowed fields depends on the resource; an
182
- * unsupported value is rejected by the server, which also applies the
183
- * per-resource default when omitted.
184
- *
185
- */
186
- sort?: string;
187
- /**
188
- * Sort direction, applied when a `sort` field is selected. An unsupported value
189
- * is rejected.
190
- *
191
- */
192
- direction?: ListAttributesDirectionEnum;
193
180
  }
194
181
  export interface UpdateAttributeOperationRequest {
195
182
  /**
@@ -308,22 +295,14 @@ export declare class AttributesApi extends runtime.BaseAPI {
308
295
  */
309
296
  updateAttributeRequestOpts(requestParameters: UpdateAttributeOperationRequest): Promise<runtime.RequestOpts>;
310
297
  /**
311
- * Update an attribute definition\'s `displayName`, `description` and constraint: its inline `allowedValues`, or the code list it binds (`codeListBinding`). Omitted or null members are left as they are; `clearCodeListBinding: true` removes the binding. The constraint may switch kind, as `UpdateAttributeRequest` describes; mixing both kinds, or a `codeListBinding` together with `clearCodeListBinding`, is refused with 400 `validation-error`, and an attribute of a catalog that cannot be changed with 409 `catalog-read-only`. Send the `ETag` from a read as `If-Match` to have the update refused with 412 `resource-modified` if the resource changed since; without it, the last write wins.
298
+ * Update an attribute definition\'s `name` and constraint: its inline `allowedValues`, or the code list it binds (`codeListBinding`). Omitted or null members are left as they are; `clearCodeListBinding: true` removes the binding. The constraint may switch kind, as `UpdateAttributeRequest` describes; mixing both kinds, or a `codeListBinding` together with `clearCodeListBinding`, is refused with 400 `validation-error`, and an attribute of a catalog that cannot be changed with 409 `catalog-read-only`. Send the `ETag` from a read as `If-Match` to have the update refused with 412 `resource-modified` if the resource changed since; without it, the last write wins.
312
299
  * Update an attribute definition
313
300
  */
314
301
  updateAttributeRaw(requestParameters: UpdateAttributeOperationRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<runtime.ApiResponse<AttributeDto>>;
315
302
  /**
316
- * Update an attribute definition\'s `displayName`, `description` and constraint: its inline `allowedValues`, or the code list it binds (`codeListBinding`). Omitted or null members are left as they are; `clearCodeListBinding: true` removes the binding. The constraint may switch kind, as `UpdateAttributeRequest` describes; mixing both kinds, or a `codeListBinding` together with `clearCodeListBinding`, is refused with 400 `validation-error`, and an attribute of a catalog that cannot be changed with 409 `catalog-read-only`. Send the `ETag` from a read as `If-Match` to have the update refused with 412 `resource-modified` if the resource changed since; without it, the last write wins.
303
+ * Update an attribute definition\'s `name` and constraint: its inline `allowedValues`, or the code list it binds (`codeListBinding`). Omitted or null members are left as they are; `clearCodeListBinding: true` removes the binding. The constraint may switch kind, as `UpdateAttributeRequest` describes; mixing both kinds, or a `codeListBinding` together with `clearCodeListBinding`, is refused with 400 `validation-error`, and an attribute of a catalog that cannot be changed with 409 `catalog-read-only`. Send the `ETag` from a read as `If-Match` to have the update refused with 412 `resource-modified` if the resource changed since; without it, the last write wins.
317
304
  * Update an attribute definition
318
305
  */
319
306
  updateAttribute(requestParameters: UpdateAttributeOperationRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<AttributeDto>;
320
307
  }
321
- /**
322
- * @export
323
- */
324
- export declare const ListAttributesDirectionEnum: {
325
- readonly Asc: 'asc';
326
- readonly Desc: 'desc';
327
- };
328
- export type ListAttributesDirectionEnum = typeof ListAttributesDirectionEnum[keyof typeof ListAttributesDirectionEnum];
329
308
  //# sourceMappingURL=AttributesApi.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"AttributesApi.d.ts","sourceRoot":"","sources":["../../../../src/generated/api/apis/AttributesApi.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"AttributesApi.d.ts","sourceRoot":"","sources":["../../../../src/generated/api/apis/AttributesApi.ts"],"names":[],"mappings":"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"}
@@ -2,9 +2,9 @@
2
2
  /* eslint-disable */
3
3
  /**
4
4
  * Epistola API
5
- * Epistola generates documents, PDFs, from templates. Authors design the templates; applications send data and get documents back. This API manages templates and the catalogs that hold them, and generates documents from them, asynchronously and at volume. ## Glossary - **Tenant**: an organisation, isolated from every other. Everything else lives in one, under `/tenants/{tenantKey}`. - **Catalog**: a set of templates and everything they use, released as a whole. A catalog is named by three parts together: a **registry**, the DNS name of where it is published (`exchange.epistola.app`, or a domain that publishes its own, `acme.com`); a **namespace**, its publisher within that registry (`acme-corp`); and its key (`letters`). In a path, `~` stands for the server\'s default registry. The registry `local` names catalogs that never leave the organisation: valid within its own installations, refused by an Exchange. - **Release**: the catalog as a whole at one point, in one of two statuses. A **draft release**, or **draft**, is editable and has no version; a **released** release is immutable and has a version. \"Release `1.4.0`\" means the released one. - **Version**: the number of a released release, its `version` (`1.4.0`), a SemVer core version, or a patch release number (`1.3.1-gemeente-x.1`, see \"Versions and version ranges\"). A **version range**, `versionRange` (`^1.4.0`), selects the highest release that satisfies it, for a request that renders; it never matches a draft. - **Content hash**: what identifies a released release, its `contentHash` (`v6:…`), a hash of its content alone, not of its name or number: two releases with one content hash are the same release, whatever they are called. Names and numbers point at content hashes. - **Releasing**: turning a draft into a released release, as a version. A release keeps its id, its `releaseId`, assigned by the server, and its name when it is released, so a draft released as `1.4.1` is the same release, addressed by its `releaseId` or by `1.4.1`. - **Publishing**: making a catalog available in a registry, for other tenants and installations to install from. Only released releases are ever published; releasing is not publishing. - **Base**: the release a draft started from; its changes are measured against it. A draft is **behind** a release whose changes it may lack (see \"Releases\"). A changed resource is **ready** once someone marks it reviewed; a draft is released only when it changed something and all its changes are (`getCatalogChanges`). - **Editable** catalogs: every catalog has releases and drafts, wherever its releases come from (its **source**: an exchange, a registry, a file, or the server itself). Whether a catalog can be changed depends on the installation, which may only receive and run releases, and on whether the server supplies the catalog itself (`CatalogDto.editable`, `readOnlyReason`). - **Environment**: where documents are generated for a purpose, such as `staging` or `production`. A **deployment** makes an environment serve a release of a catalog; a request through the environment renders what it serves. - **Template**: one kind of document, with its data contract (the JSON Schema its data must meet) and data examples. A **variant** is one rendering of a template, for a language or a brand, chosen by its key or by **attributes** (such as `locale`); an attribute\'s values may come from a **code list** of `{code, label}` entries. A **stencil** is reusable template content, a **theme** a reusable set of styles, and a **preset** a named block style a catalog declares and its themes style. - **Consumer** (experimental): an application registered in a tenant, with its own permissions. ## Getting started 1. **Get an API key** from a tenant manager. A key belongs to one tenant and carries the roles it was issued with: `CONTENT_VIEWER` to find templates and read jobs and documents, and `DOCUMENT_GENERATOR` to generate. 2. **Send these headers** on every request (the client libraries set all but the key): ``` Authorization: ApiKey <key> Accept: application/vnd.epistola.v2+json Content-Type: application/vnd.epistola.v2+json (with a request body) User-Agent: epistola-contract/2.0.0 your-app/1.0 X-EP-Node-Id: <this host or pod> ``` 3. **Find your template.** `GET /tenants/{tenantKey}/catalogs` lists the catalogs, each with its `registry`, `namespace`, `catalogKey` and `highestVersion`. `GET /tenants/{tenantKey}/catalogs/{registry}/{namespace}/{catalogKey}/releases/{release}/templates`, with that version as `{release}`, lists that release\'s templates, and `getTemplate` shows a template\'s data contract. 4. **Generate.** `POST /tenants/{tenantKey}/documents/generate` with the template and its data: ```json {\"namespace\": \"acme-corp\", \"catalogKey\": \"letters\", \"templateKey\": \"invoice\", \"variantKey\": \"english\", \"data\": {\"customer\": {\"name\": \"Jane Smith\"}}} ``` It answers `202` with a `requestId` and, in `Location`, the job\'s address. Without a `versionRange` or an `environmentKey`, the catalog\'s highest release renders. 5. **Poll the job**, `GET /tenants/{tenantKey}/documents/jobs/{requestId}`, until `request.status` is `completed` (or `failed` or `cancelled`). Each item names its `documentId`. 6. **Download** the PDF: `GET /tenants/{tenantKey}/documents/{documentId}`. `validateTemplateData` checks data against a template\'s contract before you submit it, and `previewDocument` renders one document synchronously, for previews only. For high volume, poll no jobs: collect finished results as a stream instead (`collectGenerationResults`), each delivered to the node that asked for it and acknowledged when handled. That is the advanced path; the client libraries\' result collectors implement it. ## Template model A variant\'s content (`getVariantContent`, `updateVariantContent`) and a stencil\'s are a template document: a flat graph of nodes and slots, linked by id. A node is one block, of a component type such as `text`, `table` or `conditional`; a slot is a named place in a node that holds child nodes, such as a table\'s `cell-0-1` or a conditional\'s `body` and `else`. The catalog contract\'s [component registry](https://github.com/epistola-app/epistola-contract/blob/main/contracts/catalog/registry/component-registry.json) and [style registry](https://github.com/epistola-app/epistola-contract/blob/main/contracts/catalog/registry/style-registry.json) define every component and style, with examples, and the [template model guide](https://github.com/epistola-app/epistola-contract/blob/main/contracts/api/docs/template-model.md) walks through a complete letter: the example `updateVariantContent` shows. ## Media types The media type carries the API\'s major version. Contract 2.x uses `application/vnd.epistola.v2+json`, and `application/vnd.epistola.v2+ndjson` for the result stream, in `Accept` and in `Content-Type`. Problems are `application/problem+json`. ## Client identity Every request identifies the client with two headers: - **`User-Agent`** (required): [RFC 9110](https://www.rfc-editor.org/rfc/rfc9110#name-user-agent) product tokens, the first of which **must** be `epistola-contract/{version}`, the contract version the client was built against. Further tokens describe the rest of the stack: `epistola-contract/x.y.z valtimo-epistola-plugin/1.2.0 gzac/5.0.0`. - **`X-EP-Node-Id`** (required): the client node, such as its Kubernetes pod name, container id or hostname. The client libraries set both, the contract version and the hostname; an application can append its own product tokens and override the node id. ## Releases A catalog consists of releases, addressed as `/catalogs/{registry}/{namespace}/{catalogKey}/releases/{release}`, with the catalog\'s resources below each. A draft is addressed by its `releaseId`; a released release by its `releaseId` or its version, which address the same release. Every write to a released release is refused with 409. - A catalog that can be changed has **any number of drafts**, each named, each started from a released release (its base) or from another draft (`createCatalogRelease`). The base never moves. `listCatalogReleases` lists a catalog\'s releases, drafts included, each with its `status` (`?status=draft` for the drafts only) and, once released, its `contentHash` (`?contentHash=` for the releases with that content); a catalog (`CatalogDto`) does not list them. - **Any draft can be released.** Its version follows from the kind of change against its base: fixes raise the patch, additions the minor, anything that breaks callers the major (`previewCatalogDraftRelease`). The author may choose a higher version, never a lower one or one another release has. A fix to an older line is a draft from a release of that line: from `1.4.0`, while `1.5.0` and `2.0.0` exist, it is released as `1.4.1`. - **Drafts are independent copies**: releasing one changes no other. A draft is **behind** each release whose version is between its base and the version it would get, and each release released after it was started whose version is below that one; it lacks their changes unless an author applied them by hand. `getCatalogRelease` lists them, and releasing a draft that is behind must acknowledge them. - **Merging a release into a draft** (alpha, `x-experimental`): `previewCatalogDraftMerge` shows, per resource, per catalog setting (default theme and presets, entries of type `catalog`) and per catalog used (entries of type `catalogDependency`), each with the entries it goes with (`needs`), against the merge base (the closest release both descend from), what only the draft changed (`ours`), what only the release changed (`theirs`) and what both changed differently (`conflict`); `mergeIntoCatalogDraft` takes theirs and applies a resolution, `ours` or `theirs`, per conflict. The draft then contains the release and is no longer behind it; its base does not move. The preview\'s `token`, sent back as `expectedToken`, makes the merge apply what the preview showed or nothing (`merge-preview-outdated`). A conflict can also be resolved to content combined from its sides (`getCatalogDraftMergeSides`, then `mergedContent`), reviewed before the draft is released. The merge needs the merge base installed; the preview names one that is not (`missingBase`), and the merge is refused with `merge-base-missing`. - **Release registries** (alpha, `x-experimental`, ADR 0008) move releases between installations: an Epistola Exchange the installation is connected to, or a container registry it is configured with (`listReleaseRegistries`). A released release is published to one (`publishReleaseToRegistry`), and another installation lists the releases of a catalog there (`listRegistryReleases`) and installs one (`installRegistryRelease`) as an import does. A release registry is named by the installation; it is not the `{registry}` of a catalog\'s name. Documents are rendered from releases, and a version range never matches a draft. A draft renders only in a preview that names its `releaseId`, and in an environment it is deployed to. Importing a catalog archive (`importCatalog`) installs the release the archive carries, at its version, beside the releases the tenant already has; it never creates or changes a draft. A catalog with a source (`CatalogDto.source`) installs releases from it the same way (`installCatalogRelease`), and `listAvailableCatalogReleases` lists those the tenant does not have yet, older lines included. Nothing is updated in place or removed: deploying decides what an environment serves. A release keeps its id and number wherever it moves, so it is the same release in every installation. There are no catalog types: receiving releases works whether or not the catalog can be changed, and every write to one that cannot is refused with 409 `catalog-read-only`. ## Deploying An environment serves releases of catalogs (`deployCatalogRelease`): released ones, several of one catalog if need be, and at most one draft per catalog, rendered live. A request through the environment (`environmentKey`) renders: - with **no `versionRange`**: the catalog\'s deployed draft if there is one, else the highest release the environment serves; - with a **range or an exact version**: the highest served release that satisfies it. A draft never matches: it has no version. Rollback is undeploying the newer release. Deploying a draft replaces the draft the environment served for that catalog, and an environment marked **production** (`EnvironmentDto.production`) serves no draft. A document rendered from a draft carries the draft\'s `releaseId` and its name at render time (`draftLabel`), with a null `version`, and its PDF a preview watermark. Releasing a deployed draft keeps its `releaseId`, so the environment then serves it as released; discarding the draft ends the deployment. ## Versions and version ranges A version (`ReleaseVersion`) is a SemVer core version, `MAJOR.MINOR.PATCH` without leading zeros, as the holder of the catalog\'s namespace issues it, or a **patch release** number, `MAJOR.MINOR.PATCH-<namespace>.<N>`, at most 128 characters. Wherever the contract names one exact version it has that form, and is called `version`; every member called `version` is one. A patch release is how someone who does not hold a catalog\'s namespace fixes a release of it (a municipality fixing a supplier\'s catalog): it is labelled with a namespace they hold, and numbered from 1, `1.3.1-gemeente-x.1`. As a SemVer pre-release it sorts below its core and above every release below that, `1.3.0` < `1.3.1-gemeente-x.1` < `1.3.1`, so the holder\'s next release supersedes it, and the two never collide: the holder never uses a label, the patcher never issues a plain number (contract ADR 0003). Which namespaces a tenant holds is the installation\'s to know; the contract checks the shape. \"Highest\" always means by this order, a patch release included. A request that selects a release to render or check (generation, preview, validation) takes a version range, `versionRange`, in the npm SemVer range grammar: an exact version (`1.4.0`), a caret (`^1.4.0`), a tilde (`~1.4.0`), comparators (`>=1.0.0 <2.0.0`), a hyphen range (`1.0.0 - 2.0.0`), or a `||` union of these. The highest release that satisfies it renders, and responses name the exact release used. A range is at most 256 characters, so an exact release number (at most 128) always fits, and a comparator pair of patch release numbers usually does. A range matches a patch release as npm matches a pre-release: only when one of its comparators names a pre-release of the same `MAJOR.MINOR.PATCH`, such as the exact number (`1.3.1-gemeente-x.1`) or `>=1.3.1-gemeente-x.1 <1.4.0`; `^1.3.0` never selects one. ## Catalog dependencies A catalog that uses another catalog\'s resources declares that catalog once, with the exact release of it that it renders with (`version`), never a range. References into the other catalog name the catalog but no version, so a release renders with exactly the releases its declarations pin. In a draft, a declaration may name a draft of the other catalog instead (`releaseId`), to build on work that is not released yet. A released release pins only released releases: releasing such a draft is refused (`release-dependencies-unreleased`) unless the request releases those drafts along with it (`releaseDependencies`), in one transaction. ## Catalog identity A catalog\'s key alone is not unique: two publishers can each publish `letters`. The registry and the namespace complete its name, and the same namespace in two registries is two namespaces. Which registry is a server\'s default is configuration; in a path, `/catalogs/~/acme-corp/letters/…` and `/catalogs/exchange.epistola.app/acme-corp/letters/…` address the same catalog when `exchange.epistola.app` is the default, and `~` may be sent percent-encoded as `%7E`. In a body, a catalog is named by separate `registry`, `namespace` and `catalogKey` members, and a reference into another catalog by an alias: 1. **A request that names a catalog** (a generation or preview target, a dependency declaration) may omit `registry`, or send null, for the default registry. (An import\'s `registry` defaults to the one the archive names.) 2. **A reference from one catalog\'s release to a resource of another** names that catalog by the **alias** the release\'s dependency declarations give it (`CatalogAlias`, in the member `catalogKey`), never by registry or namespace: a template model\'s `themeRef`, its stencil and image nodes, a `fontFamily` (catalog content, portable catalog wire v8, contract ADR 0003), and the references this API reads and writes beside it, a release\'s default theme (`CatalogThemeReference`), an attribute\'s code-list binding and an attribute criterion in variant selection (`VariantSelectionAttribute`, resolved through the release that renders). Omitted or null, or the catalog\'s own key, is the catalog itself. A declaration (`CatalogDependencyDto`, `listCatalogDependencies`) maps each alias to the catalog\'s full name and the release it pins; that is where a client finds the name. Because content names the alias, it means the same in every installation and under any name, and pinning another release changes no content. An alias is by default the catalog\'s key (`CatalogDependencyRequirement.alias`). Responses write every registry in full, by its name, never `~`, so a value read from one installation means the same catalog on another. Content documents are returned as stored. ## Concurrency Updates can be made conditional. Templates, variants, themes, stencils, code lists, attributes, releases, environments, tenants and consumers carry a revision, which reading or updating one returns as a strong `ETag` header: a quoted decimal integer such as `\"7\"`. Send it back as `If-Match` on an update: if the resource changed since you read it, the update is refused with 412 `resource-modified` and nothing changes; read it again, reapply your change and retry. Without `If-Match` an update applies unconditionally, and the last write wins. What a revision covers: - a template: its own properties, data contract and data examples; - a variant: its title, description, attributes and template model, so `getVariant` and `getVariantContent` return the same `ETag`, and `updateVariant` and `updateVariantContent` take either; - a release: its name, default theme, presets and dependency declarations, so `getCatalogRelease` and `listCatalogDependencies` return the same `ETag`, and `updateCatalogRelease` and `updateCatalogDependencies` take either; - a code list: its properties and entries, whether each is hidden included, so `updateCodeListEntryHidden` takes the code list\'s `ETag`; - an environment: its name and production mark, not what it serves. ## Authentication Credentials go in the `Authorization` header: - **API key**, `Authorization: ApiKey <key>`: the supported method. A tenant manager issues each key for one tenant, with a set of tenant roles. The scheme name is case-insensitive. - **Bearer JWT** (**experimental**), `Authorization: Bearer <jwt>`: issued by an OAuth 2.0 identity provider, or self-signed with a key pair registered through the Consumers API. The [authentication guide](https://github.com/epistola-app/epistola-contract/blob/main/contracts/api/docs/auth.md) has the details. ## Authorization Each operation names the permissions it requires (`x-required-permissions`), such as `TEMPLATE_VIEW`, `TEMPLATE_EDIT`, `DOCUMENT_GENERATE` and `CATALOG_MANAGE`. A caller has them through its tenant roles (`CONTENT_VIEWER`, `CONTENT_AUTHOR`, `DOCUMENT_GENERATOR`, `CONTENT_PUBLISHER`, `TENANT_ADMINISTRATOR`), the roles stored on its API key. Managing tenants needs the platform role `TENANT_MANAGER`. ## Errors Errors are [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457) problem details, with `Content-Type: application/problem+json`: - `type` (URI): what went wrong, the stable value to switch on. It is `https://epistola.app/errors/{slug}`, which documents the problem type; - `title`: a short summary; - `status`: the HTTP status code; - `detail` (optional): what happened this time; - `instance` (optional): this occurrence. A problem may add members of its own, such as the field-level `errors` of a `validation-error`; ignore members you do not recognize. The problem types are listed, machine-readably, in this document\'s `x-problem-types` extension, and in the [error type registry](https://github.com/epistola-app/epistola-contract/blob/main/contracts/api/docs/error-types.md). New types may be added in a minor version, so keep a fallback when switching on them. ## Experimental parts and server support Operations and members marked `x-experimental: true`, the consumer model (Bearer JWT and the Consumers API) among them, may still change. Epistola Suite, the server that implements this contract, may not implement them yet, nor every part of the rest: deploying a draft, installing missing dependency releases when deploying, and recording who requested a document among them.
5
+ * Epistola generates documents, PDFs, from templates. Authors design the templates; applications send data and get documents back. This API manages templates and the catalogs that hold them, and generates documents from them, asynchronously and at volume. ## Glossary - **Tenant**: an organisation, isolated from every other. Everything else lives in one, under `/tenants/{tenantKey}`. - **Catalog**: a set of templates and everything they use, released as a whole. A catalog is named by three parts together: a **registry**, the DNS name of where it is published (`exchange.epistola.app`, or a domain that publishes its own, `acme.com`); a **namespace**, its publisher within that registry (`acme-corp`); and its key (`letters`). In a path, `~` stands for the server\'s default registry. The registry `local` names catalogs that never leave the organisation: valid within its own installations, refused by an Exchange. - **Release**: the catalog as a whole at one point, in one of two statuses. A **draft release**, or **draft**, is editable and has no version; a **released** release is immutable and has a version. \"Release `1.4.0`\" means the released one. - **Version**: the number of a released release, its `version` (`1.4.0`), a SemVer core version, or a patch release number (`1.3.1-gemeente-x.1`, see \"Versions and version ranges\"). A **version range**, `versionRange` (`^1.4.0`), selects the highest release that satisfies it, for a request that renders; it never matches a draft. - **Content hash**: what identifies a released release, its `contentHash` (`v6:…`), a hash of its content alone, not of its name or number: two releases with one content hash are the same release, whatever they are called. Names and numbers point at content hashes. - **Releasing**: turning a draft into a released release, as a version. A release keeps its id, its `releaseId`, assigned by the server, and its name when it is released, so a draft released as `1.4.1` is the same release, addressed by its `releaseId` or by `1.4.1`. - **Publishing**: making a catalog available in a registry, for other tenants and installations to install from. Only released releases are ever published; releasing is not publishing. - **Base**: the release a draft started from; its changes are measured against it. A draft is **behind** a release whose changes it may lack (see \"Releases\"). A changed resource is **ready** once someone marks it reviewed; a draft is released only when it changed something and all its changes are (`getCatalogChanges`). - **Editable** catalogs: every catalog has releases and drafts, wherever its releases come from (its **source**: an exchange, a registry, a file, or the server itself). Whether a catalog can be changed depends on the installation, which may only receive and run releases, and on whether the server supplies the catalog itself (`CatalogDto.editable`, `readOnlyReason`). - **Environment**: where documents are generated for a purpose, such as `staging` or `production`. A **deployment** makes an environment serve a release of a catalog; a request through the environment renders what it serves. - **Template**: one kind of document, with its data contract (the JSON Schema its data must meet) and data examples. A **variant** is one rendering of a template, for a language or a brand, chosen by its key or by **attributes** (such as `locale`); an attribute\'s values may come from a **code list** of `{code, label}` entries. A **stencil** is reusable template content, a **theme** a reusable set of styles, and a **preset** a named block style a catalog declares and its themes style. - **Consumer** (experimental): an application registered in a tenant, with its own permissions. ## Getting started 1. **Get an API key** from a tenant manager. A key belongs to one tenant and carries the roles it was issued with: `CONTENT_VIEWER` to find templates and read jobs and documents, and `DOCUMENT_GENERATOR` to generate. 2. **Send these headers** on every request (the client libraries set all but the key): ``` Authorization: ApiKey <key> Accept: application/vnd.epistola.v2+json Content-Type: application/vnd.epistola.v2+json (with a request body) User-Agent: epistola-contract/2.0.0 your-app/1.0 X-EP-Node-Id: <this host or pod> ``` 3. **Find your template.** `GET /tenants/{tenantKey}/catalogs` lists the catalogs, each with its `registry`, `namespace`, `catalogKey` and `highestVersion`. `GET /tenants/{tenantKey}/catalogs/{registry}/{namespace}/{catalogKey}/releases/{release}/templates`, with that version as `{release}`, lists that release\'s templates, and `getTemplate` shows a template\'s data contract. 4. **Generate.** `POST /tenants/{tenantKey}/documents/generate` with the template and its data: ```json {\"namespace\": \"acme-corp\", \"catalogKey\": \"letters\", \"templateKey\": \"invoice\", \"variantKey\": \"english\", \"data\": {\"customer\": {\"name\": \"Jane Smith\"}}} ``` It answers `202` with a `requestId` and, in `Location`, the job\'s address. Without a `versionRange` or an `environmentKey`, the catalog\'s highest release renders. 5. **Poll the job**, `GET /tenants/{tenantKey}/documents/jobs/{requestId}`, until `request.status` is `completed` (or `failed` or `cancelled`). Each item names its `documentId`. 6. **Download** the PDF: `GET /tenants/{tenantKey}/documents/{documentId}`. `validateTemplateData` checks data against a template\'s contract before you submit it, and `previewDocument` renders one document synchronously, for previews only. For high volume, poll no jobs: collect finished results as a stream instead (`collectGenerationResults`), each delivered to the node that asked for it and acknowledged when handled. That is the advanced path; the client libraries\' result collectors implement it. ## Template model A variant\'s content (`getVariantContent`, `updateVariantContent`) and a stencil\'s are a template document: a flat graph of nodes and slots, linked by id. A node is one block, of a component type such as `text`, `table` or `conditional`; a slot is a named place in a node that holds child nodes, such as a table\'s `cell-0-1` or a conditional\'s `body` and `else`. The catalog contract\'s [component registry](https://github.com/epistola-app/epistola-contract/blob/main/contracts/catalog/registry/component-registry.json) and [style registry](https://github.com/epistola-app/epistola-contract/blob/main/contracts/catalog/registry/style-registry.json) define every component and style, with examples, and the [template model guide](https://github.com/epistola-app/epistola-contract/blob/main/contracts/api/docs/template-model.md) walks through a complete letter: the example `updateVariantContent` shows. ## Media types The media type carries the API\'s major version. Contract 2.x uses `application/vnd.epistola.v2+json`, and `application/vnd.epistola.v2+ndjson` for the result stream, in `Accept` and in `Content-Type`. Problems are `application/problem+json`. ## Client identity Every request identifies the client with two headers: - **`User-Agent`** (required): [RFC 9110](https://www.rfc-editor.org/rfc/rfc9110#name-user-agent) product tokens, the first of which **must** be `epistola-contract/{version}`, the contract version the client was built against. Further tokens describe the rest of the stack: `epistola-contract/x.y.z valtimo-epistola-plugin/1.2.0 gzac/5.0.0`. - **`X-EP-Node-Id`** (required): the client node, such as its Kubernetes pod name, container id or hostname. The client libraries set both, the contract version and the hostname; an application can append its own product tokens and override the node id. ## Releases A catalog consists of releases, addressed as `/catalogs/{registry}/{namespace}/{catalogKey}/releases/{release}`, with the catalog\'s resources below each. A draft is addressed by its `releaseId`; a released release by its `releaseId` or its version, which address the same release. Every write to a released release is refused with 409. - A catalog that can be changed has **any number of drafts**, each named, each started from a released release (its base) or from another draft (`createCatalogRelease`). The base never moves. `listCatalogReleases` lists a catalog\'s releases, drafts included, each with its `status` (`?status=draft` for the drafts only) and, once released, its `contentHash` (`?contentHash=` for the releases with that content); a catalog (`CatalogDto`) does not list them. - **Any draft can be released.** Its version follows from the kind of change against its base: fixes raise the patch, additions the minor, anything that breaks callers the major (`previewCatalogDraftRelease`). The author may choose a higher version, never a lower one or one another release has. A fix to an older line is a draft from a release of that line: from `1.4.0`, while `1.5.0` and `2.0.0` exist, it is released as `1.4.1`. - **Drafts are independent copies**: releasing one changes no other. A draft is **behind** each release whose version is between its base and the version it would get, and each release released after it was started whose version is below that one; it lacks their changes unless an author applied them by hand. `getCatalogRelease` lists them, and releasing a draft that is behind must acknowledge them. - **Merging a release into a draft** (alpha, `x-experimental`): `previewCatalogDraftMerge` shows, per resource, per catalog setting (default theme and presets, entries of type `catalog`) and per catalog used (entries of type `catalogDependency`), each with the entries it goes with (`needs`), against the merge base (the closest release both descend from), what only the draft changed (`ours`), what only the release changed (`theirs`) and what both changed differently (`conflict`); `mergeIntoCatalogDraft` takes theirs and applies a resolution, `ours` or `theirs`, per conflict. The draft then contains the release and is no longer behind it; its base does not move. The preview\'s `token`, sent back as `expectedToken`, makes the merge apply what the preview showed or nothing (`merge-preview-outdated`). A conflict can also be resolved to content combined from its sides (`getCatalogDraftMergeSides`, then `mergedContent`), reviewed before the draft is released. The merge needs the merge base installed; the preview names one that is not (`missingBase`), and the merge is refused with `merge-base-missing`. - **Release registries** (alpha, `x-experimental`, ADR 0008) move releases between installations: an Epistola Exchange the installation is connected to, or a container registry it is configured with (`listReleaseRegistries`). A released release is published to one (`publishReleaseToRegistry`), and another installation lists the releases of a catalog there (`listRegistryReleases`) and installs one (`installRegistryRelease`) as an import does. A release registry is named by the installation; it is not the `{registry}` of a catalog\'s name. Documents are rendered from releases, and a version range never matches a draft. A draft renders only in a preview that names its `releaseId`, and in an environment it is deployed to. Importing a catalog archive (`importCatalog`) installs the release the archive carries, at its version, beside the releases the tenant already has; it never creates or changes a draft. A catalog with a source (`CatalogDto.source`) installs releases from it the same way (`installCatalogRelease`), and `listAvailableCatalogReleases` lists those the tenant does not have yet, older lines included. Nothing is updated in place or removed: deploying decides what an environment serves. A release keeps its id and number wherever it moves, so it is the same release in every installation. There are no catalog types: receiving releases works whether or not the catalog can be changed, and every write to one that cannot is refused with 409 `catalog-read-only`. ## Deploying An environment serves releases of catalogs (`deployCatalogRelease`): released ones, several of one catalog if need be, and at most one draft per catalog, rendered live. A request through the environment (`environmentKey`) renders: - with **no `versionRange`**: the catalog\'s deployed draft if there is one, else the highest release the environment serves; - with a **range or an exact version**: the highest served release that satisfies it. A draft never matches: it has no version. Rollback is undeploying the newer release. Deploying a draft replaces the draft the environment served for that catalog, and an environment marked **production** (`EnvironmentDto.production`) serves no draft. A document rendered from a draft carries the draft\'s `releaseId` and its name at render time (`releaseName`), with a null `version`, and its PDF a preview watermark. Releasing a deployed draft keeps its `releaseId`, so the environment then serves it as released; discarding the draft ends the deployment. ## Versions and version ranges A version (`ReleaseVersion`) is a SemVer core version, `MAJOR.MINOR.PATCH` without leading zeros, as the holder of the catalog\'s namespace issues it, or a **patch release** number, `MAJOR.MINOR.PATCH-<namespace>.<N>`, at most 128 characters. Wherever the contract names one exact version it has that form, and is called `version`; every member called `version` is one. A patch release is how someone who does not hold a catalog\'s namespace fixes a release of it (a municipality fixing a supplier\'s catalog): it is labelled with a namespace they hold, and numbered from 1, `1.3.1-gemeente-x.1`. As a SemVer pre-release it sorts below its core and above every release below that, `1.3.0` < `1.3.1-gemeente-x.1` < `1.3.1`, so the holder\'s next release supersedes it, and the two never collide: the holder never uses a label, the patcher never issues a plain number (contract ADR 0003). Which namespaces a tenant holds is the installation\'s to know; the contract checks the shape. \"Highest\" always means by this order, a patch release included. A request that selects a release to render or check (generation, preview, validation) takes a version range, `versionRange`, in the npm SemVer range grammar: an exact version (`1.4.0`), a caret (`^1.4.0`), a tilde (`~1.4.0`), comparators (`>=1.0.0 <2.0.0`), a hyphen range (`1.0.0 - 2.0.0`), or a `||` union of these. The highest release that satisfies it renders, and responses name the exact release used. A range is at most 256 characters, so an exact release number (at most 128) always fits, and a comparator pair of patch release numbers usually does. A range matches a patch release as npm matches a pre-release: only when one of its comparators names a pre-release of the same `MAJOR.MINOR.PATCH`, such as the exact number (`1.3.1-gemeente-x.1`) or `>=1.3.1-gemeente-x.1 <1.4.0`; `^1.3.0` never selects one. ## Catalog dependencies A catalog that uses another catalog\'s resources declares that catalog once, with the exact release of it that it renders with (`version`), never a range. References into the other catalog name the catalog but no version, so a release renders with exactly the releases its declarations pin. In a draft, a declaration may name a draft of the other catalog instead (`releaseId`), to build on work that is not released yet. A released release pins only released releases: releasing such a draft is refused (`release-dependencies-unreleased`) unless the request releases those drafts along with it (`releaseDependencies`), in one transaction. ## Catalog identity A catalog\'s key alone is not unique: two publishers can each publish `letters`. The registry and the namespace complete its name, and the same namespace in two registries is two namespaces. Which registry is a server\'s default is configuration; in a path, `/catalogs/~/acme-corp/letters/…` and `/catalogs/exchange.epistola.app/acme-corp/letters/…` address the same catalog when `exchange.epistola.app` is the default, and `~` may be sent percent-encoded as `%7E`. In a body, a catalog is named by separate `registry`, `namespace` and `catalogKey` members, and a reference into another catalog by an alias: 1. **A request that names a catalog** (a generation or preview target, a dependency declaration) may omit `registry`, or send null, for the default registry. (An import\'s `registry` defaults to the one the archive names.) 2. **A reference from one catalog\'s release to a resource of another** names that catalog by the **alias** the release\'s dependency declarations give it (`CatalogAlias`, in the member `catalogKey`), never by registry or namespace: a template model\'s `themeRef`, its stencil and image nodes, a `fontFamily` (catalog content, portable catalog wire v8, contract ADR 0003), and the references this API reads and writes beside it, a release\'s default theme (`CatalogThemeReference`), an attribute\'s code-list binding and an attribute criterion in variant selection (`VariantSelectionAttribute`, resolved through the release that renders). Omitted or null, or the catalog\'s own key, is the catalog itself. A declaration (`CatalogDependencyDto`, `listCatalogDependencies`) maps each alias to the catalog\'s full name and the release it pins; that is where a client finds the name. Because content names the alias, it means the same in every installation and under any name, and pinning another release changes no content. An alias is by default the catalog\'s key (`CatalogDependencyRequirement.alias`). Responses write every registry in full, by its name, never `~`, so a value read from one installation means the same catalog on another. Content documents are returned as stored. ## Concurrency Updates can be made conditional. Templates, variants, themes, stencils, code lists, attributes, releases, environments, tenants and consumers carry a revision, which reading or updating one returns as a strong `ETag` header: a quoted decimal integer such as `\"7\"`. Send it back as `If-Match` on an update: if the resource changed since you read it, the update is refused with 412 `resource-modified` and nothing changes; read it again, reapply your change and retry. Without `If-Match` an update applies unconditionally, and the last write wins. What a revision covers: - a template: its own properties, data contract and data examples; - a variant: its title, description, attributes and template model, so `getVariant` and `getVariantContent` return the same `ETag`, and `updateVariant` and `updateVariantContent` take either; - a release: its name, default theme, presets and dependency declarations, so `getCatalogRelease` and `listCatalogDependencies` return the same `ETag`, and `updateCatalogRelease` and `updateCatalogDependencies` take either; - a code list: its properties and entries, whether each is hidden included, so `updateCodeListEntryHidden` takes the code list\'s `ETag`; - an environment: its name and production mark, not what it serves. ## Authentication Credentials go in the `Authorization` header: - **API key**, `Authorization: ApiKey <key>`: the supported method. A tenant manager issues each key for one tenant, with a set of tenant roles. The scheme name is case-insensitive. - **Bearer JWT** (**experimental**), `Authorization: Bearer <jwt>`: issued by an OAuth 2.0 identity provider, or self-signed with a key pair registered through the Consumers API. The [authentication guide](https://github.com/epistola-app/epistola-contract/blob/main/contracts/api/docs/auth.md) has the details. ## Authorization Each operation names the permissions it requires (`x-required-permissions`), such as `TEMPLATE_VIEW`, `TEMPLATE_EDIT`, `DOCUMENT_GENERATE` and `CATALOG_MANAGE`. A caller has them through its tenant roles (`CONTENT_VIEWER`, `CONTENT_AUTHOR`, `DOCUMENT_GENERATOR`, `CONTENT_PUBLISHER`, `TENANT_ADMINISTRATOR`), the roles stored on its API key. Managing tenants needs the platform role `TENANT_MANAGER`. ## Errors Errors are [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457) problem details, with `Content-Type: application/problem+json`: - `type` (URI): what went wrong, the stable value to switch on. It is `https://epistola.app/errors/{slug}`, which documents the problem type; - `title`: a short summary; - `status`: the HTTP status code; - `detail` (optional): what happened this time; - `instance` (optional): this occurrence. A problem may add members of its own, such as the field-level `errors` of a `validation-error`; ignore members you do not recognize. The problem types are listed, machine-readably, in this document\'s `x-problem-types` extension, and in the [error type registry](https://github.com/epistola-app/epistola-contract/blob/main/contracts/api/docs/error-types.md). A server answers only with the types registered there. A type names a problem a caller can act on differently; anything else is the generic type of its status, so a missing resource is `not-found` whichever resource it is, and a refused authorization `forbidden`. New types may be added in a minor version: handle a type you do not recognize by its `status`, as the generic type of that status, and keep a fallback when switching on them. ## Experimental parts and server support Operations and members marked `x-experimental: true`, the consumer model (Bearer JWT and the Consumers API) among them, may still change. Epistola Suite, the server that implements this contract, may not implement them yet, nor every part of the rest: installing missing dependency releases when deploying, recording who requested a document, an attribute\'s `description`, listing a stencil\'s usage in a released release, and a dependency alias other than the catalog\'s key among them. An operation a server does not implement yet answers 501 `operation-not-implemented`.
6
6
  *
7
- * The version of the OpenAPI document: 2.0.0-alpha.3
7
+ * The version of the OpenAPI document: 2.0.0-alpha.4
8
8
  *
9
9
  *
10
10
  * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).
@@ -244,12 +244,6 @@ export class AttributesApi extends runtime.BaseAPI {
244
244
  if (requestParameters['size'] != null) {
245
245
  queryParameters['size'] = requestParameters['size'];
246
246
  }
247
- if (requestParameters['sort'] != null) {
248
- queryParameters['sort'] = requestParameters['sort'];
249
- }
250
- if (requestParameters['direction'] != null) {
251
- queryParameters['direction'] = requestParameters['direction'];
252
- }
253
247
  const headerParameters = {};
254
248
  if (this.configuration && this.configuration.apiKey) {
255
249
  headerParameters["Authorization"] = await this.configuration.apiKey("Authorization"); // authorizationApiKeyAuth authentication
@@ -348,7 +342,7 @@ export class AttributesApi extends runtime.BaseAPI {
348
342
  };
349
343
  }
350
344
  /**
351
- * Update an attribute definition\'s `displayName`, `description` and constraint: its inline `allowedValues`, or the code list it binds (`codeListBinding`). Omitted or null members are left as they are; `clearCodeListBinding: true` removes the binding. The constraint may switch kind, as `UpdateAttributeRequest` describes; mixing both kinds, or a `codeListBinding` together with `clearCodeListBinding`, is refused with 400 `validation-error`, and an attribute of a catalog that cannot be changed with 409 `catalog-read-only`. Send the `ETag` from a read as `If-Match` to have the update refused with 412 `resource-modified` if the resource changed since; without it, the last write wins.
345
+ * Update an attribute definition\'s `name` and constraint: its inline `allowedValues`, or the code list it binds (`codeListBinding`). Omitted or null members are left as they are; `clearCodeListBinding: true` removes the binding. The constraint may switch kind, as `UpdateAttributeRequest` describes; mixing both kinds, or a `codeListBinding` together with `clearCodeListBinding`, is refused with 400 `validation-error`, and an attribute of a catalog that cannot be changed with 409 `catalog-read-only`. Send the `ETag` from a read as `If-Match` to have the update refused with 412 `resource-modified` if the resource changed since; without it, the last write wins.
352
346
  * Update an attribute definition
353
347
  */
354
348
  async updateAttributeRaw(requestParameters, initOverrides) {
@@ -357,7 +351,7 @@ export class AttributesApi extends runtime.BaseAPI {
357
351
  return new runtime.JSONApiResponse(response, (jsonValue) => AttributeDtoFromJSON(jsonValue));
358
352
  }
359
353
  /**
360
- * Update an attribute definition\'s `displayName`, `description` and constraint: its inline `allowedValues`, or the code list it binds (`codeListBinding`). Omitted or null members are left as they are; `clearCodeListBinding: true` removes the binding. The constraint may switch kind, as `UpdateAttributeRequest` describes; mixing both kinds, or a `codeListBinding` together with `clearCodeListBinding`, is refused with 400 `validation-error`, and an attribute of a catalog that cannot be changed with 409 `catalog-read-only`. Send the `ETag` from a read as `If-Match` to have the update refused with 412 `resource-modified` if the resource changed since; without it, the last write wins.
354
+ * Update an attribute definition\'s `name` and constraint: its inline `allowedValues`, or the code list it binds (`codeListBinding`). Omitted or null members are left as they are; `clearCodeListBinding: true` removes the binding. The constraint may switch kind, as `UpdateAttributeRequest` describes; mixing both kinds, or a `codeListBinding` together with `clearCodeListBinding`, is refused with 400 `validation-error`, and an attribute of a catalog that cannot be changed with 409 `catalog-read-only`. Send the `ETag` from a read as `If-Match` to have the update refused with 412 `resource-modified` if the resource changed since; without it, the last write wins.
361
355
  * Update an attribute definition
362
356
  */
363
357
  async updateAttribute(requestParameters, initOverrides) {
@@ -365,11 +359,4 @@ export class AttributesApi extends runtime.BaseAPI {
365
359
  return await response.value();
366
360
  }
367
361
  }
368
- /**
369
- * @export
370
- */
371
- export const ListAttributesDirectionEnum = {
372
- Asc: 'asc',
373
- Desc: 'desc',
374
- };
375
362
  //# sourceMappingURL=AttributesApi.js.map