@robelest/convex-auth 0.0.4-preview.25 → 0.0.4-preview.28

package/src/component/public/identity/users.ts

@@ -1,355 +0,0 @@
-import { v } from "convex/values";
-
-import { mutation, query } from "../../functions";
-import { vPaginated, vUserDoc } from "../../model";
-
-/**
- * List users with optional filtering, sorting, and cursor-based pagination.
- *
- * Supports filtering by `email`, `phone`, `isAnonymous`, and `name`. When an
- * `email` or `phone` filter is provided, the corresponding database index is
- * used for efficient lookup; other filters are applied in-memory. Results are
- * returned as a paginated response `{ items, nextCursor }` -- pass `nextCursor`
- * back as `cursor` to fetch the next page, or receive `null` when all results
- * have been exhausted.
- *
- * @param args.where - Optional filter object. Fields: `email` (exact match),
- *   `phone` (exact match), `isAnonymous` (boolean), `name` (exact match).
- * @param args.limit - Maximum number of users to return per page (1--100, default 50).
- * @param args.cursor - An opaque cursor string from a previous response's `nextCursor`
- *   to continue pagination, or `null` / omitted to start from the beginning.
- * @param args.orderBy - The field to sort results by. One of `"_creationTime"`,
- *   `"name"`, `"email"`, or `"phone"`. Defaults to `"_creationTime"`.
- * @param args.order - Sort direction: `"asc"` or `"desc"` (default `"desc"`).
- * @returns An object with `items` (array of user documents) and `nextCursor`
- *   (`string | null`) for fetching subsequent pages.
- *
- * @example
- * ```ts
- * // Fetch the first page of non-anonymous users
- * const page1 = await ctx.runQuery(
- *   component.identity.users.userList,
- *   { where: { isAnonymous: false }, limit: 20 },
- * );
- * console.log(page1.items);
- *
- * // Fetch the next page
- * if (page1.nextCursor !== null) {
- *   const page2 = await ctx.runQuery(
- *     component.identity.users.userList,
- *     { where: { isAnonymous: false }, limit: 20, cursor: page1.nextCursor },
- *   );
- * }
- * ```
- */
-export const userList = query({
-  args: {
-    where: v.optional(
-      v.object({
-        email: v.optional(v.string()),
-        phone: v.optional(v.string()),
-        isAnonymous: v.optional(v.boolean()),
-        name: v.optional(v.string()),
-      }),
-    ),
-    limit: v.optional(v.number()),
-    cursor: v.optional(v.union(v.string(), v.null())),
-    orderBy: v.optional(
-      v.union(
-        v.literal("_creationTime"),
-        v.literal("name"),
-        v.literal("email"),
-        v.literal("phone"),
-      ),
-    ),
-    order: v.optional(v.union(v.literal("asc"), v.literal("desc"))),
-  },
-  returns: vPaginated(vUserDoc),
-  handler: async (ctx, args) => {
-    const where = args.where ?? {};
-    const limit = Math.min(Math.max(args.limit ?? 50, 1), 100);
-    const order = args.order ?? "desc";
-
-    // Pick index based on where fields
-    let q;
-    if (where.email !== undefined) {
-      q = ctx.db
-        .query("User")
-        .withIndex("email", (idx) => idx.eq("email", where.email!));
-    } else if (where.phone !== undefined) {
-      q = ctx.db
-        .query("User")
-        .withIndex("phone", (idx) => idx.eq("phone", where.phone!));
-    } else {
-      q = ctx.db.query("User");
-    }
-
-    // Apply remaining filters
-    if (where.isAnonymous !== undefined) {
-      q = q.filter((f) => f.eq(f.field("isAnonymous"), where.isAnonymous!));
-    }
-    if (where.name !== undefined) {
-      q = q.filter((f) => f.eq(f.field("name"), where.name!));
-    }
-    // email/phone filters when not used as index
-    if (where.email !== undefined && where.phone !== undefined) {
-      q = q.filter((f) => f.eq(f.field("phone"), where.phone!));
-    }
-
-    q = q.order(order);
-
-    // Cursor-based pagination: skip past the cursor ID
-    const all = await q.collect();
-    let startIdx = 0;
-    if (args.cursor) {
-      const cursorIdx = all.findIndex((doc) => doc._id === args.cursor);
-      if (cursorIdx !== -1) {
-        startIdx = cursorIdx + 1;
-      }
-    }
-    const page = all.slice(startIdx, startIdx + limit + 1);
-    const hasMore = page.length > limit;
-    const items = hasMore ? page.slice(0, limit) : page;
-    const nextCursor = hasMore ? items[items.length - 1]._id : null;
-    return { items, nextCursor };
-  },
-});
-
-/**
- * Retrieve a single user by their Convex document ID.
- *
- * Performs a direct point lookup on the `User` table. Returns `null` if the
- * user has been deleted or never existed.
- *
- * @param args.userId - The Convex document ID (`Id<"User">`) of the user to retrieve.
- * @returns The user document if it exists, or `null` otherwise.
- *
- * @example
- * ```ts
- * const user = await ctx.runQuery(
- *   component.identity.users.userGetById,
- *   { userId: session.userId },
- * );
- * if (user !== null) {
- *   console.log(`Name: ${user.name}, Email: ${user.email}`);
- * }
- * ```
- */
-export const userGetById = query({
-  args: { userId: v.id("User") },
-  returns: v.union(vUserDoc, v.null()),
-  handler: async (ctx, { userId }) => {
-    return await ctx.db.get("User", userId);
-  },
-});
-
-/**
- * Find a user by their verified email address.
- *
- * Queries the `User` table using the `email_verified` index to locate users
- * whose `email` matches and whose `emailVerificationTime` is set. If exactly
- * one user is found, that document is returned. Returns `null` if no user has
- * this email verified or if multiple users share the same verified email
- * (an ambiguous state that should not occur in normal operation).
- *
- * @param args.email - The verified email address to search for (case-sensitive, exact match).
- * @returns The matching user document if exactly one verified user is found, or `null` otherwise.
- *
- * @example
- * ```ts
- * const user = await ctx.runQuery(
- *   component.identity.users.userFindByVerifiedEmail,
- *   { email: "alice@example.com" },
- * );
- * if (user !== null) {
- *   console.log(`Found verified user: ${user._id}`);
- * }
- * ```
- */
-export const userFindByVerifiedEmail = query({
-  args: { email: v.string() },
-  returns: v.union(vUserDoc, v.null()),
-  handler: async (ctx, { email }) => {
-    const users = await ctx.db
-      .query("User")
-      .withIndex("email_verified", (q) =>
-        q.eq("email", email).gt("emailVerificationTime", undefined),
-      )
-      .take(2);
-    return users.length === 1 ? users[0] : null;
-  },
-});
-
-/**
- * Find a user by their verified phone number.
- *
- * Queries the `User` table using the `phone_verified` index to locate users
- * whose `phone` matches and whose `phoneVerificationTime` is set. If exactly
- * one user is found, that document is returned. Returns `null` if no user has
- * this phone verified or if multiple users share the same verified phone
- * (an ambiguous state that should not occur in normal operation).
- *
- * @param args.phone - The verified phone number to search for (exact match, e.g. `"+15551234567"`).
- * @returns The matching user document if exactly one verified user is found, or `null` otherwise.
- *
- * @example
- * ```ts
- * const user = await ctx.runQuery(
- *   component.identity.users.userFindByVerifiedPhone,
- *   { phone: "+15551234567" },
- * );
- * if (user !== null) {
- *   console.log(`Found verified user: ${user._id}`);
- * }
- * ```
- */
-export const userFindByVerifiedPhone = query({
-  args: { phone: v.string() },
-  returns: v.union(vUserDoc, v.null()),
-  handler: async (ctx, { phone }) => {
-    const users = await ctx.db
-      .query("User")
-      .withIndex("phone_verified", (q) =>
-        q.eq("phone", phone).gt("phoneVerificationTime", undefined),
-      )
-      .take(2);
-    return users.length === 1 ? users[0] : null;
-  },
-});
-
-/**
- * Insert a new user document into the `User` table.
- *
- * Creates a brand-new user record. The `data` argument should conform to the
- * User table schema (e.g. `name`, `email`, `phone`, `isAnonymous`, `image`,
- * `extend`), but is typed as `any` to allow flexible extension.
- *
- * @param args.data - The user document fields to insert. Typically includes `name`,
- *   `email`, `isAnonymous`, and any custom fields under `extend`.
- * @returns The document ID of the newly created user.
- *
- * @example
- * ```ts
- * const userId = await ctx.runMutation(
- *   component.identity.users.userInsert,
- *   {
- *     data: {
- *       name: "Alice",
- *       email: "alice@example.com",
- *       isAnonymous: false,
- *     },
- *   },
- * );
- * ```
- */
-export const userInsert = mutation({
-  args: { data: v.any() },
-  returns: v.id("User"),
-  handler: async (ctx, { data }) => {
-    return await ctx.db.insert("User", data);
-  },
-});
-
-/**
- * Insert a new user or update an existing one (upsert).
- *
- * When `userId` is provided and refers to an existing user, the document is
- * patched with the supplied `data` and the same `userId` is returned. When
- * `userId` is omitted or `undefined`, a new user document is inserted and its
- * generated ID is returned. This is the primary mechanism used during sign-in
- * flows to either create or refresh user profile data.
- *
- * @param args.userId - The document ID of an existing user to update. If `undefined`,
- *   a new user is created instead.
- * @param args.data - The user document fields to insert or merge. Accepts the same
- *   shape as the User table schema.
- * @returns The document ID of the created or updated user.
- *
- * @example
- * ```ts
- * // Create a new user if none exists, or update the existing one
- * const userId = await ctx.runMutation(
- *   component.identity.users.userUpsert,
- *   {
- *     userId: existingUserId ?? undefined,
- *     data: { name: "Alice", email: "alice@example.com" },
- *   },
- * );
- * ```
- */
-export const userUpsert = mutation({
-  args: { userId: v.optional(v.id("User")), data: v.any() },
-  returns: v.id("User"),
-  handler: async (ctx, { userId, data }) => {
-    if (userId !== undefined) {
-      await ctx.db.patch("User", userId, data);
-      return userId;
-    }
-    return await ctx.db.insert("User", data);
-  },
-});
-
-/**
- * Patch an existing user document with partial data.
- *
- * Merges the provided fields into the existing user document. Fields not
- * included in `data` are left unchanged. Useful for updating profile
- * information such as `name`, `email`, or custom `extend` fields without
- * overwriting the entire document.
- *
- * @param args.userId - The document ID of the user to update.
- * @param args.data - A partial object containing the fields to merge into the user document.
- * @returns `null` on success.
- *
- * @example
- * ```ts
- * await ctx.runMutation(
- *   component.identity.users.userPatch,
- *   {
- *     userId: user._id,
- *     data: { name: "Alice Smith", image: "https://example.com/avatar.png" },
- *   },
- * );
- * ```
- */
-export const userPatch = mutation({
-  args: { userId: v.id("User"), data: v.any() },
-  returns: v.null(),
-  handler: async (ctx, { userId, data }) => {
-    await ctx.db.patch("User", userId, data);
-    return null;
-  },
-});
-
-/**
- * Delete a user document by ID.
- *
- * Removes the user from the `User` table. This is a no-op if the user does not
- * exist (i.e. was already deleted). Callers should ensure that related resources
- * such as accounts, sessions, and refresh tokens are cleaned up separately.
- *
- * @param args.userId - The document ID of the user to delete.
- * @returns `null` on success (including when the user was already absent).
- *
- * @example
- * ```ts
- * await ctx.runMutation(
- *   component.identity.users.userDelete,
- *   { userId: user._id },
- * );
- * ```
- */
-export const userDelete = mutation({
-  args: { userId: v.id("User") },
-  returns: v.null(),
-  handler: async (ctx, { userId }) => {
-    if ((await ctx.db.get("User", userId)) !== null) {
-      await ctx.db.delete("User", userId);
-    }
-    return null;
-  },
-});
-
-// ============================================================================
-// Accounts
-// ============================================================================

