@robelest/convex-auth 0.0.4-preview.2 → 0.0.4-preview.21

package/dist/component/public/identity/tokens.js

@@ -0,0 +1,227 @@
+import { mutation, query } from "../../functions.js";
+import { vRefreshTokenDoc } from "../../model.js";
+import { v } from "convex/values";
+
+//#region src/component/public/identity/tokens.ts
+/**
+* Create a new refresh token for a session.
+*
+* Inserts a document into the `RefreshToken` table. Refresh tokens are used to
+* obtain new access tokens without requiring the user to re-authenticate. When
+* a refresh token is rotated, the new token references the old one via
+* `parentRefreshTokenId` to form a token chain for replay detection.
+*
+* @param args.sessionId - The document ID of the session this refresh token belongs to.
+* @param args.expirationTime - The Unix timestamp (in milliseconds) at which this refresh token expires.
+* @param args.parentRefreshTokenId - The document ID of the parent refresh token that was
+*   exchanged to create this one. Omitted for the initial token in a session.
+* @returns The document ID of the newly created refresh token.
+*
+* @example
+* ```ts
+* const tokenId = await ctx.runMutation(
+*   component.identity.tokens.refreshTokenCreate,
+*   {
+*     sessionId: session._id,
+*     expirationTime: Date.now() + 7 * 24 * 60 * 60 * 1000, // 7 days
+*   },
+* );
+* ```
+*/
+const refreshTokenCreate = mutation({
+	args: {
+		sessionId: v.id("Session"),
+		expirationTime: v.number(),
+		parentRefreshTokenId: v.optional(v.id("RefreshToken"))
+	},
+	returns: v.id("RefreshToken"),
+	handler: async (ctx, args) => {
+		return await ctx.db.insert("RefreshToken", args);
+	}
+});
+/**
+* Retrieve a single refresh token by its Convex document ID.
+*
+* Performs a direct point lookup on the `RefreshToken` table. Returns `null` if
+* the token has been deleted or never existed.
+*
+* @param args.refreshTokenId - The Convex document ID (`Id<"RefreshToken">`) of the token to retrieve.
+* @returns The refresh token document if it exists, or `null` otherwise.
+*
+* @example
+* ```ts
+* const token = await ctx.runQuery(
+*   component.identity.tokens.refreshTokenGetById,
+*   { refreshTokenId: storedTokenId },
+* );
+* if (token !== null && token.expirationTime > Date.now()) {
+*   console.log("Refresh token is still valid");
+* }
+* ```
+*/
+const refreshTokenGetById = query({
+	args: { refreshTokenId: v.id("RefreshToken") },
+	returns: v.union(vRefreshTokenDoc, v.null()),
+	handler: async (ctx, { refreshTokenId }) => {
+		return await ctx.db.get("RefreshToken", refreshTokenId);
+	}
+});
+/**
+* Patch a refresh token document with partial data.
+*
+* Merges the provided fields into the existing refresh token document. This is
+* primarily used to record `firstUsedTime` when a refresh token is first
+* exchanged, marking it as consumed for replay detection.
+*
+* @param args.refreshTokenId - The document ID of the refresh token to update.
+* @param args.data - A partial object containing the fields to merge (e.g. `{ firstUsedTime: number }`).
+* @returns `null` on success.
+*
+* @example
+* ```ts
+* // Mark the refresh token as used
+* await ctx.runMutation(
+*   component.identity.tokens.refreshTokenPatch,
+*   {
+*     refreshTokenId: token._id,
+*     data: { firstUsedTime: Date.now() },
+*   },
+* );
+* ```
+*/
+const refreshTokenPatch = mutation({
+	args: {
+		refreshTokenId: v.id("RefreshToken"),
+		data: v.any()
+	},
+	returns: v.null(),
+	handler: async (ctx, { refreshTokenId, data }) => {
+		await ctx.db.patch("RefreshToken", refreshTokenId, data);
+		return null;
+	}
+});
+/**
+* Get child tokens that were created by exchanging a specific parent token.
+*
+* Queries the `RefreshToken` table using the `session_id_parent_refresh_token_id`
+* index to find all tokens whose `parentRefreshTokenId` matches the provided
+* parent. This is used for replay detection: if a parent token has more than
+* one child, it indicates a potential token reuse attack.
+*
+* @param args.sessionId - The document ID of the session the tokens belong to.
+* @param args.parentRefreshTokenId - The document ID of the parent refresh token whose children to retrieve.
+* @returns An array of refresh token documents that were derived from the specified parent token.
+*
+* @example
+* ```ts
+* const children = await ctx.runQuery(
+*   component.identity.tokens.refreshTokenGetChildren,
+*   {
+*     sessionId: session._id,
+*     parentRefreshTokenId: parentToken._id,
+*   },
+* );
+* if (children.length > 1) {
+*   console.warn("Possible token reuse detected!");
+* }
+* ```
+*/
+const refreshTokenGetChildren = query({
+	args: {
+		sessionId: v.id("Session"),
+		parentRefreshTokenId: v.id("RefreshToken")
+	},
+	returns: v.array(vRefreshTokenDoc),
+	handler: async (ctx, { sessionId, parentRefreshTokenId }) => {
+		return await ctx.db.query("RefreshToken").withIndex("session_id_parent_refresh_token_id", (q) => q.eq("sessionId", sessionId).eq("parentRefreshTokenId", parentRefreshTokenId)).collect();
+	}
+});
+/**
+* List all refresh tokens belonging to a specific session.
+*
+* Queries the `RefreshToken` table using the `session_id_parent_refresh_token_id`
+* index to efficiently retrieve every refresh token associated with the given
+* session, including both active and consumed tokens.
+*
+* @param args.sessionId - The document ID of the session whose refresh tokens should be retrieved.
+* @returns An array of all refresh token documents for the specified session.
+*
+* @example
+* ```ts
+* const tokens = await ctx.runQuery(
+*   component.identity.tokens.refreshTokenListBySession,
+*   { sessionId: session._id },
+* );
+* console.log(`Session has ${tokens.length} refresh token(s)`);
+* ```
+*/
+const refreshTokenListBySession = query({
+	args: { sessionId: v.id("Session") },
+	returns: v.array(vRefreshTokenDoc),
+	handler: async (ctx, { sessionId }) => {
+		return await ctx.db.query("RefreshToken").withIndex("session_id_parent_refresh_token_id", (q) => q.eq("sessionId", sessionId)).collect();
+	}
+});
+/**
+* Delete all refresh tokens for a session.
+*
+* Queries the `RefreshToken` table for all tokens belonging to the given session
+* and deletes them in parallel. This is typically called when a session is
+* revoked or when token reuse is detected, effectively invalidating the entire
+* token chain for that session.
+*
+* @param args.sessionId - The document ID of the session whose refresh tokens should be deleted.
+* @returns `null` on success.
+*
+* @example
+* ```ts
+* // Invalidate all tokens for a compromised session
+* await ctx.runMutation(
+*   component.identity.tokens.refreshTokenDeleteAll,
+*   { sessionId: session._id },
+* );
+* ```
+*/
+const refreshTokenDeleteAll = mutation({
+	args: { sessionId: v.id("Session") },
+	returns: v.null(),
+	handler: async (ctx, { sessionId }) => {
+		const tokens = await ctx.db.query("RefreshToken").withIndex("session_id_parent_refresh_token_id", (q) => q.eq("sessionId", sessionId)).collect();
+		await Promise.all(tokens.map((token) => ctx.db.delete("RefreshToken", token._id)));
+		return null;
+	}
+});
+/**
+* Get the active (unused) refresh token for a session.
+*
+* Queries the `RefreshToken` table using the `session_id_first_used` index to
+* find the most recently created token for the session that has not yet been
+* exchanged (i.e. `firstUsedTime` is `undefined`). This represents the current
+* valid refresh token the client should be holding.
+*
+* @param args.sessionId - The document ID of the session whose active refresh token should be retrieved.
+* @returns The most recent unused refresh token document, or `null` if no active token exists
+*   (e.g. all tokens have been consumed or the session has no tokens).
+*
+* @example
+* ```ts
+* const activeToken = await ctx.runQuery(
+*   component.identity.tokens.refreshTokenGetActive,
+*   { sessionId: session._id },
+* );
+* if (activeToken !== null) {
+*   console.log(`Active token expires at: ${activeToken.expirationTime}`);
+* }
+* ```
+*/
+const refreshTokenGetActive = query({
+	args: { sessionId: v.id("Session") },
+	returns: v.union(vRefreshTokenDoc, v.null()),
+	handler: async (ctx, { sessionId }) => {
+		return await ctx.db.query("RefreshToken").withIndex("session_id_first_used", (q) => q.eq("sessionId", sessionId).eq("firstUsedTime", void 0)).order("desc").first();
+	}
+});
+
+//#endregion
+export { refreshTokenCreate, refreshTokenDeleteAll, refreshTokenGetActive, refreshTokenGetById, refreshTokenGetChildren, refreshTokenListBySession, refreshTokenPatch };
+//# sourceMappingURL=tokens.js.map

