Skip to content

The Open Source DocuSign Alternative.

feat: allow admin recipient search (#3277)

David Nguyen73d58bdf31f5
diff --git a/apps/remix/app/components/general/use-admin-search-categories.ts b/apps/remix/app/components/general/use-admin-search-categories.ts
index fc950b708..547fe7afb 100644
--- a/apps/remix/app/components/general/use-admin-search-categories.ts
+++ b/apps/remix/app/components/general/use-admin-search-categories.ts
@@ -39,13 +39,14 @@ const ADMIN_GROUP_ICONS: Record<TAdminSearchResultType, LucideIcon> = {
/**
* Admin list pages which support prefilling their search from the URL, used
- * for the "View all results" links on capped groups. Teams, recipients and
+ * for the "View all results" links on capped groups. Teams and
* subscriptions have no admin list pages.
*/
const ADMIN_GROUP_LIST_PATHS: Partial<Record<TAdminSearchResultType, (_query: string) => string>> = {
document: (query) => `/admin/documents?term=${encodeURIComponent(query)}`,
user: (query) => `/admin/users?search=${encodeURIComponent(query)}`,
organisation: (query) => `/admin/organisations?query=${encodeURIComponent(query)}`,
+ recipient: (query) => `/admin/documents?term=${encodeURIComponent(`recipient:${query}`)}`,
};
export type UseAdminSearchCategoriesOptions = {
diff --git a/apps/remix/app/routes/_authenticated+/admin+/documents._index.tsx b/apps/remix/app/routes/_authenticated+/admin+/documents._index.tsx
index 1f1bb5317..b8c84ff2b 100644
--- a/apps/remix/app/routes/_authenticated+/admin+/documents._index.tsx
+++ b/apps/remix/app/routes/_authenticated+/admin+/documents._index.tsx
@@ -12,7 +12,7 @@ import { msg } from '@lingui/core/macro';
import { useLingui } from '@lingui/react';
import { Trans } from '@lingui/react/macro';
import { Loader } from 'lucide-react';
-import { useMemo, useState } from 'react';
+import { useEffect, useMemo, useState } from 'react';
import { Link, useSearchParams } from 'react-router';
import { DocumentStatus } from '~/components/general/document/document-status';
@@ -30,6 +30,12 @@ export default function AdminDocumentsPage() {
const page = searchParams?.get?.('page') ? Number(searchParams.get('page')) : undefined;
const perPage = searchParams?.get?.('perPage') ? Number(searchParams.get('perPage')) : undefined;
+ const urlTerm = searchParams?.get?.('term') ?? '';
+
+ useEffect(() => {
+ setTerm(urlTerm);
+ }, [urlTerm]);
+
const { data: findDocumentsData, isPending: isFindDocumentsLoading } = trpc.admin.document.find.useQuery(
{
query: debouncedTerm,
@@ -131,7 +137,7 @@ export default function AdminDocumentsPage() {
<div>
<Input
type="search"
- placeholder={_(msg`Search by document title, team:123 or user:123`)}
+ placeholder={_(msg`Search by document title, recipient:123, team:123 or user:123`)}
value={term}
onChange={(e) => setTerm(e.target.value)}
/>
diff --git a/packages/app-tests/e2e/admin/global-search.spec.ts b/packages/app-tests/e2e/admin/global-search.spec.ts
index d8a1b5fbe..ab9f2d698 100644
--- a/packages/app-tests/e2e/admin/global-search.spec.ts
+++ b/packages/app-tests/e2e/admin/global-search.spec.ts
@@ -437,3 +437,98 @@ test('[ADMIN][GLOBAL_SEARCH]: over-length query skips the admin search without e
expect(adminSearchRequests).toHaveLength(0);
});
+
+test('[ADMIN][GLOBAL_SEARCH]: capped recipients group links to the admin documents page', async ({ page }) => {
+ const { user: adminUser } = await seedUser({ isAdmin: true });
+ const { user: sender, team } = await seedUser();
+
+ const recipientPrefix = `viewall-recipient-${nanoid()}`;
+
+ // Seed 5 documents, each with one recipient email sharing the prefix, to
+ // hit the 5 result cap on the recipients group.
+ const documents = [];
+
+ for (let i = 0; i < 5; i++) {
+ documents.push(
+ await seedPendingDocument(sender, team.id, [`${recipientPrefix}-${i}@test.documenso.com`], {
+ createDocumentOptions: { title: `recipient-viewall-${nanoid()}` },
+ }),
+ );
+ }
+
+ await apiSignin({ page, email: adminUser.email });
+
+ await openCommandMenu(page, ADMIN_PROMPT_PLACEHOLDER);
+
+ await page.getByPlaceholder(ADMIN_PROMPT_PLACEHOLDER).first().fill(recipientPrefix);
+
+ await expect(page.getByText('Global Recipients', { exact: true })).toBeVisible();
+
+ // Only the recipients group matches the prefix, so this is its link.
+ const viewAllOption = page.getByRole('option').filter({ hasText: 'View all results' }).first();
+
+ await expect(viewAllOption.getByRole('link')).toHaveAttribute(
+ 'href',
+ `/admin/documents?term=${encodeURIComponent(`recipient:${recipientPrefix}`)}`,
+ );
+
+ await viewAllOption.click();
+
+ await page.waitForURL((url) => url.pathname === '/admin/documents');
+
+ // The term input is prefilled with the recipient query and the matching
+ // documents are listed.
+ await expect(page.getByPlaceholder(/Search by document title/)).toHaveValue(`recipient:${recipientPrefix}`);
+
+ for (const document of documents) {
+ await expect(page.getByRole('link', { name: document.title })).toBeVisible();
+ }
+});
+
+test('[ADMIN][GLOBAL_SEARCH]: view all results updates the documents page when already on it', async ({ page }) => {
+ const { user: adminUser } = await seedUser({ isAdmin: true });
+ const { user: sender, team } = await seedUser();
+
+ const recipientPrefix = `viewall-live-${nanoid()}`;
+
+ // Seed 5 documents with recipients matching the prefix to hit the cap, and
+ // one control document whose recipient does not match: with a stale
+ // (unfiltered) query the control would show, with the filter it must not.
+ const documents = [];
+
+ for (let i = 0; i < 5; i++) {
+ documents.push(
+ await seedPendingDocument(sender, team.id, [`${recipientPrefix}-${i}@test.documenso.com`], {
+ createDocumentOptions: { title: `recipient-live-${nanoid()}` },
+ }),
+ );
+ }
+
+ const controlDocument = await seedPendingDocument(sender, team.id, [`control-${nanoid()}@test.documenso.com`], {
+ createDocumentOptions: { title: `recipient-live-control-${nanoid()}` },
+ });
+
+ await apiSignin({ page, email: adminUser.email });
+
+ // Start ON the admin documents page: the buggy state initializer has
+ // already run with an empty term.
+ await page.goto('/admin/documents');
+
+ await expect(page.getByPlaceholder(/Search by document title/)).toBeVisible();
+
+ await openCommandMenu(page, ADMIN_PROMPT_PLACEHOLDER);
+
+ await page.getByPlaceholder(ADMIN_PROMPT_PLACEHOLDER).first().fill(recipientPrefix);
+
+ await expect(page.getByText('Global Recipients', { exact: true })).toBeVisible();
+
+ await page.getByRole('option').filter({ hasText: 'View all results' }).first().click();
+
+ await page.waitForURL((url) => url.searchParams.get('term') === `recipient:${recipientPrefix}`);
+
+ // The same-route navigation must update both the input and the results.
+ await expect(page.getByPlaceholder(/Search by document title/)).toHaveValue(`recipient:${recipientPrefix}`);
+
+ await expect(page.getByRole('link', { name: documents[0].title })).toBeVisible();
+ await expect(page.getByRole('link', { name: controlDocument.title })).toHaveCount(0);
+});
diff --git a/packages/app-tests/e2e/api/trpc/admin/admin-find-documents.spec.ts b/packages/app-tests/e2e/api/trpc/admin/admin-find-documents.spec.ts
new file mode 100644
index 000000000..92ea6b4cc
--- /dev/null
+++ b/packages/app-tests/e2e/api/trpc/admin/admin-find-documents.spec.ts
@@ -0,0 +1,226 @@
+import { NEXT_PUBLIC_WEBAPP_URL } from '@documenso/lib/constants/app';
+import { seedPendingDocument } from '@documenso/prisma/seed/documents';
+import { seedUser } from '@documenso/prisma/seed/users';
+import type { Page } from '@playwright/test';
+import { expect, test } from '@playwright/test';
+import { customAlphabet } from 'nanoid';
+
+import { apiSignin } from '../../../fixtures/authentication';
+
+const nanoid = customAlphabet('1234567890abcdef', 10);
+
+const WEBAPP_BASE_URL = NEXT_PUBLIC_WEBAPP_URL();
+
+test.describe.configure({ mode: 'parallel' });
+
+type AdminFindDocumentsResult = {
+ data: Array<{ envelopeId: string; title: string }>;
+ count: number;
+};
+
+const callAdminFindDocuments = async (page: Page, query: string) => {
+ const inputParam = encodeURIComponent(JSON.stringify({ json: { query, page: 1, perPage: 20 } }));
+ const url = `${WEBAPP_BASE_URL}/api/trpc/admin.document.find?input=${inputParam}`;
+
+ const res = await page.context().request.get(url);
+
+ return {
+ res,
+ result: res.ok()
+ ? // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
+ ((await res.json()).result.data.json as AdminFindDocumentsResult)
+ : null,
+ };
+};
+
+// ─── Access control ──────────────────────────────────────────────────────────
+
+test('[ADMIN][TRPC][FIND_DOCUMENTS]: non-admin user is rejected with 401', async ({ page }) => {
+ const { user: nonAdminUser } = await seedUser({ isAdmin: false });
+
+ await apiSignin({ page, email: nonAdminUser.email });
+
+ const { res } = await callAdminFindDocuments(page, 'recipient:anything');
+
+ expect(res.ok()).toBeFalsy();
+ expect(res.status()).toBe(401);
+});
+
+// ─── recipient: prefix ───────────────────────────────────────────────────────
+
+test('[ADMIN][TRPC][FIND_DOCUMENTS]: recipient prefix matches by recipient email', async ({ page }) => {
+ const { user: adminUser } = await seedUser({ isAdmin: true });
+ const { user: sender, team } = await seedUser();
+
+ const recipientEmail = `recipient-find-${nanoid()}@test.documenso.com`;
+
+ const matchingDocument = await seedPendingDocument(sender, team.id, [recipientEmail], {
+ createDocumentOptions: { title: `recipient-find-match-${nanoid()}` },
+ });
+
+ const otherDocument = await seedPendingDocument(sender, team.id, [`other-${nanoid()}@test.documenso.com`], {
+ createDocumentOptions: { title: `recipient-find-other-${nanoid()}` },
+ });
+
+ await apiSignin({ page, email: adminUser.email });
+
+ const { res, result } = await callAdminFindDocuments(page, `recipient:${recipientEmail}`);
+
+ expect(res.ok()).toBeTruthy();
+ expect(result?.count).toBe(1);
+ expect(result?.data.map((document) => document.envelopeId)).toContain(matchingDocument.id);
+ expect(result?.data.map((document) => document.envelopeId)).not.toContain(otherDocument.id);
+});
+
+test('[ADMIN][TRPC][FIND_DOCUMENTS]: recipient prefix matches by recipient name case-insensitively', async ({
+ page,
+}) => {
+ const { user: adminUser } = await seedUser({ isAdmin: true });
+ const { user: sender, team } = await seedUser();
+
+ const recipientName = `recipient-name-${nanoid()}`;
+ const { user: recipientUser } = await seedUser({ name: recipientName });
+
+ const matchingDocument = await seedPendingDocument(sender, team.id, [recipientUser], {
+ createDocumentOptions: { title: `recipient-name-match-${nanoid()}` },
+ });
+
+ await apiSignin({ page, email: adminUser.email });
+
+ // Query the uppercased name: matching must be case-insensitive.
+ const { res, result } = await callAdminFindDocuments(page, `recipient:${recipientName.toUpperCase()}`);
+
+ expect(res.ok()).toBeTruthy();
+ expect(result?.count).toBe(1);
+ expect(result?.data.map((document) => document.envelopeId)).toContain(matchingDocument.id);
+});
+
+test('[ADMIN][TRPC][FIND_DOCUMENTS]: recipient prefix with empty value returns no results', async ({ page }) => {
+ const { user: adminUser } = await seedUser({ isAdmin: true });
+
+ await apiSignin({ page, email: adminUser.email });
+
+ const emptyValueSearch = await callAdminFindDocuments(page, 'recipient:');
+
+ expect(emptyValueSearch.res.ok()).toBeTruthy();
+ expect(emptyValueSearch.result?.data).toEqual([]);
+ expect(emptyValueSearch.result?.count).toBe(0);
+
+ // Whitespace-only values are treated the same as empty.
+ const whitespaceValueSearch = await callAdminFindDocuments(page, 'recipient: ');
+
+ expect(whitespaceValueSearch.res.ok()).toBeTruthy();
+ expect(whitespaceValueSearch.result?.data).toEqual([]);
+ expect(whitespaceValueSearch.result?.count).toBe(0);
+});
+
+test('[ADMIN][TRPC][FIND_DOCUMENTS]: recipient prefix with no matches returns no results', async ({ page }) => {
+ const { user: adminUser } = await seedUser({ isAdmin: true });
+
+ await apiSignin({ page, email: adminUser.email });
+
+ const { res, result } = await callAdminFindDocuments(page, 'recipient:zzzz-no-such-recipient-9x7q');
+
+ expect(res.ok()).toBeTruthy();
+ expect(result?.data).toEqual([]);
+ expect(result?.count).toBe(0);
+});
+
+test('[ADMIN][TRPC][FIND_DOCUMENTS]: recipient prefix with numeric value matches by exact recipient ID', async ({
+ page,
+}) => {
+ const { user: adminUser } = await seedUser({ isAdmin: true });
+ const { user: sender, team } = await seedUser();
+
+ const matchingDocument = await seedPendingDocument(sender, team.id, [`recipient-id-${nanoid()}@test.documenso.com`], {
+ createDocumentOptions: { title: `recipient-id-match-${nanoid()}` },
+ });
+
+ const recipient = matchingDocument.recipients[0];
+
+ // A decoy whose recipient email contains the ID as text: an exact ID lookup
+ // must exclude it, while an accidental "ID or contains" match would not.
+ const decoyDocument = await seedPendingDocument(
+ sender,
+ team.id,
+ [`decoy-${recipient.id}-${nanoid()}@test.documenso.com`],
+ {
+ createDocumentOptions: { title: `recipient-id-decoy-${nanoid()}` },
+ },
+ );
+
+ await apiSignin({ page, email: adminUser.email });
+
+ const { res, result } = await callAdminFindDocuments(page, `recipient:${recipient.id}`);
+
+ expect(res.ok()).toBeTruthy();
+ expect(result?.count).toBe(1);
+ expect(result?.data.map((document) => document.envelopeId)).toContain(matchingDocument.id);
+ expect(result?.data.map((document) => document.envelopeId)).not.toContain(decoyDocument.id);
+});
+
+test('[ADMIN][TRPC][FIND_DOCUMENTS]: recipient prefix with nonexistent recipient ID returns no results', async ({
+ page,
+}) => {
+ const { user: adminUser } = await seedUser({ isAdmin: true });
+
+ await apiSignin({ page, email: adminUser.email });
+
+ // Int4 max - 1: a valid ID-shaped number that no autoincrement recipient
+ // sequence will plausibly reach, and that no other test seeds as text.
+ const { res, result } = await callAdminFindDocuments(page, 'recipient:2147483646');
+
+ expect(res.ok()).toBeTruthy();
+ expect(result?.data).toEqual([]);
+ expect(result?.count).toBe(0);
+});
+
+test('[ADMIN][TRPC][FIND_DOCUMENTS]: recipient prefix with oversized number falls back to text search', async ({
+ page,
+}) => {
+ const { user: adminUser } = await seedUser({ isAdmin: true });
+ const { user: sender, team } = await seedUser();
+
+ // 99999999999999 exceeds Int4, so it cannot be an ID lookup: it must be
+ // treated as text (and must not 500).
+ const oversizedNumber = '99999999999999';
+
+ const matchingDocument = await seedPendingDocument(
+ sender,
+ team.id,
+ [`${oversizedNumber}-${nanoid()}@test.documenso.com`],
+ {
+ createDocumentOptions: { title: `recipient-oversized-${nanoid()}` },
+ },
+ );
+
+ await apiSignin({ page, email: adminUser.email });
+
+ const { res, result } = await callAdminFindDocuments(page, `recipient:${oversizedNumber}`);
+
+ expect(res.ok()).toBeTruthy();
+ expect(result?.data.map((document) => document.envelopeId)).toContain(matchingDocument.id);
+});
+
+test('[ADMIN][TRPC][FIND_DOCUMENTS]: user and team prefixes with oversized numbers return no results', async ({
+ page,
+}) => {
+ const { user: adminUser } = await seedUser({ isAdmin: true });
+
+ await apiSignin({ page, email: adminUser.email });
+
+ // 99999999999999 exceeds Int4, so it can never be a valid user or team ID.
+ // The ID schema must reject it so the query returns empty instead of
+ // overflowing Postgres and erroring.
+ const userSearch = await callAdminFindDocuments(page, 'user:99999999999999');
+
+ expect(userSearch.res.ok()).toBeTruthy();
+ expect(userSearch.result?.data).toEqual([]);
+ expect(userSearch.result?.count).toBe(0);
+
+ const teamSearch = await callAdminFindDocuments(page, 'team:99999999999999');
+
+ expect(teamSearch.res.ok()).toBeTruthy();
+ expect(teamSearch.result?.data).toEqual([]);
+ expect(teamSearch.result?.count).toBe(0);
+});
diff --git a/packages/lib/server-only/admin/admin-find-documents.ts b/packages/lib/server-only/admin/admin-find-documents.ts
index 994422ba7..4643daed8 100644
--- a/packages/lib/server-only/admin/admin-find-documents.ts
+++ b/packages/lib/server-only/admin/admin-find-documents.ts
@@ -10,7 +10,13 @@ export interface AdminFindDocumentsOptions {
perPage?: number;
}
-const ZPositiveIntegerSchema = z.coerce.number().int().positive();
+const MAX_POSTGRES_INT = 2147483647;
+
+/**
+ * IDs are Postgres int4 columns: values above the range can never be valid
+ * IDs and would make Prisma throw on overflow, so the schema rejects them.
+ */
+const ZPositiveIntegerSchema = z.coerce.number().int().positive().max(MAX_POSTGRES_INT);
const emptyResponse = {
data: [],
@@ -58,7 +64,41 @@ export const adminFindDocuments = async ({ query, page = 1, perPage = 10 }: Admi
}
}
- if (query && query?.startsWith('envelope_')) {
+ if (query?.startsWith('recipient:')) {
+ const recipientQuery = query.slice('recipient:'.length).trim();
+
+ if (recipientQuery.length === 0) {
+ return emptyResponse;
+ }
+
+ // Bare numeric values are exact recipient ID lookups, consistent with the
+ // user: and team: prefixes. Oversized numbers cannot be IDs and fall back
+ // to the text search, mirroring the admin global search.
+ const parsedRecipientId = ZPositiveIntegerSchema.safeParse(recipientQuery);
+
+ if (/^\d+$/.test(recipientQuery) && parsedRecipientId.success) {
+ termFilters = {
+ recipients: {
+ some: {
+ id: parsedRecipientId.data,
+ },
+ },
+ };
+ } else {
+ termFilters = {
+ recipients: {
+ some: {
+ OR: [
+ { email: { contains: recipientQuery, mode: 'insensitive' } },
+ { name: { contains: recipientQuery, mode: 'insensitive' } },
+ ],
+ },
+ },
+ };
+ }
+ }
+
+ if (query?.startsWith('envelope_')) {
termFilters = {
id: {
equals: query,
@@ -66,7 +106,7 @@ export const adminFindDocuments = async ({ query, page = 1, perPage = 10 }: Admi
};
}
- if (query && query?.startsWith('document_')) {
+ if (query?.startsWith('document_')) {
termFilters = {
secondaryId: {
equals: query,