@vexcms/core 0.0.20 → 0.1.0-alpha.3

package/dist/api/utils.d.ts

@@ -0,0 +1,57 @@
+import { type GenericDataModel, GenericQueryCtx } from "convex/server";
+import { type GenericId } from "convex/values";
+import { type VexConfig } from "../config";
+import { type CollectionSlug } from "../types";
+import { VexAccessConfig } from "../access";
+import { AccessCallOptions } from "./types";
+/**
+ * Resolves the access config and action for one server-function call.
+ *
+ * Single seam for `access.action` / `access.bypass`. Bypass returns `undefined` for
+ * `access`, which is the documented "RBAC not configured" path — no separate enforcement
+ * branch exists or should be added.
+ *
+ * @param props.config - Resolved Vex config; `config.access` supplies the matrix.
+ * @param props.access - Per-call overrides.
+ * @param props.defaultAction - The function's natural verb.
+ * @param props.resource - Subject slug: the custom-action lookup key, and the name the
+ *   dev warnings report.
+ * @returns The access config to enforce (`undefined` when bypassed) and the action to check.
+ */
+export declare function resolveAccessCall<A extends string>(props: {
+    config?: VexConfig;
+    access?: AccessCallOptions<A>;
+    defaultAction: A;
+    resource: string;
+}): {
+    access: VexAccessConfig | undefined;
+    action: A;
+    resource: string;
+};
+/**
+ * Resolves the collection slug that owns a document `id` by probing
+ * `ctx.db.normalizeId` against every registered collection.
+ *
+ * A Convex `Id` does not expose its table name at runtime. `get/server.ts`'s
+ * D12 comment documents the same constraint for depth-populate, where
+ * degrading to "unresolvable" is safe (populate is simply skipped). It is
+ * NOT safe here — `get`, `update`, and `remove` gate a real permission
+ * check — so this resolves the slug via the `ctx.db.normalizeId(tableName, id)`
+ * syscall instead of string-parsing the id. Unlike the D12 trick, this works
+ * identically in `convex-test` and production Convex.
+ *
+ * @param props.ctx - Query or mutation context — only `ctx.db.normalizeId` is used.
+ * @param props.config - The resolved `VexConfig`, to enumerate candidate collections.
+ * @param props.id - The document id to resolve.
+ * @returns The owning collection's slug.
+ * @throws {Error} When no registered collection claims the id (e.g. an id for a
+ *   non-collection table like `vex_globals`, or a stale id from a deleted collection).
+ *   Callers gate the permission check behind this, so an unresolvable id is a hard error,
+ *   not a silent skip.
+ */
+export declare function resolveCollectionSlug<DataModel extends GenericDataModel>(props: {
+    ctx: GenericQueryCtx<DataModel>;
+    config?: VexConfig;
+    id: GenericId<CollectionSlug>;
+}): CollectionSlug;
+//# sourceMappingURL=utils.d.ts.map

package/dist/api/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../src/api/utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,gBAAgB,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AACvE,OAAO,EAAE,KAAK,SAAS,EAAE,MAAM,eAAe,CAAC;AAC/C,OAAO,EAAE,KAAK,SAAS,EAAE,MAAM,WAAW,CAAC;AAC3C,OAAO,EAAE,KAAK,cAAc,EAAE,MAAM,UAAU,CAAC;AAC/C,OAAO,EAAwD,eAAe,EAAE,MAAM,WAAW,CAAC;AAClG,OAAO,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAC;AAE5C;;;;;;;;;;;;;GAaG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,SAAS,MAAM,EAAE,KAAK,EAAE;IACzD,MAAM,CAAC,EAAE,SAAS,CAAC;IACnB,MAAM,CAAC,EAAE,iBAAiB,CAAC,CAAC,CAAC,CAAC;IAC9B,aAAa,EAAE,CAAC,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;CAClB,GAAG;IAAE,MAAM,EAAE,eAAe,GAAG,SAAS,CAAC;IAAC,MAAM,EAAE,CAAC,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAkDvE;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,qBAAqB,CAAC,SAAS,SAAS,gBAAgB,EAAE,KAAK,EAAE;IAC/E,GAAG,EAAE,eAAe,CAAC,SAAS,CAAC,CAAC;IAChC,MAAM,CAAC,EAAE,SAAS,CAAC;IACnB,EAAE,EAAE,SAAS,CAAC,cAAc,CAAC,CAAC;CAC/B,GAAG,cAAc,CASjB"}

package/dist/auth/mergeCollections.d.ts

@@ -0,0 +1,28 @@
+import type { CollectionConfig } from "../collections";
+import { type AuthCollectionConfig } from "./types";
+/**
+ * Merges auth collections with user-defined collections, respecting
+ * `protected` at the collection level and `meta.locked` on individual fields.
+ *
+ * Merge rules:
+ * 1. User collections that match a `protected` auth slug throw an error.
+ * 2. Iterate remaining user collections in their declared order.
+ * 3. If a user collection's slug matches an auth collection:
+ *    - Auth fields with `meta.locked === true` are preserved.
+ *    - All other fields: user field wins (override or extend).
+ *    - Admin config: user collection wins.
+ *    - The merged collection appears at the user's declared position.
+ * 4. Auth collections with no matching user collection are appended at the end.
+ * 5. User collections with no matching auth collection are added as-is.
+ *
+ * @param props — authCollections, userCollections
+ * @param props.authCollections — Collections from the auth adapter.
+ * @param props.userCollections — Collections defined by the user.
+ * @throws VexAuthConfigError when users pass a protected collection slug.
+ * @returns Merged collections array for `VexConfig`.
+ */
+export declare function mergeAuthCollections(props: {
+    authCollections: AuthCollectionConfig[];
+    userCollections: CollectionConfig[];
+}): CollectionConfig[];
+//# sourceMappingURL=mergeCollections.d.ts.map

