feat: add audit logs to document details page (#2379)

- Add collapsible audit logs section with paginated table
- Add View JSON button to inspect raw audit log entries
- Display legacy document ID and recipient roles
- Add admin TRPC endpoint for fetching audit logs
- Add database index on envelopeId for DocumentAuditLog table

<img width="887" height="724" alt="image"
src="https://github.com/user-attachments/assets/aeb904c9-515f-49e1-9f8f-513aef455678"
/>

AGENTS.md

@@ -11,6 +11,8 @@
 - `npm run format` - Format code with Prettier
 - `npm run dev` - Start development server for Remix app
 
+**Important:** Do not run `npm run build` to verify changes unless explicitly asked. Builds take a long time (~2 minutes). Use `npx tsc --noEmit` for type checking specific packages if needed.
+
 ## Code Style Guidelines
 
 - Use TypeScript for all code; prefer `type` over `interface`

apps/remix/app/components/tables/admin-document-logs-table.tsx

@@ -0,0 +1,210 @@
+import { useMemo, useState } from 'react';
+
+import { msg } from '@lingui/core/macro';
+import { useLingui } from '@lingui/react';
+import { Trans } from '@lingui/react/macro';
+import { DateTime } from 'luxon';
+import type { DateTimeFormatOptions } from 'luxon';
+import { useSearchParams } from 'react-router';
+import { UAParser } from 'ua-parser-js';
+
+import { useUpdateSearchParams } from '@documenso/lib/client-only/hooks/use-update-search-params';
+import type { TDocumentAuditLog } from '@documenso/lib/types/document-audit-logs';
+import { ZUrlSearchParamsSchema } from '@documenso/lib/types/search-params';
+import { formatDocumentAuditLogAction } from '@documenso/lib/utils/document-audit-logs';
+import { trpc } from '@documenso/trpc/react';
+import { CopyTextButton } from '@documenso/ui/components/common/copy-text-button';
+import { Button } from '@documenso/ui/primitives/button';
+import type { DataTableColumnDef } from '@documenso/ui/primitives/data-table';
+import { DataTable } from '@documenso/ui/primitives/data-table';
+import { DataTablePagination } from '@documenso/ui/primitives/data-table-pagination';
+import { Dialog, DialogContent, DialogHeader, DialogTitle } from '@documenso/ui/primitives/dialog';
+import { Skeleton } from '@documenso/ui/primitives/skeleton';
+import { TableCell } from '@documenso/ui/primitives/table';
+import { useToast } from '@documenso/ui/primitives/use-toast';
+
+export type AdminDocumentLogsTableProps = {
+  envelopeId: string;
+};
+
+const dateFormat: DateTimeFormatOptions = {
+  ...DateTime.DATETIME_SHORT,
+  hourCycle: 'h12',
+};
+
+export const AdminDocumentLogsTable = ({ envelopeId }: AdminDocumentLogsTableProps) => {
+  const { _, i18n } = useLingui();
+  const { toast } = useToast();
+
+  const [searchParams] = useSearchParams();
+  const updateSearchParams = useUpdateSearchParams();
+
+  const [selectedAuditLog, setSelectedAuditLog] = useState<TDocumentAuditLog | null>(null);
+
+  const parsedSearchParams = ZUrlSearchParamsSchema.parse(Object.fromEntries(searchParams ?? []));
+
+  const { data, isLoading, isLoadingError } = trpc.admin.document.findAuditLogs.useQuery(
+    {
+      envelopeId,
+      page: parsedSearchParams.page,
+      perPage: parsedSearchParams.perPage,
+    },
+    {
+      placeholderData: (previousData) => previousData,
+    },
+  );
+
+  const onPaginationChange = (page: number, perPage: number) => {
+    updateSearchParams({
+      page,
+      perPage,
+    });
+  };
+
+  const results = data ?? {
+    data: [],
+    perPage: 10,
+    currentPage: 1,
+    totalPages: 1,
+  };
+
+  const columns = useMemo(() => {
+    const parser = new UAParser();
+
+    return [
+      {
+        header: _(msg`Time`),
+        accessorKey: 'createdAt',
+        cell: ({ row }) => i18n.date(row.original.createdAt, dateFormat),
+      },
+      {
+        header: _(msg`User`),
+        accessorKey: 'name',
+        cell: ({ row }) =>
+          row.original.name || row.original.email ? (
+            <div>
+              {row.original.name && (
+                <p className="truncate" title={row.original.name}>
+                  {row.original.name}
+                </p>
+              )}
+
+              {row.original.email && (
+                <p className="truncate" title={row.original.email}>
+                  {row.original.email}
+                </p>
+              )}
+            </div>
+          ) : (
+            <p>N/A</p>
+          ),
+      },
+      {
+        header: _(msg`Action`),
+        accessorKey: 'type',
+        cell: ({ row }) => (
+          <span>{formatDocumentAuditLogAction(i18n, row.original).description}</span>
+        ),
+      },
+      {
+        header: _(msg`IP Address`),
+        accessorKey: 'ipAddress',
+      },
+      {
+        header: _(msg`Browser`),
+        cell: ({ row }) => {
+          if (!row.original.userAgent) {
+            return 'N/A';
+          }
+
+          parser.setUA(row.original.userAgent);
+
+          const result = parser.getResult();
+
+          return result.browser.name ?? 'N/A';
+        },
+      },
+      {
+        header: '',
+        id: 'actions',
+        cell: ({ row }) => (
+          <Button variant="link" size="sm" onClick={() => setSelectedAuditLog(row.original)}>
+            <Trans>View JSON</Trans>
+          </Button>
+        ),
+      },
+    ] satisfies DataTableColumnDef<(typeof results)['data'][number]>[];
+  }, []);
+
+  return (
+    <>
+      <DataTable
+        columns={columns}
+        data={results.data}
+        perPage={results.perPage}
+        currentPage={results.currentPage}
+        totalPages={results.totalPages}
+        onPaginationChange={onPaginationChange}
+        error={{
+          enable: isLoadingError,
+        }}
+        skeleton={{
+          enable: isLoading,
+          rows: 3,
+          component: (
+            <>
+              <TableCell>
+                <Skeleton className="h-4 w-12 rounded-full" />
+              </TableCell>
+              <TableCell className="w-1/2 py-4 pr-4">
+                <div className="ml-2 flex flex-grow flex-col">
+                  <Skeleton className="h-4 w-1/3 max-w-[8rem]" />
+                  <Skeleton className="mt-1 h-4 w-1/2 max-w-[12rem]" />
+                </div>
+              </TableCell>
+              <TableCell>
+                <Skeleton className="h-4 w-12 rounded-full" />
+              </TableCell>
+              <TableCell>
+                <Skeleton className="h-4 w-10 rounded-full" />
+              </TableCell>
+              <TableCell>
+                <Skeleton className="h-4 w-10 rounded-full" />
+              </TableCell>
+              <TableCell>
+                <Skeleton className="h-4 w-8 rounded-full" />
+              </TableCell>
+            </>
+          ),
+        }}
+      >
+        {(table) => <DataTablePagination additionalInformation="VisibleCount" table={table} />}
+      </DataTable>
+
+      <Dialog open={selectedAuditLog !== null} onOpenChange={() => setSelectedAuditLog(null)}>
+        <DialogContent className="max-w-2xl">
+          <DialogHeader>
+            <DialogTitle>
+              <Trans>Audit Log Details</Trans>
+            </DialogTitle>
+          </DialogHeader>
+
+          {selectedAuditLog && (
+            <div className="group relative">
+              <div className="absolute right-2 top-2 opacity-0 transition-opacity group-hover:opacity-100">
+                <CopyTextButton
+                  value={JSON.stringify(selectedAuditLog, null, 2)}
+                  onCopySuccess={() => toast({ title: _(msg`Copied to clipboard`) })}
+                />
+              </div>
+
+              <pre className="max-h-[60vh] overflow-auto whitespace-pre-wrap break-all rounded-lg border border-border bg-muted/50 p-4 font-mono text-xs leading-relaxed text-foreground">
+                {JSON.stringify(selectedAuditLog, null, 2)}
+              </pre>
+            </div>
+          )}
+        </DialogContent>
+      </Dialog>
+    </>
+  );
+};

apps/remix/app/routes/_authenticated+/admin+/documents.$id.tsx

@@ -6,6 +6,7 @@ import { DateTime } from 'luxon';
 import { Link, redirect } from 'react-router';
 
 import { unsafeGetEntireEnvelope } from '@documenso/lib/server-only/admin/get-entire-document';
+import { mapSecondaryIdToDocumentId } from '@documenso/lib/utils/envelope';
 import { trpc } from '@documenso/trpc/react';
 import {
   Accordion,
@@ -26,6 +27,7 @@ import { useToast } from '@documenso/ui/primitives/use-toast';
 import { AdminDocumentDeleteDialog } from '~/components/dialogs/admin-document-delete-dialog';
 import { DocumentStatus } from '~/components/general/document/document-status';
 import { AdminDocumentJobsTable } from '~/components/tables/admin-document-jobs-table';
+import { AdminDocumentLogsTable } from '~/components/tables/admin-document-logs-table';
 import { AdminDocumentRecipientItemTable } from '~/components/tables/admin-document-recipient-item-table';
 
 import type { Route } from './+types/documents.$id';
@@ -87,6 +89,10 @@ export default function AdminDocumentDetailsPage({ loaderData }: Route.Component
       </div>
 
       <div className="mt-4 text-sm text-muted-foreground">
+        <div>
+          <Trans>Document ID</Trans>: {mapSecondaryIdToDocumentId(envelope.secondaryId)}
+        </div>
+
         <div>
           <Trans>Created on</Trans>: {i18n.date(envelope.createdAt, DateTime.DATETIME_MED)}
         </div>
@@ -156,6 +162,9 @@ export default function AdminDocumentDetailsPage({ loaderData }: Route.Component
                   <Badge size="small" variant="neutral">
                     {recipient.email}
                   </Badge>
+                  <Badge size="small" variant="secondary">
+                    {recipient.role}
+                  </Badge>
                 </div>
               </AccordionTrigger>
 
@@ -175,6 +184,22 @@ export default function AdminDocumentDetailsPage({ loaderData }: Route.Component
 
       <hr className="my-4" />
 
+      <Accordion type="single" collapsible className="w-full">
+        <AccordionItem value="audit-logs" className="rounded-lg border">
+          <AccordionTrigger className="px-4">
+            <h2 className="text-lg font-semibold">
+              <Trans>Audit Logs</Trans>
+            </h2>
+          </AccordionTrigger>
+
+          <AccordionContent className="border-t px-4 pt-4">
+            <AdminDocumentLogsTable envelopeId={envelope.id} />
+          </AccordionContent>
+        </AccordionItem>
+      </Accordion>
+
+      <hr className="my-4" />
+
       {envelope && <AdminDocumentDeleteDialog envelopeId={envelope.id} />}
     </div>
   );

packages/prisma/migrations/20260113022858_add_envelope_id_index_to_document_audit_log_table/migration.sql

@@ -0,0 +1,2 @@
+-- CreateIndex
+CREATE INDEX IF NOT EXISTS "DocumentAuditLog_envelopeId_idx" ON "DocumentAuditLog"("envelopeId");

packages/prisma/schema.prisma

@@ -472,6 +472,8 @@ model DocumentAuditLog {
   ipAddress String?
 
   envelope Envelope @relation(fields: [envelopeId], references: [id], onDelete: Cascade)
+
+  @@index([envelopeId])
 }
 
 enum DocumentDataType {

packages/trpc/server/admin-router/find-document-audit-logs.ts

@@ -0,0 +1,66 @@
+import { EnvelopeType } from '@prisma/client';
+
+import { AppError, AppErrorCode } from '@documenso/lib/errors/app-error';
+import type { FindResultResponse } from '@documenso/lib/types/search-params';
+import { parseDocumentAuditLogData } from '@documenso/lib/utils/document-audit-logs';
+import { unsafeBuildEnvelopeIdQuery } from '@documenso/lib/utils/envelope';
+import { prisma } from '@documenso/prisma';
+
+import { adminProcedure } from '../trpc';
+import {
+  ZFindDocumentAuditLogsRequestSchema,
+  ZFindDocumentAuditLogsResponseSchema,
+} from './find-document-audit-logs.types';
+
+export const findDocumentAuditLogsRoute = adminProcedure
+  .input(ZFindDocumentAuditLogsRequestSchema)
+  .output(ZFindDocumentAuditLogsResponseSchema)
+  .query(async ({ input }) => {
+    const {
+      envelopeId,
+      page = 1,
+      perPage = 50,
+      orderByColumn = 'createdAt',
+      orderByDirection = 'desc',
+    } = input;
+
+    const envelope = await prisma.envelope.findFirst({
+      where: unsafeBuildEnvelopeIdQuery(
+        {
+          type: 'envelopeId',
+          id: envelopeId,
+        },
+        EnvelopeType.DOCUMENT,
+      ),
+    });
+
+    if (!envelope) {
+      throw new AppError(AppErrorCode.NOT_FOUND, {
+        message: 'Envelope not found',
+      });
+    }
+
+    const [data, count] = await Promise.all([
+      prisma.documentAuditLog.findMany({
+        where: { envelopeId: envelope.id },
+        skip: Math.max(page - 1, 0) * perPage,
+        take: perPage,
+        orderBy: {
+          [orderByColumn]: orderByDirection,
+        },
+      }),
+      prisma.documentAuditLog.count({
+        where: { envelopeId: envelope.id },
+      }),
+    ]);
+
+    const parsedData = data.map((auditLog) => parseDocumentAuditLogData(auditLog));
+
+    return {
+      data: parsedData,
+      count,
+      currentPage: Math.max(page, 1),
+      perPage,
+      totalPages: Math.ceil(count / perPage),
+    } satisfies FindResultResponse<typeof parsedData>;
+  });

packages/trpc/server/admin-router/find-document-audit-logs.types.ts

@@ -0,0 +1,17 @@
+import { z } from 'zod';
+
+import { ZDocumentAuditLogSchema } from '@documenso/lib/types/document-audit-logs';
+import { ZFindResultResponse, ZFindSearchParamsSchema } from '@documenso/lib/types/search-params';
+
+export const ZFindDocumentAuditLogsRequestSchema = ZFindSearchParamsSchema.extend({
+  envelopeId: z.string(),
+  orderByColumn: z.enum(['createdAt']).optional(),
+  orderByDirection: z.enum(['asc', 'desc']).optional(),
+});
+
+export const ZFindDocumentAuditLogsResponseSchema = ZFindResultResponse.extend({
+  data: ZDocumentAuditLogSchema.array(),
+});
+
+export type TFindDocumentAuditLogsRequest = z.infer<typeof ZFindDocumentAuditLogsRequestSchema>;
+export type TFindDocumentAuditLogsResponse = z.infer<typeof ZFindDocumentAuditLogsResponseSchema>;

packages/trpc/server/admin-router/router.ts

@@ -8,6 +8,7 @@ import { deleteUserRoute } from './delete-user';
 import { disableUserRoute } from './disable-user';
 import { enableUserRoute } from './enable-user';
 import { findAdminOrganisationsRoute } from './find-admin-organisations';
+import { findDocumentAuditLogsRoute } from './find-document-audit-logs';
 import { findDocumentJobsRoute } from './find-document-jobs';
 import { findDocumentsRoute } from './find-documents';
 import { findSubscriptionClaimsRoute } from './find-subscription-claims';
@@ -56,6 +57,7 @@ export const adminRouter = router({
     delete: deleteDocumentRoute,
     reseal: resealDocumentRoute,
     findJobs: findDocumentJobsRoute,
+    findAuditLogs: findDocumentAuditLogsRoute,
   },
   recipient: {
     update: updateRecipientRoute,