@classytic/arc 2.4.3 → 2.5.1

package/dist/{types-BJmgxNbF.d.mts → types-ByCPlfZ1.d.mts}

@@ -1,4 +1,4 @@
-import { Lt as ResourceDefinition } from "./interface-DGmPxakH.mjs";
+import { Bt as ResourceDefinition } from "./interface-BnNjdl33.mjs";
 import { z } from "zod";
 
 //#region src/integrations/mcp/types.d.ts

package/dist/{types-Dt0-AI6E.d.mts → types-Guk83PDz.d.mts}

@@ -1,5 +1,5 @@
-import { n as ElevationOptions } from "./elevation-Ca_yveIO.mjs";
-import { h as Authenticator } from "./interface-DGmPxakH.mjs";
+import { n as ElevationOptions } from "./elevation-C_taLQrM.mjs";
+import { g as Authenticator } from "./interface-BnNjdl33.mjs";
 import { t as ExternalOpenApiPaths } from "./externalPaths-DpO-s7r8.mjs";
 import { i as CacheStore } from "./interface-D_BWALyZ.mjs";
 import { r as QueryCachePluginOptions } from "./queryCachePlugin-DcmETvcB.mjs";

package/dist/utils/index.d.mts

@@ -1,5 +1,5 @@
-import { G as ParsedQuery, U as OpenApiSchemas, X as QueryParserInterface, l as AnyRecord } from "../interface-DGmPxakH.mjs";
-import { a as NotFoundError, c as RateLimitError, d as ValidationError, f as createError, i as ForbiddenError, l as ServiceUnavailableError, n as ConflictError, o as OrgAccessDeniedError, p as isArcError, r as ErrorDetails, s as OrgRequiredError, t as ArcError, u as UnauthorizedError } from "../errors-CPpvPHT0.mjs";
+import { K as ParsedQuery, W as OpenApiSchemas, Z as QueryParserInterface, l as AnyRecord } from "../interface-BnNjdl33.mjs";
+import { a as NotFoundError, c as RateLimitError, d as ValidationError, i as ForbiddenError, l as ServiceUnavailableError, m as isArcError, n as ConflictError, o as OrgAccessDeniedError, p as createError, r as ErrorDetails, s as OrgRequiredError, t as ArcError, u as UnauthorizedError } from "../errors-CcVbl1-T.mjs";
 import { a as CircuitBreakerStats, c as createCircuitBreakerRegistry, i as CircuitBreakerRegistry, n as CircuitBreakerError, o as CircuitState, r as CircuitBreakerOptions, s as createCircuitBreaker, t as CircuitBreaker } from "../circuitBreaker-JP2GdJ4b.mjs";
 import { FastifyInstance } from "fastify";
 

package/dist/utils/index.mjs

@@ -1,7 +1,7 @@
 import { n as createQueryParser, t as ArcQueryParser } from "../queryParser-CgCtsjti.mjs";
 import { a as createCircuitBreaker, i as CircuitState, n as CircuitBreakerError, o as createCircuitBreakerRegistry, r as CircuitBreakerRegistry, t as CircuitBreaker } from "../circuitBreaker-BOBOpN2w.mjs";
 import { _ as defineCompensation, a as getListQueryParams, c as listResponse, d as paginateWrapper, f as paginationSchema, g as wrapResponse, h as successResponseSchema, i as getDefaultCrudSchemas, l as messageWrapper, m as responses, n as deleteResponse, o as itemResponse, p as queryParams, r as errorResponseSchema, s as itemWrapper, t as createStateMachine, u as mutationResponse, v as withCompensation } from "../utils-Dc0WhlIl.mjs";
