Skip to main content

​
Overview

The InviteType and related types define the structure of invitation data stored in the database and used throughout the invite plugin.

​
InviteType

Core invitation data structure without the database ID. 
export type InviteType = {
  token: string;
  createdByUserId: string;
  createdAt: Date;
  expiresAt: Date;
  maxUses: number;
  redirectToAfterUpgrade?: string;
  shareInviterName: boolean;
  email?: string;
  role: string;
  newAccount?: boolean;
  status: InvitationStatus;
};

​
Fields

​
token
string
required
Unique invitation token used for activation. Generated based on tokenType:
  • "token": 24-character random string
  • "code": 6-character alphanumeric code
  • "custom": Generated by options.generateToken
​
createdByUserId
string
required
ID of the user who created this invitation.
​
createdAt
Date
required
Timestamp when the invitation was created.
​
expiresAt
Date
required
Timestamp when the invitation expires. Calculated as createdAt + invitationTokenExpiresIn.
​
maxUses
number
required
Maximum number of times this invitation can be used.
  • Default: 1 for private invites (with email)
  • Default: Infinity for public invites (no email)
​
redirectToAfterUpgrade
string
Optional URL to redirect users to after accepting the invitation (for logged-in users). Can include {token} placeholder which will be replaced with the actual token.
​
shareInviterName
boolean
required
Whether to share the inviter’s name with the invitee. When true, the invitee can see who invited them via the getInvite endpoint.
​
email
string
Email address for private invitations. When present:
  • Only the user with this email can accept/reject
  • Creates a private invite
  • Email notification is sent
When absent:
  • Creates a public invite (shareable link)
  • Anyone with the token can accept
​
role
string
required
The role to assign to the user when they accept the invitation.
​
newAccount
boolean
Only set for private invites. Indicates whether this invitation is for:
  • true: A new user who needs to create an account
  • false: An existing user who will get a role upgrade
This field is determined when the invitation is created based on whether a user with the email already exists.
​
status
InvitationStatus
required
Current status of the invitation. See InvitationStatus below.

​
InviteTypeWithId

Invitation type with database ID included. 
export type InviteTypeWithId = InviteType & {
  id: string;
};
This type is used when working with invitation records retrieved from the database.

​
Fields

Includes all fields from InviteType plus:
​
id
string
required
Unique database identifier for the invitation.

​
InvitationStatus

Enum-like type defining the possible states of an invitation. 
export type InvitationStatus = "pending" | "rejected" | "canceled" | "used";

​
Status Values

​
pending
status
Initial state. Invitation has been created but not yet accepted, rejected, or canceled.
​
rejected
status
The invitee has rejected the invitation (private invites only).Triggered by: POST /invite/reject
​
canceled
status
The invitation creator has canceled the invitation.Triggered by: POST /invite/cancel
​
used
status
The invitation has been successfully activated.Triggered by: POST /invite/activate (when user is authenticated)

​
Status Flow

pending → used (via activate)
pending → rejected (via reject)
pending → canceled (via cancel)
Once an invitation moves from pending to any other status, it cannot be used or changed.

​
InviteUseType

Tracks individual uses of an invitation (for invitations with maxUses > 1). 
export type InviteUseType = {
  inviteId: string;
  usedByUserId: string;
  usedAt: Date;
};

​
Fields

​
inviteId
string
required
Reference to the invitation ID that was used.
​
usedByUserId
string
required
ID of the user who used the invitation.
​
usedAt
Date
required
Timestamp when the invitation was used.

​
InviteUseTypeWithId

Invitation use record with database ID. 
export type InviteUseTypeWithId = InviteUseType & {
  id: string;
};

​
Fields

Includes all fields from InviteUseType plus:
​
id
string
required
Unique database identifier for this usage record.

​
Examples

​
Private Invite for New User

