@classytic/arc 2.45.2 → 2.46.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.
- package/README.md +1 -1
- package/dist/{EventTransport-CiicKz2Z.d.mts → EventTransport-CYEoCJGe.d.mts} +0 -2
- package/dist/{EventTransport-DHb1tpu-.mjs → EventTransport-DNgD9NP4.mjs} +3 -4
- package/dist/{HookSystem-C1u0EUnt.mjs → HookSystem-DRbPzEcP.mjs} +3 -4
- package/dist/{QueryCache--5uAuYPW.d.mts → QueryCache-DdvrGG8Q.d.mts} +1 -3
- package/dist/{ResourceRegistry-D2jXWVN_.mjs → ResourceRegistry-Douk51fa.mjs} +15 -4
- package/dist/{acquire-DTkA8Lme.mjs → acquire-RbtvDg9s.mjs} +2 -3
- package/dist/{actionPermissions-DRVk6m7x.mjs → actionPermissions-De0AJ7hm.mjs} +37 -42
- package/dist/audit/index.d.mts +2 -10
- package/dist/audit/index.mjs +8 -12
- package/dist/auth/audit.d.mts +0 -2
- package/dist/auth/audit.mjs +2 -3
- package/dist/auth/index.d.mts +9 -17
- package/dist/auth/index.mjs +26 -29
- package/dist/auth/redis-session.d.mts +2 -4
- package/dist/auth/redis-session.mjs +2 -3
- package/dist/{authorizationDecision-D48fUJv1.mjs → authorizationDecision-DeZMrHcm.mjs} +5 -6
- package/dist/{base-CZyixEQR.d.mts → base-HXNgPQww.d.mts} +1 -7
- package/dist/{boundedMap-DkKiPifd.mjs → boundedMap-2WBh3gM9.mjs} +2 -3
- package/dist/{buildHandler-BiZ4VATS.mjs → buildHandler-DxVOOBpw.mjs} +5 -6
- package/dist/cache/index.d.mts +4 -10
- package/dist/cache/index.mjs +5 -6
- package/dist/{caching-Cj0as-P1.mjs → caching-BYRwYrUo.mjs} +3 -4
- package/dist/{claimed-ChI13rUR.mjs → claimed-DYlELdnm.mjs} +2 -3
- package/dist/cleanup/index.d.mts +4 -18
- package/dist/cleanup/index.mjs +12 -20
- package/dist/cli/commands/describe.d.mts +1 -3
- package/dist/cli/commands/describe.mjs +4 -5
- package/dist/cli/commands/docs.d.mts +1 -3
- package/dist/cli/commands/docs.mjs +4 -5
- package/dist/cli/commands/doctor.d.mts +1 -3
- package/dist/cli/commands/doctor.mjs +2 -3
- package/dist/cli/commands/generate.d.mts +1 -1
- package/dist/cli/commands/generate.mjs +2 -2
- package/dist/cli/commands/init.d.mts +1 -1
- package/dist/cli/commands/init.mjs +2 -2
- package/dist/cli/commands/introspect.d.mts +1 -3
- package/dist/cli/commands/introspect.mjs +3 -4
- package/dist/cli/index.d.mts +2 -2
- package/dist/cli/index.mjs +3 -3
- package/dist/{constants-D_aiew34.mjs → constants-CHZMUwBW.mjs} +2 -3
- package/dist/context/index.d.mts +0 -8
- package/dist/context/index.mjs +6 -7
- package/dist/core/index.d.mts +3 -3
- package/dist/core/index.mjs +8 -8
- package/dist/{core-QIZ2560Y.mjs → core-D9rS2BxO.mjs} +9 -12
- package/dist/{createActionRouter-CvH84dyx.mjs → createActionRouter-0qkCRzTL.mjs} +7 -8
- package/dist/{createAggregationRouter-DGyK2Hp6.mjs → createAggregationRouter-CUf5Esd9.mjs} +9 -10
- package/dist/{createApp-CKjZpmq9.mjs → createApp-DZIXfDKD.mjs} +49 -62
- package/dist/{createMcpServer-DSztofa9.d.mts → createMcpServer-DeVpqQF-.d.mts} +1 -3
- package/dist/{defineAggregation-BLza7Ca4.mjs → defineAggregation-bmKQ4NmC.mjs} +2 -3
- package/dist/{defineResource-CEo0gDCb.mjs → defineResource-CGmdmGwh.mjs} +78 -29
- package/dist/discovery/index.d.mts +1 -3
- package/dist/discovery/index.mjs +2 -3
- package/dist/docs/index.d.mts +8 -8
- package/dist/docs/index.mjs +4 -5
- package/dist/{elevation-BJTsSnke.mjs → elevation-CzhqAyVN.mjs} +9 -10
- package/dist/{elevation-BW2J3tNj.d.mts → elevation-DPD0hcU-.d.mts} +0 -2
- package/dist/encryption/index.d.mts +1 -7
- package/dist/encryption/index.mjs +8 -13
- package/dist/{errorHandler--4rSMMvq.d.mts → errorHandler-B9r88jZV.d.mts} +8 -3
- package/dist/{errorHandler-2p4SL5zm.mjs → errorHandler-dFyGOEoB.mjs} +16 -6
- package/dist/{errors-grZkIA8N.mjs → errors-BY8vzlP4.mjs} +2 -3
- package/dist/{errors-JYc9vwqE.d.mts → errors-DTo0me1o.d.mts} +0 -2
- package/dist/{eventPlugin-BtmA4-3P.d.mts → eventPlugin-BY38F6yK.d.mts} +1 -7
- package/dist/{eventPlugin-ItcYBGUs.mjs → eventPlugin-eMhAPtQA.mjs} +10 -12
- package/dist/{eventTypes-Ck6fD3ne.mjs → eventTypes-Do2KYeJx.mjs} +5 -8
- package/dist/events/index.d.mts +4 -16
- package/dist/events/index.mjs +8 -9
- package/dist/events/transports/redis-stream-entry.d.mts +1 -1
- package/dist/events/transports/redis-stream-entry.mjs +5 -6
- package/dist/events/transports/redis.d.mts +2 -4
- package/dist/events/transports/redis.mjs +3 -4
- package/dist/{externalPaths-CmGOxOtD.d.mts → externalPaths-BOqdq5wr.d.mts} +0 -2
- package/dist/factory/index.d.mts +4 -14
- package/dist/factory/index.mjs +12 -18
- package/dist/{fastify-augmentation-DRlCIWE9.d.mts → fastify-augmentation-Dtn0IIRn.d.mts} +4 -10
- package/dist/{fields-BBSpf8pS.d.mts → fields-JTkrtO-r.d.mts} +0 -2
- package/dist/{fields-BRX0Krcj.mjs → fields-LnbCcvsw.mjs} +2 -3
- package/dist/{filter-merge-CDc7YMwX.mjs → filter-merge-BAWi019Q.mjs} +2 -3
- package/dist/{generate-DCGuEbqI.d.mts → generate-C-g_KOkV.d.mts} +0 -4
- package/dist/{generate-hvg7V2g1.mjs → generate-oXoDnpJf.mjs} +7 -12
- package/dist/{headers-Cqkg4LzI.mjs → headers-DBd3Qheo.mjs} +3 -4
- package/dist/{health-PVt0VjOx.mjs → health-BlJu9GXS.mjs} +2 -3
- package/dist/{health-DyeP3mTW.mjs → health-Dp-3EC9o.mjs} +4 -7
- package/dist/hooks/index.d.mts +1 -1
- package/dist/hooks/index.mjs +2 -2
- package/dist/idempotency/index.d.mts +3 -9
- package/dist/idempotency/index.mjs +10 -13
- package/dist/idempotency/redis.d.mts +1 -1
- package/dist/idempotency/redis.mjs +3 -4
- package/dist/{index-Bxriq3so.d.mts → index-B5i9-vuP.d.mts} +4 -26
- package/dist/{index-Chgz3d0i.d.mts → index-BAXDo5eE.d.mts} +1 -7
- package/dist/{index-Beg3aNnK.d.mts → index-BTxzJ_MN.d.mts} +67 -25
- package/dist/{index-CUJvoyw3.d.mts → index-Bqfo8hLz.d.mts} +2 -24
- package/dist/{index-uhkUA5-U.d.mts → index-CUdaoCYt.d.mts} +13 -23
- package/dist/{index-WH7xgvxS.d.mts → index-DyJFTJLA.d.mts} +31 -92
- package/dist/index.d.mts +7 -9
- package/dist/index.mjs +12 -13
- package/dist/{init-jC3rMPzb.mjs → init-BOaNkLYb.mjs} +18 -35
- package/dist/{init-Cscs4lab.d.mts → init-CV2_Fw3H.d.mts} +0 -4
- package/dist/integrations/event-gateway.d.mts +3 -5
- package/dist/integrations/event-gateway.mjs +3 -4
- package/dist/integrations/index.d.mts +3 -3
- package/dist/integrations/index.mjs +1 -1
- package/dist/integrations/jobs/index.d.mts +1 -1
- package/dist/integrations/jobs/index.mjs +7 -11
- package/dist/integrations/mcp/index.d.mts +7 -39
- package/dist/integrations/mcp/index.mjs +8 -14
- package/dist/integrations/mcp/testing.d.mts +3 -5
- package/dist/integrations/mcp/testing.mjs +3 -4
- package/dist/integrations/streamline.d.mts +1 -3
- package/dist/integrations/streamline.mjs +4 -5
- package/dist/integrations/webhooks.d.mts +2 -4
- package/dist/integrations/webhooks.mjs +4 -5
- package/dist/integrations/websocket-pushref-redis.d.mts +2 -4
- package/dist/integrations/websocket-pushref-redis.mjs +2 -3
- package/dist/integrations/websocket-redis.d.mts +2 -4
- package/dist/integrations/websocket-redis.mjs +2 -3
- package/dist/integrations/websocket.d.mts +2 -2
- package/dist/integrations/websocket.mjs +13 -24
- package/dist/{interface-JJzwH4Ro.d.mts → interface-BmExzQRD.d.mts} +0 -2
- package/dist/{interface-BOk3YnTz.d.mts → interface-WR1U0K7t.d.mts} +0 -2
- package/dist/{jsonBody-ptwyzZQ-.mjs → jsonBody-DpRpKR_K.mjs} +3 -4
- package/dist/{keys-C1vFuSbv.mjs → keys-FBz6Ull-.mjs} +2 -3
- package/dist/{loadResources-CHPDyIPn.mjs → loadResources-Bx1sKPnF.mjs} +4 -5
- package/dist/{loadResourcesFromEntry-BkHHTu_B.mjs → loadResourcesFromEntry-b_jcqbxh.mjs} +3 -4
- package/dist/logger/index.d.mts +1 -3
- package/dist/logger/index.mjs +2 -2
- package/dist/{logger-C5bvCiAK.mjs → logger-CbFcIEBZ.mjs} +3 -5
- package/dist/{mcpPlugin-C9qohJCF.mjs → mcpPlugin-yix548XX.mjs} +41 -60
- package/dist/{memory-CxiTwT0j.mjs → memory-Bgw5dn8N.mjs} +4 -5
- package/dist/{metrics-Ckp2zRy-.mjs → metrics-CZDQWVjS.mjs} +4 -5
- package/dist/middleware/index.d.mts +1 -5
- package/dist/middleware/index.mjs +4 -5
- package/dist/migrations/index.d.mts +0 -2
- package/dist/migrations/index.mjs +3 -4
- package/dist/{module-CfnKuIuH.mjs → module-Dsc_nKL5.mjs} +2 -3
- package/dist/{multiTenant-CAtYlW6H.d.mts → multiTenant-XCxAUlru.d.mts} +1 -5
- package/dist/{multipartBody-BFasGtP9.mjs → multipartBody-B85ek8Kj.mjs} +2 -3
- package/dist/observeSend-BK-JN1jK.mjs +20 -0
- package/dist/{openapi-DAPxjYHX.mjs → openapi-Co7hl073.mjs} +18 -28
- package/dist/outbox-admin/index.d.mts +2 -4
- package/dist/outbox-admin/index.mjs +6 -7
- package/dist/{outbox-module-gZCHoE4H.d.mts → outbox-module-XvUThpqn.d.mts} +2 -8
- package/dist/{outbox-module-B4FAkx3A.mjs → outbox-module-mg9kDYkd.mjs} +13 -17
- package/dist/permissions/index.d.mts +4 -4
- package/dist/permissions/index.mjs +7 -7
- package/dist/{permissions-B14c3OMp.mjs → permissions-A1oKtpiC.mjs} +19 -29
- package/dist/{pipe-CQv7PsAK.mjs → pipe-Czpw9U2n.mjs} +3 -4
- package/dist/pipeline/index.d.mts +1 -9
- package/dist/pipeline/index.mjs +5 -8
- package/dist/{plan-CpnTykjb.mjs → plan-KVseuBCL.mjs} +5 -9
- package/dist/{plugin-DXTjVg_Q.mjs → plugin-DTWt_8C3.mjs} +130 -62
- package/dist/plugins/index.d.mts +8 -16
- package/dist/plugins/index.mjs +22 -26
- package/dist/plugins/response-cache.d.mts +2 -4
- package/dist/plugins/response-cache.mjs +10 -10
- package/dist/plugins/tracing-entry.d.mts +1 -1
- package/dist/plugins/tracing-entry.mjs +3 -4
- package/dist/{pluralize-C3VJKRGp.mjs → pluralize-msB9X3yw.mjs} +2 -3
- package/dist/presets/filesUpload.d.mts +4 -6
- package/dist/presets/filesUpload.mjs +6 -7
- package/dist/presets/index.d.mts +3 -19
- package/dist/presets/index.mjs +2 -2
- package/dist/presets/multiTenant.d.mts +1 -1
- package/dist/presets/multiTenant.mjs +7 -7
- package/dist/presets/search.d.mts +3 -5
- package/dist/presets/search.mjs +3 -4
- package/dist/{presets-CquqYJPy.mjs → presets-qKCehiJM.mjs} +11 -18
- package/dist/{projection-CgfSLOSM.mjs → projection-ClBqtsIw.mjs} +3 -4
- package/dist/{pushref-registry-UxCkoA4C.d.mts → pushref-registry-d86QUaSq.d.mts} +0 -6
- package/dist/{queryCachePlugin-D0HUISHJ.mjs → queryCachePlugin-3gJj5Rbz.mjs} +8 -10
- package/dist/{queryCachePlugin-C2lZjTxk.d.mts → queryCachePlugin-DYQUyeJ9.d.mts} +2 -4
- package/dist/{rateLimitKey-AvkBOMkl.mjs → rateLimitKey-Kro---xl.mjs} +2 -3
- package/dist/{realtime-CbWtVbqK.mjs → realtime-Ber8uJN2.mjs} +17 -19
- package/dist/{redis-BDgv9Glw.d.mts → redis-RpDMemdm.d.mts} +2 -4
- package/dist/{redis-stream-BMk-bpQS.d.mts → redis-stream-CS1N9dwM.d.mts} +1 -3
- package/dist/{redisShapes-CQksY67q.d.mts → redisShapes-CqBXTn_s.d.mts} +0 -2
- package/dist/registry/index.d.mts +2 -12
- package/dist/registry/index.mjs +3 -3
- package/dist/{registry-BVwpAuFI.mjs → registry-BA-_vFYk.mjs} +7 -12
- package/dist/{renewingLease-CykpeNcQ.mjs → renewingLease-CMY8YOcc.mjs} +2 -3
- package/dist/{replyHelpers-DA51IZio.mjs → replyHelpers-DK9P_XSz.mjs} +3 -4
- package/dist/{requestContext-DIWHKDtQ.mjs → requestContext-GYO_0gEw.mjs} +2 -3
- package/dist/{requirement-CbiLdQ1n.d.mts → requirement-CTRQjjQx.d.mts} +0 -2
- package/dist/{requirement-Cp_fsMDL.mjs → requirement-DeNjZIH3.mjs} +2 -3
- package/dist/{resourceRateLimit-Wf6d6FL9.d.mts → resourceRateLimit-DCWglD7V.d.mts} +1 -3
- package/dist/{resourceRateLimit-BFuluodF.mjs → resourceRateLimit-tHLbrtWc.mjs} +3 -4
- package/dist/{rolldown-runtime-D_lMdYOd.mjs → rolldown-runtime-Kv1fZdLg.mjs} +2 -3
- package/dist/{routeValidator-DuLonYwr.mjs → routeValidator-C_H5NanI.mjs} +2 -3
- package/dist/{runtimeCapabilities-CydRfm0i.mjs → runtimeCapabilities-DWqbxkyw.mjs} +2 -3
- package/dist/{schedules-B693KXxa.mjs → schedules-eO_RzhCU.mjs} +132 -9
- package/dist/{schemaConverter-DNvZWTV6.mjs → schemaConverter-DBJrPZN4.mjs} +3 -4
- package/dist/{schemaIR-REV2y7Wd.mjs → schemaIR-CEScKT2v.mjs} +3 -4
- package/dist/schemas/index.d.mts +0 -2
- package/dist/schemas/index.mjs +2 -3
- package/dist/scim/index.d.mts +0 -12
- package/dist/scim/index.mjs +10 -18
- package/dist/scope/index.d.mts +2 -6
- package/dist/scope/index.mjs +5 -5
- package/dist/{scope-Bevxy_ST.mjs → scope-B-Sm9m_E.mjs} +5 -6
- package/dist/{sessionManager-qimlKV0P.d.mts → sessionManager-CdvDF04x.d.mts} +2 -4
- package/dist/{shutdown-CfrqPR7A.mjs → shutdown-DzLFbe27.mjs} +2 -3
- package/dist/{simpleEqualityMatcher-BJwfuRKP.mjs → simpleEqualityMatcher-DOJhwQ8g.mjs} +2 -3
- package/dist/{sse-CuNNWr2z.mjs → sse-2972pVwV.mjs} +8 -9
- package/dist/{sseStream-C_2ujAVY.mjs → sseStream-AWLEeNV-.mjs} +3 -4
- package/dist/{storage-Cx9Sz3Ou.d.mts → storage-odC5MNKN.d.mts} +0 -2
- package/dist/{store-helpers-C8uBGCbb.mjs → store-helpers-VzjgVTkM.mjs} +2 -3
- package/dist/{streaming-Bdq_M4d5.mjs → streaming-DvraWW6x.mjs} +2 -3
- package/dist/{subscriberIdentity-B-KpZkdl.mjs → subscriberIdentity-Bya56jsg.mjs} +2 -3
- package/dist/{tenancy-C5PCvm1h.mjs → tenancy-DSa_0hhw.mjs} +3 -4
- package/dist/{tenantPreparation-dYvWrgNa.mjs → tenantPreparation-BrpkQre3.mjs} +5 -6
- package/dist/testing/cleanupStoreContract.d.mts +2 -4
- package/dist/testing/cleanupStoreContract.mjs +2 -3
- package/dist/testing/index.d.mts +6 -32
- package/dist/testing/index.mjs +24 -37
- package/dist/testing/outboxStoreContract.d.mts +1 -3
- package/dist/testing/outboxStoreContract.mjs +3 -4
- package/dist/testing/requiredPorts.d.mts +2 -4
- package/dist/testing/requiredPorts.mjs +3 -4
- package/dist/testing/storageContract.d.mts +2 -4
- package/dist/testing/storageContract.mjs +2 -3
- package/dist/{timing-DCqsezX8.mjs → timing-6rQTuCwg.mjs} +3 -5
- package/dist/{tracing-Dro5eH6j.d.mts → tracing-JSFiBl5r.d.mts} +0 -2
- package/dist/{transactionContext-DrcNyjpv.mjs → transactionContext-DaxYUEgH.mjs} +2 -3
- package/dist/{typeGuards-CEl10KPy.mjs → typeGuards-UKnX8wPX.mjs} +2 -3
- package/dist/types/index.d.mts +4 -4
- package/dist/types/index.mjs +1 -1
- package/dist/types/storage.d.mts +1 -1
- package/dist/types/storage.mjs +1 -1
- package/dist/{types-ByHn9rEO.d.mts → types-0Dqlbgn8.d.mts} +0 -2
- package/dist/{types-D3Ixsh00.d.mts → types-BYEb_dLW.d.mts} +2 -4
- package/dist/{types-BJ-2XqVF.d.mts → types-BeEJm-DV.d.mts} +114 -14
- package/dist/{types-DVLddu2q.d.mts → types-C0YJAiL0.d.mts} +0 -2
- package/dist/{types-D9NWjpYc.mjs → types-CuGjhn83.mjs} +5 -6
- package/dist/{types-Ddl9OjmE.d.mts → types-DnkIALZ8.d.mts} +0 -4
- package/dist/usage/index.d.mts +2 -10
- package/dist/usage/index.mjs +8 -12
- package/dist/{userHelpers-BHig1kHq.mjs → userHelpers-oX5_mOVs.mjs} +2 -3
- package/dist/utils/index.d.mts +5 -39
- package/dist/utils/index.mjs +12 -12
- package/dist/{utils-BG5P7_Vb.mjs → utils-CjjGOT4E.mjs} +20 -30
- package/dist/{validate-D_mdOCir.mjs → validate-4RlTKOJb.mjs} +5 -7
- package/dist/{versioning-DBGHjPh7.mjs → versioning-Dk2-19La.mjs} +4 -5
- package/dist/{versioning-Bqm_57Qt.d.mts → versioning-S18y2-0C.d.mts} +1 -15
- package/dist/{websocket-Cs4awVyD.d.mts → websocket-BGuc-WVZ.d.mts} +1 -15
- package/dist/{workScope-DPPfM4m6.mjs → workScope-DoBsoVo4.mjs} +3 -4
- package/llms.txt +37 -30
- package/package.json +9 -8
- package/skills/arc/SKILL.md +65 -844
- package/skills/arc/references/agent-auth.md +82 -193
- package/skills/arc/references/api-reference.md +41 -245
- package/skills/arc/references/auth-api-keys.md +99 -0
- package/skills/arc/references/auth-better-auth-overlay.md +87 -0
- package/skills/arc/references/auth-better-auth.md +78 -0
- package/skills/arc/references/auth-permissions.md +100 -0
- package/skills/arc/references/auth-strategies.md +122 -0
- package/skills/arc/references/boot.md +80 -0
- package/skills/arc/references/enterprise-auth.md +65 -81
- package/skills/arc/references/events-outbox.md +90 -0
- package/skills/arc/references/events.md +75 -440
- package/skills/arc/references/integrations-jobs.md +74 -0
- package/skills/arc/references/integrations-realtime.md +84 -0
- package/skills/arc/references/integrations-webhooks.md +71 -0
- package/skills/arc/references/integrations-workflows.md +47 -0
- package/skills/arc/references/mcp-auth.md +83 -0
- package/skills/arc/references/mcp-custom-tools.md +125 -0
- package/skills/arc/references/mcp-setup.md +115 -0
- package/skills/arc/references/mcp-testing.md +63 -0
- package/skills/arc/references/multi-tenancy.md +56 -230
- package/skills/arc/references/permissions-scope.md +81 -0
- package/skills/arc/references/production-api.md +119 -0
- package/skills/arc/references/production-audit.md +101 -0
- package/skills/arc/references/production-boot.md +91 -0
- package/skills/arc/references/production-caching.md +63 -0
- package/skills/arc/references/production-distributed.md +75 -0
- package/skills/arc/references/production-idempotency.md +83 -0
- package/skills/arc/references/production-observability.md +83 -0
- package/skills/arc/references/production-realtime.md +70 -0
- package/skills/arc/references/production-reliability.md +100 -0
- package/skills/arc/references/production-shutdown.md +43 -0
- package/skills/arc/references/querying.md +76 -0
- package/skills/arc/references/resources.md +97 -0
- package/skills/arc/references/schedules.md +79 -0
- package/skills/arc/references/scim.md +61 -208
- package/skills/arc/references/tenancy-scope-install.md +82 -0
- package/skills/arc/references/testing.md +101 -144
- package/skills/arc/references/usage-cleanup-capabilities.md +45 -0
- package/skills/arc/references/validation.md +91 -0
- package/skills/arc/references/writes-hooks-errors.md +80 -0
- package/skills/arc-code-review/SKILL.md +67 -114
- package/skills/arc-code-review/references/arc-cheatsheet.md +68 -167
- package/skills/arc-code-review/references/mongokit-repositories.md +104 -0
- package/skills/arc-code-review/references/recipe-events-cache-jobs.md +112 -0
- package/skills/arc-code-review/references/recipe-resource.md +100 -0
- package/skills/arc-code-review/references/recipe-schemas-fields.md +93 -0
- package/skills/arc-code-review/references/recipe-scope-permissions.md +82 -0
- package/skills/arc-code-review/references/scaffolding.md +61 -198
- package/skills/arc-code-review/references/severity.md +49 -102
- package/skills/arc-code-review/references/smells-auth-scope.md +80 -0
- package/skills/arc-code-review/references/smells-data-events.md +66 -0
- package/skills/arc-code-review/references/smells-imports-style.md +59 -0
- package/skills/arc-code-review/references/smells-platform.md +89 -0
- package/skills/arc-code-review/references/smells-routes-schemas.md +66 -0
- package/skills/arc-module-publishing/SKILL.md +82 -208
- package/skills/arc-module-publishing/references/action-presets-and-plugins.md +87 -0
- package/skills/arc-module-publishing/references/build-and-types.md +73 -0
- package/skills/arc-module-publishing/references/module-lifecycle.md +101 -0
- package/skills/arc-module-publishing/references/package-manifest.md +34 -122
- package/skills/arc-module-publishing/references/publishing-workflow.md +44 -140
- package/skills/arc-module-publishing/references/resource-assembly.md +102 -0
- package/skills/arc-module-publishing/references/testing-packages.md +82 -0
- package/skills/arc/references/auth.md +0 -729
- package/skills/arc/references/integrations.md +0 -452
- package/skills/arc/references/mcp.md +0 -691
- package/skills/arc/references/production.md +0 -835
- package/skills/arc-code-review/references/anti-patterns.md +0 -1008
- package/skills/arc-code-review/references/migration-recipes.md +0 -649
- package/skills/arc-code-review/references/mongokit-migration.md +0 -360
- package/skills/arc-module-publishing/references/authoring-modules.md +0 -327
|
@@ -1,200 +1,157 @@
|
|
|
1
|
-
#
|
|
1
|
+
# Testing (`@classytic/arc/testing`)
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
| Need | Use |
|
|
4
|
+
|---|---|
|
|
5
|
+
| Auto CRUD + permission + validation coverage for one resource | `createHttpTestHarness` |
|
|
6
|
+
| Custom scenarios, one app with auth and fixtures | `createTestApp` + `expectArc` |
|
|
7
|
+
| Real app around modules (boots green means it composes) | `bootModuleApp` |
|
|
8
|
+
| Prove an adapter or store satisfies a contract | `runStorageContract`, `runOutboxStoreContract` (`/testing/outbox`), `runCleanupRunStoreContract` (`/testing/cleanup`) |
|
|
4
9
|
|
|
5
|
-
|
|
6
|
-
|---|---|---|
|
|
7
|
-
| `createHttpTestHarness(resource, ctxFn)` | You want auto-generated CRUD + permission + validation coverage per resource | ~16 tests / resource, zero boilerplate |
|
|
8
|
-
| `createTestApp({ resources, authMode, db })` | Custom scenarios, end-to-end flows, integration across resources | You write assertions with `expectArc(res)` |
|
|
9
|
-
| `runStorageContract(setup)` | You're building an adapter and want to prove it satisfies arc's Storage contract | DB-agnostic adapter conformance |
|
|
10
|
-
|
|
11
|
-
---
|
|
12
|
-
|
|
13
|
-
## `createTestApp()` — turnkey Fastify + in-memory Mongo + auth + fixtures
|
|
10
|
+
## createTestApp
|
|
14
11
|
|
|
15
12
|
```typescript
|
|
16
13
|
import { createTestApp, expectArc } from '@classytic/arc/testing';
|
|
17
14
|
import type { TestAppContext } from '@classytic/arc/testing';
|
|
18
15
|
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
db: 'in-memory', // default; or { uri } | false
|
|
27
|
-
connectMongoose: true, // optional — one-liner for Mongoose apps
|
|
28
|
-
});
|
|
29
|
-
|
|
30
|
-
ctx.auth.register('admin', {
|
|
31
|
-
user: { id: '1', roles: ['admin'] },
|
|
32
|
-
orgId: 'org-1',
|
|
33
|
-
});
|
|
34
|
-
});
|
|
35
|
-
|
|
36
|
-
afterAll(() => ctx.close());
|
|
37
|
-
|
|
38
|
-
it('GET /products — public', async () => {
|
|
39
|
-
const res = await ctx.app.inject({ method: 'GET', url: '/products' });
|
|
40
|
-
expectArc(res).ok().paginated();
|
|
16
|
+
let ctx: TestAppContext;
|
|
17
|
+
beforeAll(async () => {
|
|
18
|
+
ctx = await createTestApp({
|
|
19
|
+
resources: [productResource],
|
|
20
|
+
authMode: 'jwt', // 'jwt' (default) | 'better-auth' | 'none'
|
|
21
|
+
db: 'in-memory', // default | { uri } | false
|
|
22
|
+
connectMongoose: true, // mongoose.connect(dbUri) for Mongoose apps
|
|
41
23
|
});
|
|
24
|
+
ctx.auth!.register('admin', { user: { id: '1', roles: ['admin'] }, orgId: 'org-1' });
|
|
25
|
+
});
|
|
26
|
+
afterAll(() => ctx.close());
|
|
42
27
|
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
payload: { name: 'Widget', price: 99 },
|
|
49
|
-
});
|
|
50
|
-
expectArc(res).ok();
|
|
28
|
+
it('POST /products as admin', async () => {
|
|
29
|
+
const res = await ctx.app.inject({
|
|
30
|
+
method: 'POST', url: '/products',
|
|
31
|
+
headers: ctx.auth!.as('admin').headers,
|
|
32
|
+
payload: { name: 'Widget', price: 99 },
|
|
51
33
|
});
|
|
34
|
+
expectArc(res).ok(201);
|
|
52
35
|
});
|
|
53
36
|
```
|
|
54
37
|
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
- `'
|
|
59
|
-
- `
|
|
60
|
-
- `false` — no DB wiring (pure Fastify unit tests).
|
|
61
|
-
|
|
62
|
-
**`authMode: 'better-auth'`** requires the caller to also pass `auth: { type: 'better-auth', ... }`. Mismatched config fails fast at setup.
|
|
38
|
+
- `TestAppContext`: `{ app, auth, fixtures, dbUri, close }`. `auth` is `undefined` when `authMode: 'none'`.
|
|
39
|
+
- Other `createApp` options pass through (`plugins`, `auth`, `ports` ...). Defaults: `preset: 'testing'`, no logger, helmet, cors, rate limit.
|
|
40
|
+
- `db: 'in-memory'` needs `mongodb-memory-server` (dev dependency). `dbUri` is NOT wired into your adapters: connect them yourself.
|
|
41
|
+
- `authMode: 'better-auth'` requires you to pass `auth: { type: 'better-auth', ... }`; it throws otherwise.
|
|
42
|
+
- `ok()` defaults to 200, so pass the exact status (`ok(201)`).
|
|
63
43
|
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
## `TestAuthProvider` — unified session primitive
|
|
67
|
-
|
|
68
|
-
One `register()` → `.as(role).headers` flow across JWT, Better Auth, and custom providers.
|
|
69
|
-
|
|
70
|
-
```typescript
|
|
71
|
-
// JWT — provider signs on-the-fly via app.jwt.sign()
|
|
72
|
-
ctx.auth.register('admin', { user: { id: '1', roles: ['admin'] }, orgId: 'org-1' });
|
|
73
|
-
ctx.auth.register('user', { user: { id: '2', roles: ['user'] } });
|
|
74
|
-
|
|
75
|
-
// Better Auth / custom — pre-signed tokens
|
|
76
|
-
ctx.auth.register('admin', { token: existingToken, orgId: 'org-1' });
|
|
77
|
-
|
|
78
|
-
// Use
|
|
79
|
-
const headers = ctx.auth.as('admin').headers; // { authorization, x-organization-id }
|
|
80
|
-
const withExtra = ctx.auth.as('admin').withExtra({ 'x-request-id': 'r-1' }).headers;
|
|
81
|
-
```
|
|
44
|
+
## Auth sessions
|
|
82
45
|
|
|
83
|
-
|
|
46
|
+
`ctx.auth.register(role, { user | token, orgId?, extraHeaders? })`, then `ctx.auth.as(role).headers` (`authorization`, `x-organization-id`), `.withExtra({...})`, `ctx.auth.anonymous()` for 401 tests, `ctx.auth.roles`.
|
|
84
47
|
|
|
85
48
|
```typescript
|
|
86
|
-
import { createJwtAuthProvider, createBetterAuthProvider } from '@classytic/arc/testing';
|
|
87
|
-
const auth = createJwtAuthProvider(app, { defaultOrgId: 'org-1' });
|
|
49
|
+
import { createJwtAuthProvider, createBetterAuthProvider, createCustomAuthProvider } from '@classytic/arc/testing';
|
|
50
|
+
const auth = createJwtAuthProvider(app, { defaultOrgId: 'org-1' }); // signs via app.jwt.sign
|
|
88
51
|
```
|
|
89
52
|
|
|
90
|
-
|
|
53
|
+
`user` is signed by the JWT provider; Better Auth and custom providers need a pre-minted `token`.
|
|
91
54
|
|
|
92
|
-
##
|
|
55
|
+
## expectArc
|
|
93
56
|
|
|
94
|
-
|
|
57
|
+
Success bodies have no envelope, failures are `{ code, message, status }`.
|
|
95
58
|
|
|
96
59
|
```typescript
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
createHttpTestHarness(productResource, () => ({
|
|
104
|
-
app: ctx.app,
|
|
105
|
-
auth: ctx.auth,
|
|
106
|
-
adminRole: 'admin',
|
|
107
|
-
fixtures: { product: (i) => ({ name: `P${i}`, price: 10 + i }) },
|
|
108
|
-
})).runAll();
|
|
109
|
-
});
|
|
60
|
+
expectArc(res).ok(201);
|
|
61
|
+
expectArc(res).forbidden(); // also unauthorized(), notFound(), validationError(), conflict(), failed(status?)
|
|
62
|
+
expectArc(res).notFound().hasError(/not exist/);
|
|
63
|
+
expectArc(res).paginated({ total: 10 }); // docs[] plus pagination fields
|
|
64
|
+
expectArc(res).hidesField('password'); // also showsField, hasData(), hasMeta(key, value?)
|
|
110
65
|
```
|
|
111
66
|
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
## `expectArc(response)` — fluent envelope matchers
|
|
67
|
+
## createHttpTestHarness
|
|
115
68
|
|
|
116
69
|
```typescript
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
70
|
+
createHttpTestHarness(productResource, () => ({
|
|
71
|
+
app: ctx.app,
|
|
72
|
+
auth: ctx.auth!,
|
|
73
|
+
adminRole: 'admin',
|
|
74
|
+
fixtures: { valid: { name: 'P', price: 10 }, update: { price: 20 }, invalid: { price: 'x' } },
|
|
75
|
+
apiPrefix: '/api', // optional
|
|
76
|
+
})).runAll(); // or runCrud() / runPermissions() / runValidation()
|
|
124
77
|
```
|
|
125
78
|
|
|
126
|
-
|
|
79
|
+
Reads the resource config (`disabledRoutes`, `updateMethod`) and probes each enabled route. Pass a getter when the app is built in `beforeAll`.
|
|
127
80
|
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
## `createTestFixtures()` — DB-agnostic seeding
|
|
81
|
+
## Fixtures
|
|
131
82
|
|
|
132
83
|
```typescript
|
|
133
84
|
import { createTestFixtures } from '@classytic/arc/testing';
|
|
134
|
-
|
|
135
85
|
const fixtures = createTestFixtures();
|
|
136
|
-
fixtures.register('product',
|
|
137
|
-
|
|
138
|
-
|
|
86
|
+
fixtures.register('product', {
|
|
87
|
+
create: (data) => Product.create(data),
|
|
88
|
+
destroy: (doc) => Product.deleteOne({ _id: doc._id }).then(() => undefined),
|
|
139
89
|
});
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
await fixtures.clear();
|
|
90
|
+
await fixtures.create('product', { name: 'Widget' });
|
|
91
|
+
await fixtures.createMany('product', 3);
|
|
92
|
+
await fixtures.clear(); // destroyers run newest first
|
|
143
93
|
```
|
|
144
94
|
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
---
|
|
95
|
+
`register` also accepts a bare factory function (no cleanup). `ctx.fixtures` is the same tracker.
|
|
148
96
|
|
|
149
|
-
##
|
|
150
|
-
|
|
151
|
-
Composes `createTestApp` with Better Auth sign-up + org creation. Use when you need real Better Auth tokens rather than pre-signed stubs:
|
|
97
|
+
## bootModuleApp
|
|
152
98
|
|
|
153
99
|
```typescript
|
|
154
|
-
import {
|
|
100
|
+
import { bootModuleApp, testActorHeaders } from '@classytic/arc/testing';
|
|
155
101
|
|
|
156
|
-
const
|
|
157
|
-
|
|
158
|
-
|
|
102
|
+
const t = await bootModuleApp((ctx) => [catalogModule(ctx.connection)], {
|
|
103
|
+
replset: false, // true for transactions
|
|
104
|
+
actor: { roles: ['manager'], organizationId: 'org-1' }, // default actor
|
|
105
|
+
ports: { /* host ports */ },
|
|
106
|
+
app: { /* extra createApp options */ },
|
|
107
|
+
});
|
|
108
|
+
const engine = t.exports<CatalogEngine>('catalog');
|
|
109
|
+
await t.app.inject({ url: '/x', headers: testActorHeaders('cashier', 'org-1') });
|
|
110
|
+
await t.close();
|
|
159
111
|
```
|
|
160
112
|
|
|
161
|
-
|
|
113
|
+
- Database is a seam: `database` (default `mongoMemoryDatabase`) returns `{ uri, connection, teardown }`; kits inject their own.
|
|
114
|
+
- Identity comes from the `x-test-actor` header (`testActorHeaders(actor | roleString | null, orgId?)`). `null` stays public. Only `bootModuleApp` installs it; `createApp` never does.
|
|
115
|
+
- Gate routes with arc primitives (`requireRoles`, `requireOrgMembership`), not test-only gates.
|
|
116
|
+
- `assertModuleBootsAlone(modules, name, { probe })` boots a module with its dependency closure only.
|
|
117
|
+
- `assertRequiresPorts(module, ports, { with, ports })` proves declared required ports.
|
|
118
|
+
- `createTestModuleSetup({ ports })` gives `{ context, deferred, dispose }` to unit-test module phases.
|
|
119
|
+
- `runAuthorizationConformance`, `scopeRoleGate(...roles)` exist for authorization suites.
|
|
162
120
|
|
|
163
|
-
##
|
|
121
|
+
## Better Auth
|
|
164
122
|
|
|
165
123
|
```typescript
|
|
166
|
-
import {
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
}
|
|
124
|
+
import { setupBetterAuthTestApp } from '@classytic/arc/testing';
|
|
125
|
+
|
|
126
|
+
const r = await setupBetterAuthTestApp({
|
|
127
|
+
app, // built app with Better Auth registered
|
|
128
|
+
org: { name: 'Acme', slug: 'acme' },
|
|
129
|
+
users: [
|
|
130
|
+
{ key: 'admin', email: 'a@x.co', password: 'pw', name: 'A', role: 'owner', isCreator: true },
|
|
131
|
+
],
|
|
132
|
+
addMember, // required for non-creator users
|
|
133
|
+
});
|
|
134
|
+
r.auth.as('admin').headers; r.orgId; r.users.admin.token; await r.teardown();
|
|
176
135
|
```
|
|
177
136
|
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
## `runStorageContract(setup)` — adapter conformance
|
|
137
|
+
Exactly one user has `isCreator: true`. Lower level: `createBetterAuthTestHelpers()` gives `signUp`, `signIn`, `createOrg`, `setActiveOrg`, `authHeaders`.
|
|
181
138
|
|
|
182
|
-
|
|
139
|
+
## Contracts
|
|
183
140
|
|
|
184
141
|
```typescript
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
const storage = createMyAdapter();
|
|
188
|
-
return { storage, cleanup: async () => storage.close() };
|
|
189
|
-
});
|
|
142
|
+
runStorageContract('my-storage', async () => ({ storage, teardown: async () => storage.close() }));
|
|
143
|
+
runOutboxStoreContract('my-store', async () => ({ store, reset: async () => { /* empty it */ }, teardown }));
|
|
190
144
|
```
|
|
191
145
|
|
|
192
|
-
|
|
146
|
+
`reset` is required for the outbox contract and runs before every test.
|
|
147
|
+
|
|
148
|
+
## Unit-test mocks
|
|
149
|
+
|
|
150
|
+
`createMockRepository`, `createMockController`, `createMockUser`, `createMockRequest`, `createMockReply`, `createDataFactory`, `createSpy`, `createTestTimer`, `waitFor`.
|
|
193
151
|
|
|
194
152
|
## Tips
|
|
195
153
|
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
5. **Reach for `createHttpTestHarness` first** — 16 tests for one function call.
|
|
154
|
+
- Use `app.inject()`, never a real port.
|
|
155
|
+
- Register one auth session per role in `beforeAll`.
|
|
156
|
+
- Call `ctx.fixtures.clear()` in `afterEach`.
|
|
157
|
+
- Assert denials with `expectArc(res).forbidden()`, not raw status codes.
|
|
@@ -0,0 +1,45 @@
|
|
|
1
|
+
# Usage counters, tenant cleanup, runtime capabilities
|
|
2
|
+
|
|
3
|
+
## Usage counters and plan limits
|
|
4
|
+
|
|
5
|
+
`usagePlugin` (`@classytic/arc/usage`) decorates `fastify.usage` with per-actor, per-UTC-month counters: `record`, `summary`, `period`, `actorOf` (actor chain: org, user, client, ip). It tracks `api.requests` by default and `api.egress.bytes` on request; recording is fail-safe (a throwing store never fails a request).
|
|
6
|
+
|
|
7
|
+
| Store | Use |
|
|
8
|
+
|---|---|
|
|
9
|
+
| `MemoryUsageStore` | single process (default) |
|
|
10
|
+
| `RedisUsageStore` | distributed; retention is opt-in (`retentionSeconds`), counters are kept forever otherwise |
|
|
11
|
+
| a kit's `usage` store | counters beside domain data |
|
|
12
|
+
|
|
13
|
+
Quota gate: `requireQuota({ kind: 'ai.tokens', limit })` (number, `false` = unlimited, or a plan-aware resolver); denies with 429 `quota.exceeded` carrying `{ kind, used, limit, period, resetsAt }`. Fail-open on store errors unless `onStoreError: 'deny'`. Per-plan request ceilings: `createApp({ rateLimit: { plan } })` (the limiter runs before auth, so `resolve` sees the raw request).
|
|
14
|
+
|
|
15
|
+
## Tenant cleanup (GDPR / SOX / HIPAA)
|
|
16
|
+
|
|
17
|
+
```typescript
|
|
18
|
+
defineResource({ name: 'invoice', tenantField: 'organizationId',
|
|
19
|
+
onTenantDelete: { strategy: { type: 'anonymize', fields: { customerName: '[REDACTED]', email: null } },
|
|
20
|
+
priority: 50, batchSize: 1000 } });
|
|
21
|
+
defineResource({ name: 'event', onTenantDelete: { strategy: { type: 'hard' } } });
|
|
22
|
+
defineResource({ name: 'ledger', onTenantDelete: { strategy: { type: 'skip', reason: 'SOX retention' } } });
|
|
23
|
+
|
|
24
|
+
import { assertNoTenantData, cascadeDeleteForOrganization } from '@classytic/arc/registry';
|
|
25
|
+
const report = await cascadeDeleteForOrganization(fastify.arc.registry, { organizationId, concurrency: 4, logger: fastify.log });
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
Strategies: `hard`, `soft`, `anonymize` (`fields` static or `(doc) => value`), `skip` (`reason` mandatory). Resources without `onTenantDelete` are never touched. Index `tenantField` on every cascading resource. Smoke check: `assertNoTenantData(registry, { organizationId })`.
|
|
29
|
+
|
|
30
|
+
## Runtime capability registry
|
|
31
|
+
|
|
32
|
+
Under `runtime: 'distributed'`, a subsystem holding process-local state must declare it, or the end-of-boot audit fails naming every violator.
|
|
33
|
+
|
|
34
|
+
```typescript
|
|
35
|
+
import { declareRuntimeCapability } from '@classytic/arc/utils';
|
|
36
|
+
|
|
37
|
+
declareRuntimeCapability(fastify, {
|
|
38
|
+
subsystem: 'billing.sequence-cache',
|
|
39
|
+
durability: 'memory', // 'memory' | 'shared'
|
|
40
|
+
detail: 'invoice numbering cached per process',
|
|
41
|
+
// accepted: true, // only when per-process is intended by design; never inferred
|
|
42
|
+
});
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
Arc's own memory defaults declare themselves (`auth.sessions`, `usage.store`, `audit.store`, `cache.query`, `permissions.dynamic-cache`, `websocket.adapter`, `webhooks.store`); a distributed app must replace each with a shared store or accept it explicitly. See the production references for the store-by-store table.
|
|
@@ -0,0 +1,91 @@
|
|
|
1
|
+
# Validation: declare a zod schema once
|
|
2
|
+
|
|
3
|
+
Zod v4 is accepted in every schema slot. Arc converts it once at registration (`draft-7` for AJV, `openapi-3.0` for docs); plain JSON Schema passes through. Zod stays an optional peer.
|
|
4
|
+
|
|
5
|
+
## Slots
|
|
6
|
+
|
|
7
|
+
| Where | Slot | Direction |
|
|
8
|
+
|---|---|---|
|
|
9
|
+
| `routes[].schema` | `body`, `querystring`, `params`, `headers` | input |
|
|
10
|
+
| `routes[].schema.response` | `{ 200: schema }` | output |
|
|
11
|
+
| `customSchemas.{list,get,create,update,delete}` | same parts, replaces the generated part wholesale | input / output |
|
|
12
|
+
| `actions.<name>.schema` | the body schema itself | input |
|
|
13
|
+
| `openApiSchemas` | docs only (`createBody`, `updateBody`, `listQuery`, ...) | input |
|
|
14
|
+
|
|
15
|
+
Input direction keeps `.default()` optional on the wire and keeps `.transform()` representable. A plain `z.object()` strips unknown keys, so it does not emit `additionalProperties: false` on input; use `z.strictObject()` to reject them. A `z.object` response doubles as a field-stripping contract. `.meta({ description, examples })` flows into OpenAPI and MCP.
|
|
16
|
+
|
|
17
|
+
## routeInput: AJV + parsed handler input
|
|
18
|
+
|
|
19
|
+
AJV validates what JSON Schema can express. JSON Schema cannot trim, refine across fields or fill nested defaults, so `routeInput` adds a `preHandler` that runs the same zod schema and replaces `request.body|query|params` with its OUTPUT.
|
|
20
|
+
|
|
21
|
+
```typescript
|
|
22
|
+
import { parsed, routeInput } from '@classytic/arc/core';
|
|
23
|
+
import { allowPublic } from '@classytic/arc/permissions';
|
|
24
|
+
import { z } from 'zod';
|
|
25
|
+
|
|
26
|
+
const createNote = z.object({ title: z.string().trim().min(2), tags: z.array(z.string()).default([]) });
|
|
27
|
+
const listQuery = z.object({ limit: z.coerce.number().int().min(1).default(20) });
|
|
28
|
+
|
|
29
|
+
routes: [{
|
|
30
|
+
method: 'POST', path: '/notes', permissions: allowPublic(),
|
|
31
|
+
...routeInput({ body: createNote, querystring: listQuery, response: { 200: z.object({ id: z.string() }) } }),
|
|
32
|
+
rawHandler: async (req, reply) => {
|
|
33
|
+
const body = parsed(createNote, req.body); // typed z.output, trimmed, defaulted
|
|
34
|
+
return reply.send({ id: await notes.create(body) });
|
|
35
|
+
},
|
|
36
|
+
}]
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
- A failed parse is `400 arc.validation_error` with `details[]` (`path`, `message`), the same wire as an AJV failure.
|
|
40
|
+
- A plain JSON Schema slot is AJV-only (no preHandler is added for it).
|
|
41
|
+
- `parsed(schema, value)` is a typing helper: it does not parse again.
|
|
42
|
+
- `headers` and `response` are schema-only.
|
|
43
|
+
|
|
44
|
+
## CRUD verbs: crudInput
|
|
45
|
+
|
|
46
|
+
```typescript
|
|
47
|
+
import { crudInput } from '@classytic/arc/core';
|
|
48
|
+
|
|
49
|
+
defineResource({
|
|
50
|
+
name: 'course', adapter,
|
|
51
|
+
...crudInput({ create: courseCreate, update: courseUpdate, parse: true }),
|
|
52
|
+
});
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
Returns `customSchemas` (what AJV enforces) and `openApiSchemas` (what docs show, instead of the stored model). `parse: true` also returns `middlewares.create|update` that hand the repository the zod output; merge it with your own `middlewares` instead of overwriting.
|
|
56
|
+
|
|
57
|
+
## Actions
|
|
58
|
+
|
|
59
|
+
```typescript
|
|
60
|
+
import { defineAction, noPayloadSchema } from '@classytic/arc/core';
|
|
61
|
+
|
|
62
|
+
actions: {
|
|
63
|
+
close: defineAction({
|
|
64
|
+
schema: z.object({ note: z.string().trim().min(2) }),
|
|
65
|
+
parse: true, // handler's data is the zod output; default false = what AJV accepted
|
|
66
|
+
permissions: requireRoles(['admin']),
|
|
67
|
+
handler: async (id, data) => tickets.close(id, data.note),
|
|
68
|
+
}),
|
|
69
|
+
touch: { schema: noPayloadSchema, permissions: requireAuth(), handler: async (id) => touch(id) },
|
|
70
|
+
}
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
`noPayloadSchema` is plain JSON Schema (`additionalProperties: false`): any stray field is a 400.
|
|
74
|
+
|
|
75
|
+
## The wrapper pitfall
|
|
76
|
+
|
|
77
|
+
An action's `schema` IS the body schema. `schema: { body: X }` has no `type` or `properties`, arc reads it as empty, and the action accepts anything with no error.
|
|
78
|
+
|
|
79
|
+
```typescript
|
|
80
|
+
schema: { body: z.object({ note: z.string() }) } // WRONG: validates nothing
|
|
81
|
+
schema: z.object({ note: z.string() }) // right
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
`defineResource()` records a `schema.slot_wrapper` diagnostic (logged at registration) for this shape in action schemas and in route or `customSchemas` slots (`body: { body: X }`). Make it fatal: `strictSchemas: true` on the resource or `ARC_STRICT_SCHEMAS=true`.
|
|
85
|
+
|
|
86
|
+
## Other rules
|
|
87
|
+
|
|
88
|
+
- `customSchemas` parts replace generated parts; untouched parts keep auto-generation. Model-required fields the server fills: `schemaOptions.fieldRules: { f: { systemManaged: true } }`.
|
|
89
|
+
- Unconvertible zod in a validation slot (`z.date()`, `z.bigint()`, custom checks) fails boot: use the wire form (`z.iso.datetime()`, `z.string()`) and convert in the handler.
|
|
90
|
+
- A `.refine()` is not enforced by AJV: it needs `routeInput` / `parse: true`, or do it in the handler.
|
|
91
|
+
- A thrown raw `ZodError` from your own `.parse()` is not mapped to a 400 by arc; use `routeInput` or throw `ValidationError`.
|
|
@@ -0,0 +1,80 @@
|
|
|
1
|
+
# Writes, hooks, errors, audit
|
|
2
|
+
|
|
3
|
+
## Write verbs and transactions
|
|
4
|
+
|
|
5
|
+
`writes` binds a domain command to a CRUD slot. `transactional: true` runs the persistence step inside the kit's `withTransaction`; the verb receives the tx-bound repository and `ctx.uow`.
|
|
6
|
+
|
|
7
|
+
```typescript
|
|
8
|
+
defineResource({
|
|
9
|
+
name: 'order', adapter, transactional: true,
|
|
10
|
+
writes: {
|
|
11
|
+
create: async (data, ctx) => {
|
|
12
|
+
const order = await ctx.repository.create(data); // tx-bound
|
|
13
|
+
await outbox.store(event, { session: ctx.uow?.session }); // same transaction
|
|
14
|
+
return order;
|
|
15
|
+
},
|
|
16
|
+
},
|
|
17
|
+
});
|
|
18
|
+
```
|
|
19
|
+
|
|
20
|
+
- Hooks run once, outside the retry; only persistence re-runs on a transient conflict. `VersionConflictError` surfaces as 409, never retried.
|
|
21
|
+
- Retry belongs to the kit (`transactionRetry`); arc never stacks a second policy.
|
|
22
|
+
- Boot fails without `withTransaction`, and at registration when `capabilities.transactions !== true` (standalone Mongo, D1).
|
|
23
|
+
- `ctx.uow.session` is empty on connection-bound backends (SQLite): use the tx-bound repository.
|
|
24
|
+
|
|
25
|
+
## Hooks
|
|
26
|
+
|
|
27
|
+
```typescript
|
|
28
|
+
hooks: {
|
|
29
|
+
beforeCreate: async (ctx) => { ctx.data.slug = slugify(ctx.data.name); },
|
|
30
|
+
afterCreate: async (ctx) => { analytics.track('created', { id: ctx.data._id }); },
|
|
31
|
+
beforeUpdate: async (ctx) => { /* ctx.meta.existing is the pre-image */ },
|
|
32
|
+
beforeDelete: async (ctx) => { if (ctx.data.isProtected) throw new Error('locked'); },
|
|
33
|
+
}
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
`ctx = { data, user?, meta? }`; `meta` carries `id` and `existing`. Cross-resource: `createHookSystem()` and `beforeCreate(hooks, 'product', fn)` from `@classytic/arc/hooks`.
|
|
37
|
+
|
|
38
|
+
## Errors
|
|
39
|
+
|
|
40
|
+
```typescript
|
|
41
|
+
import { createDomainError, NotFoundError } from '@classytic/arc';
|
|
42
|
+
|
|
43
|
+
throw new NotFoundError('Product'); // 404 arc.not_found
|
|
44
|
+
throw createDomainError('SELF_REFERRAL', 'Cannot self-refer', 422, { field });
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
Wire (repo-core `ErrorContract`, no envelope, HTTP status discriminates): `{ code, message, status, details?, meta?, correlationId? }`. AJV and zod failures are `400 arc.validation_error` with `details[]`. Unknown routes are `404 arc.not_found`.
|
|
48
|
+
|
|
49
|
+
```typescript
|
|
50
|
+
errorHandler: { errorMappers: [{ type: AccountingError,
|
|
51
|
+
toResponse: (e) => ({ status: e.status, code: e.code, message: e.message }) }] }
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
Modules ship mappers with `defineModule({ errorMappers })`; host mappers keep priority. A raw `ZodError` from your own `.parse()` is not mapped (use `routeInput`). Driver duplicate-key errors become 409 `arc.conflict`.
|
|
55
|
+
|
|
56
|
+
## Audit and history
|
|
57
|
+
|
|
58
|
+
```typescript
|
|
59
|
+
await fastify.register(auditPlugin, { autoAudit: { perResource: true } });
|
|
60
|
+
|
|
61
|
+
defineResource({ name: 'order', audit: true });
|
|
62
|
+
defineResource({ name: 'invoice', history: true }); // adds GET /:id/history from audit rows; implies audit
|
|
63
|
+
defineResource({ name: 'payment', audit: { operations: ['delete'] } });
|
|
64
|
+
await app.audit.custom('order', id, 'refund', { reason }, { user }); // manual, e.g. read auditing
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
History is gated update -> get -> `requireAuth` unless you pass `{ permissions, limit }`.
|
|
68
|
+
|
|
69
|
+
## Refusing from your own hook
|
|
70
|
+
|
|
71
|
+
A hook that refuses must end the lifecycle itself. `reply.sent` stays false while 2+ async `preSerialization`/`onSend` hooks defer the write, so Fastify runs the handler after a `reply.send(...)` that returned nothing (the write happened, so did the side effects).
|
|
72
|
+
|
|
73
|
+
```typescript
|
|
74
|
+
fastify.addHook('preHandler', async (req, reply) => {
|
|
75
|
+
if (!allowed(req)) return reply.code(403).send({ code: 'arc.forbidden', message: 'No', status: 403 }); // return the reply
|
|
76
|
+
});
|
|
77
|
+
// or throw: createError(403, 'No') from @classytic/arc/utils; the error handler serializes it
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
Arc's own gates (permissions, auth, org scope, rate limit, cache hit) return the reply. `defineGuard` and a custom `auth.authenticate` that reply without returning are detected and ended for you. Pinned by `tests/core/refusal-ends-lifecycle.test.ts`; guard a host app with `checkRefusalDoesNoWork` from `@classytic/arc-testkit/conformance`.
|