feat: add template and field endpoints (#1572)

This commit is contained in:
David Nguyen
2025-01-11 15:33:20 +11:00
committed by GitHub
parent 6520bbd5e3
commit ebbe922982
92 changed files with 3920 additions and 1396 deletions

View File

@ -1,26 +1,57 @@
import { z } from 'zod';
import { completeDocumentWithToken } from '@documenso/lib/server-only/document/complete-document-with-token';
import { rejectDocumentWithToken } from '@documenso/lib/server-only/document/reject-document-with-token';
import {
ZCreateDocumentRecipientsResponseSchema,
createDocumentRecipients,
} from '@documenso/lib/server-only/recipient/create-document-recipients';
import {
ZCreateTemplateRecipientsResponseSchema,
createTemplateRecipients,
} from '@documenso/lib/server-only/recipient/create-template-recipients';
import { deleteDocumentRecipient } from '@documenso/lib/server-only/recipient/delete-document-recipient';
import { deleteTemplateRecipient } from '@documenso/lib/server-only/recipient/delete-template-recipient';
import {
ZGetRecipientByIdResponseSchema,
getRecipientById,
} from '@documenso/lib/server-only/recipient/get-recipient-by-id';
import {
ZSetRecipientsForDocumentResponseSchema,
setRecipientsForDocument,
} from '@documenso/lib/server-only/recipient/set-recipients-for-document';
ZSetDocumentRecipientsResponseSchema,
setDocumentRecipients,
} from '@documenso/lib/server-only/recipient/set-document-recipients';
import {
ZSetRecipientsForTemplateResponseSchema,
setRecipientsForTemplate,
} from '@documenso/lib/server-only/recipient/set-recipients-for-template';
ZSetTemplateRecipientsResponseSchema,
setTemplateRecipients,
} from '@documenso/lib/server-only/recipient/set-template-recipients';
import { updateDocumentRecipients } from '@documenso/lib/server-only/recipient/update-document-recipients';
import { updateTemplateRecipients } from '@documenso/lib/server-only/recipient/update-template-recipients';
import { extractNextApiRequestMetadata } from '@documenso/lib/universal/extract-request-metadata';
import { authenticatedProcedure, procedure, router } from '../trpc';
import {
ZAddSignersMutationSchema,
ZAddTemplateSignersMutationSchema,
ZCompleteDocumentWithTokenMutationSchema,
ZCreateDocumentRecipientRequestSchema,
ZCreateDocumentRecipientResponseSchema,
ZCreateDocumentRecipientsRequestSchema,
ZCreateTemplateRecipientRequestSchema,
ZCreateTemplateRecipientResponseSchema,
ZCreateTemplateRecipientsRequestSchema,
ZDeleteDocumentRecipientRequestSchema,
ZDeleteTemplateRecipientRequestSchema,
ZGetRecipientQuerySchema,
ZRejectDocumentWithTokenMutationSchema,
ZSetDocumentRecipientsRequestSchema,
ZSetTemplateRecipientsRequestSchema,
ZUpdateDocumentRecipientRequestSchema,
ZUpdateDocumentRecipientResponseSchema,
ZUpdateDocumentRecipientsRequestSchema,
ZUpdateDocumentRecipientsResponseSchema,
ZUpdateTemplateRecipientRequestSchema,
ZUpdateTemplateRecipientResponseSchema,
ZUpdateTemplateRecipientsRequestSchema,
ZUpdateTemplateRecipientsResponseSchema,
} from './schema';
export const recipientRouter = router({
@ -35,13 +66,14 @@ export const recipientRouter = router({
summary: 'Get recipient',
description:
'Returns a single recipient. If you want to retrieve all the recipients for a document or template, use the "Get Document" or "Get Template" request.',
tags: ['Recipients'],
tags: ['Document Recipients', 'Template Recipients'],
},
})
.input(ZGetRecipientQuerySchema)
.output(ZGetRecipientByIdResponseSchema)
.query(async ({ input, ctx }) => {
const { recipientId, teamId } = input;
const { teamId } = ctx;
const { recipientId } = input;
return await getRecipientById({
userId: ctx.user.id,
@ -53,64 +85,349 @@ export const recipientRouter = router({
/**
* @public
*/
addSigners: authenticatedProcedure
createDocumentRecipient: authenticatedProcedure
.meta({
openapi: {
method: 'POST',
path: '/document/{documentId}/recipient/set',
summary: 'Set document recipients',
tags: ['Recipients'],
path: '/document/recipient/create',
summary: 'Create document recipient',
description: 'Create a single recipient for a document.',
tags: ['Document Recipients'],
},
})
.input(ZAddSignersMutationSchema)
.output(ZSetRecipientsForDocumentResponseSchema)
.input(ZCreateDocumentRecipientRequestSchema)
.output(ZCreateDocumentRecipientResponseSchema)
.mutation(async ({ input, ctx }) => {
const { documentId, teamId, signers } = input;
const { teamId } = ctx;
const { documentId, recipient } = input;
return await setRecipientsForDocument({
const createdRecipients = await createDocumentRecipients({
userId: ctx.user.id,
documentId,
teamId,
recipients: signers.map((signer) => ({
id: signer.nativeId,
email: signer.email,
name: signer.name,
role: signer.role,
signingOrder: signer.signingOrder,
actionAuth: signer.actionAuth,
})),
requestMetadata: extractNextApiRequestMetadata(ctx.req),
documentId,
recipients: [recipient],
requestMetadata: ctx.metadata,
});
return createdRecipients.recipients[0];
}),
/**
* @public
*/
createDocumentRecipients: authenticatedProcedure
.meta({
openapi: {
method: 'POST',
path: '/document/recipient/create-many',
summary: 'Create document recipients',
description: 'Create multiple recipients for a document.',
tags: ['Document Recipients'],
},
})
.input(ZCreateDocumentRecipientsRequestSchema)
.output(ZCreateDocumentRecipientsResponseSchema)
.mutation(async ({ input, ctx }) => {
const { teamId } = ctx;
const { documentId, recipients } = input;
return await createDocumentRecipients({
userId: ctx.user.id,
teamId,
documentId,
recipients,
requestMetadata: ctx.metadata,
});
}),
/**
* @public
*/
addTemplateSigners: authenticatedProcedure
updateDocumentRecipient: authenticatedProcedure
.meta({
openapi: {
method: 'POST',
path: '/template/{templateId}/recipient/set',
summary: 'Set template recipients',
tags: ['Recipients'],
path: '/document/recipient/update',
summary: 'Update document recipient',
description: 'Update a single recipient for a document.',
tags: ['Document Recipients'],
},
})
.input(ZAddTemplateSignersMutationSchema)
.output(ZSetRecipientsForTemplateResponseSchema)
.input(ZUpdateDocumentRecipientRequestSchema)
.output(ZUpdateDocumentRecipientResponseSchema)
.mutation(async ({ input, ctx }) => {
const { templateId, signers, teamId } = input;
const { teamId } = ctx;
const { documentId, recipient } = input;
return await setRecipientsForTemplate({
const updatedRecipients = await updateDocumentRecipients({
userId: ctx.user.id,
teamId,
documentId,
recipients: [recipient],
requestMetadata: ctx.metadata,
});
return updatedRecipients.recipients[0];
}),
/**
* @public
*/
updateDocumentRecipients: authenticatedProcedure
.meta({
openapi: {
method: 'POST',
path: '/document/recipient/update-many',
summary: 'Update document recipients',
description: 'Update multiple recipients for a document.',
tags: ['Document Recipients'],
},
})
.input(ZUpdateDocumentRecipientsRequestSchema)
.output(ZUpdateDocumentRecipientsResponseSchema)
.mutation(async ({ input, ctx }) => {
const { teamId } = ctx;
const { documentId, recipients } = input;
return await updateDocumentRecipients({
userId: ctx.user.id,
teamId,
documentId,
recipients,
requestMetadata: ctx.metadata,
});
}),
/**
* @public
*/
deleteDocumentRecipient: authenticatedProcedure
.meta({
openapi: {
method: 'DELETE',
path: '/document/recipient/{recipientId}',
summary: 'Delete document recipient',
tags: ['Document Recipients'],
},
})
.input(ZDeleteDocumentRecipientRequestSchema)
.output(z.void())
.mutation(async ({ input, ctx }) => {
const { teamId } = ctx;
const { recipientId } = input;
await deleteDocumentRecipient({
userId: ctx.user.id,
teamId,
recipientId,
requestMetadata: ctx.metadata,
});
}),
/**
* @private
*/
setDocumentRecipients: authenticatedProcedure
// .meta({
// openapi: {
// method: 'POST',
// path: '/document/recipient/set',
// summary: 'Set document recipients',
// description:
// 'This will replace all recipients attached to the document. If the array contains existing recipients, they will be updated and the original fields will be retained.',
// tags: ['Document Recipients'],
// },
// })
.input(ZSetDocumentRecipientsRequestSchema)
.output(ZSetDocumentRecipientsResponseSchema)
.mutation(async ({ input, ctx }) => {
const { teamId } = ctx;
const { documentId, recipients } = input;
return await setDocumentRecipients({
userId: ctx.user.id,
teamId,
documentId,
recipients: recipients.map((recipient) => ({
id: recipient.nativeId,
email: recipient.email,
name: recipient.name,
role: recipient.role,
signingOrder: recipient.signingOrder,
actionAuth: recipient.actionAuth,
})),
requestMetadata: ctx.metadata,
});
}),
/**
* @public
*/
createTemplateRecipient: authenticatedProcedure
.meta({
openapi: {
method: 'POST',
path: '/template/recipient/create',
summary: 'Create template recipient',
description: 'Create a single recipient for a template.',
tags: ['Template Recipients'],
},
})
.input(ZCreateTemplateRecipientRequestSchema)
.output(ZCreateTemplateRecipientResponseSchema)
.mutation(async ({ input, ctx }) => {
const { teamId } = ctx;
const { templateId, recipient } = input;
const createdRecipients = await createTemplateRecipients({
userId: ctx.user.id,
teamId,
templateId,
recipients: signers.map((signer) => ({
id: signer.nativeId,
email: signer.email,
name: signer.name,
role: signer.role,
signingOrder: signer.signingOrder,
actionAuth: signer.actionAuth,
recipients: [recipient],
});
return createdRecipients.recipients[0];
}),
/**
* @public
*/
createTemplateRecipients: authenticatedProcedure
.meta({
openapi: {
method: 'POST',
path: '/template/recipient/create-many',
summary: 'Create template recipients',
description: 'Create multiple recipients for a template.',
tags: ['Template Recipients'],
},
})
.input(ZCreateTemplateRecipientsRequestSchema)
.output(ZCreateTemplateRecipientsResponseSchema)
.mutation(async ({ input, ctx }) => {
const { teamId } = ctx;
const { templateId, recipients } = input;
return await createTemplateRecipients({
userId: ctx.user.id,
teamId,
templateId,
recipients,
});
}),
/**
* @public
*/
updateTemplateRecipient: authenticatedProcedure
.meta({
openapi: {
method: 'POST',
path: '/template/recipient/update',
summary: 'Update template recipient',
description: 'Update a single recipient for a template.',
tags: ['Template Recipients'],
},
})
.input(ZUpdateTemplateRecipientRequestSchema)
.output(ZUpdateTemplateRecipientResponseSchema)
.mutation(async ({ input, ctx }) => {
const { teamId } = ctx;
const { templateId, recipient } = input;
const updatedRecipients = await updateTemplateRecipients({
userId: ctx.user.id,
teamId,
templateId,
recipients: [recipient],
});
return updatedRecipients.recipients[0];
}),
/**
* @public
*/
updateTemplateRecipients: authenticatedProcedure
.meta({
openapi: {
method: 'POST',
path: '/template/recipient/update-many',
summary: 'Update template recipients',
description: 'Update multiple recipients for a template.',
tags: ['Template Recipients'],
},
})
.input(ZUpdateTemplateRecipientsRequestSchema)
.output(ZUpdateTemplateRecipientsResponseSchema)
.mutation(async ({ input, ctx }) => {
const { teamId } = ctx;
const { templateId, recipients } = input;
return await updateTemplateRecipients({
userId: ctx.user.id,
teamId,
templateId,
recipients,
});
}),
/**
* @public
*/
deleteTemplateRecipient: authenticatedProcedure
.meta({
openapi: {
method: 'DELETE',
path: '/template/recipient/{recipientId}',
summary: 'Delete template recipient',
tags: ['Template Recipients'],
},
})
.input(ZDeleteTemplateRecipientRequestSchema)
.output(z.void())
.mutation(async ({ input, ctx }) => {
const { teamId } = ctx;
const { recipientId } = input;
await deleteTemplateRecipient({
recipientId,
userId: ctx.user.id,
teamId,
});
}),
/**
* @private
*/
setTemplateRecipients: authenticatedProcedure
// .meta({
// openapi: {
// method: 'POST',
// path: '/template/recipient/set',
// summary: 'Set template recipients',
// description:
// 'This will replace all recipients attached to the template. If the array contains existing recipients, they will be updated and the original fields will be retained.',
// tags: ['Template Recipients'],
// },
// })
.input(ZSetTemplateRecipientsRequestSchema)
.output(ZSetTemplateRecipientsResponseSchema)
.mutation(async ({ input, ctx }) => {
const { teamId } = ctx;
const { templateId, recipients } = input;
return await setTemplateRecipients({
userId: ctx.user.id,
teamId,
templateId,
recipients: recipients.map((recipient) => ({
id: recipient.nativeId,
email: recipient.email,
name: recipient.name,
role: recipient.role,
signingOrder: recipient.signingOrder,
actionAuth: recipient.actionAuth,
})),
});
}),
@ -147,4 +464,32 @@ export const recipientRouter = router({
requestMetadata: extractNextApiRequestMetadata(ctx.req),
});
}),
/**
* Leaving this here and will remove after deployment.
*
* @deprecated Remove after deployment.
*/
addSigners: authenticatedProcedure
.input(ZAddSignersMutationSchema)
.output(ZSetDocumentRecipientsResponseSchema)
.mutation(async ({ input, ctx }) => {
const { teamId } = ctx;
const { documentId, signers } = input;
return await setDocumentRecipients({
userId: ctx.user.id,
documentId,
teamId,
recipients: signers.map((signer) => ({
id: signer.nativeId,
email: signer.email,
name: signer.name,
role: signer.role,
signingOrder: signer.signingOrder,
actionAuth: signer.actionAuth,
})),
requestMetadata: ctx.metadata,
});
}),
});

View File

@ -1,24 +1,114 @@
import { z } from 'zod';
import {
ZRecipientAccessAuthTypesSchema,
ZRecipientActionAuthSchema,
ZRecipientActionAuthTypesSchema,
} from '@documenso/lib/types/document-auth';
import { RecipientRole } from '@documenso/prisma/client';
import { FieldSchema, RecipientSchema } from '@documenso/prisma/generated/zod';
export const ZGetRecipientQuerySchema = z.object({
recipientId: z.number(),
teamId: z.number().optional(),
});
export const ZAddSignersMutationSchema = z
const ZCreateRecipientSchema = z.object({
email: z.string().toLowerCase().email().min(1),
name: z.string(),
role: z.nativeEnum(RecipientRole),
signingOrder: z.number().optional(),
accessAuth: ZRecipientAccessAuthTypesSchema.optional().nullable(),
actionAuth: ZRecipientActionAuthTypesSchema.optional().nullable(),
});
const ZUpdateRecipientSchema = z.object({
id: z.number().describe('The ID of the recipient to update.'),
email: z.string().toLowerCase().email().min(1).optional(),
name: z.string().optional(),
role: z.nativeEnum(RecipientRole).optional(),
signingOrder: z.number().optional(),
accessAuth: ZRecipientAccessAuthTypesSchema.optional().nullable(),
actionAuth: ZRecipientActionAuthTypesSchema.optional().nullable(),
});
/**
* Use this when returning base recipients from the API.
*/
export const ZRecipientBaseResponseSchema = RecipientSchema.pick({
id: true,
documentId: true,
templateId: true,
email: true,
name: true,
token: true,
documentDeletedAt: true,
expired: true,
signedAt: true,
authOptions: true,
signingOrder: true,
rejectionReason: true,
role: true,
readStatus: true,
signingStatus: true,
sendStatus: true,
});
/**
* Use this when returning a full recipient from the API.
*/
export const ZRecipientResponseSchema = ZRecipientBaseResponseSchema.extend({
Field: FieldSchema.array(),
});
export const ZCreateDocumentRecipientRequestSchema = z.object({
documentId: z.number(),
recipient: ZCreateRecipientSchema,
});
export const ZCreateDocumentRecipientResponseSchema = ZRecipientBaseResponseSchema;
export const ZCreateDocumentRecipientsRequestSchema = z.object({
documentId: z.number(),
recipients: z.array(ZCreateRecipientSchema).refine((recipients) => {
const emails = recipients.map((recipient) => recipient.email.toLowerCase());
return new Set(emails).size === emails.length;
}),
});
export const ZUpdateDocumentRecipientRequestSchema = z.object({
documentId: z.number(),
recipient: ZUpdateRecipientSchema,
});
export const ZUpdateDocumentRecipientResponseSchema = ZRecipientResponseSchema;
export const ZUpdateDocumentRecipientsRequestSchema = z.object({
documentId: z.number(),
recipients: z.array(ZUpdateRecipientSchema).refine((recipients) => {
const emails = recipients
.filter((recipient) => recipient.email !== undefined)
.map((recipient) => recipient.email?.toLowerCase());
return new Set(emails).size === emails.length;
}),
});
export const ZUpdateDocumentRecipientsResponseSchema = z.object({
recipients: z.array(ZRecipientResponseSchema),
});
export const ZDeleteDocumentRecipientRequestSchema = z.object({
recipientId: z.number(),
});
export const ZSetDocumentRecipientsRequestSchema = z
.object({
documentId: z.number(),
teamId: z.number().optional(),
signers: z.array(
recipients: z.array(
z.object({
nativeId: z.number().optional(),
email: z.string().email().min(1),
email: z.string().toLowerCase().email().min(1),
name: z.string(),
role: z.nativeEnum(RecipientRole),
signingOrder: z.number().optional(),
@ -28,7 +118,7 @@ export const ZAddSignersMutationSchema = z
})
.refine(
(schema) => {
const emails = schema.signers.map((signer) => signer.email.toLowerCase());
const emails = schema.recipients.map((recipient) => recipient.email.toLowerCase());
return new Set(emails).size === emails.length;
},
@ -36,16 +126,59 @@ export const ZAddSignersMutationSchema = z
{ message: 'Signers must have unique emails', path: ['signers__root'] },
);
export type TAddSignersMutationSchema = z.infer<typeof ZAddSignersMutationSchema>;
export const ZCreateTemplateRecipientRequestSchema = z.object({
templateId: z.number(),
recipient: ZCreateRecipientSchema,
});
export const ZAddTemplateSignersMutationSchema = z
export const ZCreateTemplateRecipientResponseSchema = ZRecipientBaseResponseSchema;
export const ZCreateTemplateRecipientsRequestSchema = z.object({
templateId: z.number(),
recipients: z.array(ZCreateRecipientSchema).refine((recipients) => {
const emails = recipients.map((recipient) => recipient.email);
return new Set(emails).size === emails.length;
}),
});
export const ZUpdateTemplateRecipientRequestSchema = z.object({
templateId: z.number(),
recipient: ZUpdateRecipientSchema,
});
export const ZUpdateTemplateRecipientResponseSchema = ZRecipientResponseSchema;
export const ZUpdateTemplateRecipientsRequestSchema = z.object({
templateId: z.number(),
recipients: z.array(ZUpdateRecipientSchema).refine((recipients) => {
const emails = recipients
.filter((recipient) => recipient.email !== undefined)
.map((recipient) => recipient.email);
return new Set(emails).size === emails.length;
}),
});
export const ZUpdateTemplateRecipientsResponseSchema = z.object({
recipients: z.array(ZRecipientResponseSchema).refine((recipients) => {
const emails = recipients.map((recipient) => recipient.email);
return new Set(emails).size === emails.length;
}),
});
export const ZDeleteTemplateRecipientRequestSchema = z.object({
recipientId: z.number(),
});
export const ZSetTemplateRecipientsRequestSchema = z
.object({
teamId: z.number().optional(),
templateId: z.number(),
signers: z.array(
recipients: z.array(
z.object({
nativeId: z.number().optional(),
email: z.string().email().min(1),
email: z.string().toLowerCase().email().min(1),
name: z.string(),
role: z.nativeEnum(RecipientRole),
signingOrder: z.number().optional(),
@ -55,16 +188,14 @@ export const ZAddTemplateSignersMutationSchema = z
})
.refine(
(schema) => {
const emails = schema.signers.map((signer) => signer.email.toLowerCase());
const emails = schema.recipients.map((recipient) => recipient.email);
return new Set(emails).size === emails.length;
},
// Dirty hack to handle errors when .root is populated for an array type
{ message: 'Signers must have unique emails', path: ['signers__root'] },
{ message: 'Recipients must have unique emails', path: ['recipients__root'] },
);
export type TAddTemplateSignersMutationSchema = z.infer<typeof ZAddTemplateSignersMutationSchema>;
export const ZCompleteDocumentWithTokenMutationSchema = z.object({
token: z.string(),
documentId: z.number(),
@ -85,3 +216,32 @@ export const ZRejectDocumentWithTokenMutationSchema = z.object({
export type TRejectDocumentWithTokenMutationSchema = z.infer<
typeof ZRejectDocumentWithTokenMutationSchema
>;
/**
* Legacy schema. Remove after deployment (when addSigners trpc is removed).
*
* @deprecated
*/
export const ZAddSignersMutationSchema = z
.object({
documentId: z.number(),
signers: z.array(
z.object({
nativeId: z.number().optional(),
email: z.string().toLowerCase().email().min(1),
name: z.string(),
role: z.nativeEnum(RecipientRole),
signingOrder: z.number().optional(),
actionAuth: ZRecipientActionAuthTypesSchema.optional().nullable(),
}),
),
})
.refine(
(schema) => {
const emails = schema.signers.map((signer) => signer.email.toLowerCase());
return new Set(emails).size === emails.length;
},
// Dirty hack to handle errors when .root is populated for an array type
{ message: 'Signers must have unique emails', path: ['signers__root'] },
);