-import { a as OrgAccessDeniedError, c as ServiceUnavailableError, d as createError, f as isArcError, i as NotFoundError, l as UnauthorizedError, n as ConflictError, o as OrgRequiredError, r as ForbiddenError, s as RateLimitError, t as ArcError, u as ValidationError } from "../errors-rxhfP7Hf.mjs";
+import { a as OrgAccessDeniedError, c as ServiceUnavailableError, f as createError, i as NotFoundError, l as UnauthorizedError, n as ConflictError, o as OrgRequiredError, p as isArcError, r as ForbiddenError, s as RateLimitError, t as ArcError, u as ValidationError } from "../errors-NoQKsbAT.mjs";
 import { a as toJsonSchema, i as isZodSchema, n as convertRouteSchema, r as isJsonSchema, t as convertOpenApiSchemas } from "../schemaConverter-DjzHpFam.mjs";
 import { t as hasEvents } from "../typeGuards-Cj5Rgvlg.mjs";
 export { ArcError, ArcQueryParser, CircuitBreaker, CircuitBreakerError, CircuitBreakerRegistry, CircuitState, ConflictError, ForbiddenError, NotFoundError, OrgAccessDeniedError, OrgRequiredError, RateLimitError, ServiceUnavailableError, UnauthorizedError, ValidationError, convertOpenApiSchemas, convertRouteSchema, createCircuitBreaker, createCircuitBreakerRegistry, createError, createQueryParser, createStateMachine, defineCompensation, deleteResponse, errorResponseSchema, getDefaultCrudSchemas, getListQueryParams, hasEvents, isArcError, isJsonSchema, isZodSchema, itemResponse, itemWrapper, listResponse, messageWrapper, mutationResponse, paginateWrapper, paginationSchema, queryParams, responses, successResponseSchema, toJsonSchema, withCompensation, wrapResponse };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@classytic/arc",
-  "version": "2.4.3",
+  "version": "2.5.1",
   "description": "Resource-oriented backend framework for Fastify — clean, minimal, powerful, tree-shakable",
   "type": "module",
   "exports": {
@@ -220,7 +220,7 @@
     "node": ">=22"
   },
   "peerDependencies": {
-    "@classytic/mongokit": ">=3.4.5",
+    "@classytic/mongokit": ">=3.5.0",
     "@classytic/streamline": ">=2.0.0",
     "@fastify/cors": "^11.0.0",
     "@fastify/helmet": "^13.0.0",
@@ -244,7 +244,7 @@
     "fastify-raw-body": "^5.0.0",
     "ioredis": "^5.0.0",
     "mongodb": "^6.0.0 || ^7.0.0",
-    "mongoose": "^8.0.0 || ^9.0.0",
+    "mongoose": ">=9.0.0",
     "pino-pretty": "^13.0.0",
     "zod": "^4.0.0"
   },
