@classytic/repo-core 0.2.0 → 0.4.0

package/dist/adapter/types.d.mts

@@ -0,0 +1,222 @@
+import { DeleteResult, MinimalRepo, StandardRepo } from "../repository/types.mjs";
+import { SchemaBuilderOptions } from "../schema/types.mjs";
+
+//#region src/adapter/types.d.ts
+/**
+ * Cross-kit repository contract.
+ *
+ * Defined as `MinimalRepo<TDoc> & Partial<StandardRepo<TDoc>>` — the
+ * 5-method floor every kit must implement, plus every other
+ * `StandardRepo` method (atomic CAS, batch ops, aggregation, soft-delete,
+ * transactions) as optional. Hosts feature-detect optional methods at
+ * call sites; kits declare only what they implement.
+ *
+ * **Why compound and not `StandardRepo` alone:** forcing every kit to
+ * implement the full surface would break kits with partial capabilities
+ * (sqlitekit has no aggregation, prismakit has no native atomic CAS the
+ * same way). Hosts use `typeof repo.method === 'function'` checks at
+ * construction.
+ *
+ * **Why compound and not `MinimalRepo` alone:** internal subsystems
+ * (audit, outbox, idempotency stores) need `StandardRepo` type info at
+ * call sites. `Partial<StandardRepo>` keeps the type-level backing
+ * without forcing every kit to implement everything.
+ */
+type RepositoryLike<TDoc = unknown> = MinimalRepo<TDoc> & Partial<StandardRepo<TDoc>>;
+/**
+ * Permissive structural input accepted at every adapter factory boundary.
+ *
+ * Wider than `RepositoryLike<TDoc>` on `getAll`'s `params`/`options` —
+ * uses method-shorthand syntax with `unknown` so kit-native repository
+ * classes plug in directly without `as RepositoryLike<TDoc>` casts on
+ * the host.
+ *
+ * **Why this exists.** repo-core 0.2 widened `MinimalRepo['getAll']`'s
+ * `params.filters` to a `Filter | Record<string, unknown>` IR union, but
+ * concrete kit `Repository` classes still type `filters` as the narrower
+ * `Record<string, unknown>`. Under `strictFunctionTypes` the kit's
+ * narrower function-property `getAll` is no longer assignable to the
+ * IR-aware one, which forced every host adapter glue file to write
+ * `repository as unknown as RepositoryLike<TDoc>`.
+ *
+ * Adapter factories accept this permissive shape, then call
+ * `asRepositoryLike()` once to widen for host internals (which still see
+ * the strict `RepositoryLike` view). The documented escape hatch lives
+ * in repo-core, not at every host call site.
+ */
+interface AdapterRepositoryInput<TDoc = unknown> {
+  readonly idField?: string;
+  getAll(params?: unknown, options?: unknown): Promise<unknown>;
+  getById(id: string, options?: unknown): Promise<TDoc | null>;
+  create(data: Partial<TDoc>, options?: unknown): Promise<TDoc>;
+  update(id: string, data: Partial<TDoc>, options?: unknown): Promise<TDoc | null>;
+  delete(id: string, options?: unknown): Promise<DeleteResult | null>;
+}
+/**
+ * Generic OpenAPI-shaped schema bag emitted by `DataAdapter.generateSchemas`.
+ *
+ * Loose `unknown` slots so kits emit JSON Schema or kit-native shapes
+ * without type pressure. Hosts that want a specific shape (Fastify route
+ * schemas, Zod models, ...) narrow on consumption.
+ */
+interface OpenApiSchemas {
+  /** Resource entity schema (the row shape). */
+  entity?: unknown;
+  /** Create-body schema (POST / PUT body). */
+  createBody?: unknown;
+  /** Update-body schema (PATCH body). */
+  updateBody?: unknown;
+  /** Path-params schema (`/:id`). */
+  params?: unknown;
+  /** List-query querystring schema (filtering / pagination / sort). */
+  listQuery?: unknown;
+  /**
+   * Response schema for OpenAPI documentation. Auto-derived from the
+   * entity / create-body shape if omitted.
+   */
+  response?: unknown;
+  [key: string]: unknown;
+}
+/**
+ * Context passed to `adapter.generateSchemas()` so adapters shape output
+ * to match host-level configuration. All fields optional — adapters that
+ * ignore this still work; the host applies its own normalization.
+ */
+interface AdapterSchemaContext {
+  /** The `idField` configured on the resource. Defaults to `_id`. */
+  idField?: string;
+  /** Resource name (for error messages / logging). */
+  resourceName?: string;
+}
+/**
+ * Field-level metadata returned by `getSchemaMetadata()`. JSON-Schema-
+ * adjacent vocabulary kept driver-free so introspection tooling can
+ * consume any kit's output uniformly.
+ */
+interface FieldMetadata {
+  type: 'string' | 'number' | 'boolean' | 'date' | 'object' | 'array' | 'objectId' | 'enum';
+  required?: boolean;
+  unique?: boolean;
+  default?: unknown;
+  enum?: Array<string | number>;
+  min?: number;
+  max?: number;
+  minLength?: number;
+  maxLength?: number;
+  pattern?: string;
+  description?: string;
+  ref?: string;
+  array?: boolean;
+}
+/**
+ * Relation metadata returned by `getSchemaMetadata()`.
+ */
+interface RelationMetadata {
+  type: 'one-to-one' | 'one-to-many' | 'many-to-many';
+  target: string;
+  foreignKey?: string;
+  through?: string;
+}
+/**
+ * Schema metadata returned by `getSchemaMetadata()`. Shape-only — no kit
+ * types leak through.
+ */
+interface SchemaMetadata {
+  name: string;
+  fields: Record<string, FieldMetadata>;
+  indexes?: Array<{
+    fields: string[];
+    unique?: boolean;
+    sparse?: boolean;
+  }>;
+  relations?: Record<string, RelationMetadata>;
+}
+/**
+ * Result of `adapter.validate()`. Structurally identical to repo-core's
+ * `schema/types.ts` `ValidationResult` for the message/violations shape,
+ * but uses `errors[]` (the OpenAPI/AJV convention) for adapter-time
+ * validation. Kept distinct so adapter validation and update-body
+ * validation can evolve independently.
+ */
+interface AdapterValidationResult {
+  valid: boolean;
+  errors?: Array<{
+    field: string;
+    message: string;
+    code?: string;
+  }>;
+}
+/**
+ * Cross-framework data-adapter contract.
+ *
+ * A kit's `createXxxAdapter()` factory produces an instance of this
+ * interface. Frameworks (arc, custom hosts) consume the same shape; the
+ * kit never imports the framework.
+ */
+interface DataAdapter<TDoc = unknown> {
+  /**
+   * Repository implementing CRUD operations. Any value that satisfies
+   * `RepositoryLike<TDoc>` — which includes `StandardRepo<TDoc>` (all
+   * methods implemented), `MinimalRepo<TDoc>` (5-method floor), or
+   * anything in between a kit declares. Hosts feature-detect optional
+   * methods at runtime.
+   */
+  repository: RepositoryLike<TDoc>;
+  /** Adapter identifier for introspection. */
+  readonly type: 'mongoose' | 'prisma' | 'drizzle' | 'typeorm' | 'custom';
+  /** Human-readable name. */
+  readonly name: string;
+  /**
+   * Generate OpenAPI-shaped schemas for CRUD operations. Each adapter
+   * produces schemas appropriate to its ORM/database (mongokit
+   * introspects Mongoose paths; sqlitekit introspects Drizzle columns).
+   *
+   * Options use repo-core's `SchemaBuilderOptions` floor — host-specific
+   * extensions (arc's `RouteSchemaOptions`) extend this base structurally.
+   *
+   * @param options - Schema generation options (field rules, populate hints).
+   * @param context - Resource-level context (`idField` for params shape,
+   *   `name` for logs).
+   */
+  generateSchemas?(options?: SchemaBuilderOptions, context?: AdapterSchemaContext): OpenApiSchemas | Record<string, unknown> | null;
+  /** Extract schema metadata for OpenAPI / introspection. */
+  getSchemaMetadata?(): SchemaMetadata | null;
+  /** Validate data against schema before persistence. */
+  validate?(data: unknown): Promise<AdapterValidationResult> | AdapterValidationResult;
+  /** Health check for database connection. */
+  healthCheck?(): Promise<boolean>;
+  /**
+   * Custom filter matching for in-memory policy enforcement. Falls back
+   * to the host's built-in shallow matcher when omitted. Override for
+   * SQL adapters, non-Mongo operators, or kits that compile Filter IR.
+   */
+  matchesFilter?: (item: unknown, filters: Record<string, unknown>) => boolean;
+  /** Close / cleanup resources. */
+  close?(): Promise<void>;
+  /**
+   * Optional: does the underlying schema declare a path with this name?
+   *
+   * Used by hosts (e.g. arc's `defineResource()`) to infer absent tenant
+   * fields — without this hook, hosts who forget `tenantField: false` on
+   * cross-tenant tables get queries silently filtered to zero results.
+   * Adapters that can introspect their schema implement it; ones that
+   * can't omit it (the host falls back to its default behaviour).
+   *
+   * Implementation guidance:
+   *   - Mongoose: `Boolean(this.model.schema.paths[name])`.
+   *   - Drizzle / SQL kits: check column metadata.
+   *
+   * @returns `true` if the schema declares the path, `false` if not,
+   *   `undefined` if the adapter can't determine it (treated as
+   *   "unknown" — same as omitting the method).
+   */
+  hasFieldPath?(name: string): boolean | undefined;
+}
+/**
+ * Adapter factory signature. A kit's `createXxxAdapter(config)` matches
+ * this shape — config is kit-specific so adapters can accept their own
+ * options (e.g. `{ model, schemaGenerator, ... }`).
+ */
+type AdapterFactory<TDoc = unknown> = (config: unknown) => DataAdapter<TDoc>;
+//#endregion
+export { AdapterFactory, AdapterRepositoryInput, AdapterSchemaContext, AdapterValidationResult, DataAdapter, FieldMetadata, OpenApiSchemas, RelationMetadata, RepositoryLike, SchemaMetadata };

