@classytic/mongokit 3.18.0 → 3.20.0

package/dist/index.mjs

@@ -1,16 +1,18 @@
-import { n as idVariants } from "./id-resolution-CnN0YA8t.mjs";
-import { a as withTransaction, c as MUTATING_OPERATIONS, d as operationsByPolicyKey, f as MONGOKIT_CAPABILITIES, i as isTransactionUnsupported, l as OP_REGISTRY, n as Repository, o as AggregationBuilder, p as createMongoPurgePort, r as batchTransaction, s as ALL_OPERATIONS, t as HOOK_PRIORITY, u as READ_OPERATIONS } from "./Repository-B01VW_fU.mjs";
-import { b as LookupBuilder, x as compileFilterToMongo } from "./update-CvCMv5Cl.mjs";
-import { n as warn, t as configureLogger } from "./logger-B8wf-Mtb.mjs";
-import { n as isDuplicateKeyError, r as parseDuplicateKeyError, t as createError } from "./error-BTeepSNL.mjs";
+import { n as idVariants } from "./id-resolution-P2OzcyRl.mjs";
+import { a as withTransaction, c as MUTATING_OPERATIONS, d as operationsByPolicyKey, f as MONGOKIT_CAPABILITIES, i as isTransactionUnsupported, l as OP_REGISTRY, n as Repository, o as AggregationBuilder, p as createMongoPurgePort, r as batchTransaction, s as ALL_OPERATIONS, t as HOOK_PRIORITY, u as READ_OPERATIONS } from "./Repository-dbbgOGjK.mjs";
+import { b as LookupBuilder, x as compileFilterToMongo } from "./update-1Lq9OMD2.mjs";
+import { n as warn, t as configureLogger } from "./logger-K7dPmu2U.mjs";
+import { n as isDuplicateKeyError, r as parseDuplicateKeyError, t as createError } from "./error-BuByZwKU.mjs";
 import { t as actions_exports } from "./actions/index.mjs";
-import { A as auditLogPlugin, C as getNextSequence, D as batchOperationsPlugin, E as cachePlugin, O as AuditTrailQuery, S as dateSequentialId, T as sequentialId, _ as softDeletePlugin, a as uniqueField, b as methodRegistryPlugin, c as subdocumentPlugin, d as leasePlugin, f as fieldFilterPlugin, g as timestampPlugin, h as aggregateHelpersPlugin, i as requireField, k as auditTrailPlugin, l as observabilityPlugin, m as cascadePlugin, n as blockIf, o as validationChainPlugin, p as elasticSearchPlugin, r as immutableField, s as createTenantContext, t as autoInject, u as mongoOperationsPlugin, v as adminBypass, w as prefixedId, x as customIdPlugin, y as multiTenantPlugin } from "./validation-chain.plugin-DJtC0KJ-.mjs";
-import { t as PaginationEngine } from "./PaginationEngine-BcvaXBQ-.mjs";
+import { a as methodRegistryPlugin, c as getNextSequence, d as cachePlugin, f as batchOperationsPlugin, h as auditLogPlugin, i as multiTenantPlugin, l as prefixedId, m as auditTrailPlugin, n as softDeletePlugin, o as customIdPlugin, p as AuditTrailQuery, r as adminBypass, s as dateSequentialId, t as timestampPlugin, u as sequentialId } from "./timestamp.plugin-nG9Z1JEk.mjs";
+import { t as PaginationEngine } from "./PaginationEngine-BT1ywu9k.mjs";
 import { isGeoOperator, parseGeoFilter } from "./query/primitives/geo.mjs";
-import { i as getMongooseProjection, n as filterResponseData, r as getFieldsForUser, t as createFieldPreset } from "./field-selection-CQW3WBiK.mjs";
+import { t as createRepository } from "./create-repository-CJATiAKX.mjs";
+import { a as uniqueField, c as subdocumentPlugin, d as leasePlugin, f as fieldFilterPlugin, h as aggregateHelpersPlugin, i as requireField, l as observabilityPlugin, m as cascadePlugin, n as blockIf, o as validationChainPlugin, p as elasticSearchPlugin, r as immutableField, s as createTenantContext, t as autoInject, u as mongoOperationsPlugin } from "./validation-chain.plugin-Dn_wZYLA.mjs";
+import { i as getMongooseProjection, n as filterResponseData, r as getFieldsForUser, t as createFieldPreset } from "./field-selection-FSQFLpsU.mjs";
 import { buildFieldTypeMap, coerceFieldValue, coerceHeuristic } from "./query/primitives/coercion.mjs";
 import { extractSchemaIndexes } from "./query/primitives/indexes.mjs";