@@ -337,7 +337,7 @@
   },
   "devDependencies": {
     "@biomejs/biome": "^2.4.10",
-    "@classytic/mongokit": "^3.4.5",
+    "@classytic/mongokit": "^3.5.2",
     "@fastify/jwt": "^10.0.0",
     "@fastify/multipart": "^9.0.0",
     "@fastify/type-provider-typebox": "^6.0.0",

package/skills/arc/SKILL.md

@@ -314,6 +314,26 @@ const app = await createApp({
 
 ## Hooks
 
+**Inline on resource (recommended):**
+
+```typescript
+defineResource({
+  name: 'chat',
+  hooks: {
+    beforeCreate: async (ctx) => { ctx.data.slug = slugify(ctx.data.name); },
+    afterCreate: async (ctx) => { analytics.track('created', { id: ctx.data._id, user: ctx.user?.id }); },
+    beforeUpdate: async (ctx) => { console.log('Updating', ctx.meta?.id, 'existing:', ctx.meta?.existing); },
+    afterUpdate: async (ctx) => { await invalidateCache(ctx.data._id); },
+    beforeDelete: async (ctx) => { if (ctx.data.isProtected) throw new Error('Cannot delete'); },
+    afterDelete: async (ctx) => { await cleanupFiles(ctx.meta?.id); },
+  },
+});
+```
+
+`ResourceHookContext`: `{ data, user?, meta? }` — `data` is the document, `meta` has `id` and `existing` (for update/delete).
+
+**App-level (cross-resource):**
+
 ```typescript
 import { createHookSystem, beforeCreate, afterUpdate } from '@classytic/arc/hooks';
 
@@ -386,8 +406,10 @@ defineResource({
 ## Error Classes
 
 ```typescript
-import { ArcError, NotFoundError, ValidationError, UnauthorizedError, ForbiddenError } from '@classytic/arc';
-throw new NotFoundError('Product not found');  // 404
+import { ArcError, NotFoundError, ValidationError, createDomainError } from '@classytic/arc';
+throw new NotFoundError('Product not found');                      // 404
+throw createDomainError('MEMBER_NOT_FOUND', 'Not found', 404);    // domain error with code
+throw createDomainError('SELF_REFERRAL', 'Cannot self-refer', 422, { field: 'referralCode' });
 ```
 
 Error handler catches: `ArcError` → `.statusCode` (Fastify) → `.status` (MongoKit, http-errors) → `errorMap` → Mongoose/MongoDB → fallback 500. DB-agnostic — any error with `.status` or `.statusCode` gets the correct HTTP response.
@@ -481,6 +503,35 @@ src/resources/order/
 
 Generate: `arc generate resource order --mcp` | Wire: `extraTools: [fulfillOrderTool]`
 
+**DX helpers** (v2.4.4):
+
+```typescript
+// Typed request for wrapHandler: false routes — no more (req as any).user
+import type { ArcRequest } from '@classytic/arc';
+handler: async (req: ArcRequest, reply) => { req.user?.id; req.scope; req.signal; }
+
+// Response envelope — no manual { success, data } wrapping
+import { envelope } from '@classytic/arc';
+reply.send(envelope(data, { total: 100 }));
+
+// Canonical org extraction — replaces 19 duplicated patterns
+import { getOrgContext } from '@classytic/arc/scope';
+const { userId, organizationId, roles, orgRoles } = getOrgContext(request);
+
+// Domain errors with auto HTTP status mapping
+import { createDomainError } from '@classytic/arc';
+throw createDomainError('SELF_REFERRAL', 'Cannot refer yourself', 422);
+
+// Resource lifecycle hook — wire singletons during registration
+defineResource({ name: 'notification', onRegister: (f) => setSseManager(f.sseManager) });
+
+// SSE auth — preAuth runs BEFORE auth middleware (EventSource can't set headers)
+additionalRoutes: [{ preAuth: [(req) => { req.headers.authorization = `Bearer ${req.query.token}`; }] }]
+
+// SSE streaming — auto headers + bypasses response wrapper
+additionalRoutes: [{ streamResponse: true, handler: async (req, reply) => reply.send(stream) }]
+```
+
 ## Subpath Imports
 
 ```typescript

package/skills/arc/references/mcp.md

@@ -429,3 +429,138 @@ await app.register(mcpPlugin, {
 - `DELETE /mcp` — terminates session
 
 Sessions: lazily created, TTL-cached, LRU-evicted at max capacity, auto-cleaned on shutdown.
+
+## Health Endpoint
+
+`GET /mcp/health` — no MCP protocol needed, plain JSON:
+
+```json
+{
+  "status": "ok",
+  "mode": "stateless",
+  "tools": 11,
+  "resources": 2,
+  "toolNames": ["list_products", "get_product", ...],
+  "sessions": null
+}
+```
+
+Use to verify the MCP server is alive before configuring Claude CLI.
+
+## DX Helpers (v2.4.4)
+
+### ArcRequest — Typed Fastify Request
+
+For `wrapHandler: false` routes, use `ArcRequest` instead of `(req as any).user`:
+
+```typescript
+import type { ArcRequest } from '@classytic/arc';
+
+handler: async (req: ArcRequest, reply) => {
+  req.user?.id;                    // typed
+  req.scope.organizationId;        // typed (when member)
+  req.signal;                      // AbortSignal (Fastify 5 built-in)
+}
+```
+
+### envelope() — Response Helper
+
+```typescript
+import { envelope } from '@classytic/arc';
+
+handler: async (req, reply) => {
+  const data = await service.getResults();
+  return reply.send(envelope(data));
+  // → { success: true, data }
+  return reply.send(envelope(data, { total: 100, page: 1 }));
+  // → { success: true, data, total: 100, page: 1 }
+}
+```
+
+### getOrgContext() — Canonical Org Extraction
+
+Eliminates duplicated `req.user.organizationId || req.headers['x-organization-id']` patterns:
+
+```typescript
+import { getOrgContext } from '@classytic/arc/scope';
+
+handler: async (req, reply) => {
+  const { userId, organizationId, roles, orgRoles } = getOrgContext(req);
+  // Works regardless of auth type (JWT, Better Auth, custom)
+}
+```
+
+### createDomainError() — Error Factory
+
+Eliminates manual `if (err.code) return status` mapping:
+
+```typescript
+import { createDomainError } from '@classytic/arc';
+
+throw createDomainError('MEMBER_NOT_FOUND', 'Member does not exist', 404);
+throw createDomainError('SELF_REFERRAL', 'Cannot refer yourself', 422);
+throw createDomainError('INSUFFICIENT_BALANCE', 'Not enough credits', 402, { balance: 0 });
+// Arc's error handler auto-maps statusCode to HTTP response
+```
+
+### onRegister — Resource Lifecycle Hook
+
+Called during plugin registration with the scoped Fastify instance:
+
+```typescript
+defineResource({
+  name: 'notification',
+  onRegister: (fastify) => {
+    setSseManager(fastify.sseManager);
+  },
+})
+```
+
+### preAuth — Pre-Auth Handlers for SSE/WebSocket
+
+Run before auth middleware. Use for promoting `?token=` to `Authorization` header (EventSource can't set headers):
+
+```typescript
+additionalRoutes: [{
+  method: 'GET',
+  path: '/stream',
+  wrapHandler: false,
+  permissions: requireAuth(),
+  preAuth: [(req) => {
+    const token = req.query?.token;
+    if (token) req.headers.authorization = `Bearer ${token}`;
+  }],
+  handler: sseHandler,
+}]
+```
+
+### streamResponse — SSE Route Flag
+
+Auto-sets SSE headers and bypasses Arc's response wrapper:
+
+```typescript
+additionalRoutes: [{
+  method: 'POST',
+  path: '/stream',
+  streamResponse: true,        // SSE headers + no { success, data } wrapper
+  permissions: requireAuth(),
+  handler: async (request, reply) => {
+    const { stream } = await generateStream({ abortSignal: request.signal });
+    return reply.send(stream);
+  },
+}]
+```
+
+## Test Coverage
+
+165 test files, 2439 tests. MCP-specific:
+
+| Test File | Tests | Covers |
+|-----------|-------|--------|
+| `mcp-auth-e2e.test.ts` | 16 | All auth modes, multi-tenancy, permission filters, async permissions |
+| `mcp-dx-features.test.ts` | 14 | include, names, prefix, disableDefaultRoutes, mcpHandler, guards, CRUD lifecycle |
+| `resourceToTools.test.ts` | 12 | Tool generation, annotations, field hiding, soft delete |
+| `createMcpServer.test.ts` | 10 | Server creation, tool registration, InMemoryTransport |
+| `guards.test.ts` | 8 | requireAuth, requireOrg, requireRole, customGuard, composition |
+| `dx-features.test.ts` | 17 | envelope, getOrgContext, createDomainError, onRegister, preAuth, streamResponse |
+| Others | 32 | fieldRulesToZod, defineTool, definePrompt, buildRequestContext, sessionCache, authCache |