@classytic/arc 2.10.3 → 2.11.0

package/dist/testing/storageContract.d.mts

@@ -1,4 +1,4 @@
-import { t as Storage } from "../storage-CVk_SEn2.mjs";
+import { t as Storage } from "../storage-BwGQXUpd.mjs";
 
 //#region src/testing/storageContract.d.ts
 interface StorageContractSetupResult {

package/dist/{tracing-65B51Dw3.d.mts → tracing-DokiEsuz.d.mts}

@@ -1,4 +1,5 @@
 import { FastifyInstance, FastifyRequest } from "fastify";
+import { Span, Tracer } from "@opentelemetry/api";
 
 //#region src/plugins/tracing.d.ts
 interface TracingOptions {
@@ -28,8 +29,8 @@ interface TracingOptions {
   sampleRate?: number;
 }
 interface TracerContext {
-  tracer: any;
-  currentSpan: any;
+  tracer: Tracer;
+  currentSpan: Span;
 }
 declare module "fastify" {
   interface FastifyRequest {
@@ -53,7 +54,7 @@ declare function tracingPlugin(fastify: FastifyInstance, options?: TracingOption
  *   });
  * }
  */
-declare function createSpan<T>(request: FastifyRequest, name: string, fn: (span: any) => Promise<T>, attributes?: Record<string, any>): Promise<T>;
+declare function createSpan<T>(request: FastifyRequest, name: string, fn: (span: Span | null) => Promise<T>, attributes?: Record<string, string | number | boolean>): Promise<T>;
 /**
  * Decorator to automatically trace repository methods
  *
@@ -65,7 +66,11 @@ declare function createSpan<T>(request: FastifyRequest, name: string, fn: (span:
  *   }
  * }
  */
-declare function traced(spanName?: string): (target: any, propertyKey: string, descriptor: PropertyDescriptor) => PropertyDescriptor;
+declare function traced(spanName?: string): (target: {
+  constructor: {
+    name: string;
+  };
+}, propertyKey: string, descriptor: PropertyDescriptor) => PropertyDescriptor;
 /**
  * Check if OpenTelemetry is available
  */

package/dist/types/index.d.mts

@@ -1,5 +1,5 @@
-import { n as ElevationOptions, t as ElevationEvent } from "../elevation-C5SwtkAn.mjs";
-import { _ as isAuthenticated, c as getOrgRoles, g as hasOrgAccess, n as PUBLIC_SCOPE, p as getTeamId, r as RequestScope, s as getOrgId, t as AUTHENTICATED_SCOPE, v as isElevated, y as isMember } from "../types-BD85MlEK.mjs";
-import { c as PermissionCheck, d as UserBase, l as PermissionContext, u as PermissionResult } from "../fields-Lo1VUDpt.mjs";
-import { $ as CrudSchemas, A as AuthHelpers, B as FastifyWithDecorators, Bt as ArcInternalMetadata, C as ResourceMetadata, Ct as RouteHandler, D as HealthOptions, E as HealthCheck, F as TokenPair, Gt as PopulateOption, H as RequestWithExtras, Ht as LookupOption, I as ArcDecorator, J as ActionEntry, Jt as ServiceContext, Kt as QueryParserInterface, L as EventsDecorator, M as Authenticator, N as AuthenticatorContext, O as IntrospectionPluginOptions, P as JwtContext, Q as CrudRouteKey, R as FastifyRequestExtras, S as RegistryStats, St as IRequestContext, T as GracefulShutdownOptions, Ut as OwnershipCheck, V as MiddlewareHandler, Vt as ControllerQueryOptions, Wt as ParsedQuery, X as ActionsMap, Y as ActionHandlerFn, Z as CrudController, _ as ConfigError, _n as UserOrganization, _t as ControllerHandler, at as PresetHook, b as IntrospectionData, bt as IController, ct as ResourceCacheConfig, d as InferAdapterDoc, dn as AnyRecord, dt as ResourceHooks, et as EventDefinition, f as InferDocType, fn as ApiResponse, ft as ResourcePermissions, g as TypedResourceConfig, gn as UserLike, gt as RouteSchemaOptions, h as TypedRepository, hn as ObjectId, ht as RouteMethod, it as PresetFunction, j as AuthPluginOptions, k as RequestIdOptions, lt as ResourceConfig, m as TypedController, mn as JWTPayload, mt as RouteMcpConfig, nt as MiddlewareConfig, ot as PresetResult, p as InferResourceDoc, pn as ArcRequest, pt as RouteDefinition, q as ActionDefinition, qt as RequestContext, r as BaseControllerOptions, rt as OpenApiSchemas, st as RateLimitConfig, t as RouteHandlerMethod, tt as FieldRule, u as PaginationResult, ut as ResourceHookContext, v as ValidateOptions, vn as envelope, vt as ControllerLike, w as CrudRouterOptions, x as RegistryEntry, xt as IControllerResponse, y as ValidationResult, yn as getUserId, yt as FastifyHandler, z as FastifyWithAuth } from "../index-Cl0uoKd5.mjs";
-export { AUTHENTICATED_SCOPE, ActionDefinition, ActionEntry, ActionHandlerFn, ActionsMap, AnyRecord, ApiResponse, ArcDecorator, ArcInternalMetadata, ArcRequest, AuthHelpers, AuthPluginOptions, Authenticator, AuthenticatorContext, BaseControllerOptions, ConfigError, ControllerHandler, ControllerLike, ControllerQueryOptions, CrudController, CrudRouteKey, CrudRouterOptions, CrudSchemas, ElevationEvent, ElevationOptions, EventDefinition, EventsDecorator, FastifyHandler, FastifyRequestExtras, FastifyWithAuth, FastifyWithDecorators, FieldRule, GracefulShutdownOptions, HealthCheck, HealthOptions, IController, IControllerResponse, IRequestContext, InferAdapterDoc, InferDocType, InferResourceDoc, IntrospectionData, IntrospectionPluginOptions, JWTPayload, JwtContext, LookupOption, MiddlewareConfig, MiddlewareHandler, ObjectId, OpenApiSchemas, OwnershipCheck, PUBLIC_SCOPE, PaginationResult, ParsedQuery, PermissionCheck, PermissionContext, PermissionResult, PopulateOption, PresetFunction, PresetHook, PresetResult, QueryParserInterface, RateLimitConfig, RegistryEntry, RegistryStats, RequestContext, RequestIdOptions, RequestScope, RequestWithExtras, ResourceCacheConfig, ResourceConfig, ResourceHookContext, ResourceHooks, ResourceMetadata, ResourcePermissions, RouteDefinition, RouteHandler, RouteHandlerMethod, RouteMcpConfig, RouteMethod, RouteSchemaOptions, ServiceContext, TokenPair, TypedController, TypedRepository, TypedResourceConfig, UserBase, UserLike, UserOrganization, ValidateOptions, ValidationResult, envelope, getOrgId, getOrgRoles, getTeamId, getUserId, hasOrgAccess, isAuthenticated, isElevated, isMember };
+import { $ as OpenApiSchemas, A as RequestIdOptions, At as Authenticator, Bt as UserOrganization, C as RequestContext, D as HealthCheck, E as GracefulShutdownOptions, F as FastifyWithDecorators, Ft as ApiResponse, G as ActionsMap, H as ActionDefinition, I as MiddlewareHandler, It as ArcRequest, J as CrudRouteKey, K as ArcFieldRule, L as RequestWithExtras, Lt as JWTPayload, M as EventsDecorator, Mt as JwtContext, N as FastifyRequestExtras, Nt as TokenPair, O as HealthOptions, Ot as AuthHelpers, P as FastifyWithAuth, Pt as AnyRecord, Q as MiddlewareConfig, Rt as ObjectId, S as QueryParserInterface, T as CrudRouterOptions, U as ActionEntry, W as ActionHandlerFn, X as EventDefinition, Y as CrudSchemas, Z as FieldRule, _ as ControllerQueryOptions, _t as IControllerResponse, a as InferAdapterDoc, at as ResourceConfig, b as ParsedQuery, c as TypedController, ct as ResourcePermissions, d as PaginationResult, dt as RouteMethod, et as PresetFunction, f as IntrospectionData, ft as RouteSchemaOptions, g as ArcInternalMetadata, gt as IController, h as ResourceMetadata, ht as FastifyHandler, i as ValidationResult, it as ResourceCacheConfig, j as ArcDecorator, jt as AuthenticatorContext, k as IntrospectionPluginOptions, kt as AuthPluginOptions, l as TypedRepository, lt as RouteDefinition, m as RegistryStats, mt as ControllerLike, n as ConfigError, nt as PresetResult, o as InferDocType, ot as ResourceHookContext, p as RegistryEntry, pt as ControllerHandler, q as CrudController, r as ValidateOptions, rt as RateLimitConfig, s as InferResourceDoc, st as ResourceHooks, t as RouteHandlerMethod, tn as BaseControllerOptions, tt as PresetHook, u as TypedResourceConfig, ut as RouteMcpConfig, v as LookupOption, vt as IRequestContext, w as ServiceContext, x as PopulateOption, y as OwnershipCheck, yt as RouteHandler, zt as UserLike } from "../index-Cm0vUrr_.mjs";
+import { r as RequestScope } from "../types-tgR4Pt8F.mjs";
+import { c as PermissionCheck, d as UserBase, l as PermissionContext, u as PermissionResult } from "../fields-C8Y0XLAu.mjs";
+import { n as ElevationOptions, t as ElevationEvent } from "../elevation-s5ykdNHr.mjs";
+export { ActionDefinition, ActionEntry, ActionHandlerFn, ActionsMap, AnyRecord, ApiResponse, ArcDecorator, ArcFieldRule, ArcInternalMetadata, ArcRequest, AuthHelpers, AuthPluginOptions, Authenticator, AuthenticatorContext, BaseControllerOptions, ConfigError, ControllerHandler, ControllerLike, ControllerQueryOptions, CrudController, CrudRouteKey, CrudRouterOptions, CrudSchemas, ElevationEvent, ElevationOptions, EventDefinition, EventsDecorator, FastifyHandler, FastifyRequestExtras, FastifyWithAuth, FastifyWithDecorators, FieldRule, GracefulShutdownOptions, HealthCheck, HealthOptions, IController, IControllerResponse, IRequestContext, InferAdapterDoc, InferDocType, InferResourceDoc, IntrospectionData, IntrospectionPluginOptions, JWTPayload, JwtContext, LookupOption, MiddlewareConfig, MiddlewareHandler, ObjectId, OpenApiSchemas, OwnershipCheck, PaginationResult, ParsedQuery, PermissionCheck, PermissionContext, PermissionResult, PopulateOption, PresetFunction, PresetHook, PresetResult, QueryParserInterface, RateLimitConfig, RegistryEntry, RegistryStats, RequestContext, RequestIdOptions, RequestScope, RequestWithExtras, ResourceCacheConfig, ResourceConfig, ResourceHookContext, ResourceHooks, ResourceMetadata, ResourcePermissions, RouteDefinition, RouteHandler, RouteHandlerMethod, RouteMcpConfig, RouteMethod, RouteSchemaOptions, ServiceContext, TokenPair, TypedController, TypedRepository, TypedResourceConfig, UserBase, UserLike, UserOrganization, ValidateOptions, ValidationResult };

package/dist/types/index.mjs

@@ -1,3 +1 @@
-import { _ as isElevated, f as getTeamId, g as isAuthenticated, h as hasOrgAccess, n as PUBLIC_SCOPE, o as getOrgId, s as getOrgRoles, t as AUTHENTICATED_SCOPE, v as isMember } from "../types-AOD8fxIw.mjs";
-import { n as getUserId, t as envelope } from "../types-Csi3FLfq.mjs";
-export { AUTHENTICATED_SCOPE, PUBLIC_SCOPE, envelope, getOrgId, getOrgRoles, getTeamId, getUserId, hasOrgAccess, isAuthenticated, isElevated, isMember };
+export {};

package/dist/types/storage.d.mts

@@ -1,2 +1,2 @@
-import { a as StorageReadResult, i as StorageReadRange, n as StorageContext, o as StorageUploadInput, r as StorageFile, t as Storage } from "../storage-CVk_SEn2.mjs";
+import { a as StorageReadResult, i as StorageReadRange, n as StorageContext, o as StorageUploadInput, r as StorageFile, t as Storage } from "../storage-BwGQXUpd.mjs";
 export { Storage, StorageContext, StorageFile, StorageReadRange, StorageReadResult, StorageUploadInput };

package/dist/{types-Co8k3NyS.d.mts → types-CgikqKAj.d.mts}

@@ -1,12 +1,13 @@
-import { n as ElevationOptions } from "./elevation-C5SwtkAn.mjs";
-import { M as Authenticator } from "./index-Cl0uoKd5.mjs";
-import { o as EventTransport } from "./EventTransport-CUw5NNWe.mjs";
-import { t as ExternalOpenApiPaths } from "./externalPaths-BQ8QijNH.mjs";
-import { r as CacheStore } from "./interface-D218ikEo.mjs";
-import { r as QueryCachePluginOptions } from "./queryCachePlugin-BKbWjgDG.mjs";
-import { t as EventPluginOptions } from "./eventPlugin-CxWgpd6K.mjs";
-import { a as VersioningOptions, g as CachingOptions, p as SSEOptions, t as ErrorHandlerOptions, u as MetricsOptions } from "./errorHandler-DRQ3EqfL.mjs";
-import { r as IdempotencyStore } from "./interface-CSbZdv_3.mjs";
+import { At as Authenticator } from "./index-Cm0vUrr_.mjs";
+import { r as CacheStore } from "./interface-Da0r7Lna.mjs";
+import { n as ElevationOptions } from "./elevation-s5ykdNHr.mjs";
+import { o as EventTransport } from "./EventTransport-CfVEGaEl.mjs";
+import { t as ExternalOpenApiPaths } from "./externalPaths-Bapitwvd.mjs";
+import { r as QueryCachePluginOptions } from "./queryCachePlugin-BUXBSm4F.mjs";
+import { t as EventPluginOptions } from "./eventPlugin-CUNjYYRY.mjs";
+import { f as CachingOptions, l as SSEOptions, o as MetricsOptions, t as VersioningOptions } from "./versioning-M9lNLhO8.mjs";
+import { t as ErrorHandlerOptions } from "./errorHandler-Co3lnVmJ.mjs";
+import { r as IdempotencyStore } from "./interface-CkkWm5uR.mjs";
 import { FastifyInstance, FastifyPluginAsync, FastifyReply, FastifyRequest, FastifyServerOptions } from "fastify";
 
 //#region src/factory/loadResources.d.ts
@@ -149,6 +150,18 @@ type HelmetOptions = Record<string, unknown>;
 type RateLimitOpts = Record<string, unknown> & {
   max?: number;
   timeWindow?: string | number;
+  /**
+   * Path patterns to exempt from rate limiting. Supports exact match
+   * (`/health`) or prefix match with trailing `*` (`/api/auth/*`).
+   *
+   * Implemented by synthesising a `@fastify/rate-limit` `allowList`
+   * function. When combined with a user-supplied `allowList`, both
+   * are OR-ed together (path OR ip/custom match skips the limit).
+   *
+   * Use this for endpoints that are hit frequently but independently
+   * of user traffic — session heartbeat, webhooks, health probes.
+   */
+  skipPaths?: string[];
 };
 /**
  * Arc's built-in JWT auth
@@ -640,18 +653,70 @@ interface CreateAppOptions {
    */
   serializeBigInt?: boolean;
   /**
-   * Resources to register automatically.
-   * Each resource's `.toPlugin()` is called and registered for you.
+   * Resources to register automatically. Accepts two shapes:
    *
-   * @example
+   *   1. **Array** — each resource's `.toPlugin()` is called and registered.
+   *      Defined at module-import time, so the resource's adapter must be
+   *      constructible without any async state.
+   *
+   *   2. **Factory function** (sync or async) — called AFTER `bootstrap[]`
+   *      but BEFORE routes are wired. Use this when a resource's adapter
+   *      depends on an engine / singleton that boots asynchronously
+   *      (e.g. `await ensureCatalogEngine()` / `await createFlowEngine()`).
+   *      The factory receives the Fastify instance for symmetry with
+   *      `plugins` and `bootstrap`.
+   *
+   * Arc's lifecycle contract:
+   * ```
+   * 1. Arc core (security, auth, events)
+   * 2. plugins()            ← infra (DB, SSE, docs)
+   * 3. bootstrap[]          ← domain init (engines, singletons)
+   * 4. resources resolution ← (factory form: call it here)
+   * 5. resources registered ← plugins mounted on Fastify
+   * 6. afterResources()     ← post-registration wiring
+   * ```
+   *
+   * The factory form is the canonical answer to "my repository lives in an
+   * engine that boots asynchronously." Before this shape existed, hosts had
+   * to write per-resource lazy-bridge adapters that awaited the engine on
+   * every CRUD call — pure boilerplate. With a factory, `defineResource(...)`
+   * runs with the engine already live, so `createMongooseAdapter(engine.models.X, engine.repositories.X)`
+   * works directly.
+   *
+   * @example Static array (most resources)
    * ```ts
    * const app = await createApp({
    *   resources: [productResource, orderResource, userResource],
    *   auth: { type: 'jwt', jwt: { secret: 'xxx' } },
    * });
    * ```
+   *
+   * @example Factory with async-booted engine
+   * ```ts
+   * const app = await createApp({
+   *   bootstrap: [async () => { await ensureCatalogEngine(); }],
+   *   resources: async () => {
+   *     const cat = await ensureCatalogEngine();
+   *     return [
+   *       defineResource({
+   *         name: 'product',
+   *         adapter: createMongooseAdapter(cat.models.Product, cat.repositories.product),
+   *         // ...
+   *       }),
+   *     ];
+   *   },
+   * });
+   * ```
+   *
+   * @example Factory delegating to auto-discovery
+   * ```ts
+   * const app = await createApp({
+   *   bootstrap: [async () => { await ensureCatalogEngine(); }],
+   *   resources: async () => loadResources(import.meta.url),
+   * });
+   * ```
    */
-  resources?: Array<ResourceLike>;
+  resources?: ReadonlyArray<ResourceLike> | ((fastify: FastifyInstance) => ReadonlyArray<ResourceLike> | Promise<ReadonlyArray<ResourceLike>>);
   /**
    * URL prefix for all auto-registered resources.
    * Applied only to resources in the `resources` array — not to `plugins()`.
@@ -668,25 +733,72 @@ interface CreateAppOptions {
   resourcePrefix?: string;
   /**
    * Auto-discover resources from a directory instead of passing an explicit
-   * `resources` array. Resolves relative to `process.cwd()`.
+   * `resources` array.
    *
-   * This replaces the common pattern:
-   * ```ts
-   * resources: await loadResources(import.meta.url)
-   * ```
+   * Accepts either a filesystem path OR `import.meta.url` (a `file://` URL).
+   * **Prefer the URL form in production** — bare strings resolve relative to
+   * `process.cwd()`, which diverges from `dist/` at runtime and was the root
+   * cause of a reported "deployed app serves 404 on every route" incident.
    *
-   * When both `resourceDir` and `resources` are provided, `resources` wins
-   * (explicit always beats convention).
+   * When both `resourceDir` and `resources` are provided, `resources` wins —
+   * explicit always beats convention, **including an explicit empty array**.
+   * `resources: []` disables resource registration entirely even with
+   * `resourceDir` set, which is the common case for shared base configs
+   * that turn resource loading off in test / CLI / health-check subprocesses.
+   * Auto-discovery from `resourceDir` fires only when `resources` is
+   * `undefined` (absent).
    *
    * @example
    * ```ts
+   * // Recommended (v2.10.9+): URL form works in both src/ and dist/
    * const app = await createApp({
-   *   resourceDir: 'src/resources',
+   *   resourceDir: import.meta.url,
    *   resourcePrefix: '/api/v1',
    * });
+   *
+   * // String form — resolves against process.cwd(), mind the dist/ gap
+   * const app = await createApp({
+   *   resourceDir: 'src/resources',
+   * });
    * ```
    */
   resourceDir?: string;
+  /**
+   * Throw instead of silently booting with zero resources when `resourceDir`
+   * yields an empty result. Off by default to preserve back-compat — turning
+   * it on in production catches the "typoed path / stale dist/ layout"
+   * failure mode before the app accepts traffic.
+   *
+   * Only takes effect when `resourceDir` is set.
+   *
+   * @example
+   * ```ts
+   * await createApp({
+   *   resourceDir: import.meta.url,
+   *   strictResourceDir: process.env.NODE_ENV === 'production',
+   * });
+   * ```
+   *
+   * @default false
+   */
+  strictResourceDir?: boolean;
+  /**
+   * Throw instead of warn when two resources share the same `name`. Off by
+   * default to preserve back-compat; turn on in production to catch stale
+   * `dist/` files (a common source of `Mongoose model already exists`
+   * collisions downstream of arc's own registry).
+   *
+   * @example
+   * ```ts
+   * await createApp({
+   *   resources: await loadResources(import.meta.url),
+   *   strictResources: process.env.NODE_ENV === 'production',
+   * });
+   * ```
+   *
+   * @default false
+   */
+  strictResources?: boolean;
   /**
    * Custom plugin registration — runs after Arc core (security, auth, events)
    * but before `bootstrap` and `resources`.

package/dist/{types-Btdda02s.d.mts → types-D9NqiYIw.d.mts}

@@ -1,4 +1,4 @@
-import { G as ResourceDefinition } from "./index-Cl0uoKd5.mjs";
+import { B as ResourceDefinition } from "./index-Cm0vUrr_.mjs";
 import { z } from "zod";
 
 //#region src/integrations/mcp/types.d.ts