@classytic/arc 2.6.3 → 2.7.3

package/dist/{interface-DYH8AXGe.d.mts → interface-B91alUzq.d.mts}

@@ -1,6 +1,6 @@
-import { s as RequestScope } from "./elevation-C_taLQrM.mjs";
-import { n as FieldPermissionMap } from "./fields-DFwdaWCq.mjs";
-import { i as UserBase, t as PermissionCheck } from "./types-BNUccdcf.mjs";
+import { r as RequestScope } from "./types--D3vvfdt.mjs";
+import { n as FieldPermissionMap } from "./fields-D4nMDqnK.mjs";
+import { i as UserBase, t as PermissionCheck } from "./types-B4BNthET.mjs";
 import { FastifyInstance, FastifyPluginAsync, FastifyReply, FastifyRequest, RouteHandlerMethod, RouteHandlerMethod as RouteHandlerMethod$1 } from "fastify";
 
 //#region src/hooks/HookSystem.d.ts
@@ -618,17 +618,54 @@ interface ServerAccessor {
   };
 }
 /**
- * Request context passed to controller handlers
+ * Request context passed to controller handlers.
+ *
+ * **Generic parameters** (all default to safe permissive types so existing code keeps working):
+ * - `TBody`     — request body shape (default: `unknown`)
+ * - `TParams`   — route param shape (default: `Record<string, string>`)
+ * - `TQuery`    — query string shape (default: `Record<string, unknown>`)
+ * - `TUser`     — authenticated user shape (default: `UserBase`)
+ * - `TMetadata` — internal metadata shape (default: `Record<string, unknown>`;
+ *   override with `ArcInternalMetadata` or your own augmentation when you
+ *   need typed access to `_scope`, `_policyFilters`, custom hook context, etc.)
+ *
+ * @example
+ * ```typescript
+ * // Untyped (default) — req.body is `unknown`, must be narrowed
+ * async create(req: IRequestContext) {
+ *   const data = req.body as Partial<Product>;
+ *   return { success: true, data: await productRepo.create(data) };
+ * }
+ *
+ * // Typed body — req.body is `CreateProductInput`, narrowing not needed
+ * async create(req: IRequestContext<CreateProductInput>) {
+ *   return { success: true, data: await productRepo.create(req.body) };
+ * }
+ *
+ * // Fully typed — body, route params, query, and metadata
+ * async update(
+ *   req: IRequestContext<
+ *     Partial<Product>,
+ *     { id: string },
+ *     { fields?: string },
+ *     ArcInternalMetadata
+ *   >,
+ * ) {
+ *   const fields = req.query.fields?.split(',');
+ *   const orgId = req.metadata?._scope ? getOrgId(req.metadata._scope) : undefined;
+ *   return { success: true, data: await productRepo.update(req.params.id, req.body) };
+ * }
+ * ```
  */
