fix: support dynamic external ids for direct templates (#1274)

Adds support for an `externalId` query param to be passed when linking a
user to a direct template. This external id will then be stored on the
document upon signing completion.

apps/web/src/app/(recipient)/d/[token]/direct-template.tsx

@@ -2,7 +2,7 @@
 
 import { useState } from 'react';
 
-import { useRouter } from 'next/navigation';
+import { useRouter, useSearchParams } from 'next/navigation';
 
 import { RECIPIENT_ROLES_DESCRIPTION } from '@documenso/lib/constants/recipient-roles';
 import type { Field } from '@documenso/prisma/client';
@@ -39,6 +39,7 @@ export const DirectTemplatePageView = ({
   directTemplateToken,
 }: TemplatesDirectPageViewProps) => {
   const router = useRouter();
+  const searchParams = useSearchParams();
 
   const { toast } = useToast();
 
@@ -82,8 +83,15 @@ export const DirectTemplatePageView = ({
 
   const onSignDirectTemplateSubmit = async (fields: DirectTemplateLocalField[]) => {
     try {
+      let directTemplateExternalId = searchParams?.get('externalId') || undefined;
+
+      if (directTemplateExternalId) {
+        directTemplateExternalId = decodeURIComponent(directTemplateExternalId);
+      }
+
       const token = await createDocumentFromDirectTemplate({
         directTemplateToken,
+        directTemplateExternalId,
         directRecipientName: fullName,
         directRecipientEmail: recipient.email,
         templateUpdatedAt: template.updatedAt,

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

@@ -44,6 +44,7 @@ export type CreateDocumentFromDirectTemplateOptions = {
   directRecipientName?: string;
   directRecipientEmail: string;
   directTemplateToken: string;
+  directTemplateExternalId?: string;
   signedFieldValues: TSignFieldWithTokenMutationSchema[];
   templateUpdatedAt: Date;
   requestMetadata: RequestMetadata;
@@ -63,6 +64,7 @@ export const createDocumentFromDirectTemplate = async ({
   directRecipientName: initialDirectRecipientName,
   directRecipientEmail,
   directTemplateToken,
+  directTemplateExternalId,
   signedFieldValues,
   templateUpdatedAt,
   requestMetadata,
@@ -227,6 +229,7 @@ export const createDocumentFromDirectTemplate = async ({
         title: template.title,
         createdAt: initialRequestTime,
         status: DocumentStatus.PENDING,
+        externalId: directTemplateExternalId,
         documentDataId: documentData.id,
         authOptions: createDocumentAuthOptions({
           globalAccessAuth: templateAuthOptions.globalAccessAuth,

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

@@ -66,6 +66,7 @@ export const templateRouter = router({
           directRecipientName,
           directRecipientEmail,
           directTemplateToken,
+          directTemplateExternalId,
           signedFieldValues,
           templateUpdatedAt,
         } = input;
@@ -76,6 +77,7 @@ export const templateRouter = router({
           directRecipientName,
           directRecipientEmail,
           directTemplateToken,
+          directTemplateExternalId,
           signedFieldValues,
           templateUpdatedAt,
           user: ctx.user

packages/trpc/server/template-router/schema.ts

@@ -20,6 +20,7 @@ export const ZCreateDocumentFromDirectTemplateMutationSchema = z.object({
   directRecipientName: z.string().optional(),
   directRecipientEmail: z.string().email(),
   directTemplateToken: z.string().min(1),
+  directTemplateExternalId: z.string().optional(),
   signedFieldValues: z.array(ZSignFieldWithTokenMutationSchema),
   templateUpdatedAt: z.date(),
 });