const privateInviteNew: InviteType = {
  token: "abc123xyz789012345678901",
  createdByUserId: "user_admin_123",
  createdAt: new Date("2026-03-04T10:00:00Z"),
  expiresAt: new Date("2026-03-04T11:00:00Z"),
  maxUses: 1,
  shareInviterName: true,
  email: "[email protected]",
  role: "member",
  newAccount: true,
  status: "pending",
};

​
Private Invite for Role Upgrade

const privateInviteUpgrade: InviteType = {
  token: "XYZ789ABC",
  createdByUserId: "user_admin_123",
  createdAt: new Date("2026-03-04T10:00:00Z"),
  expiresAt: new Date("2026-03-04T11:00:00Z"),
  maxUses: 1,
  redirectToAfterUpgrade: "/admin/dashboard",
  shareInviterName: true,
  email: "[email protected]",
  role: "admin",
  newAccount: false,
  status: "pending",
};

const publicInvite: InviteType = {
  token: "public-invite-code",
  createdByUserId: "user_admin_123",
  createdAt: new Date("2026-03-04T10:00:00Z"),
  expiresAt: new Date("2026-03-11T10:00:00Z"), // 7 days
  maxUses: 50,
  shareInviterName: false,
  // No email - public invite
  role: "member",
  // No newAccount - public invites don't have this
  status: "pending",
};

​
Used Invitation with ID

const usedInvite: InviteTypeWithId = {
  id: "inv_abc123",
  token: "used-token-123",
  createdByUserId: "user_admin_123",
  createdAt: new Date("2026-03-04T10:00:00Z"),
  expiresAt: new Date("2026-03-04T11:00:00Z"),
  maxUses: 1,
  shareInviterName: true,
  email: "[email protected]",
  role: "editor",
  newAccount: true,
  status: "used",
};

​
Invitation Use Record

const inviteUse: InviteUseTypeWithId = {
  id: "use_xyz789",
  inviteId: "inv_abc123",
  usedByUserId: "user_new_456",
  usedAt: new Date("2026-03-04T10:30:00Z"),
};

​
Database Schema

These types correspond to the following database tables:

​
invite Table

schema.invite = {
  fields: {
    token: { type: "string", unique: true },
    createdAt: { type: "date" },
    expiresAt: { type: "date", required: true },
    maxUses: { type: "number", required: true },
    createdByUserId: {
      type: "string",
      references: { model: "user", field: "id", onDelete: "set null" },
    },
    redirectToAfterUpgrade: { type: "string", required: false },
    shareInviterName: { type: "boolean", required: true },
    email: { type: "string", required: false },
    role: { type: "string", required: true },
    newAccount: { type: "boolean", required: false },
    status: {
      type: ["pending", "rejected", "canceled", "used"] as const,
      required: true,
    },
  },
};

​
inviteUse Table

schema.inviteUse = {
  fields: {
    inviteId: {
      type: "string",
      required: true,
      references: { model: "invite", field: "id", onDelete: "set null" },
    },
    usedAt: { type: "date", required: true },
    usedByUserId: {
      type: "string",
      required: false,
      references: { model: "user", field: "id", onDelete: "set null" },
    },
  },
};

​
Type Guards

Useful type guards for working with invitations: 
// Check if invitation is private
function isPrivateInvite(invite: InviteType): invite is InviteType & { email: string } {
  return invite.email !== undefined;
}

// Check if invitation is for new account
function isNewAccountInvite(invite: InviteType): invite is InviteType & { newAccount: true } {
  return invite.newAccount === true;
}

// Check if invitation is expired
function isExpired(invite: InviteType): boolean {
  return new Date() > invite.expiresAt;
}

// Check if invitation is pending
function isPending(invite: InviteType): boolean {
  return invite.status === "pending";
}

​
Source Code Reference

Type definitions: src/types.ts:323-364 Database schema: src/schema.ts:3-40

Build docs developers (and LLMs) love

Get started for freeTalk to us