package/dist/component/public/identity/tokens.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tokens.js","names":[],"sources":["../../../../src/component/public/identity/tokens.ts"],"sourcesContent":["import { v } from \"convex/values\";\nimport { mutation, query } from \"../../functions\";\nimport { vRefreshTokenDoc } from \"../../model\";\n\n/**\n * Create a new refresh token for a session.\n *\n * Inserts a document into the `RefreshToken` table. Refresh tokens are used to\n * obtain new access tokens without requiring the user to re-authenticate. When\n * a refresh token is rotated, the new token references the old one via\n * `parentRefreshTokenId` to form a token chain for replay detection.\n *\n * @param args.sessionId - The document ID of the session this refresh token belongs to.\n * @param args.expirationTime - The Unix timestamp (in milliseconds) at which this refresh token expires.\n * @param args.parentRefreshTokenId - The document ID of the parent refresh token that was\n *   exchanged to create this one. Omitted for the initial token in a session.\n * @returns The document ID of the newly created refresh token.\n *\n * @example\n * ```ts\n * const tokenId = await ctx.runMutation(\n *   component.identity.tokens.refreshTokenCreate,\n *   {\n *     sessionId: session._id,\n *     expirationTime: Date.now() + 7 * 24 * 60 * 60 * 1000, // 7 days\n *   },\n * );\n * ```\n */\nexport const refreshTokenCreate = mutation({\n  args: {\n    sessionId: v.id(\"Session\"),\n    expirationTime: v.number(),\n    parentRefreshTokenId: v.optional(v.id(\"RefreshToken\")),\n  },\n  returns: v.id(\"RefreshToken\"),\n  handler: async (ctx, args) => {\n    return await ctx.db.insert(\"RefreshToken\", args as any);\n  },\n});\n\n/**\n * Retrieve a single refresh token by its Convex document ID.\n *\n * Performs a direct point lookup on the `RefreshToken` table. Returns `null` if\n * the token has been deleted or never existed.\n *\n * @param args.refreshTokenId - The Convex document ID (`Id<\"RefreshToken\">`) of the token to retrieve.\n * @returns The refresh token document if it exists, or `null` otherwise.\n *\n * @example\n * ```ts\n * const token = await ctx.runQuery(\n *   component.identity.tokens.refreshTokenGetById,\n *   { refreshTokenId: storedTokenId },\n * );\n * if (token !== null && token.expirationTime > Date.now()) {\n *   console.log(\"Refresh token is still valid\");\n * }\n * ```\n */\nexport const refreshTokenGetById = query({\n  args: { refreshTokenId: v.id(\"RefreshToken\") },\n  returns: v.union(vRefreshTokenDoc, v.null()),\n  handler: async (ctx, { refreshTokenId }) => {\n    return await ctx.db.get(\"RefreshToken\", refreshTokenId);\n  },\n});\n\n/**\n * Patch a refresh token document with partial data.\n *\n * Merges the provided fields into the existing refresh token document. This is\n * primarily used to record `firstUsedTime` when a refresh token is first\n * exchanged, marking it as consumed for replay detection.\n *\n * @param args.refreshTokenId - The document ID of the refresh token to update.\n * @param args.data - A partial object containing the fields to merge (e.g. `{ firstUsedTime: number }`).\n * @returns `null` on success.\n *\n * @example\n * ```ts\n * // Mark the refresh token as used\n * await ctx.runMutation(\n *   component.identity.tokens.refreshTokenPatch,\n *   {\n *     refreshTokenId: token._id,\n *     data: { firstUsedTime: Date.now() },\n *   },\n * );\n * ```\n */\nexport const refreshTokenPatch = mutation({\n  args: { refreshTokenId: v.id(\"RefreshToken\"), data: v.any() },\n  returns: v.null(),\n  handler: async (ctx, { refreshTokenId, data }) => {\n    await ctx.db.patch(\"RefreshToken\", refreshTokenId, data);\n    return null;\n  },\n});\n\n/**\n * Get child tokens that were created by exchanging a specific parent token.\n *\n * Queries the `RefreshToken` table using the `session_id_parent_refresh_token_id`\n * index to find all tokens whose `parentRefreshTokenId` matches the provided\n * parent. This is used for replay detection: if a parent token has more than\n * one child, it indicates a potential token reuse attack.\n *\n * @param args.sessionId - The document ID of the session the tokens belong to.\n * @param args.parentRefreshTokenId - The document ID of the parent refresh token whose children to retrieve.\n * @returns An array of refresh token documents that were derived from the specified parent token.\n *\n * @example\n * ```ts\n * const children = await ctx.runQuery(\n *   component.identity.tokens.refreshTokenGetChildren,\n *   {\n *     sessionId: session._id,\n *     parentRefreshTokenId: parentToken._id,\n *   },\n * );\n * if (children.length > 1) {\n *   console.warn(\"Possible token reuse detected!\");\n * }\n * ```\n */\nexport const refreshTokenGetChildren = query({\n  args: {\n    sessionId: v.id(\"Session\"),\n    parentRefreshTokenId: v.id(\"RefreshToken\"),\n  },\n  returns: v.array(vRefreshTokenDoc),\n  handler: async (ctx, { sessionId, parentRefreshTokenId }) => {\n    return await ctx.db\n      .query(\"RefreshToken\")\n      .withIndex(\"session_id_parent_refresh_token_id\", (q) =>\n        q\n          .eq(\"sessionId\", sessionId as any)\n          .eq(\"parentRefreshTokenId\", parentRefreshTokenId as any),\n      )\n      .collect();\n  },\n});\n\n/**\n * List all refresh tokens belonging to a specific session.\n *\n * Queries the `RefreshToken` table using the `session_id_parent_refresh_token_id`\n * index to efficiently retrieve every refresh token associated with the given\n * session, including both active and consumed tokens.\n *\n * @param args.sessionId - The document ID of the session whose refresh tokens should be retrieved.\n * @returns An array of all refresh token documents for the specified session.\n *\n * @example\n * ```ts\n * const tokens = await ctx.runQuery(\n *   component.identity.tokens.refreshTokenListBySession,\n *   { sessionId: session._id },\n * );\n * console.log(`Session has ${tokens.length} refresh token(s)`);\n * ```\n */\nexport const refreshTokenListBySession = query({\n  args: { sessionId: v.id(\"Session\") },\n  returns: v.array(vRefreshTokenDoc),\n  handler: async (ctx, { sessionId }) => {\n    return await ctx.db\n      .query(\"RefreshToken\")\n      .withIndex(\"session_id_parent_refresh_token_id\", (q) =>\n        q.eq(\"sessionId\", sessionId as any),\n      )\n      .collect();\n  },\n});\n\n/**\n * Delete all refresh tokens for a session.\n *\n * Queries the `RefreshToken` table for all tokens belonging to the given session\n * and deletes them in parallel. This is typically called when a session is\n * revoked or when token reuse is detected, effectively invalidating the entire\n * token chain for that session.\n *\n * @param args.sessionId - The document ID of the session whose refresh tokens should be deleted.\n * @returns `null` on success.\n *\n * @example\n * ```ts\n * // Invalidate all tokens for a compromised session\n * await ctx.runMutation(\n *   component.identity.tokens.refreshTokenDeleteAll,\n *   { sessionId: session._id },\n * );\n * ```\n */\nexport const refreshTokenDeleteAll = mutation({\n  args: { sessionId: v.id(\"Session\") },\n  returns: v.null(),\n  handler: async (ctx, { sessionId }) => {\n    const tokens = await ctx.db\n      .query(\"RefreshToken\")\n      .withIndex(\"session_id_parent_refresh_token_id\", (q) =>\n        q.eq(\"sessionId\", sessionId as any),\n      )\n      .collect();\n    await Promise.all(\n      tokens.map((token) => ctx.db.delete(\"RefreshToken\", token._id)),\n    );\n    return null;\n  },\n});\n\n/**\n * Get the active (unused) refresh token for a session.\n *\n * Queries the `RefreshToken` table using the `session_id_first_used` index to\n * find the most recently created token for the session that has not yet been\n * exchanged (i.e. `firstUsedTime` is `undefined`). This represents the current\n * valid refresh token the client should be holding.\n *\n * @param args.sessionId - The document ID of the session whose active refresh token should be retrieved.\n * @returns The most recent unused refresh token document, or `null` if no active token exists\n *   (e.g. all tokens have been consumed or the session has no tokens).\n *\n * @example\n * ```ts\n * const activeToken = await ctx.runQuery(\n *   component.identity.tokens.refreshTokenGetActive,\n *   { sessionId: session._id },\n * );\n * if (activeToken !== null) {\n *   console.log(`Active token expires at: ${activeToken.expirationTime}`);\n * }\n * ```\n */\nexport const refreshTokenGetActive = query({\n  args: { sessionId: v.id(\"Session\") },\n  returns: v.union(vRefreshTokenDoc, v.null()),\n  handler: async (ctx, { sessionId }) => {\n    return await ctx.db\n      .query(\"RefreshToken\")\n      .withIndex(\"session_id_first_used\", (q) =>\n        q.eq(\"sessionId\", sessionId as any).eq(\"firstUsedTime\", undefined),\n      )\n      .order(\"desc\")\n      .first();\n  },\n});\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA6BA,MAAa,qBAAqB,SAAS;CACzC,MAAM;EACJ,WAAW,EAAE,GAAG,UAAU;EAC1B,gBAAgB,EAAE,QAAQ;EAC1B,sBAAsB,EAAE,SAAS,EAAE,GAAG,eAAe,CAAC;EACvD;CACD,SAAS,EAAE,GAAG,eAAe;CAC7B,SAAS,OAAO,KAAK,SAAS;AAC5B,SAAO,MAAM,IAAI,GAAG,OAAO,gBAAgB,KAAY;;CAE1D,CAAC;;;;;;;;;;;;;;;;;;;;;AAsBF,MAAa,sBAAsB,MAAM;CACvC,MAAM,EAAE,gBAAgB,EAAE,GAAG,eAAe,EAAE;CAC9C,SAAS,EAAE,MAAM,kBAAkB,EAAE,MAAM,CAAC;CAC5C,SAAS,OAAO,KAAK,EAAE,qBAAqB;AAC1C,SAAO,MAAM,IAAI,GAAG,IAAI,gBAAgB,eAAe;;CAE1D,CAAC;;;;;;;;;;;;;;;;;;;;;;;;AAyBF,MAAa,oBAAoB,SAAS;CACxC,MAAM;EAAE,gBAAgB,EAAE,GAAG,eAAe;EAAE,MAAM,EAAE,KAAK;EAAE;CAC7D,SAAS,EAAE,MAAM;CACjB,SAAS,OAAO,KAAK,EAAE,gBAAgB,WAAW;AAChD,QAAM,IAAI,GAAG,MAAM,gBAAgB,gBAAgB,KAAK;AACxD,SAAO;;CAEV,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;AA4BF,MAAa,0BAA0B,MAAM;CAC3C,MAAM;EACJ,WAAW,EAAE,GAAG,UAAU;EAC1B,sBAAsB,EAAE,GAAG,eAAe;EAC3C;CACD,SAAS,EAAE,MAAM,iBAAiB;CAClC,SAAS,OAAO,KAAK,EAAE,WAAW,2BAA2B;AAC3D,SAAO,MAAM,IAAI,GACd,MAAM,eAAe,CACrB,UAAU,uCAAuC,MAChD,EACG,GAAG,aAAa,UAAiB,CACjC,GAAG,wBAAwB,qBAA4B,CAC3D,CACA,SAAS;;CAEf,CAAC;;;;;;;;;;;;;;;;;;;;AAqBF,MAAa,4BAA4B,MAAM;CAC7C,MAAM,EAAE,WAAW,EAAE,GAAG,UAAU,EAAE;CACpC,SAAS,EAAE,MAAM,iBAAiB;CAClC,SAAS,OAAO,KAAK,EAAE,gBAAgB;AACrC,SAAO,MAAM,IAAI,GACd,MAAM,eAAe,CACrB,UAAU,uCAAuC,MAChD,EAAE,GAAG,aAAa,UAAiB,CACpC,CACA,SAAS;;CAEf,CAAC;;;;;;;;;;;;;;;;;;;;;AAsBF,MAAa,wBAAwB,SAAS;CAC5C,MAAM,EAAE,WAAW,EAAE,GAAG,UAAU,EAAE;CACpC,SAAS,EAAE,MAAM;CACjB,SAAS,OAAO,KAAK,EAAE,gBAAgB;EACrC,MAAM,SAAS,MAAM,IAAI,GACtB,MAAM,eAAe,CACrB,UAAU,uCAAuC,MAChD,EAAE,GAAG,aAAa,UAAiB,CACpC,CACA,SAAS;AACZ,QAAM,QAAQ,IACZ,OAAO,KAAK,UAAU,IAAI,GAAG,OAAO,gBAAgB,MAAM,IAAI,CAAC,CAChE;AACD,SAAO;;CAEV,CAAC;;;;;;;;;;;;;;;;;;;;;;;;AAyBF,MAAa,wBAAwB,MAAM;CACzC,MAAM,EAAE,WAAW,EAAE,GAAG,UAAU,EAAE;CACpC,SAAS,EAAE,MAAM,kBAAkB,EAAE,MAAM,CAAC;CAC5C,SAAS,OAAO,KAAK,EAAE,gBAAgB;AACrC,SAAO,MAAM,IAAI,GACd,MAAM,eAAe,CACrB,UAAU,0BAA0B,MACnC,EAAE,GAAG,aAAa,UAAiB,CAAC,GAAG,iBAAiB,OAAU,CACnE,CACA,MAAM,OAAO,CACb,OAAO;;CAEb,CAAC"}

