@classytic/arc 2.7.1 → 2.7.3

package/dist/{types-D0qf0Mf4.d.mts → types-2FlNl0mL.d.mts}

@@ -1,12 +1,12 @@
-import { _ as Authenticator } from "./interface-Dwzqt4mn.mjs";
-import { n as ElevationOptions } from "./elevation-Dm-HTBCt.mjs";
-import { t as ExternalOpenApiPaths } from "./externalPaths-Dg7OLsKo.mjs";
-import { i as CacheStore } from "./interface-CnluRL4_.mjs";
-import { r as QueryCachePluginOptions } from "./queryCachePlugin-Bw8XyJpX.mjs";
-import { i as EventTransport } from "./EventTransport-CUpRK_Lg.mjs";
-import { t as EventPluginOptions } from "./eventPlugin-BgLxJkIB.mjs";
-import { c as MetricsOptions, d as SSEOptions, m as CachingOptions, r as VersioningOptions, t as ErrorHandlerOptions } from "./errorHandler-COa51ho_.mjs";
-import { r as IdempotencyStore } from "./interface-B9rHWPxD.mjs";
+import { _ as Authenticator } from "./interface-B91alUzq.mjs";
+import { n as ElevationOptions } from "./elevation-D7WK0RXq.mjs";
+import { t as ExternalOpenApiPaths } from "./externalPaths-iba7jD3d.mjs";
+import { i as CacheStore } from "./interface-CG7oRZjX.mjs";
+import { r as QueryCachePluginOptions } from "./queryCachePlugin-Ckl71mkc.mjs";
+import { i as EventTransport } from "./EventTransport-C4VheKeC.mjs";
+import { t as EventPluginOptions } from "./eventPlugin-CdvUoUna.mjs";
+import { c as MetricsOptions, d as SSEOptions, m as CachingOptions, r as VersioningOptions, t as ErrorHandlerOptions } from "./errorHandler-pCpEtNd7.mjs";
+import { r as IdempotencyStore } from "./interface-CSbZdv_3.mjs";
 import { FastifyInstance, FastifyPluginAsync, FastifyReply, FastifyRequest, FastifyServerOptions } from "fastify";
 
 //#region src/factory/loadResources.d.ts
