@classytic/arc 2.10.3 → 2.11.0

package/dist/versioning-M9lNLhO8.d.mts

@@ -0,0 +1,117 @@
+import { n as DomainEvent } from "./EventTransport-CfVEGaEl.mjs";
+import { FastifyPluginAsync, FastifyRequest } from "fastify";
+
+//#region src/plugins/caching.d.ts
+interface CachingRule {
+  /** Path prefix to match (e.g., '/api/products') */
+  match: string;
+  /** Cache-Control max-age in seconds */
+  maxAge: number;
+  /** Cache-Control: private vs public (default: public) */
+  private?: boolean;
+  /** stale-while-revalidate directive in seconds */
+  staleWhileRevalidate?: number;
+}
+interface CachingOptions {
+  /** Default max-age in seconds for Cache-Control (default: 0 = no-cache) */
+  maxAge?: number;
+  /** Enable ETag generation (default: true) */
+  etag?: boolean;
+  /** Enable conditional requests — 304 Not Modified (default: true) */
+  conditional?: boolean;
+  /** HTTP methods to cache (default: ['GET', 'HEAD']) */
+  methods?: string[];
+  /** Paths to exclude from caching (prefix match) */
+  exclude?: string[];
+  /** Custom cache rules per path prefix */
+  rules?: CachingRule[];
+}
+declare const cachingPlugin: FastifyPluginAsync<CachingOptions>;
+declare const _default$3: FastifyPluginAsync<CachingOptions>;
+//#endregion
+//#region src/plugins/sse.d.ts
+interface SSEOptions {
+  /** SSE endpoint path (default: '/events/stream') */
+  path?: string;
+  /** Require authentication (default: true) */
+  requireAuth?: boolean;
+  /** Event patterns to stream (default: ['*'] = all) */
+  patterns?: string[];
+  /** Heartbeat interval in ms (default: 30000) */
+  heartbeat?: number;
+  /** Filter events by organizationId from request.scope (default: false) */
+  orgScoped?: boolean;
+  /** Custom event filter function */
+  filter?: (event: DomainEvent<unknown>, request: FastifyRequest) => boolean;
+}
+declare const ssePlugin: FastifyPluginAsync<SSEOptions>;
+declare const _default$2: FastifyPluginAsync<SSEOptions>;
+//#endregion
+//#region src/plugins/metrics.d.ts
+interface MetricsOptions {
+  /** Endpoint path (default: '/_metrics') */
+  path?: string;
+  /** Prefix for all metric names (default: 'arc') */
+  prefix?: string;
+  /** Called after metrics are collected (for OTLP push, etc.) */
+  onCollect?: (metrics: MetricEntry[]) => void;
+}
+interface MetricEntry {
+  name: string;
+  type: "counter" | "histogram" | "gauge";
+  help: string;
+  values: Array<{
+    labels: Record<string, string>;
+    value: number;
+  }>;
+}
+interface MetricsCollector {
+  /** Get all metrics as structured data */
+  collect(): MetricEntry[];
+  /** Reset all metrics */
+  reset(): void;
+  /** Record a CRUD operation */
+  recordOperation(resource: string, operation: string, status: number, durationMs: number): void;
+  /** Record a cache hit */
+  recordCacheHit(resource: string): void;
+  /** Record a cache miss */
+  recordCacheMiss(resource: string): void;
+  /** Record an event publish */
+  recordEventPublish(eventType: string): void;
+  /** Record an event consume */
+  recordEventConsume(eventType: string): void;
+  /** Record a circuit breaker state change */
+  recordCircuitBreakerState(service: string, state: string): void;
+}
+declare module "fastify" {
+  interface FastifyInstance {
+    metrics: MetricsCollector;
+  }
+}
+declare const metricsPlugin: FastifyPluginAsync<MetricsOptions>;
+declare const _default$1: FastifyPluginAsync<MetricsOptions>;
+//#endregion
+//#region src/plugins/versioning.d.ts
+interface VersioningOptions {
+  /** Versioning strategy */
+  type: "header" | "prefix";
+  /** Default version when none specified (default: '1') */
+  defaultVersion?: string;
+  /** Header name to read (default: 'accept-version') */
+  headerName?: string;
+  /** Response header name (default: 'x-api-version') */
+  responseHeader?: string;
+  /** Deprecated versions — adds Deprecation + Sunset headers */
+  deprecated?: string[];
+  /** Sunset date for deprecated versions (ISO 8601) */
+  sunset?: string;
+}
+declare module "fastify" {
+  interface FastifyRequest {
+    apiVersion: string;
+  }
+}
+declare const versioningPlugin: FastifyPluginAsync<VersioningOptions>;
+declare const _default: FastifyPluginAsync<VersioningOptions>;
+//#endregion
+export { MetricsCollector as a, metricsPlugin as c, ssePlugin as d, CachingOptions as f, cachingPlugin as h, MetricEntry as i, SSEOptions as l, _default$3 as m, _default as n, MetricsOptions as o, CachingRule as p, versioningPlugin as r, _default$1 as s, VersioningOptions as t, _default$2 as u };

