Convex Invite-links

Copy codenpm install convex-invite-links

Copy code// convex/convex.config.ts
import { defineApp } from "convex/server";
import inviteLinks from "convex-invite-links/convex.config";

const app = defineApp();
app.use(inviteLinks);

export default app;

Copy code// convex/invites.ts
import { InviteLinks } from "convex-invite-links";
import { components } from "./_generated/api.js";

const invites = new InviteLinks(components.inviteLinks, {
  defaultExpiryMs: 7 * 24 * 60 * 60 * 1000, // 7 days
  baseUrl: "https://myapp.com/invite",
});

Copy codeimport { mutation } from "./_generated/server.js";
import { v } from "convex/values";

export const createInvite = mutation({
  args: { email: v.optional(v.string()), groupId: v.string() },
  handler: async (ctx, args) => {
    const userId = await getAuthUserId(ctx);

    const result = await invites.makeInvite(ctx, {
      email: args.email,
      groupId: args.groupId,
      createdBy: userId,
      destinationUrl: "https://myapp.com/dashboard",
      metadata: { role: "member" },
      ogTitle: "Join My Team",
      ogDescription: "You've been invited to collaborate!",
    });

    // Generate a shareable URL
    const url = invites.makeInviteUrl(result.token);
    return { ...result, url };
  },
});

Copy codeexport const acceptInvite = mutation({
  args: { token: v.string() },
  handler: async (ctx, args) => {
    const userId = await getAuthUserId(ctx);
    const userEmail = await getUserEmail(ctx);

    const result = await invites.claimInvite(ctx, {
      token: args.token,
      userId,
      email: userEmail,
    });

    if (!result.ok) {
      throw new Error(`Invite invalid: ${result.reason}`);
      // reason: "invalid" | "expired" | "revoked" | "already_claimed"
      //         | "email_mismatch" | "phone_mismatch"
    }

    return {
      destinationUrl: result.destinationUrl,
      groupId: result.groupId,
    };
  },
});

Copy codeexport const checkAccess = query({
  args: { groupId: v.string() },
  handler: async (ctx, args) => {
    const userId = await getAuthUserId(ctx);

    const isMember = await invites.isMember(ctx, {
      userId,
      groupId: args.groupId,
    });

    return { isMember };
  },
});

Copy code// Add a user to a group directly (without invite)
await invites.addMember(ctx, {
  userId: targetUserId,
  groupId: "team_123",
  addedBy: adminUserId,
});

// Grant resource access directly
await invites.grantAccess(ctx, {
  userId: targetUserId,
  resourceId: "doc_456",
  grantedBy: adminUserId,
});

// Remove membership or access
await invites.removeMember(ctx, { userId, groupId: "team_123" });
await invites.revokeAccess(ctx, { userId, resourceId: "doc_456" });

Copy code// Revoke by ID
await invites.revokeInvite(ctx, { inviteId: "invite_id_here" });

// Revoke by token
await invites.revokeInviteByToken(ctx, { token: "inv_abc123..." });

// List pending invites for a group
const pending = await invites.listInvites(ctx, {
  groupId: "team_123",
});

// List all invites including claimed/expired
const all = await invites.listInvites(ctx, {
  groupId: "team_123",
  includeClaimed: true,
  includeRevoked: true,
  includeExpired: true,
});

Copy code// In a cron job (convex/crons.ts)
import { cronJobs } from "convex/server";
import { internal } from "./_generated/api.js";

const crons = cronJobs();
crons.daily("cleanup invites", { hourUTC: 3, minuteUTC: 0 }, internal.invites.cleanupOld);
export default crons;

// In your invites file
export const cleanupOld = internalMutation({
  handler: async (ctx) => {
    const deleted = await invites.deleteOldInvites(ctx, {
      olderThanMs: 30 * 24 * 60 * 60 * 1000,
    });
    console.log(`Cleaned up ${deleted} old invites`);
  },
});

Copy codeimport { handleInviteWebhook } from "convex-invite-links";
import { httpRouter } from "convex/server";

const http = httpRouter();

const inviteHandler = handleInviteWebhook(components.inviteLinks, {
  appName: "My App",
  redirectUrl: "https://myapp.com/accept-invite",
});

http.route({
  path: "/invite",
  method: "GET",
  handler: httpAction(async (ctx, request) => {
    return await inviteHandler(ctx, request);
  }),
});

export default http;

Copy code// In an HTTP action or server function
const token = invites.inviteFromUrl(request);
if (token) {
  const invite = await invites.getInviteByToken(ctx, { token });
  if (invite?.isValid) {
    // Show invite acceptance page
  }
}