@classytic/arc 2.21.0 → 2.23.0

package/dist/{utils-CO8a3B_1.mjs → utils-CZyeRXTh.mjs}

@@ -1,75 +1,8 @@
 import { m as RESERVED_QUERY_PARAMS, t as CRUD_OPERATIONS } from "./constants-DNre0wRg.mjs";
 import { arcLog } from "./logger/index.mjs";
 import { t as ArcError } from "./errors-DkO8Nk6-.mjs";
-import { r as getAvailablePresets } from "./presets-gw0ciIUD.mjs";
+import { r as getAvailablePresets } from "./presets-BOe4Ugkl.mjs";
 import { errorContractSchema as errorContractSchema$1, errorDetailSchema as errorDetailSchema$1 } from "@classytic/repo-core/errors";
-//#region src/utils/simpleEqualityMatcher.ts
-/**
-* `simpleEqualityMatcher` — a minimal, dialect-agnostic flat-key equality
-* matcher for `DataAdapter.matchesFilter` / `BaseController({ matchesFilter })`.
-*
-* **What it does:** for each `[key, expected]` in the filter, compares
-* `item[key]` to `expected` via string coercion (so Mongo `ObjectId` values
-* match their string representation) and returns `true` only if every
-* filter entry matches. Array item values are matched implicitly (contains).
-*
-* **What it does NOT do:**
-* - No `$eq` / `$ne` / `$in` / `$nin` / `$gt` / `$lt` / `$regex` / `$exists`
-* - No `$and` / `$or`
-* - No dot-path traversal (`"owner.id"`)
-* - No schema-specific coercion
-*
-* **Why it exists:** 95%+ of arc's `_policyFilters` are produced by built-in
-* permission helpers and are shaped like `{ ownerId: "u1" }` or
-* `{ organizationId: "org_x" }` — flat equality. For that common shape,
-* this helper is a safe, tested, 15-line defense-in-depth matcher that
-* hosts using minimal repos (no `getOne(compoundFilter)` DB path) can opt
-* into without arc shipping a full Mongo-syntax engine.
-*
-* **When to use:**
-* - Your adapter/repo doesn't natively filter on `getOne(compoundFilter)`
-* - Your `_policyFilters` are flat equality (from arc's built-in permission helpers)
-* - You want defense-in-depth on `validateItemAccess` / `fetchDetailed`'s `getById` fallback
-*
-* **When NOT to use:**
-* - Your `_policyFilters` use operators (`$in`, `$ne`, etc.) — supply a
-*   native matcher (mongokit's repo does the filter at the DB layer; for
-*   custom repos, wrap the kit's own predicate engine).
-* - You're a mongokit / sqlitekit / Prisma user — the DB-level filter
-*   applied by `getOne(compoundFilter)` already covers this.
-*
-* @example
-* ```ts
-* import { simpleEqualityMatcher } from '@classytic/arc/utils';
-*
-* // On a custom adapter
-* const adapter: DataAdapter = {
-*   repository,
-*   type: 'custom',
-*   name: 'in-memory',
-*   matchesFilter: simpleEqualityMatcher,
-* };
-*
-* // Or directly on BaseController for ad-hoc controllers
-* new BaseController(repo, { matchesFilter: simpleEqualityMatcher });
-* ```
-*/
-function simpleEqualityMatcher(item, filters) {
-	if (!item || typeof item !== "object") return false;
-	const obj = item;
-	for (const [key, expected] of Object.entries(filters)) {
-		if (expected && typeof expected === "object" && !Array.isArray(expected) && Object.getPrototypeOf(expected) === Object.prototype && Object.keys(expected).some((k) => k.startsWith("$"))) return false;
-		const actual = obj[key];
-		if (Array.isArray(actual)) {
-			const expectedStr = String(expected);
-			if (!actual.some((v) => String(v) === expectedStr)) return false;
-			continue;
-		}
-		if (String(actual) !== String(expected)) return false;
-	}
-	return true;
-}
-//#endregion
 //#region src/core/validateResourceConfig.ts
 /**
 * Resource Configuration Validator
@@ -837,6 +770,25 @@ function handleRaw(handler, statusCode = 200) {
 	};
 }
 //#endregion
+//#region src/utils/headers.ts
+/**
+* Read a single header value. Lowercases the name (Node normalizes incoming
+* header names to lowercase) and returns the FIRST value when the header
+* was repeated.
+*
+* Duplicate policy: first-value is deterministic, but for security-sensitive
+* headers (authorization material, forwarded-for chains, content-length) a
+* duplicate usually signals smuggling or a broken proxy — consumers that
+* care should check `Array.isArray(headers[name])` and REJECT instead of
+* picking a winner.
+*/
+function getHeader(headers, name) {
+	if (!headers) return void 0;
+	const value = headers[name.toLowerCase()];
+	if (Array.isArray(value)) return value[0];
+	return value;
+}
+//#endregion
 //#region src/utils/queryParser.ts
 /**
 * Arc Query Parser - Default URL-to-Query Parser
@@ -1295,26 +1247,72 @@ const paginationSchema = {
 	]
 };
 /**
-* List response schema — full union of every wire shape `toCanonicalList`
-* can emit. Hosts who know their endpoint only ever produces one variant
-* can pin to a narrower helper:
+* List response schema — accepts every wire shape `toCanonicalList` can
+* emit. Hosts who know their endpoint only ever produces one variant can
+* pin to a narrower helper (sharper OpenAPI docs, same serializer speed):
 *   - `offsetListResponse(item)` — `{ method: 'offset', data, page, limit, total, pages, hasNext, hasPrev }`
 *   - `keysetListResponse(item)` — `{ method: 'keyset', data, limit, hasMore, next: string|null }`
 *   - `aggregateListResponse(item)` — `{ method: 'aggregate', ...offset fields }`
 *   - `bareListResponse(item)` — `{ data }`
 *
-* The default `listResponse(item)` is the union (`oneOf`) of all four so
-* Fastify validation accepts any canonical kit shape — pre-2.13 this only
-* modelled offset and rejected keyset/aggregate/bare lists at the
-* response-schema gate.
+* SHAPE: one merged permissive object, NOT a `oneOf` union (2.22). The
+* pre-2.22 union was semantically identical on the wire — every variant is
+* `additionalProperties: true` and the property definitions never conflict
+* (`next` only exists on keyset, the offset counters only on offset/
+* aggregate; fast-json-stringify skips undefined optionals) — but
+* fast-json-stringify implements top-level `oneOf` by running full AJV
+* validation PER RESPONSE to pick the branch, on the hottest route of
+* every arc app. The merge keeps the exact bytes (pinned by
+* `tests/utils/list-response-serialization.test.ts`) and drops the
+* per-response branch validation. Only `data` is required — the one field
+* all four variants share.
 */
 function listResponse(itemSchema) {
-	return { oneOf: [
-		offsetListResponse(itemSchema),
-		keysetListResponse(itemSchema),
-		aggregateListResponse(itemSchema),
-		bareListResponse(itemSchema)
-	] };
+	return {
+		type: "object",
+		properties: {
+			method: {
+				type: "string",
+				description: "Pagination method discriminant — 'offset' | 'keyset' | 'aggregate'; absent on bare lists.",
+				example: "offset"
+			},
+			data: {
+				type: "array",
+				items: itemSchema
+			},
+			page: {
+				type: "integer",
+				example: 1
+			},
+			limit: {
+				type: "integer",
+				example: 20
+			},
+			total: {
+				type: "integer",
+				example: 100
+			},
+			pages: {
+				type: "integer",
+				example: 5
+			},
+			hasNext: {
+				type: "boolean",
+				example: false
+			},
+			hasPrev: {
+				type: "boolean",
+				example: false
+			},
+			hasMore: { type: "boolean" },
+			next: {
+				type: ["string", "null"],
+				description: "Cursor token for the next page, or null."
+			}
+		},
+		required: ["data"],
+		additionalProperties: true
+	};
 }
 /** Offset variant — `{ method: 'offset', data, page, limit, total, pages, hasNext, hasPrev }`. */
 function offsetListResponse(itemSchema) {
@@ -1732,4 +1730,4 @@ function getUserId(user) {
 	return id ? String(id) : void 0;
 }
 //#endregion
-export { createCircuitBreaker as A, defineErrorMapper as C, CircuitBreakerError as D, CircuitBreaker as E, simpleEqualityMatcher as F, assertValidConfig as M, formatValidationErrors as N, CircuitBreakerRegistry as O, validateResourceConfig as P, defineGuard as S, withCompensation as T, ArcQueryParser as _, bareListResponse as a, MONGO_DIALECT as b, errorDetailSchema$1 as c, keysetListResponse as d, listResponse as f, responses as g, queryParams as h, aggregateListResponse as i, createCircuitBreakerRegistry as j, CircuitState as k, getDefaultCrudSchemas as l, paginationSchema as m, createStateMachine as n, deleteResponse as o, offsetListResponse as p, scheduleBackground as r, errorContractSchema$1 as s, getUserId as t, getListQueryParams as u, createQueryParser as v, defineCompensation as w, NEUTRAL_DIALECT as x, handleRaw as y };
+export { CircuitState as A, defineGuard as C, CircuitBreaker as D, withCompensation as E, validateResourceConfig as F, createCircuitBreakerRegistry as M, assertValidConfig as N, CircuitBreakerError as O, formatValidationErrors as P, NEUTRAL_DIALECT as S, defineCompensation as T, ArcQueryParser as _, bareListResponse as a, handleRaw as b, errorDetailSchema$1 as c, keysetListResponse as d, listResponse as f, responses as g, queryParams as h, aggregateListResponse as i, createCircuitBreaker as j, CircuitBreakerRegistry as k, getDefaultCrudSchemas as l, paginationSchema as m, createStateMachine as n, deleteResponse as o, offsetListResponse as p, scheduleBackground as r, errorContractSchema$1 as s, getUserId as t, getListQueryParams as u, createQueryParser as v, defineErrorMapper as w, MONGO_DIALECT as x, getHeader as y };

package/dist/{versioning-DQ4mCvg0.d.mts → versioning-D6PvCwpq.d.mts}

@@ -1,11 +1,6 @@
 import { n as DomainEvent } from "./EventTransport-QmY7A258.mjs";
 import { FastifyPluginAsync, FastifyRequest } from "fastify";
 //#region src/plugins/health.d.ts
-declare module "fastify" {
-  interface FastifyRequest {
-    _startTime?: number;
-  }
-}
 interface HealthCheck {
   /** Name of the dependency */
   name: string;
@@ -31,7 +26,7 @@ interface HealthOptions {
   collectHttpMetrics?: boolean;
 }
 declare const healthPlugin: FastifyPluginAsync<HealthOptions>;
-declare const _default$4: FastifyPluginAsync<HealthOptions>;
+declare const _default$5: FastifyPluginAsync<HealthOptions>;
 //#endregion
 //#region src/plugins/caching.d.ts
 interface CachingRule {
@@ -59,7 +54,7 @@ interface CachingOptions {
   rules?: CachingRule[];
 }
 declare const cachingPlugin: FastifyPluginAsync<CachingOptions>;
-declare const _default$3: FastifyPluginAsync<CachingOptions>;
+declare const _default$4: FastifyPluginAsync<CachingOptions>;
 //#endregion
 //#region src/plugins/sse.d.ts
 interface SSEOptions {
@@ -84,7 +79,46 @@ interface SSEOptions {
   tokenQueryParam?: string | null;
 }
 declare const ssePlugin: FastifyPluginAsync<SSEOptions>;
-declare const _default$2: FastifyPluginAsync<SSEOptions>;
+declare const _default$3: FastifyPluginAsync<SSEOptions>;
+//#endregion
+//#region src/plugins/realtime.d.ts
+declare const CHANGE_OPERATIONS: readonly ["created", "updated", "deleted"];
+type ChangeOperation = (typeof CHANGE_OPERATIONS)[number];
+interface RealtimeOptions {
+  /**
+   * Route path — must contain `:resource` (default: `/realtime/:resource`).
+   */
+  path?: string;
+  /** Heartbeat interval in ms (default: 30000). */
+  heartbeat?: number;
+  /**
+   * Subscribable resources. Default: every registered resource — safe
+   * because each subscription runs that resource's own `list` permission;
+   * narrow it when only some resources should have a change feed at all.
+   */
+  resources?: readonly string[];
+  /** Operations streamed (default: created + updated + deleted). */
+  operations?: readonly ChangeOperation[];
+  /**
+   * Query parameter carrying the bearer token for browser `EventSource`
+   * clients (default `'token'`, matching the sse plugin / arc-next).
+   * Set `null` to disable promotion.
+   */
+  tokenQueryParam?: string | null;
+  /**
+   * Hard ceiling (ms) on any single connection's lifetime. Bounds
+   * permission STALENESS: the row filters are snapshotted at connect, so a
+   * caller whose permissions are revoked mid-connection keeps receiving
+   * their old view until they reconnect. Independently, arc ALWAYS closes
+   * the feed when the auth token's `exp` passes (forcing reconnect +
+   * re-authorization with fresh filters) — this option adds a cap for
+   * session/cookie auth that carries no `exp`, or to tighten below the
+   * token TTL. Omit for token-exp-only bounding.
+   */
+  maxConnectionMs?: number;
+}
+declare const realtimePlugin: FastifyPluginAsync<RealtimeOptions>;
+declare const _default$2: FastifyPluginAsync<RealtimeOptions>;
 //#endregion
 //#region src/plugins/metrics.d.ts
 interface MetricsOptions {
@@ -153,4 +187,4 @@ declare module "fastify" {
 declare const versioningPlugin: FastifyPluginAsync<VersioningOptions>;
 declare const _default: FastifyPluginAsync<VersioningOptions>;
 //#endregion
-export { HealthOptions as _, MetricsCollector as a, metricsPlugin as c, ssePlugin as d, CachingOptions as f, HealthCheck as g, 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, _default$4 as v, healthPlugin as y };
+export { healthPlugin as C, _default$5 as S, CachingRule as _, MetricsCollector as a, HealthCheck as b, metricsPlugin as c, _default$2 as d, realtimePlugin as f, CachingOptions as g, ssePlugin as h, MetricEntry as i, ChangeOperation as l, _default$3 as m, _default as n, MetricsOptions as o, SSEOptions as p, versioningPlugin as r, _default$1 as s, VersioningOptions as t, RealtimeOptions as u, _default$4 as v, HealthOptions as x, cachingPlugin as y };

package/llms.txt

@@ -0,0 +1,39 @@
+# @classytic/arc
+
+> Resource-oriented backend framework for Fastify. One `defineResource()` call =
+> REST + validation + auth + permissions + events + caching + OpenAPI + MCP tools.
+> DB-agnostic via @classytic/repo-core adapter kits (mongokit, sqlitekit, prismakit).
+
+IMPORTANT for coding agents: hand-rolling is a bug in arc apps. Before writing any
+route, validation, pagination, auth check, cron, queue worker, counter, or audit
+code, check whether arc provides it — it almost certainly does:
+
+- CRUD routes            → defineResource({ name, adapter, permissions })
+- Role/ownership checks  → @classytic/arc/permissions (requireRoles, requireOwnership, permissionMatrix, requireQuota)
+- Identity/tenant access → @classytic/arc/scope (getUserId, requireOrgId — never read scope fields directly)
+- Body/response schemas  → schemaOptions.fieldRules (customSchemas when wire ≠ model)
+- Query filter/sort/page → the resource queryParser (allow-listed) + keyset cursors
+- Soft delete/slug/tree/bulk/files/search → presets: [...]
+- Recurring jobs         → schedulesPlugin (@classytic/arc/plugins; LockAdapter leader safety)
+- Durable queues         → @classytic/arc/integrations/jobs (BullMQ/Redis) or @classytic/streamline (Mongo)
+- Headless worker process→ createWorker(sameOptions) (@classytic/arc/factory)
+- Usage counters/quotas  → @classytic/arc/usage (usagePlugin, requireQuota) + rateLimit.plan
+- Audit + record history → audit: true, history: true on the resource
+- Idempotency            → @classytic/arc/idempotency
+- Events/outbox/webhooks → @classytic/arc/events, integrations/webhooks
+- AI/MCP tools           → generated from every resource (incl. _count/_exists/_distinct list verbs)
+- App boot               → createApp({ beforeBoot: connectDatabase, ... }) — DB connect goes IN beforeBoot
+
+## Docs (inside this package)
+
+- skills/arc/SKILL.md — full framework guide (boot, defineResource, presets, auth, testing)
+- skills/arc/references/api-reference.md — every subpath import
+- skills/arc-code-review/references/arc-cheatsheet.md — hand-rolled-code → arc-feature map
+- skills/arc-code-review/SKILL.md — audit workflow for existing codebases
+
+## Conventions that bite
+
+- request.user is undefined on public routes — guard it.
+- Custom endpoints go in the resource's routes:/actions: (inherit auth/OpenAPI/MCP);
+  bare fastify.get() bypasses everything.
+- mongokit >=3.21 defaults schemaGenerator; schemaGenerator: false kills OpenAPI+MCP bodies.