@classytic/arc 2.8.4 → 2.9.1

package/dist/idempotency/redis.mjs

@@ -77,18 +77,24 @@ var RedisIdempotencyStore = class {
 	}
 	async findByPrefix(prefix) {
 		const keys = await this.scanByPrefix(this.resultKey(prefix));
-		for (const key of keys) {
-			const data = await this.client.get(key);
-			if (!data) continue;
-			try {
-				const result = JSON.parse(data);
-				if (new Date(result.expiresAt) < /* @__PURE__ */ new Date()) continue;
-				return {
-					...result,
-					createdAt: new Date(result.createdAt),
-					expiresAt: new Date(result.expiresAt)
-				};
-			} catch {}
+		if (keys.length === 0) return void 0;
+		const BATCH_SIZE = 10;
+		const now = /* @__PURE__ */ new Date();
+		for (let i = 0; i < keys.length; i += BATCH_SIZE) {
+			const batch = keys.slice(i, i + BATCH_SIZE);
+			const values = await Promise.all(batch.map((k) => this.client.get(k)));
+			for (const data of values) {
+				if (!data) continue;
+				try {
+					const result = JSON.parse(data);
+					if (new Date(result.expiresAt) < now) continue;
+					return {
+						...result,
+						createdAt: new Date(result.createdAt),
+						expiresAt: new Date(result.expiresAt)
+					};
+				} catch {}
+			}
 		}
 	}
 	/** Scan Redis keys matching a prefix pattern. Falls back to empty if SCAN unavailable. */
@@ -105,5 +111,120 @@ var RedisIdempotencyStore = class {
 	}
 	async close() {}
 };
+/**
+* Wrap an ioredis instance as the arc idempotency `RedisClient`.
+*
+* Arc's idempotency store expects node-redis-v4 style option objects
+* (`{ EX, NX }`). ioredis uses positional flags. This adapter lets users
+* plug an ioredis instance in without writing the bridge themselves.
+*
+* @example
+* ```typescript
+* import Redis from 'ioredis';
+* import { RedisIdempotencyStore, ioredisAsIdempotencyClient }
+*   from '@classytic/arc/idempotency/redis';
+*
+* const redis = new Redis(process.env.REDIS_URL);
+* const store = new RedisIdempotencyStore({
+*   client: ioredisAsIdempotencyClient(redis),
+* });
+* ```
+*/
+function ioredisAsIdempotencyClient(client) {
+	return {
+		async get(key) {
+			return client.get(key);
+		},
+		async set(key, value, options) {
+			const args = [key, value];
+			if (options?.EX != null) args.push("EX", options.EX);
+			if (options?.NX) args.push("NX");
+			return client.set(...args);
+		},
+		async del(key) {
+			if (Array.isArray(key)) return client.del(...key);
+			return client.del(key);
+		},
+		async exists(key) {
+			if (Array.isArray(key)) return client.exists(...key);
+			return client.exists(key);
+		},
+		async scan(cursor, ...args) {
+			const [next, keys] = await client.scan(cursor, ...args);
+			return [next, keys];
+		},
+		eval: client.eval ? (script, numKeys, ...args) => client.eval(script, numKeys, ...args) : void 0,
+		async quit() {
+			if (client.quit) return client.quit();
+			return "OK";
+		},
+		async disconnect() {
+			if (client.disconnect) client.disconnect();
+		}
+	};
+}
+/**
+* Wrap an `@upstash/redis` REST client as an idempotency `RedisClient`.
+*
+* Enables running arc's idempotency store on Cloudflare Workers, Vercel Edge
+* and Deno Deploy — runtimes that don't support raw TCP (ioredis).
+*
+* @example
+* ```typescript
+* import { Redis } from '@upstash/redis';
+* import { RedisIdempotencyStore, upstashAsIdempotencyClient }
+*   from '@classytic/arc/idempotency/redis';
+*
+* const redis = Redis.fromEnv();
+* const store = new RedisIdempotencyStore({
+*   client: upstashAsIdempotencyClient(redis),
+* });
+* ```
+*/
+function upstashAsIdempotencyClient(client) {
+	return {
+		async get(key) {
+			const raw = await client.get(key);
+			if (raw == null) return null;
+			return typeof raw === "string" ? raw : JSON.stringify(raw);
+		},
+		async set(key, value, options) {
+			const opts = {};
+			if (options?.EX != null) opts.ex = options.EX;
+			if (options?.NX) opts.nx = true;
+			const res = await client.set(key, value, opts);
+			return res == null ? null : String(res);
+		},
+		async del(key) {
+			if (Array.isArray(key)) return client.del(...key);
+			return client.del(key);
+		},
+		async exists(key) {
+			if (Array.isArray(key)) return client.exists(...key);
+			return client.exists(key);
+		},
+		async scan(cursor, ...args) {
+			const opts = {};
+			for (let i = 0; i < args.length; i += 2) {
+				const flag = String(args[i]).toLowerCase();
+				const val = args[i + 1];
+				if (flag === "match" && typeof val === "string") opts.match = val;
+				if (flag === "count") opts.count = Number(val);
+			}
+			const [next, keys] = await client.scan(cursor, opts);
+			return [next, keys];
+		},
+		eval: client.eval ? async (script, _numKeys, ...args) => {
+			const keyCount = _numKeys;
+			const keys = args.slice(0, keyCount).map(String);
+			const rest = args.slice(keyCount);
+			return client.eval(script, keys, rest);
+		} : void 0,
+		async quit() {
+			return "OK";
+		},
+		async disconnect() {}
+	};
+}
 //#endregion
-export { RedisIdempotencyStore };
+export { RedisIdempotencyStore, ioredisAsIdempotencyClient, upstashAsIdempotencyClient };

package/dist/{index-CSkeivBx.d.mts → index-C-xjcA6F.d.mts}

@@ -1,5 +1,5 @@
-import { r as RequestScope } from "./types-C72d3NDn.mjs";
-import { n as PermissionContext, r as PermissionResult, t as PermissionCheck } from "./types-CVC4HOKi.mjs";
+import { r as RequestScope } from "./types-BD85MlEK.mjs";
+import { n as PermissionContext, r as PermissionResult, t as PermissionCheck } from "./types-DZi1aYhm.mjs";
 import { i as CacheStore, t as CacheLogger } from "./interface-DplgQO2e.mjs";
 import { FastifyRequest } from "fastify";
 

