@classytic/arc 2.45.2 → 2.47.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (333) hide show
  1. package/README.md +1 -1
  2. package/dist/{EventTransport-DHb1tpu-.mjs → EventTransport-BHKy4_Bi.mjs} +5 -6
  3. package/dist/{EventTransport-CiicKz2Z.d.mts → EventTransport-CYEoCJGe.d.mts} +0 -2
  4. package/dist/{HookSystem-C1u0EUnt.mjs → HookSystem-CAIDVoKC.mjs} +3 -4
  5. package/dist/{QueryCache--5uAuYPW.d.mts → QueryCache-DdvrGG8Q.d.mts} +1 -3
  6. package/dist/{ResourceRegistry-D2jXWVN_.mjs → ResourceRegistry-23Ml6FNe.mjs} +15 -4
  7. package/dist/{acquire-DTkA8Lme.mjs → acquire-DoFX06fm.mjs} +2 -3
  8. package/dist/{actionPermissions-DRVk6m7x.mjs → actionPermissions-DXrlWHHK.mjs} +37 -42
  9. package/dist/audit/index.d.mts +2 -10
  10. package/dist/audit/index.mjs +8 -12
  11. package/dist/auth/audit.d.mts +0 -2
  12. package/dist/auth/audit.mjs +2 -3
  13. package/dist/auth/index.d.mts +9 -17
  14. package/dist/auth/index.mjs +26 -29
  15. package/dist/auth/redis-session.d.mts +2 -4
  16. package/dist/auth/redis-session.mjs +2 -3
  17. package/dist/{authorizationDecision-D48fUJv1.mjs → authorizationDecision-DYiubkYw.mjs} +5 -6
  18. package/dist/{base-CZyixEQR.d.mts → base-HXNgPQww.d.mts} +1 -7
  19. package/dist/{boundedMap-DkKiPifd.mjs → boundedMap-CtdzpJ3X.mjs} +2 -3
  20. package/dist/{buildHandler-BiZ4VATS.mjs → buildHandler-CARdmPNo.mjs} +5 -6
  21. package/dist/cache/index.d.mts +4 -10
  22. package/dist/cache/index.mjs +5 -6
  23. package/dist/{caching-Cj0as-P1.mjs → caching-QRiryDLs.mjs} +3 -4
  24. package/dist/{claimed-ChI13rUR.mjs → claimed-BLecr1j3.mjs} +2 -3
  25. package/dist/cleanup/index.d.mts +4 -18
  26. package/dist/cleanup/index.mjs +12 -20
  27. package/dist/cli/commands/describe.d.mts +1 -3
  28. package/dist/cli/commands/describe.mjs +4 -5
  29. package/dist/cli/commands/docs.d.mts +1 -3
  30. package/dist/cli/commands/docs.mjs +4 -5
  31. package/dist/cli/commands/doctor.d.mts +1 -3
  32. package/dist/cli/commands/doctor.mjs +2 -3
  33. package/dist/cli/commands/generate.d.mts +1 -1
  34. package/dist/cli/commands/generate.mjs +2 -2
  35. package/dist/cli/commands/init.d.mts +1 -1
  36. package/dist/cli/commands/init.mjs +2 -2
  37. package/dist/cli/commands/introspect.d.mts +1 -3
  38. package/dist/cli/commands/introspect.mjs +3 -4
  39. package/dist/cli/index.d.mts +2 -2
  40. package/dist/cli/index.mjs +3 -3
  41. package/dist/{constants-D_aiew34.mjs → constants-Cx7BcnHT.mjs} +2 -3
  42. package/dist/context/index.d.mts +0 -8
  43. package/dist/context/index.mjs +6 -7
  44. package/dist/core/index.d.mts +3 -3
  45. package/dist/core/index.mjs +8 -8
  46. package/dist/{core-QIZ2560Y.mjs → core-0WyMuo0f.mjs} +9 -12
  47. package/dist/{createActionRouter-CvH84dyx.mjs → createActionRouter-mLAGbpDV.mjs} +7 -8
  48. package/dist/{createAggregationRouter-DGyK2Hp6.mjs → createAggregationRouter-BEAjn3dA.mjs} +9 -10
  49. package/dist/{createApp-CKjZpmq9.mjs → createApp-QDP4vYWH.mjs} +49 -62
  50. package/dist/{createMcpServer-DSztofa9.d.mts → createMcpServer-DzXHX0SO.d.mts} +1 -3
  51. package/dist/{defineAggregation-BLza7Ca4.mjs → defineAggregation-CFNfvz-C.mjs} +2 -3
  52. package/dist/{defineResource-CEo0gDCb.mjs → defineResource-BROJmhzJ.mjs} +80 -29
  53. package/dist/discovery/index.d.mts +1 -3
  54. package/dist/discovery/index.mjs +2 -3
  55. package/dist/docs/index.d.mts +8 -8
  56. package/dist/docs/index.mjs +4 -5
  57. package/dist/{elevation-BW2J3tNj.d.mts → elevation-DPD0hcU-.d.mts} +0 -2
  58. package/dist/{elevation-BJTsSnke.mjs → elevation-DrXeEWWk.mjs} +9 -10
  59. package/dist/encryption/index.d.mts +1 -7
  60. package/dist/encryption/index.mjs +8 -13
  61. package/dist/{errorHandler--4rSMMvq.d.mts → errorHandler-B9r88jZV.d.mts} +8 -3
  62. package/dist/{errorHandler-2p4SL5zm.mjs → errorHandler-BiBXtxj4.mjs} +16 -6
  63. package/dist/{errors-JYc9vwqE.d.mts → errors-DTo0me1o.d.mts} +0 -2
  64. package/dist/{errors-grZkIA8N.mjs → errors-DnrUChAy.mjs} +2 -3
  65. package/dist/{eventPlugin-BtmA4-3P.d.mts → eventPlugin-BY38F6yK.d.mts} +1 -7
  66. package/dist/{eventPlugin-ItcYBGUs.mjs → eventPlugin-BhKLUe7H.mjs} +10 -12
  67. package/dist/{eventTypes-Ck6fD3ne.mjs → eventTypes-CCIRGakw.mjs} +5 -8
  68. package/dist/events/index.d.mts +5 -17
  69. package/dist/events/index.mjs +9 -9
  70. package/dist/events/transports/redis-stream-entry.d.mts +1 -1
  71. package/dist/events/transports/redis-stream-entry.mjs +5 -6
  72. package/dist/events/transports/redis.d.mts +2 -4
  73. package/dist/events/transports/redis.mjs +3 -4
  74. package/dist/{externalPaths-CmGOxOtD.d.mts → externalPaths-BOqdq5wr.d.mts} +0 -2
  75. package/dist/factory/index.d.mts +4 -14
  76. package/dist/factory/index.mjs +12 -18
  77. package/dist/{fastify-augmentation-DRlCIWE9.d.mts → fastify-augmentation-bzkWPt1f.d.mts} +4 -10
  78. package/dist/{fields-BRX0Krcj.mjs → fields-CYdpcV73.mjs} +2 -3
  79. package/dist/{fields-BBSpf8pS.d.mts → fields-JTkrtO-r.d.mts} +0 -2
  80. package/dist/{filter-merge-CDc7YMwX.mjs → filter-merge-6kasezRH.mjs} +2 -3
  81. package/dist/{generate-DCGuEbqI.d.mts → generate-C-g_KOkV.d.mts} +0 -4
  82. package/dist/{generate-hvg7V2g1.mjs → generate-DUkcbc4r.mjs} +7 -12
  83. package/dist/{headers-Cqkg4LzI.mjs → headers-KxhrKevA.mjs} +3 -4
  84. package/dist/{health-PVt0VjOx.mjs → health-CRJg3IIq.mjs} +2 -3
  85. package/dist/{health-DyeP3mTW.mjs → health-jkYNdobJ.mjs} +4 -7
  86. package/dist/hooks/index.d.mts +1 -1
  87. package/dist/hooks/index.mjs +2 -2
  88. package/dist/http-cache/index.d.mts +211 -0
  89. package/dist/http-cache/index.mjs +605 -0
  90. package/dist/http-cache/purgers/cloudflare.d.mts +13 -0
  91. package/dist/http-cache/purgers/cloudflare.mjs +46 -0
  92. package/dist/http-cache/purgers/fastly.d.mts +12 -0
  93. package/dist/http-cache/purgers/fastly.mjs +47 -0
  94. package/dist/http-cache/testing/index.d.mts +68 -0
  95. package/dist/http-cache/testing/index.mjs +168 -0
  96. package/dist/idempotency/index.d.mts +3 -9
  97. package/dist/idempotency/index.mjs +11 -14
  98. package/dist/idempotency/redis.d.mts +1 -1
  99. package/dist/idempotency/redis.mjs +3 -4
  100. package/dist/{index-Bxriq3so.d.mts → index-B5i9-vuP.d.mts} +4 -26
  101. package/dist/{index-Chgz3d0i.d.mts → index-BAXDo5eE.d.mts} +1 -7
  102. package/dist/{index-Beg3aNnK.d.mts → index-BxZS-8So.d.mts} +67 -25
  103. package/dist/{index-WH7xgvxS.d.mts → index-Cy2-QffW.d.mts} +40 -92
  104. package/dist/{index-uhkUA5-U.d.mts → index-D1X_C_qz.d.mts} +13 -23
  105. package/dist/{index-CUJvoyw3.d.mts → index-DFCCQ9AE.d.mts} +2 -24
  106. package/dist/index.d.mts +7 -9
  107. package/dist/index.mjs +12 -13
  108. package/dist/{init-jC3rMPzb.mjs → init-CACwpktI.mjs} +18 -35
  109. package/dist/{init-Cscs4lab.d.mts → init-CV2_Fw3H.d.mts} +0 -4
  110. package/dist/integrations/event-gateway.d.mts +3 -5
  111. package/dist/integrations/event-gateway.mjs +3 -4
  112. package/dist/integrations/index.d.mts +3 -3
  113. package/dist/integrations/index.mjs +1 -1
  114. package/dist/integrations/jobs/index.d.mts +1 -1
  115. package/dist/integrations/jobs/index.mjs +7 -11
  116. package/dist/integrations/mcp/index.d.mts +7 -39
  117. package/dist/integrations/mcp/index.mjs +8 -14
  118. package/dist/integrations/mcp/testing.d.mts +3 -5
  119. package/dist/integrations/mcp/testing.mjs +3 -4
  120. package/dist/integrations/streamline.d.mts +1 -3
  121. package/dist/integrations/streamline.mjs +4 -5
  122. package/dist/integrations/webhooks.d.mts +2 -4
  123. package/dist/integrations/webhooks.mjs +5 -5
  124. package/dist/integrations/websocket-pushref-redis.d.mts +2 -4
  125. package/dist/integrations/websocket-pushref-redis.mjs +2 -3
  126. package/dist/integrations/websocket-redis.d.mts +2 -4
  127. package/dist/integrations/websocket-redis.mjs +2 -3
  128. package/dist/integrations/websocket.d.mts +2 -2
  129. package/dist/integrations/websocket.mjs +13 -24
  130. package/dist/{interface-JJzwH4Ro.d.mts → interface-BmExzQRD.d.mts} +0 -2
  131. package/dist/{interface-BOk3YnTz.d.mts → interface-WR1U0K7t.d.mts} +0 -2
  132. package/dist/{jsonBody-ptwyzZQ-.mjs → jsonBody-CzDBkCme.mjs} +3 -4
  133. package/dist/{keys-C1vFuSbv.mjs → keys-Cbwf6r1B.mjs} +2 -3
  134. package/dist/{loadResources-CHPDyIPn.mjs → loadResources-Kr6vuljv.mjs} +4 -5
  135. package/dist/{loadResourcesFromEntry-BkHHTu_B.mjs → loadResourcesFromEntry-D2e0qoDR.mjs} +3 -4
  136. package/dist/logger/index.d.mts +1 -3
  137. package/dist/logger/index.mjs +2 -2
  138. package/dist/{logger-C5bvCiAK.mjs → logger-C110X5Yz.mjs} +3 -5
  139. package/dist/{mcpPlugin-C9qohJCF.mjs → mcpPlugin-4lIPr9OJ.mjs} +41 -60
  140. package/dist/{memory-CxiTwT0j.mjs → memory-D9qkhXiB.mjs} +4 -5
  141. package/dist/{metrics-Ckp2zRy-.mjs → metrics-B-qrrWfI.mjs} +4 -5
  142. package/dist/middleware/index.d.mts +1 -5
  143. package/dist/middleware/index.mjs +4 -5
  144. package/dist/migrations/index.d.mts +0 -2
  145. package/dist/migrations/index.mjs +3 -4
  146. package/dist/{module-CfnKuIuH.mjs → module-BD8xHgrz.mjs} +2 -3
  147. package/dist/{multiTenant-CAtYlW6H.d.mts → multiTenant-KZj8j1uJ.d.mts} +1 -5
  148. package/dist/{multipartBody-BFasGtP9.mjs → multipartBody-qU7KCn1l.mjs} +2 -3
  149. package/dist/observeSend-BnPtTotW.mjs +20 -0
  150. package/dist/{openapi-DAPxjYHX.mjs → openapi-DoVa5SVP.mjs} +18 -28
  151. package/dist/outbox-admin/index.d.mts +2 -4
  152. package/dist/outbox-admin/index.mjs +6 -7
  153. package/dist/{outbox-module-gZCHoE4H.d.mts → outbox-module-5Mnwcycy.d.mts} +3 -9
  154. package/dist/outbox-module-DyITEIop.mjs +297 -0
  155. package/dist/permissions/index.d.mts +4 -4
  156. package/dist/permissions/index.mjs +7 -7
  157. package/dist/{permissions-B14c3OMp.mjs → permissions-BBy4bOGi.mjs} +19 -29
  158. package/dist/{pipe-CQv7PsAK.mjs → pipe-BOm2o4UA.mjs} +3 -4
  159. package/dist/pipeline/index.d.mts +1 -9
  160. package/dist/pipeline/index.mjs +5 -8
  161. package/dist/{plan-CpnTykjb.mjs → plan-DDIGwuxr.mjs} +5 -9
  162. package/dist/{plugin-DXTjVg_Q.mjs → plugin-Bn4D_0XK.mjs} +156 -64
  163. package/dist/plugins/index.d.mts +8 -16
  164. package/dist/plugins/index.mjs +22 -26
  165. package/dist/plugins/response-cache.d.mts +2 -4
  166. package/dist/plugins/response-cache.mjs +10 -10
  167. package/dist/plugins/tracing-entry.d.mts +1 -1
  168. package/dist/plugins/tracing-entry.mjs +3 -4
  169. package/dist/{pluralize-C3VJKRGp.mjs → pluralize-ClEjcKlG.mjs} +2 -3
  170. package/dist/policy.types-DPqToKG1.d.mts +50 -0
  171. package/dist/presets/filesUpload.d.mts +4 -6
  172. package/dist/presets/filesUpload.mjs +6 -7
  173. package/dist/presets/index.d.mts +3 -19
  174. package/dist/presets/index.mjs +2 -2
  175. package/dist/presets/multiTenant.d.mts +1 -1
  176. package/dist/presets/multiTenant.mjs +7 -7
  177. package/dist/presets/search.d.mts +3 -5
  178. package/dist/presets/search.mjs +3 -4
  179. package/dist/{presets-CquqYJPy.mjs → presets-DK2jh5YR.mjs} +11 -18
  180. package/dist/{projection-CgfSLOSM.mjs → projection-BHH-sXyS.mjs} +3 -4
  181. package/dist/purger.types-2wNJK_89.mjs +24 -0
  182. package/dist/purger.types-DvPp4-yd.d.mts +26 -0
  183. package/dist/{pushref-registry-UxCkoA4C.d.mts → pushref-registry-d86QUaSq.d.mts} +0 -6
  184. package/dist/{queryCachePlugin-D0HUISHJ.mjs → queryCachePlugin-Ckqe98AM.mjs} +8 -10
  185. package/dist/{queryCachePlugin-C2lZjTxk.d.mts → queryCachePlugin-DYQUyeJ9.d.mts} +2 -4
  186. package/dist/{rateLimitKey-AvkBOMkl.mjs → rateLimitKey-CWAjlqcN.mjs} +2 -3
  187. package/dist/{realtime-CbWtVbqK.mjs → realtime-BIJi9USY.mjs} +17 -19
  188. package/dist/{redis-BDgv9Glw.d.mts → redis-RpDMemdm.d.mts} +2 -4
  189. package/dist/{redis-stream-BMk-bpQS.d.mts → redis-stream-CS1N9dwM.d.mts} +1 -3
  190. package/dist/{redisShapes-CQksY67q.d.mts → redisShapes-CqBXTn_s.d.mts} +0 -2
  191. package/dist/registry/index.d.mts +2 -12
  192. package/dist/registry/index.mjs +3 -3
  193. package/dist/{registry-BVwpAuFI.mjs → registry-y9ZA-R_J.mjs} +7 -12
  194. package/dist/{outbox-module-B4FAkx3A.mjs → relay-BNrC1CEP.mjs} +8 -306
  195. package/dist/{renewingLease-CykpeNcQ.mjs → renewingLease-CS43br5E.mjs} +2 -3
  196. package/dist/{replyHelpers-DA51IZio.mjs → replyHelpers-oZDzakGb.mjs} +3 -4
  197. package/dist/{requestContext-DIWHKDtQ.mjs → requestContext-fWb_YaV2.mjs} +2 -3
  198. package/dist/{requirement-Cp_fsMDL.mjs → requirement--2hWyyHi.mjs} +2 -3
  199. package/dist/{requirement-CbiLdQ1n.d.mts → requirement-CTRQjjQx.d.mts} +0 -2
  200. package/dist/{resourceRateLimit-BFuluodF.mjs → resourceRateLimit-1WbcyMZY.mjs} +3 -4
  201. package/dist/{resourceRateLimit-Wf6d6FL9.d.mts → resourceRateLimit-DCWglD7V.d.mts} +1 -3
  202. package/dist/{rolldown-runtime-D_lMdYOd.mjs → rolldown-runtime-yH2lHMo_.mjs} +2 -3
  203. package/dist/{routeValidator-DuLonYwr.mjs → routeValidator-BSlRIA5c.mjs} +2 -3
  204. package/dist/{runtimeCapabilities-CydRfm0i.mjs → runtimeCapabilities-CYCEtU1W.mjs} +2 -3
  205. package/dist/{schedules-B693KXxa.mjs → schedules-B5WGlYIT.mjs} +132 -9
  206. package/dist/{schemaConverter-DNvZWTV6.mjs → schemaConverter-DtNvts-6.mjs} +3 -4
  207. package/dist/{schemaIR-REV2y7Wd.mjs → schemaIR-uS_RHqa3.mjs} +3 -4
  208. package/dist/schemas/index.d.mts +0 -2
  209. package/dist/schemas/index.mjs +2 -3
  210. package/dist/scim/index.d.mts +0 -12
  211. package/dist/scim/index.mjs +10 -18
  212. package/dist/scope/index.d.mts +2 -6
  213. package/dist/scope/index.mjs +5 -5
  214. package/dist/{scope-Bevxy_ST.mjs → scope-BwVLSyNG.mjs} +5 -6
  215. package/dist/{sessionManager-qimlKV0P.d.mts → sessionManager-CdvDF04x.d.mts} +2 -4
  216. package/dist/{shutdown-CfrqPR7A.mjs → shutdown-BJiJN7FT.mjs} +2 -3
  217. package/dist/{simpleEqualityMatcher-BJwfuRKP.mjs → simpleEqualityMatcher-DGRLq-1k.mjs} +2 -3
  218. package/dist/{sse-CuNNWr2z.mjs → sse-B_50llZu.mjs} +8 -9
  219. package/dist/{sseStream-C_2ujAVY.mjs → sseStream-BjSo9Ult.mjs} +3 -4
  220. package/dist/{storage-Cx9Sz3Ou.d.mts → storage-odC5MNKN.d.mts} +0 -2
  221. package/dist/{store-helpers-C8uBGCbb.mjs → store-helpers-D-n5cwy5.mjs} +2 -3
  222. package/dist/{streaming-Bdq_M4d5.mjs → streaming-Dcgqa-hH.mjs} +2 -3
  223. package/dist/{subscriberIdentity-B-KpZkdl.mjs → subscriberIdentity-C9KhIXTF.mjs} +2 -3
  224. package/dist/{tenancy-C5PCvm1h.mjs → tenancy-COrhjPRZ.mjs} +3 -4
  225. package/dist/{tenantPreparation-dYvWrgNa.mjs → tenantPreparation-BElWHytd.mjs} +5 -6
  226. package/dist/testing/cleanupStoreContract.d.mts +2 -4
  227. package/dist/testing/cleanupStoreContract.mjs +2 -3
  228. package/dist/testing/index.d.mts +6 -32
  229. package/dist/testing/index.mjs +24 -37
  230. package/dist/testing/outboxStoreContract.d.mts +1 -3
  231. package/dist/testing/outboxStoreContract.mjs +3 -4
  232. package/dist/testing/requiredPorts.d.mts +2 -4
  233. package/dist/testing/requiredPorts.mjs +3 -4
  234. package/dist/testing/storageContract.d.mts +2 -4
  235. package/dist/testing/storageContract.mjs +2 -3
  236. package/dist/{timing-DCqsezX8.mjs → timing-CaxKbRk_.mjs} +3 -5
  237. package/dist/{tracing-Dro5eH6j.d.mts → tracing-JSFiBl5r.d.mts} +0 -2
  238. package/dist/{transactionContext-DrcNyjpv.mjs → transactionContext-8qKON0Nk.mjs} +2 -3
  239. package/dist/{typeGuards-CEl10KPy.mjs → typeGuards-DVjVSsXO.mjs} +2 -3
  240. package/dist/types/index.d.mts +4 -4
  241. package/dist/types/index.mjs +1 -1
  242. package/dist/types/storage.d.mts +1 -1
  243. package/dist/types/storage.mjs +1 -1
  244. package/dist/{types-ByHn9rEO.d.mts → types-0Dqlbgn8.d.mts} +0 -2
  245. package/dist/{types-BJ-2XqVF.d.mts → types-BeEJm-DV.d.mts} +114 -14
  246. package/dist/{types-DVLddu2q.d.mts → types-C0YJAiL0.d.mts} +0 -2
  247. package/dist/{types-D9NWjpYc.mjs → types-DZHqOuJE.mjs} +5 -6
  248. package/dist/{types-D3Ixsh00.d.mts → types-DeLiuaNv.d.mts} +2 -4
  249. package/dist/{types-Ddl9OjmE.d.mts → types-DnkIALZ8.d.mts} +0 -4
  250. package/dist/usage/index.d.mts +2 -10
  251. package/dist/usage/index.mjs +8 -12
  252. package/dist/{userHelpers-BHig1kHq.mjs → userHelpers-_eGj6kf0.mjs} +2 -3
  253. package/dist/utils/index.d.mts +5 -39
  254. package/dist/utils/index.mjs +12 -12
  255. package/dist/{utils-BG5P7_Vb.mjs → utils-Dd6MWpye.mjs} +20 -30
  256. package/dist/{validate-D_mdOCir.mjs → validate-BaF5wd0x.mjs} +5 -7
  257. package/dist/{versioning-DBGHjPh7.mjs → versioning-DyV7mwtK.mjs} +4 -5
  258. package/dist/{versioning-Bqm_57Qt.d.mts → versioning-S18y2-0C.d.mts} +1 -15
  259. package/dist/{websocket-Cs4awVyD.d.mts → websocket-BGuc-WVZ.d.mts} +1 -15
  260. package/dist/{workScope-DPPfM4m6.mjs → workScope-CmCBUmPR.mjs} +3 -4
  261. package/llms.txt +37 -30
  262. package/package.json +51 -22
  263. package/skills/arc/SKILL.md +65 -844
  264. package/skills/arc/references/agent-auth.md +82 -193
  265. package/skills/arc/references/api-reference.md +41 -245
  266. package/skills/arc/references/auth-api-keys.md +99 -0
  267. package/skills/arc/references/auth-better-auth-overlay.md +87 -0
  268. package/skills/arc/references/auth-better-auth.md +78 -0
  269. package/skills/arc/references/auth-permissions.md +100 -0
  270. package/skills/arc/references/auth-strategies.md +122 -0
  271. package/skills/arc/references/boot.md +80 -0
  272. package/skills/arc/references/enterprise-auth.md +65 -81
  273. package/skills/arc/references/events-outbox.md +90 -0
  274. package/skills/arc/references/events.md +75 -440
  275. package/skills/arc/references/integrations-jobs.md +74 -0
  276. package/skills/arc/references/integrations-realtime.md +84 -0
  277. package/skills/arc/references/integrations-webhooks.md +71 -0
  278. package/skills/arc/references/integrations-workflows.md +47 -0
  279. package/skills/arc/references/mcp-auth.md +83 -0
  280. package/skills/arc/references/mcp-custom-tools.md +125 -0
  281. package/skills/arc/references/mcp-setup.md +115 -0
  282. package/skills/arc/references/mcp-testing.md +63 -0
  283. package/skills/arc/references/multi-tenancy.md +56 -230
  284. package/skills/arc/references/permissions-scope.md +81 -0
  285. package/skills/arc/references/production-api.md +119 -0
  286. package/skills/arc/references/production-audit.md +101 -0
  287. package/skills/arc/references/production-boot.md +91 -0
  288. package/skills/arc/references/production-caching.md +63 -0
  289. package/skills/arc/references/production-distributed.md +75 -0
  290. package/skills/arc/references/production-idempotency.md +83 -0
  291. package/skills/arc/references/production-observability.md +83 -0
  292. package/skills/arc/references/production-realtime.md +70 -0
  293. package/skills/arc/references/production-reliability.md +100 -0
  294. package/skills/arc/references/production-shutdown.md +43 -0
  295. package/skills/arc/references/querying.md +76 -0
  296. package/skills/arc/references/resources.md +97 -0
  297. package/skills/arc/references/schedules.md +79 -0
  298. package/skills/arc/references/scim.md +61 -208
  299. package/skills/arc/references/tenancy-scope-install.md +82 -0
  300. package/skills/arc/references/testing.md +101 -144
  301. package/skills/arc/references/usage-cleanup-capabilities.md +45 -0
  302. package/skills/arc/references/validation.md +91 -0
  303. package/skills/arc/references/writes-hooks-errors.md +80 -0
  304. package/skills/arc-code-review/SKILL.md +67 -114
  305. package/skills/arc-code-review/references/arc-cheatsheet.md +68 -167
  306. package/skills/arc-code-review/references/mongokit-repositories.md +104 -0
  307. package/skills/arc-code-review/references/recipe-events-cache-jobs.md +112 -0
  308. package/skills/arc-code-review/references/recipe-resource.md +100 -0
  309. package/skills/arc-code-review/references/recipe-schemas-fields.md +93 -0
  310. package/skills/arc-code-review/references/recipe-scope-permissions.md +82 -0
  311. package/skills/arc-code-review/references/scaffolding.md +61 -198
  312. package/skills/arc-code-review/references/severity.md +49 -102
  313. package/skills/arc-code-review/references/smells-auth-scope.md +80 -0
  314. package/skills/arc-code-review/references/smells-data-events.md +66 -0
  315. package/skills/arc-code-review/references/smells-imports-style.md +59 -0
  316. package/skills/arc-code-review/references/smells-platform.md +89 -0
  317. package/skills/arc-code-review/references/smells-routes-schemas.md +66 -0
  318. package/skills/arc-module-publishing/SKILL.md +82 -208
  319. package/skills/arc-module-publishing/references/action-presets-and-plugins.md +87 -0
  320. package/skills/arc-module-publishing/references/build-and-types.md +73 -0
  321. package/skills/arc-module-publishing/references/module-lifecycle.md +101 -0
  322. package/skills/arc-module-publishing/references/package-manifest.md +34 -122
  323. package/skills/arc-module-publishing/references/publishing-workflow.md +44 -140
  324. package/skills/arc-module-publishing/references/resource-assembly.md +102 -0
  325. package/skills/arc-module-publishing/references/testing-packages.md +82 -0
  326. package/skills/arc/references/auth.md +0 -729
  327. package/skills/arc/references/integrations.md +0 -452
  328. package/skills/arc/references/mcp.md +0 -691
  329. package/skills/arc/references/production.md +0 -835
  330. package/skills/arc-code-review/references/anti-patterns.md +0 -1008
  331. package/skills/arc-code-review/references/migration-recipes.md +0 -649
  332. package/skills/arc-code-review/references/mongokit-migration.md +0 -360
  333. package/skills/arc-module-publishing/references/authoring-modules.md +0 -327