package/dist/adapter/widen.d.mts

@@ -0,0 +1,22 @@
+import { AdapterRepositoryInput, RepositoryLike } from "./types.mjs";
+
+//#region src/adapter/widen.d.ts
+/**
+ * Widen a permissive `AdapterRepositoryInput<TDoc>` to the strict
+ * `RepositoryLike<TDoc>` view used by host internals.
+ *
+ * Single-source cast — kit adapters call this once at their factory
+ * boundary; host code (arc, future arc-next) consumes the strict view
+ * everywhere else.
+ */
+declare function asRepositoryLike<TDoc = unknown>(input: AdapterRepositoryInput<TDoc>): RepositoryLike<TDoc>;
+/**
+ * Runtime guard: does `value` look like a `RepositoryLike<TDoc>`?
+ *
+ * Checks for the five required methods (`getAll`, `getById`, `create`,
+ * `update`, `delete`) plus the optional `idField`. Used by adapter
+ * factories to validate input before wrapping.
+ */
+declare function isRepository<TDoc = unknown>(value: unknown): value is RepositoryLike<TDoc>;
+//#endregion
+export { asRepositoryLike, isRepository };

package/dist/adapter/widen.mjs

@@ -0,0 +1,26 @@
+//#region src/adapter/widen.ts
+/**
+* Widen a permissive `AdapterRepositoryInput<TDoc>` to the strict
+* `RepositoryLike<TDoc>` view used by host internals.
+*
+* Single-source cast — kit adapters call this once at their factory
+* boundary; host code (arc, future arc-next) consumes the strict view
+* everywhere else.
+*/
+function asRepositoryLike(input) {
+	return input;
+}
+/**
+* Runtime guard: does `value` look like a `RepositoryLike<TDoc>`?
+*
+* Checks for the five required methods (`getAll`, `getById`, `create`,
+* `update`, `delete`) plus the optional `idField`. Used by adapter
+* factories to validate input before wrapping.
+*/
+function isRepository(value) {
+	if (!value || typeof value !== "object") return false;
+	const v = value;
+	return typeof v["getAll"] === "function" && typeof v["getById"] === "function" && typeof v["create"] === "function" && typeof v["update"] === "function" && typeof v["delete"] === "function";
+}
+//#endregion
+export { asRepositoryLike, isRepository };