package/dist/{index-CpTSDqmD.d.mts → index-Cibkchnx.d.mts}

@@ -1,7 +1,7 @@
-import { r as RequestScope } from "./types-C72d3NDn.mjs";
-import { D as CrudRouterOptions, Ht as IControllerResponse, N as FastifyWithDecorators, T as CrudController, Ut as IRequestContext, Vt as IController, ct as RequestWithExtras, m as AnyRecord, ot as RequestContext, qt as ResourceDefinition, ut as ResourceConfig } from "./interface-BVuMfeVv.mjs";
-import { t as PermissionCheck } from "./types-CVC4HOKi.mjs";
-import { FastifyInstance, FastifyReply, FastifyRequest, RouteHandlerMethod } from "fastify";
+import { r as RequestScope } from "./types-BD85MlEK.mjs";
+import { Bt as IController, E as CrudRouterOptions, Ht as IRequestContext, Kt as ResourceDefinition, M as FastifyWithDecorators, Vt as IControllerResponse, at as RequestContext, lt as ResourceConfig, p as AnyRecord, w as CrudController } from "./interface-YrWsmKqE.mjs";
+import { t as PermissionCheck } from "./types-DZi1aYhm.mjs";
+import { FastifyReply, FastifyRequest, RouteHandlerMethod } from "fastify";
 
 //#region src/constants.d.ts
 /**
@@ -52,137 +52,6 @@ declare const MAX_FILTER_DEPTH: 10;
  */
 declare const RESERVED_QUERY_PARAMS: Readonly<Set<string>>;
 //#endregion
