feat: add cancellable document status (#2992)

Adds a CANCELLED envelope status that privileged members (owner or team
admin/manager) can move a pending document into. Sending recipient
notifications via a background job while retaining the document in the
dashboard as proof of distribution.

Includes a dedicated Cancelled tab, single and bulk cancel actions,
the ENVELOPE_CANCELLED mutability guard, and e2e coverage for
permissions
and visibility.

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

@@ -0,0 +1,129 @@
+import { jobs } from '@documenso/lib/jobs/client';
+import { prisma } from '@documenso/prisma';
+import { DocumentStatus, EnvelopeType, WebhookTriggerEvents } from '@prisma/client';
+
+import { AppError, AppErrorCode } from '../../errors/app-error';
+import { DOCUMENT_AUDIT_LOG_TYPE } from '../../types/document-audit-logs';
+import { mapEnvelopeToWebhookDocumentPayload, ZWebhookDocumentSchema } from '../../types/webhook-payload';
+import type { ApiRequestMetadata } from '../../universal/extract-request-metadata';
+import { createDocumentAuditLogData } from '../../utils/document-audit-logs';
+import type { EnvelopeIdOptions } from '../../utils/envelope';
+import { mapSecondaryIdToDocumentId, unsafeBuildEnvelopeIdQuery } from '../../utils/envelope';
+import { isMemberManagerOrAbove } from '../../utils/teams';
+import { getMemberRoles } from '../team/get-member-roles';
+import { triggerWebhook } from '../webhooks/trigger/trigger-webhook';
+
+export type CancelDocumentOptions = {
+  id: EnvelopeIdOptions;
+  userId: number;
+  teamId: number;
+  reason?: string;
+  requestMetadata: ApiRequestMetadata;
+};
+
+export const cancelDocument = async ({ id, userId, teamId, reason, requestMetadata }: CancelDocumentOptions) => {
+  // Note: This is an unsafe request, we validate the ownership/permission later in the function.
+  const envelope = await prisma.envelope.findUnique({
+    where: unsafeBuildEnvelopeIdQuery(id, EnvelopeType.DOCUMENT),
+    include: {
+      recipients: true,
+      documentMeta: true,
+    },
+  });
+
+  if (!envelope) {
+    throw new AppError(AppErrorCode.NOT_FOUND, {
+      message: 'Document not found',
+    });
+  }
+
+  const isUserOwner = envelope.userId === userId;
+
+  const teamRole = await getMemberRoles({
+    teamId: envelope.teamId,
+    reference: {
+      type: 'User',
+      id: userId,
+    },
+  })
+    .then((roles) => roles.teamRole)
+    .catch(() => null);
+
+  const isUserTeamMember = teamRole !== null;
+
+  // Callers with no relationship to the document must not be able to determine
+  // whether it exists, so respond as if it was not found.
+  if (!isUserOwner && !isUserTeamMember) {
+    throw new AppError(AppErrorCode.NOT_FOUND, {
+      message: 'Document not found',
+    });
+  }
+
+  const isPrivilegedTeamMember = teamRole && isMemberManagerOrAbove(teamRole);
+
+  // The document is visible to the caller, but cancelling requires elevated permissions.
+  if (!isUserOwner && !isPrivilegedTeamMember) {
+    throw new AppError(AppErrorCode.UNAUTHORIZED, {
+      message: 'Not allowed',
+    });
+  }
+
+  if (envelope.status !== DocumentStatus.PENDING) {
+    throw new AppError(AppErrorCode.INVALID_REQUEST, {
+      message: 'Only pending documents can be cancelled',
+    });
+  }
+
+  const updatedEnvelope = await prisma.$transaction(async (tx) => {
+    const updated = await tx.envelope.update({
+      where: {
+        id: envelope.id,
+      },
+      data: {
+        status: DocumentStatus.CANCELLED,
+        completedAt: new Date(),
+      },
+    });
+
+    await tx.documentAuditLog.create({
+      data: createDocumentAuditLogData({
+        envelopeId: envelope.id,
+        type: DOCUMENT_AUDIT_LOG_TYPE.DOCUMENT_CANCELLED,
+        metadata: requestMetadata,
+        data: {
+          reason,
+        },
+      }),
+    });
+
+    return updated;
+  });
+
+  const legacyDocumentId = mapSecondaryIdToDocumentId(envelope.secondaryId);
+
+  // Send cancellation emails to recipients via the resilient background job.
+  await jobs.triggerJob({
+    name: 'send.document.cancelled.emails',
+    payload: {
+      documentId: legacyDocumentId,
+      cancellationReason: reason,
+      requestMetadata: requestMetadata.requestMetadata,
+    },
+  });
+
+  // Trigger the webhook with the updated (cancelled) envelope payload.
+  await triggerWebhook({
+    event: WebhookTriggerEvents.DOCUMENT_CANCELLED,
+    data: ZWebhookDocumentSchema.parse(
+      mapEnvelopeToWebhookDocumentPayload({
+        ...envelope,
+        status: updatedEnvelope.status,
+        completedAt: updatedEnvelope.completedAt,
+      }),
+    ),
+    userId,
+    teamId,
+  });
+
+  return updatedEnvelope;
+};

packages/lib/server-only/document/find-documents.ts

@@ -220,7 +220,11 @@ export const findDocuments = async ({
             eb.or([
               eb('Envelope.userId', '=', user.id),
               eb.and([
-                eb('Envelope.status', 'in', [sql.lit(DocumentStatus.COMPLETED), sql.lit(DocumentStatus.PENDING)]),
+                eb('Envelope.status', 'in', [
+                  sql.lit(DocumentStatus.COMPLETED),
+                  sql.lit(DocumentStatus.PENDING),
+                  sql.lit(DocumentStatus.CANCELLED),
+                ]),
                 recipientExists(eb, user.email),
               ]),
             ]),
@@ -291,6 +295,16 @@ export const findDocuments = async ({
             ]),
           ),
       )
+      .with(ExtendedDocumentStatus.CANCELLED, () =>
+        qb
+          .where('Envelope.status', '=', sql.lit(ExtendedDocumentStatus.CANCELLED))
+          .where((eb) =>
+            eb.and([
+              personalDeletedFilter(eb),
+              eb.or([eb('Envelope.userId', '=', user.id), recipientExists(eb, user.email)]),
+            ]),
+          ),
+      )
       .exhaustive();
   };
 