package/dist/websocket-CyJ1VIFI.d.mts

@@ -0,0 +1,186 @@
+import { FastifyPluginAsync } from "fastify";
+
+//#region src/integrations/websocket/adapter.d.ts
+/**
+ * WebSocket cross-instance adapter contract.
+ *
+ * The adapter is NOT used for local broadcasts — `RoomManager` handles those.
+ * The adapter only handles the cross-instance relay (Redis pub/sub, NATS, etc.)
+ * so a message broadcast on instance A is also delivered to clients connected
+ * to instance B.
+ *
+ * Implementations:
+ *   - `LocalWebSocketAdapter` (here) — no-op, single-instance only
+ *   - `RedisWebSocketAdapter` (@classytic/arc/integrations/websocket-redis)
+ *
+ * Custom adapters just need to satisfy the interface.
+ */
+/**
+ * Adapter interface for cross-instance WebSocket broadcast.
+ *
+ * - `publish()`: Send a message to all instances (via Redis, NATS, etc.)
+ * - `subscribe()`: Receive messages from other instances
+ * - `close()`: Clean up connections
+ */
+interface WebSocketAdapter {
+  /** Adapter name for logging */
+  readonly name: string;
+  /** Publish a room broadcast to all other instances */
+  publish(room: string, message: string): Promise<void>;
+  /** Subscribe to broadcasts from other instances */
+  subscribe(callback: (room: string, message: string) => void): Promise<void>;
+  /** Close adapter connections */
+  close(): Promise<void>;
+}
+/**
+ * Default adapter — no cross-instance broadcast (single-instance only).
+ * All methods are no-ops. Used when no adapter is configured.
+ */
+declare class LocalWebSocketAdapter implements WebSocketAdapter {
+  readonly name = "local";
+  publish(): Promise<void>;
+  subscribe(): Promise<void>;
+  close(): Promise<void>;
+}
+//#endregion
+//#region src/integrations/websocket/types.d.ts
+/**
+ * A connected WebSocket client — one entry per TCP socket.
+ *
+ * `subscriptions` is mutated by `RoomManager`; other fields are set once at
+ * handshake time and treated as effectively immutable for the lifetime of
+ * the connection.
+ */
+interface WebSocketClient {
+  id: string;
+  socket: {
+    send(data: string): void;
+    close(): void;
+    readyState: number;
+  };
+  subscriptions: Set<string>;
+  userId?: string;
+  organizationId?: string;
+  /** OAuth client ID — present for service/machine-to-machine connections */
+  clientId?: string;
+  /** OAuth scopes — present for service/machine-to-machine connections */
+  scopes?: readonly string[];
+  metadata?: Record<string, unknown>;
+}
+interface WebSocketMessage {
+  type: string;
+  resource?: string;
+  channel?: string;
+  data?: unknown;
+}
+/**
+ * Result of a successful authentication. The plugin's handshake and the
+ * optional re-auth loop both return this shape so the downstream code
+ * doesn't branch on auth mode. `null` means rejected.
+ */
+interface AuthResult {
+  userId?: string;
+  organizationId?: string;
+  /** Set for machine-to-machine / service account auth */
+  clientId?: string;
+  /** OAuth scopes for service accounts */
+  scopes?: readonly string[];
+}
+interface WebSocketPluginOptions {
+  /** WebSocket endpoint path (default: '/ws') */
+  path?: string;
+  /** Require authentication for WebSocket connections (default: true) */
+  auth?: boolean;
+  /** Resources to auto-broadcast CRUD events for */
+  resources?: string[];
+  /** Heartbeat interval in ms (default: 30000). Set 0 to disable. */
+  heartbeatInterval?: number;
+  /** Custom authentication function for WebSocket upgrade */
+  authenticate?: (request: unknown) => Promise<AuthResult | null>;
+  /** Max clients per resource subscription (default: 10000) */
+  maxClientsPerRoom?: number;
+  /**
+   * Expose a stats endpoint at `{path}/stats`.
+   * - `false` (default): stats endpoint is not registered
+   * - `true`: registered without auth
+   * - `'authenticated'`: guarded by `fastify.authenticate` if available
+   */
+  exposeStats?: boolean | "authenticated";
+  /**
+   * Authorize room subscriptions. Return true to allow, false to deny.
+   * Called before every subscribe. If not provided, all rooms are allowed.
+   */
+  roomPolicy?: (client: WebSocketClient, room: string) => boolean | Promise<boolean>;
+  /** Maximum message size in bytes from client (default: 16384 = 16KB). Messages exceeding this are dropped. */
+  maxMessageBytes?: number;
+  /** Maximum subscriptions per client (default: 100). Prevents resource exhaustion. */
+  maxSubscriptionsPerClient?: number;
+  /**
+   * Periodic re-authentication interval in ms (default: 0 = disabled).
+   * When set, the server periodically re-validates the client's auth token.
+   * If the token is expired/revoked, the client is disconnected with code 4003.
+   *
+   * Recommended: 300000 (5 minutes) for production.
+   *
+   * @example
+   * ```typescript
+   * websocketPlugin({ reauthInterval: 5 * 60 * 1000 }) // re-check every 5 min
+   * ```
+   */
+  reauthInterval?: number;
+  /** Custom message handler */
+  onMessage?: (client: WebSocketClient, message: WebSocketMessage) => void | Promise<void>;
+  /** Called when a client connects */
+  onConnect?: (client: WebSocketClient) => void | Promise<void>;
+  /** Called when a client disconnects */
+  onDisconnect?: (client: WebSocketClient) => void | Promise<void>;
+  /**
+   * Cross-instance broadcast adapter (default: LocalWebSocketAdapter — single-instance only).
+   * Provide a RedisWebSocketAdapter for multi-instance deployments.
+   *
+   * @example
+   * ```typescript
+   * import { RedisWebSocketAdapter } from '@classytic/arc/integrations/websocket-redis';
+   * adapter: new RedisWebSocketAdapter(redis, { channel: 'arc-ws' })
+   * ```
+   */
+  adapter?: WebSocketAdapter;
+}
+//#endregion
+//#region src/integrations/websocket/plugin.d.ts
+/** Pluggable WebSocket integration for Arc */
+declare const websocketPlugin: FastifyPluginAsync<WebSocketPluginOptions>;
+//#endregion
+//#region src/integrations/websocket/room-manager.d.ts
+declare class RoomManager {
+  private rooms;
+  private clients;
+  private maxPerRoom;
+  private adapter?;
+  constructor(maxPerRoom?: number, adapter?: WebSocketAdapter);
+  addClient(client: WebSocketClient): void;
+  removeClient(clientId: string): void;
+  subscribe(clientId: string, room: string): boolean;
+  unsubscribe(clientId: string, room: string): void;
+  broadcast(room: string, message: string, excludeClientId?: string): void;
+  broadcastToOrg(organizationId: string, room: string, message: string): void;
+  /**
+   * Broadcast locally AND through adapter (for cross-instance delivery).
+   * Use this instead of broadcast() when multi-instance is possible.
+   */
+  broadcastWithAdapter(room: string, message: string, excludeClientId?: string): Promise<void>;
+  /**
+   * Org-scoped broadcast locally AND through adapter.
+   * Uses a namespaced room key for the adapter so other instances
+   * can filter by org when delivering locally.
+   */
+  broadcastToOrgWithAdapter(organizationId: string, room: string, message: string): Promise<void>;
+  getClient(clientId: string): WebSocketClient | undefined;
+  getStats(): {
+    clients: number;
+    rooms: number;
+    subscriptions: Record<string, number>;
+  };
+}
+//#endregion
+export { WebSocketMessage as a, WebSocketAdapter as c, WebSocketClient as i, websocketPlugin as n, WebSocketPluginOptions as o, AuthResult as r, LocalWebSocketAdapter as s, RoomManager as t };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@classytic/arc",
-  "version": "2.10.3",
+  "version": "2.11.0",
   "description": "Resource-oriented backend framework for Fastify — clean, minimal, powerful, tree-shakable",
   "type": "module",
   "exports": {
@@ -64,6 +64,22 @@
       "types": "./dist/hooks/index.d.mts",
       "default": "./dist/hooks/index.mjs"
     },