-//#region src/core/createActionRouter.d.ts
-/**
- * Action handler function
- * @param id - Resource ID
- * @param data - Action-specific data from request body
- * @param req - Full Fastify request object
- * @returns Action result (will be wrapped in success response)
- */
-type ActionHandler<TData = Record<string, unknown>, TResult = unknown> = (id: string, data: TData, req: RequestWithExtras) => Promise<TResult>;
-/**
- * Action router configuration
- */
-interface ActionRouterConfig {
-  /**
-   * OpenAPI tag for grouping routes
-   */
-  readonly tag?: string;
-  /**
-   * Action handlers map
-   * @example { approve: (id, data, req) => service.approve(id), ... }
-   */
-  readonly actions: Record<string, ActionHandler>;
-  /**
-   * Per-action permission checks (PermissionCheck functions)
-   * @example { approve: requireRoles(['admin', 'manager']), cancel: requireRoles(['admin']) }
-   */
-  readonly actionPermissions?: Record<string, PermissionCheck>;
-  /**
-   * Per-action schema for body validation.
-   *
-   * Accepted shapes per action:
-   *
-   * 1. **Full JSON Schema object** with `type: 'object'`, `properties`, `required` —
-   *    used verbatim. Required fields ARE enforced by Fastify's AJV.
-   *
-   * 2. **Zod v4 schema** — auto-converted via `z.toJSONSchema()`. Required fields
-   *    ARE enforced.
-   *
-   * 3. **Legacy field map** `{ fieldName: { type: 'string' } }` — each key becomes
-   *    a property and is treated as REQUIRED unless the property schema has
-   *    `nullable: true` or Arc's sentinel `required: false`. Kept for back-compat.
-   *
-   * All shapes are compiled into a single `oneOf` discriminator body schema
-   * so AJV can validate action-specific required fields at the HTTP layer.
-   *
-   * @example JSON Schema
-   * ```ts
-   * actionSchemas: {
-   *   dispatch: {
-   *     type: 'object',
-   *     properties: { carrier: { type: 'string' } },
-   *     required: ['carrier'],
-   *   },
-   * }
-   * ```
-   *
-   * @example Zod v4
-   * ```ts
-   * actionSchemas: {
-   *   dispatch: z.object({ carrier: z.string() }),
-   * }
-   * ```
-   */
-  readonly actionSchemas?: Record<string, Record<string, unknown>>;
-  /**
-   * Global permission check applied to all actions (if action-specific not defined)
-   */
-  readonly globalAuth?: PermissionCheck;
-  /**
-   * Optional idempotency service
-   * If provided, will handle idempotency-key header
-   */
-  readonly idempotencyService?: IdempotencyService;
-  /**
-   * Custom error handler for action execution failures
-   * @param error - The error thrown by action handler
-   * @param action - The action that failed
-   * @param id - The resource ID
-   * @returns Status code and error response
-   */
-  readonly onError?: (error: Error, action: string, id: string) => {
-    statusCode: number;
-    error: string;
-    code?: string;
-  };
-}
-/**
- * Idempotency service interface
- * Apps can provide their own implementation
- */
-interface IdempotencyService {
-  check(key: string, payload: unknown): Promise<{
-    isNew: boolean;
-    existingResult?: unknown;
-  }>;
-  complete(key: string | undefined, result: unknown): Promise<void>;
-  fail(key: string | undefined, error: Error): Promise<void>;
-}
-/**
- * Create action-based state transition endpoint
- *
- * Registers: POST /:id/action
- * Body: { action: string, ...actionData }
- *
- * @param fastify - Fastify instance
- * @param config - Action router configuration
- */
-declare function createActionRouter(fastify: FastifyInstance, config: ActionRouterConfig): void;
-/**
- * Build a discriminated body schema for the unified action endpoint.
- *
- * Produces a schema of the form:
- * ```json
- * {
- *   "type": "object",
- *   "required": ["action"],
- *   "oneOf": [
- *     { "properties": { "action": { "const": "dispatch" }, "carrier": {...} }, "required": ["action", "carrier"] },
- *     { "properties": { "action": { "const": "approve" } }, "required": ["action"] }
- *   ]
- * }
- * ```
- *
- * AJV validates this natively, so an action call missing required fields is
- * rejected with HTTP 400 before the handler ever runs.
- *
- * Exported so OpenAPI generation and MCP tool generation can reuse the same
- * schema shape (single source of truth).
- */
-declare function buildActionBodySchema(actionEnum: readonly string[], actionSchemas?: Record<string, Record<string, unknown>>): Record<string, unknown>;
-//#endregion
 //#region src/core/createCrudRouter.d.ts
 /**
  * Create CRUD routes for a controller
@@ -309,4 +178,4 @@ declare function createCrudHandlers<TDoc>(controller: IController<TDoc>): {
   delete: (req: FastifyRequest, reply: FastifyReply) => Promise<void>;
 };
 //#endregion
-export { MUTATION_OPERATIONS as A, HOOK_OPERATIONS as C, MAX_FILTER_DEPTH as D, HookPhase as E, RESERVED_QUERY_PARAMS as M, SYSTEM_FIELDS as N, MAX_REGEX_LENGTH as O, DEFAULT_UPDATE_METHOD as S, HookOperation as T, DEFAULT_ID_FIELD as _, getControllerScope as a, DEFAULT_SORT as b, createCrudRouter as c, ActionRouterConfig as d, IdempotencyService as f, CrudOperation as g, CRUD_OPERATIONS as h, getControllerContext as i, MutationOperation as j, MAX_SEARCH_LENGTH as k, createPermissionMiddleware as l, createActionRouter as m, createFastifyHandler as n, sendControllerResponse as o, buildActionBodySchema as p, createRequestContext as r, defineResourceVariants as s, createCrudHandlers as t, ActionHandler as u, DEFAULT_LIMIT as v, HOOK_PHASES as w, DEFAULT_TENANT_FIELD as x, DEFAULT_MAX_LIMIT as y };
+export { MAX_REGEX_LENGTH as C, RESERVED_QUERY_PARAMS as D, MutationOperation as E, SYSTEM_FIELDS as O, MAX_FILTER_DEPTH as S, MUTATION_OPERATIONS as T, DEFAULT_UPDATE_METHOD as _, getControllerScope as a, HookOperation as b, createCrudRouter as c, CrudOperation as d, DEFAULT_ID_FIELD as f, DEFAULT_TENANT_FIELD as g, DEFAULT_SORT as h, getControllerContext as i, createPermissionMiddleware as l, DEFAULT_MAX_LIMIT as m, createFastifyHandler as n, sendControllerResponse as o, DEFAULT_LIMIT as p, createRequestContext as r, defineResourceVariants as s, createCrudHandlers as t, CRUD_OPERATIONS as u, HOOK_OPERATIONS as v, MAX_SEARCH_LENGTH as w, HookPhase as x, HOOK_PHASES as y };

package/dist/{index-BgmMdpm8.d.mts → index-CtGKT0lf.d.mts}

@@ -1,4 +1,4 @@
-import { Y as OpenApiSchemas, Z as ParsedQuery, Zt as CrudRepository, c as ValidationResult, n as AdapterSchemaContext, nt as QueryParserInterface, o as RepositoryLike, r as DataAdapter, s as SchemaMetadata, vt as RouteSchemaOptions } from "./interface-BVuMfeVv.mjs";
+import { J as OpenApiSchemas, X as ParsedQuery, Xt as CrudRepository, _t as RouteSchemaOptions, c as ValidationResult, n as AdapterSchemaContext, o as RepositoryLike, r as DataAdapter, s as SchemaMetadata, tt as QueryParserInterface } from "./interface-YrWsmKqE.mjs";
 import { Model } from "mongoose";
 
 //#region src/adapters/mongoose.d.ts

package/dist/index.d.mts

@@ -1,10 +1,10 @@
-import { $ as PresetFunction, $t as DeleteOptions, At as BaseController, B as InferResourceDoc, C as ConfigError, Ct as TypedResourceConfig, D as CrudRouterOptions, Dt as ValidationResult$1, E as CrudRouteKey, Et as ValidateOptions, F as GracefulShutdownOptions, H as IntrospectionPluginOptions, Ht as IControllerResponse, I as HealthCheck, Jt as defineResource, K as MiddlewareConfig, L as HealthOptions, M as FastifyWithAuth, N as FastifyWithDecorators, O as CrudSchemas, Ot as envelope, P as FieldRule, Qt as DeleteManyResult, R as InferAdapterDoc, St as TypedRepository, T as CrudController, Tt as UserOrganization, U as JWTPayload, Ut as IRequestContext, V as IntrospectionData, Vt as IController, Wt as RouteHandler, X as OwnershipCheck, Xt as BulkWriteResult, Yt as BulkWriteOperation, Zt as CrudRepository, _ as ArcInternalMetadata, _n as PipelineStep, a as RelationMetadata, an as PaginationParams, at as RegistryStats, b as AuthPluginOptions, c as ValidationResult, cn as RepositorySession, ct as RequestWithExtras, dn as Guard, en as DeleteResult, fn as Interceptor, gn as PipelineContext, gt as RouteHandlerMethod, h as ApiResponse, hn as PipelineConfig, i as FieldMetadata, in as PaginatedResult, it as RegistryEntry, j as FastifyRequestExtras, jt as BaseControllerOptions, k as EventDefinition, ln as UpdateManyResult, m as AnyRecord, mn as OperationFilter, nn as KeysetPaginatedResult, o as RepositoryLike, on as PaginationResult, ot as RequestContext, p as AdditionalRoute, pn as NextFunction, pt as ResourceMetadata, q as MiddlewareHandler, qt as ResourceDefinition, r as DataAdapter, rn as OffsetPaginatedResult, rt as RateLimitConfig, s as SchemaMetadata, sn as QueryOptions, st as RequestIdOptions, tt as PresetResult, un as WriteOptions, ut as ResourceConfig, v as ArcRequest, vn as Transform, vt as RouteSchemaOptions, xt as TypedController, yt as ServiceContext, z as InferDocType, zt as ControllerLike } from "./interface-BVuMfeVv.mjs";
-import { a as applyFieldWritePermissions, i as applyFieldReadPermissions, n as FieldPermissionMap, o as fields, t as FieldPermission } from "./fields-DC4So2M2.mjs";
-import { i as UserBase, n as PermissionContext, r as PermissionResult, t as PermissionCheck } from "./types-CVC4HOKi.mjs";
-import { l as createMongooseAdapter, o as createPrismaAdapter, s as MongooseAdapter, t as PrismaAdapter } from "./index-BgmMdpm8.mjs";
-import { A as MUTATION_OPERATIONS, C as HOOK_OPERATIONS, D as MAX_FILTER_DEPTH, E as HookPhase, M as RESERVED_QUERY_PARAMS, N as SYSTEM_FIELDS, O as MAX_REGEX_LENGTH, S as DEFAULT_UPDATE_METHOD, T as HookOperation, _ as DEFAULT_ID_FIELD, a as getControllerScope, b as DEFAULT_SORT, g as CrudOperation, h as CRUD_OPERATIONS, j as MutationOperation, k as MAX_SEARCH_LENGTH, s as defineResourceVariants, v as DEFAULT_LIMIT, w as HOOK_PHASES, x as DEFAULT_TENANT_FIELD, y as DEFAULT_MAX_LIMIT } from "./index-CpTSDqmD.mjs";
-import { C as authenticated, D as publicRead, E as presets_d_exports, O as publicReadAdminWrite, S as adminOnly, T as ownerWithAdminBypass, _ as requireScopeContext, a as allOf, c as createDynamicPermissionMatrix, d as requireAuth, f as requireOrgInScope, g as requireRoles, h as requireOwnership, k as readOnly, l as createOrgPermissions, m as requireOrgRole, n as DynamicPermissionMatrix, o as allowPublic, p as requireOrgMembership, r as DynamicPermissionMatrixConfig, s as anyOf, u as denyAll, v as requireServiceScope, w as fullPublic, x as when, y as requireTeamMembership } from "./index-CSkeivBx.mjs";
-import { a as NotFoundError, d as ValidationError, f as createDomainError, i as ForbiddenError, t as ArcError, u as UnauthorizedError } from "./errors-Bmn3eZT6.mjs";
+import { $t as DeleteResult, A as FastifyRequestExtras, At as BaseControllerOptions, B as IntrospectionData, Bt as IController, D as CrudSchemas, Dt as envelope, E as CrudRouterOptions, Et as ValidationResult$1, F as HealthCheck, G as MiddlewareConfig, H as JWTPayload, Ht as IRequestContext, I as HealthOptions, Jt as BulkWriteOperation, K as MiddlewareHandler, Kt as ResourceDefinition, L as InferAdapterDoc, M as FastifyWithDecorators, N as FieldRule, O as EventDefinition, P as GracefulShutdownOptions, Q as PresetFunction, Qt as DeleteOptions, R as InferDocType, Rt as ControllerLike, S as ConfigError, St as TypedResourceConfig, T as CrudRouteKey, Tt as ValidateOptions, Ut as RouteHandler, V as IntrospectionPluginOptions, Vt as IControllerResponse, Xt as CrudRepository, Y as OwnershipCheck, Yt as BulkWriteResult, Zt as DeleteManyResult, _ as ArcRequest, _n as PipelineStep, _t as RouteSchemaOptions, a as RelationMetadata, an as PaginationParams, at as RequestContext, bt as TypedController, c as ValidationResult, cn as RepositorySession, dn as Guard, et as PresetResult, fn as Interceptor, ft as ResourceMetadata, g as ArcInternalMetadata, gn as PipelineContext, hn as PipelineConfig, ht as RouteHandlerMethod, i as FieldMetadata, in as PaginatedResult, it as RegistryStats, j as FastifyWithAuth, kt as BaseController, ln as UpdateManyResult, lt as ResourceConfig, m as ApiResponse, mn as OperationFilter, nn as KeysetPaginatedResult, nt as RateLimitConfig, o as RepositoryLike, on as PaginationResult, ot as RequestIdOptions, p as AnyRecord, pn as NextFunction, qt as defineResource, r as DataAdapter, rn as OffsetPaginatedResult, rt as RegistryEntry, s as SchemaMetadata, sn as QueryOptions, st as RequestWithExtras, un as WriteOptions, vn as Transform, vt as ServiceContext, w as CrudController, wt as UserOrganization, xt as TypedRepository, y as AuthPluginOptions, z as InferResourceDoc } from "./interface-YrWsmKqE.mjs";
+import { a as applyFieldWritePermissions, i as applyFieldReadPermissions, n as FieldPermissionMap, o as fields, t as FieldPermission } from "./fields-BC7zcmI9.mjs";
+import { i as UserBase, n as PermissionContext, r as PermissionResult, t as PermissionCheck } from "./types-DZi1aYhm.mjs";
+import { l as createMongooseAdapter, o as createPrismaAdapter, s as MongooseAdapter, t as PrismaAdapter } from "./index-CtGKT0lf.mjs";
+import { C as MAX_REGEX_LENGTH, D as RESERVED_QUERY_PARAMS, E as MutationOperation, O as SYSTEM_FIELDS, S as MAX_FILTER_DEPTH, T as MUTATION_OPERATIONS, _ as DEFAULT_UPDATE_METHOD, a as getControllerScope, b as HookOperation, d as CrudOperation, f as DEFAULT_ID_FIELD, g as DEFAULT_TENANT_FIELD, h as DEFAULT_SORT, m as DEFAULT_MAX_LIMIT, p as DEFAULT_LIMIT, s as defineResourceVariants, u as CRUD_OPERATIONS, v as HOOK_OPERATIONS, w as MAX_SEARCH_LENGTH, x as HookPhase, y as HOOK_PHASES } from "./index-Cibkchnx.mjs";
+import { C as authenticated, D as publicRead, E as presets_d_exports, O as publicReadAdminWrite, S as adminOnly, T as ownerWithAdminBypass, _ as requireScopeContext, a as allOf, c as createDynamicPermissionMatrix, d as requireAuth, f as requireOrgInScope, g as requireRoles, h as requireOwnership, k as readOnly, l as createOrgPermissions, m as requireOrgRole, n as DynamicPermissionMatrix, o as allowPublic, p as requireOrgMembership, r as DynamicPermissionMatrixConfig, s as anyOf, u as denyAll, v as requireServiceScope, w as fullPublic, x as when, y as requireTeamMembership } from "./index-C-xjcA6F.mjs";
+import { a as NotFoundError, d as ValidationError, f as createDomainError, i as ForbiddenError, t as ArcError, u as UnauthorizedError } from "./errors-BI8kEKsO.mjs";
 import { AsyncLocalStorage } from "node:async_hooks";
 import { RouteHandlerMethod as RouteHandlerMethod$1 } from "fastify";
 
@@ -253,4 +253,4 @@ declare function arcLog(module: string): ArcLogger;
 //#region src/index.d.ts
 declare const version: string;
 //#endregion
-export { type ValidationResult as AdapterValidationResult, type AdditionalRoute, type AnyRecord, type ApiResponse, ArcError, type ArcInternalMetadata, type ArcLogWriter, type ArcLogger, type ArcLoggerOptions, type ArcRequest, type AuthPluginOptions, BaseController, type BaseControllerOptions, type BulkWriteOperation, type BulkWriteResult, CRUD_OPERATIONS, type ConfigError, type ControllerLike, type CrudController, CrudOperation, type CrudRepository, type CrudRouteKey, type CrudRouterOptions, type CrudSchemas, DEFAULT_ID_FIELD, DEFAULT_LIMIT, DEFAULT_MAX_LIMIT, DEFAULT_SORT, DEFAULT_TENANT_FIELD, DEFAULT_UPDATE_METHOD, type DataAdapter, type DeleteManyResult, type DeleteOptions, type DeleteResult, type DynamicPermissionMatrix, type DynamicPermissionMatrixConfig, type EventDefinition, type FastifyRequestExtras, type FastifyWithAuth, type FastifyWithDecorators, type FieldMetadata, type FieldPermission, type FieldPermissionMap, type FieldRule, ForbiddenError, type GracefulShutdownOptions, type Guard, HOOK_OPERATIONS, HOOK_PHASES, type HealthCheck, type HealthOptions, HookOperation, HookPhase, type IController, type IControllerResponse, type IRequestContext, type InferAdapterDoc, type InferDocType, type InferResourceDoc, type Interceptor, type IntrospectionData, type IntrospectionPluginOptions, type JWTPayload, type KeysetPaginatedResult, MAX_FILTER_DEPTH, MAX_REGEX_LENGTH, MAX_SEARCH_LENGTH, MUTATION_OPERATIONS, type MiddlewareConfig, MongooseAdapter, MutationOperation, type NamedMiddleware, NotFoundError, type OffsetPaginatedResult, type OwnershipCheck, type PaginatedResult, type PaginationParams, type PaginationResult, type PermissionCheck, type PermissionContext, type PermissionResult, type PipelineConfig, type PipelineContext, type PipelineStep, type PresetFunction, type PresetResult, PrismaAdapter, type QueryOptions, RESERVED_QUERY_PARAMS, type RateLimitConfig, type RegistryEntry, type RegistryStats, type RelationMetadata, type RepositoryLike, type RepositorySession, type RequestContext, type RequestIdOptions, type RequestStore, type RequestWithExtras, type ResourceConfig, ResourceDefinition, type ResourceMetadata, type RouteHandler, type RouteHandlerMethod, type RouteSchemaOptions, SYSTEM_FIELDS, type SchemaMetadata, type ServiceContext, type Transform, type TypedController, type TypedRepository, type TypedResourceConfig, UnauthorizedError, type UpdateManyResult, type UserBase, type UserOrganization, type ValidateOptions, ValidationError, type ValidationResult$1 as ValidationResult, type WriteOptions, adminOnly, allOf, allowPublic, anyOf, applyFieldReadPermissions, applyFieldWritePermissions, arcLog, assertValidConfig, authenticated, configureArcLogger, createDomainError, createDynamicPermissionMatrix, createMongooseAdapter, createOrgPermissions, createPrismaAdapter, defineResource, defineResourceVariants, denyAll, envelope, fields, formatValidationErrors, fullPublic, getControllerScope, guard, intercept, middleware, ownerWithAdminBypass, presets_d_exports as permissions, pipe, publicRead, publicReadAdminWrite, readOnly, requestContext, requireAuth, requireOrgInScope, requireOrgMembership, requireOrgRole, requireOwnership, requireRoles, requireScopeContext, requireServiceScope, requireTeamMembership, sortMiddlewares, transform, validateResourceConfig, version, when };
+export { type ValidationResult as AdapterValidationResult, type AnyRecord, type ApiResponse, ArcError, type ArcInternalMetadata, type ArcLogWriter, type ArcLogger, type ArcLoggerOptions, type ArcRequest, type AuthPluginOptions, BaseController, type BaseControllerOptions, type BulkWriteOperation, type BulkWriteResult, CRUD_OPERATIONS, type ConfigError, type ControllerLike, type CrudController, CrudOperation, type CrudRepository, type CrudRouteKey, type CrudRouterOptions, type CrudSchemas, DEFAULT_ID_FIELD, DEFAULT_LIMIT, DEFAULT_MAX_LIMIT, DEFAULT_SORT, DEFAULT_TENANT_FIELD, DEFAULT_UPDATE_METHOD, type DataAdapter, type DeleteManyResult, type DeleteOptions, type DeleteResult, type DynamicPermissionMatrix, type DynamicPermissionMatrixConfig, type EventDefinition, type FastifyRequestExtras, type FastifyWithAuth, type FastifyWithDecorators, type FieldMetadata, type FieldPermission, type FieldPermissionMap, type FieldRule, ForbiddenError, type GracefulShutdownOptions, type Guard, HOOK_OPERATIONS, HOOK_PHASES, type HealthCheck, type HealthOptions, HookOperation, HookPhase, type IController, type IControllerResponse, type IRequestContext, type InferAdapterDoc, type InferDocType, type InferResourceDoc, type Interceptor, type IntrospectionData, type IntrospectionPluginOptions, type JWTPayload, type KeysetPaginatedResult, MAX_FILTER_DEPTH, MAX_REGEX_LENGTH, MAX_SEARCH_LENGTH, MUTATION_OPERATIONS, type MiddlewareConfig, MongooseAdapter, MutationOperation, type NamedMiddleware, NotFoundError, type OffsetPaginatedResult, type OwnershipCheck, type PaginatedResult, type PaginationParams, type PaginationResult, type PermissionCheck, type PermissionContext, type PermissionResult, type PipelineConfig, type PipelineContext, type PipelineStep, type PresetFunction, type PresetResult, PrismaAdapter, type QueryOptions, RESERVED_QUERY_PARAMS, type RateLimitConfig, type RegistryEntry, type RegistryStats, type RelationMetadata, type RepositoryLike, type RepositorySession, type RequestContext, type RequestIdOptions, type RequestStore, type RequestWithExtras, type ResourceConfig, ResourceDefinition, type ResourceMetadata, type RouteHandler, type RouteHandlerMethod, type RouteSchemaOptions, SYSTEM_FIELDS, type SchemaMetadata, type ServiceContext, type Transform, type TypedController, type TypedRepository, type TypedResourceConfig, UnauthorizedError, type UpdateManyResult, type UserBase, type UserOrganization, type ValidateOptions, ValidationError, type ValidationResult$1 as ValidationResult, type WriteOptions, adminOnly, allOf, allowPublic, anyOf, applyFieldReadPermissions, applyFieldWritePermissions, arcLog, assertValidConfig, authenticated, configureArcLogger, createDomainError, createDynamicPermissionMatrix, createMongooseAdapter, createOrgPermissions, createPrismaAdapter, defineResource, defineResourceVariants, denyAll, envelope, fields, formatValidationErrors, fullPublic, getControllerScope, guard, intercept, middleware, ownerWithAdminBypass, presets_d_exports as permissions, pipe, publicRead, publicReadAdminWrite, readOnly, requestContext, requireAuth, requireOrgInScope, requireOrgMembership, requireOrgRole, requireOwnership, requireRoles, requireScopeContext, requireServiceScope, requireTeamMembership, sortMiddlewares, transform, validateResourceConfig, version, when };

package/dist/index.mjs

@@ -1,13 +1,13 @@
 import { a as DEFAULT_SORT, c as HOOK_OPERATIONS, d as MAX_REGEX_LENGTH, f as MAX_SEARCH_LENGTH, h as SYSTEM_FIELDS, i as DEFAULT_MAX_LIMIT, l as HOOK_PHASES, m as RESERVED_QUERY_PARAMS, n as DEFAULT_ID_FIELD, o as DEFAULT_TENANT_FIELD, p as MUTATION_OPERATIONS, r as DEFAULT_LIMIT, s as DEFAULT_UPDATE_METHOD, t as CRUD_OPERATIONS, u as MAX_FILTER_DEPTH } from "./constants-Cxde4rpC.mjs";
 import { a as createMongooseAdapter, i as MongooseAdapter, r as createPrismaAdapter, t as PrismaAdapter } from "./adapters-BBqAVvPK.mjs";
-import { t as BaseController } from "./BaseController-DAGGc5Xn.mjs";
+import { t as BaseController } from "./BaseController-Vu2yc56T.mjs";
 import { envelope } from "./types/index.mjs";
-import { n as applyFieldWritePermissions, r as fields, t as applyFieldReadPermissions } from "./fields-ipsbIRPK.mjs";
-import { t as requestContext } from "./requestContext-DYvHl113.mjs";
-import { d as createDomainError, i as NotFoundError, l as UnauthorizedError, r as ForbiddenError, t as ArcError, u as ValidationError } from "./errors-BF2bIOIS.mjs";
-import { a as validateResourceConfig, f as getControllerScope, i as formatValidationErrors, m as pipe, n as defineResource, r as assertValidConfig, t as ResourceDefinition } from "./defineResource-Bb_Bdhtw.mjs";
-import { C as publicRead, S as presets_exports, T as readOnly, _ as when, a as createOrgPermissions, b as fullPublic, c as requireOrgInScope, d as requireOwnership, f as requireRoles, h as requireTeamMembership, i as createDynamicPermissionMatrix, l as requireOrgMembership, m as requireServiceScope, n as allowPublic, o as denyAll, p as requireScopeContext, r as anyOf, s as requireAuth, t as allOf, u as requireOrgRole, v as adminOnly, w as publicReadAdminWrite, x as ownerWithAdminBypass, y as authenticated } from "./permissions-CH4cNwJi.mjs";
-import { t as defineResourceVariants } from "./core-DKSwNSXf.mjs";
+import { n as applyFieldWritePermissions, r as fields, t as applyFieldReadPermissions } from "./fields-CU6FlaDV.mjs";
+import { d as createDomainError, i as NotFoundError, l as UnauthorizedError, r as ForbiddenError, t as ArcError, u as ValidationError } from "./errors-CqWnSqM-.mjs";
+import { t as requestContext } from "./requestContext-DYtmNpm5.mjs";
+import { a as validateResourceConfig, f as getControllerScope, i as formatValidationErrors, m as pipe, n as defineResource, r as assertValidConfig, t as ResourceDefinition } from "./defineResource-C__jkwvs.mjs";
+import { C as publicRead, S as presets_exports, T as readOnly, _ as when, a as createOrgPermissions, b as fullPublic, c as requireOrgInScope, d as requireOwnership, f as requireRoles, h as requireTeamMembership, i as createDynamicPermissionMatrix, l as requireOrgMembership, m as requireServiceScope, n as allowPublic, o as denyAll, p as requireScopeContext, r as anyOf, s as requireAuth, t as allOf, u as requireOrgRole, v as adminOnly, w as publicReadAdminWrite, x as ownerWithAdminBypass, y as authenticated } from "./permissions-oNZawnkR.mjs";
+import { t as defineResourceVariants } from "./core-DNncu0xF.mjs";
 import { n as configureArcLogger, t as arcLog } from "./logger-CDjpjySd.mjs";
 //#region src/middleware/middleware.ts
 /**
@@ -128,6 +128,6 @@ function transform(name, handlerOrOptions) {
 }
 //#endregion
 //#region src/index.ts
-const version = "2.8.4";
+const version = "2.9.1";
 //#endregion
 export { ArcError, BaseController, CRUD_OPERATIONS, DEFAULT_ID_FIELD, DEFAULT_LIMIT, DEFAULT_MAX_LIMIT, DEFAULT_SORT, DEFAULT_TENANT_FIELD, DEFAULT_UPDATE_METHOD, ForbiddenError, HOOK_OPERATIONS, HOOK_PHASES, MAX_FILTER_DEPTH, MAX_REGEX_LENGTH, MAX_SEARCH_LENGTH, MUTATION_OPERATIONS, MongooseAdapter, NotFoundError, PrismaAdapter, RESERVED_QUERY_PARAMS, ResourceDefinition, SYSTEM_FIELDS, UnauthorizedError, ValidationError, adminOnly, allOf, allowPublic, anyOf, applyFieldReadPermissions, applyFieldWritePermissions, arcLog, assertValidConfig, authenticated, configureArcLogger, createDomainError, createDynamicPermissionMatrix, createMongooseAdapter, createOrgPermissions, createPrismaAdapter, defineResource, defineResourceVariants, denyAll, envelope, fields, formatValidationErrors, fullPublic, getControllerScope, guard, intercept, middleware, ownerWithAdminBypass, presets_exports as permissions, pipe, publicRead, publicReadAdminWrite, readOnly, requestContext, requireAuth, requireOrgInScope, requireOrgMembership, requireOrgRole, requireOwnership, requireRoles, requireScopeContext, requireServiceScope, requireTeamMembership, sortMiddlewares, transform, validateResourceConfig, version, when };

package/dist/integrations/event-gateway.d.mts

@@ -1,4 +1,4 @@
-import { t as DomainEvent } from "../EventTransport-CinyO7zQ.mjs";
+import { n as DomainEvent } from "../EventTransport-CqZ8FyM_.mjs";
 import { WebSocketClient, WebSocketMessage } from "./websocket.mjs";
 import { FastifyPluginAsync, FastifyRequest } from "fastify";
 

package/dist/integrations/index.d.mts

@@ -1,7 +1,7 @@
 import { WebSocketClient, WebSocketMessage, WebSocketPluginOptions } from "./websocket.mjs";
 import { EventGatewayOptions } from "./event-gateway.mjs";
 import { JobDefinition, JobDispatchOptions, JobDispatcher, JobMeta, JobsPluginOptions, QueueStats } from "./jobs.mjs";
-import { c as McpResourceConfig, f as ToolAnnotations, i as CrudOperation, l as PromptDefinition, m as ToolDefinition, n as CallToolResult, o as McpAuthResult, p as ToolContext, r as CreateMcpServerConfig, s as McpPluginOptions, t as BetterAuthHandler } from "../types-CcG4avic.mjs";
+import { c as McpResourceConfig, f as ToolAnnotations, i as CrudOperation, l as PromptDefinition, m as ToolDefinition, n as CallToolResult, o as McpAuthResult, p as ToolContext, r as CreateMcpServerConfig, s as McpPluginOptions, t as BetterAuthHandler } from "../types-CoSzA-s-.mjs";
 import { StreamlinePluginOptions, WorkflowLike, WorkflowRunLike } from "./streamline.mjs";
 import { WebhookDeliveryRecord, WebhookManager, WebhookPluginOptions, WebhookStore, WebhookSubscription } from "./webhooks.mjs";
 export { type BetterAuthHandler, type CallToolResult, type CreateMcpServerConfig, type CrudOperation, type EventGatewayOptions, type JobDefinition, type JobDispatchOptions, type JobDispatcher, type JobMeta, type JobsPluginOptions, type McpAuthResult, type McpPluginOptions, type McpResourceConfig, type PromptDefinition, type QueueStats, type StreamlinePluginOptions, type ToolAnnotations, type ToolContext, type ToolDefinition, type WebSocketClient, type WebSocketMessage, type WebSocketPluginOptions, type WebhookDeliveryRecord, type WebhookManager, type WebhookPluginOptions, type WebhookStore, type WebhookSubscription, type WorkflowLike, type WorkflowRunLike };

package/dist/integrations/jobs.d.mts

@@ -1,6 +1,19 @@
 import { FastifyPluginAsync } from "fastify";
 
 //#region src/integrations/jobs.d.ts
+/** Repeat schedule — cron pattern or fixed interval. Explicit timezone is required. */
+interface JobRepeatOptions {
+  /** Cron pattern (e.g. '0 9 * * *' = every day 09:00). Mutually exclusive with `every`. */
+  pattern?: string;
+  /** Fixed interval in ms. Mutually exclusive with `pattern`. */
+  every?: number;
+  /** IANA timezone (e.g. 'UTC', 'America/New_York'). Required for `pattern` — prevents DST drift. */
+  tz?: string;
+  /** Stop repeating after this date. */
+  endDate?: Date | string | number;
+  /** Max total runs. */
+  limit?: number;
+}
 interface JobDefinition<TData = unknown, TResult = unknown> {
   /** Unique job name */
   name: string;
@@ -22,8 +35,10 @@ interface JobDefinition<TData = unknown, TResult = unknown> {
     max: number;
     duration: number;
   };
-  /** Dead letter queue name (default: '{name}:dead') */
+  /** Dead letter queue name (default: '{name}-dead') */
   deadLetterQueue?: string;
+  /** Repeat schedule — cron or interval. Requires explicit timezone for cron. */
+  repeat?: JobRepeatOptions;
 }
 interface JobMeta {
   jobId: string;
@@ -41,6 +56,8 @@ interface JobDispatchOptions {
   removeOnComplete?: boolean | number;
   /** Remove job after failure */
   removeOnFail?: boolean | number;
+  /** One-shot repeat override at dispatch time. Usually prefer `JobDefinition.repeat`. */
+  repeat?: JobRepeatOptions;
 }
 interface JobsPluginOptions {
   /** Redis connection options (passed to BullMQ) */
@@ -97,7 +114,12 @@ interface QueueStats {
  * });
  */
 declare function defineJob<TData = unknown, TResult = unknown>(definition: JobDefinition<TData, TResult>): JobDefinition<TData, TResult>;
-/** Pluggable BullMQ job queue integration for Arc */
+/**
+ * Pluggable BullMQ job queue integration for Arc.
+ *
+ * Wrapped with fastify-plugin so the `fastify.jobs` decorator is available
+ * in the outer scope (the documented `fastify.jobs.dispatch(...)` usage).
+ */
 declare const jobsPlugin: FastifyPluginAsync<JobsPluginOptions>;
 //#endregion
-export { JobDefinition, JobDispatchOptions, JobDispatcher, JobMeta, JobsPluginOptions, QueueStats, defineJob, jobsPlugin };
+export { JobDefinition, JobDispatchOptions, JobDispatcher, JobMeta, JobRepeatOptions, JobsPluginOptions, QueueStats, defineJob, jobsPlugin };

package/dist/integrations/jobs.mjs

@@ -1,3 +1,4 @@
+import fp from "fastify-plugin";
 //#region src/integrations/jobs.ts
 /**
 * Define a background job with typed data and configuration.
@@ -26,16 +27,41 @@ const jobsPluginImpl = async (fastify, options) => {
 	} catch {
 		throw new Error("@classytic/arc/integrations/jobs requires \"bullmq\" package.\nInstall it: npm install bullmq");
 	}
+	if (connection && typeof connection === "object" && "options" in connection) {
+		if (connection.options?.maxRetriesPerRequest !== null) fastify.log.warn("[arc/jobs] BullMQ requires ioredis `maxRetriesPerRequest: null`. Pass `new Redis(url, { maxRetriesPerRequest: null, enableReadyCheck: false })` or workers will stall on transient Redis errors.");
+	}
 	const queues = /* @__PURE__ */ new Map();
 	const dlqQueues = /* @__PURE__ */ new Map();
 	const workers = /* @__PURE__ */ new Map();
+	for (const job of jobs) {
+		if (!job.repeat) continue;
+		const { pattern, every, tz } = job.repeat;
+		if (pattern && every) throw new Error(`[arc/jobs] Job '${job.name}' sets both repeat.pattern and repeat.every — use one.`);
+		if (!pattern && every == null) throw new Error(`[arc/jobs] Job '${job.name}' has repeat config but no pattern or every.`);
+		if (pattern && !tz) throw new Error(`[arc/jobs] Job '${job.name}' uses a cron pattern but no timezone. Set repeat.tz (e.g. 'UTC' or 'America/New_York') to avoid DST drift.`);
+	}
 	for (const job of jobs) {
 		const queueName = job.name;
 		const queue = new Queue(queueName, { connection });
 		queues.set(queueName, queue);
+		if (job.repeat) {
+			const repeatOpts = {
+				...job.repeat.pattern ? {
+					pattern: job.repeat.pattern,
+					tz: job.repeat.tz
+				} : { every: job.repeat.every },
+				...job.repeat.endDate ? { endDate: job.repeat.endDate } : {},
+				...job.repeat.limit != null ? { limit: job.repeat.limit } : {}
+			};
+			await queue.add(queueName, {}, {
+				repeat: repeatOpts,
+				removeOnComplete: defaults.removeOnComplete ?? 100,
+				removeOnFail: defaults.removeOnFail ?? 500
+			});
+		}
 		let dlqQueue = null;
 		if (job.deadLetterQueue != null) {
-			const dlqName = job.deadLetterQueue || `${queueName}:dead`;
+			const dlqName = job.deadLetterQueue || `${queueName}-dead`;
 			dlqQueue = new Queue(dlqName, { connection });
 			dlqQueues.set(dlqName, dlqQueue);
 		}
@@ -110,12 +136,35 @@ const jobsPluginImpl = async (fastify, options) => {
 				}, `Failed to publish job.${queueName}.failed event`);
 			}
 		});
