better-auth-lead 0.4.3 → 0.6.0

package/README.md

@@ -56,6 +56,8 @@ const authClient = createAuthClient({
 
 ### Subscribe
 
+Provide an `email` to subscribe an anonymous lead:
+
 ```ts
 // POST /lead/subscribe
 const { data, error } = await authClient.lead.subscribe({
@@ -67,6 +69,19 @@ const { data, error } = await authClient.lead.subscribe({
 });
 ```
 
+Or omit `email` to subscribe the currently authenticated user. The lead is associated to the session user's `id` (a valid session cookie is required):
+
+```ts
+// POST /lead/subscribe
+const { data, error } = await authClient.lead.subscribe({
+  metadata: {
+    preferences: 'engineering',
+  },
+});
+```
+
+If neither `email` nor an active session is provided, the endpoint responds with `400 Bad Request` (`EMAIL_OR_SESSION_REQUIRED`).
+
 ### Verify
 
 ```ts
@@ -80,7 +95,7 @@ await authClient.lead.verify({
 
 ### Unsubscribe
 
-The unsubscribe endpoint is designed for [RFC 8058](https://www.rfc-editor.org/rfc/rfc8058) one-click unsubscribe. The signed `token` is embedded in the `unsubscribeUrl` provided to `sendVerificationEmail` and should be used in `List-Unsubscribe` email headers — email clients (Gmail, Apple Mail, Yahoo Mail) will POST to this URL automatically when the user clicks "Unsubscribe".
+The unsubscribe endpoint is designed for [RFC 8058](https://www.rfc-editor.org/rfc/rfc8058) one-click unsubscribe. The signed `token` is embedded in the `unsubscribeUrl` provided to `sendConfirmationEmail` and should be used in `List-Unsubscribe` email headers — email clients (Gmail, Apple Mail, Yahoo Mail) will POST to this URL automatically when the user clicks "Unsubscribe".
 
 ```ts
 // POST /lead/unsubscribe?token=<signed-token>
@@ -89,8 +104,17 @@ const { data, error } = await authClient.lead.unsubscribe({
 });
 ```
 
+For an authenticated user (e.g. from a "Manage preferences" page in your app), use the session-based endpoint. It requires a valid session and deletes the lead associated with the session user's `id`:
+
+```ts
+// POST /lead/unsubscribe-session
+const { data, error } = await authClient.lead.unsubscribeSession();
+```
+
 ### Resend
 
+Resend the confirmation email by `email`:
+
 ```ts
 // POST /lead/resend
 const { data, error } = await authClient.lead.resend({
@@ -98,25 +122,132 @@ const { data, error } = await authClient.lead.resend({
 });
 ```
 
+Or omit `email` to resend for the currently authenticated user (lead is looked up by the session user's `id`):
+
+```ts
+// POST /lead/resend
+const { data, error } = await authClient.lead.resend();
+```
+
+If neither `email` nor an active session is provided, the endpoint responds with `400 Bad Request` (`EMAIL_OR_SESSION_REQUIRED`).
+
 ### Update
 
+Update the metadata of the lead associated with the currently authenticated user. Requires a valid session — the lead is looked up by the session user's `id`:
+
 ```ts
 // POST /lead/update
 const { data, error } = await authClient.lead.update({
-  id: 'lead-id',
   metadata: {
     preferences: 'ai',
   },
 });
 ```
 
-### Email Verification
+If no session is present the endpoint responds with `401 Unauthorized`.
+
+### Admin
+
+The lead plugin ships with a set of admin-only endpoints to manage leads: `listLead`, `getLead`, and `removeLead`. They are only available when:
+
+1. The better-auth [`admin`](https://www.better-auth.com/docs/plugins/admin) plugin is registered.
+2. The `admin.enabled` lead option is set to `true`.
+
+Enable them in your auth config:
+
+```ts
+// server/auth.ts
+import { betterAuth } from 'better-auth';
+import { admin } from 'better-auth/plugins';
+import { lead } from 'better-auth-lead';
+
+export const auth = betterAuth({
+  plugins: [
+    admin(),
+    lead({
+      admin: {
+        enabled: true,
+        // Optional. Roles allowed to call the admin endpoints.
+        // Default: ['admin'].
+        // Checked against session.user.role (the admin plugin supports
+        // comma-separated roles).
+        roles: ['admin', 'editor'],
+      },
+    }),
+  ],
+});
+```
+
+#### List leads
+
+List a page of leads with optional search, filter, sort, and pagination. Requires a session with a role in `admin.roles`.
+
+```ts
+// GET /lead/list-leads
+const { data, error } = await authClient.lead.listLeads({
+  query: {
+    searchValue: 'user@example.com', // optional
+    searchField: 'email', // optional, default 'email'
+    searchOperator: 'contains', // optional: 'contains' | 'starts_with' | 'ends_with'
+    filterField: 'confirmed', // optional
+    filterValue: true, // optional
+    filterOperator: 'eq', // optional: any better-auth where operator
+    sortBy: 'createdAt', // optional
+    sortDirection: 'desc', // optional: 'asc' | 'desc'
+    limit: 100, // optional, default 100
+    offset: 0, // optional, default 0
+  },
+});
+```
+
+The response includes the page of `leads`, the `total` number of leads in the database, and the resolved `limit` and `offset` for client-side pagination.
+
+#### Get a lead
+
+Fetch a single lead by `id`. Requires a session with a role in `admin.roles`.
+
+```ts
+// POST /lead/get-lead
+const { data, error } = await authClient.lead.getLead({
+  query: {
+    id: 'lead-id',
+  },
+});
+```
+
+Returns the lead object, or `404 Not Found` (`LEAD_NOT_FOUND`) if no lead matches the id.
+
+#### Remove a lead
+
+Delete a single lead by `id`. Requires a session with a role in `admin.roles`.
+
+```ts
+// POST /lead/remove-lead
+const { data, error } = await authClient.lead.removeLead({
+  body: {
+    leadId: 'lead-id',
+  },
+});
+```
 
-To enable email verification, you need to pass a function that sends a verification email with a link. The `sendVerificationEmail` takes a data object with the following properties:
+Returns `{ success: true }` on success, or `404 Not Found` (`LEAD_NOT_FOUND`) if no lead matches the id.
+
+#### Responses
+
+All admin endpoints share the following responses:
+
+- `404 Not Found` (`ADMIN_PLUGIN_REQUIRED`) if the admin plugin is not registered or `admin.enabled` is not set.
+- `403 Forbidden` (`FORBIDDEN`) if the session user's role is not in `admin.roles`.
+- `401 Unauthorized` if no session is present.
+
+### Email Confirmation
+
+To enable double opt-in email confirmation, pass a `sendConfirmationEmail` function. It receives a data object with:
 
 - `lead`: The lead object.
-- `url`: The URL to send to the user which contains the token.
-- `token`: A verification token used to complete the email verification.
+- `email`: The lead's email address.
+- `url`: The URL containing the confirmation token to send to the user.
+- `token`: The confirmation token used to complete the verification.
 - `unsubscribeUrl`: The endpoint URL for one-click unsubscribe (RFC 8058). Use this in `List-Unsubscribe` email headers.
 
 and a `request` object as the second parameter.
@@ -130,22 +261,22 @@ import { sendEmail } from './email'; // your email sending function
 export const auth = betterAuth({
   plugins: [
     lead({
-      sendVerificationEmail: async ({ lead, url, token, unsubscribeUrl }) => {
-        const { verificationEmailSentAt } = lead;
+      sendConfirmationEmail: async ({ lead, email, url, token, unsubscribeUrl }) => {
+        const { confirmationSentAt } = lead;
         if (
-          verificationEmailSentAt &&
-          Date.now() - verificationEmailSentAt.getTime() < 60 * 1000 // 1 minute
+          confirmationSentAt &&
+          Date.now() - confirmationSentAt.getTime() < 60 * 1000 // 1 minute
         ) {
           console.log(
-            `Skipping sending verification email to ${lead.email} because a recent email was already sent.`,
+            `Skipping sending confirmation email to ${email} because a recent email was already sent.`,
           );
           return false;
         }
 
         void sendEmail({
-          to: lead.email,
-          subject: 'Newsletter: Verify your email address',
-          text: `Click the link to verify your email: ${url}`,
+          to: email,
+          subject: 'Newsletter: Confirm your subscription',
+          text: `Click the link to confirm your subscription: ${url}`,
           // One-click unsubscribe headers (RFC 8058)
           // Supported by Gmail, Apple Mail, and Yahoo Mail.
           headers: {
@@ -156,9 +287,9 @@ export const auth = betterAuth({
 
         return true;
       },
-      onEmailVerified: async ({ lead }) => {
-        // do something when a lead's email is verified
-        console.log(`Lead ${lead.email} has been verified!`);
+      onConfirmed: async ({ lead }) => {
+        // do something when a lead confirms their subscription
+        console.log(`Lead ${lead} has confirmed their subscription!`);
       },
     }),
   ],
@@ -167,7 +298,7 @@ export const auth = betterAuth({
 
 > Avoid awaiting the email sending to prevent timing attacks.
 
-Additionally, you can provide an `onEmailVerified` callback to execute logic after a lead's email is verified.
+Additionally, you can provide an `onConfirmed` callback to execute logic after a lead confirms their subscription.
 
 ### Metadata Validation
 
@@ -218,6 +349,11 @@ await authClient.lead.subscribe({
   email: 'user@example.com',
   metadata: { preferences: 'engineering' },
 });
+
+// or for the currently authenticated user (omit email)
+await authClient.lead.subscribe({
+  metadata: { preferences: 'engineering' },
+});
 ```
 
 ## Schema
@@ -226,29 +362,33 @@ await authClient.lead.subscribe({
 
 Table name: `lead`
 
-|  Field                  |  Type   |  Key   |  Description                                      |
-| ----------------------- | ------- | ------ | ------------------------------------------------- |
-| id                      | string  | pk     | Unique identifier for each lead                   |
-| email                   | string  | unique | Email address of the lead                         |
-| emailVerified           | boolean |        | Whether the email is verified                     |
-| verificationEmailSentAt | Date    | ?      | Timestamp of when the verification email was sent |
-| metadata                | json    | ?      | Additional data about the lead                    |
-| createdAt               | date    |        | Timestamp of lead creation                        |
-| updatedAt               | date    |        | Timestamp of last update                          |
+| Field              | Type    | Key    | Description                                       |
+| ------------------ | ------- | ------ | ------------------------------------------------- |
+| id                 | string  | pk     | Unique identifier for each lead                   |
+| email              | string? | unique | Email address of the lead (optional)              |
+| userId             | string? | unique | ID of an associated better-auth user (optional)   |
+| confirmed          | boolean |        | Whether the lead has confirmed their subscription |
+| confirmationSentAt | Date    | ?      | Timestamp of when the confirmation email was sent |
+| metadata           | json    | ?      | Additional data about the lead                    |
+| createdAt          | date    |        | Timestamp of lead creation                        |
+| updatedAt          | date    |        | Timestamp of last update                          |
 
 #### Prisma
 
 ```prisma
 model Lead {
-  id                      String    @id
-  createdAt               DateTime  @default(now())
-  updatedAt               DateTime  @updatedAt
-  email                   String
-  emailVerified           Boolean   @default(false)
-  verificationEmailSentAt DateTime?
-  metadata                String?
+  id                 String    @id
+  createdAt          DateTime  @default(now())
+  updatedAt          DateTime  @updatedAt
+  email              String?
+  userId             String?
+  user               User?     @relation(fields: [userId], references: [id], onDelete: Cascade)
+  confirmed          Boolean   @default(false)
+  confirmationSentAt DateTime?
+  metadata           String?
 
   @@unique([email])
+  @@unique([userId])
   @@map("lead")
 }
 ```

package/dist/client.d.mts

@@ -1,4 +1,4 @@
-import { r as LeadOptions, t as lead } from "./index-P6m89iLp.mjs";
+import { r as LeadOptions, t as lead } from "./index-BX1SlAVz.mjs";
 import { StandardSchemaV1 } from "better-auth";
 
 //#region src/client.d.ts