+    "./middleware": {
+      "types": "./dist/middleware/index.d.mts",
+      "default": "./dist/middleware/index.mjs"
+    },
+    "./pipeline": {
+      "types": "./dist/pipeline/index.d.mts",
+      "default": "./dist/pipeline/index.mjs"
+    },
+    "./context": {
+      "types": "./dist/context/index.d.mts",
+      "default": "./dist/context/index.mjs"
+    },
+    "./logger": {
+      "types": "./dist/logger/index.d.mts",
+      "default": "./dist/logger/index.mjs"
+    },
     "./registry": {
       "types": "./dist/registry/index.d.mts",
       "default": "./dist/registry/index.mjs"
@@ -217,15 +233,16 @@
     "test:e2e": "vitest run tests/e2e",
     "test:unit": "vitest run tests/core tests/hooks tests/utils tests/plugins",
     "smoke": "node scripts/smoke-test.mjs",
+    "push": "classytic-push",
     "prepublishOnly": "npm run typecheck && npm run lint && npm run build && npm run test:ci && npm run smoke"
   },
   "engines": {
     "node": ">=22"
   },
   "peerDependencies": {
-    "@classytic/mongokit": ">=3.10.2",
-    "@classytic/repo-core": ">=0.1.0",
-    "@classytic/streamline": ">=2.1.0",
+    "@classytic/mongokit": ">=3.11.1",
+    "@classytic/repo-core": ">=0.2.0",
+    "@classytic/streamline": ">=2.2.0",
     "@fastify/cors": ">=11.0.0",
     "@fastify/helmet": ">=13.0.0",
     "@fastify/jwt": ">=10.0.0",
@@ -347,10 +364,11 @@
     "@better-auth/drizzle-adapter": "^1.6.2",
     "@better-auth/mongo-adapter": "^1.6.2",
     "@biomejs/biome": "^2.4.11",
-    "@classytic/mongokit": "^3.10.2",
-    "@classytic/repo-core": "^0.1.0",
-    "@classytic/sqlitekit": "^0.1.0",
-    "@classytic/streamline": "^2.1.0",
+    "@classytic/dev-tools": "^0.2.0",
+    "@classytic/mongokit": "^3.11.1",
+    "@classytic/repo-core": "^0.2.0",
+    "@classytic/sqlitekit": "^0.2.0",
+    "@classytic/streamline": "^2.2.0",
     "@fastify/cors": "^11.2.0",
     "@fastify/helmet": "^13.0.2",
     "@fastify/jwt": "^10.0.0",