package/dist/auth/mergeCollections.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mergeCollections.d.ts","sourceRoot":"","sources":["../../src/auth/mergeCollections.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AACvD,OAAO,EAEL,KAAK,oBAAoB,EAE1B,MAAM,SAAS,CAAC;AAGjB;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE;IAC1C,eAAe,EAAE,oBAAoB,EAAE,CAAC;IACxC,eAAe,EAAE,gBAAgB,EAAE,CAAC;CACrC,GAAG,gBAAgB,EAAE,CAsCrB"}

package/dist/auth/types.d.ts

@@ -0,0 +1,84 @@
+import { CollectionConfig } from "../collections";
+import { ComponentHKT } from "../fields";
+import { CollectionSlug } from "../types";
+/**
+ * Metadata attached to auth fields to control merge behavior during
+ * auth collection merging.
+ *
+ * When `locked: true`, the field definition from the auth adapter is
+ * preserved and cannot be overridden by a user-defined collection.
+ * Unlocked fields can be extended or replaced by the user.
+ *
+ * @see {@link mergeAuthCollections} for the merge logic that respects this flag
+ * @see {@link better-auth/src!betterAuthAdapter} for the adapter that sets `locked` on system fields
+ */
+export interface AuthFieldMeta {
+    /** When `true`, this field cannot be overridden by user-defined collections. */
+    locked: boolean;
+}
+/**
+ * Metadata attached to auth collections to control merge behavior with
+ * user-defined collections.
+ *
+ * Auth adapters mark collections as `protected` to prevent accidental
+ * overrides that could break authentication.
+ */
+export type AuthCollectionMeta = {
+    /**
+     * When `true`, this auth collection cannot be overridden by a user-defined
+     * collection with the same slug. Attempting to do so throws a
+     * {@link VexAuthConfigError}.
+     *
+     * When `false` or omitted, user-defined collections can extend or
+     * override this auth collection (unlocked fields can still be overridden,
+     * but locked fields are preserved — see {@link AuthFieldMeta}).
+     */
+    protected?: boolean;
+};
+/**
+ * Auth collection config — extends `CollectionConfig` with field-level
+ * locking so auth adapters can protect fields that must not be overridden.
+ */
+export type AuthCollectionConfig<TCollectionSlug extends CollectionSlug = CollectionSlug, TFieldSlug extends string = string, TComponent extends ComponentHKT = ComponentHKT> = CollectionConfig<AuthFieldMeta, AuthCollectionMeta, TCollectionSlug, TFieldSlug, TComponent>;
+/**
+ * Auth adapter returned by an auth provider package (e.g. `@vexcms/better-auth`).
+ *
+ * The adapter exposes auth collections as standard Vex `CollectionConfig[]`
+ * so that schema generation, admin navigation, and CRUD views treat them
+ * identically to user-defined collections.
+ *
+ * @see {@link better-auth/src!betterAuthAdapter} — the Better Auth implementation
+ */
+export interface VexAuthAdapter {
+    /** Provider identifier for debugging and telemetry. */
+    readonly name: string;
+    /**
+     * Auth collections to register alongside user-defined collections.
+     *
+     * These are merged into `VexConfig.collections` automatically by
+     * `defineConfig()`. Each collection uses standard Vex field builders
+     * (`text()`, `relationship()`, etc.) and may carry `admin.readOnly`
+     * defaults on system fields.
+     */
+    readonly collections: AuthCollectionConfig[];
+    /**
+     * The slug of the collection that stores user documents.
+     *
+     * Used by the admin panel to resolve user references and by auth-aware
+     * components to look up the current user collection.
+     */
+    readonly userCollection: CollectionSlug;
+}
+/**
+ * Error thrown when auth configuration is invalid or when a user-defined
+ * collection attempts to override a protected auth collection.
+ *
+ * @see {@link mergeAuthCollections} for the merge logic that throws this error
+ */
+export declare class VexAuthConfigError extends Error {
+    /**
+     * @param message — Human-readable description of the configuration error.
+     */
+    constructor(message: string);
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/auth/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/auth/types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAClD,OAAO,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAE1C;;;;;;;;;;GAUG;AACH,MAAM,WAAW,aAAa;IAC5B,gFAAgF;IAChF,MAAM,EAAE,OAAO,CAAC;CACjB;AAED;;;;;;GAMG;AACH,MAAM,MAAM,kBAAkB,GAAG;IAC/B;;;;;;;;OAQG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB,CAAC;AAEF;;;GAGG;AACH,MAAM,MAAM,oBAAoB,CAC9B,eAAe,SAAS,cAAc,GAAG,cAAc,EACvD,UAAU,SAAS,MAAM,GAAG,MAAM,EAClC,UAAU,SAAS,YAAY,GAAG,YAAY,IAC5C,gBAAgB,CAClB,aAAa,EACb,kBAAkB,EAClB,eAAe,EACf,UAAU,EACV,UAAU,CACX,CAAC;AAEF;;;;;;;;GAQG;AACH,MAAM,WAAW,cAAc;IAC7B,uDAAuD;IACvD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB;;;;;;;OAOG;IACH,QAAQ,CAAC,WAAW,EAAE,oBAAoB,EAAE,CAAC;IAE7C;;;;;OAKG;IACH,QAAQ,CAAC,cAAc,EAAE,cAAc,CAAC;CACzC;AAED;;;;;GAKG;AACH,qBAAa,kBAAmB,SAAQ,KAAK;IAC3C;;OAEG;gBACS,OAAO,EAAE,MAAM;CAI5B"}