package/dist/aggregate/index.d.mts

@@ -0,0 +1,3 @@
+import { DecodedCursor, decodeAggCursor, encodeAggCursor, isKeysetMode } from "./keyset.mjs";
+import { normalizeGroupBy, validateMeasures } from "./normalize.mjs";
+export { type DecodedCursor, decodeAggCursor, encodeAggCursor, isKeysetMode, normalizeGroupBy, validateMeasures };

package/dist/aggregate/index.mjs

@@ -0,0 +1,3 @@
+import { decodeAggCursor, encodeAggCursor, isKeysetMode } from "./keyset.mjs";
+import { normalizeGroupBy, validateMeasures } from "./normalize.mjs";
+export { decodeAggCursor, encodeAggCursor, isKeysetMode, normalizeGroupBy, validateMeasures };

package/dist/aggregate/keyset.d.mts

@@ -0,0 +1,57 @@
+//#region src/aggregate/keyset.d.ts
+/**
+ * Keyset (cursor) pagination helpers — the portable, kit-neutral half.
+ *
+ * Cursor encode/decode is identical across kits: serialize the sort-key
+ * tuple of the last row, base64url it, hand back. Every kit's
+ * `aggregatePaginate(req)` produced byte-identical encodings before
+ * this module landed — the duplication served no purpose.
+ *
+ * What this module does NOT cover: building the kit-specific predicate
+ * that selects rows AFTER the cursor. Mongo emits a `$match` JSON
+ * stage; SQL emits a `HAVING (col1, col2) > (?, ?)` Drizzle SQL
+ * fragment. Those compilers stay in each kit because they speak the
+ * driver's query language. They consume `DecodedCursor` from here.
+ *
+ * **Cross-kit cursor compatibility is not promised.** The encoded
+ * cursor depends on which keys the kit's sort spec ends up using — a
+ * Mongo cursor with `_id` won't round-trip on a SQL kit using `id`.
+ * Consumers MUST round-trip cursors verbatim against the same backend
+ * that produced them.
+ */
+/**
+ * Decoded cursor — sort-key → value tuples from the last row of the
+ * prior page. Values are JSON-serialisable scalars (numbers, strings,
+ * booleans, ISO date strings). `undefined` and `null` collapse to
+ * `null` on encode so the round-trip is stable.
+ */
+type DecodedCursor = Record<string, unknown>;
+/**
+ * Encode a cursor from the last row of a page given the sort spec.
+ *
+ * Only sort keys are extracted — the cursor MUST be small (it travels
+ * over the URL on every "next page" request). Carrying the full row
+ * would inflate cursors with measure values and group keys that
+ * aren't load-bearing for pagination.
+ */
+declare function encodeAggCursor(row: Record<string, unknown>, sort: Record<string, 1 | -1>): string;
+/**
+ * Decode a cursor previously produced by `encodeAggCursor`. Throws on
+ * any malformed cursor — callers should treat the throw as "client
+ * sent garbage" and surface a 400-class error rather than masking it.
+ *
+ * The `kitName` prefix on the error message keeps stack-trace context
+ * legible (`'mongokit/aggregate: ...'` vs `'sqlitekit/aggregate: ...'`).
+ */
+declare function decodeAggCursor(cursor: string, kitName: string): DecodedCursor;
+/**
+ * Pick the keyset mode flag from the request shape. `pagination:
+ * 'keyset'` is the explicit form; setting `after` implies keyset
+ * (handing back a cursor token in offset mode would be a wiring bug).
+ */
+declare function isKeysetMode(req: {
+  pagination?: string;
+  after?: string;
+}): boolean;
+//#endregion
+export { DecodedCursor, decodeAggCursor, encodeAggCursor, isKeysetMode };

