@robelest/convex-auth 0.0.4-preview.32 → 0.0.4-preview.34

package/dist/component/public/groups/core.js

@@ -39,15 +39,6 @@ function normalizeTags(tags) {
 * @param args.extend - An optional arbitrary payload for application-specific metadata.
 * @returns The `Id<"Group">` of the newly created group document.
 *
-* @example
-* ```ts
-* const groupId = await ctx.runMutation(components.auth.groups.groupCreate, {
-*   name: "Acme Corp",
-*   slug: "acme-corp",
-*   type: "organization",
-*   tags: [{ key: "plan", value: "group-sso" }],
-* });
-* ```
 */
 const groupCreate = mutation({
 	args: {
@@ -81,52 +72,26 @@ const groupCreate = mutation({
 	}
 });
 /**
-* Retrieve a group by its document ID.
-*
-* Performs a direct lookup in the `Group` table and returns the full group
-* document, or `null` if no group exists with the given ID.
-*
-* @param args.groupId - The `Id<"Group">` of the group to retrieve.
-* @returns The group document (including `name`, `slug`, `type`, `tags`, hierarchy fields, etc.) or `null` if not found.
-*
-* @example
-* ```ts
-* const group = await ctx.runQuery(components.auth.groups.groupGet, {
-*   groupId: existingGroupId,
-* });
-* if (group !== null) {
-*   console.log(group.name, group.slug);
-* }
-* ```
+* Read a group by identity — one function, all-optional args, unioned
+* return: `{ id }` → `Doc<"Group"> | null`, or `{ ids }` → ordered
+* `(Doc<"Group"> | null)[]` (deduped).
 */
 const groupGet = query({
-	args: { groupId: v.id("Group") },
-	returns: v.union(vGroupDoc, v.null()),
-	handler: async (ctx, { groupId }) => {
-		return await ctx.db.get("Group", groupId);
-	}
-});
-/**
-* Batched equivalent of {@link groupGet}. Fetches many group documents by ID
-* in a single component round-trip. Returns each group (or `null`) in the
-* same slot as the input ID; duplicates are tolerated but de-duplicated
-* internally so each `ctx.db.get` runs exactly once per distinct ID.
-*
-* Used by app-side aggregate handlers (e.g. `groups:listMyGroups`) that
-* previously fanned out one `groupGet` per item.
-*
-* @param args.groupIds - Array of group document IDs.
-* @returns Array of group documents (or `null` entries) in input order.
-*/
-const groupGetMany = query({
-	args: { groupIds: v.array(v.id("Group")) },
-	returns: v.array(v.union(vGroupDoc, v.null())),
-	handler: async (ctx, { groupIds }) => {
-		if (groupIds.length === 0) return [];
-		const unique = Array.from(new Set(groupIds));
-		const docs = await Promise.all(unique.map((id) => ctx.db.get("Group", id)));
-		const byId = new Map(unique.map((id, i) => [id, docs[i] ?? null]));
-		return groupIds.map((id) => byId.get(id) ?? null);
+	args: {
+		id: v.optional(v.id("Group")),
+		ids: v.optional(v.array(v.id("Group")))
+	},
+	returns: v.union(vGroupDoc, v.null(), v.array(v.union(vGroupDoc, v.null()))),
+	handler: async (ctx, args) => {
+		if (args.ids !== void 0) {
+			if (args.ids.length === 0) return [];
+			const unique = Array.from(new Set(args.ids));
+			const docs = await Promise.all(unique.map((id) => ctx.db.get("Group", id)));
+			const byId = new Map(unique.map((id, i) => [id, docs[i] ?? null]));
+			return args.ids.map((id) => byId.get(id) ?? null);
+		}
+		if (args.id === void 0) return null;
+		return await ctx.db.get("Group", args.id);
 	}
 });
 /**
@@ -216,17 +181,6 @@ const groupAncestors = query({
 * @param args.order - Sort direction: `"asc"` or `"desc"` (defaults to `"desc"`).
 * @returns An object `{ items, nextCursor }` where `items` is an array of group documents and `nextCursor` is `null` when there are no more pages.
 *
-* @example
-* ```ts
-* const { items, nextCursor } = await ctx.runQuery(
-*   components.auth.groups.groupList,
-*   {
-*     where: { type: "team", isRoot: false },
-*     limit: 20,
-*     order: "asc",
-*   },
-* );
-* ```
 */
 const groupList = query({
 	args: {
@@ -314,16 +268,6 @@ const groupList = query({
 * @param args.data - A partial object of fields to patch. Supported keys include `name`, `slug`, `type`, `parentGroupId`, `tags`, and `extend`.
 * @returns `null` on success.
 *
-* @example
-* ```ts
-* await ctx.runMutation(components.auth.groups.groupUpdate, {
-*   groupId: existingGroupId,
-*   data: {
-*     name: "Acme Corp (renamed)",
-*     tags: [{ key: "plan", value: "pro" }],
-*   },
-* });
-* ```
 */
 const groupUpdate = mutation({
 	args: {
@@ -376,13 +320,6 @@ const groupUpdate = mutation({
 * @param args.groupId - The `Id<"Group">` of the group to delete. All children are deleted recursively.
 * @returns `null` on success.
 *
-* @example
-* ```ts
-* // Delete an organization and everything nested under it
-* await ctx.runMutation(components.auth.groups.groupDelete, {
-*   groupId: organizationGroupId,
-* });
-* ```
 */
 const groupDelete = mutation({
 	args: { groupId: v.id("Group") },
@@ -405,5 +342,5 @@ const groupDelete = mutation({
 });
 
 //#endregion
-export { groupAncestors, groupCreate, groupDelete, groupGet, groupGetMany, groupList, groupUpdate };
+export { groupAncestors, groupCreate, groupDelete, groupGet, groupList, groupUpdate };
 //# sourceMappingURL=core.js.map

package/dist/component/public/groups/invites.js

@@ -1,4 +1,4 @@
-import { vGroupInviteDoc, vInviteAcceptByTokenResult, vInviteStatus, vPaginated } from "../../model.js";
+import { vGroupInviteDoc, vInviteRedeemResult, vInviteStatus, vPaginated } from "../../model.js";
 import { mutation, query } from "../../functions.js";
 import { ConvexError, v } from "convex/values";
 
@@ -28,21 +28,6 @@ import { ConvexError, v } from "convex/values";
 * @param args.extend - Optional arbitrary payload for application-specific metadata.
 * @returns The `Id<"GroupInvite">` of the newly created invite document.
 *
-* @example
-* ```ts
-* const inviteId = await ctx.runMutation(
-*   components.auth.groups.inviteCreate,
-*   {
-*     groupId: teamGroupId,
-*     invitedByUserId: currentUserId,
-*     email: "alice@example.com",
-*     tokenHash: hashedToken,
-*     roleIds: ["editor"],
-*     status: "pending",
-*     expiresTime: Date.now() + 7 * 24 * 60 * 60 * 1000, // 7 days
-*   },
-* );
-* ```
 */
 const inviteCreate = mutation({
 	args: {
@@ -92,57 +77,20 @@ const inviteCreate = mutation({
 	}
 });
 /**
-* Retrieve an invite by its document ID.
+* Read an invite by identity — one function, all-optional args, unioned
+* return: `{ id }` (point lookup) or `{ tokenHash }` (token index).
 *
-* Performs a direct lookup in the `GroupInvite` table and returns the full
-* invite document, or `null` if no invite exists with the given ID.
-*
-* @param args.inviteId - The `Id<"GroupInvite">` of the invite to retrieve.
-* @returns The invite document (including `email`, `status`, `groupId`, `tokenHash`, etc.) or `null` if not found.
-*
-* @example
-* ```ts
-* const invite = await ctx.runQuery(components.auth.groups.inviteGet, {
-*   inviteId: existingInviteId,
-* });
-* if (invite !== null) {
-*   console.log(invite.email, invite.status);
-* }
-* ```
 */
 const inviteGet = query({
-	args: { inviteId: v.id("GroupInvite") },
-	returns: v.union(vGroupInviteDoc, v.null()),
-	handler: async (ctx, { inviteId }) => {
-		return await ctx.db.get("GroupInvite", inviteId);
-	}
-});
-/**
-* Retrieve an invite by its hashed token.
-*
-* Looks up the `GroupInvite` table using the `token_hash` index. This is
-* the primary mechanism for resolving an invite from a URL-embedded token.
-* Returns `null` if no invite matches the given hash.
-*
-* @param args.tokenHash - The hashed token string to look up (must match the value stored at creation time).
-* @returns The invite document or `null` if no invite exists with the given token hash.
-*
-* @example
-* ```ts
-* const invite = await ctx.runQuery(
-*   components.auth.groups.inviteGetByTokenHash,
-*   { tokenHash: "sha256_abc123..." },
-* );
-* if (invite !== null && invite.status === "pending") {
-*   // proceed with acceptance flow
-* }
-* ```
-*/
-const inviteGetByTokenHash = query({
-	args: { tokenHash: v.string() },
+	args: {
+		id: v.optional(v.id("GroupInvite")),
+		tokenHash: v.optional(v.string())
+	},
 	returns: v.union(vGroupInviteDoc, v.null()),
-	handler: async (ctx, { tokenHash }) => {
-		return await ctx.db.query("GroupInvite").withIndex("token_hash", (q) => q.eq("tokenHash", tokenHash)).first();
+	handler: async (ctx, args) => {
+		if (args.tokenHash !== void 0) return await ctx.db.query("GroupInvite").withIndex("token_hash", (q) => q.eq("tokenHash", args.tokenHash)).first();
+		if (args.id === void 0) return null;
+		return await ctx.db.get("GroupInvite", args.id);
 	}
 });
 /**
@@ -169,17 +117,6 @@ const inviteGetByTokenHash = query({
 * @param args.order - Sort direction: `"asc"` or `"desc"` (defaults to `"desc"`).
 * @returns An object `{ items, nextCursor }` where `items` is an array of invite documents and `nextCursor` is `null` when there are no more pages.
 *
-* @example
-* ```ts
-* const { items, nextCursor } = await ctx.runQuery(
-*   components.auth.groups.inviteList,
-*   {
-*     where: { groupId: teamGroupId, status: "pending" },
-*     limit: 25,
-*     order: "desc",
-*   },
-* );
-* ```
 */
 const inviteList = query({
 	args: {
@@ -242,7 +179,7 @@ const inviteList = query({
 * automatically transitioned to `"expired"` and the acceptance is rejected.
 *
 * The caller is responsible for creating the corresponding member record
-* (see {@link inviteAcceptByToken} for an all-in-one alternative that also
+* (see {@link inviteRedeem} for an all-in-one alternative that also
 * handles membership).
 *
 * @param args.inviteId - The `Id<"GroupInvite">` of the invite to accept.
@@ -252,13 +189,6 @@ const inviteList = query({
 * @throws `ConvexError` with code `INVITE_NOT_PENDING` if the invite has already been accepted, revoked, or otherwise finalized.
 * @throws `ConvexError` with code `INVITE_EXPIRED` if the invite's `expiresTime` has passed.
 *
-* @example
-* ```ts
-* await ctx.runMutation(components.auth.groups.inviteAccept, {
-*   inviteId: pendingInviteId,
-*   acceptedByUserId: currentUserId,
-* });
-* ```
 */
 const inviteAccept = mutation({
 	args: {
@@ -321,26 +251,13 @@ const inviteAccept = mutation({
 * @throws `ConvexError` with code `INVITE_NOT_PENDING` if the invite has been revoked or is in another non-pending state.
 * @throws `ConvexError` with code `INVITE_EMAIL_MISMATCH` if the accepting user's email does not match the invite's email.
 *
-* @example
-* ```ts
-* const result = await ctx.runMutation(
-*   components.auth.groups.inviteAcceptByToken,
-*   {
-*     tokenHash: "sha256_abc123...",
-*     acceptedByUserId: currentUserId,
-*   },
-* );
-* if (result.membershipStatus === "joined") {
-*   console.log("Joined group", result.groupId, "as member", result.memberId);
-* }
-* ```
 */
-const inviteAcceptByToken = mutation({
+const inviteRedeem = mutation({
 	args: {
 		tokenHash: v.string(),
 		acceptedByUserId: v.id("User")
 	},
-	returns: vInviteAcceptByTokenResult,
+	returns: vInviteRedeemResult,
 	handler: async (ctx, { tokenHash, acceptedByUserId }) => {
 		const invite = await ctx.db.query("GroupInvite").withIndex("token_hash", (q) => q.eq("tokenHash", tokenHash)).first();
 		if (invite === null) throw new ConvexError({
@@ -424,12 +341,6 @@ const inviteAcceptByToken = mutation({
 * @throws `ConvexError` with code `INVITE_NOT_FOUND` if the invite does not exist.
 * @throws `ConvexError` with code `INVITE_NOT_PENDING` if the invite has already been accepted, revoked, or expired.
 *
-* @example
-* ```ts
-* await ctx.runMutation(components.auth.groups.inviteRevoke, {
-*   inviteId: pendingInviteId,
-* });
-* ```
 */
 const inviteRevoke = mutation({
 	args: { inviteId: v.id("GroupInvite") },
@@ -453,5 +364,5 @@ const inviteRevoke = mutation({
 });
 
 //#endregion
-export { inviteAccept, inviteAcceptByToken, inviteCreate, inviteGet, inviteGetByTokenHash, inviteList, inviteRevoke };
+export { inviteAccept, inviteCreate, inviteGet, inviteList, inviteRedeem, inviteRevoke };
 //# sourceMappingURL=invites.js.map

package/dist/component/public/groups/members.js

@@ -22,18 +22,6 @@ import { ConvexError, v } from "convex/values";
 * @returns The `Id<"GroupMember">` of the newly created member document.
 * @throws `ConvexError` with code `DUPLICATE_MEMBERSHIP` if the user is already a member of this group.
 *
-* @example
-* ```ts
-* const memberId = await ctx.runMutation(
-*   components.auth.groups.memberAdd,
-*   {
-*     groupId: teamGroupId,
-*     userId: newUserId,
-*     roleIds: ["viewer"],
-*     status: "active",
-*   },
-* );
-* ```
 */
 const memberAdd = mutation({
 	args: {
@@ -57,29 +45,33 @@ const memberAdd = mutation({
 	}
 });
 /**
-* Retrieve a member record by its document ID.
-*
-* Performs a direct lookup in the `GroupMember` table and returns the full
-* member document, or `null` if no member exists with the given ID.
-*
-* @param args.memberId - The `Id<"GroupMember">` of the member record to retrieve.
-* @returns The member document (including `groupId`, `userId`, `roleIds`, `status`, etc.) or `null` if not found.
-*
-* @example
-* ```ts
-* const member = await ctx.runQuery(components.auth.groups.memberGet, {
-*   memberId: existingMemberId,
-* });
-* if (member !== null) {
-*   console.log(member.userId, member.roleIds);
-* }
-* ```
+* Read a membership by identity. Accepts exactly one selector:
+* - `{ id }` — point lookup → `Doc | null`.
+* - `{ groupId, userId }` — unique per group+user → `Doc | null`.
+* - `{ userId, groupIds }` — batch: resolve this user's membership in
+*   each group, returning `(Doc | null)[]` aligned to `groupIds` order
+*   (duplicates de-duplicated internally).
 */
 const memberGet = query({
-	args: { memberId: v.id("GroupMember") },
-	returns: v.union(vGroupMemberDoc, v.null()),
-	handler: async (ctx, { memberId }) => {
-		return await ctx.db.get("GroupMember", memberId);
+	args: {
+		id: v.optional(v.id("GroupMember")),
+		groupId: v.optional(v.id("Group")),
+		userId: v.optional(v.id("User")),
+		groupIds: v.optional(v.array(v.id("Group")))
+	},
+	returns: v.union(vGroupMemberDoc, v.null(), v.array(v.union(vGroupMemberDoc, v.null()))),
+	handler: async (ctx, args) => {
+		if (args.userId !== void 0 && args.groupIds !== void 0) {
+			const groupIds = args.groupIds;
+			if (groupIds.length === 0) return [];
+			const unique = Array.from(new Set(groupIds));
+			const docs = await Promise.all(unique.map((groupId) => ctx.db.query("GroupMember").withIndex("group_id_user_id", (q) => q.eq("groupId", groupId).eq("userId", args.userId)).unique()));
+			const byGroupId = new Map(unique.map((id, i) => [id, docs[i] ?? null]));
+			return groupIds.map((id) => byGroupId.get(id) ?? null);
+		}
+		if (args.groupId !== void 0 && args.userId !== void 0) return await ctx.db.query("GroupMember").withIndex("group_id_user_id", (q) => q.eq("groupId", args.groupId).eq("userId", args.userId)).unique();
+		if (args.id === void 0) return null;
+		return await ctx.db.get("GroupMember", args.id);
 	}
 });
 /**
@@ -102,17 +94,6 @@ const memberGet = query({
 * @param args.order - Sort direction: `"asc"` or `"desc"` (defaults to `"desc"`).
 * @returns An object `{ items, nextCursor }` where `items` is an array of member documents and `nextCursor` is `null` when there are no more pages.
 *
-* @example
-* ```ts
-* const { items, nextCursor } = await ctx.runQuery(
-*   components.auth.groups.memberList,
-*   {
-*     where: { groupId: teamGroupId, status: "active" },
-*     limit: 30,
-*     order: "asc",
-*   },
-* );
-* ```
 */
 const memberList = query({
 	args: {
@@ -163,77 +144,6 @@ const memberList = query({
 	}
 });
 /**
-* Look up a specific user's membership in a specific group.
-*
-* Uses the `group_id_user_id` compound index for an efficient exact-match
-* lookup. Returns `null` if the user is not a member of the group. Unlike
-* {@link memberResolve}, this does **not** walk the group hierarchy — it
-* checks only the specified group.
-*
-* @param args.groupId - The `Id<"Group">` of the group to check.
-* @param args.userId - The `Id<"User">` of the user whose membership to look up.
-* @returns The member document or `null` if the user is not a direct member of the group.
-*
-* @example
-* ```ts
-* const member = await ctx.runQuery(
-*   components.auth.groups.memberGetByGroupAndUser,
-*   { groupId: teamGroupId, userId: currentUserId },
-* );
-* if (member !== null) {
-*   console.log("User has roles:", member.roleIds);
-* }
-* ```
-*/
-const memberGetByGroupAndUser = query({
-	args: {
-		groupId: v.id("Group"),
-		userId: v.id("User")
-	},
-	returns: v.union(vGroupMemberDoc, v.null()),
-	handler: async (ctx, { groupId, userId }) => {
-		return await ctx.db.query("GroupMember").withIndex("group_id_user_id", (q) => q.eq("groupId", groupId).eq("userId", userId)).unique();
-	}
-});
-/**
-* Batched equivalent of {@link memberGetByGroupAndUser}. Resolves many
-* `(groupId, userId)` pairs for the same user in a single component
-* round-trip. Used by app-side handlers (e.g. `groups:getDashboard`) that
-* need to inspect the current user's membership across every root group
-* they can see.
-*
-* Each `groupId` is resolved using the `group_id_user_id` index; missing
-* memberships come back as `null` in the same slot order as the input.
-*
-* @param args.userId - The user whose memberships to look up.
-* @param args.groupIds - One or more groups to resolve. Order is preserved;
-*   duplicates tolerated (but de-duplicated internally so the DB only sees
-*   each pair once).
-* @returns Array of member documents or `null` entries, in `groupIds` order.
-*
-* @example
-* ```ts
-* const members = await ctx.runQuery(
-*   components.auth.groups.memberGetByGroupAndUserMany,
-*   { userId: viewerId, groupIds: rootGroupIds },
-* );
-* ```
-*/
-const memberGetByGroupAndUserMany = query({
-	args: {
-		userId: v.id("User"),
-		groupIds: v.array(v.id("Group"))
-	},
-	returns: v.array(v.union(vGroupMemberDoc, v.null())),
-	handler: async (ctx, { userId, groupIds }) => {
-		if (groupIds.length === 0) return [];
-		const unique = Array.from(new Set(groupIds));
-		const docs = await Promise.all(unique.map((groupId) => ctx.db.query("GroupMember").withIndex("group_id_user_id", (q) => q.eq("groupId", groupId).eq("userId", userId)).unique()));
-		const byGroupId = new Map(unique.map((id, i) => [id, docs[i] ?? null]));
-		return groupIds.map((id) => byGroupId.get(id) ?? null);
-	}
-});
-/**
 * Resolve a user's membership by walking the group hierarchy from the
 * requested group up to the root. Returns the first matching membership
 * found, enabling inherited (ancestor-level) access checks.
@@ -261,23 +171,6 @@ const memberGetByGroupAndUserMany = query({
 *   - `isInherited` — `true` when `depth > 0`.
 *   - `traversedGroupIds` — (only when `ancestry` is `true`) array of group IDs visited.
 *
-* @example
-* ```ts
-* const result = await ctx.runQuery(
-*   components.auth.groups.memberResolve,
-*   {
-*     userId: currentUserId,
-*     groupId: subTeamGroupId,
-*     maxDepth: 5,
-*     ancestry: true,
-*   },
-* );
-* if (result.membership !== null) {
-*   console.log(
-*     result.isDirect ? "Direct member" : `Inherited from depth ${result.depth}`,
-*   );
-* }
-* ```
 */
 const memberResolve = query({
 	args: {
@@ -339,12 +232,6 @@ const memberResolve = query({
 * @param args.memberId - The `Id<"GroupMember">` of the member record to delete.
 * @returns `null` on success.
 *
-* @example
-* ```ts
-* await ctx.runMutation(components.auth.groups.memberRemove, {
-*   memberId: memberToRemoveId,
-* });
-* ```
 */
 const memberRemove = mutation({
 	args: { memberId: v.id("GroupMember") },
@@ -365,16 +252,6 @@ const memberRemove = mutation({
 * @param args.data - A partial object of fields to patch. Supported keys include `roleIds`, `status`, and `extend`.
 * @returns `null` on success.
 *
-* @example
-* ```ts
-* await ctx.runMutation(components.auth.groups.memberUpdate, {
-*   memberId: existingMemberId,
-*   data: {
-*     roleIds: ["admin", "editor"],
-*     status: "active",
-*   },
-* });
-* ```
 */
 const memberUpdate = mutation({
 	args: {
@@ -389,5 +266,5 @@ const memberUpdate = mutation({
 });
 
 //#endregion
-export { memberAdd, memberGet, memberGetByGroupAndUser, memberGetByGroupAndUserMany, memberList, memberRemove, memberResolve, memberUpdate };
+export { memberAdd, memberGet, memberList, memberRemove, memberResolve, memberUpdate };
 //# sourceMappingURL=members.js.map