package/src/component/public/identity/verifiers.ts

@@ -1,158 +0,0 @@
-import { v } from "convex/values";
-
-import { mutation, query } from "../../functions";
-import { vAuthVerifierDoc } from "../../model";
-
-/**
- * Create a new PKCE verifier, optionally linked to a session.
- *
- * Inserts a document into the `AuthVerifier` table. Verifiers are used during
- * OAuth/OIDC flows to implement the PKCE (Proof Key for Code Exchange) pattern,
- * preventing authorization code interception attacks. The verifier can optionally
- * be linked to an existing session for session-aware flows.
- *
- * @param args.sessionId - An optional session document ID to associate with the verifier.
- *   When provided, the verifier is scoped to the given session.
- * @returns The document ID of the newly created verifier.
- *
- * @example
- * ```ts
- * const verifierId = await ctx.runMutation(
- *   component.identity.verifiers.verifierCreate,
- *   { sessionId: session._id },
- * );
- * ```
- */
-export const verifierCreate = mutation({
-  args: { sessionId: v.optional(v.id("Session")) },
-  returns: v.id("AuthVerifier"),
-  handler: async (ctx, { sessionId }) => {
-    return await ctx.db.insert("AuthVerifier", { sessionId: sessionId as any });
-  },
-});
-
-/**
- * Retrieve a single verifier by its Convex document ID.
- *
- * Performs a direct point lookup on the `AuthVerifier` table. Returns `null` if
- * the verifier has been deleted or never existed.
- *
- * @param args.verifierId - The Convex document ID (`Id<"AuthVerifier">`) of the verifier to retrieve.
- * @returns The verifier document if it exists, or `null` otherwise.
- *
- * @example
- * ```ts
- * const verifier = await ctx.runQuery(
- *   component.identity.verifiers.verifierGetById,
- *   { verifierId: storedVerifierId },
- * );
- * if (verifier !== null) {
- *   console.log(`Verifier signature: ${verifier.signature}`);
- * }
- * ```
- */
-export const verifierGetById = query({
-  args: { verifierId: v.id("AuthVerifier") },
-  returns: v.union(vAuthVerifierDoc, v.null()),
-  handler: async (ctx, { verifierId }) => {
-    return await ctx.db.get("AuthVerifier", verifierId);
-  },
-});
-
-/**
- * Look up a verifier by its cryptographic signature.
- *
- * Queries the `AuthVerifier` table using the `signature` index to find the
- * unique verifier matching the given signature string. This is the primary
- * lookup used during the OAuth callback phase to correlate the incoming
- * authorization response with the original PKCE challenge.
- *
- * @param args.signature - The cryptographic signature string to search for (exact match).
- * @returns The matching verifier document, or `null` if no verifier has the given signature.
- *
- * @example
- * ```ts
- * const verifier = await ctx.runQuery(
- *   component.identity.verifiers.verifierGetBySignature,
- *   { signature: incomingStateParam },
- * );
- * if (verifier === null) {
- *   throw new Error("Invalid or expired OAuth state");
- * }
- * ```
- */
-export const verifierGetBySignature = query({
-  args: { signature: v.string() },
-  returns: v.union(vAuthVerifierDoc, v.null()),
-  handler: async (ctx, { signature }) => {
-    return await ctx.db
-      .query("AuthVerifier")
-      .withIndex("signature", (q) => q.eq("signature", signature))
-      .unique();
-  },
-});
-
-/**
- * Patch a verifier document with partial data.
- *
- * Merges the provided fields into the existing verifier document. This is
- * typically used to set the `signature` field after the verifier is initially
- * created, or to associate a `sessionId` with an existing verifier.
- *
- * @param args.verifierId - The document ID of the verifier to update.
- * @param args.data - A partial object containing the fields to merge into the verifier document
- *   (e.g. `{ signature: string }` or `{ sessionId: Id<"Session"> }`).
- * @returns `null` on success.
- *
- * @example
- * ```ts
- * // Set the PKCE signature on the verifier
- * await ctx.runMutation(
- *   component.identity.verifiers.verifierPatch,
- *   {
- *     verifierId: verifier._id,
- *     data: { signature: generatedSignature },
- *   },
- * );
- * ```
- */
-export const verifierPatch = mutation({
-  args: { verifierId: v.id("AuthVerifier"), data: v.any() },
-  returns: v.null(),
-  handler: async (ctx, { verifierId, data }) => {
-    await ctx.db.patch("AuthVerifier", verifierId, data);
-    return null;
-  },
-});
-
-/**
- * Delete a verifier document permanently.
- *
- * Removes the verifier from the `AuthVerifier` table. This is typically called
- * after a successful OAuth callback to clean up the consumed PKCE state, or
- * to expire stale verifiers that were never completed.
- *
- * @param args.verifierId - The document ID of the verifier to delete.
- * @returns `null` on success.
- *
- * @example
- * ```ts
- * // Clean up the verifier after a successful OAuth exchange
- * await ctx.runMutation(
- *   component.identity.verifiers.verifierDelete,
- *   { verifierId: verifier._id },
- * );
- * ```
- */
-export const verifierDelete = mutation({
-  args: { verifierId: v.id("AuthVerifier") },
-  returns: v.null(),
-  handler: async (ctx, { verifierId }) => {
-    await ctx.db.delete("AuthVerifier", verifierId);
-    return null;
-  },
-});
-
-// ============================================================================
-// Verification Codes
-// ============================================================================