package/dist/component/public/identity/users.d.ts

@@ -0,0 +1,212 @@
+declare namespace users_d_exports {
+  export { userDelete, userFindByVerifiedEmail, userFindByVerifiedPhone, userGetById, userInsert, userList, userPatch, userUpsert };
+}
+/**
+ * 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 },
+ *   );
+ * }
+ * ```
+ */
+declare const userList: any;
+/**
+ * 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}`);
+ * }
+ * ```
+ */
+declare const userGetById: any;
+/**
+ * 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}`);
+ * }
+ * ```
+ */
+declare const userFindByVerifiedEmail: any;
+/**
+ * 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}`);
+ * }
+ * ```
+ */
+declare const userFindByVerifiedPhone: any;
+/**
+ * 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,
+ *     },
+ *   },
+ * );
+ * ```
+ */
+declare const userInsert: any;
+/**
+ * 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" },
+ *   },
+ * );
+ * ```
+ */
+declare const userUpsert: any;
+/**
+ * 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" },
+ *   },
+ * );
+ * ```
+ */
+declare const userPatch: any;
+/**
+ * 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 },
+ * );
+ * ```
+ */
+declare const userDelete: any;
+//#endregion
+export { userDelete, userFindByVerifiedEmail, userFindByVerifiedPhone, userGetById, userInsert, userList, userPatch, userUpsert, users_d_exports };
+//# sourceMappingURL=users.d.ts.map

package/dist/component/public/identity/users.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"users.d.ts","names":[],"sources":["../../../../src/component/public/identity/users.ts"],"mappings":";;;;;;;;;;;;;;;;AA2CA;;;;;AA6FA;;;;;AA+BA;;;;;AAqCA;;;;;AAuCA;;;;;AAmCA;cA3Oa,QAAA;;;;AA8Qb;;;;;AA2BA;;;;;;;;;;;;cA5Ma,WAAA;;;;;;;;;;;;;;;;;;;;;;;;cA+BA,uBAAA;;;;;;;;;;;;;;;;;;;;;;;;cAqCA,uBAAA;;;;;;;;;;;;;;;;;;;;;;;;;;cAuCA,UAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;cAmCA,UAAA;;;;;;;;;;;;;;;;;;;;;;;;cAmCA,SAAA;;;;;;;;;;;;;;;;;;;cA2BA,UAAA"}