package/dist/aggregate/keyset.mjs

@@ -0,0 +1,45 @@
+//#region src/aggregate/keyset.ts
+/**
+* Encode a cursor from the last row of a page given the sort spec.
+*
+* Only sort keys are extracted — the cursor MUST be small (it travels
+* over the URL on every "next page" request). Carrying the full row
+* would inflate cursors with measure values and group keys that
+* aren't load-bearing for pagination.
+*/
+function encodeAggCursor(row, sort) {
+	const tuple = {};
+	for (const key of Object.keys(sort)) tuple[key] = row[key];
+	return Buffer.from(JSON.stringify(tuple), "utf8").toString("base64url");
+}
+/**
+* Decode a cursor previously produced by `encodeAggCursor`. Throws on
+* any malformed cursor — callers should treat the throw as "client
+* sent garbage" and surface a 400-class error rather than masking it.
+*
+* The `kitName` prefix on the error message keeps stack-trace context
+* legible (`'mongokit/aggregate: ...'` vs `'sqlitekit/aggregate: ...'`).
+*/
+function decodeAggCursor(cursor, kitName) {
+	let parsed;
+	try {
+		const json = Buffer.from(cursor, "base64url").toString("utf8");
+		parsed = JSON.parse(json);
+	} catch (cause) {
+		throw new Error(`${kitName}/aggregate: malformed keyset cursor — base64url+JSON decode failed (${cause.message})`);
+	}
+	if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) throw new Error(`${kitName}/aggregate: malformed keyset cursor — expected an object payload`);
+	return parsed;
+}
+/**
+* Pick the keyset mode flag from the request shape. `pagination:
+* 'keyset'` is the explicit form; setting `after` implies keyset
+* (handing back a cursor token in offset mode would be a wiring bug).
+*/
+function isKeysetMode(req) {
+	if (req.pagination === "keyset") return true;
+	if (typeof req.after === "string" && req.after.length > 0) return true;
+	return false;
+}
+//#endregion
+export { decodeAggCursor, encodeAggCursor, isKeysetMode };