-import { n as buildCrudSchemasFromMongooseSchema, r as createMemoryCache, t as buildCrudSchemasFromModel } from "./mongooseToJsonSchema-CBEQmeEa.mjs";
+import { n as buildCrudSchemasFromMongooseSchema, r as createMemoryCache, t as buildCrudSchemasFromModel } from "./mongooseToJsonSchema-khdzVo8x.mjs";
 import { runChunkedPurge } from "@classytic/repo-core/repository";
 import { isControlParam } from "@classytic/repo-core/query-parser";
 //#region src/actions/cascade-references.ts
@@ -142,32 +144,6 @@ async function cascadePurgeReferences(options) {
 	return out;
 }
 //#endregion
-//#region src/create-repository.ts
-function isLoggerAudit(value) {
-	const v = value;
-	return typeof v.info === "function" || typeof v.warn === "function" || typeof v.error === "function" || typeof v.debug === "function";
-}
-/**
-* Build a `Repository` from a declarative config. See module JSDoc for
-* ordering guarantees and an example.
-*/
-function createRepository(model, config = {}) {
-	const { tenant, softDelete, timestamps, batch, cache, audit, customId, plugins = [], pagination = {}, ...repositoryOptions } = config;
-	const stack = [methodRegistryPlugin()];
-	if (tenant) stack.push(multiTenantPlugin(tenant));
-	if (softDelete) stack.push(softDeletePlugin(softDelete === true ? {} : softDelete));
-	if (timestamps) stack.push(timestampPlugin());
-	if (customId) stack.push(customIdPlugin(customId));
-	if (cache) stack.push(cachePlugin(cache));
-	if (audit) stack.push(isLoggerAudit(audit) ? auditLogPlugin(audit) : auditTrailPlugin(audit));
-	if (batch) stack.push(batchOperationsPlugin());
-	stack.push(...plugins);
-	return new Repository(model, stack, pagination, {
-		pluginOrderChecks: repositoryOptions.pluginOrderChecks ?? "throw",
-		...repositoryOptions
-	});
-}
-//#endregion
 //#region src/query/QueryParser.ts
 /**
 * Modern Query Parser - URL to MongoDB Query Transpiler
@@ -250,7 +226,7 @@ function createRepository(model, config = {}) {
 * without this guard. Kept as a Set for O(1) lookup; values mirror the
 * reserved-key list at the top of `_parseFilters`.
 */