+		worker.on("stalled", async (jobId) => {
+			fastify.log.warn({
+				jobId,
+				queue: queueName
+			}, "Job stalled — worker may have crashed");
+			if (bridgeEvents && fastify.events?.publish) try {
+				await fastify.events.publish(`job.${queueName}.stalled`, { jobId });
+			} catch (err) {
+				fastify.log.warn({
+					err,
+					jobId
+				}, `Failed to publish job.${queueName}.stalled event`);
+			}
+		});
 		workers.set(queueName, worker);
 	}
+	const JOB_PAYLOAD_WARN_BYTES = 100 * 1024;
 	const dispatcher = {
 		async dispatch(name, data, opts = {}) {
 			const queue = queues.get(name);
 			if (!queue) throw new Error(`Job queue '${name}' not registered. Available: ${Array.from(queues.keys()).join(", ")}`);
+			try {
+				const serializedBytes = Buffer.byteLength(JSON.stringify(data) ?? "", "utf8");
+				if (serializedBytes > JOB_PAYLOAD_WARN_BYTES) fastify.log.warn({
+					queue: name,
+					bytes: serializedBytes,
+					limit: JOB_PAYLOAD_WARN_BYTES
+				}, `[arc/jobs] Large job payload — prefer passing IDs and reloading in the handler`);
+			} catch {}
 			const jobDef = jobs.find((j) => j.name === name);
 			return { jobId: (await queue.add(name, data, {
 				delay: opts.delay,
@@ -127,7 +176,8 @@ const jobsPluginImpl = async (fastify, options) => {
 				backoff: jobDef?.backoff ?? defaults.backoff ?? {
 					type: "exponential",
 					delay: 1e3
-				}
+				},
+				repeat: jobDef?.repeat ?? opts.repeat
 			})).id };
 		},
 		getQueue(name) {
@@ -148,6 +198,7 @@ const jobsPluginImpl = async (fastify, options) => {
 			return stats;
 		},
 		async close() {
+			await Promise.all(Array.from(workers.values()).map((w) => w.pause().catch(() => {})));
 			const closePromises = [];
 			for (const worker of workers.values()) closePromises.push(worker.close());
 			for (const queue of queues.values()) closePromises.push(queue.close());
@@ -166,7 +217,15 @@ const jobsPluginImpl = async (fastify, options) => {
 		await dispatcher.close();
 	});
 };
-/** Pluggable BullMQ job queue integration for Arc */
-const jobsPlugin = jobsPluginImpl;
+/**
+* Pluggable BullMQ job queue integration for Arc.
+*
+* Wrapped with fastify-plugin so the `fastify.jobs` decorator is available
+* in the outer scope (the documented `fastify.jobs.dispatch(...)` usage).
+*/
+const jobsPlugin = fp(jobsPluginImpl, {
+	name: "arc-jobs",
+	fastify: "5.x"
+});
 //#endregion
 export { defineJob, jobsPlugin };