@robelest/convex-auth 0.0.2-preview.0 → 0.0.2-preview.2

package/dist/component/public.js

@@ -1,12 +1,20 @@
-import { v } from "convex/values";
+import { ConvexError, v } from "convex/values";
 import { mutation, query } from "./_generated/server";
+// ============================================================================
 // Users
+// ============================================================================
+/** Retrieve a user by their document ID. */
 export const userGetById = query({
     args: { userId: v.id("user") },
     handler: async (ctx, { userId }) => {
         return await ctx.db.get(userId);
     },
 });
+/**
+ * Find a user by their verified email address. Returns `null` if no user
+ * has this email verified, or if multiple users share the same verified email
+ * (ambiguous — should not happen in normal operation).
+ */
 export const userFindByVerifiedEmail = query({
     args: { email: v.string() },
     handler: async (ctx, { email }) => {
@@ -18,6 +26,11 @@ export const userFindByVerifiedEmail = query({
         return users.length === 1 ? users[0] : null;
     },
 });
+/**
+ * Find a user by their verified phone number. Returns `null` if no user
+ * has this phone verified, or if multiple users share the same verified phone
+ * (ambiguous — should not happen in normal operation).
+ */
 export const userFindByVerifiedPhone = query({
     args: { phone: v.string() },
     handler: async (ctx, { phone }) => {
@@ -29,12 +42,14 @@ export const userFindByVerifiedPhone = query({
         return users.length === 1 ? users[0] : null;
     },
 });
+/** Insert a new user document. */
 export const userInsert = mutation({
     args: { data: v.any() },
     handler: async (ctx, { data }) => {
         return await ctx.db.insert("user", data);
     },
 });
+/** Insert a new user or update an existing one. */
 export const userUpsert = mutation({
     args: { userId: v.optional(v.id("user")), data: v.any() },
     handler: async (ctx, { userId, data }) => {
@@ -45,13 +60,17 @@ export const userUpsert = mutation({
         return await ctx.db.insert("user", data);
     },
 });
+/** Patch an existing user document with partial data. */
 export const userPatch = mutation({
     args: { userId: v.id("user"), data: v.any() },
     handler: async (ctx, { userId, data }) => {
         await ctx.db.patch(userId, data);
     },
 });
+// ============================================================================
 // Accounts
+// ============================================================================
+/** Look up an account by provider and provider-specific account ID. */
 export const accountGet = query({
     args: { provider: v.string(), providerAccountId: v.string() },
     handler: async (ctx, { provider, providerAccountId }) => {
@@ -61,12 +80,14 @@ export const accountGet = query({
             .unique();
     },
 });
+/** Retrieve an account by its document ID. */
 export const accountGetById = query({
     args: { accountId: v.id("account") },
     handler: async (ctx, { accountId }) => {
         return await ctx.db.get(accountId);
     },
 });
+/** Create a new account linking a user to an auth provider. */
 export const accountInsert = mutation({
     args: {
         userId: v.id("user"),
@@ -78,19 +99,24 @@ export const accountInsert = mutation({
         return await ctx.db.insert("account", args);
     },
 });
+/** Patch an existing account document with partial data. */
 export const accountPatch = mutation({
     args: { accountId: v.id("account"), data: v.any() },
     handler: async (ctx, { accountId, data }) => {
         await ctx.db.patch(accountId, data);
     },
 });
+/** Delete an account document. */
 export const accountDelete = mutation({
     args: { accountId: v.id("account") },
     handler: async (ctx, { accountId }) => {
         await ctx.db.delete(accountId);
     },
 });
+// ============================================================================
 // Sessions
+// ============================================================================
+/** Create a new session for a user with an expiration time. */
 export const sessionCreate = mutation({
     args: { userId: v.id("user"), expirationTime: v.number() },
     handler: async (ctx, { userId, expirationTime }) => {
@@ -100,12 +126,14 @@ export const sessionCreate = mutation({
         });
     },
 });
+/** Retrieve a session by its document ID. */
 export const sessionGetById = query({
     args: { sessionId: v.id("session") },
     handler: async (ctx, { sessionId }) => {
         return await ctx.db.get(sessionId);
     },
 });
+/** Delete a session. No-op if the session does not exist. */
 export const sessionDelete = mutation({
     args: { sessionId: v.id("session") },
     handler: async (ctx, { sessionId }) => {
@@ -114,6 +142,7 @@ export const sessionDelete = mutation({
         }
     },
 });
+/** List all sessions for a user. */
 export const sessionListByUser = query({
     args: { userId: v.id("user") },
     handler: async (ctx, { userId }) => {
@@ -123,19 +152,24 @@ export const sessionListByUser = query({
             .collect();
     },
 });
+// ============================================================================
 // Verifiers
+// ============================================================================
+/** Create a new PKCE verifier, optionally linked to a session. */
 export const verifierCreate = mutation({
     args: { sessionId: v.optional(v.id("session")) },
     handler: async (ctx, { sessionId }) => {
         return await ctx.db.insert("verifier", { sessionId: sessionId });
     },
 });
+/** Retrieve a verifier by its document ID. */
 export const verifierGetById = query({
     args: { verifierId: v.id("verifier") },
     handler: async (ctx, { verifierId }) => {
         return await ctx.db.get(verifierId);
     },
 });
+/** Look up a verifier by its cryptographic signature. */
 export const verifierGetBySignature = query({
     args: { signature: v.string() },
     handler: async (ctx, { signature }) => {
@@ -145,19 +179,24 @@ export const verifierGetBySignature = query({
             .unique();
     },
 });
+/** Patch a verifier document with partial data. */
 export const verifierPatch = mutation({
     args: { verifierId: v.id("verifier"), data: v.any() },
     handler: async (ctx, { verifierId, data }) => {
         await ctx.db.patch(verifierId, data);
     },
 });
+/** Delete a verifier document. */
 export const verifierDelete = mutation({
     args: { verifierId: v.id("verifier") },
     handler: async (ctx, { verifierId }) => {
         await ctx.db.delete(verifierId);
     },
 });
-// Verification codes
+// ============================================================================
+// Verification Codes
+// ============================================================================
+/** Find a verification code by its associated account ID. */
 export const verificationCodeGetByAccountId = query({
     args: { accountId: v.id("account") },
     handler: async (ctx, { accountId }) => {
@@ -167,6 +206,7 @@ export const verificationCodeGetByAccountId = query({
             .unique();
     },
 });
+/** Find a verification code by its code string. */
 export const verificationCodeGetByCode = query({
     args: { code: v.string() },
     handler: async (ctx, { code }) => {
@@ -176,6 +216,7 @@ export const verificationCodeGetByCode = query({
             .unique();
     },
 });
+/** Create a new verification code for OTP, magic link, or OAuth flows. */
 export const verificationCodeCreate = mutation({
     args: {
         accountId: v.id("account"),
@@ -190,13 +231,17 @@ export const verificationCodeCreate = mutation({
         return await ctx.db.insert("verification", args);
     },
 });
+/** Delete a verification code document. */
 export const verificationCodeDelete = mutation({
     args: { verificationCodeId: v.id("verification") },
     handler: async (ctx, { verificationCodeId }) => {
         await ctx.db.delete(verificationCodeId);
     },
 });
-// Refresh tokens
+// ============================================================================
+// Refresh Tokens
+// ============================================================================
+/** Create a new refresh token for a session. */
 export const refreshTokenCreate = mutation({
     args: {
         sessionId: v.id("session"),
@@ -207,18 +252,21 @@ export const refreshTokenCreate = mutation({
         return await ctx.db.insert("token", args);
     },
 });
+/** Retrieve a refresh token by its document ID. */
 export const refreshTokenGetById = query({
     args: { refreshTokenId: v.id("token") },
     handler: async (ctx, { refreshTokenId }) => {
         return await ctx.db.get(refreshTokenId);
     },
 });
+/** Patch a refresh token document with partial data. */
 export const refreshTokenPatch = mutation({
     args: { refreshTokenId: v.id("token"), data: v.any() },
     handler: async (ctx, { refreshTokenId, data }) => {
         await ctx.db.patch(refreshTokenId, data);
     },
 });
+/** Get child tokens that were created by exchanging a specific parent token. */
 export const refreshTokenGetChildren = query({
     args: {
         sessionId: v.id("session"),
@@ -233,6 +281,7 @@ export const refreshTokenGetChildren = query({
             .collect();
     },
 });
+/** List all refresh tokens for a session. */
 export const refreshTokenListBySession = query({
     args: { sessionId: v.id("session") },
     handler: async (ctx, { sessionId }) => {
@@ -242,6 +291,7 @@ export const refreshTokenListBySession = query({
             .collect();
     },
 });
+/** Delete all refresh tokens for a session. */
 export const refreshTokenDeleteAll = mutation({
     args: { sessionId: v.id("session") },
     handler: async (ctx, { sessionId }) => {
@@ -252,6 +302,7 @@ export const refreshTokenDeleteAll = mutation({
         await Promise.all(tokens.map((token) => ctx.db.delete(token._id)));
     },
 });
+/** Get the active (unused) refresh token for a session. */
 export const refreshTokenGetActive = query({
     args: { sessionId: v.id("session") },
     handler: async (ctx, { sessionId }) => {
@@ -263,7 +314,10 @@ export const refreshTokenGetActive = query({
             .first();
     },
 });
-// Rate limits
+// ============================================================================
+// Rate Limits
+// ============================================================================
+/** Look up a rate limit entry by its identifier. */
 export const rateLimitGet = query({
     args: { identifier: v.string() },
     handler: async (ctx, { identifier }) => {
@@ -273,6 +327,7 @@ export const rateLimitGet = query({
             .unique();
     },
 });
+/** Create a new rate limit entry. */
 export const rateLimitCreate = mutation({
     args: {
         identifier: v.string(),
@@ -283,245 +338,363 @@ export const rateLimitCreate = mutation({
         return await ctx.db.insert("limit", args);
     },
 });
+/** Patch a rate limit entry with partial data. */
 export const rateLimitPatch = mutation({
     args: { rateLimitId: v.id("limit"), data: v.any() },
     handler: async (ctx, { rateLimitId, data }) => {
         await ctx.db.patch(rateLimitId, data);
     },
 });
+/** Delete a rate limit entry. */
 export const rateLimitDelete = mutation({
     args: { rateLimitId: v.id("limit") },
     handler: async (ctx, { rateLimitId }) => {
         await ctx.db.delete(rateLimitId);
     },
 });
-// Singular aliases
-export const verificationGetByAccountId = verificationCodeGetByAccountId;
-export const verificationGetByCode = verificationCodeGetByCode;
-export const verificationCreate = verificationCodeCreate;
-export const verificationDelete = verificationCodeDelete;
-export const tokenCreate = refreshTokenCreate;
-export const tokenGetById = refreshTokenGetById;
-export const tokenPatch = refreshTokenPatch;
-export const tokenGetChildren = refreshTokenGetChildren;
-export const tokenListBySession = refreshTokenListBySession;
-export const tokenDeleteAll = refreshTokenDeleteAll;
-export const tokenGetActive = refreshTokenGetActive;
-export const limitGet = rateLimitGet;
-export const limitCreate = rateLimitCreate;
-export const limitPatch = rateLimitPatch;
-export const limitDelete = rateLimitDelete;
-// Organization
-export const organizationCreate = mutation({
-    args: { data: v.any() },
-    handler: async (ctx, { data }) => {
-        return await ctx.db.insert("organization", data);
-    },
-});
-export const organizationGet = query({
-    args: { organizationId: v.id("organization") },
-    handler: async (ctx, { organizationId }) => {
-        return await ctx.db.get(organizationId);
-    },
-});
-export const organizationList = query({
-    args: { ownerUserId: v.optional(v.id("user")) },
-    handler: async (ctx, { ownerUserId }) => {
-        if (ownerUserId === undefined) {
-            return await ctx.db.query("organization").collect();
-        }
-        return await ctx.db
-            .query("organization")
-            .withIndex("ownerUserId", (q) => q.eq("ownerUserId", ownerUserId))
-            .collect();
-    },
-});
-export const organizationUpdate = mutation({
-    args: { organizationId: v.id("organization"), data: v.any() },
-    handler: async (ctx, { organizationId, data }) => {
-        await ctx.db.patch(organizationId, data);
-    },
-});
-export const organizationDelete = mutation({
-    args: { organizationId: v.id("organization") },
-    handler: async (ctx, { organizationId }) => {
-        await ctx.db.delete(organizationId);
-    },
-});
-// Team
-export const teamCreate = mutation({
+// ============================================================================
+// Groups
+// ============================================================================
+/**
+ * Create a new group. Groups are hierarchical — set `parentGroupId` to nest
+ * under an existing group, or omit it to create a root-level group.
+ *
+ * @returns The ID of the newly created group.
+ */
+export const groupCreate = mutation({
     args: {
-        organizationId: v.id("organization"),
         name: v.string(),
         slug: v.optional(v.string()),
-        parentTeamId: v.optional(v.id("team")),
-        metadata: v.optional(v.any()),
+        parentGroupId: v.optional(v.id("group")),
+        extend: v.optional(v.any()),
     },
     handler: async (ctx, args) => {
-        return await ctx.db.insert("team", args);
+        return await ctx.db.insert("group", args);
     },
 });
-export const teamGet = query({
-    args: { teamId: v.id("team") },
-    handler: async (ctx, { teamId }) => {
-        return await ctx.db.get(teamId);
+/** Retrieve a group by its document ID. Returns `null` if not found. */
+export const groupGet = query({
+    args: { groupId: v.id("group") },
+    handler: async (ctx, { groupId }) => {
+        return await ctx.db.get(groupId);
     },
 });
-export const teamListByOrganization = query({
-    args: { organizationId: v.id("organization") },
-    handler: async (ctx, { organizationId }) => {
+/**
+ * List groups. When `parentGroupId` is provided, returns children of that
+ * group. When omitted, returns all root-level groups (groups with no parent).
+ */
+export const groupList = query({
+    args: { parentGroupId: v.optional(v.id("group")) },
+    handler: async (ctx, { parentGroupId }) => {
         return await ctx.db
-            .query("team")
-            .withIndex("organizationId", (q) => q.eq("organizationId", organizationId))
+            .query("group")
+            .withIndex("parentGroupId", (q) => q.eq("parentGroupId", parentGroupId))
             .collect();
     },
 });
-export const teamUpdate = mutation({
-    args: { teamId: v.id("team"), data: v.any() },
-    handler: async (ctx, { teamId, data }) => {
-        await ctx.db.patch(teamId, data);
-    },
-});
-export const teamDelete = mutation({
-    args: { teamId: v.id("team") },
-    handler: async (ctx, { teamId }) => {
-        await ctx.db.delete(teamId);
+/** Update a group's fields (name, slug, extend, parentGroupId). */
+export const groupUpdate = mutation({
+    args: { groupId: v.id("group"), data: v.any() },
+    handler: async (ctx, { groupId, data }) => {
+        await ctx.db.patch(groupId, data);
+    },
+});
+/**
+ * Delete a group and all of its descendants. This cascades to:
+ * - All child groups (recursively)
+ * - All members of this group and its descendants
+ * - All invites for this group and its descendants
+ */
+export const groupDelete = mutation({
+    args: { groupId: v.id("group") },
+    handler: async (ctx, { groupId }) => {
+        const deleteGroup = async (id) => {
+            const children = await ctx.db
+                .query("group")
+                .withIndex("parentGroupId", (q) => q.eq("parentGroupId", id))
+                .collect();
+            for (const child of children) {
+                await deleteGroup(child._id);
+            }
+            const members = await ctx.db
+                .query("member")
+                .withIndex("groupId", (q) => q.eq("groupId", id))
+                .collect();
+            for (const member of members) {
+                await ctx.db.delete(member._id);
+            }
+            const invites = await ctx.db
+                .query("invite")
+                .withIndex("groupId", (q) => q.eq("groupId", id))
+                .collect();
+            for (const invite of invites) {
+                await ctx.db.delete(invite._id);
+            }
+            await ctx.db.delete(id);
+        };
+        await deleteGroup(groupId);
     },
 });
-// Team relations
-export const teamRelationCreate = mutation({
+// ============================================================================
+// Members
+// ============================================================================
+/**
+ * Add a user as a member of a group.
+ *
+ * The `role` field is an application-defined string (e.g. "owner", "admin",
+ * "member", "viewer"). The auth component stores it but does not enforce
+ * access control — your application defines what each role means.
+ *
+ * Throws `ConvexError` with code `DUPLICATE_MEMBERSHIP` when the user is
+ * already a member of the target group.
+ *
+ * @returns The ID of the new member record.
+ */
+export const memberAdd = mutation({
     args: {
-        organizationId: v.id("organization"),
-        parentTeamId: v.id("team"),
-        childTeamId: v.id("team"),
-        relation: v.optional(v.string()),
+        groupId: v.id("group"),
+        userId: v.id("user"),
+        role: v.optional(v.string()),
+        status: v.optional(v.string()),
+        extend: v.optional(v.any()),
     },
     handler: async (ctx, args) => {
-        return await ctx.db.insert("teamRelation", args);
+        const existingMembership = await ctx.db
+            .query("member")
+            .withIndex("groupIdAndUserId", (q) => q.eq("groupId", args.groupId).eq("userId", args.userId))
+            .unique();
+        if (existingMembership !== null) {
+            throw new ConvexError({
+                code: "DUPLICATE_MEMBERSHIP",
+                message: "User is already a member of this group",
+                groupId: args.groupId,
+                userId: args.userId,
+                existingMemberId: existingMembership._id,
+            });
+        }
+        return await ctx.db.insert("member", args);
     },
 });
-export const teamRelationGet = query({
-    args: { teamRelationId: v.id("teamRelation") },
-    handler: async (ctx, { teamRelationId }) => {
-        return await ctx.db.get(teamRelationId);
+/** Retrieve a member record by its document ID. Returns `null` if not found. */
+export const memberGet = query({
+    args: { memberId: v.id("member") },
+    handler: async (ctx, { memberId }) => {
+        return await ctx.db.get(memberId);
     },
 });
-export const teamRelationListByParent = query({
-    args: {
-        organizationId: v.id("organization"),
-        parentTeamId: v.id("team"),
-    },
-    handler: async (ctx, { organizationId, parentTeamId }) => {
+/** List all members of a specific group. */
+export const memberList = query({
+    args: { groupId: v.id("group") },
+    handler: async (ctx, { groupId }) => {
         return await ctx.db
-            .query("teamRelation")
-            .withIndex("organizationIdAndParentTeamId", (q) => q.eq("organizationId", organizationId).eq("parentTeamId", parentTeamId))
+            .query("member")
+            .withIndex("groupId", (q) => q.eq("groupId", groupId))
             .collect();
     },
 });
-export const teamRelationDelete = mutation({
-    args: { teamRelationId: v.id("teamRelation") },
-    handler: async (ctx, { teamRelationId }) => {
-        await ctx.db.delete(teamRelationId);
+/**
+ * List all group memberships for a specific user. Returns member records
+ * which include the `groupId`, `role`, `status`, and `extend` for each
+ * group the user belongs to.
+ */
+export const memberListByUser = query({
+    args: { userId: v.id("user") },
+    handler: async (ctx, { userId }) => {
+        return await ctx.db
+            .query("member")
+            .withIndex("userId", (q) => q.eq("userId", userId))
+            .collect();
     },
 });
-// Members
-export const memberAdd = mutation({
-    args: { data: v.any() },
-    handler: async (ctx, { data }) => {
-        return await ctx.db.insert("member", data);
+/**
+ * Look up a specific user's membership in a specific group.
+ * Returns `null` if the user is not a member of the group.
+ */
+export const memberGetByGroupAndUser = query({
+    args: { groupId: v.id("group"), userId: v.id("user") },
+    handler: async (ctx, { groupId, userId }) => {
+        return await ctx.db
+            .query("member")
+            .withIndex("groupIdAndUserId", (q) => q.eq("groupId", groupId).eq("userId", userId))
+            .unique();
     },
 });
+/** Remove a member from a group by deleting the member record. */
 export const memberRemove = mutation({
     args: { memberId: v.id("member") },
     handler: async (ctx, { memberId }) => {
         await ctx.db.delete(memberId);
     },
 });
-export const memberList = query({
-    args: {
-        organizationId: v.id("organization"),
-        teamId: v.optional(v.id("team")),
-    },
-    handler: async (ctx, { organizationId, teamId }) => {
-        if (teamId !== undefined) {
-            return await ctx.db
-                .query("member")
-                .withIndex("teamId", (q) => q.eq("teamId", teamId))
-                .collect();
-        }
-        return await ctx.db
-            .query("member")
-            .withIndex("organizationId", (q) => q.eq("organizationId", organizationId))
-            .collect();
-    },
-});
-export const memberRoleSet = mutation({
-    args: { memberId: v.id("member"), role: v.string() },
-    handler: async (ctx, { memberId, role }) => {
-        await ctx.db.patch(memberId, { role });
-    },
-});
-export const memberRoleGet = query({
-    args: { memberId: v.id("member") },
-    handler: async (ctx, { memberId }) => {
-        const member = await ctx.db.get(memberId);
-        return member?.role ?? null;
+/**
+ * Update a member record's fields (role, status, extend).
+ *
+ * Common usage: `memberUpdate({ memberId, data: { role: "admin" } })`
+ */
+export const memberUpdate = mutation({
+    args: { memberId: v.id("member"), data: v.any() },
+    handler: async (ctx, { memberId, data }) => {
+        await ctx.db.patch(memberId, data);
     },
 });
+// ============================================================================
 // Invites
+// ============================================================================
+/**
+ * Create a new platform-level invitation. Optionally set `groupId` to tie
+ * the invite to a specific group. The invitation is sent to an email address
+ * and includes a hashed token for secure acceptance.
+ *
+ * Throws `ConvexError` with code `DUPLICATE_INVITE` when a pending invite
+ * already exists for the same email and scope:
+ * - group invite: same `email` + same `groupId`
+ * - platform invite: same `email` with no `groupId`
+ *
+ * @returns The ID of the new invite record.
+ */
 export const inviteCreate = mutation({
-    args: { data: v.any() },
-    handler: async (ctx, { data }) => {
-        return await ctx.db.insert("invite", data);
+    args: {
+        groupId: v.optional(v.id("group")),
+        invitedByUserId: v.id("user"),
+        email: v.string(),
+        tokenHash: v.string(),
+        role: v.optional(v.string()),
+        status: v.union(v.literal("pending"), v.literal("accepted"), v.literal("revoked"), v.literal("expired")),
+        expiresTime: v.number(),
+        extend: v.optional(v.any()),
+    },
+    handler: async (ctx, args) => {
+        if (args.groupId !== undefined) {
+            const existingGroupInvite = await ctx.db
+                .query("invite")
+                .withIndex("groupIdAndStatus", (q) => q.eq("groupId", args.groupId).eq("status", "pending"))
+                .filter((q) => q.eq(q.field("email"), args.email))
+                .first();
+            if (existingGroupInvite !== null) {
+                throw new ConvexError({
+                    code: "DUPLICATE_INVITE",
+                    message: "A pending invite already exists for this email in this group",
+                    email: args.email,
+                    groupId: args.groupId,
+                    existingInviteId: existingGroupInvite._id,
+                });
+            }
+        }
+        else {
+            const existingPlatformInvite = await ctx.db
+                .query("invite")
+                .withIndex("emailAndStatus", (q) => q.eq("email", args.email).eq("status", "pending"))
+                .filter((q) => q.eq(q.field("groupId"), undefined))
+                .first();
+            if (existingPlatformInvite !== null) {
+                throw new ConvexError({
+                    code: "DUPLICATE_INVITE",
+                    message: "A pending platform invite already exists for this email",
+                    email: args.email,
+                    existingInviteId: existingPlatformInvite._id,
+                });
+            }
+        }
+        return await ctx.db.insert("invite", args);
     },
 });
+/** Retrieve an invite by its document ID. Returns `null` if not found. */
 export const inviteGet = query({
     args: { inviteId: v.id("invite") },
     handler: async (ctx, { inviteId }) => {
         return await ctx.db.get(inviteId);
     },
 });
+/**
+ * List invites, optionally filtered by group and/or status.
+ * Both `groupId` and `status` are optional filters.
+ */
 export const inviteList = query({
     args: {
-        organizationId: v.optional(v.id("organization")),
-        status: v.optional(v.string()),
+        groupId: v.optional(v.id("group")),
+        status: v.optional(v.union(v.literal("pending"), v.literal("accepted"), v.literal("revoked"), v.literal("expired"))),
     },
-    handler: async (ctx, { organizationId, status }) => {
-        if (organizationId !== undefined && status !== undefined) {
+    handler: async (ctx, { groupId, status }) => {
+        if (groupId !== undefined && status !== undefined) {
             return await ctx.db
                 .query("invite")
-                .withIndex("organizationIdAndStatus", (q) => q.eq("organizationId", organizationId).eq("status", status))
+                .withIndex("groupIdAndStatus", (q) => q.eq("groupId", groupId).eq("status", status))
                 .collect();
         }
-        if (organizationId !== undefined) {
+        if (groupId !== undefined) {
             return await ctx.db
                 .query("invite")
-                .withIndex("organizationId", (q) => q.eq("organizationId", organizationId))
+                .withIndex("groupId", (q) => q.eq("groupId", groupId))
                 .collect();
         }
         if (status !== undefined) {
             return await ctx.db
                 .query("invite")
-                .filter((q) => q.eq(q.field("status"), status))
+                .withIndex("status", (q) => q.eq("status", status))
                 .collect();
         }
-        return await ctx.db
-            .query("invite")
-            .collect();
-    },
-});
+        return await ctx.db.query("invite").collect();
+    },
+});
+/**
+ * Accept a pending invitation.
+ *
+ * Marks the invite as "accepted" and records the acceptance timestamp.
+ * Throws a structured `ConvexError` when the invite doesn't exist or is not
+ * currently pending.
+ *
+ * The caller is responsible for creating the corresponding member record.
+ */
 export const inviteAccept = mutation({
     args: { inviteId: v.id("invite") },
     handler: async (ctx, { inviteId }) => {
+        const invite = await ctx.db.get(inviteId);
+        if (invite === null) {
+            throw new ConvexError({
+                code: "INVITE_NOT_FOUND",
+                message: "Invite not found",
+                inviteId,
+            });
+        }
+        if (invite.status !== "pending") {
+            throw new ConvexError({
+                code: "INVITE_NOT_PENDING",
+                message: `Cannot accept invite with status "${invite.status}"`,
+                inviteId,
+                currentStatus: invite.status,
+            });
+        }
         await ctx.db.patch(inviteId, {
             status: "accepted",
             acceptedTime: Date.now(),
         });
     },
 });
+/**
+ * Revoke a pending invitation.
+ *
+ * Marks the invite as "revoked". Throws a structured `ConvexError` when the
+ * invite doesn't exist or is not currently pending.
+ */
 export const inviteRevoke = mutation({
     args: { inviteId: v.id("invite") },
     handler: async (ctx, { inviteId }) => {
+        const invite = await ctx.db.get(inviteId);
+        if (invite === null) {
+            throw new ConvexError({
+                code: "INVITE_NOT_FOUND",
+                message: "Invite not found",
+                inviteId,
+            });
+        }
+        if (invite.status !== "pending") {
+            throw new ConvexError({
+                code: "INVITE_NOT_PENDING",
+                message: `Cannot revoke invite with status "${invite.status}"`,
+                inviteId,
+                currentStatus: invite.status,
+            });
+        }
         await ctx.db.patch(inviteId, { status: "revoked" });
     },
 });