-const RESERVED_PAGINATION_KEYS = new Set([
+const RESERVED_PAGINATION_KEYS = /* @__PURE__ */ new Set([
 	"page",
 	"limit",
 	"sort",
@@ -1067,7 +1043,7 @@ var QueryParser = class {
 			return {};
 		}
 		const sanitized = {};
-		const logicalArrayOps = new Set([
+		const logicalArrayOps = /* @__PURE__ */ new Set([
 			"$or",
 			"$and",
 			"$nor"
@@ -1445,6 +1421,44 @@ function systemContext(extra) {
 }
 //#endregion
 //#region src/index.ts
+/**
+* MongoKit - Event-driven repository pattern for MongoDB
+*
+* Production-grade MongoDB repositories with zero dependencies -
+* smart pagination, events, and plugins.
+*
+* @module @classytic/mongokit
+* @author Classytic (https://github.com/classytic)
+* @license MIT
+*
+* @example
+* ```typescript
+* import { createRepository } from '@classytic/mongokit';
+*
+* // Create repository with declarative config (plugins composed in the
+* // canonical safe order automatically)
+* const userRepo = createRepository(UserModel, {
+*   timestamps: true,
+*   softDelete: true,
+* });
+*
+* // Create
+* const user = await userRepo.create({ name: 'John', email: 'john@example.com' });
+*
+* // Read with pagination (auto-detects offset vs keyset)
+* const users = await userRepo.getAll({ page: 1, limit: 20 });
+*
+* // Keyset pagination for infinite scroll
+* const stream = await userRepo.getAll({ sort: { createdAt: -1 }, limit: 50 });
+* const nextStream = await userRepo.getAll({ after: stream.next, sort: { createdAt: -1 } });
+*
+* // Update
+* await userRepo.update(user._id, { name: 'John Doe' });
+*
+* // Delete
+* await userRepo.delete(user._id);
+* ```
+*/
 var src_default = Repository;
 //#endregion
 export { ALL_OPERATIONS, AggregationBuilder, AuditTrailQuery, HOOK_PRIORITY, LookupBuilder, MONGOKIT_CAPABILITIES, MUTATING_OPERATIONS, OP_REGISTRY, PaginationEngine, QueryParser, READ_OPERATIONS, Repository, actions_exports as actions, adminBypass, aggregateHelpersPlugin, auditLogPlugin, auditTrailPlugin, autoInject, batchOperationsPlugin, batchTransaction, blockIf, buildCrudSchemasFromModel, buildCrudSchemasFromMongooseSchema, cachePlugin, cascadePlugin, cascadePurgeReferences, compileFilterToMongo, configureLogger, createError, createFieldPreset, createMemoryCache, createOptionsExtractor, createRepository, createTenantContext, customIdPlugin, dateSequentialId, src_default as default, elasticSearchPlugin, fieldFilterPlugin, filterResponseData, getFieldsForUser, getMongooseProjection, getNextSequence, idVariants, immutableField, isDuplicateKeyError, isTransactionUnsupported, leasePlugin, methodRegistryPlugin, mongoOperationsPlugin, multiTenantPlugin, observabilityPlugin, operationsByPolicyKey, parseDuplicateKeyError, prefixedId, repoOptionsFromCtx, requireField, sequentialId, softDeletePlugin, subdocumentPlugin, systemContext, timestampPlugin, uniqueField, validationChainPlugin, withTransaction };

package/dist/lock/index.d.mts

@@ -1,6 +1,5 @@
 import { Connection } from "mongoose";
 import { BaseLockAdapterOptions, LockAdapter } from "@classytic/repo-core/lock";
-
 //#region src/lock/index.d.ts
 /** Adapter-construction options. */
 interface MongoLockAdapterOptions extends BaseLockAdapterOptions {

package/dist/{mongooseToJsonSchema-BdQJU39w.d.mts → mongooseToJsonSchema-D2CyAMIC.d.mts}

@@ -1,9 +1,8 @@
-import { C as FieldPreset, gt as UserContext } from "./types-CU3SEDbD.mjs";
+import { C as FieldPreset, gt as UserContext } from "./types-DNFMofHy.mjs";
 import mongoose, { Schema } from "mongoose";
 import { CacheAdapter } from "@classytic/repo-core/cache";
 import { CrudSchemas, SchemaBuilderOptions } from "@classytic/repo-core/schema";
 import { HttpError } from "@classytic/repo-core/errors";
-
 //#region src/utils/error.d.ts
 /** Optional structured fields for createError. */
 interface CreateErrorOptions {
@@ -170,9 +169,10 @@ interface SchemaLike {
   }>;
 }
 /**
- * Detect the _id path type from a Mongoose schema.
+ * Detect an id path's type from a Mongoose schema. Defaults to the `_id`
+ * path; pass `field` to resolve a custom id field (Repository's `idField`).
  *
- * Returns 'objectid' as the safe default when:
+ * For `_id`, returns 'objectid' as the safe default when:
  *   - No schema is provided (mock models, test harnesses)
  *   - The schema has no `paths._id` (auto-generated ObjectId)
  *   - The instance string is unrecognized
@@ -180,8 +180,12 @@ interface SchemaLike {
  * This safe-default means existing callers that don't set _id explicitly
  * get the same ObjectId validation they always had — the behavioral change
  * is strictly opt-in via schema declaration.
+ *
+ * For a custom `field` with no resolvable path, returns 'unknown' instead —
+ * custom id fields carry no ObjectId convention, so validation stays
+ * permissive and the DB remains the authority.
  */
-declare function getSchemaIdType(schema?: SchemaLike | null): IdType;
+declare function getSchemaIdType(schema?: SchemaLike | null, field?: string): IdType;
 /**
  * Validate an id value against a known _id type — WITHOUT hitting the DB.
  *

package/dist/{mongooseToJsonSchema-CBEQmeEa.mjs → mongooseToJsonSchema-khdzVo8x.mjs}

@@ -1,4 +1,4 @@
-import { r as isObjectIdInstance } from "./id-resolution-CnN0YA8t.mjs";
+import { r as isObjectIdInstance } from "./id-resolution-P2OzcyRl.mjs";
 import mongoose from "mongoose";
 import { applyFieldRules, collectFieldsToOmit } from "@classytic/repo-core/schema";
 //#region src/utils/memory-cache.ts

package/dist/multi-tenant.plugin-CTsWz0XK.d.mts

@@ -0,0 +1,486 @@
+import { B as ObjectId, G as Plugin, Q as RepositoryContext } from "./types-DNFMofHy.mjs";
+import mongoose from "mongoose";
+import { CacheAdapter as CacheAdapter$1, CacheOptions, RepositoryCacheHandle, RepositoryCachePluginOptions, cachePlugin } from "@classytic/repo-core/cache";
+import { TenantConfig } from "@classytic/repo-core/tenant";
+//#region src/plugins/audit-trail.plugin.d.ts
+interface AuditTrailOptions {
+  /** Operations to track (default: ['create', 'update', 'delete']) */
+  operations?: AuditOperation[];
+  /** Store field-level before/after diff on updates (default: true) */
+  trackChanges?: boolean;
+  /** Store full document snapshot on create (default: false — can be heavy) */
+  trackDocument?: boolean;
+  /** Auto-purge after N days via MongoDB TTL index (default: undefined — keep forever) */
+  ttlDays?: number;
+  /** MongoDB collection name (default: 'audit_trails') */
+  collectionName?: string;
+  /**
+   * Extract custom metadata from the repository context.
+   * Returned object is stored on the audit entry as `metadata`.
+   */
+  metadata?: (context: RepositoryContext) => Record<string, unknown>;
+  /**
+   * Fields to exclude from change tracking (e.g., passwords, tokens).
+   * These fields are redacted in the `changes` diff.
+   */
+  excludeFields?: string[];
+  /**
+   * Custom callback fired when an audit write fails. Receives the error
+   * and the entry that failed to land. Default: `console.warn` only.
+   *
+   * **Use this for compliance-grade audit trails (SOC 2 / PCI / HIPAA)
+   * where missing entries must be surfaced upstream** — e.g. forward to
+   * a dead-letter queue, page on-call, or short-circuit the request.
+   * The default `warn` log is appropriate for development and
+   * eventually-consistent observability use cases but is invisible to
+   * compliance review.
+   *
+   * The callback runs on the same fire-and-forget microtask that wrote
+   * the entry, so throwing from here will surface as an unhandled
+   * rejection — handle (or rethrow into your error reporter) inside.
+   */
+  onWriteError?: (error: Error, entry: Omit<AuditEntry, 'timestamp'>) => void;
+}
+type AuditOperation = 'create' | 'update' | 'delete' | 'findOneAndUpdate';
+interface AuditEntry {
+  model: string;
+  operation: AuditOperation;
+  documentId: unknown;
+  userId?: unknown;
+  orgId?: unknown;
+  changes?: Record<string, {
+    from: unknown;
+    to: unknown;
+  }>;
+  document?: Record<string, unknown>;
+  metadata?: Record<string, unknown>;
+  timestamp: Date;
+}
+declare function auditTrailPlugin(options?: AuditTrailOptions): Plugin;
+interface AuditQueryOptions {
+  model?: string;
+  documentId?: string | ObjectId;
+  userId?: string | ObjectId;
+  orgId?: string | ObjectId;
+  operation?: AuditOperation;
+  from?: Date;
+  to?: Date;
+  page?: number;
+  limit?: number;
+}
+interface AuditQueryResult {
+  data: AuditEntry[];
+  page: number;
+  limit: number;
+  total: number;
+  pages: number;
+  hasNext: boolean;
+  hasPrev: boolean;
+}
+/**
+ * Standalone audit trail query utility.
+ * Use this to query audits across all models — e.g., admin dashboards, audit APIs.
+ *
+ * @example
+ * ```typescript
+ * import { AuditTrailQuery } from '@classytic/mongokit';
+ *
+ * const auditQuery = new AuditTrailQuery(); // defaults to 'audit_trails' collection
+ *
+ * // All audits for an org
+ * const orgAudits = await auditQuery.query({ orgId: '...' });
+ *
+ * // All updates by a user
+ * const userUpdates = await auditQuery.query({
+ *   userId: '...',
+ *   operation: 'update',
+ * });
+ *
+ * // All audits for a specific document
+ * const docHistory = await auditQuery.query({
+ *   model: 'Job',
+ *   documentId: '...',
+ * });
+ *
+ * // Date range
+ * const recent = await auditQuery.query({
+ *   from: new Date('2025-01-01'),
+ *   to: new Date(),
+ *   page: 1,
+ *   limit: 50,
+ * });
+ *
+ * // Direct model access for custom queries
+ * const model = auditQuery.getModel();
+ * const count = await model.countDocuments({ operation: 'delete' });
+ * ```
+ */
+declare class AuditTrailQuery {
+  private model;
+  constructor(collectionName?: string, ttlDays?: number);
+  /**
+   * Get the underlying Mongoose model for custom queries
+   */
+  getModel(): mongoose.Model<AuditEntry>;
+  /**
+   * Query audit entries with filters and pagination
+   */
+  query(options?: AuditQueryOptions): Promise<AuditQueryResult>;
+  /**
+   * Get audit trail for a specific document
+   */
+  getDocumentTrail(model: string, documentId: string | ObjectId, options?: {
+    page?: number;
+    limit?: number;
+    operation?: AuditOperation;
+  }): Promise<AuditQueryResult>;
+  /**
+   * Get all audits for a user
+   */
+  getUserTrail(userId: string | ObjectId, options?: {
+    page?: number;
+    limit?: number;
+    operation?: AuditOperation;
+    orgId?: string | ObjectId;
+  }): Promise<AuditQueryResult>;
+  /**
+   * Get all audits for an organization
+   */
+  getOrgTrail(orgId: string | ObjectId, options?: {
+    page?: number;
+    limit?: number;
+    operation?: AuditOperation;
+    model?: string;
+  }): Promise<AuditQueryResult>;
+}
+interface AuditTrailMethods {
+  /**
+   * Get paginated audit trail for a document
+   */
+  getAuditTrail(documentId: string | ObjectId, options?: {
+    page?: number;
+    limit?: number;
+    operation?: AuditOperation;
+  }): Promise<AuditQueryResult>;
+}
+//#endregion
+//#region src/plugins/custom-id.plugin.d.ts
+/**
+ * Generator function that produces a unique ID.
+ * Receives the full repository context for conditional logic.
+ */
+type IdGenerator = (context: RepositoryContext) => string | Promise<string>;
+interface CustomIdOptions {
+  /** Field to store the custom ID (default: 'customId') */
+  field?: string;
+  /** Function to generate the ID. Can be async. */
+  generator: IdGenerator;
+  /** Only generate if the field is missing/empty (default: true) */
+  generateOnlyIfEmpty?: boolean;
+}
+/**
+ * Atomically increment and return the next sequence value for a given key.
+ * Uses `findOneAndUpdate` with `upsert` + `$inc` — fully atomic even under
+ * heavy concurrency.
+ *
+ * @param counterKey - Unique key identifying this counter (e.g., "Invoice" or "Invoice:2026-02")
+ * @param increment - Value to increment by (default: 1)
+ * @param connection - Mongoose connection to use (defaults to the default connection)
+ * @param session - Optional client session. When provided, the counter bump
+ *   participates in the caller's transaction — if the surrounding transaction
+ *   aborts, the counter does NOT advance. Without a session, the bump commits
+ *   immediately and is not rolled back if a sibling write fails.
+ * @returns The next sequence number (after increment)
+ *
+ * @example
+ * const seq = await getNextSequence('invoices');
+ * // First call → 1, second → 2, ...
+ *
+ * @example Batch increment for createMany
+ * const startSeq = await getNextSequence('invoices', 5);
+ * // If current was 10, returns 15 (you use 11, 12, 13, 14, 15)
+ *
+ * @example Transactional counter bump
+ * await withTransaction(conn, async (session) => {
+ *   const seq = await getNextSequence('invoices', 1, conn, session);
+ *   await invoiceRepo.create({ invoiceNumber: `INV-${seq}` }, { session });
+ *   // if this throws, the counter is rolled back with the insert
+ * });
+ */
+declare function getNextSequence(counterKey: string, increment?: number, connection?: mongoose.Connection, session?: mongoose.ClientSession): Promise<number>;
+interface SequentialIdOptions {
+  /** Prefix string (e.g., 'INV', 'ORD') */
+  prefix: string;
+  /** Mongoose model — used to derive the counter key from model name */
+  model: mongoose.Model<any>;
+  /** Number of digits to pad to (default: 4 → "0001") */
+  padding?: number;
+  /** Separator between prefix and number (default: '-') */
+  separator?: string;
+  /** Custom counter key override (default: model.modelName) */
+  counterKey?: string;
+}
+/**
+ * Generator: Simple sequential counter.
+ * Produces IDs like `INV-0001`, `INV-0002`, etc.
+ *
+ * Uses atomic MongoDB counters — safe under concurrency.
+ *
+ * @example
+ * ```typescript
+ * customIdPlugin({
+ *   field: 'invoiceNumber',
+ *   generator: sequentialId({ prefix: 'INV', model: InvoiceModel }),
+ * })
+ * ```
+ */
+declare function sequentialId(options: SequentialIdOptions): IdGenerator;
+interface DateSequentialIdOptions {
+  /** Prefix string (e.g., 'BILL', 'INV') */
+  prefix: string;
+  /** Mongoose model — used to derive the counter key */
+  model: mongoose.Model<any>;
+  /**
+   * Partition granularity — counter resets each period.
+   * - 'yearly'  → BILL-2026-0001, resets every January
+   * - 'monthly' → BILL-2026-02-0001, resets every month
+   * - 'daily'   → BILL-2026-02-20-0001, resets every day
+   */
+  partition?: 'yearly' | 'monthly' | 'daily';
+  /** Number of digits to pad to (default: 4) */
+  padding?: number;
+  /** Separator (default: '-') */
+  separator?: string;
+}
+/**
+ * Generator: Date-partitioned sequential counter.
+ * Counter resets per period — great for invoice/bill numbering.
+ *
+ * Produces IDs like:
+ * - yearly:  `BILL-2026-0001`
+ * - monthly: `BILL-2026-02-0001`
+ * - daily:   `BILL-2026-02-20-0001`
+ *
+ * @example
+ * ```typescript
+ * customIdPlugin({
+ *   field: 'billNumber',
+ *   generator: dateSequentialId({
+ *     prefix: 'BILL',
+ *     model: BillModel,
+ *     partition: 'monthly',
+ *   }),
+ * })
+ * ```
+ */
+declare function dateSequentialId(options: DateSequentialIdOptions): IdGenerator;
+interface PrefixedIdOptions {
+  /** Prefix string (e.g., 'USR', 'TXN') */
+  prefix: string;
+  /** Separator (default: '_') */
+  separator?: string;
+  /** Length of the random suffix (default: 12) */
+  length?: number;
+}
+/**
+ * Generator: Prefix + random alphanumeric suffix.
+ * Does NOT require a database round-trip — purely in-memory.
+ *
+ * Produces IDs like: `USR_a7b3xk9m2p1q`
+ *
+ * Good for: user-facing IDs where ordering doesn't matter.
+ * Not suitable for sequential numbering.
+ *
+ * @example
+ * ```typescript
+ * customIdPlugin({
+ *   field: 'publicId',
+ *   generator: prefixedId({ prefix: 'USR', length: 10 }),
+ * })
+ * ```
+ */
+declare function prefixedId(options: PrefixedIdOptions): IdGenerator;
+/**
+ * Custom ID plugin — injects generated IDs into documents before creation.
+ *
+ * @param options - Configuration for ID generation
+ * @returns Plugin instance
+ *
+ * @example
+ * ```typescript
+ * import { Repository, customIdPlugin, sequentialId } from '@classytic/mongokit';
+ *
+ * const invoiceRepo = new Repository(InvoiceModel, [
+ *   customIdPlugin({
+ *     field: 'invoiceNumber',
+ *     generator: sequentialId({ prefix: 'INV', model: InvoiceModel }),
+ *   }),
+ * ]);
+ *
+ * const inv = await invoiceRepo.create({ amount: 100 });
+ * console.log(inv.invoiceNumber); // "INV-0001"
+ * ```
+ */
+declare function customIdPlugin(options: CustomIdOptions): Plugin;
+//#endregion
+//#region src/plugins/multi-tenant.plugin.d.ts
+/**
+ * Static tenant fields are picked from `@classytic/repo-core/tenant` so the
+ * vocabulary (`tenantField`, `contextKey`, `required`, `fieldType`) stays
+ * locked to the org-wide canonical source. Mongokit-specific runtime
+ * callbacks (`skipWhen`, `resolveContext`, `skipOperations`,
+ * `allowDataInjection`) extend on top — those genuinely differ from
+ * sqlitekit's runtime shape because mongokit's `RepositoryContext` carries
+ * Mongoose-specific bits the resolver may inspect.
+ *
+ * Mongokit defaults `fieldType` to `'string'` (not repo-core's `'objectId'`)
+ * for back-compat — pre-3.x stored tenant ids as raw strings; flipping the
+ * default would silently change cast behavior for existing apps.
+ */
+interface MultiTenantOptions extends Pick<TenantConfig, 'tenantField' | 'contextKey' | 'required' | 'fieldType'> {
+  /** Operations to skip tenant injection (e.g., for admin/system queries) */
+  skipOperations?: string[];
+  /**
+   * Dynamic skip — receives the context and operation name, returns true to
+   * bypass tenant scoping for this call. Use for role-based bypass (e.g.,
+   * super admin) without needing a separate repo instance.
+   *
+   * @example
+   * ```typescript
+   * skipWhen: (context) => context.role === 'superadmin'
+   * ```
+   */
+  skipWhen?: (context: RepositoryContext, operation: string) => boolean;
+  /**
+   * Resolve tenant ID from external source (e.g., AsyncLocalStorage, CLS).
+   * Called when tenant ID is not found in context. If it returns a value,
+   * that value is used as the tenant ID without requiring it in context.
+   *
+   * @example
+   * ```typescript
+   * resolveContext: () => asyncLocalStorage.getStore()?.tenantId
+   * ```
+   */
+  resolveContext?: () => string | undefined;
+  /**
+   * When `true`, bypass the `required` throw if the operation's policy
+   * target already carries the tenant field. This lets hosts that stamp
+   * the tenant into the payload themselves (e.g., `data[tenantField]`
+   * on writes, `filters[tenantField]` on paginated reads) use the plugin
+   * without having to hand-roll a `skipWhen` that duplicates this check.
+   *
+   * **Default: `false` (secure / fail-closed).** Tenant scope MUST come
+   * from `context` or `resolveContext`, otherwise the plugin throws
+   * (when `required: true`). This is the right posture for a security-
+   * sensitive boundary: caller-supplied scope on the payload cannot be
+   * trusted as authentication. If a host control-plane has already
+   * authenticated the tenant out-of-band and stamps it onto every
+   * write/read, set this to `true` explicitly — making the trust model
+   * visible at the call site.
+   *
+   * **Migration from < 4.0:** the prior default was `true`. To preserve
+   * the old behavior verbatim, set `allowDataInjection: true`. To get
+   * the new secure default, leave it unset.
+   *
+   * Composition: a user-supplied `skipWhen` still runs first and can
+   * always opt out. This option controls the behavior after `skipWhen`
+   * and `resolveContext` have had their turn.
+   *
+   * Safety: when the payload supplies the tenant AND this is `true`,
+   * the plugin skips its own injection (it does not overwrite). Cross-
+   * tenant isolation is therefore only as strong as the caller's own
+   * stamping — same guarantee as a hand-rolled `skipWhen`.
+   */
+  allowDataInjection?: boolean;
+  /**
+   * What to do when the call's filter/payload ALREADY carries
+   * `tenantField` with a value that does NOT match the resolved tenant
+   * scope (a caller-supplied cross-tenant value — fat-fingered org id,
+   * stale client state, or an injection attempt).
+   *
+   * - `'throw'` (default, fail-closed): reject the call with a clear
+   *   error. A mismatch is never legitimate on a scoped call — callers
+   *   who genuinely need cross-tenant access use `bypassTenant: true`
+   *   (per-call) or `skipWhen` (plugin-level), both of which emit the
+   *   `after:tenant-bypass` audit event. Operator-shaped values
+   *   (`{ $in: [...] }`) on the tenant field can't be verified against
+   *   the scope and are rejected too — multi-value tenant scoping is
+   *   deliberately not supported (see CLAUDE.md); use an explicit
+   *   bypass + manual filter.
+   * - `'overwrite'` (legacy, pre-3.16 behavior): silently replace the
+   *   supplied value with the resolved scope. Still leak-safe (the
+   *   resolved scope always wins) but hides caller bugs.
+   *
+   * Matching values (same tenant, any representation — string vs
+   * ObjectId) are never a mismatch; the plugin normalizes them to the
+   * configured `fieldType`.
+   */
+  onMismatch?: 'throw' | 'overwrite';
+}
+declare function multiTenantPlugin(options?: MultiTenantOptions): Plugin;
+/**
+ * Build the canonical `skipWhen` callback for role-based tenant
+ * bypass — replaces the hand-rolled
+ * `(ctx) => ctx.role === 'superadmin'` callback that ~6 packages
+ * across the classytic codebase carry as boilerplate. Eliminates the
+ * "I forgot to include 'platform_admin'" drift class — the role
+ * vocabulary lives in one place.
+ *
+ * **Composes with `bypassTenant: true` per-call**, doesn't replace
+ * it. `bypassTenant` is the deliberate per-call form for migration
+ * scripts and one-off admin queries; `adminBypass` is the
+ * always-on role-based bypass for users whose JWT / session carries
+ * a privileged role.
+ *
+ * **NOT a substitute for authentication or RBAC.** This factory only
+ * answers "should the tenant scope hook fire for this call?" — it
+ * does NOT validate that the caller is authenticated, that their
+ * role claim is genuine, or that the requested operation is
+ * permitted. Always run auth + RBAC before the call reaches the
+ * repository layer; this is the LAST gate, not the only one.
+ *
+ * @example Single role
+ * ```ts
+ * import { adminBypass, multiTenantPlugin } from '@classytic/mongokit';
+ *
+ * const repo = new Repository(InvoiceModel, [
+ *   multiTenantPlugin({
+ *     tenantField: 'organizationId',
+ *     skipWhen: adminBypass({ adminRoles: ['superadmin'] }),
+ *   }),
+ * ]);
+ *
+ * await repo.getAll({}, { role: 'superadmin' }); // sees all orgs
+ * await repo.getAll({}, { role: 'user', organizationId: 'org-1' }); // scoped
+ * ```
+ *
+ * @example Multiple admin roles + custom field name
+ * ```ts
+ * skipWhen: adminBypass({
+ *   roleField: 'principalRole',                  // ctx.principalRole, not ctx.role
+ *   adminRoles: ['superadmin', 'platform_admin', 'support'],
+ * }),
+ * ```
+ *
+ * @example Composing with custom logic
+ * ```ts
+ * // adminBypass for the role check, then your own additional logic:
+ * const adminCheck = adminBypass({ adminRoles: ['superadmin'] });
+ * skipWhen: (ctx, op) => adminCheck(ctx, op) || ctx.internalSystemFlag === true,
+ * ```
+ *
+ * @param options.roleField - Path on the context to read the role
+ *   from. Defaults to `'role'`. Top-level keys only — for nested
+ *   shapes (e.g. `ctx.user.role`), wrap your own `(ctx) => …` callback
+ *   instead.
+ * @param options.adminRoles - Role values that grant the bypass. The
+ *   factory does an exact-match `includes` check — case-sensitive,
+ *   no fuzzy matching. Lowercase your role vocabulary upstream.
+ * @returns A `skipWhen`-compatible callback `(ctx, op) → boolean`.
+ */
+declare function adminBypass(options: {
+  roleField?: string;
+  adminRoles: readonly string[];
+}): (context: RepositoryContext, operation: string) => boolean;
+//#endregion
+export { AuditTrailMethods as C, auditTrailPlugin as E, AuditQueryResult as S, AuditTrailQuery as T, RepositoryCachePluginOptions as _, DateSequentialIdOptions as a, AuditOperation as b, SequentialIdOptions as c, getNextSequence as d, prefixedId as f, RepositoryCacheHandle as g, CacheOptions as h, CustomIdOptions as i, customIdPlugin as l, CacheAdapter$1 as m, adminBypass as n, IdGenerator as o, sequentialId as p, multiTenantPlugin as r, PrefixedIdOptions as s, MultiTenantOptions as t, dateSequentialId as u, cachePlugin as v, AuditTrailOptions as w, AuditQueryOptions as x, AuditEntry as y };