@@ -429,6 +443,18 @@ export const findDocuments = async ({
           return eb.and([teamDeletedFilter(eb), visibilityFilter(eb), eb.or(accessBranches)]);
         }),
       )
+      .with(ExtendedDocumentStatus.CANCELLED, () =>
+        qb.where('Envelope.status', '=', sql.lit(ExtendedDocumentStatus.CANCELLED)).where((eb) => {
+          const accessBranches = [eb('Envelope.teamId', '=', teamData.id)];
+
+          if (teamEmail) {
+            accessBranches.push(senderEmailIs(eb, teamEmail));
+            accessBranches.push(recipientExists(eb, teamEmail));
+          }
+
+          return eb.and([teamDeletedFilter(eb), visibilityFilter(eb), eb.or(accessBranches)]);
+        }),
+      )
       .exhaustive();
   };
 

packages/lib/server-only/document/get-stats.ts

@@ -239,6 +239,20 @@ export const getStats = async ({ userId, teamId, period, search = '', folderId,
       return eb.and([teamDeletedFilter(eb), visibilityFilter(eb), eb.or(accessBranches)]);
     });
 
+  // CANCELLED: team-owned cancelled + team-email received cancelled docs
+  const cancelledQuery = buildBaseQuery()
+    .where('Envelope.status', '=', sql.lit(DocumentStatus.CANCELLED))
+    .where((eb) => {
+      const accessBranches = [eb('Envelope.teamId', '=', team.id)];
+
+      if (teamEmail) {
+        accessBranches.push(senderEmailIs(eb, teamEmail));
+        accessBranches.push(recipientExists(eb, teamEmail));
+      }
+
+      return eb.and([teamDeletedFilter(eb), visibilityFilter(eb), eb.or(accessBranches)]);
+    });
+
   // INBOX: non-draft docs where team email is a NOT_SIGNED, non-CC recipient
   // Returns 0 if the team has no team email.
   const inboxQuery = teamEmail
@@ -260,21 +274,23 @@ export const getStats = async ({ userId, teamId, period, search = '', folderId,
 
   // ─── Execute all counts in parallel ──────────────────────────────────
 
-  const [draft, pending, completed, rejected, inbox] = await Promise.all([
+  const [draft, pending, completed, rejected, cancelled, inbox] = await Promise.all([
     cappedCount(draftQuery),
     cappedCount(pendingQuery),
     cappedCount(completedQuery),
     cappedCount(rejectedQuery),
+    cappedCount(cancelledQuery),
     inboxQuery ? cappedCount(inboxQuery) : Promise.resolve(0),
   ]);
 
-  const all = Math.min(draft + pending + completed + rejected + inbox, STATS_COUNT_CAP);
+  const all = Math.min(draft + pending + completed + rejected + cancelled + inbox, STATS_COUNT_CAP);
 
   const stats: Record<ExtendedDocumentStatus, number> = {
     [ExtendedDocumentStatus.DRAFT]: draft,
     [ExtendedDocumentStatus.PENDING]: pending,
     [ExtendedDocumentStatus.COMPLETED]: completed,
     [ExtendedDocumentStatus.REJECTED]: rejected,
+    [ExtendedDocumentStatus.CANCELLED]: cancelled,
     [ExtendedDocumentStatus.INBOX]: inbox,
     [ExtendedDocumentStatus.ALL]: all,
   };