package/dist/aggregate/normalize.d.mts

@@ -0,0 +1,24 @@
+import { AggRequest } from "../repository/types.mjs";
+
+//#region src/aggregate/normalize.d.ts
+/**
+ * Normalize `AggRequest['groupBy']` into a readonly string array.
+ * Returns `[]` for scalar aggregation (no groupBy). Downstream
+ * compilers treat `[]` uniformly — Mongo emits `$group: { _id: null }`,
+ * SQL emits a single SELECT without a GROUP BY clause.
+ */
+declare function normalizeGroupBy(groupBy: AggRequest['groupBy']): readonly string[];
+/**
+ * Fail loud on an empty measures bag — there's nothing to compute and
+ * the caller's code path is almost certainly a wiring bug (conditional
+ * collapsed, key renamed, etc.). Silently returning `{ rows: [] }`
+ * would mask it.
+ *
+ * The `kitName` prefix (`'mongokit'`, `'sqlitekit'`, ...) on the error
+ * message keeps stack-trace context legible — when a developer sees
+ * the throw they know which kit's compiler raised it without having
+ * to walk the trace.
+ */
+declare function validateMeasures(measures: AggRequest['measures'], kitName: string): void;
+//#endregion
+export { normalizeGroupBy, validateMeasures };

package/dist/aggregate/normalize.mjs

@@ -0,0 +1,28 @@
+//#region src/aggregate/normalize.ts
+/**
+* Normalize `AggRequest['groupBy']` into a readonly string array.
+* Returns `[]` for scalar aggregation (no groupBy). Downstream
+* compilers treat `[]` uniformly — Mongo emits `$group: { _id: null }`,
+* SQL emits a single SELECT without a GROUP BY clause.
+*/
+function normalizeGroupBy(groupBy) {
+	if (!groupBy) return [];
+	if (typeof groupBy === "string") return [groupBy];
+	return groupBy;
+}
+/**
+* Fail loud on an empty measures bag — there's nothing to compute and
+* the caller's code path is almost certainly a wiring bug (conditional
+* collapsed, key renamed, etc.). Silently returning `{ rows: [] }`
+* would mask it.
+*
+* The `kitName` prefix (`'mongokit'`, `'sqlitekit'`, ...) on the error
+* message keeps stack-trace context legible — when a developer sees
+* the throw they know which kit's compiler raised it without having
+* to walk the trace.
+*/
+function validateMeasures(measures, kitName) {
+	if (!measures || Object.keys(measures).length === 0) throw new Error(`${kitName}/aggregate: AggRequest requires at least one measure — empty measures bag is a wiring bug`);
+}
+//#endregion
+export { normalizeGroupBy, validateMeasures };

package/dist/better-auth/index.d.mts

