@epistola.app/epistola-client 2.0.0-beta.2 → 2.0.0-beta.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 (457) hide show
  1. package/CHANGELOG.md +29 -20
  2. package/README.md +20 -9
  3. package/dist/error/problemDetailException.d.ts +24 -3
  4. package/dist/error/problemDetailException.d.ts.map +1 -1
  5. package/dist/error/problemDetailException.js +29 -2
  6. package/dist/error/problemDetailException.js.map +1 -1
  7. package/dist/generated/api/apis/AttributesApi.d.ts +2 -2
  8. package/dist/generated/api/apis/AttributesApi.js +2 -2
  9. package/dist/generated/api/apis/CatalogsApi.d.ts +4 -4
  10. package/dist/generated/api/apis/CatalogsApi.d.ts.map +1 -1
  11. package/dist/generated/api/apis/CatalogsApi.js +5 -5
  12. package/dist/generated/api/apis/CatalogsApi.js.map +1 -1
  13. package/dist/generated/api/apis/CodeListsApi.d.ts +2 -2
  14. package/dist/generated/api/apis/CodeListsApi.js +2 -2
  15. package/dist/generated/api/apis/ConsumersApi.d.ts +4 -4
  16. package/dist/generated/api/apis/ConsumersApi.js +4 -4
  17. package/dist/generated/api/apis/EnvironmentsApi.d.ts +2 -2
  18. package/dist/generated/api/apis/EnvironmentsApi.js +2 -2
  19. package/dist/generated/api/apis/FontsApi.d.ts +2 -2
  20. package/dist/generated/api/apis/FontsApi.js +2 -2
  21. package/dist/generated/api/apis/GenerationApi.d.ts +6 -6
  22. package/dist/generated/api/apis/GenerationApi.js +7 -7
  23. package/dist/generated/api/apis/GenerationApi.js.map +1 -1
  24. package/dist/generated/api/apis/ImagesApi.d.ts +2 -2
  25. package/dist/generated/api/apis/ImagesApi.js +2 -2
  26. package/dist/generated/api/apis/QualityProfilesApi.d.ts +2 -2
  27. package/dist/generated/api/apis/QualityProfilesApi.js +2 -2
  28. package/dist/generated/api/apis/SearchApi.d.ts +2 -2
  29. package/dist/generated/api/apis/SearchApi.js +2 -2
  30. package/dist/generated/api/apis/StencilsApi.d.ts +2 -2
  31. package/dist/generated/api/apis/StencilsApi.js +2 -2
  32. package/dist/generated/api/apis/SystemApi.d.ts +2 -2
  33. package/dist/generated/api/apis/SystemApi.js +2 -2
  34. package/dist/generated/api/apis/TemplatesApi.d.ts +2 -2
  35. package/dist/generated/api/apis/TemplatesApi.js +2 -2
  36. package/dist/generated/api/apis/TenantsApi.d.ts +2 -2
  37. package/dist/generated/api/apis/TenantsApi.js +2 -2
  38. package/dist/generated/api/apis/ThemesApi.d.ts +2 -2
  39. package/dist/generated/api/apis/ThemesApi.js +2 -2
  40. package/dist/generated/api/apis/VariantsApi.d.ts +2 -2
  41. package/dist/generated/api/apis/VariantsApi.js +2 -2
  42. package/dist/generated/api/models/AmbiguousVariantProblemDetail.d.ts +2 -2
  43. package/dist/generated/api/models/AmbiguousVariantProblemDetail.js +2 -2
  44. package/dist/generated/api/models/ApproveConsumerRequest.d.ts +2 -2
  45. package/dist/generated/api/models/ApproveConsumerRequest.js +2 -2
  46. package/dist/generated/api/models/AttributeDto.d.ts +2 -2
  47. package/dist/generated/api/models/AttributeDto.js +2 -2
  48. package/dist/generated/api/models/AttributeListResponse.d.ts +2 -2
  49. package/dist/generated/api/models/AttributeListResponse.js +2 -2
  50. package/dist/generated/api/models/AvailableCatalogReleases.d.ts +2 -2
  51. package/dist/generated/api/models/AvailableCatalogReleases.js +2 -2
  52. package/dist/generated/api/models/AvailableReleaseDependencyDto.d.ts +2 -2
  53. package/dist/generated/api/models/AvailableReleaseDependencyDto.js +2 -2
  54. package/dist/generated/api/models/AvailableReleaseDto.d.ts +2 -2
  55. package/dist/generated/api/models/AvailableReleaseDto.js +2 -2
  56. package/dist/generated/api/models/BatchGenerationItem.d.ts +2 -2
  57. package/dist/generated/api/models/BatchGenerationItem.js +2 -2
  58. package/dist/generated/api/models/BehindReleaseDto.d.ts +2 -2
  59. package/dist/generated/api/models/BehindReleaseDto.js +2 -2
  60. package/dist/generated/api/models/BlockStylePreset.d.ts +2 -2
  61. package/dist/generated/api/models/BlockStylePreset.js +2 -2
  62. package/dist/generated/api/models/CatalogChangesDto.d.ts +2 -2
  63. package/dist/generated/api/models/CatalogChangesDto.js +2 -2
  64. package/dist/generated/api/models/CatalogDependencyDto.d.ts +2 -2
  65. package/dist/generated/api/models/CatalogDependencyDto.js +2 -2
  66. package/dist/generated/api/models/CatalogDependencyListResponse.d.ts +2 -2
  67. package/dist/generated/api/models/CatalogDependencyListResponse.js +2 -2
  68. package/dist/generated/api/models/CatalogDependencyRequirement.d.ts +2 -2
  69. package/dist/generated/api/models/CatalogDependencyRequirement.js +2 -2
  70. package/dist/generated/api/models/CatalogDraftInUseProblemDetail.d.ts +70 -0
  71. package/dist/generated/api/models/CatalogDraftInUseProblemDetail.d.ts.map +1 -0
  72. package/dist/generated/api/models/CatalogDraftInUseProblemDetail.js +64 -0
  73. package/dist/generated/api/models/CatalogDraftInUseProblemDetail.js.map +1 -0
  74. package/dist/generated/api/models/CatalogDraftMergePreview.d.ts +2 -2
  75. package/dist/generated/api/models/CatalogDraftMergePreview.js +2 -2
  76. package/dist/generated/api/models/CatalogDraftMergeResource.d.ts +2 -2
  77. package/dist/generated/api/models/CatalogDraftMergeResource.js +2 -2
  78. package/dist/generated/api/models/CatalogDraftMergeSides.d.ts +2 -2
  79. package/dist/generated/api/models/CatalogDraftMergeSides.js +2 -2
  80. package/dist/generated/api/models/CatalogDraftRefDto.d.ts +51 -0
  81. package/dist/generated/api/models/CatalogDraftRefDto.d.ts.map +1 -0
  82. package/dist/generated/api/models/CatalogDraftRefDto.js +61 -0
  83. package/dist/generated/api/models/CatalogDraftRefDto.js.map +1 -0
  84. package/dist/generated/api/models/CatalogDraftReleasePreview.d.ts +2 -2
  85. package/dist/generated/api/models/CatalogDraftReleasePreview.js +2 -2
  86. package/dist/generated/api/models/CatalogDto.d.ts +2 -2
  87. package/dist/generated/api/models/CatalogDto.js +2 -2
  88. package/dist/generated/api/models/CatalogLevelChangeDto.d.ts +2 -2
  89. package/dist/generated/api/models/CatalogLevelChangeDto.js +2 -2
  90. package/dist/generated/api/models/CatalogListResponse.d.ts +2 -2
  91. package/dist/generated/api/models/CatalogListResponse.js +2 -2
  92. package/dist/generated/api/models/CatalogMergeBaseRef.d.ts +2 -2
  93. package/dist/generated/api/models/CatalogMergeBaseRef.js +2 -2
  94. package/dist/generated/api/models/CatalogMergeOutcome.d.ts +2 -2
  95. package/dist/generated/api/models/CatalogMergeOutcome.js +2 -2
  96. package/dist/generated/api/models/CatalogMergeSide.d.ts +2 -2
  97. package/dist/generated/api/models/CatalogMergeSide.js +2 -2
  98. package/dist/generated/api/models/CatalogPresetDto.d.ts +2 -2
  99. package/dist/generated/api/models/CatalogPresetDto.js +2 -2
  100. package/dist/generated/api/models/CatalogReadOnlyProblemDetail.d.ts +2 -2
  101. package/dist/generated/api/models/CatalogReadOnlyProblemDetail.js +2 -2
  102. package/dist/generated/api/models/CatalogReadOnlyReason.d.ts +2 -2
  103. package/dist/generated/api/models/CatalogReadOnlyReason.js +2 -2
  104. package/dist/generated/api/models/CatalogReleaseDto.d.ts +2 -2
  105. package/dist/generated/api/models/CatalogReleaseDto.js +2 -2
  106. package/dist/generated/api/models/CatalogReleaseListResponse.d.ts +2 -2
  107. package/dist/generated/api/models/CatalogReleaseListResponse.js +2 -2
  108. package/dist/generated/api/models/CatalogReleaseRefDto.d.ts +2 -2
  109. package/dist/generated/api/models/CatalogReleaseRefDto.js +2 -2
  110. package/dist/generated/api/models/CatalogReleaseStatus.d.ts +2 -2
  111. package/dist/generated/api/models/CatalogReleaseStatus.js +2 -2
  112. package/dist/generated/api/models/CatalogRenderingDefaultsTooNewProblemDetail.d.ts +2 -2
  113. package/dist/generated/api/models/CatalogRenderingDefaultsTooNewProblemDetail.js +2 -2
  114. package/dist/generated/api/models/CatalogThemeReference.d.ts +2 -2
  115. package/dist/generated/api/models/CatalogThemeReference.js +2 -2
  116. package/dist/generated/api/models/CatalogVersionBehindProblemDetail.d.ts +2 -2
  117. package/dist/generated/api/models/CatalogVersionBehindProblemDetail.js +2 -2
  118. package/dist/generated/api/models/CodeListAuthType.d.ts +2 -2
  119. package/dist/generated/api/models/CodeListAuthType.js +2 -2
  120. package/dist/generated/api/models/CodeListBindingRef.d.ts +2 -2
  121. package/dist/generated/api/models/CodeListBindingRef.js +2 -2
  122. package/dist/generated/api/models/CodeListDto.d.ts +2 -2
  123. package/dist/generated/api/models/CodeListDto.js +2 -2
  124. package/dist/generated/api/models/CodeListEntriesResponse.d.ts +2 -2
  125. package/dist/generated/api/models/CodeListEntriesResponse.js +2 -2
  126. package/dist/generated/api/models/CodeListEntryDto.d.ts +2 -2
  127. package/dist/generated/api/models/CodeListEntryDto.js +2 -2
  128. package/dist/generated/api/models/CodeListListResponse.d.ts +2 -2
  129. package/dist/generated/api/models/CodeListListResponse.js +2 -2
  130. package/dist/generated/api/models/CodeListSourceType.d.ts +2 -2
  131. package/dist/generated/api/models/CodeListSourceType.js +2 -2
  132. package/dist/generated/api/models/CollectMeta.d.ts +2 -2
  133. package/dist/generated/api/models/CollectMeta.js +2 -2
  134. package/dist/generated/api/models/CollectRequest.d.ts +2 -2
  135. package/dist/generated/api/models/CollectRequest.js +2 -2
  136. package/dist/generated/api/models/ConsumerDto.d.ts +2 -2
  137. package/dist/generated/api/models/ConsumerDto.js +2 -2
  138. package/dist/generated/api/models/ConsumerListResponse.d.ts +2 -2
  139. package/dist/generated/api/models/ConsumerListResponse.js +2 -2
  140. package/dist/generated/api/models/ConsumerNodeDto.d.ts +2 -2
  141. package/dist/generated/api/models/ConsumerNodeDto.js +2 -2
  142. package/dist/generated/api/models/ConsumerPermissions.d.ts +2 -2
  143. package/dist/generated/api/models/ConsumerPermissions.js +2 -2
  144. package/dist/generated/api/models/CreateAttributeRequest.d.ts +2 -2
  145. package/dist/generated/api/models/CreateAttributeRequest.js +2 -2
  146. package/dist/generated/api/models/CreateCatalogReleaseRequest.d.ts +2 -2
  147. package/dist/generated/api/models/CreateCatalogReleaseRequest.js +2 -2
  148. package/dist/generated/api/models/CreateCodeListRequest.d.ts +2 -2
  149. package/dist/generated/api/models/CreateCodeListRequest.js +2 -2
  150. package/dist/generated/api/models/CreateEnvironmentRequest.d.ts +2 -2
  151. package/dist/generated/api/models/CreateEnvironmentRequest.js +2 -2
  152. package/dist/generated/api/models/CreateQualityProfileRequest.d.ts +2 -2
  153. package/dist/generated/api/models/CreateQualityProfileRequest.js +2 -2
  154. package/dist/generated/api/models/CreateStencilRequest.d.ts +2 -2
  155. package/dist/generated/api/models/CreateStencilRequest.js +2 -2
  156. package/dist/generated/api/models/CreateTemplateRequest.d.ts +2 -2
  157. package/dist/generated/api/models/CreateTemplateRequest.js +2 -2
  158. package/dist/generated/api/models/CreateTenantRequest.d.ts +2 -2
  159. package/dist/generated/api/models/CreateTenantRequest.js +2 -2
  160. package/dist/generated/api/models/CreateThemeRequest.d.ts +2 -2
  161. package/dist/generated/api/models/CreateThemeRequest.js +2 -2
  162. package/dist/generated/api/models/CreateVariantRequest.d.ts +2 -2
  163. package/dist/generated/api/models/CreateVariantRequest.js +2 -2
  164. package/dist/generated/api/models/DataExampleDto.d.ts +2 -2
  165. package/dist/generated/api/models/DataExampleDto.js +2 -2
  166. package/dist/generated/api/models/DataModelValidationError.d.ts +2 -2
  167. package/dist/generated/api/models/DataModelValidationError.js +2 -2
  168. package/dist/generated/api/models/DataModelValidationProblemDetail.d.ts +2 -2
  169. package/dist/generated/api/models/DataModelValidationProblemDetail.js +2 -2
  170. package/dist/generated/api/models/DeploymentDto.d.ts +2 -2
  171. package/dist/generated/api/models/DeploymentDto.js +2 -2
  172. package/dist/generated/api/models/DeploymentEventDto.d.ts +2 -2
  173. package/dist/generated/api/models/DeploymentEventDto.js +2 -2
  174. package/dist/generated/api/models/DeploymentHistoryResponse.d.ts +2 -2
  175. package/dist/generated/api/models/DeploymentHistoryResponse.js +2 -2
  176. package/dist/generated/api/models/DeploymentListResponse.d.ts +2 -2
  177. package/dist/generated/api/models/DeploymentListResponse.js +2 -2
  178. package/dist/generated/api/models/DocumentDto.d.ts +2 -2
  179. package/dist/generated/api/models/DocumentDto.js +2 -2
  180. package/dist/generated/api/models/DocumentGenerationItemDto.d.ts +2 -2
  181. package/dist/generated/api/models/DocumentGenerationItemDto.js +2 -2
  182. package/dist/generated/api/models/DocumentGenerationJobDto.d.ts +2 -2
  183. package/dist/generated/api/models/DocumentGenerationJobDto.js +2 -2
  184. package/dist/generated/api/models/DocumentListResponse.d.ts +2 -2
  185. package/dist/generated/api/models/DocumentListResponse.js +2 -2
  186. package/dist/generated/api/models/EnvironmentDto.d.ts +2 -2
  187. package/dist/generated/api/models/EnvironmentDto.js +2 -2
  188. package/dist/generated/api/models/EnvironmentListResponse.d.ts +2 -2
  189. package/dist/generated/api/models/EnvironmentListResponse.js +2 -2
  190. package/dist/generated/api/models/FontDto.d.ts +2 -2
  191. package/dist/generated/api/models/FontDto.js +2 -2
  192. package/dist/generated/api/models/FontListResponse.d.ts +2 -2
  193. package/dist/generated/api/models/FontListResponse.js +2 -2
  194. package/dist/generated/api/models/FontVariantDto.d.ts +2 -2
  195. package/dist/generated/api/models/FontVariantDto.js +2 -2
  196. package/dist/generated/api/models/ForbiddenProblemDetail.d.ts +2 -2
  197. package/dist/generated/api/models/ForbiddenProblemDetail.js +2 -2
  198. package/dist/generated/api/models/GenerateBatchRequest.d.ts +2 -2
  199. package/dist/generated/api/models/GenerateBatchRequest.js +2 -2
  200. package/dist/generated/api/models/GenerateDocumentRequest.d.ts +2 -2
  201. package/dist/generated/api/models/GenerateDocumentRequest.js +2 -2
  202. package/dist/generated/api/models/GenerationItemStatus.d.ts +2 -2
  203. package/dist/generated/api/models/GenerationItemStatus.js +2 -2
  204. package/dist/generated/api/models/GenerationJobItemListResponse.d.ts +2 -2
  205. package/dist/generated/api/models/GenerationJobItemListResponse.js +2 -2
  206. package/dist/generated/api/models/GenerationJobListResponse.d.ts +2 -2
  207. package/dist/generated/api/models/GenerationJobListResponse.js +2 -2
  208. package/dist/generated/api/models/GenerationJobResponse.d.ts +2 -2
  209. package/dist/generated/api/models/GenerationJobResponse.js +2 -2
  210. package/dist/generated/api/models/GenerationJobStatus.d.ts +2 -2
  211. package/dist/generated/api/models/GenerationJobStatus.js +2 -2
  212. package/dist/generated/api/models/GenerationJobType.d.ts +2 -2
  213. package/dist/generated/api/models/GenerationJobType.js +2 -2
  214. package/dist/generated/api/models/GenerationResult.d.ts +2 -2
  215. package/dist/generated/api/models/GenerationResult.js +2 -2
  216. package/dist/generated/api/models/ImageDto.d.ts +2 -2
  217. package/dist/generated/api/models/ImageDto.js +2 -2
  218. package/dist/generated/api/models/ImageListResponse.d.ts +2 -2
  219. package/dist/generated/api/models/ImageListResponse.js +2 -2
  220. package/dist/generated/api/models/ImportCatalogResponse.d.ts +2 -2
  221. package/dist/generated/api/models/ImportCatalogResponse.js +2 -2
  222. package/dist/generated/api/models/InstallCatalogReleaseResponse.d.ts +2 -2
  223. package/dist/generated/api/models/InstallCatalogReleaseResponse.js +2 -2
  224. package/dist/generated/api/models/InvalidDataField.d.ts +2 -2
  225. package/dist/generated/api/models/InvalidDataField.js +2 -2
  226. package/dist/generated/api/models/Margins.d.ts +2 -2
  227. package/dist/generated/api/models/Margins.js +2 -2
  228. package/dist/generated/api/models/MarkStencilReadyResponse.d.ts +2 -2
  229. package/dist/generated/api/models/MarkStencilReadyResponse.js +2 -2
  230. package/dist/generated/api/models/MergeBaseMissingProblemDetail.d.ts +2 -2
  231. package/dist/generated/api/models/MergeBaseMissingProblemDetail.js +2 -2
  232. package/dist/generated/api/models/MergeConflictsUnresolvedProblemDetail.d.ts +2 -2
  233. package/dist/generated/api/models/MergeConflictsUnresolvedProblemDetail.js +2 -2
  234. package/dist/generated/api/models/MergeIntoCatalogDraftRequest.d.ts +2 -2
  235. package/dist/generated/api/models/MergeIntoCatalogDraftRequest.js +2 -2
  236. package/dist/generated/api/models/MergeIntoCatalogDraftResponse.d.ts +2 -2
  237. package/dist/generated/api/models/MergeIntoCatalogDraftResponse.js +2 -2
  238. package/dist/generated/api/models/MissingDataField.d.ts +2 -2
  239. package/dist/generated/api/models/MissingDataField.js +2 -2
  240. package/dist/generated/api/models/MissingReleaseDependency.d.ts +2 -2
  241. package/dist/generated/api/models/MissingReleaseDependency.js +2 -2
  242. package/dist/generated/api/models/MissingReleaseDependencyReason.d.ts +2 -2
  243. package/dist/generated/api/models/MissingReleaseDependencyReason.js +2 -2
  244. package/dist/generated/api/models/Node.d.ts +2 -2
  245. package/dist/generated/api/models/Node.js +2 -2
  246. package/dist/generated/api/models/Orientation.d.ts +2 -2
  247. package/dist/generated/api/models/Orientation.js +2 -2
  248. package/dist/generated/api/models/PageFormat.d.ts +2 -2
  249. package/dist/generated/api/models/PageFormat.js +2 -2
  250. package/dist/generated/api/models/PageMeta.d.ts +2 -2
  251. package/dist/generated/api/models/PageMeta.js +2 -2
  252. package/dist/generated/api/models/PageSettings.d.ts +2 -2
  253. package/dist/generated/api/models/PageSettings.js +2 -2
  254. package/dist/generated/api/models/PartitionAssignment.d.ts +2 -2
  255. package/dist/generated/api/models/PartitionAssignment.js +2 -2
  256. package/dist/generated/api/models/PingRequest.d.ts +2 -2
  257. package/dist/generated/api/models/PingRequest.js +2 -2
  258. package/dist/generated/api/models/PongDetailsDto.d.ts +2 -2
  259. package/dist/generated/api/models/PongDetailsDto.js +2 -2
  260. package/dist/generated/api/models/PongResponse.d.ts +2 -2
  261. package/dist/generated/api/models/PongResponse.js +2 -2
  262. package/dist/generated/api/models/PreviewDocumentRequest.d.ts +9 -7
  263. package/dist/generated/api/models/PreviewDocumentRequest.d.ts.map +1 -1
  264. package/dist/generated/api/models/PreviewDocumentRequest.js +4 -4
  265. package/dist/generated/api/models/PreviewDocumentRequest.js.map +1 -1
  266. package/dist/generated/api/models/ProblemDetail.d.ts +2 -2
  267. package/dist/generated/api/models/ProblemDetail.js +2 -2
  268. package/dist/generated/api/models/PublishReleaseToRegistryRequest.d.ts +2 -2
  269. package/dist/generated/api/models/PublishReleaseToRegistryRequest.js +2 -2
  270. package/dist/generated/api/models/QualityBinding.d.ts +2 -2
  271. package/dist/generated/api/models/QualityBinding.js +2 -2
  272. package/dist/generated/api/models/QualityProfileDto.d.ts +2 -2
  273. package/dist/generated/api/models/QualityProfileDto.js +2 -2
  274. package/dist/generated/api/models/QualityProfileListResponse.d.ts +2 -2
  275. package/dist/generated/api/models/QualityProfileListResponse.js +2 -2
  276. package/dist/generated/api/models/QualityProfileRef.d.ts +2 -2
  277. package/dist/generated/api/models/QualityProfileRef.js +2 -2
  278. package/dist/generated/api/models/QualityRule.d.ts +2 -2
  279. package/dist/generated/api/models/QualityRule.js +2 -2
  280. package/dist/generated/api/models/QualityRuleExamples.d.ts +2 -2
  281. package/dist/generated/api/models/QualityRuleExamples.js +2 -2
  282. package/dist/generated/api/models/QualityRuleOverride.d.ts +2 -2
  283. package/dist/generated/api/models/QualityRuleOverride.js +2 -2
  284. package/dist/generated/api/models/QualityRuleScope.d.ts +2 -2
  285. package/dist/generated/api/models/QualityRuleScope.js +2 -2
  286. package/dist/generated/api/models/QualitySeverity.d.ts +2 -2
  287. package/dist/generated/api/models/QualitySeverity.js +2 -2
  288. package/dist/generated/api/models/RegisterConsumerRequest.d.ts +2 -2
  289. package/dist/generated/api/models/RegisterConsumerRequest.js +2 -2
  290. package/dist/generated/api/models/RegistryReleaseDto.d.ts +2 -2
  291. package/dist/generated/api/models/RegistryReleaseDto.js +2 -2
  292. package/dist/generated/api/models/RegistryReleaseListResponse.d.ts +2 -2
  293. package/dist/generated/api/models/RegistryReleaseListResponse.js +2 -2
  294. package/dist/generated/api/models/RejectConsumerRequest.d.ts +2 -2
  295. package/dist/generated/api/models/RejectConsumerRequest.js +2 -2
  296. package/dist/generated/api/models/ReleaseCatalogDraftRequest.d.ts +2 -2
  297. package/dist/generated/api/models/ReleaseCatalogDraftRequest.js +2 -2
  298. package/dist/generated/api/models/ReleaseCatalogDraftResponse.d.ts +7 -6
  299. package/dist/generated/api/models/ReleaseCatalogDraftResponse.d.ts.map +1 -1
  300. package/dist/generated/api/models/ReleaseCatalogDraftResponse.js +5 -4
  301. package/dist/generated/api/models/ReleaseCatalogDraftResponse.js.map +1 -1
  302. package/dist/generated/api/models/ReleaseDependenciesMissingProblemDetail.d.ts +2 -2
  303. package/dist/generated/api/models/ReleaseDependenciesMissingProblemDetail.js +2 -2
  304. package/dist/generated/api/models/ReleaseDependenciesUnreleasedProblemDetail.d.ts +2 -2
  305. package/dist/generated/api/models/ReleaseDependenciesUnreleasedProblemDetail.js +2 -2
  306. package/dist/generated/api/models/ReleaseDependencyDto.d.ts +2 -2
  307. package/dist/generated/api/models/ReleaseDependencyDto.js +2 -2
  308. package/dist/generated/api/models/ReleaseInUseProblemDetail.d.ts +2 -2
  309. package/dist/generated/api/models/ReleaseInUseProblemDetail.js +2 -2
  310. package/dist/generated/api/models/ReleasePublicationDto.d.ts +2 -2
  311. package/dist/generated/api/models/ReleasePublicationDto.js +2 -2
  312. package/dist/generated/api/models/ReleasePublicationStatus.d.ts +2 -2
  313. package/dist/generated/api/models/ReleasePublicationStatus.js +2 -2
  314. package/dist/generated/api/models/ReleaseRegistryDto.d.ts +2 -2
  315. package/dist/generated/api/models/ReleaseRegistryDto.js +2 -2
  316. package/dist/generated/api/models/ReleaseRegistryKind.d.ts +2 -2
  317. package/dist/generated/api/models/ReleaseRegistryKind.js +2 -2
  318. package/dist/generated/api/models/ReleaseRegistryListResponse.d.ts +2 -2
  319. package/dist/generated/api/models/ReleaseRegistryListResponse.js +2 -2
  320. package/dist/generated/api/models/ReleasedChangeDto.d.ts +2 -2
  321. package/dist/generated/api/models/ReleasedChangeDto.js +2 -2
  322. package/dist/generated/api/models/ReleasedDependencyDto.d.ts +2 -2
  323. package/dist/generated/api/models/ReleasedDependencyDto.js +2 -2
  324. package/dist/generated/api/models/ResourceChangeDto.d.ts +2 -2
  325. package/dist/generated/api/models/ResourceChangeDto.js +2 -2
  326. package/dist/generated/api/models/ResourceStatus.d.ts +2 -2
  327. package/dist/generated/api/models/ResourceStatus.js +2 -2
  328. package/dist/generated/api/models/RotatePublicKeyRequest.d.ts +2 -2
  329. package/dist/generated/api/models/RotatePublicKeyRequest.js +2 -2
  330. package/dist/generated/api/models/SearchHit.d.ts +2 -2
  331. package/dist/generated/api/models/SearchHit.js +2 -2
  332. package/dist/generated/api/models/SearchHitCatalog.d.ts +2 -2
  333. package/dist/generated/api/models/SearchHitCatalog.js +2 -2
  334. package/dist/generated/api/models/SearchHitVariant.d.ts +2 -2
  335. package/dist/generated/api/models/SearchHitVariant.js +2 -2
  336. package/dist/generated/api/models/SearchKindCount.d.ts +2 -2
  337. package/dist/generated/api/models/SearchKindCount.js +2 -2
  338. package/dist/generated/api/models/SearchResults.d.ts +2 -2
  339. package/dist/generated/api/models/SearchResults.js +2 -2
  340. package/dist/generated/api/models/Slot.d.ts +2 -2
  341. package/dist/generated/api/models/Slot.js +2 -2
  342. package/dist/generated/api/models/StencilContentDto.d.ts +2 -2
  343. package/dist/generated/api/models/StencilContentDto.js +2 -2
  344. package/dist/generated/api/models/StencilDto.d.ts +2 -2
  345. package/dist/generated/api/models/StencilDto.js +2 -2
  346. package/dist/generated/api/models/StencilListResponse.d.ts +2 -2
  347. package/dist/generated/api/models/StencilListResponse.js +2 -2
  348. package/dist/generated/api/models/StencilSummaryDto.d.ts +2 -2
  349. package/dist/generated/api/models/StencilSummaryDto.js +2 -2
  350. package/dist/generated/api/models/StencilUsageDto.d.ts +2 -2
  351. package/dist/generated/api/models/StencilUsageDto.js +2 -2
  352. package/dist/generated/api/models/StencilUsageListResponse.d.ts +2 -2
  353. package/dist/generated/api/models/StencilUsageListResponse.js +2 -2
  354. package/dist/generated/api/models/TemplateDataValidationError.d.ts +2 -2
  355. package/dist/generated/api/models/TemplateDataValidationError.js +2 -2
  356. package/dist/generated/api/models/TemplateDataValidationProblemDetail.d.ts +2 -2
  357. package/dist/generated/api/models/TemplateDataValidationProblemDetail.js +2 -2
  358. package/dist/generated/api/models/TemplateDataValidationResult.d.ts +2 -2
  359. package/dist/generated/api/models/TemplateDataValidationResult.js +2 -2
  360. package/dist/generated/api/models/TemplateDocument.d.ts +2 -2
  361. package/dist/generated/api/models/TemplateDocument.js +2 -2
  362. package/dist/generated/api/models/TemplateDto.d.ts +2 -2
  363. package/dist/generated/api/models/TemplateDto.js +2 -2
  364. package/dist/generated/api/models/TemplateListResponse.d.ts +2 -2
  365. package/dist/generated/api/models/TemplateListResponse.js +2 -2
  366. package/dist/generated/api/models/TemplateSummaryDto.d.ts +2 -2
  367. package/dist/generated/api/models/TemplateSummaryDto.js +2 -2
  368. package/dist/generated/api/models/TenantDto.d.ts +2 -2
  369. package/dist/generated/api/models/TenantDto.js +2 -2
  370. package/dist/generated/api/models/TenantListResponse.d.ts +2 -2
  371. package/dist/generated/api/models/TenantListResponse.js +2 -2
  372. package/dist/generated/api/models/ThemeDto.d.ts +2 -2
  373. package/dist/generated/api/models/ThemeDto.js +2 -2
  374. package/dist/generated/api/models/ThemeListResponse.d.ts +2 -2
  375. package/dist/generated/api/models/ThemeListResponse.js +2 -2
  376. package/dist/generated/api/models/ThemeRef.d.ts +2 -2
  377. package/dist/generated/api/models/ThemeRef.js +2 -2
  378. package/dist/generated/api/models/UnreleasedCatalogDependency.d.ts +2 -2
  379. package/dist/generated/api/models/UnreleasedCatalogDependency.js +2 -2
  380. package/dist/generated/api/models/UpdateAttributeRequest.d.ts +2 -2
  381. package/dist/generated/api/models/UpdateAttributeRequest.js +2 -2
  382. package/dist/generated/api/models/UpdateCatalogDependenciesRequest.d.ts +5 -4
  383. package/dist/generated/api/models/UpdateCatalogDependenciesRequest.d.ts.map +1 -1
  384. package/dist/generated/api/models/UpdateCatalogDependenciesRequest.js +2 -2
  385. package/dist/generated/api/models/UpdateCatalogDependenciesRequest.js.map +1 -1
  386. package/dist/generated/api/models/UpdateCatalogReleaseRequest.d.ts +3 -3
  387. package/dist/generated/api/models/UpdateCatalogReleaseRequest.js +2 -2
  388. package/dist/generated/api/models/UpdateCodeListEntryHiddenRequest.d.ts +2 -2
  389. package/dist/generated/api/models/UpdateCodeListEntryHiddenRequest.js +2 -2
  390. package/dist/generated/api/models/UpdateCodeListRequest.d.ts +2 -2
  391. package/dist/generated/api/models/UpdateCodeListRequest.js +2 -2
  392. package/dist/generated/api/models/UpdateConsumerRequest.d.ts +2 -2
  393. package/dist/generated/api/models/UpdateConsumerRequest.js +2 -2
  394. package/dist/generated/api/models/UpdateEnvironmentRequest.d.ts +2 -2
  395. package/dist/generated/api/models/UpdateEnvironmentRequest.js +2 -2
  396. package/dist/generated/api/models/UpdateQualityProfileRequest.d.ts +2 -2
  397. package/dist/generated/api/models/UpdateQualityProfileRequest.js +2 -2
  398. package/dist/generated/api/models/UpdateStencilContentRequest.d.ts +2 -2
  399. package/dist/generated/api/models/UpdateStencilContentRequest.js +2 -2
  400. package/dist/generated/api/models/UpdateStencilRequest.d.ts +2 -2
  401. package/dist/generated/api/models/UpdateStencilRequest.js +2 -2
  402. package/dist/generated/api/models/UpdateTemplateRequest.d.ts +2 -2
  403. package/dist/generated/api/models/UpdateTemplateRequest.js +2 -2
  404. package/dist/generated/api/models/UpdateTenantRequest.d.ts +2 -2
  405. package/dist/generated/api/models/UpdateTenantRequest.js +2 -2
  406. package/dist/generated/api/models/UpdateThemeRequest.d.ts +2 -2
  407. package/dist/generated/api/models/UpdateThemeRequest.js +2 -2
  408. package/dist/generated/api/models/UpdateVariantContentRequest.d.ts +2 -2
  409. package/dist/generated/api/models/UpdateVariantContentRequest.js +2 -2
  410. package/dist/generated/api/models/UpdateVariantRequest.d.ts +2 -2
  411. package/dist/generated/api/models/UpdateVariantRequest.js +2 -2
  412. package/dist/generated/api/models/ValidateTemplateDataRequest.d.ts +2 -2
  413. package/dist/generated/api/models/ValidateTemplateDataRequest.js +2 -2
  414. package/dist/generated/api/models/ValidationError.d.ts +2 -2
  415. package/dist/generated/api/models/ValidationError.js +2 -2
  416. package/dist/generated/api/models/ValidationProblemDetail.d.ts +2 -2
  417. package/dist/generated/api/models/ValidationProblemDetail.js +2 -2
  418. package/dist/generated/api/models/VariantContentDto.d.ts +2 -2
  419. package/dist/generated/api/models/VariantContentDto.js +2 -2
  420. package/dist/generated/api/models/VariantDto.d.ts +2 -2
  421. package/dist/generated/api/models/VariantDto.js +2 -2
  422. package/dist/generated/api/models/VariantListResponse.d.ts +2 -2
  423. package/dist/generated/api/models/VariantListResponse.js +2 -2
  424. package/dist/generated/api/models/VariantSelectionAttribute.d.ts +3 -3
  425. package/dist/generated/api/models/VariantSelectionAttribute.js +2 -2
  426. package/dist/generated/api/models/VariantSummaryDto.d.ts +2 -2
  427. package/dist/generated/api/models/VariantSummaryDto.js +2 -2
  428. package/dist/generated/api/models/index.d.ts +2 -0
  429. package/dist/generated/api/models/index.d.ts.map +1 -1
  430. package/dist/generated/api/models/index.js +2 -0
  431. package/dist/generated/api/models/index.js.map +1 -1
  432. package/dist/generated/api/runtime.d.ts +2 -2
  433. package/dist/generated/api/runtime.js +2 -2
  434. package/dist/generated/contractOperations.js +1 -1
  435. package/dist/generated/contractOperations.js.map +1 -1
  436. package/dist/generated/contractVersion.d.ts +1 -1
  437. package/dist/generated/contractVersion.js +1 -1
  438. package/dist/generated/knownProblemSlugs.d.ts +7 -1
  439. package/dist/generated/knownProblemSlugs.d.ts.map +1 -1
  440. package/dist/generated/knownProblemSlugs.js +7 -1
  441. package/dist/generated/knownProblemSlugs.js.map +1 -1
  442. package/dist/generated/knownValidationCodes.d.ts +3 -3
  443. package/dist/generated/knownValidationCodes.d.ts.map +1 -1
  444. package/dist/generated/knownValidationCodes.js +3 -3
  445. package/dist/generated/knownValidationCodes.js.map +1 -1
  446. package/dist/generated/modelValidation.d.ts +4 -2
  447. package/dist/generated/modelValidation.d.ts.map +1 -1
  448. package/dist/generated/modelValidation.js +15 -1
  449. package/dist/generated/modelValidation.js.map +1 -1
  450. package/dist/http/operations.d.ts +4 -2
  451. package/dist/http/operations.d.ts.map +1 -1
  452. package/dist/http/operations.js +23 -5
  453. package/dist/http/operations.js.map +1 -1
  454. package/dist/index.d.ts +1 -1
  455. package/dist/index.d.ts.map +1 -1
  456. package/dist/index.js.map +1 -1
  457. package/package.json +1 -1