@@ -598,6 +598,41 @@ interface CreateAppOptions {
   ajv?: {
     keywords?: string[];
   };
+  /**
+   * Enable `reply.ok()`, `reply.fail()`, `reply.paginated()` response helpers.
+   *
+   * Default: `false` (opt-in).
+   *
+   * @example
+   * ```typescript
+   * const app = await createApp({ replyHelpers: true });
+   *
+   * // Then in any handler:
+   * return reply.ok({ name: 'MacBook' });          // → 200 { success: true, data: { ... } }
+   * return reply.ok(product, 201);                  // → 201 { success: true, data: { ... } }
+   * return reply.fail('Not found', 404);            // → 404 { success: false, error: '...' }
+   * return reply.fail(['err1', 'err2'], 422);       // → 422 { success: false, errors: [...] }
+   * return reply.paginated({ docs, total, page, limit });
+   * ```
+   */
+  replyHelpers?: boolean;
+  /**
+   * Auto-convert BigInt values to Number in all JSON responses.
+   *
+   * When `true`, Arc adds a `preSerialization` hook that converts BigInt values
+   * to Number before JSON serialization. Without this, `JSON.stringify` throws
+   * on BigInt values (e.g., from financial libraries like fin-io).
+   *
+   * Default: `false` (opt-in — most apps don't use BigInt).
+   *
+   * @example
+   * ```typescript
+   * const app = await createApp({
+   *   serializeBigInt: true,
+   * });
+   * ```
+   */
+  serializeBigInt?: boolean;
   /**
    * Resources to register automatically.
    * Each resource's `.toPlugin()` is called and registered for you.

package/dist/{types-DPsC0taJ.d.mts → types-B4BNthET.d.mts}

@@ -1,4 +1,4 @@
-import { r as RequestScope } from "./types-CNEbix8T.mjs";
+import { r as RequestScope } from "./types--D3vvfdt.mjs";
 import { FastifyRequest } from "fastify";
 
 //#region src/permissions/types.d.ts

package/dist/{types-ClmkMDK1.d.mts → types-C5g2oRC7.d.mts}

@@ -1,4 +1,4 @@
-import { Vt as ResourceDefinition } from "./interface-Dwzqt4mn.mjs";
+import { Vt as ResourceDefinition } from "./interface-B91alUzq.mjs";
 import { z } from "zod";
 
 //#region src/integrations/mcp/types.d.ts
@@ -220,12 +220,28 @@ interface McpSession {
 }
 /** Resolved auth identity for a single MCP request */
 interface McpAuthResult {
-  userId: string;
+  /**
+   * Human user ID. Optional for service/machine principals — when `clientId`
+   * is set and `userId` is omitted, the principal is purely machine-identity
+   * and `ctx.user` will be `null` (not a synthetic user object).
+   */
+  userId?: string;
   organizationId?: string;
   /** User roles (global) — used by guard helpers like requireRole() */
   roles?: string[];
   /** Org-level roles — used by guard helpers */
   orgRoles?: string[];
+  /**
+   * OAuth client ID — set this to enable `kind: "service"` scope.
+   * When present, buildRequestContext produces a service scope instead
+   * of member/authenticated, enabling `requireServiceScope()` checks.
+   */
+  clientId?: string;
+  /**
+   * OAuth scopes (e.g. `['read:products', 'write:orders']`).
+   * Carried on the `service` RequestScope for fine-grained permission checks.
+   */
+  scopes?: readonly string[];
   /** Any extra metadata from the auth resolver */
   [key: string]: unknown;
 }

package/dist/utils/index.d.mts

@@ -1,6 +1,6 @@
-import { G as OpenApiSchemas, Q as QueryParserInterface, q as ParsedQuery, u as AnyRecord } from "../interface-Dwzqt4mn.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-CCSsMpXE.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-DwxrljLB.mjs";
+import { G as OpenApiSchemas, Q as QueryParserInterface, q as ParsedQuery, u as AnyRecord } from "../interface-B91alUzq.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-BS6lZvWy.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-BBPDt-J_.mjs";
 import { FastifyInstance } from "fastify";
 
 //#region src/utils/compensation.d.ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@classytic/arc",
-  "version": "2.7.1",
+  "version": "2.7.3",
   "description": "Resource-oriented backend framework for Fastify — clean, minimal, powerful, tree-shakable",
   "type": "module",
   "exports": {
@@ -212,13 +212,16 @@
     "lint:fix": "biome check --fix src/",
     "lint:all": "biome check src/ tests/",
     "test": "vitest run",
+    "test:main": "vitest run",
+    "test:perf": "node --expose-gc ./node_modules/vitest/vitest.mjs run --config vitest.perf.config.ts",
+    "test:ci": "npm run test:main && npm run test:perf",
     "test:watch": "vitest",
     "test:ui": "vitest --ui",
     "test:coverage": "vitest run --coverage",
     "test:e2e": "vitest run tests/e2e",
     "test:unit": "vitest run tests/core tests/hooks tests/utils tests/plugins",
     "smoke": "node scripts/smoke-test.mjs",
-    "prepublishOnly": "npm run typecheck && npm test && npm run build && npm run smoke"
+    "prepublishOnly": "npm run typecheck && npm run test:ci && npm run build && npm run smoke"
   },
   "engines": {
     "node": ">=22"

package/skills/arc/SKILL.md

@@ -8,7 +8,7 @@ description: |
   Triggers: arc, fastify resource, defineResource, createApp, BaseController, arc preset,
   arc auth, arc events, arc jobs, arc websocket, arc mcp, arc plugin, arc testing, arc cli,
   arc permissions, arc hooks, arc pipeline, arc factory, arc cache, arc QueryCache.
-version: 2.7.1
+version: 2.7.3
 license: MIT
 metadata:
   author: Classytic
@@ -748,14 +748,26 @@ Connect Claude CLI: `claude mcp add --transport http my-api http://localhost:300
 **Auth** — three modes, user chooses: `false` | `getAuth()` (Better Auth OAuth 2.1) | custom function:
 
 ```typescript
+// Human user auth
 auth: async (headers) => {
   if (headers['x-api-key'] !== process.env.MCP_KEY) return null;
   return { userId: 'bot', organizationId: 'org-1', roles: ['admin'] };
 },
+
+// Service account / machine-to-machine (produces kind: "service" scope)
+auth: async (headers) => ({
+  clientId: 'ingestion-pipeline',
+  organizationId: 'org-1',
+  scopes: ['read:products', 'write:events'],
+}),
 ```
 
+`auth: false` → `ctx.user` is `null`, `scope.kind` is `"public"`. Permission guards like `!!ctx.user` correctly block anonymous callers.
+
 **Guards** for custom tools: `guard(requireAuth, requireOrg, requireRole('admin'), handler)`
 
+**Service scope**: When `clientId` is set in auth result, MCP produces `kind: "service"` RequestScope — works with `requireServiceScope()`, `getClientId()`, `getServiceScopes()`. No synthetic userId needed for machine principals.
+
 **Multi-tenancy**: `organizationId` from auth flows into BaseController org-scoping automatically.
 
 **Permission filters**: `PermissionResult.filters` from resource permissions flow into MCP tools — same as REST. Define once, works everywhere:
@@ -881,6 +893,55 @@ additionalRoutes: [{ preAuth: [(req) => { req.headers.authorization = `Bearer ${
 additionalRoutes: [{ streamResponse: true, handler: async (req, reply) => reply.send(stream) }]
 ```
 
+## DX Helpers (v2.7.3)
+
+**Reply helpers** — consistent response envelopes (opt-in via `createApp({ replyHelpers: true })`):
+
+```typescript
+return reply.ok({ name: 'MacBook' });              // → 200 { success: true, data: {...} }
+return reply.ok(product, 201);                      // → 201 { success: true, data: {...} }
+return reply.fail('Not found', 404);                // → 404 { success: false, error: '...' }
+return reply.fail(['err1', 'err2'], 422);           // → 422 { success: false, errors: [...] }
+return reply.paginated({ docs, total, page, limit });
+return reply.stream(csvReadable, { contentType: 'text/csv', filename: 'export.csv' });
+```
+
+**Error mappers** — class-based domain error → HTTP response (in `errorHandler` options):
+
+```typescript
+const app = await createApp({
+  errorHandler: {
+    errorMappers: [{
+      type: AccountingError,
+      toResponse: (err) => ({ status: err.status, code: err.code, message: err.message }),
+    }],
+  },
+});
+// Handlers just throw — Arc catches and maps automatically
+```
+
+**BigInt serialization** — opt-in via `createApp({ serializeBigInt: true })`. Converts BigInt → Number in all JSON responses.
+
+**Multipart body middleware** — opt-in file upload for CRUD routes:
+
+```typescript
+import { multipartBody } from '@classytic/arc/middleware';
+
+defineResource({
+  name: 'product',
+  adapter,
+  middlewares: { create: [multipartBody({ allowedMimeTypes: ['image/png', 'image/jpeg'], maxFileSize: 5 * 1024 * 1024 })] },
+  hooks: {
+    'before:create': async (data) => {
+      if (data._files?.image) { data.imageUrl = await uploadToS3(data._files.image); delete data._files; }
+      return data;
+    },
+  },
+});
+```
+
+`multipartBody()` is a no-op for JSON requests — safe to always add.
+
 ## Subpath Imports
 
 ```typescript

package/skills/arc/references/integrations.md

@@ -297,7 +297,7 @@ All optional, gracefully degrade:
 import { webhookPlugin } from '@classytic/arc/integrations/webhooks';
 ```
 
-Fastify plugin that auto-dispatches Arc events to customer webhook endpoints with HMAC-SHA256 signing, delivery logging, and pluggable persistence.
+Fastify plugin that auto-dispatches Arc events to customer webhook endpoints with HMAC-SHA256 signing, delivery logging, bounded concurrency, and pluggable persistence.
 
 ### Setup
 
@@ -309,6 +309,7 @@ await fastify.register(webhookPlugin, {
   store: myMongoWebhookStore,  // implements WebhookStore { getAll, save, remove }
   timeout: 5000,               // delivery timeout (default: 10000ms)
   maxLogEntries: 500,          // ring buffer cap (default: 1000)
+  concurrency: 10,             // max parallel deliveries per event (default: 5)
 });
 ```
 
@@ -338,21 +339,45 @@ await app.events.publish('order.created', { orderId: '123' });
 //   Body: { type, payload, meta }
 ```
 
-### HMAC Signing
+Deliveries run with bounded concurrency (default: 5) — one slow endpoint won't block the rest. Set `concurrency: 1` for sequential delivery.
 
-Every delivery is signed with the subscription's secret using HMAC-SHA256:
+### HMAC Signing & Verification
+
+**Outbound** — every delivery is signed with the subscription's secret:
 
 ```
 x-webhook-signature: sha256=a1b2c3...
 ```
 
-Verify on the receiving end:
+**Inbound** — verify with `verifySignature()` (timing-safe, never throws):
+
+```typescript
+import { verifySignature } from '@classytic/arc/integrations/webhooks';
+
+fastify.post('/webhooks/incoming', async (req, reply) => {
+  const sig = req.headers['x-webhook-signature'] as string;
+  if (!verifySignature(req.rawBody, secret, sig)) {
+    return reply.status(401).send({ error: 'Invalid signature' });
+  }
+  // handle event via req.headers['x-webhook-event']
+});
+```
+
+Accepts `string | Buffer` body, `string | undefined` signature. Configurable for non-Arc senders:
+
 ```typescript
-import { createHmac } from 'node:crypto';
-const expected = 'sha256=' + createHmac('sha256', secret).update(rawBody).digest('hex');
-if (expected !== req.headers['x-webhook-signature']) throw new Error('Invalid signature');
+// GitHub (same prefix, same algorithm — works with defaults)
+verifySignature(body, secret, req.headers['x-hub-signature-256']);
+
+// Custom algorithm / bare hex
+verifySignature(body, secret, req.headers['x-custom-sig'], {
+  prefix: '',           // bare hex, no prefix
+  algorithm: 'sha512',  // non-default algorithm
+});
 ```
 
+**Note:** `req.rawBody` requires `fastify-raw-body` — JSON re-serialization breaks HMAC since field ordering differs.
+
 ### Delivery Log
 
 ```typescript

package/skills/arc/references/mcp.md

@@ -139,7 +139,7 @@ Arc doesn't enforce an auth strategy. You choose what fits.
 await app.register(mcpPlugin, { resources, auth: false });
 ```
 
-All tools open. Every request gets `{ userId: 'anonymous' }`.
+All tools open. `ctx.user` is `null`, `scope.kind` is `"public"`. Permission guards like `!!ctx.user` correctly block — anonymous callers cannot bypass auth checks.
 
 ### 2. Better Auth OAuth 2.1 (production SaaS)
 
@@ -175,13 +175,27 @@ type McpAuthResolver = (headers: Record<string, string | undefined>) =>
   Promise<McpAuthResult | null> | McpAuthResult | null;
 ```
 
-Return `{ userId, organizationId? }` to allow. Return `null` to reject (401).
+Return `McpAuthResult` to allow. Return `null` to reject (401).
+
+**`McpAuthResult` fields:**
+- `userId?` — human user ID (optional for machine principals)
+- `organizationId?` — org scope
+- `roles?` / `orgRoles?` — user roles
+- `clientId?` — set this to produce `kind: "service"` scope (machine-to-machine)
+- `scopes?` — OAuth scopes for service accounts
 
 ```typescript
-// API key
+// Human user — API key
 auth: async (headers) => {
   if (headers['x-api-key'] !== process.env.MCP_API_KEY) return null;
-  return { userId: 'service', organizationId: 'org-123' };
+  return { userId: 'alice', organizationId: 'org-123', roles: ['admin'] };
+},
+
+// Machine principal — service account (no userId needed)
+auth: async (headers) => {
+  const key = headers['x-service-key'];
+  if (key !== process.env.SVC_KEY) return null;
+  return { clientId: 'ingestion-pipeline', organizationId: 'org-123', scopes: ['write:events'] };
 },
 
 // Gateway-validated JWT (token already verified upstream)
@@ -191,9 +205,6 @@ auth: async (headers) => {
   return userId ? { userId, organizationId: orgId } : null;
 },
 
-// Static org (trusted internal network)
-auth: async () => ({ userId: 'internal', organizationId: 'org-main' }),
-
 // Bearer token with custom validation
 auth: async (headers) => {
   const token = headers['authorization']?.replace('Bearer ', '');
@@ -203,6 +214,19 @@ auth: async (headers) => {
 },
 ```
 
+### Service Scope (machine-to-machine)
+
+When `clientId` is present in the auth result, Arc produces `kind: "service"` RequestScope:
+
+```
+auth resolver returns { clientId: 'pipeline-v2', organizationId: 'org-a', scopes: ['read:all'] }
+  → buildRequestContext sets _scope: { kind: 'service', clientId: 'pipeline-v2', organizationId: 'org-a', scopes: ['read:all'] }
+  → ctx.user is null (machine principals don't masquerade as users)
+  → isService(scope), getClientId(scope), getServiceScopes(scope) all work
+```
+
+When `userId` is present (without `clientId`), Arc produces `kind: "member"` or `kind: "authenticated"` as before.
+
 ### Multi-Tenancy
 
 The `organizationId` from auth flows into BaseController's org-scoping automatically:

package/skills/arc/references/production.md

@@ -267,6 +267,75 @@ import { errorHandlerPlugin } from '@classytic/arc/plugins';
 // Auto-registered by createApp()
 ```
 
+### Error Mappers (v2.7.3)
+
+Class-based domain error → HTTP response mapping. Register once, handlers just throw:
+
+```typescript
+class AccountingError extends Error {
+  constructor(message: string, public status: number, public code: string) { super(message); }
+}
+
+const app = await createApp({
+  errorHandler: {
+    errorMappers: [{
+      type: AccountingError,
+      toResponse: (err) => ({ status: err.status, code: err.code, message: err.message }),
+    }],
+  },
+});
+// Now handlers just throw — Arc catches and maps automatically
+```
+
+Mappers are checked via `instanceof` before all other error classification. Multiple mappers supported — first match wins.
+
+## Reply Helpers (v2.7.3)
+
+Opt-in response envelope decorators: `createApp({ replyHelpers: true })`
+
+```typescript
+return reply.ok({ name: 'MacBook' });              // → 200 { success: true, data: {...} }
+return reply.ok(product, 201);                      // → 201 { success: true, data: {...} }
+return reply.fail('Not found', 404);                // → 404 { success: false, error: '...' }
+return reply.fail(['err1', 'err2'], 422);           // → 422 { success: false, errors: [...] }
+return reply.paginated({ docs, total, page, limit });
+```
+
+### Streaming Responses
+
+```typescript
+// CSV export
+return reply.stream(csvReadableStream, { contentType: 'text/csv', filename: 'export.csv' });
+// PDF download
+return reply.stream(pdfBuffer, { contentType: 'application/pdf', filename: 'report.pdf' });
+// Raw stream (Fastify native — works without reply helpers too)
+return reply.header('content-type', 'text/csv').send(readableStream);
+```
+
+### BigInt Serialization
+
+Opt-in: `createApp({ serializeBigInt: true })` — auto-converts BigInt → Number in all JSON responses.
+
+## Multipart Body Middleware (v2.7.3)
+
+Opt-in file upload support for CRUD routes — parses multipart form fields into `req.body`, attaches files to `req.body._files`:
+
+```typescript
+import { multipartBody } from '@classytic/arc/middleware';
+
+defineResource({
+  middlewares: { create: [multipartBody({ allowedMimeTypes: ['image/png'], maxFileSize: 5_000_000 })] },
+  hooks: {
+    'before:create': async (data) => {
+      if (data._files?.image) { data.imageUrl = await uploadToS3(data._files.image); delete data._files; }
+      return data;
+    },
+  },
+});
+```
+
+No-op for JSON requests — safe to always add. Options: `maxFileSize`, `maxFiles`, `allowedMimeTypes`, `filesKey`.
+
 ## Migrations
 
 ```typescript