-interface IRequestContext {
+interface IRequestContext<TBody = unknown, TParams extends Record<string, string> = Record<string, string>, TQuery extends Record<string, unknown> = Record<string, unknown>, TUser extends UserBase = UserBase, TMetadata extends Record<string, unknown> = Record<string, unknown>> {
   /** Route parameters (e.g., { id: '123' }) */
-  params: Record<string, string>;
+  params: TParams;
   /** Query string parameters */
-  query: Record<string, unknown>;
+  query: TQuery;
   /** Request body */
-  body: unknown;
+  body: TBody;
   /** Authenticated user or null */
-  user: UserBase | null;
+  user: TUser | null;
   /** Request headers */
   headers: Record<string, string | undefined>;
   /** Organization ID (for multi-tenant apps) */
@@ -649,8 +686,12 @@ interface IRequestContext {
    * ```
    */
   context?: RequestContext;
-  /** Internal metadata (includes context + Arc internals like _policyFilters, log) */
-  metadata?: Record<string, unknown>;
+  /**
+   * Internal metadata (includes context + Arc internals like `_policyFilters`,
+   * `_scope`, `log`). Type as `ArcInternalMetadata` for typed access to Arc's
+   * built-in fields, or supply your own interface to layer custom fields.
+   */
+  metadata?: TMetadata;
   /**
    * Fastify server accessor — publish events, log, and audit
    * from any handler without switching to `wrapHandler: false`.
@@ -686,18 +727,41 @@ interface IControllerResponse<T = unknown> {
   headers?: Record<string, string>;
 }
 /**
- * Controller handler - Arc's standard pattern
+ * Controller handler — Arc's standard pattern.
  *
  * Receives a request context object, returns IControllerResponse.
  * Use with `wrapHandler: true` in additionalRoutes.
  *
+ * **Generic parameters:**
+ * - `TResponse` — shape of `IControllerResponse.data` (default: `unknown`)
+ * - `TBody`     — shape of `req.body` (default: `unknown`)
+ * - `TParams`   — shape of `req.params` (default: `Record<string, string>`)
+ * - `TQuery`    — shape of `req.query` (default: `Record<string, unknown>`)
+ *
+ * Backward-compatible: `ControllerHandler<Product>` still works (only the
+ * response data is typed); add more generics as needed when you want
+ * type-safe access to the request body, params, or query string.
+ *
  * @example
  * ```typescript
+ * // Untyped req — body is unknown, must be narrowed
  * const createProduct: ControllerHandler<Product> = async (req) => {
- *   const product = await productRepo.create(req.body);
+ *   const product = await productRepo.create(req.body as Partial<Product>);
  *   return { success: true, data: product, status: 201 };
  * };
  *
+ * // Fully typed — body, params, query, and response all inferred
+ * const updateProduct: ControllerHandler<
+ *   Product,
+ *   Partial<Product>,
+ *   { id: string },
+ *   { upsert?: string }
+ * > = async (req) => {
+ *   const upsert = req.query.upsert === "true";
+ *   const product = await productRepo.update(req.params.id, req.body, { upsert });
+ *   return { success: true, data: product };
+ * };
+ *
  * additionalRoutes: [{
  *   method: 'POST',
  *   path: '/products',
@@ -707,7 +771,7 @@ interface IControllerResponse<T = unknown> {
  * }]
  * ```
  */
-type ControllerHandler<T = unknown> = (req: IRequestContext) => Promise<IControllerResponse<T>>;
+type ControllerHandler<TResponse = unknown, TBody = unknown, TParams extends Record<string, string> = Record<string, string>, TQuery extends Record<string, unknown> = Record<string, unknown>> = (req: IRequestContext<TBody, TParams, TQuery>) => Promise<IControllerResponse<TResponse>>;
 /**
  * Fastify native handler
  *
@@ -731,7 +795,7 @@ type ControllerHandler<T = unknown> = (req: IRequestContext) => Promise<IControl
  * }]
  * ```
  */
-type FastifyHandler = (request: FastifyRequest, reply: FastifyReply) => Promise<void> | void;
+type FastifyHandler<RouteGeneric extends Record<string, unknown> = Record<string, unknown>> = (request: FastifyRequest<RouteGeneric>, reply: FastifyReply) => Promise<unknown> | unknown;
 /**
  * Union type for route handlers
  */
@@ -951,6 +1015,14 @@ interface BaseControllerOptions {
   tenantField?: string | false;
   /**
    * Primary key field name (default: '_id').
+   *
+   * If not set, the controller auto-derives it from the repository's own
+   * `idField` property (e.g. MongoKit's `Repository({ idField: 'id' })`),
+   * so you only need to configure it in one place.
+   *
+   * Set explicitly to override the repo's setting (e.g. `'_id'` to opt out
+   * of native pass-through and force the slug-translation path).
+   *
    * Override for non-MongoDB adapters (e.g., 'id' for SQL databases).
    */
   idField?: string;
@@ -1010,6 +1082,23 @@ declare class BaseController<TDoc = AnyRecord, TRepository extends RepositoryLik
   private meta;
   /** Get hook system from request context (instance-scoped) */
   private getHooks;
+  /**
+   * Resolve the repository primary key for mutation calls (update/delete/restore).
+   *
+   * When the resource declares a custom `idField` (e.g. `slug`, `jobId`, UUID),
+   * the default behavior is to translate the route id → the fetched doc's `_id`
+   * because most Mongo repositories key their mutation methods off `_id`.
+   *
+   * Exception: if the repository itself exposes a matching `idField` property
+   * (e.g. MongoKit's `new Repository(Model, [], {}, { idField: 'id' })`), the
+   * repository already knows how to look up by that field — so we pass the
+   * route id through unchanged and skip the translation.
+   *
+   * This makes `defineResource({ idField: 'id' })` work end-to-end with repos
+   * that natively support custom primary keys, without breaking the slug-style
+   * aliasing that Arc 2.6.3 introduced for repos keyed on `_id`.
+   */
+  private resolveRepoId;
   /** Resolve cache config for a specific operation, merging per-op overrides */
   private resolveCacheConfig;
   /**
@@ -1056,10 +1145,43 @@ declare class BaseController<TDoc = AnyRecord, TRepository extends RepositoryLik
    * Returns the merged filter, or `null` when access must be denied.
    */
   private buildBulkFilter;
+  /**
+   * Sanitize a bulk update data payload through the same write-permission
+   * pipeline as single-doc update(). Handles both shapes:
+   *
+   *   - Flat:           `{ name: 'x', status: 'y' }`
+   *   - Mongo operator: `{ $set: { name: 'x' }, $inc: { views: 1 }, $unset: { tag: '' } }`
+   *
+   * For each operand, runs `bodySanitizer.sanitize('update', ...)` so that
+   * system fields, systemManaged/readonly/immutable rules, AND field-level
+   * write permissions are enforced. Without this, a tenant-scoped user could
+   * pass `{ $set: { organizationId: 'org-b' } }` to move records across orgs.
+   *
+   * Returns the sanitized payload along with the list of stripped fields for
+   * audit/error reporting.
+   */
+  private sanitizeBulkUpdateData;
   bulkUpdate(req: IRequestContext): Promise<IControllerResponse<{
     matchedCount: number;
     modifiedCount: number;
   }>>;
+  /**
+   * Bulk delete by `filter` or `ids`.
+   *
+   * Body shape (one of):
+   *   - `{ filter: { status: 'archived' } }`     — delete by query filter
+   *   - `{ ids: ['id1', 'id2', 'id3'] }`         — delete specific docs by id
+   *
+   * The `ids` form translates to `{ [idField]: { $in: ids } }` using the
+   * resource's `idField` (so it works with custom PKs like `slug`, `jobId`,
+   * UUID, etc.). Tenant scope and policy filters are merged in either way,
+   * so cross-tenant deletes are blocked at the controller layer.
+   *
+   * Both forms perform a single `repo.deleteMany()` DB call — no per-doc
+   * fetch loop. Per-doc lifecycle hooks (`before:delete`/`after:delete`) do
+   * NOT fire for bulk operations; use the single-doc `delete()` if you need
+   * them, or subscribe to the bulk lifecycle event from the events plugin.
+   */
   bulkDelete(req: IRequestContext): Promise<IControllerResponse<{
     deletedCount: number;
   }>>;
@@ -2369,6 +2491,20 @@ interface RepositoryLike {
   create(data: unknown, options?: unknown): Promise<unknown>;
   update(id: string, data: unknown, options?: unknown): Promise<unknown>;
   delete(id: string, options?: unknown): Promise<unknown>;
+  /**
+   * The repository's native primary key field. When set, Arc's BaseController
+   * will pass route params through to `update()`/`delete()`/`restore()` calls
+   * unchanged instead of translating them to `_id`.
+   *
+   * Set this to match your `defineResource({ idField })` for repositories that
+   * natively look up by a custom field (e.g. MongoKit's
+   * `new Repository(Model, [], {}, { idField: 'id' })`). Without it, Arc will
+   * try to translate route ids → fetched doc's `_id` which 404s on repos that
+   * don't key on `_id`.
+   *
+   * Defaults to `'_id'` (Mongo). Repositories that always use `_id` may omit it.
+   */
+  readonly idField?: string;
   /** Find single doc by compound filter — used by AccessControl for idField + org/policy scoping.
    * Without this, Arc falls back to getById + post-fetch security checks. */
   getOne?(filter: Record<string, unknown>, options?: unknown): Promise<unknown>;

package/dist/{mongodb-pMvOlR5_.d.mts → mongodb-B7zupyck.d.mts}

@@ -1,4 +1,4 @@
-import { n as IdempotencyResult, r as IdempotencyStore } from "./interface-gr-7qo9j.mjs";
+import { n as IdempotencyResult, r as IdempotencyStore } from "./interface-CSbZdv_3.mjs";
 
 //#region src/idempotency/stores/mongodb.d.ts
 interface MongoConnection {

package/dist/{mongodb-kltrBPa1.d.mts → mongodb-Cgu9F1Nd.d.mts}

@@ -1,4 +1,4 @@
-import { i as UserBase } from "./types-BNUccdcf.mjs";
+import { i as UserBase } from "./types-B4BNthET.mjs";
 
 //#region src/audit/stores/interface.d.ts
 type AuditAction = "create" | "update" | "delete" | "restore" | "custom";

package/dist/{openapi-CBmZ6EQN.mjs → openapi-BBSTVcMm.mjs}

@@ -1,5 +1,5 @@
 import { t as getUserRoles } from "./types-ZUu_h0jp.mjs";
-import { n as convertRouteSchema } from "./schemaConverter-DjzHpFam.mjs";
+import { n as convertRouteSchema } from "./schemaConverter-0TyONAwM.mjs";
 import fp from "fastify-plugin";
 //#region src/docs/openapi.ts
 const openApiPlugin = async (fastify, opts = {}) => {

package/dist/org/index.d.mts

@@ -1,5 +1,5 @@
-import { Rt as RouteHandler } from "../interface-DYH8AXGe.mjs";
-import { i as UserBase } from "../types-BNUccdcf.mjs";
+import { Rt as RouteHandler } from "../interface-B91alUzq.mjs";
+import { i as UserBase } from "../types-B4BNthET.mjs";
 import { InvitationAdapter, InvitationDoc, MemberDoc, OrgAdapter, OrgDoc, OrgPermissionStatement, OrgRole, OrganizationPluginOptions } from "./types.mjs";
 import { FastifyPluginAsync, RouteHandlerMethod } from "fastify";
 

package/dist/org/index.mjs

@@ -1,4 +1,4 @@
-import { a as getOrgRoles, d as isElevated, f as isMember, l as hasOrgAccess, n as PUBLIC_SCOPE } from "../types-BhtYdxZU.mjs";
+import { _ as isElevated, h as hasOrgAccess, n as PUBLIC_SCOPE, s as getOrgRoles, v as isMember } from "../types-AOD8fxIw.mjs";
 import fp from "fastify-plugin";
 //#region src/org/organizationPlugin.ts
 const DEFAULT_ROLES = [

package/dist/permissions/index.d.mts

@@ -1,4 +1,4 @@
-import { a as applyFieldWritePermissions, i as applyFieldReadPermissions, n as FieldPermissionMap, o as fields, r as FieldPermissionType, s as resolveEffectiveRoles, t as FieldPermission } from "../fields-DFwdaWCq.mjs";
-import { a as getUserRoles, i as UserBase, n as PermissionContext, o as normalizeRoles, r as PermissionResult, t as PermissionCheck } from "../types-BNUccdcf.mjs";
-import { C as presets_d_exports, D as RoleHierarchy, E as readOnly, O as createRoleHierarchy, S as ownerWithAdminBypass, T as publicReadAdminWrite, _ as roles, a as allOf, b as authenticated, c as createDynamicPermissionMatrix, d as requireAuth, f as requireOrgMembership, g as requireTeamMembership, h as requireRoles, i as PermissionEventBus, l as createOrgPermissions, m as requireOwnership, n as DynamicPermissionMatrix, o as allowPublic, p as requireOrgRole, r as DynamicPermissionMatrixConfig, s as anyOf, t as ConnectEventsOptions, u as denyAll, v as when, w as publicRead, x as fullPublic, y as adminOnly } from "../index-NGZksqM5.mjs";
-export { ConnectEventsOptions, DynamicPermissionMatrix, DynamicPermissionMatrixConfig, FieldPermission, FieldPermissionMap, FieldPermissionType, PermissionCheck, PermissionContext, PermissionEventBus, PermissionResult, RoleHierarchy, UserBase, adminOnly, allOf, allowPublic, anyOf, applyFieldReadPermissions, applyFieldWritePermissions, authenticated, createDynamicPermissionMatrix, createOrgPermissions, createRoleHierarchy, denyAll, fields, fullPublic, getUserRoles, normalizeRoles, ownerWithAdminBypass, presets_d_exports as permissions, publicRead, publicReadAdminWrite, readOnly, requireAuth, requireOrgMembership, requireOrgRole, requireOwnership, requireRoles, requireTeamMembership, resolveEffectiveRoles, roles, when };
+import { a as applyFieldWritePermissions, i as applyFieldReadPermissions, n as FieldPermissionMap, o as fields, r as FieldPermissionType, s as resolveEffectiveRoles, t as FieldPermission } from "../fields-D4nMDqnK.mjs";
+import { a as getUserRoles, i as UserBase, n as PermissionContext, o as normalizeRoles, r as PermissionResult, t as PermissionCheck } from "../types-B4BNthET.mjs";
+import { A as RoleHierarchy, C as authenticated, D as publicRead, E as presets_d_exports, M as applyPermissionResult, N as normalizePermissionResult, O as publicReadAdminWrite, S as adminOnly, T as ownerWithAdminBypass, _ as requireScopeContext, a as allOf, b as roles, c as createDynamicPermissionMatrix, d as requireAuth, f as requireOrgInScope, g as requireRoles, h as requireOwnership, i as PermissionEventBus, j as createRoleHierarchy, k as readOnly, l as createOrgPermissions, m as requireOrgRole, n as DynamicPermissionMatrix, o as allowPublic, p as requireOrgMembership, r as DynamicPermissionMatrixConfig, s as anyOf, t as ConnectEventsOptions, u as denyAll, v as requireServiceScope, w as fullPublic, x as when, y as requireTeamMembership } from "../index-B0extFr4.mjs";
+export { ConnectEventsOptions, DynamicPermissionMatrix, DynamicPermissionMatrixConfig, FieldPermission, FieldPermissionMap, FieldPermissionType, PermissionCheck, PermissionContext, PermissionEventBus, PermissionResult, RoleHierarchy, UserBase, adminOnly, allOf, allowPublic, anyOf, applyFieldReadPermissions, applyFieldWritePermissions, applyPermissionResult, authenticated, createDynamicPermissionMatrix, createOrgPermissions, createRoleHierarchy, denyAll, fields, fullPublic, getUserRoles, normalizePermissionResult, normalizeRoles, ownerWithAdminBypass, presets_d_exports as permissions, publicRead, publicReadAdminWrite, readOnly, requireAuth, requireOrgInScope, requireOrgMembership, requireOrgRole, requireOwnership, requireRoles, requireScopeContext, requireServiceScope, requireTeamMembership, resolveEffectiveRoles, roles, when };

package/dist/permissions/index.mjs

@@ -1,4 +1,5 @@
 import { i as resolveEffectiveRoles, n as applyFieldWritePermissions, r as fields, t as applyFieldReadPermissions } from "../fields-ipsbIRPK.mjs";
 import { n as normalizeRoles, t as getUserRoles } from "../types-ZUu_h0jp.mjs";
-import { C as createRoleHierarchy, S as readOnly, _ as fullPublic, a as createOrgPermissions, b as publicRead, c as requireOrgMembership, d as requireRoles, f as requireTeamMembership, g as authenticated, h as adminOnly, i as createDynamicPermissionMatrix, l as requireOrgRole, m as when, n as allowPublic, o as denyAll, p as roles, r as anyOf, s as requireAuth, t as allOf, u as requireOwnership, v as ownerWithAdminBypass, x as publicReadAdminWrite, y as presets_exports } from "../permissions-C8ImI8gC.mjs";
-export { adminOnly, allOf, allowPublic, anyOf, applyFieldReadPermissions, applyFieldWritePermissions, authenticated, createDynamicPermissionMatrix, createOrgPermissions, createRoleHierarchy, denyAll, fields, fullPublic, getUserRoles, normalizeRoles, ownerWithAdminBypass, presets_exports as permissions, publicRead, publicReadAdminWrite, readOnly, requireAuth, requireOrgMembership, requireOrgRole, requireOwnership, requireRoles, requireTeamMembership, resolveEffectiveRoles, roles, when };
+import { n as normalizePermissionResult, t as applyPermissionResult } from "../applyPermissionResult-D6GPMsvh.mjs";
+import { C as publicRead, E as createRoleHierarchy, S as presets_exports, T as readOnly, _ as when, a as createOrgPermissions, b as fullPublic, c as requireOrgInScope, d as requireOwnership, f as requireRoles, g as roles, 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";
+export { adminOnly, allOf, allowPublic, anyOf, applyFieldReadPermissions, applyFieldWritePermissions, applyPermissionResult, authenticated, createDynamicPermissionMatrix, createOrgPermissions, createRoleHierarchy, denyAll, fields, fullPublic, getUserRoles, normalizePermissionResult, normalizeRoles, ownerWithAdminBypass, presets_exports as permissions, publicRead, publicReadAdminWrite, readOnly, requireAuth, requireOrgInScope, requireOrgMembership, requireOrgRole, requireOwnership, requireRoles, requireScopeContext, requireServiceScope, requireTeamMembership, resolveEffectiveRoles, roles, when };