feat: add customizable contact double opt-in flow (#350)

* feat: add customizable contact double opt-in flow

* test: add double opt-in service coverage

* fix: address review comments for double opt-in PR

- Make pending status conditional on doubleOptInEnabled flag
- Backfill legacy unsubscribeReason for reliable pending detection
- Add doubleOptInContent to contact book listing select
- Fix duplicate toast on DOI editor subject save failure
- Harden searchParams parsing against string[] values
- Make default DOI template use link mark for clickable URL
- Make public API create+update atomic via transaction
- Prevent contact upsert failure when DOI email send fails
- Fix empty string template variable replacement

Co-authored-by: opencode <opencode@anthropic.com>

* fix: harden double opt-in confirmation safeguards

Preserve explicit unsubscribe intent in DOI flows and prevent confirmation links from re-subscribing opted-out contacts. Also sanitize subscribe-page error messaging and use timing-safe hash comparison for link verification.

* ui stuff

* fix: require doubleOptInUrl in double opt-in templates

* feat: add configurable from address for double opt-in emails

* feat: add resend confirmation flow for pending contacts

* fix: move subscribe confirmation to explicit POST flow

* test: add contact book public API endpoint coverage

* docs: add double opt-in documentation and update OpenAPI spec

Add a user guide for the double opt-in feature covering setup, contact
statuses, email customization, template variables, and best practices.
Update the OpenAPI spec to include doubleOptIn fields in all contactBook
request/response schemas.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

---------

Co-authored-by: opencode <opencode@anthropic.com>
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

apps/web/src/server/api/routers/contacts.ts

@@ -49,6 +49,10 @@ export const contactsRouter = createTRPCRouter({
         name: z.string().optional(),
         properties: z.record(z.string()).optional(),
         emoji: z.string().optional(),
+        doubleOptInEnabled: z.boolean().optional(),
+        doubleOptInFrom: z.string().nullable().optional(),
+        doubleOptInSubject: z.string().optional(),
+        doubleOptInContent: z.string().optional(),
       }),
     )
     .mutation(async ({ ctx: { contactBook }, input }) => {
@@ -190,6 +194,45 @@ export const contactsRouter = createTRPCRouter({
       return deletedContact;
     }),
 
+  resendDoubleOptInConfirmation: contactBookProcedure
+    .input(z.object({ contactId: z.string() }))
+    .mutation(async ({ ctx: { contactBook, team }, input }) => {
+      try {
+        const contact =
+          await contactService.resendDoubleOptInConfirmationInContactBook(
+            input.contactId,
+            contactBook.id,
+            team.id,
+          );
+
+        if (!contact) {
+          throw new TRPCError({
+            code: "NOT_FOUND",
+            message: "Contact not found",
+          });
+        }
+
+        return { success: true };
+      } catch (error) {
+        if (error instanceof TRPCError) {
+          throw error;
+        }
+
+        if (
+          error instanceof Error &&
+          error.message ===
+            "Double opt-in confirmation can only be resent to pending contacts"
+        ) {
+          throw new TRPCError({
+            code: "BAD_REQUEST",
+            message: error.message,
+          });
+        }
+
+        throw error;
+      }
+    }),
+
   exportContacts: contactBookProcedure
     .input(
       z.object({