feat: signing reminders (#1749)

packages/lib/client-only/hooks/use-editor-fields.ts

@@ -1,7 +1,7 @@
 import { useCallback, useEffect, useMemo, useState } from 'react';
 
 import { zodResolver } from '@hookform/resolvers/zod';
-import type { Field, Recipient } from '@prisma/client';
+import type { Field } from '@prisma/client';
 import { FieldType } from '@prisma/client';
 import { useFieldArray, useForm } from 'react-hook-form';
 import { z } from 'zod';
@@ -61,7 +61,7 @@ type UseEditorFieldsResponse = {
   getFieldsByRecipient: (recipientId: number) => TLocalField[];
 
   // Selected recipient
-  selectedRecipient: Recipient | null;
+  selectedRecipient: TEditorEnvelope['recipients'][number] | null;
   setSelectedRecipient: (recipientId: number | null) => void;
 
   resetForm: (fields?: Field[]) => void;

packages/lib/client-only/hooks/use-editor-recipients.ts

@@ -1,7 +1,7 @@
 import { useId } from 'react';
 
 import { zodResolver } from '@hookform/resolvers/zod';
-import { DocumentSigningOrder, type Recipient, RecipientRole } from '@prisma/client';
+import { DocumentSigningOrder, RecipientRole } from '@prisma/client';
 import type { UseFormReturn } from 'react-hook-form';
 import { useForm } from 'react-hook-form';
 import { prop, sortBy } from 'remeda';
@@ -39,7 +39,7 @@ type EditorRecipientsProps = {
 };
 
 type ResetFormOptions = {
-  recipients?: Recipient[];
+  recipients?: TEditorEnvelope['recipients'];
   documentMeta?: TEditorEnvelope['documentMeta'];
 };
 

packages/lib/client-only/recipient-type.ts

@@ -7,6 +7,8 @@ import {
   SigningStatus,
 } from '@prisma/client';
 
+type RecipientForType = Pick<Recipient, 'role' | 'signingStatus' | 'readStatus' | 'sendStatus'>;
+
 export enum RecipientStatusType {
   COMPLETED = 'completed',
   OPENED = 'opened',
@@ -16,7 +18,7 @@ export enum RecipientStatusType {
 }
 
 export const getRecipientType = (
-  recipient: Recipient,
+  recipient: RecipientForType,
   distributionMethod: DocumentDistributionMethod = DocumentDistributionMethod.EMAIL,
 ) => {
   if (recipient.role === RecipientRole.CC || recipient.signingStatus === SigningStatus.SIGNED) {
@@ -45,7 +47,7 @@ export const getRecipientType = (
   return RecipientStatusType.UNSIGNED;
 };
 
-export const getExtraRecipientsType = (extraRecipients: Recipient[]) => {
+export const getExtraRecipientsType = (extraRecipients: RecipientForType[]) => {
   const types = extraRecipients.map((r) => getRecipientType(r));
 
   if (types.includes(RecipientStatusType.UNSIGNED)) {

packages/lib/constants/document-audit-logs.ts

@@ -19,4 +19,7 @@ export const DOCUMENT_AUDIT_LOG_EMAIL_FORMAT = {
   [DOCUMENT_EMAIL_TYPE.DOCUMENT_COMPLETED]: {
     description: 'Document completed',
   },
+  [DOCUMENT_EMAIL_TYPE.REMINDER]: {
+    description: 'Signing Reminder',
+  },
 } satisfies Record<keyof typeof DOCUMENT_EMAIL_TYPE, unknown>;

packages/lib/constants/envelope-reminder.ts

@@ -0,0 +1,86 @@
+import type { DurationLikeObject } from 'luxon';
+import { Duration } from 'luxon';
+import { z } from 'zod';
+
+export const ZEnvelopeReminderDurationPeriod = z.object({
+  unit: z.enum(['day', 'week', 'month']),
+  amount: z.number().int().min(1),
+});
+
+export const ZEnvelopeReminderDisabledPeriod = z.object({
+  disabled: z.literal(true),
+});
+
+export const ZEnvelopeReminderPeriod = z.union([
+  ZEnvelopeReminderDurationPeriod,
+  ZEnvelopeReminderDisabledPeriod,
+]);
+
+export type TEnvelopeReminderPeriod = z.infer<typeof ZEnvelopeReminderPeriod>;
+export type TEnvelopeReminderDurationPeriod = z.infer<typeof ZEnvelopeReminderDurationPeriod>;
+
+export const ZEnvelopeReminderSettings = z.object({
+  sendAfter: ZEnvelopeReminderPeriod,
+  repeatEvery: ZEnvelopeReminderPeriod,
+});
+
+export type TEnvelopeReminderSettings = z.infer<typeof ZEnvelopeReminderSettings>;
+
+export const DEFAULT_ENVELOPE_REMINDER_SETTINGS: TEnvelopeReminderSettings = {
+  sendAfter: { unit: 'day', amount: 5 },
+  repeatEvery: { unit: 'day', amount: 2 },
+};
+
+const UNIT_TO_LUXON_KEY: Record<TEnvelopeReminderDurationPeriod['unit'], keyof DurationLikeObject> =
+  {
+    day: 'days',
+    week: 'weeks',
+    month: 'months',
+  };
+
+export const getEnvelopeReminderDuration = (period: TEnvelopeReminderDurationPeriod): Duration => {
+  return Duration.fromObject({ [UNIT_TO_LUXON_KEY[period.unit]]: period.amount });
+};
+
+/**
+ * Resolve the next reminder timestamp from the config and the last reminder sent time.
+ *
+ * - `null` config means reminders are disabled (inherit = no override, resolved as disabled).
+ * - `{ sendAfter: { disabled: true }, ... }` means never send the first reminder.
+ * - `{ repeatEvery: { disabled: true }, ... }` means don't repeat after the first reminder.
+ *
+ * `sentAt` is when the signing request was sent to this specific recipient.
+ *
+ * Returns the next Date the reminder should be sent, or null if no reminder should be sent.
+ */
+export const resolveNextReminderAt = (options: {
+  config: TEnvelopeReminderSettings | null;
+  sentAt: Date;
+  lastReminderSentAt: Date | null;
+}): Date | null => {
+  const { config, sentAt, lastReminderSentAt } = options;
+
+  if (!config) {
+    return null;
+  }
+
+  // If we haven't sent the first reminder yet, use sendAfter.
+  if (!lastReminderSentAt) {
+    if ('disabled' in config.sendAfter) {
+      return null;
+    }
+
+    const delay = getEnvelopeReminderDuration(config.sendAfter);
+
+    return new Date(sentAt.getTime() + delay.toMillis());
+  }
+
+  // For subsequent reminders, use repeatEvery.
+  if ('disabled' in config.repeatEvery) {
+    return null;
+  }
+
+  const interval = getEnvelopeReminderDuration(config.repeatEvery);
+
+  return new Date(lastReminderSentAt.getTime() + interval.toMillis());
+};

packages/lib/jobs/client.ts

@@ -16,8 +16,10 @@ import { CLEANUP_RATE_LIMITS_JOB_DEFINITION } from './definitions/internal/clean
 import { EXECUTE_WEBHOOK_JOB_DEFINITION } from './definitions/internal/execute-webhook';
 import { EXPIRE_RECIPIENTS_SWEEP_JOB_DEFINITION } from './definitions/internal/expire-recipients-sweep';
 import { PROCESS_RECIPIENT_EXPIRED_JOB_DEFINITION } from './definitions/internal/process-recipient-expired';
+import { PROCESS_SIGNING_REMINDER_JOB_DEFINITION } from './definitions/internal/process-signing-reminder';
 import { SEAL_DOCUMENT_JOB_DEFINITION } from './definitions/internal/seal-document';
 import { SEAL_DOCUMENT_SWEEP_JOB_DEFINITION } from './definitions/internal/seal-document-sweep';
+import { SEND_SIGNING_REMINDERS_SWEEP_JOB_DEFINITION } from './definitions/internal/send-signing-reminders-sweep';
 import { SYNC_EMAIL_DOMAINS_JOB_DEFINITION } from './definitions/internal/sync-email-domains';
 
 /**
@@ -43,6 +45,8 @@ export const jobsClient = new JobClient([
   EXECUTE_WEBHOOK_JOB_DEFINITION,
   EXPIRE_RECIPIENTS_SWEEP_JOB_DEFINITION,
   PROCESS_RECIPIENT_EXPIRED_JOB_DEFINITION,
+  SEND_SIGNING_REMINDERS_SWEEP_JOB_DEFINITION,
+  PROCESS_SIGNING_REMINDER_JOB_DEFINITION,
   CLEANUP_RATE_LIMITS_JOB_DEFINITION,
   SYNC_EMAIL_DOMAINS_JOB_DEFINITION,
 ] as const);

packages/lib/jobs/definitions/emails/send-signing-email.handler.ts

@@ -22,6 +22,7 @@ import {
   RECIPIENT_ROLE_TO_EMAIL_TYPE,
 } from '../../../constants/recipient-roles';
 import { getEmailContext } from '../../../server-only/email/get-email-context';
+import { updateRecipientNextReminder } from '../../../server-only/recipient/update-recipient-next-reminder';
 import { DOCUMENT_AUDIT_LOG_TYPE } from '../../../types/document-audit-logs';
 import { extractDerivedDocumentEmailSettings } from '../../../types/document-email';
 import { createDocumentAuditLogData } from '../../../utils/document-audit-logs';
@@ -206,6 +207,8 @@ export const run = async ({
     });
   }
 
+  const sentAt = new Date();
+
   await io.runTask('update-recipient', async () => {
     await prisma.recipient.update({
       where: {
@@ -213,26 +216,33 @@ export const run = async ({
       },
       data: {
         sendStatus: SendStatus.SENT,
+        sentAt,
       },
     });
   });
 
-  await io.runTask('store-audit-log', async () => {
-    await prisma.documentAuditLog.create({
-      data: createDocumentAuditLogData({
-        type: DOCUMENT_AUDIT_LOG_TYPE.EMAIL_SENT,
-        envelopeId: envelope.id,
-        user,
-        requestMetadata,
-        data: {
-          emailType: recipientEmailType,
-          recipientId: recipient.id,
-          recipientName: recipient.name,
-          recipientEmail: recipient.email,
-          recipientRole: recipient.role,
-          isResending: false,
-        },
-      }),
-    });
+  // Compute the first reminder time based on the envelope's effective settings.
+  await updateRecipientNextReminder({
+    recipientId: recipient.id,
+    envelopeId: envelope.id,
+    sentAt,
+    lastReminderSentAt: null,
+  });
+
+  await prisma.documentAuditLog.create({
+    data: createDocumentAuditLogData({
+      type: DOCUMENT_AUDIT_LOG_TYPE.EMAIL_SENT,
+      envelopeId: envelope.id,
+      user,
+      requestMetadata,
+      data: {
+        emailType: recipientEmailType,
+        recipientId: recipient.id,
+        recipientName: recipient.name,
+        recipientEmail: recipient.email,
+        recipientRole: recipient.role,
+        isResending: false,
+      },
+    }),
   });
 };

packages/lib/jobs/definitions/internal/process-signing-reminder.handler.ts

@@ -0,0 +1,222 @@
+import { createElement } from 'react';
+
+import { msg } from '@lingui/core/macro';
+import {
+  DocumentDistributionMethod,
+  DocumentStatus,
+  OrganisationType,
+  RecipientRole,
+  SendStatus,
+  SigningStatus,
+  WebhookTriggerEvents,
+} from '@prisma/client';
+
+import { mailer } from '@documenso/email/mailer';
+import DocumentReminderEmailTemplate from '@documenso/email/templates/document-reminder';
+import { prisma } from '@documenso/prisma';
+
+import { getI18nInstance } from '../../../client-only/providers/i18n-server';
+import { NEXT_PUBLIC_WEBAPP_URL } from '../../../constants/app';
+import { RECIPIENT_ROLES_DESCRIPTION } from '../../../constants/recipient-roles';
+import { getEmailContext } from '../../../server-only/email/get-email-context';
+import { updateRecipientNextReminder } from '../../../server-only/recipient/update-recipient-next-reminder';
+import { triggerWebhook } from '../../../server-only/webhooks/trigger/trigger-webhook';
+import { DOCUMENT_AUDIT_LOG_TYPE, DOCUMENT_EMAIL_TYPE } from '../../../types/document-audit-logs';
+import { extractDerivedDocumentEmailSettings } from '../../../types/document-email';
+import {
+  ZWebhookDocumentSchema,
+  mapEnvelopeToWebhookDocumentPayload,
+} from '../../../types/webhook-payload';
+import { createDocumentAuditLogData } from '../../../utils/document-audit-logs';
+import { renderCustomEmailTemplate } from '../../../utils/render-custom-email-template';
+import { renderEmailWithI18N } from '../../../utils/render-email-with-i18n';
+import type { JobRunIO } from '../../client/_internal/job';
+import type { TProcessSigningReminderJobDefinition } from './process-signing-reminder';
+
+export const run = async ({
+  payload,
+  io,
+}: {
+  payload: TProcessSigningReminderJobDefinition;
+  io: JobRunIO;
+}) => {
+  const { recipientId } = payload;
+  const now = new Date();
+
+  // Atomically claim this reminder by setting lastReminderSentAt and clearing
+  // nextReminderAt so no other sweep picks it up.
+  const updatedCount = await prisma.recipient.updateMany({
+    where: {
+      id: recipientId,
+      signingStatus: SigningStatus.NOT_SIGNED,
+      sendStatus: SendStatus.SENT,
+      role: { not: RecipientRole.CC },
+      envelope: {
+        status: DocumentStatus.PENDING,
+        deletedAt: null,
+      },
+    },
+    data: {
+      lastReminderSentAt: now,
+      nextReminderAt: null,
+    },
+  });
+
+  if (updatedCount.count === 0) {
+    io.logger.info(`Recipient ${recipientId} no longer eligible for reminder, skipping`);
+    return;
+  }
+
+  const recipient = await prisma.recipient.findFirst({
+    where: { id: recipientId },
+    include: {
+      envelope: {
+        include: {
+          documentMeta: true,
+          user: true,
+          recipients: true,
+          team: {
+            select: {
+              name: true,
+            },
+          },
+        },
+      },
+    },
+  });
+
+  if (!recipient) {
+    io.logger.warn(`Recipient ${recipientId} not found`);
+    return;
+  }
+
+  const { envelope } = recipient;
+
+  if (!envelope.documentMeta) {
+    io.logger.warn(`Envelope ${envelope.id} missing documentMeta`);
+    return;
+  }
+
+  // Skip if distribution method is NONE (manual link sharing, no emails).
+  if (envelope.documentMeta.distributionMethod === DocumentDistributionMethod.NONE) {
+    io.logger.info(`Envelope ${envelope.id} uses manual distribution, skipping email reminder`);
+    return;
+  }
+
+  if (!extractDerivedDocumentEmailSettings(envelope.documentMeta).recipientSigningRequest) {
+    io.logger.info(`Envelope ${envelope.id} has email signing requests disabled, skipping`);
+    return;
+  }
+
+  const { branding, emailLanguage, organisationType, senderEmail, replyToEmail } =
+    await getEmailContext({
+      emailType: 'RECIPIENT',
+      source: {
+        type: 'team',
+        teamId: envelope.teamId,
+      },
+      meta: envelope.documentMeta,
+    });
+
+  const i18n = await getI18nInstance(emailLanguage);
+
+  const recipientActionVerb = i18n
+    ._(RECIPIENT_ROLES_DESCRIPTION[recipient.role].actionVerb)
+    .toLowerCase();
+
+  let emailSubject = i18n._(
+    msg`Reminder: Please ${recipientActionVerb} the document "${envelope.title}"`,
+  );
+
+  if (organisationType === OrganisationType.ORGANISATION) {
+    emailSubject = i18n._(
+      msg`Reminder: ${envelope.team.name} invited you to ${recipientActionVerb} a document`,
+    );
+  }
+
+  const customEmailTemplate = {
+    'signer.name': recipient.name,
+    'signer.email': recipient.email,
+    'document.name': envelope.title,
+  };
+
+  if (envelope.documentMeta.subject) {
+    emailSubject = renderCustomEmailTemplate(
+      i18n._(msg`Reminder: ${envelope.documentMeta.subject}`),
+      customEmailTemplate,
+    );
+  }
+
+  const emailMessage = envelope.documentMeta.message
+    ? renderCustomEmailTemplate(envelope.documentMeta.message, customEmailTemplate)
+    : undefined;
+
+  const assetBaseUrl = NEXT_PUBLIC_WEBAPP_URL() || 'http://localhost:3000';
+  const signDocumentLink = `${NEXT_PUBLIC_WEBAPP_URL()}/sign/${recipient.token}`;
+
+  io.logger.info(
+    `Sending signing reminder for envelope ${envelope.id} to recipient ${recipient.id} (${recipient.email})`,
+  );
+
+  const template = createElement(DocumentReminderEmailTemplate, {
+    recipientName: recipient.name,
+    documentName: envelope.title,
+    assetBaseUrl,
+    signDocumentLink,
+    customBody: emailMessage,
+    role: recipient.role,
+  });
+
+  const [html, text] = await Promise.all([
+    renderEmailWithI18N(template, { lang: emailLanguage, branding }),
+    renderEmailWithI18N(template, {
+      lang: emailLanguage,
+      branding,
+      plainText: true,
+    }),
+  ]);
+
+  await mailer.sendMail({
+    to: {
+      name: recipient.name,
+      address: recipient.email,
+    },
+    from: senderEmail,
+    replyTo: replyToEmail,
+    subject: emailSubject,
+    html,
+    text,
+  });
+
+  await prisma.documentAuditLog.create({
+    data: createDocumentAuditLogData({
+      type: DOCUMENT_AUDIT_LOG_TYPE.EMAIL_SENT,
+      envelopeId: envelope.id,
+      data: {
+        recipientEmail: recipient.email,
+        recipientName: recipient.name,
+        recipientId: recipient.id,
+        recipientRole: recipient.role,
+        emailType: DOCUMENT_EMAIL_TYPE.REMINDER,
+        isResending: false,
+      },
+    }),
+  });
+
+  await triggerWebhook({
+    event: WebhookTriggerEvents.DOCUMENT_REMINDER_SENT,
+    data: ZWebhookDocumentSchema.parse(mapEnvelopeToWebhookDocumentPayload(envelope)),
+    userId: envelope.userId,
+    teamId: envelope.teamId,
+  });
+
+  // Compute the next reminder time (repeat interval).
+  if (recipient.sentAt) {
+    await updateRecipientNextReminder({
+      recipientId: recipient.id,
+      envelopeId: envelope.id,
+      sentAt: recipient.sentAt,
+      lastReminderSentAt: now,
+    });
+  }
+};

packages/lib/jobs/definitions/internal/process-signing-reminder.ts

@@ -0,0 +1,31 @@
+import { z } from 'zod';
+
+import { type JobDefinition } from '../../client/_internal/job';
+
+const PROCESS_SIGNING_REMINDER_JOB_DEFINITION_ID = 'internal.process-signing-reminder';
+
+const PROCESS_SIGNING_REMINDER_JOB_DEFINITION_SCHEMA = z.object({
+  recipientId: z.number(),
+});
+
+export type TProcessSigningReminderJobDefinition = z.infer<
+  typeof PROCESS_SIGNING_REMINDER_JOB_DEFINITION_SCHEMA
+>;
+
+export const PROCESS_SIGNING_REMINDER_JOB_DEFINITION = {
+  id: PROCESS_SIGNING_REMINDER_JOB_DEFINITION_ID,
+  name: 'Process Signing Reminder',
+  version: '1.0.0',
+  trigger: {
+    name: PROCESS_SIGNING_REMINDER_JOB_DEFINITION_ID,
+    schema: PROCESS_SIGNING_REMINDER_JOB_DEFINITION_SCHEMA,
+  },
+  handler: async ({ payload, io }) => {
+    const handler = await import('./process-signing-reminder.handler');
+
+    await handler.run({ payload, io });
+  },
+} as const satisfies JobDefinition<
+  typeof PROCESS_SIGNING_REMINDER_JOB_DEFINITION_ID,
+  TProcessSigningReminderJobDefinition
+>;

packages/lib/jobs/definitions/internal/send-signing-reminders-sweep.handler.ts

@@ -0,0 +1,49 @@
+import { DocumentStatus, RecipientRole, SendStatus, SigningStatus } from '@prisma/client';
+
+import { prisma } from '@documenso/prisma';
+
+import { jobs } from '../../client';
+import type { JobRunIO } from '../../client/_internal/job';
+import type { TSendSigningRemindersSweepJobDefinition } from './send-signing-reminders-sweep';
+
+export const run = async ({
+  io,
+}: {
+  payload: TSendSigningRemindersSweepJobDefinition;
+  io: JobRunIO;
+}) => {
+  const now = new Date();
+
+  const recipients = await prisma.recipient.findMany({
+    where: {
+      nextReminderAt: { lte: now },
+      signingStatus: SigningStatus.NOT_SIGNED,
+      sendStatus: SendStatus.SENT,
+      role: { not: RecipientRole.CC },
+      envelope: {
+        status: DocumentStatus.PENDING,
+        deletedAt: null,
+      },
+    },
+    select: { id: true },
+    take: 1000,
+  });
+
+  if (recipients.length === 0) {
+    io.logger.info('No recipients need signing reminders');
+    return;
+  }
+
+  io.logger.info(`Found ${recipients.length} recipients needing signing reminders`);
+
+  await Promise.allSettled(
+    recipients.map(async (recipient) => {
+      await jobs.triggerJob({
+        name: 'internal.process-signing-reminder',
+        payload: {
+          recipientId: recipient.id,
+        },
+      });
+    }),
+  );
+};

packages/lib/jobs/definitions/internal/send-signing-reminders-sweep.ts

@@ -0,0 +1,30 @@
+import { z } from 'zod';
+
+import { type JobDefinition } from '../../client/_internal/job';
+
+const SEND_SIGNING_REMINDERS_SWEEP_JOB_DEFINITION_ID = 'internal.send-signing-reminders-sweep';
+
+const SEND_SIGNING_REMINDERS_SWEEP_JOB_DEFINITION_SCHEMA = z.object({});
+
+export type TSendSigningRemindersSweepJobDefinition = z.infer<
+  typeof SEND_SIGNING_REMINDERS_SWEEP_JOB_DEFINITION_SCHEMA
+>;
+
+export const SEND_SIGNING_REMINDERS_SWEEP_JOB_DEFINITION = {
+  id: SEND_SIGNING_REMINDERS_SWEEP_JOB_DEFINITION_ID,
+  name: 'Send Signing Reminders Sweep',
+  version: '1.0.0',
+  trigger: {
+    name: SEND_SIGNING_REMINDERS_SWEEP_JOB_DEFINITION_ID,
+    schema: SEND_SIGNING_REMINDERS_SWEEP_JOB_DEFINITION_SCHEMA,
+    cron: '*/15 * * * *', // Every 15 minutes.
+  },
+  handler: async ({ payload, io }) => {
+    const handler = await import('./send-signing-reminders-sweep.handler');
+
+    await handler.run({ payload, io });
+  },
+} as const satisfies JobDefinition<
+  typeof SEND_SIGNING_REMINDERS_SWEEP_JOB_DEFINITION_ID,
+  TSendSigningRemindersSweepJobDefinition
+>;

packages/lib/server-only/document/complete-document-with-token.ts

@@ -442,6 +442,7 @@ export const completeDocumentWithToken = async ({
           where: { id: nextRecipient.id },
           data: {
             sendStatus: SendStatus.SENT,
+            sentAt: new Date(),
             ...(nextSigner && envelope.documentMeta?.allowDictateNextSigner
               ? {
                   name: nextSigner.name,

packages/lib/server-only/document/viewed-document.ts

@@ -69,6 +69,8 @@ export const viewedDocument = async ({
         // This handles cases where distribution is done manually
         sendStatus: SendStatus.SENT,
         readStatus: ReadStatus.OPENED,
+        // Only set sentAt if not already set (email may have been sent before they opened).
+        ...(!recipient.sentAt ? { sentAt: new Date() } : {}),
       },
     });
 
@@ -92,6 +94,9 @@ export const viewedDocument = async ({
     });
   });
 
+  // Don't schedule reminders for manually distributed documents —
+  // there's no email pathway to send them through.
+
   const envelope = await prisma.envelope.findUniqueOrThrow({
     where: {
       id: recipient.envelopeId,

packages/lib/server-only/envelope/update-envelope.ts

@@ -18,6 +18,7 @@ import {
 import { createDocumentAuthOptions, extractDocumentAuthMethods } from '../../utils/document-auth';
 import type { EnvelopeIdOptions } from '../../utils/envelope';
 import { buildTeamWhereQuery, canAccessTeamDocument } from '../../utils/teams';
+import { recomputeNextReminderForEnvelope } from '../recipient/update-recipient-next-reminder';
 import { triggerWebhook } from '../webhooks/trigger/trigger-webhook';
 import { getEnvelopeWhereInput } from './get-envelope-by-id';
 
@@ -354,6 +355,11 @@ export const updateEnvelope = async ({
     return result;
   });
 
+  // Recompute reminders for active recipients when reminder settings change.
+  if (meta && 'reminderSettings' in meta) {
+    await recomputeNextReminderForEnvelope(envelope.id);
+  }
+
   if (envelope.type === EnvelopeType.TEMPLATE) {
     await triggerWebhook({
       event: WebhookTriggerEvents.TEMPLATE_UPDATED,

packages/lib/server-only/recipient/update-recipient-next-reminder.ts

@@ -0,0 +1,112 @@
+import {
+  DocumentDistributionMethod,
+  RecipientRole,
+  SendStatus,
+  SigningStatus,
+} from '@prisma/client';
+
+import { prisma } from '@documenso/prisma';
+
+import {
+  ZEnvelopeReminderSettings,
+  resolveNextReminderAt,
+} from '../../constants/envelope-reminder';
+
+/**
+ * Compute and store `nextReminderAt` for a single recipient.
+ *
+ * Call this after:
+ * - Sending the signing email (sentAt is set)
+ * - Sending a reminder (lastReminderSentAt is updated)
+ *
+ * If `reminderSettings` is provided it's used directly, avoiding a query.
+ * Otherwise it's read from the envelope's documentMeta (already resolved
+ * from the org/team cascade at envelope creation time).
+ */
+export const updateRecipientNextReminder = async (options: {
+  recipientId: number;
+  envelopeId: string;
+  sentAt: Date;
+  lastReminderSentAt: Date | null;
+  reminderSettings?: ReturnType<typeof ZEnvelopeReminderSettings.parse> | null;
+}) => {
+  const { recipientId, envelopeId, sentAt, lastReminderSentAt } = options;
+
+  let settings = options.reminderSettings;
+
+  if (settings === undefined) {
+    const envelope = await prisma.envelope.findFirst({
+      where: { id: envelopeId },
+      select: { documentMeta: { select: { reminderSettings: true } } },
+    });
+
+    settings = envelope?.documentMeta?.reminderSettings
+      ? ZEnvelopeReminderSettings.parse(envelope.documentMeta.reminderSettings)
+      : null;
+  }
+
+  const nextReminderAt = resolveNextReminderAt({
+    config: settings,
+    sentAt,
+    lastReminderSentAt,
+  });
+
+  await prisma.recipient.update({
+    where: { id: recipientId },
+    data: { nextReminderAt },
+  });
+};
+
+/**
+ * Recompute `nextReminderAt` for all active (unsigned, sent) recipients
+ * of a given envelope. Call when document-level reminder settings change.
+ */
+export const recomputeNextReminderForEnvelope = async (envelopeId: string) => {
+  const envelope = await prisma.envelope.findFirst({
+    where: { id: envelopeId },
+    select: {
+      documentMeta: {
+        select: { reminderSettings: true, distributionMethod: true },
+      },
+    },
+  });
+
+  // No reminders for manually distributed documents.
+  const isEmailDistribution =
+    envelope?.documentMeta?.distributionMethod !== DocumentDistributionMethod.NONE;
+
+  const settings =
+    isEmailDistribution && envelope?.documentMeta?.reminderSettings
+      ? ZEnvelopeReminderSettings.parse(envelope.documentMeta.reminderSettings)
+      : null;
+
+  const recipients = await prisma.recipient.findMany({
+    where: {
+      envelopeId,
+      signingStatus: SigningStatus.NOT_SIGNED,
+      sendStatus: SendStatus.SENT,
+      sentAt: { not: null },
+      role: { not: RecipientRole.CC },
+    },
+    select: { id: true, sentAt: true, lastReminderSentAt: true },
+  });
+
+  await Promise.all(
+    recipients.map(async (recipient) => {
+      if (!recipient.sentAt) {
+        return;
+      }
+
+      const nextReminderAt = resolveNextReminderAt({
+        config: settings,
+        sentAt: recipient.sentAt,
+        lastReminderSentAt: recipient.lastReminderSentAt,
+      });
+
+      await prisma.recipient.update({
+        where: { id: recipient.id },
+        data: { nextReminderAt },
+      });
+    }),
+  );
+};

packages/lib/server-only/template/create-document-from-direct-template.ts

@@ -705,6 +705,7 @@ export const createDocumentFromDirectTemplate = async ({
           where: { id: nextRecipient.id },
           data: {
             sendStatus: SendStatus.SENT,
+            sentAt: new Date(),
             ...(nextSigner && documentMeta?.allowDictateNextSigner
               ? {
                   name: nextSigner.name,

packages/lib/types/document-audit-logs.ts

@@ -63,6 +63,7 @@ export const ZDocumentAuditLogEmailTypeSchema = z.enum([
   'ASSISTING_REQUEST',
   'CC',
   'DOCUMENT_COMPLETED',
+  'REMINDER',
 ]);
 
 export const ZDocumentMetaDiffTypeSchema = z.enum([

packages/lib/types/document-meta.ts

@@ -4,6 +4,7 @@ import { z } from 'zod';
 
 import { VALID_DATE_FORMAT_VALUES } from '@documenso/lib/constants/date-formats';
 import { ZEnvelopeExpirationPeriod } from '@documenso/lib/constants/envelope-expiration';
+import { ZEnvelopeReminderSettings } from '@documenso/lib/constants/envelope-reminder';
 import { SUPPORTED_LANGUAGE_CODES } from '@documenso/lib/constants/i18n';
 import { isValidRedirectUrl } from '@documenso/lib/utils/is-valid-redirect-url';
 import { zEmail } from '@documenso/lib/utils/zod';
@@ -131,6 +132,7 @@ export const ZDocumentMetaCreateSchema = z.object({
   emailReplyTo: zEmail().nullish(),
   emailSettings: ZDocumentEmailSettingsSchema.nullish(),
   envelopeExpirationPeriod: ZEnvelopeExpirationPeriod.nullish(),
+  reminderSettings: ZEnvelopeReminderSettings.nullish(),
 });
 
 export type TDocumentMetaCreate = z.infer<typeof ZDocumentMetaCreateSchema>;

packages/lib/types/document.ts

@@ -72,6 +72,7 @@ export const ZDocumentSchema = LegacyDocumentSchema.pick({
     emailId: true,
     emailReplyTo: true,
     envelopeExpirationPeriod: true,
+    reminderSettings: true,
   }).extend({
     password: z.string().nullable().default(null),
     documentId: z.number().default(-1).optional(),

packages/lib/types/envelope-editor.ts

@@ -43,6 +43,7 @@ export const ZEnvelopeEditorSettingsSchema = z.object({
       allowConfigureRedirectUrl: z.boolean(),
       allowConfigureDistribution: z.boolean(),
       allowConfigureExpirationPeriod: z.boolean(),
+      allowConfigureReminders: z.boolean(),
       allowConfigureEmailSender: z.boolean(),
       allowConfigureEmailReplyTo: z.boolean(),
     })
@@ -122,6 +123,7 @@ export const DEFAULT_EDITOR_CONFIG: EnvelopeEditorConfig = {
     allowConfigureRedirectUrl: true,
     allowConfigureDistribution: true,
     allowConfigureExpirationPeriod: true,
+    allowConfigureReminders: true,
     allowConfigureEmailSender: true,
     allowConfigureEmailReplyTo: true,
   },
@@ -180,6 +182,7 @@ export const DEFAULT_EMBEDDED_EDITOR_CONFIG = {
     allowConfigureRedirectUrl: true,
     allowConfigureDistribution: true,
     allowConfigureExpirationPeriod: true,
+    allowConfigureReminders: true,
     allowConfigureEmailSender: true,
     allowConfigureEmailReplyTo: true,
   },
@@ -271,6 +274,7 @@ export const ZEditorEnvelopeSchema = EnvelopeSchema.pick({
     emailId: true,
     emailReplyTo: true,
     envelopeExpirationPeriod: true,
+    reminderSettings: true,
   }),
   recipients: ZEnvelopeRecipientLiteSchema.array(),
   fields: ZEnvelopeFieldSchema.array(),

packages/lib/types/recipient.ts

@@ -118,6 +118,13 @@ export const ZEnvelopeRecipientManySchema = ZRecipientManySchema.omit({
   templateId: true,
 });
 
+export type TRecipientSchema = z.infer<typeof ZRecipientSchema>;
+export type TRecipientLite = z.infer<typeof ZRecipientLiteSchema>;
+export type TRecipientMany = z.infer<typeof ZRecipientManySchema>;
+export type TEnvelopeRecipientSchema = z.infer<typeof ZEnvelopeRecipientSchema>;
+export type TEnvelopeRecipientLite = z.infer<typeof ZEnvelopeRecipientLiteSchema>;
+export type TEnvelopeRecipientMany = z.infer<typeof ZEnvelopeRecipientManySchema>;
+
 export const ZRecipientEmailSchema = z.union([
   z.literal(''),
   zEmail('Invalid email').trim().toLowerCase().max(254),

packages/lib/utils/document.ts

@@ -66,6 +66,9 @@ export const extractDerivedDocumentMeta = (
     // Envelope expiration.
     envelopeExpirationPeriod:
       meta.envelopeExpirationPeriod ?? settings.envelopeExpirationPeriod ?? null,
+
+    // Reminder settings.
+    reminderSettings: meta.reminderSettings ?? settings.reminderSettings ?? null,
   } satisfies Omit<DocumentMeta, 'id'>;
 };
 

packages/lib/utils/embed-config.ts

@@ -67,6 +67,9 @@ export const buildEmbeddedFeatures = (
             allowConfigureExpirationPeriod:
               features.settings?.allowConfigureExpirationPeriod ??
               DEFAULT_EMBEDDED_EDITOR_CONFIG.settings.allowConfigureExpirationPeriod,
+            allowConfigureReminders:
+              features.settings?.allowConfigureReminders ??
+              DEFAULT_EMBEDDED_EDITOR_CONFIG.settings.allowConfigureReminders,
             allowConfigureEmailSender:
               features.settings?.allowConfigureEmailSender ??
               DEFAULT_EMBEDDED_EDITOR_CONFIG.settings.allowConfigureEmailSender,

packages/lib/utils/envelope.ts

@@ -252,7 +252,7 @@ export type EnvelopeItemPermissions = {
 
 export const getEnvelopeItemPermissions = (
   envelope: Pick<Envelope, 'completedAt' | 'deletedAt' | 'type' | 'status'>,
-  recipients: Recipient[],
+  recipients: Pick<Recipient, 'role' | 'signingStatus' | 'sendStatus'>[],
 ): EnvelopeItemPermissions => {
   // Always reject completed/rejected/deleted envelopes.
   if (

packages/lib/utils/organisations.ts

@@ -9,6 +9,7 @@ import type { ORGANISATION_MEMBER_ROLE_MAP } from '@documenso/lib/constants/orga
 
 import { DEFAULT_DOCUMENT_DATE_FORMAT } from '../constants/date-formats';
 import { DEFAULT_ENVELOPE_EXPIRATION_PERIOD } from '../constants/envelope-expiration';
+import { DEFAULT_ENVELOPE_REMINDER_SETTINGS } from '../constants/envelope-reminder';
 import {
   LOWEST_ORGANISATION_ROLE,
   ORGANISATION_MEMBER_ROLE_HIERARCHY,
@@ -142,6 +143,8 @@ export const generateDefaultOrganisationSettings = (): Omit<
 
     envelopeExpirationPeriod: DEFAULT_ENVELOPE_EXPIRATION_PERIOD,
 
+    reminderSettings: DEFAULT_ENVELOPE_REMINDER_SETTINGS,
+
     aiFeaturesEnabled: false,
   };
 };

packages/lib/utils/recipients.ts

@@ -1,10 +1,11 @@
 import type { Envelope } from '@prisma/client';
-import { type Field, type Recipient, RecipientRole, SigningStatus } from '@prisma/client';
+import { type Field, RecipientRole, SigningStatus } from '@prisma/client';
 
 import { isSignatureFieldType } from '@documenso/prisma/guards/is-signature-field';
 
 import { NEXT_PUBLIC_WEBAPP_URL } from '../constants/app';
 import { AppError, AppErrorCode } from '../errors/app-error';
+import type { TRecipientLite } from '../types/recipient';
 import { extractLegacyIds } from '../universal/id';
 import { zEmail } from './zod';
 
@@ -20,7 +21,7 @@ export const RECIPIENT_ROLES_THAT_REQUIRE_FIELDS = [RecipientRole.SIGNER] as con
  *
  * Currently only SIGNERs are validated - they must have at least one signature field.
  */
-export const getRecipientsWithMissingFields = <T extends Pick<Recipient, 'id' | 'role'>>(
+export const getRecipientsWithMissingFields = <T extends Pick<TRecipientLite, 'id' | 'role'>>(
   recipients: T[],
   fields: Pick<Field, 'type' | 'recipientId'>[],
 ): T[] => {
@@ -42,7 +43,10 @@ export const formatSigningLink = (token: string) => `${NEXT_PUBLIC_WEBAPP_URL()}
 /**
  * Whether a recipient can be modified by the document owner.
  */
-export const canRecipientBeModified = (recipient: Recipient, fields: Field[]) => {
+export const canRecipientBeModified = (
+  recipient: TRecipientLite,
+  fields: Pick<Field, 'recipientId' | 'inserted'>[],
+) => {
   if (!recipient) {
     return false;
   }
@@ -72,7 +76,10 @@ export const canRecipientBeModified = (recipient: Recipient, fields: Field[]) =>
  * - They are not a Viewer or CCer
  * - They can be modified (canRecipientBeModified)
  */
-export const canRecipientFieldsBeModified = (recipient: Recipient, fields: Field[]) => {
+export const canRecipientFieldsBeModified = (
+  recipient: TRecipientLite,
+  fields: Pick<Field, 'recipientId' | 'inserted'>[],
+) => {
   if (!canRecipientBeModified(recipient, fields)) {
     return false;
   }
@@ -81,7 +88,7 @@ export const canRecipientFieldsBeModified = (recipient: Recipient, fields: Field
 };
 
 export const mapRecipientToLegacyRecipient = (
-  recipient: Recipient,
+  recipient: TRecipientLite,
   envelope: Pick<Envelope, 'type' | 'secondaryId'>,
 ) => {
   const legacyId = extractLegacyIds(envelope);
@@ -92,6 +99,7 @@ export const mapRecipientToLegacyRecipient = (
   };
 };
 
+
 export const findRecipientByEmail = <T extends { email: string }>({
   recipients,
   userEmail,
@@ -102,7 +110,7 @@ export const findRecipientByEmail = <T extends { email: string }>({
   teamEmail?: string | null;
 }) => recipients.find((r) => r.email === userEmail || (teamEmail && r.email === teamEmail));
 
-export const isRecipientEmailValidForSending = (recipient: Pick<Recipient, 'email'>) => {
+export const isRecipientEmailValidForSending = (recipient: Pick<TRecipientLite, 'email'>) => {
   return zEmail().safeParse(recipient.email).success;
 };
 

packages/lib/utils/teams.ts

@@ -208,6 +208,8 @@ export const generateDefaultTeamSettings = (): Omit<TeamGlobalSettings, 'id' | '
 
     envelopeExpirationPeriod: null,
 
+    reminderSettings: null,
+
     aiFeaturesEnabled: null,
   };
 };