add: app-invite

Author: ping-maxwell

apps/docs/content/docs/plugins/app-invite.mdx

@@ -0,0 +1,292 @@
+---
+title: App Invite
+description: Invite users to your application and allow them to sign up.
+---
+
+<StatsBadge npmPackage="@better-auth-kit/app-invite" />
+<GithubButton url="https://github.com/ping-maxwell/better-auth-kit/tree/main/packages/plugins/app-invite" />
+<NpmButton url="https://www.npmjs.com/package/@better-auth-kit/app-invite" />
+
+The App Invite plugin enables you to invite users to your application through email invitations. It supports two types of invitations:
+
+- **Personal Invitations**: Targeted to specific email addresses, ensuring only the intended recipient can use the invitation
+- **Public Invitations**: Can be used by multiple users, making it ideal for open sign-up scenarios
+
+## Installation
+
+<Steps>
+    <Step>
+    ### Add the plugin to your auth config
+
+    To use the App Invite plugin, add it to your auth config.
+
+    ```ts title="auth.ts"
+    import { betterAuth } from "better-auth"
+    import { appInvite } from "better-auth/plugins" // [!code highlight]
+
+    export const auth = betterAuth({
+        // ... other config options
+        plugins: [
+            appInvite({ // [!code highlight]
+                // required for personal invites // [!code highlight]
+                sendInvitationEmail: (data) => { // [!code highlight]
+                    // ... send invitation to the user // [!code highlight]
+                } // [!code highlight]
+            }) // [!code highlight]
+        ]
+    })
+    ```
+
+    </Step>
+    <Step>
+    ### Add the client plugin
+
+    Include the App Invite client plugin in your authentication client instance.
+
+    ```ts title="auth-client.ts"
+    import { createAuthClient } from "better-auth/client"
+    import { appInviteClient } from "better-auth/client/plugins" // [!code highlight]
+
+    const authClient = createAuthClient({
+        plugins: [
+            appInviteClient() // [!code highlight]
+        ]
+    })
+    ```
+
+    </Step>
+
+    <Step>
+    ### Run migrations
+
+    This plugin adds an additional table to the database. [Click here to see the schema](#schema)
+
+    ```package-install
+    npx @better-auth/cli migrate
+    ```
+
+    or generate
+
+    ```package-install
+    npx @better-auth/cli generate
+    ```
+
+    </Step>
+</Steps>
+
+## Usage
+
+To add members to the application, we first need to send an invitation to the user. 
+The user will receive an email with the invitation link. Once the user accepts the invitation, they will be signed up to the application.
+
+### Setup Invitation Email
+
+For personal invites to work we first need to provide `sendInvitationEmail` to the `better-auth` instance.
+This function is responsible for sending the invitation email to the user.
+
+You'll need to construct and send the invitation link to the user. The link should include the invitation ID,
+which will be used with the acceptInvitation function when the user clicks on it.
+
+This is only required for personal invites. Sharing public invitations is up to the inviter.
+
+```ts title="auth.ts"
+import { betterAuth } from "better-auth";
+import { appInvite } from "better-auth/plugins";
+import { sendAppInvitation } from "./email";
+
+export const auth = betterAuth({
+  plugins: [
+    appInvite({
+      async sendInvitationEmail(data) {
+        const inviteLink = `https://example.com/accept-invitation/${data.id}`;
+        sendAppInvitation({
+          name: data.name,
+          email: data.email,
+          invitedByUsername: data.inviter.name,
+          invitedByEmail: data.inviter.email,
+          inviteLink,
+        });
+      },
+    }),
+  ],
+});
+```
+
+### Send Invitation
+
+To invite users to the app, you can use the `invite` function provided by the client.
+the `invite` function takes an object with the following properties:
+
+- `email`: The email address of the user to invite. Leave empty to create a public invitation.
+
+- `resend`: A boolean value that determines whether to resend the invitation email,
+if the user is already invited. Defaults to `false`
+
+- `domainWhitelist`: An optional comma separated list of domains that allows public invitations
+to be accepted only from approved domains.
+
+```ts title="invitation.ts"
+await authClient.inviteUser({
+  email: "test@email.com",
+});
+```
+
+### Accept Invitation
+
+When a user receives an invitation email, they can click on the invitation link to accept the invitation.
+The link should include the invitation ID, which will be used to accept the invitation.
+
+```ts title="auth-client.ts"
+await authClient.acceptInvitation({
+  invitationId: "invitation-id",
+  name: "John Doe", // overridden if predefined in the invitation
+  email: "test@email.com", // must be set for public invites
+  password: "password123456",
+  // ... additional user data
+});
+```
+
+### Update Invitation Status
+
+To update the status of invitations you can use the `acceptInvitation`, `rejectInvitation`, `cancelInvitation`
+function provided by the client. The functions take the invitation id as an argument.
+
+```ts title="auth-client.ts"
+// cancel invitation (by default only the inviter can cancel invitations)
+await authClient.cancelInvitation({
+  invitationId: "invitation-id",
+});
+
+// reject invitation (this is only available for personal invites)
+await authClient.rejectInvitation({
+  invitationId: "invitation-id",
+});
+```
+
+### Get Invitation
+
+To get an invitation you can use the `getAppInvitation` function provided by the client. You need to provide the
+invitation id as a query parameter.
+
+```ts title="auth-client"
+await authClient.getAppInvitation({
+  query: {
+    id: params.id,
+  },
+});
+```
+
+### List Invitations
+
+Allows an user to list all invitations issued by themself.
+
+```ts title="auth-client"
+await authClient.listInvitations({
+  query: {
+    limit: 10,
+  },
+});
+```
+
+By default 100 invitations are returned. You can adjust the limit and offset using the following query parameters:
+
+- `searchField`: The field to search on, which can be `email`, `name` or `domainWhitelist`.
+- `searchOperator`: The operator to use for the search. It can be `contains`, `starts_with`, or `ends_with`.
+- `searchValue`: The value to search for.
+- `limit`: The number of invitations to return.
+- `offset`: The number of invitations to skip.
+- `sortBy`: The field to sort the invitations by.
+- `sortDirection`: The direction to sort the invitations by. Defaults to `asc`.
+- `filterField`: The field to filter the invitations by.
+- `filterOperator`: The operator to use for the filter. It can be `eq`, `ne`, `lt`, `lte`, `gt` or `gte`.
+- `filterValue`: The value to filter the invitations by.
+
+```ts title="Example"
+await authClient.listInvitations({
+  query: {
+    searchField: "domainWhitelist",
+    searchOperator: "contains",
+    searchValue: "example.com",
+    limit: 10,
+    offset: 0,
+    sortBy: "createdAt",
+    sortDirection: "desc",
+    filterField: "expiresAt",
+    filterOperator: "lt",
+    filterValue: new Date().toISOString(),
+  },
+});
+```
+
+## Schema
+
+
+
+The plugin requires an additional table in the database.
+
+Table Name: `appInvitation`
+
+<SchemaDemo plugin="appInvite" includeDefaultUser focus="appInvitation" schema={{
+    appInvitation: {
+      fields: {
+        name: {
+        type: "string",
+        required: false,
+      },
+      email: {
+        type: "string",
+        required: false,
+      },
+      inviterId: {
+        type: "string",
+        required: true,
+        references: {
+            model: "user",
+            field: "id",
+        }
+      },
+      status: {
+        type: "string",
+        required: true,
+      },
+      domainWhitelist: {
+        type: "string",
+        required: true
+      },
+      expiresAt: {
+        type: "date",
+        required: true
+      },
+      createdAt: {
+        type: "date",
+        required: true,
+      },
+      }
+  }
+}} />
+
+Fields:
+
+- `id`: Unique identifier for each invitation
+- `name`: The name of the user
+- `email`: The email address of the user
+- `inviterId`: The ID of the inviter
+- `status`: The status of the invitation
+- `domainWhitelist`: A comma separated whitelist of domains for a public invitation
+- `expiresAt`: Timestamp of when the invitation expires
+- `createdAt`: Timestamp of when the invitation was created
+
+
+## Options
+
+**allowUserToCreateInvitation**: `boolean` | `((user: User, type: "personal" | "public") => Promise<boolean> | boolean)` - A function that determines whether a user can create invite others. By defaults it's `true`. You can set it to `false` to restrict users from creating invitations.
+
+**allowUserToCancelInvitation**: `(data: { user: User, invitation: AppInvitation }) => Promise<boolean> | boolean` - A functon that determines whether a user can cancel inivtations. By default the user can only cancel invites created by them. You can set it to `false` to restrict users from canceling invitations.
+
+**invitationExpiresIn**: `number` - How long the invitation link is valid for in seconds. By default, it's 48 hours (2 days).
+
+**sendInvitationEmail**: `async (data) => Promise<void>` - A function that sends an invitation email to the user. This is only required for personal invitations.
+
+**autoSignIn**: A boolean value that determines whether to prevent automatic sign-up when accepting an invitation. Defaults to `false`.
+
+**$Infer.AdditionalFields**: Allows you to infer additional data for the user. This option is available in the client plugin aswell.

apps/docs/src/components/sidebar-content.tsx

@@ -21,6 +21,7 @@ import {
 	Brain,
 	Book,
 	User,
+	UserPlus,
 } from "lucide-react";
 import type { Content } from "./sidebar";
 
@@ -67,6 +68,11 @@ export const contents: Content[] = [
 				title: "Legal Consent",
 				icon: () => <Scale size={16} />,
 			},
+			{
+				href: "/docs/plugins/app-invite",
+				title: "App Invite",
+				icon: () => <UserPlus size={16} />,
+			},
 			{
 				href: "/docs/plugins/blockade",
 				title: "Blockade",