@@ -0,0 +1,110 @@
+//#region src/better-auth/index.d.ts
+/**
+ * Better Auth — kit-agnostic registry of which collections each plugin owns.
+ *
+ * This module ships **zero DB code**. It's the source of truth that every
+ * kit's `better-auth` overlay subpath consumes (`@classytic/mongokit/better-auth`,
+ * `@classytic/sqlitekit/better-auth`, future `@classytic/prismakit/better-auth`)
+ * so the per-kit overlays don't each maintain their own copy of the
+ * plugin → collection list.
+ *
+ * Why repo-core: kits depend on repo-core; arc/hosts consume kits. Putting the
+ * registry one level below the kit layer keeps it accessible to every kit
+ * without forcing kits to peer-dep each other or to peer-dep arc.
+ *
+ * @example
+ * ```ts
+ * import { resolveBetterAuthCollections } from '@classytic/repo-core/better-auth';
+ *
+ * const names = resolveBetterAuthCollections({
+ *   plugins: ['organization'],
+ *   extraCollections: ['passkey'],
+ * });
+ * // → ['user', 'session', 'account', 'verification', 'organization', 'member', 'invitation', 'passkey']
+ * ```
+ */
+/**
+ * Plugin keys that map to Better Auth collection sets.
+ *
+ * Only plugins that ship inside the **core `better-auth` package** are listed
+ * here. Plugins distributed as separate `@better-auth/*` packages
+ * (api-key, passkey, sso, oauth-provider, etc.) evolve independently and
+ * should be handled via `extraCollections` — see `resolveBetterAuthCollections`.
+ *
+ * Plugins that only add *fields* to existing tables (admin, username,
+ * phoneNumber, magicLink, emailOtp, anonymous, bearer, multiSession, siwe,
+ * lastLoginMethod, genericOAuth, etc.) don't need an entry — kit overlays
+ * register schemas with `strict: false` (Mongoose) or pass-through column
+ * mappings (SQL), so extra fields round-trip automatically.
+ *
+ * - `core` — always included; covers `user`, `session`, `account`, `verification`.
+ * - `organization` — adds `organization`, `member`, `invitation`.
+ * - `organization-teams` — adds `team`, `teamMember` (only when `teams.enabled`).
+ * - `twoFactor` — adds `twoFactor`.
+ * - `jwt` — adds `jwks`.
+ * - `oidcProvider` — adds `oauthApplication`, `oauthAccessToken`, `oauthConsent`.
+ * - `oauthProvider` — alias of `oidcProvider` (same schema).
+ * - `mcp` — MCP plugin reuses the oidcProvider schema (BA docs are explicit).
+ * - `deviceAuthorization` — adds `deviceCode` (RFC 8628 device authorization).
+ */
+type BetterAuthPluginKey = 'core' | 'organization' | 'organization-teams' | 'twoFactor' | 'jwt' | 'oidcProvider' | 'oauthProvider' | 'mcp' | 'deviceAuthorization';
+/**
+ * Canonical collection lists per plugin. `core` is always implied by
+ * `resolveBetterAuthCollections` — callers don't need to pass it.
+ *
+ * Naming follows BA's mongo adapter (`usePlural: false`) convention. Hosts
+ * that opted into `usePlural: true` should pass that flag to the kit overlay,
+ * which appends `s` to each name (`user` → `users`).
+ */
+declare const BA_COLLECTIONS_BY_PLUGIN: Record<BetterAuthPluginKey, readonly string[]>;
+/**
+ * Naive English pluralization that matches Better Auth's `usePlural` behavior:
+ * BA's mongo adapter just appends `s` (it doesn't handle irregular nouns —
+ * none of its collection names are irregular). Kit overlays mirror this.
+ */
+declare function pluralizeBetterAuthCollection(name: string): string;
+interface ResolveBetterAuthCollectionsOptions {
+  /**
+   * Which plugin collection sets to include. `core` is always implied —
+   * you don't need to pass it.
+   *
+   * @default []
+   */
+  plugins?: BetterAuthPluginKey[];
+  /**
+   * Additional collection names beyond the built-in plugin set.
+   *
+   * Use for plugins that ship as separate `@better-auth/*` packages — their
+   * collection names live in their own packages and are intentionally not
+   * hardcoded here so they can evolve independently.
+   *
+   * Known names for official separate-package plugins:
+   * - `@better-auth/passkey` → `'passkey'`
+   * - `@better-auth/sso` → `'ssoProvider'`
+   * - `@better-auth/oauth-provider` → already covered by `plugins: ['oauthProvider']`
+   *
+   * @default []
+   */
+  extraCollections?: string[];
+  /**
+   * When BA's adapter was configured with `usePlural: true`, every name is
+   * pluralized (`user` → `users`). Must match what you passed to BA's adapter.
+   *
+   * @default false
+   */
+  usePlural?: boolean;
+  /**
+   * Per-collection name override. Applies AFTER pluralization. Use when
+   * you've passed `user: { modelName: 'profile' }` (or similar) to
+   * `betterAuth()` — pass the same map here so downstream consumers
+   * (kit overlays, populate resolution) line up.
+   */
+  modelOverrides?: Partial<Record<string, string>>;
+}
+/**
+ * Resolve a plugin set + extras to a deduplicated, ordered list of
+ * collection names. `core` is always included.
+ */
+declare function resolveBetterAuthCollections(options?: ResolveBetterAuthCollectionsOptions): string[];
+//#endregion
+export { BA_COLLECTIONS_BY_PLUGIN, BetterAuthPluginKey, ResolveBetterAuthCollectionsOptions, pluralizeBetterAuthCollection, resolveBetterAuthCollections };