@@ -1,835 +0,0 @@
1
- # Arc Production Features
2
-
3
- Health checks, audit trail, idempotency, tracing, SSE, caching, graceful shutdown.
4
-
5
- ## v2.9 Security Defaults
6
-
7
- - **Field-write perms reject by default** — `defineResource({ fields, onFieldWriteDenied })`. Default `'reject'` → 403 with denied field list. Legacy silent-strip: `onFieldWriteDenied: 'strip'`.
8
- - **Elevation always emits `arc.scope.elevated`** — subscribe via `fastify.events.subscribe('arc.scope.elevated', handler)` for audit. `onElevation` callback still supported.
9
- - **multiTenant injects org on UPDATE** — closes cross-tenant hop vector. Body-supplied `organizationId` overwritten with caller's scope.
10
- - **`verifySignature(body, secret, sig)` throws TypeError** if body isn't string/Buffer — register `@fastify/raw-body` before webhook routes; pass `req.rawBody`.
11
- - **Upload `sanitizeFilename` (preset)** — strict by default; `false` / `'*'` / custom fn to relax per adapter needs.
12
- - **Idempotency `namespace`** — fold an env key into the fingerprint when multiple deployments share a Redis (prod + canary, api + jobs).
13
-
14
- ## Health Plugin
15
-
16
- Kubernetes-ready liveness/readiness probes:
17
-
18
- ```typescript
19
- import { healthPlugin } from '@classytic/arc/plugins';
20
-
21
- await fastify.register(healthPlugin, {
22
- prefix: '/_health',
23
- version: '1.0.0',
24
- checks: [
25
- { name: 'mongodb', check: () => mongoose.connection.readyState === 1, critical: true },
26
- { name: 'redis', check: async () => await redis.ping() === 'PONG', timeout: 3000 },
27
- ],
28
- });
29
-
30
- // GET /_health/live → { status: 'ok', timestamp, version }
31
- // GET /_health/ready → { status: 'ok', checks: { mongodb: { status: 'ok', latency: 5 } } }
32
- // Returns 503 if critical check fails
33
- ```
34
-
35
- ## Request ID Plugin
36
-
37
- ```typescript
38
- import { requestIdPlugin } from '@classytic/arc/plugins';
39
-
40
- await fastify.register(requestIdPlugin, {
41
- header: 'x-request-id',
42
- setResponseHeader: true,
43
- generator: () => crypto.randomUUID(),
44
- });
45
- ```
46
-
47
- ## Graceful Shutdown Plugin
48
-
49
- Registered by default (`arcPlugins.gracefulShutdown`). Pass an options object to configure it inline from `createApp`.
50
-
51
- ```typescript
52
- import { gracefulShutdownPlugin } from '@classytic/arc/plugins';
53
-
54
- await fastify.register(gracefulShutdownPlugin, {
55
- timeout: 30000, // hard cap; drainDelayMs counts against it
56
- drainDelayMs: 10000, // lame-duck window — see below
57
- signals: ['SIGTERM', 'SIGINT'],
58
- logEvents: true,
59
- onShutdown: async () => {
60
- await mongoose.disconnect();
61
- await redis.quit();
62
- },
63
- onForceExit: () => {}, // tests: stop a timeout from killing the runner
64
- });
65
-
66
- // Sequence: signal → shutdownState.draining = true (/ready starts 503ing)
67
- // → wait drainDelayMs (still serving) → fastify.close() (stops accepting,
68
- // drains in-flight) → onShutdown() → exit naturally
69
- ```
70
-
71
- **`fastify.close()` runs BEFORE `onShutdown`** — so `onShutdown` is where you release what arc doesn't own (DB connections, your own Redis client), and it runs after in-flight requests are done. Don't close anything a request might still need.
72
-
73
- ### `drainDelayMs` — the rolling-deploy 502
74
-
75
- Default `0`, which is the pre-2.41 behaviour: close the moment SIGTERM arrives. That is the classic rolling-deploy 502 — a load balancer keeps routing to an instance until its readiness probe has failed **for several intervals**, and by then the instance already stopped accepting.
76
-
77
- `drainDelayMs` is the window between "start failing readiness" and "stop accepting":
78
-
79
- - `/_health/ready` → `503 { status: 'draining' }` immediately on signal
80
- - `/_health/live` → stays `200` (a draining process is alive — that's the point; a 503 here gets the pod **killed**, not drained)
81
- - everything already routed here is still served for the whole window
82
-
83
- Set it **above** your LB's deregistration window — typically 5000–15000ms. On Kubernetes, also keep `terminationGracePeriodSeconds` > `drainDelayMs + timeout`, or the kubelet SIGKILLs you mid-drain.
84
-
85
- ```typescript
86
- createApp({
87
- arcPlugins: { gracefulShutdown: { drainDelayMs: 10_000, timeout: 30_000 } },
88
- });
89
- ```
90
-
91
- **Do not also write `process.on('SIGTERM', () => app.close())`.** The plugin already owns those signals; a second handler closes the server immediately and skips the drain entirely — you get the 502s back while the config says you fixed them.
92
-
93
- ## Audit Plugin
94
-
95
- Change tracking. Pass a `RepositoryLike` for persistence, or omit for in-memory dev:
96
-
97
- ```typescript
98
- import { auditPlugin } from '@classytic/arc/audit';
99
- import { Repository } from '@classytic/mongokit';
100
-
101
- // Development (in-memory)
102
- await fastify.register(auditPlugin, { enabled: true });
103
-
104
- // Production — any kit (mongokit / prismakit / custom)
105
- await fastify.register(auditPlugin, {
106
- enabled: true,
107
- repository: new Repository(AuditModel),
108
- });
109
- // ── Retention (audit rows ARE `history: true` timelines — prune together) ──
110
- // Option A (zero code, Mongo): TTL index — the DB does it server-side.
111
- // AuditSchema.index({ timestamp: 1 }, { expireAfterSeconds: 60 * 60 * 24 * 365 });
112
- // Option B (built-in, single instance): retention: { maxAgeMs, purgeIntervalMs }.
113
- // Option C (multi-replica, RECOMMENDED): purgeIntervalMs: 0 + a schedulesPlugin
114
- // entry calling fastify.audit.purge(cutoff) — leader-safe, jittered, observable.
115
- // (The built-in timer runs on EVERY replica — idempotent but wasteful.)
116
- //
117
- // ── Indexes (kit territory — the audit model is yours) ──
118
- // Mongo: TTL index above + compound for the history timeline:
119
- // AuditSchema.index({ resource: 1, documentId: 1, timestamp: -1 });
120
- // SQL kits: index (resource, document_id, timestamp) + the kit's ttl/sweep plugin.
121
- //
122
- // ── Rich search (admin audit-log UI) ──
123
- // audit.query() is deliberately narrow. For full repo-core filter/sort/keyset
124
- // power + MCP tools, mount the audit repo AS a read-only resource:
125
- // defineResource({ name: 'audit-log', crud: { list: true, get: true },
126
- // adapter: { repository: auditRepo },
127
- // queryParser: new QueryParser({ allowedFilterFields: ['resource','documentId','userId','action','organizationId'] }),
128
- // permissions: { list: requireRoles(['auditor']), get: requireRoles(['auditor']) } });
129
-
130
- // Usage
131
- await fastify.audit.create('product', product._id, product, request.auditContext);
132
- await fastify.audit.update('product', id, beforeDoc, afterDoc, request.auditContext);
133
- await fastify.audit.delete('product', id, deletedDoc, request.auditContext);
134
- await fastify.audit.custom('product', id, 'price_changed', { oldPrice: 100, newPrice: 150 }, ctx);
135
-
136
- // Query
137
- const entries = await fastify.audit.query({
138
- resource: 'product', documentId: 'prod-123',
139
- action: 'update', from: new Date('2024-01-01'), limit: 100,
140
- });
141
- ```
142
-
143
- **Audit entry:**
144
-
145
- ```typescript
146
- interface AuditEntry {
147
- id: string; timestamp: Date;
148
- action: 'create' | 'update' | 'delete' | 'restore' | 'custom';
149
- resource: string; documentId: string;
150
- before?: Record<string, unknown>;
151
- after?: Record<string, unknown>;
152
- metadata?: Record<string, unknown>;
153
- context: { user?; organizationId?; requestId?; ipAddress?; userAgent?; };
154
- }
155
- ```
156
-
157
- **Custom store:** Implement `AuditStore` interface (`log`, `query`, `close`).
158
-
159
- ## Idempotency Plugin
160
-
161
- Exactly-once semantics for mutating operations:
162
-
163
- ```typescript
164
- import { idempotencyPlugin } from '@classytic/arc/idempotency';
165
-
166
- await fastify.register(idempotencyPlugin, {
167
- enabled: true,
168
- headerName: 'idempotency-key', // Default
169
- ttlMs: 86400000, // 24 hours
170
- lockTimeoutMs: 30000,
171
- methods: ['POST', 'PUT', 'PATCH'],
172
- include: [/\/orders/], // Only these routes
173
- exclude: [/\/health/],
174
- retryAfterSeconds: 1,
175
- });
176
- ```
177
-
178
- **Client:**
179
-
180
- ```typescript
181
- fetch('/api/orders', {
182
- method: 'POST',
183
- headers: { 'Idempotency-Key': 'order-abc123-uuid' },
184
- body: JSON.stringify({ items: [...] }),
185
- });
186
- // First request: processes, caches response
187
- // Retry: returns cached response + x-idempotency-replayed: true
188
- // Concurrent: returns 409 Conflict + Retry-After: 1
189
- ```
190
-
191
- **Storage backends:**
192
-
193
- ```typescript
194
- // Memory (default, dev) — omit both `repository` and `store`
195
- import { MemoryIdempotencyStore } from '@classytic/arc/idempotency';
196
-
197
- // Redis (production, multi-instance)
198
- import { RedisIdempotencyStore } from '@classytic/arc/idempotency/redis';
199
- store: new RedisIdempotencyStore({ client: redis, prefix: 'idem:', ttlMs: 86400000 })
200
-
201
- // DB-backed via RepositoryLike (mongokit / prismakit / custom)
202
- import { Repository, methodRegistryPlugin, batchOperationsPlugin, mongoOperationsPlugin } from '@classytic/mongokit';
203
- repository: new Repository(IdempotencyModel, [
204
- methodRegistryPlugin(), batchOperationsPlugin(), mongoOperationsPlugin(),
205
- ])
206
- ```
207
-
208
- **IdempotencyStore interface:**
209
-
210
- ```typescript
211
- interface IdempotencyStore {
212
- readonly name: string;
213
- get(key: string): Promise<IdempotencyResult | undefined>;
214
- set(key: string, result): Promise<void>;
215
- tryLock(key: string, requestId: string, ttlMs: number): Promise<boolean>;
216
- unlock(key: string, requestId: string): Promise<void>;
217
- isLocked(key: string): Promise<boolean>;
218
- delete(key: string): Promise<void>;
219
- close?(): Promise<void>;
220
- }
221
- ```
222
-
223
- ## OpenTelemetry Tracing
224
-
225
- ```typescript
226
- import { tracingPlugin } from '@classytic/arc/plugins/tracing';
227
-
228
- await fastify.register(tracingPlugin, {
229
- serviceName: 'my-api',
230
- exporterUrl: 'http://localhost:4318/v1/traces',
231
- sampleRate: 0.1, // Trace 10% of requests
232
- });
233
-
234
- // Custom spans
235
- import { createSpan } from '@classytic/arc/plugins/tracing';
236
-
237
- return createSpan(req, 'processPayment', async (span) => {
238
- span.setAttribute('orderId', order._id);
239
- return await processPayment(order);
240
- });
241
- ```
242
-
243
- ## QueryCache (Server Cache)
244
-
245
- TanStack Query-inspired server cache with stale-while-revalidate and auto-invalidation on mutations.
246
-
247
- ```typescript
248
- // Enable globally
249
- const app = await createApp({
250
- arcPlugins: { queryCache: true }, // Memory store, zero config
251
- });
252
-
253
- // Per-resource config
254
- defineResource({
255
- name: 'product',
256
- cache: {
257
- staleTime: 30, // seconds fresh (no revalidation)
258
- gcTime: 300, // seconds stale data kept (SWR window)
259
- tags: ['catalog'], // cross-resource grouping
260
- invalidateOn: { 'category.*': ['catalog'] }, // event → tag invalidation
261
- },
262
- });
263
- ```
264
-
265
- **How it works:**
266
- - `GET` → cached with `x-cache: HIT | STALE | MISS` header
267
- - `POST/PATCH/DELETE` → auto-bumps resource version, invalidating cached queries
268
- - Cross-resource: category mutation bumps `catalog` tag → products cache invalidated
269
- - Multi-tenant safe: cache keys scoped by userId + orgId
270
-
271
- **Runtime modes:**
272
-
273
- | Mode | Store | Config |
274
- |------|-------|--------|
275
- | `memory` (default) | `MemoryCacheStore` (50 MiB budget) | Zero config |
276
- | `distributed` | `RedisCacheStore` | `stores: { queryCache: new RedisCacheStore({ client: redis }) }` |
277
-
278
- ## Response Cache Plugin
279
-
280
- ```typescript
281
- import { responseCachePlugin } from '@classytic/arc/plugins/response-cache';
282
-
283
- await fastify.register(responseCachePlugin, {
284
- // ETag generation + Cache-Control headers per route
285
- });
286
- ```
287
-
288
- **Note:** When QueryCache is active for a resource, response-cache is automatically skipped for that resource's GET routes.
289
-
290
- ## SSE Plugin (Server-Sent Events)
291
-
292
- Bridges Arc domain events to SSE streams. Requires `eventPlugin` (auto-registered by factory).
293
-
294
- ```typescript
295
- // Via factory (recommended)
296
- const app = await createApp({
297
- arcPlugins: {
298
- sse: {
299
- path: '/events/stream', // SSE endpoint (default: '/events/stream')
300
- requireAuth: true, // Fail-closed auth (default: true)
301
- patterns: ['order.*', 'product.*'], // Event patterns to stream (default: ['*'])
302
- // orgScoped defaults to TRUE (2.41.1) — a caller only sees its own org's events.
303
- heartbeat: 30000, // Heartbeat interval in ms (default: 30000)
304
- },
305
- },
306
- });
307
-
308
- // Manual registration
309
- import { ssePlugin } from '@classytic/arc/plugins';
310
- await fastify.register(ssePlugin, { requireAuth: true });
311
- ```
312
-
313
- ### Realtime resource change feed (2.22)
314
-
315
- `arcPlugins: { realtime: true }` → `GET /realtime/:resource` (resource NAME) and
316
- multiplexed `GET /realtime?resources=a,b,c` (cap 20): SSE change feed gated by the
317
- resource's own `list` permission with per-event row filtering, tenant guard, and
318
- field masking. Client = plain `EventSource` with `?token=`. No replay — reconnect
319
- refetches the list. Choosing: per-user resource views → realtime; bidirectional/geo
320
- → `integrations/websocket` (its CRUD bridge is org-coarse — never expose
321
- row-permissioned resources through it); event firehose → sse. Massive fan-out
322
- (viral feeds, live scores) → publish once to a dedicated edge fan-out layer
323
- via `app.events.subscribe(...)`; full tiering guide: docs/production-ops/realtime.mdx.
324
-
325
- **Fail-closed auth:** When `requireAuth: true` (default), throws at registration if `fastify.authenticate` is missing — prevents exposing SSE without auth.
326
-
327
- **Org-scoped by default (2.41.1):** an event carrying `organizationId` reaches only callers in that org. It defaulted to `false` — with `patterns: ['*']`, one tenant's member received every tenant's events, full documents included. Events with no `organizationId` still reach everyone, so single-tenant apps are unaffected; an elevated admin with no active org sees all tenants (the platform view). `orgScoped: false` is for a deliberately cross-tenant stream only — keep `requireAuth` and add a `filter`.
328
-
329
- ## Error Handler Plugin
330
-
331
- ```typescript
332
- import { errorHandlerPlugin } from '@classytic/arc/plugins';
333
-
334
- // Global error handling — catches all errors, logs, formats response
335
- // Auto-registered by createApp()
336
- ```
337
-
338
- ### Error Mappers (v2.7.3)
339
-
340
- Class-based domain error → HTTP response mapping. Register once, handlers just throw:
341
-
342
- ```typescript
343
- class AccountingError extends Error {
344
- constructor(message: string, public status: number, public code: string) { super(message); }
345
- }
346
-
347
- const app = await createApp({
348
- errorHandler: {
349
- errorMappers: [{
350
- type: AccountingError,
351
- toResponse: (err) => ({ status: err.status, code: err.code, message: err.message }),
352
- }],
353
- },
354
- });
355
- // Now handlers just throw — Arc catches and maps automatically
356
- ```
357
-
358
- Mappers are checked via `instanceof` before all other error classification. Multiple mappers supported — first match wins.
359
-
360
- ## Reply Helpers
361
-
362
- Opt-in `sendList` + `stream` decorators: `createApp({ replyHelpers: true })`. Arc emits raw data on success — no `{ success, data }` envelope; HTTP status discriminates — so single-doc handlers just `return doc` (or `reply.send(doc)`) and errors throw `ArcError` (the global handler serialises to `ErrorContract`). The two decorators below cover the cases that DO need framework support:
363
-
364
- ```typescript
365
- // List response — any kit-shaped paginated result OR a bare array → canonical wire shape
366
- return reply.sendList({ method: 'offset', data, total, page, limit, pages, hasNext, hasPrev });
367
- return reply.sendList(rows); // bare array endpoints
368
- ```
369
-
370
- ### Streaming Responses
371
-
372
- ```typescript
373
- // CSV export
374
- return reply.stream(csvReadableStream, { contentType: 'text/csv', filename: 'export.csv' });
375
- // PDF download
376
- return reply.stream(pdfBuffer, { contentType: 'application/pdf', filename: 'report.pdf' });
377
- // Raw stream (Fastify native — works without reply helpers too)
378
- return reply.header('content-type', 'text/csv').send(readableStream);
379
- ```
380
-
381
- ### BigInt Serialization
382
-
383
- Opt-in: `createApp({ serializeBigInt: 'string' })` — BigInt → decimal string in JSON responses (lossless); `'number'` is lossy above 2^53-1.
384
-
385
- ## Multipart Body Middleware (v2.7.3)
386
-
387
- Opt-in file upload support for CRUD routes — parses multipart form fields into `req.body`, attaches files to `req.body._files`:
388
-
389
- ```typescript
390
- import { multipartBody } from '@classytic/arc/middleware';
391
-
392
- defineResource({
393
- middlewares: { create: [multipartBody({ allowedMimeTypes: ['image/png'], maxFileSize: 5_000_000 })] },
394
- hooks: {
395
- 'before:create': async (data) => {
396
- if (data._files?.image) { data.imageUrl = await uploadToS3(data._files.image); delete data._files; }
397
- return data;
398
- },
399
- },
400
- });
401
- ```
402
-
403
- No-op for JSON requests — safe to always add. Options: `maxFileSize`, `maxFiles`, `allowedMimeTypes`, `filesKey`.
404
-
405
- ## Migrations
406
-
407
- ```typescript
408
- import { defineMigration, MigrationRunner } from '@classytic/arc/migrations';
409
-
410
- const v2 = defineMigration({
411
- version: 2,
412
- resource: 'product',
413
- up: async (db) => {
414
- await db.collection('products').updateMany({}, { $rename: { oldField: 'newField' } });
415
- },
416
- down: async (db) => {
417
- await db.collection('products').updateMany({}, { $rename: { newField: 'oldField' } });
418
- },
419
- });
420
-
421
- const runner = new MigrationRunner(mongoose.connection.db);
422
- await runner.up([v2]);
423
- ```
424
-
425
- ## OpenAPI & External Paths
426
-
427
- Arc auto-generates OpenAPI 3.0 specs from resource definitions. External integrations (auth adapters, custom routes) inject their paths via `ExternalOpenApiPaths`.
428
-
429
- ```typescript
430
- import type { ExternalOpenApiPaths } from '@classytic/arc/docs';
431
-
432
- const externalPaths: ExternalOpenApiPaths = {
433
- paths: { '/api/auth/sign-in': { post: { summary: 'Sign in', ... } } },
434
- schemas: { User: { type: 'object', properties: { ... } } },
435
- securitySchemes: {
436
- cookieAuth: { type: 'apiKey', in: 'cookie', name: 'session_token' },
437
- },
438
- tags: [{ name: 'Authentication' }],
439
- // Declare additional security alternatives for Arc resource paths
440
- resourceSecurity: [{ apiKeyAuth: [], orgHeader: [] }],
441
- };
442
- ```
443
-
444
- **`resourceSecurity`** — declarative registration of auth alternatives for resource paths:
445
- - Each array item is **OR**'d with `bearerAuth` (the default)
446
- - Keys within the same object are **AND**'d (all required together)
447
- - Example: `[{ apiKeyAuth: [], orgHeader: [] }]` → "bearer OR (api-key AND org-header)"
448
-
449
- Arc's Better Auth adapter (`extractBetterAuthOpenApi`) auto-populates `resourceSecurity` when the `apiKey()` plugin is detected — no manual configuration needed.
450
-
451
- **Security scheme definitions:**
452
-
453
- | Scheme | Type | Source | Always present? |
454
- |--------|------|--------|-----------------|
455
- | `bearerAuth` | HTTP Bearer | Arc core | Yes |
456
- | `orgHeader` | API Key (`x-organization-id`) | Arc core | Yes (multi-tenant) |
457
- | `cookieAuth` | API Key (cookie) | Better Auth adapter | When Better Auth active |
458
- | `apiKeyAuth` | API Key (`x-api-key`) | Better Auth adapter | When `apiKey()` plugin active |
459
-
460
- ## Deployment
461
-
462
- Arc requires Node.js APIs (`node:crypto`, `AsyncLocalStorage`). Use `toFetchHandler()` for serverless/edge.
463
-
464
- | Environment | Preset | Handler | Notes |
465
- |-------------|--------|---------|-------|
466
- | Docker/K8s | `production` | `app.listen()` | Full production |
467
- | Google Cloud Run | `production` | `app.listen()` | Set min-instances > 0 for WebSocket |
468
- | Railway/Render/Fly.io | `production` | `app.listen()` | Works with zero config |
469
- | AWS Lambda | `edge` | `toFetchHandler()` | Node.js runtime |
470
- | Vercel Serverless | `edge` | `toFetchHandler()` | Node.js runtime |
471
- | Cloudflare Workers | `edge` | `toFetchHandler()` | Enable `nodejs_compat` in wrangler.toml |
472
-
473
- **Edge handler:**
474
- ```typescript
475
- import { createApp, toFetchHandler } from '@classytic/arc/factory';
476
- const app = await createApp({ preset: 'edge', auth: { type: 'jwt', jwt: { secret } } });
477
- export default { fetch: toFetchHandler(app) }; // Cloudflare Workers / any fetch-based runtime
478
- ```
479
-
480
- **Production checklist:**
481
-
482
- ```typescript
483
- // Validate env vars at startup
484
- if (!process.env.JWT_SECRET || process.env.JWT_SECRET.length < 32) throw new Error('...');
485
-
486
- const app = await createApp({
487
- preset: 'production',
488
- auth: { type: 'jwt', jwt: { secret: process.env.JWT_SECRET } },
489
- cors: { origin: process.env.ALLOWED_ORIGINS?.split(',') ?? [], credentials: true },
490
- rateLimit: { max: 100, timeWindow: '1 minute' },
491
- arcPlugins: {
492
- queryCache: true,
493
- // Behind a load balancer: fail readiness first, keep serving while it
494
- // deregisters, then close. No manual process.on('SIGTERM') — the plugin
495
- // owns the signals, and a second handler skips the drain.
496
- gracefulShutdown: { drainDelayMs: 10_000 },
497
- },
498
- });
499
- ```
500
-
501
- ## Distributed Runtime
502
-
503
- `runtime: 'distributed'` is the "more than one replica" switch. It refuses to boot when something in the app holds state that only exists in **this** process. Two checks, one policy:
504
-
505
- **1. Constructor-time guard** — what `createApp` can see in its own options, checked before any boot cost:
506
-
507
- - `stores.events` — always required
508
- - `stores.cache` — only when `arcPlugins.caching` enabled
509
- - `stores.queryCache` — only when `arcPlugins.queryCache` enabled
510
- - `stores.idempotency` — warn only (per-resource opt-in)
511
- - `rateLimit` — needs a shared store: `{ redis: client }` or `{ store: CustomStore }`. Both forms count; `rateLimit: false` opts out.
512
- - `arcPlugins.schedules` — needs `lock` (a `LockAdapter`, for a fleet where any replica may arm schedules) **or** `singleReplica: true` (exactly one replica arms them — the `role: 'scheduler'` deployment pinned at 1). Without one, boot fails: otherwise every replica fires every tick, and duplicate side effects are two invoices, not a stale cache. `singleReplica` is a claim about your deployment — scale that deployment past one replica and it becomes false.
513
-
514
- **2. Capability audit** (end of boot) — everything wired inside `plugins()`, `bootstrap[]`, or a module phase, which the guard above cannot inspect. Subsystems declare via `declareRuntimeCapability`; an undeclared-shared memory default **fails the boot in one error naming every violator**, so you fix them in one pass rather than one restart each.
515
-
516
- What declares itself, and what fixes it:
517
-
518
- | Subsystem | Default | Shared option |
519
- |---|---|---|
520
- | `auth.sessions` | `MemorySessionStore` | `RedisSessionStore` (`@classytic/arc/auth/redis`) |
521
- | `usage.store` | `MemoryUsageStore` | `RedisUsageStore` (`@classytic/arc/usage`) or `@classytic/mongokit/usage` |
522
- | `audit.store` | `MemoryAuditStore` | `repository: yourRepo` (any kit) |
523
- | `cache.query` | `MemoryCacheStore` | `RedisCacheStore` (`@classytic/arc/cache`) |
524
- | `permissions.dynamic-cache` | internal memory | `cacheStore:` — **and pass `fastify:`**, the matrix has no handle of its own so it is invisible to the audit without it |
525
- | `websocket.adapter` | `LocalWebSocketAdapter` | Redis adapter (`@classytic/arc/integrations/websocket-redis`) |
526
- | `websocket.pushref-store` | memory | Redis pushRef store |
527
- | `webhooks.store` | memory | shared store, or durable mode |
528
- | `http.response-cache` | memory | **nothing — declared `accepted`.** Per-replica by design; correctness comes from short TTLs. Logged, never a failure. |
529
-
530
- ### Circuit breakers count per replica unless you say otherwise
531
-
532
- `CircuitBreaker` state is in-process. With 50 pods and `failureThreshold: 5`, a dead downstream absorbs **250 real requests** before anything opens — each pod rediscovers the same outage independently. Share the failure window:
533
-
534
- ```typescript
535
- import { CircuitBreaker, RedisCircuitBreakerState } from '@classytic/arc/utils';
536
-
537
- const shared = new RedisCircuitBreakerState({ redis }); // fixed window, default 60s
538
-
539
- const payments = new CircuitBreaker(charge, {
540
- name: 'stripe.charges', // REQUIRED with sharedState — the key every replica counts under
541
- failureThreshold: 5,
542
- sharedState: shared,
543
- });
544
- ```
545
-
546
- First replica trips at the threshold; every other trips on its **next** failure. It shares the failure *signal*, not the state machine — each replica still owns its own OPEN/HALF_OPEN probing, which avoids needing consensus over who probes. Nothing touches the network on the success path, the failure path never *waits* on the store, and a store that throws degrades to local counting rather than disabling the breaker.
547
-
548
- Hosts declare their own too — a replica-local cache you built in `plugins()` belongs in the audit:
549
-
550
- ```typescript
551
- import { declareRuntimeCapability } from '@classytic/arc/utils';
552
-
553
- declareRuntimeCapability(fastify, {
554
- subsystem: 'billing.sequence-cache',
555
- durability: 'memory', // 'memory' | 'shared'
556
- detail: 'invoice numbering cached per process',
557
- // accepted: true, // only when per-process is INTENDED
558
- });
559
- ```
560
-
561
- Declare from anywhere a registration reaches — `plugins()`, a module phase, or inside your own encapsulated `fastify.register()`; all land in the one audit. `accepted: true` is for state that is per-process **by design**; it must be stated by the declarant, never inferred.
562
-
563
- **Migration note:** a distributed app that booted fine before 2.41 can now fail on a default it was silently running replica-local (usage counters and audit trails were the common ones). The boot error names each. That is the bug surfacing, not a new one.
564
-
565
- ## Under-Pressure
566
-
567
- Production preset: `maxEventLoopDelay: 3000` (avoids false 503s on Render/Railway/Fly.io). Override: `underPressure: { maxEventLoopDelay: 500 }`. Disable: `underPressure: false`.
568
-
569
- ## CORS
570
-
571
- Production warns (not throws) when origin missing. `origin: '*'` from env is allowed. Smart CORS auto-converts `credentials: true` + `origin: '*'` to `origin: true`, and (2.22) auto-merges arc's protocol headers (`x-organization-id`, `x-arc-scope`, `x-request-id`) into any host-declared `allowedHeaders` allow-list — hosts never enumerate framework internals.
572
-
573
- ### Mobile apps (Capacitor / Ionic / React Native webviews)
574
-
575
- Arc needs no special mode — mobile is a CORS + auth-transport recipe:
576
-
577
- ```typescript
578
- cors: {
579
- // Webview origins alongside your web domains. Also add these to
580
- // Better Auth's trustedOrigins when using BA.
581
- origin: [...webOrigins, 'https://localhost', 'capacitor://localhost'],
582
- credentials: true,
583
- // Optional allow-list — arc's own headers auto-merge (2.22); you only
584
- // list YOUR custom ones. Omit entirely to use reflection mode.
585
- allowedHeaders: ['Content-Type', 'Authorization'],
586
- // BA bearer plugin returns the fresh session token in this RESPONSE
587
- // header — without exposing it, cross-origin JS cannot READ it and
588
- // app login dies silently. The one mobile knob arc can't infer.
589
- exposedHeaders: ['set-auth-token'],
590
- },
591
- trustProxy: true, // webviews arrive through your LB/tunnel
592
- ```
593
-
594
- Native (non-webview) HTTP clients send no `Origin` header — CORS doesn't apply to them at all; bearer auth just works.
595
-
596
- ## Metrics Plugin
597
-
598
- Prometheus-compatible metrics endpoint — zero external dependencies:
599
-
600
- ```typescript
601
- import { metricsPlugin } from '@classytic/arc/plugins';
602
-
603
- await fastify.register(metricsPlugin, {
604
- path: '/_metrics', // default
605
- prefix: 'arc', // metric name prefix (default: 'arc')
606
- onCollect: (metrics) => pushToOTLP(metrics), // optional OTLP push
607
- });
608
-
609
- // GET /_metrics → Prometheus text format
610
- ```
611
-
612
- **Built-in counters**: `arc_http_requests_total`, `arc_http_request_duration_seconds`, `arc_crud_operations_total`, `arc_cache_hits_total`, `arc_cache_misses_total`, `arc_events_published_total`, `arc_events_consumed_total`, `arc_circuit_breaker_state`.
613
-
614
- **Programmatic access**: `fastify.metrics.recordOperation(resource, op, status, durationMs)`, `.recordCacheHit(resource)`, `.recordEventPublish(type)`, `.reset()`.
615
-
616
- ## API Versioning Plugin
617
-
618
- Header-based or URL prefix-based versioning with deprecation warnings:
619
-
620
- ```typescript
621
- import { versioningPlugin } from '@classytic/arc/plugins';
622
-
623
- // Header-based: clients send Accept-Version: 2
624
- await fastify.register(versioningPlugin, {
625
- type: 'header',
626
- deprecated: ['1'],
627
- sunset: '2025-12-01',
628
- });
629
-
630
- // Prefix-based: /v2/products
631
- await fastify.register(versioningPlugin, { type: 'prefix' });
632
- ```
633
-
634
- **Headers set**: `x-api-version` on every response. `Deprecation: true` + `Sunset` for deprecated versions. Access via `request.apiVersion`.
635
-
636
- ## Per-Tenant Rate Limiting
637
-
638
- Scope-aware rate limit key generator — isolates rate limits by org, user, or IP:
639
-
640
- ```typescript
641
- import { createTenantKeyGenerator } from '@classytic/arc/scope';
642
-
643
- const app = await createApp({
644
- rateLimit: {
645
- max: 100,
646
- timeWindow: '1 minute',
647
- keyGenerator: createTenantKeyGenerator(),
648
- },
649
- });
650
- ```
651
-
652
- **Key resolution**: `member` → `organizationId`, `authenticated` → `userId`, `elevated` → `organizationId ?? userId`, `public` → IP. Custom strategy: `createTenantKeyGenerator({ strategy: (ctx) => ctx.ip })`.
653
-
654
- ## Event Outbox
655
-
656
- Transactional outbox pattern — at-least-once delivery even if transport is down:
657
-
658
- ```typescript
659
- import { EventOutbox, MemoryOutboxStore } from '@classytic/arc/events';
660
- import { Repository } from '@classytic/mongokit';
661
-
662
- // Dev
663
- const outbox = new EventOutbox({ store: new MemoryOutboxStore(), transport: redisTransport });
664
-
665
- // Production — any RepositoryLike
666
- const outbox = new EventOutbox({
667
- repository: new Repository(OutboxModel),
668
- transport: redisTransport,
669
- });
670
-
671
- // In business logic (same DB transaction via `{ session }`)
672
- await outbox.store(event, { session });
673
-
674
- // Relay cron (runs every few seconds)
675
- const relayed = await outbox.relay(); // publishes pending → transport
676
- ```
677
-
678
- **Prefer the module form** — it owns the relay schedule, shutdown, and a readiness check, so none of that is hand-wired:
679
-
680
- ```typescript
681
- import { createOutboxModule, exponentialBackoff, repositoryAsOutboxStore } from '@classytic/arc/events';
682
-
683
- const outbox = createOutboxModule({
684
- store: repositoryAsOutboxStore(new Repository(OutboxModel)),
685
- // Bounds retries AND log volume. `attempts` is the DURABLE count (it survives relay
686
- // restarts and is shared across relays), so a poison event really does stop at 5.
687
- failurePolicy: ({ attempts }) =>
688
- attempts >= 5 ? { deadLetter: true } : { retryAt: exponentialBackoff({ attempt: attempts }) },
689
- health: { relayLagUnhealthyMs: 5 * 60_000, probeCacheMs: 5_000 },
690
- });
691
- // createApp({ modules: [outbox] }); consumers declare dependsOn: ['outbox'].
692
- ```
693
-
694
- - `requestDrain()` — nudge a pass after commit (milliseconds, not `relayEveryMs`); runs outside the caller's request scope.
695
- - `drain()` — await delivery, cascades included. For tests and a shutdown that should empty the queue.
696
- - `health()` + readiness check `<name>.relay` — **non-critical** (a stalled relay is a cluster problem; pulling one pod would not drain it). Unhealthy on any dead letter or pending lag past the threshold. The probe reuses a reading for `probeCacheMs` so N replicas × probe rate do not become N count queries a second on the outbox table.
697
-
698
- **OutboxStore contract** (`@classytic/primitives/outbox`): required `save`, `getPending`, `acknowledge`; optional `claimPending` / `claimPendingFenced` (lease + fencing token, and the durable `attempts`), `fail`, `getDeadLettered`, `requeue`, `purge`, `countByStatus`, `oldestPendingAgeMs`. Prove a custom store with `runOutboxStoreContract` from `@classytic/arc/testing/outbox`. When you pass `repository`, arc adapts it internally.
699
-
700
- ## Bulk Operations Preset
701
-
702
- Adds bulk CRUD routes — repository must provide `createMany`, `updateMany`, `deleteMany`:
703
-
704
- ```typescript
705
- import { createMongooseAdapter } from '@classytic/mongokit/adapter';
706
- import { buildCrudSchemasFromModel } from '@classytic/mongokit';
707
-
708
- defineResource({
709
- name: 'product',
710
- adapter: createMongooseAdapter({ model, repository, schemaGenerator: buildCrudSchemasFromModel }),
711
- presets: ['bulk'], // adds POST/PATCH/DELETE /{resource}/bulk
712
- });
713
-
714
- // Or with options
715
- presets: [bulkPreset({ operations: ['createMany', 'updateMany'], maxCreateItems: 500 })]
716
- ```
717
-
718
- **Routes**: `POST /bulk` (body: `{ items }`) → `createMany`, `PATCH /bulk` (body: `{ filter, data }`) → `updateMany`, `DELETE /bulk` (body: `{ filter }`) → `deleteMany`. Permissions inherit from `create`/`update`/`delete`.
719
-
720
- ## Compensating Transaction
721
-
722
- In-process rollback primitive — runs steps in order, compensates in reverse on failure.
723
- For distributed sagas across services, use `@classytic/streamline` or a dedicated workflow orchestrator.
724
-
725
- ```typescript
726
- import { withCompensation } from '@classytic/arc/utils';
727
-
728
- const result = await withCompensation('place-order', [
729
- {
730
- name: 'reserve-inventory',
731
- execute: async (ctx) => {
732
- const res = await inventoryService.reserve(ctx.items);
733
- ctx.reservationId = res.id;
734
- return res;
735
- },
736
- compensate: async (_ctx, result) => {
737
- await inventoryService.release(result.id);
738
- },
739
- },
740
- {
741
- name: 'charge-payment',
742
- execute: async (ctx) => await paymentService.charge(ctx.total),
743
- compensate: async (_ctx, result) => await paymentService.refund(result.chargeId),
744
- },
745
- {
746
- name: 'send-confirmation',
747
- execute: async (ctx) => await emailService.send(ctx.email),
748
- // No compensate — emails can't be unsent
749
- },
750
- ], { items: cart.items, total: cart.total, email: user.email });
751
-
752
- if (!result.success) {
753
- console.error(`Saga failed at ${result.failedStep}: ${result.error}`);
754
- // Compensation already ran for completed steps
755
- }
756
- ```
757
-
758
- **`defineCompensation()`** — reusable definition:
759
-
760
- ```typescript
761
- const placeOrder = defineCompensation('place-order', steps);
762
- await placeOrder.execute({ items, total, email });
763
- ```
764
-
765
- **Fire-and-forget steps** — don't block, don't compensate, errors swallowed:
766
-
767
- ```typescript
768
- await withCompensation('checkout', [
769
- { name: 'save-order', execute: saveOrder, compensate: cancelOrder },
770
- { name: 'send-email', execute: sendEmail, fireAndForget: true }, // non-blocking
771
- { name: 'charge', execute: chargeCard, compensate: refundCard },
772
- ]);
773
- // 'charge' runs immediately after 'save-order' — doesn't wait for email
774
- ```
775
-
776
- **Lifecycle hooks** — wire to Arc events, logging, or metrics:
777
-
778
- ```typescript
779
- await withCompensation('checkout', steps, { orderId }, {
780
- onStepComplete: (stepName, result) => {
781
- fastify.events.publish(`checkout.${stepName}.completed`, result);
782
- },
783
- onStepFailed: (stepName, error) => {
784
- fastify.events.publish(`checkout.${stepName}.failed`, { error: error.message });
785
- },
786
- onCompensate: (stepName) => {
787
- fastify.log.warn(`Compensated: ${stepName}`);
788
- },
789
- });
790
- ```
791
-
792
- **In a custom route with Arc auth:**
793
-
794
- ```typescript
795
- defineResource({
796
- name: 'order',
797
- routes: [{
798
- method: 'POST',
799
- path: '/:id/checkout',
800
- permissions: requireAuth(),
801
- rawHandler: async (request, reply) => {
802
- const result = await withCompensation('checkout', steps, { orderId: request.params.id });
803
- if (!result.success) return reply.code(422).send({ error: result.error });
804
- return reply.send({ data: result.results });
805
- },
806
- }],
807
- });
808
- ```
809
-
810
- **Compensation errors**: collected in `result.compensationErrors[]` without stopping rollback. **Context**: mutable `Record<string, unknown>` shared across all steps.
811
-
812
- **Scope**: In-process primitive. Process crash = no compensation. For durable distributed workflows, use Temporal, Inngest, or `@classytic/streamline`.
813
-
814
- ## Multi-Domain Deployment
815
-
816
- Arc supports multi-domain applications through COMPOSITION — it deliberately owns no domain routing, domain databases, certificate provisioning, or wildcard-domain management. The deployment shape:
817
-
818
- ```
819
- api.example.com → arc API
820
- auth.example.com → Better Auth (or auth module)
821
- events.example.com → SSE/WebSocket edge tier
822
- admin.example.com → frontend
823
- customer-domain.com → gateway/domain resolver → tenant context
824
- ```
825
-
826
- The primitives are already there: CORS allowlists, Better Auth trusted origins, tenant scope, request context, `trustProxy` configuration, resource/module prefixes.
827
-
828
- **Custom tenant domains**: resolve the domain at a gateway or an early host plugin, then convert it into a trusted `RequestScope` — a small host-provided resolver is enough:
829
-
830
- ```typescript
831
- // onRequest, before auth: map host → tenant hint
832
- const tenant = await resolveTenantDomain(request.hostname); // → { organizationId } | null
833
- ```
834
-
835
- Then validate membership or service scope through the NORMAL permission path. **Never treat raw `Host` / `X-Forwarded-Host` as tenant authorization by itself** — behind a misconfigured proxy those are attacker-controlled (see the `trustProxy` boot warning). The header selects the tenant *candidate*; membership resolution authorizes it — same rule `resolveOrgFromHeader` follows for `x-organization-id`.