package/CHANGELOG.md CHANGED
@@ -11,6 +11,13 @@ records contract changes; this file records changes to the hand-written library
11
11
 
12
12
  ### Added
13
13
 
14
+ - `ProblemDetailException.dependents`, `heldResources` and `isCatalogDraftInUseProblem` surface a
15
+ `catalog-draft-in-use` problem (409 from `deleteCatalogRelease`, which refuses to discard a draft
16
+ something outside it relies on): the drafts of other catalogs whose dependency declarations name
17
+ it, each a `CatalogDraftRef` (the generated `CatalogDraftRefDto`; an entry missing a member is
18
+ dropped), and the resources only it holds that something outside it still uses, as
19
+ `resourceType/resourceKey`. `environments`, `pinnedBy` and `isReleaseInUseProblem` stay, for
20
+ `release-in-use`, which no operation answers yet.
14
21
  - `KnownValidationCodes` (and the `KnownValidationCode` type), generated from the contract's
15
22
  `x-validation-codes` registry: one constant per code that says why a field of a
16
23
  `validation-error` failed. Compare a field error's `code` (`undefined` when the server sent none)
@@ -57,31 +64,33 @@ records contract changes; this file records changes to the hand-written library
57
64
 
58
65
  ### Changed
59
66
 
60
- - **BREAKING:** a resource's address is its `key` (#84). The hand-written API follows the
61
- generated one: `TemplateDataValidator.validate`, `TemplateSchemaValidator.validate`,
62
- `ServerTemplateDataValidator.validate` and `SchemaCache.getOrLoad` / `evict` take
63
- `(tenantKey, registry, namespace, catalogKey, templateKey, …)`; `ServerValidationTarget` takes
64
- `variantKey` and `environmentKey` in place of `variantId` and `environmentId`; and
65
- `ResultCollector.builder().tenantId(…)` is now `.tenantKey(…)`. The generated request parameters
66
- and models carry the same renames (`tenantKey`, `templateKey`, …, and `key` in place of `slug` and
67
- of a create request's `id`).
68
- - **BREAKING:** a catalog is addressed by registry, namespace and key. `TemplateDataValidator.validate`,
69
- `TemplateSchemaValidator.validate` and `ServerTemplateDataValidator.validate` take
70
- `(tenantId, registry, namespace, catalogKey, templateId, data)` in place of
71
- `(tenantId, catalogId, templateId, data)`, the registry in its path-segment form (`~` for the
72
- server's default registry, or named in full, such as `acme.com`) and the namespace a plain slug.
73
- `SchemaCache.getOrLoad` / `evict` are keyed the same way. `ValidatingGenerationApi` hands a
74
- pre-flighting validator the request's `registry`, or `~` when the request leaves it out or null.
75
- - **BREAKING:** `ServerValidationTarget` takes a `versionRange` (a version range such as `1.4.0` or
76
- `^1.4.0`, sent as the request's `versionRange`) in place of `versionId`, matching contract 2.0's
77
- generation by release. It may be combined with `environmentKey`; without either, the catalog's
78
- latest release is checked.
67
+ - `findOperation` breaks a tie between two path templates with as many literal segments by the
68
+ first segment where they differ, a literal winning over a parameter, rather than by comparing the
69
+ templates as strings. `GET /documents/jobs/content` matched both `getGenerationJobStatus` and the
70
+ moved `downloadDocument` (`/documents/{documentId}/content`), and resolved to the latter, so the
71
+ request asked for a PDF. Neither id can be `jobs` or `content` in practice, both being UUIDs.
72
+ - **BREAKING:** contract 2.0 addresses a resource by its `key` (#84), a catalog by registry,
73
+ namespace and key, and renders a release rather than a template version. Against 1.4, the
74
+ hand-written API changes as follows:
75
+ - `TemplateDataValidator.validate`, `TemplateSchemaValidator.validate` and
76
+ `ServerTemplateDataValidator.validate` take `(tenantKey, registry, namespace, catalogKey,
77
+ templateKey, data)` in place of `(tenantId, catalogId, templateId, data)`, the registry in its
78
+ path-segment form (`~` for the server's default registry, or named in full, such as
79
+ `acme.com`). `SchemaCache.getOrLoad` / `evict` are keyed the same way. `ValidatingGenerationApi`
80
+ hands a pre-flighting validator the request's `registry`, or `~` when the request leaves it out
81
+ or null.
82
+ - `ServerValidationTarget` takes `variantKey` and `environmentKey` in place of `variantId` and
83
+ `environmentId`, and a `versionRange` (`1.4.0`, `^1.4.0`, sent as the request's
84
+ `versionRange`) in place of `versionId`. Without a range or an environment, the catalog's
85
+ highest release is checked.
86
+ - `ResultCollector.builder().tenantId(…)` is now `.tenantKey(…)`.
87
+ - The generated request parameters and models carry the same renames (`tenantKey`,
88
+ `templateKey`, …, and `key` in place of `slug` and of a create request's `id`).
79
89
  - Results handed to a `ResultCollector` handler carry the template's catalog as `registry`,
80
90
  `namespace` and `catalogKey`, always set, next to `version`, which is null for a result
81
91
  rendered from a draft.
82
92
  - The README no longer mentions the `X-API-Key` header: the contract dropped it, and the client
83
93
  only ever sent `Authorization: ApiKey <key>`.
84
-
85
94
  - **Template data is validated by the server, not by a bundled schema compiler.**
86
95
  `TemplateSchemaValidator` and `ValidatingGenerationApi` now call `validateTemplateData` through a
87
96
  pluggable `TemplateDataValidator`, whose only shipped implementation is
package/README.md CHANGED
@@ -115,6 +115,14 @@ const image = await new ImagesApi(client).uploadImage({ tenantKey: 'acme-corp',
115
115
  A plain `Blob` is always sent with the filename `blob`, and as `application/octet-stream` unless it
116
116
  was given a type. The server then names the image `blob`.
117
117
 
118
+ ## Newer servers
119
+
120
+ A minor version of the contract may add response members and enum values ("Compatibility within
121
+ 2.x" in the API description), so this client keeps working against a later 2.x server: a response
122
+ member it does not know is ignored, and an enum value it does not know is kept as the string
123
+ received, though the generated type does not list it. Keep a `default` branch when switching on an
124
+ enum.
125
+
118
126
  ## Error handling
119
127
 
120
128
  Catch `ProblemDetailException` and switch on `typeSlug` against `KnownProblemSlugs`. The slug list is
@@ -132,8 +140,6 @@ try {
132
140
  case KnownProblemSlugs.NOT_FOUND:
133
141
  log.warn(`tenant not found: ${e.detail}`)
134
142
  break
135
- case KnownProblemSlugs.FORBIDDEN:
136
- throw new PermissionError(e.detail)
137
143
  case KnownProblemSlugs.VALIDATION_ERROR:
138
144
  for (const err of e.errors) log.warn(`${err.field}: ${err.message}`) // field-level ValidationProblemDetail
139
145
  break
@@ -169,9 +175,10 @@ try {
169
175
  case KnownProblemSlugs.CATALOG_VERSION_BEHIND:
170
176
  log.warn(`the draft is behind ${e.behind.join(', ')}`) // releaseCatalogDraft: name them in acknowledgedBehind
171
177
  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(', ')}`)
178
+ case KnownProblemSlugs.CATALOG_DRAFT_IN_USE:
179
+ // deleteCatalogRelease: drafts of other catalogs name the draft, or it alone holds resources
180
+ // something outside it uses (resourceType/resourceKey); change those first
181
+ log.warn(`named by ${e.dependents.map((d) => `${d.catalogKey}: ${d.releaseName}`).join(', ')}; holds ${e.heldResources.join(', ')}`)
175
182
  break
176
183
  case KnownProblemSlugs.AMBIGUOUS_VARIANT:
177
184
  log.warn(`several variants match: ${e.tiedVariants.join(', ')}`) // generateDocument, previewDocument: name one by variantKey
@@ -219,7 +226,8 @@ ResponseError` sites keep working. It exposes `type`, `typeSlug`, `title`, `prob
219
226
  `missingDependencies`, `unreleasedDependencies`, `readOnlyReason`, `unresolvedConflicts`,
220
227
  `isMergeConflictsUnresolvedProblem`, `missingBaseVersion`, `missingBaseFingerprint`,
221
228
  `isMergeBaseMissingProblem`, `behind`, `isCatalogVersionBehindProblem`, `environments`,
222
- `pinnedBy`, `isReleaseInUseProblem`, `tiedVariants`, `isAmbiguousVariantProblem`,
229
+ `pinnedBy`, `isReleaseInUseProblem`, `dependents`, `heldResources`, `isCatalogDraftInUseProblem`,
230
+ `tiedVariants`, `isAmbiguousVariantProblem`,
223
231
  `requiredPermission`, `refusedTenantKey`, `requiredPlatformRole`, `refusalReason`,
224
232
  `isForbiddenProblem`, `extensions` (every member
225
233
  outside the base members, RFC 9457's five and `help`), `statusCode`, `rawBody`, `isValidationProblem`,
@@ -232,6 +240,12 @@ releases. `unreleasedDependencies` lists each such draft (`registry`, `namespace
232
240
  `releaseId`, `releaseName`); release them first, or send `releaseDependencies: true` to release them
233
241
  along with the draft.
234
242
 
243
+ A `catalog-draft-in-use` problem (409) means `deleteCatalogRelease` was refused because something
244
+ outside the draft still relies on it. `dependents` lists the drafts of other catalogs whose
245
+ dependency declarations name it (`registry`, `namespace`, `catalogKey`, `releaseId`, `releaseName`),
246
+ and `heldResources` the resources only it holds that something outside it still uses, as
247
+ `resourceType/resourceKey` (`theme/house-style`); change those first.
248
+
235
249
  A `release-dependencies-missing` problem (409) means `deployCatalogRelease` was refused because releases
236
250
  of other catalogs the release pins cannot be had: the tenant does not have them and they could not
237
251
  be fetched or verified. `missingDependencies` lists each, with a `reason` kept as the string the
@@ -295,9 +309,6 @@ validateCreateTenantRequest({ key: 'Acme Corp', name: 'Acme' }) // throws Model
295
309
  Each failure carries a **JSON Pointer** into the data (`/customer/email`), the JSON Schema `keyword`
296
310
  that failed, and a human-readable `message` — so a form can mark the field that is wrong.
297
311
 
298
- `validateTemplateData` arrived with contract **1.4.0**; against an older server the call fails like
299
- any other unknown operation rather than reporting unvalidated data as acceptable.
300
-
301
312
  ### Validating in-process instead
302
313
 
303
314
  To avoid a request per check — pre-flighting a large batch, say — implement `TemplateDataValidator`
@@ -1,4 +1,4 @@
1
- import type { CatalogReadOnlyReason, CatalogReleaseRefDto, DataModelValidationError, InvalidDataField, MissingDataField, MissingReleaseDependency, MissingReleaseDependencyReason, ProblemDetail, UnreleasedCatalogDependency, ValidationError } from '../generated/api/models/index.js';
1
+ import type { CatalogDraftRefDto, 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)
@@ -170,8 +170,9 @@ export declare class ProblemDetailException extends ResponseError {
170
170
  /** True when this problem said the draft is behind releases the request did not acknowledge. */
171
171
  get isCatalogVersionBehindProblem(): boolean;
172
172
  /**
173
- * The environments a `release-in-use` problem (409, from `deleteCatalogRelease`) says deploy the
174
- * release; empty for any other problem, and when none does.
173
+ * The environments a `release-in-use` problem (409) says deploy the release; empty for any other
174
+ * problem, and when none does. No operation deletes a released release yet; discarding a draft is
175
+ * refused with `catalog-draft-in-use` ({@link dependents}, {@link heldResources}).
175
176
  */
176
177
  get environments(): readonly string[];
177
178
  /**
@@ -181,6 +182,21 @@ export declare class ProblemDetailException extends ResponseError {
181
182
  get pinnedBy(): readonly CatalogReleaseRef[];
182
183
  /** True when this problem said the release cannot be deleted while something uses it. */
183
184
  get isReleaseInUseProblem(): boolean;
185
+ /**
186
+ * The drafts of other catalogs a `catalog-draft-in-use` problem (409, from `deleteCatalogRelease`)
187
+ * says name the draft in their dependency declarations, in the order the server listed them;
188
+ * empty for any other problem, and when none does. Change their declarations, or discard them,
189
+ * first. An entry that does not carry all five members as strings is dropped rather than guessed at.
190
+ */
191
+ get dependents(): readonly CatalogDraftRef[];
192
+ /**
193
+ * The resources a `catalog-draft-in-use` problem says only the draft holds while something outside
194
+ * it still uses them, each as `resourceType/resourceKey` (`theme/house-style`); empty for any
195
+ * other problem, and when none.
196
+ */
197
+ get heldResources(): readonly string[];
198
+ /** True when this problem said the draft cannot be discarded while something relies on it. */
199
+ get isCatalogDraftInUseProblem(): boolean;
184
200
  /**
185
201
  * The keys of the variants an `ambiguous-variant` problem (409, from generating or previewing a
186
202
  * document) says match the request's attributes equally well: name one by `variantKey`, or send
@@ -235,4 +251,9 @@ export type UnreleasedDependency = Readonly<UnreleasedCatalogDependency>;
235
251
  * `pinnedBy` member: the generated `CatalogReleaseRefDto`.
236
252
  */
237
253
  export type CatalogReleaseRef = Readonly<CatalogReleaseRefDto>;
254
+ /**
255
+ * One draft a problem names in full, such as each entry of a `catalog-draft-in-use` problem's
256
+ * `dependents` member: the generated `CatalogDraftRefDto`.
257
+ */
258
+ export type CatalogDraftRef = Readonly<CatalogDraftRefDto>;
238
259
  //# 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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"}
@@ -221,8 +221,9 @@ export class ProblemDetailException extends ResponseError {
221
221
  return this.typeSlug === KnownProblemSlugs.CATALOG_VERSION_BEHIND;
222
222
  }
223
223
  /**
224
- * The environments a `release-in-use` problem (409, from `deleteCatalogRelease`) says deploy the
225
- * release; empty for any other problem, and when none does.
224
+ * The environments a `release-in-use` problem (409) says deploy the release; empty for any other
225
+ * problem, and when none does. No operation deletes a released release yet; discarding a draft is
226
+ * refused with `catalog-draft-in-use` ({@link dependents}, {@link heldResources}).
226
227
  */
227
228
  get environments() {
228
229
  return stringsAt(this.extensions, ProblemExtensionMembers.ENVIRONMENTS);
@@ -238,6 +239,27 @@ export class ProblemDetailException extends ResponseError {
238
239
  get isReleaseInUseProblem() {
239
240
  return this.typeSlug === KnownProblemSlugs.RELEASE_IN_USE;
240
241
  }
242
+ /**
243
+ * The drafts of other catalogs a `catalog-draft-in-use` problem (409, from `deleteCatalogRelease`)
244
+ * says name the draft in their dependency declarations, in the order the server listed them;
245
+ * empty for any other problem, and when none does. Change their declarations, or discard them,
246
+ * first. An entry that does not carry all five members as strings is dropped rather than guessed at.
247
+ */
248
+ get dependents() {
249
+ return objectsAt(this.extensions, ProblemExtensionMembers.DEPENDENTS).filter(isCatalogDraftRef);
250
+ }
251
+ /**
252
+ * The resources a `catalog-draft-in-use` problem says only the draft holds while something outside
253
+ * it still uses them, each as `resourceType/resourceKey` (`theme/house-style`); empty for any
254
+ * other problem, and when none.
255
+ */
256
+ get heldResources() {
257
+ return stringsAt(this.extensions, ProblemExtensionMembers.HELD_RESOURCES);
258
+ }
259
+ /** True when this problem said the draft cannot be discarded while something relies on it. */
260
+ get isCatalogDraftInUseProblem() {
261
+ return this.typeSlug === KnownProblemSlugs.CATALOG_DRAFT_IN_USE;
262
+ }
241
263
  /**
242
264
  * The keys of the variants an `ambiguous-variant` problem (409, from generating or previewing a
243
265
  * document) says match the request's attributes equally well: name one by `variantKey`, or send
@@ -312,6 +334,11 @@ function isCatalogReleaseRef(entry) {
312
334
  const record = entry;
313
335
  return CATALOG_RELEASE_REF_MEMBERS.every((member) => typeof record[member] === 'string');
314
336
  }
337
+ const CATALOG_DRAFT_REF_MEMBERS = ['registry', 'namespace', 'catalogKey', 'releaseId', 'releaseName'];
338
+ function isCatalogDraftRef(entry) {
339
+ const record = entry;
340
+ return CATALOG_DRAFT_REF_MEMBERS.every((member) => typeof record[member] === 'string');
341
+ }
315
342
  /** One extension member's array of strings, or empty when absent; entries that are not strings are dropped. */
316
343
  function stringsAt(extensions, member) {
317
344
  const value = extensions[member];
@@ -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. - **Quality profiles** (alpha, `x-experimental`, contract ADR 0010) record how an organisation writes: rules with a plain-language intent, a severity and extras per kind of checking system (`listQualityProfiles` and the rest of the group). A release binds the profiles every template in it is checked against, and a template adds its own (`quality` on `CatalogReleaseDto` and `TemplateDto`). 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`. A request member that needs a permission beyond its operation\'s says so in its description: changing a quality binding (`quality`, alpha) needs `QUALITY_EDIT` as well. ## 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; - `help` (optional): the type\'s page with this request\'s context, such as the `operation` that answered, for hints that fit it. It names this contract\'s terms only, never a value. 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. Six statuses are not listed on each operation, because any operation may answer them: 405 `method-not-allowed`, 406 `not-acceptable`, 413 `content-too-large` and 415 `unsupported-media-type` (the last two where it takes a body), 500 `internal-error`, and 501 `operation-not-implemented`. `x-problem-types` marks them `anyOperation: true`. ## 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`.
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 `DOCUMENT_GENERATOR` to generate and to read jobs and documents (`DOCUMENT_READER` reads them without generating). 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 its `status` is `completed` (or `failed` or `cancelled`). Its items, `GET /tenants/{tenantKey}/documents/jobs/{requestId}/items`, each name their `documentId`. 6. **Download** the PDF: `GET /tenants/{tenantKey}/documents/{documentId}/content`. `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. - **Quality profiles** (alpha, `x-experimental`, contract ADR 0010) record how an organisation writes: rules with a plain-language intent, a severity and extras per kind of checking system (`listQualityProfiles` and the rest of the group). A release binds the profiles every template in it is checked against, and a template adds its own (`quality` on `CatalogReleaseDto` and `TemplateDto`). 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 name, 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`, `DOCUMENT_READER`, `CONTENT_PUBLISHER`, `TENANT_ADMINISTRATOR`), the roles stored on its API key. Managing tenants needs the platform role `TENANT_MANAGER`. A request member that needs a permission beyond its operation\'s says so in its description: changing a quality binding (`quality`, alpha) needs `QUALITY_EDIT` as well. ## 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; - `help` (optional): the type\'s page with this request\'s context, such as the `operation` that answered, for hints that fit it. It names this contract\'s terms only, never a value. 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. Six statuses are not listed on each operation, because any operation may answer them: 405 `method-not-allowed`, 406 `not-acceptable`, 413 `content-too-large` and 415 `unsupported-media-type` (the last two where it takes a body), 500 `internal-error`, and 501 `operation-not-implemented`. `x-problem-types` marks them `anyOperation: true`. ## Compatibility within 2.x A minor version adds and never takes away, so a client built against an earlier 2.x keeps working against a later 2.x server. A minor version may add: - operations, and optional request members and query parameters; - **response members**: ignore a member you do not recognize; - **enum values in responses**: a status, kind or reason may gain a value. Treat one you do not recognize as unknown rather than failing, and keep a default branch when switching on an enum. The client libraries read it without failing: the Kotlin, Jakarta and .NET enums as their `unknown_default_open_api` member (`UNKNOWN_DEFAULT_OPEN_API` in Jakarta, `UnknownDefaultOpenApi` in .NET), the Python client as an unknown member that keeps the value, and the Node.js client as the string received; - problem types and validation codes (see \"Errors\"). It never removes or renames a member or an enum value, makes an optional request member required, or narrows what a request may send. A server refuses a request enum value it does not know with 400, so never send `unknown_default_open_api`. Operations and members marked `x-experimental` are outside these rules. ## 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, 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-beta.2
5
+ * The version of the OpenAPI document: 2.0.0-beta.4
6
6
  *
7
7
  *
8
8
  * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).
@@ -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. - **Quality profiles** (alpha, `x-experimental`, contract ADR 0010) record how an organisation writes: rules with a plain-language intent, a severity and extras per kind of checking system (`listQualityProfiles` and the rest of the group). A release binds the profiles every template in it is checked against, and a template adds its own (`quality` on `CatalogReleaseDto` and `TemplateDto`). 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`. A request member that needs a permission beyond its operation\'s says so in its description: changing a quality binding (`quality`, alpha) needs `QUALITY_EDIT` as well. ## 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; - `help` (optional): the type\'s page with this request\'s context, such as the `operation` that answered, for hints that fit it. It names this contract\'s terms only, never a value. 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. Six statuses are not listed on each operation, because any operation may answer them: 405 `method-not-allowed`, 406 `not-acceptable`, 413 `content-too-large` and 415 `unsupported-media-type` (the last two where it takes a body), 500 `internal-error`, and 501 `operation-not-implemented`. `x-problem-types` marks them `anyOperation: true`. ## 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`.
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 `DOCUMENT_GENERATOR` to generate and to read jobs and documents (`DOCUMENT_READER` reads them without generating). 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 its `status` is `completed` (or `failed` or `cancelled`). Its items, `GET /tenants/{tenantKey}/documents/jobs/{requestId}/items`, each name their `documentId`. 6. **Download** the PDF: `GET /tenants/{tenantKey}/documents/{documentId}/content`. `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. - **Quality profiles** (alpha, `x-experimental`, contract ADR 0010) record how an organisation writes: rules with a plain-language intent, a severity and extras per kind of checking system (`listQualityProfiles` and the rest of the group). A release binds the profiles every template in it is checked against, and a template adds its own (`quality` on `CatalogReleaseDto` and `TemplateDto`). 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 name, 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`, `DOCUMENT_READER`, `CONTENT_PUBLISHER`, `TENANT_ADMINISTRATOR`), the roles stored on its API key. Managing tenants needs the platform role `TENANT_MANAGER`. A request member that needs a permission beyond its operation\'s says so in its description: changing a quality binding (`quality`, alpha) needs `QUALITY_EDIT` as well. ## 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; - `help` (optional): the type\'s page with this request\'s context, such as the `operation` that answered, for hints that fit it. It names this contract\'s terms only, never a value. 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. Six statuses are not listed on each operation, because any operation may answer them: 405 `method-not-allowed`, 406 `not-acceptable`, 413 `content-too-large` and 415 `unsupported-media-type` (the last two where it takes a body), 500 `internal-error`, and 501 `operation-not-implemented`. `x-problem-types` marks them `anyOperation: true`. ## Compatibility within 2.x A minor version adds and never takes away, so a client built against an earlier 2.x keeps working against a later 2.x server. A minor version may add: - operations, and optional request members and query parameters; - **response members**: ignore a member you do not recognize; - **enum values in responses**: a status, kind or reason may gain a value. Treat one you do not recognize as unknown rather than failing, and keep a default branch when switching on an enum. The client libraries read it without failing: the Kotlin, Jakarta and .NET enums as their `unknown_default_open_api` member (`UNKNOWN_DEFAULT_OPEN_API` in Jakarta, `UnknownDefaultOpenApi` in .NET), the Python client as an unknown member that keeps the value, and the Node.js client as the string received; - problem types and validation codes (see \"Errors\"). It never removes or renames a member or an enum value, makes an optional request member required, or narrows what a request may send. A server refuses a request enum value it does not know with 400, so never send `unknown_default_open_api`. Operations and members marked `x-experimental` are outside these rules. ## 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, 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-beta.2
7
+ * The version of the OpenAPI document: 2.0.0-beta.4
8
8
  *
9
9
  *
10
10
  * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).