package/dist/better-auth/index.mjs

@@ -0,0 +1,71 @@
+//#region src/better-auth/index.ts
+/**
+* Canonical collection lists per plugin. `core` is always implied by
+* `resolveBetterAuthCollections` — callers don't need to pass it.
+*
+* Naming follows BA's mongo adapter (`usePlural: false`) convention. Hosts
+* that opted into `usePlural: true` should pass that flag to the kit overlay,
+* which appends `s` to each name (`user` → `users`).
+*/
+const BA_COLLECTIONS_BY_PLUGIN = {
+	core: [
+		"user",
+		"session",
+		"account",
+		"verification"
+	],
+	organization: [
+		"organization",
+		"member",
+		"invitation"
+	],
+	"organization-teams": ["team", "teamMember"],
+	twoFactor: ["twoFactor"],
+	jwt: ["jwks"],
+	oidcProvider: [
+		"oauthApplication",
+		"oauthAccessToken",
+		"oauthConsent"
+	],
+	oauthProvider: [
+		"oauthApplication",
+		"oauthAccessToken",
+		"oauthConsent"
+	],
+	mcp: [
+		"oauthApplication",
+		"oauthAccessToken",
+		"oauthConsent"
+	],
+	deviceAuthorization: ["deviceCode"]
+};
+/**
+* Naive English pluralization that matches Better Auth's `usePlural` behavior:
+* BA's mongo adapter just appends `s` (it doesn't handle irregular nouns —
+* none of its collection names are irregular). Kit overlays mirror this.
+*/
+function pluralizeBetterAuthCollection(name) {
+	return name.endsWith("s") ? name : `${name}s`;
+}
+/**
+* Resolve a plugin set + extras to a deduplicated, ordered list of
+* collection names. `core` is always included.
+*/
+function resolveBetterAuthCollections(options = {}) {
+	const { plugins = [], extraCollections = [], usePlural = false, modelOverrides = {} } = options;
+	const pluginSet = new Set(["core", ...plugins]);
+	const collected = [];
+	for (const key of pluginSet) for (const name of BA_COLLECTIONS_BY_PLUGIN[key]) collected.push(name);
+	for (const name of extraCollections) collected.push(name);
+	const seen = /* @__PURE__ */ new Set();
+	const unique = [];
+	for (const canonical of collected) {
+		if (seen.has(canonical)) continue;
+		seen.add(canonical);
+		const finalName = modelOverrides[canonical] ?? (usePlural ? pluralizeBetterAuthCollection(canonical) : canonical);
+		unique.push(finalName);
+	}
+	return unique;
+}
+//#endregion
+export { BA_COLLECTIONS_BY_PLUGIN, pluralizeBetterAuthCollection, resolveBetterAuthCollections };