From 6ace46fefd46abf49c206b1217a4ec4d4acf41d2 Mon Sep 17 00:00:00 2001
From: ephraimduncan <ephraimduncan68@gmail.com>
Date: Thu, 30 Jul 2026 21:37:26 +0000
Subject: [PATCH] docs(trpc): add openapi descriptions to envelope cancel,
 delete and update routes

- these routes rendered without descriptions in the generated API reference
- add route-level descriptions and field-level .describe() calls matching sibling schemas
---
 .../envelope-router/cancel-envelope.types.ts  |  5 +++--
 .../envelope-router/delete-envelope.types.ts  |  3 ++-
 .../envelope-router/update-envelope.types.ts  | 20 +++++++++++++------
 3 files changed, 19 insertions(+), 9 deletions(-)

diff --git a/packages/trpc/server/envelope-router/cancel-envelope.types.ts b/packages/trpc/server/envelope-router/cancel-envelope.types.ts
index 06a6637fb..59ab827c1 100644
--- a/packages/trpc/server/envelope-router/cancel-envelope.types.ts
+++ b/packages/trpc/server/envelope-router/cancel-envelope.types.ts
@@ -8,13 +8,14 @@ export const cancelEnvelopeMeta: TrpcRouteMeta = {
     method: 'POST',
     path: '/envelope/cancel',
     summary: 'Cancel envelope',
+    description: 'Cancel a pending envelope',
     tags: ['Envelope'],
   },
 };
 
 export const ZCancelEnvelopeRequestSchema = z.object({
-  envelopeId: z.string(),
-  reason: z.string().optional(),
+  envelopeId: z.string().describe('The ID of the envelope to cancel.'),
+  reason: z.string().describe('The reason for cancelling the envelope.').optional(),
 });
 
 export const ZCancelEnvelopeResponseSchema = ZSuccessResponseSchema;
diff --git a/packages/trpc/server/envelope-router/delete-envelope.types.ts b/packages/trpc/server/envelope-router/delete-envelope.types.ts
index 654d24c6d..8eaf7db9e 100644
--- a/packages/trpc/server/envelope-router/delete-envelope.types.ts
+++ b/packages/trpc/server/envelope-router/delete-envelope.types.ts
@@ -8,12 +8,13 @@ export const deleteEnvelopeMeta: TrpcRouteMeta = {
     method: 'POST',
     path: '/envelope/delete',
     summary: 'Delete envelope',
+    description: 'Delete an envelope',
     tags: ['Envelope'],
   },
 };
 
 export const ZDeleteEnvelopeRequestSchema = z.object({
-  envelopeId: z.string(),
+  envelopeId: z.string().describe('The ID of the envelope to delete.'),
 });
 
 export const ZDeleteEnvelopeResponseSchema = ZSuccessResponseSchema;
diff --git a/packages/trpc/server/envelope-router/update-envelope.types.ts b/packages/trpc/server/envelope-router/update-envelope.types.ts
index c08da086f..a4a89f9ea 100644
--- a/packages/trpc/server/envelope-router/update-envelope.types.ts
+++ b/packages/trpc/server/envelope-router/update-envelope.types.ts
@@ -12,24 +12,32 @@ export const updateEnvelopeMeta: TrpcRouteMeta = {
     method: 'POST',
     path: '/envelope/update',
     summary: 'Update envelope',
+    description: 'Update envelope properties and settings',
     tags: ['Envelope'],
   },
 };
 
 export const ZUpdateEnvelopeRequestSchema = z.object({
-  envelopeId: z.string(),
+  envelopeId: z.string().describe('The ID of the envelope to update.'),
   data: z
     .object({
       title: ZDocumentTitleSchema.optional(),
       externalId: ZDocumentExternalIdSchema.nullish(),
       visibility: ZDocumentVisibilitySchema.optional(),
-      globalAccessAuth: z.array(ZDocumentAccessAuthTypesSchema).optional(),
-      globalActionAuth: z.array(ZDocumentActionAuthTypesSchema).optional(),
-      folderId: z.string().nullish(),
-      templateType: z.nativeEnum(TemplateType).optional(),
+      globalAccessAuth: z
+        .array(ZDocumentAccessAuthTypesSchema)
+        .describe('The authentication methods required to access the envelope.')
+        .optional(),
+      globalActionAuth: z
+        .array(ZDocumentActionAuthTypesSchema)
+        .describe('The authentication methods required to sign the envelope.')
+        .optional(),
+      folderId: z.string().describe('The ID of the folder containing the envelope.').nullish(),
+      templateType: z.nativeEnum(TemplateType).describe('The template type.').optional(),
     })
+    .describe('The envelope properties to update.')
     .optional(),
-  meta: ZDocumentMetaUpdateSchema.optional(),
+  meta: ZDocumentMetaUpdateSchema.describe('The email and signing settings to update.').optional(),
 });
 
 export const ZUpdateEnvelopeResponseSchema = ZEnvelopeLiteSchema;