chore: add v1 API deprecation callouts and clean up imports

Add deprecation warning callouts to public API documentation pages.
Remove unused imports from webhook router and hooks.

.agents/scratches/v1-api-legacy-deprecation-spec.md

@@ -0,0 +1,103 @@
+# V1 API Legacy Deprecation Specification
+
+## Overview
+
+Mark all V1 API endpoints as legacy/deprecated in the OpenAPI documentation to signal that users should migrate to the V2 API.
+
+## Decision Summary
+
+| Decision | Choice |
+|----------|--------|
+| Deprecation Scope | All V1 endpoints |
+| Message Style | Generic for all endpoints |
+| Sunset Timeline | No specific date |
+| V2 API Status | V2 exists now |
+| OpenAPI Info | Update to include deprecation notice |
+
+## Implementation Details
+
+### Files to Modify
+
+1. `packages/api/v1/contract.ts` - Add `deprecated: true` and `description` to all endpoints
+2. `packages/api/v1/openapi.ts` - Update the OpenAPI info description
+
+### Documentation Files to Modify
+
+1. `apps/documentation/pages/developers/public-api/index.mdx` - Add deprecation `<Callout type="warning">` under "API V1 - Deprecated" section:
+   ```
+   <Callout type="warning">
+     V1 API is deprecated and will be removed in a future release. Please migrate to V2.
+   </Callout>
+   ```
+
+2. `apps/documentation/pages/developers/public-api/versioning.mdx` - Add callout after "current version is v2" stating V1 is deprecated:
+   ```
+   <Callout type="warning">
+     V1 API is deprecated. Please migrate to V2.
+   </Callout>
+   ```
+
+### Deprecation Message
+
+**Per-endpoint message:**
+```
+Deprecated. Please migrate to the V2 API.
+```
+
+**OpenAPI info description:**
+```
+[DEPRECATED] The Documenso API for retrieving, creating, updating and deleting documents. Please migrate to V2.
+```
+
+### Endpoints to Update (19 total)
+
+| Endpoint | Method | Path | Action |
+|----------|--------|------|--------|
+| getDocuments | GET | /api/v1/documents | Add deprecation |
+| getDocument | GET | /api/v1/documents/:id | Add deprecation |
+| downloadSignedDocument | GET | /api/v1/documents/:id/download | Add deprecation |
+| createDocument | POST | /api/v1/documents | Add deprecation |
+| createTemplate | POST | /api/v1/templates | Add deprecation |
+| deleteTemplate | DELETE | /api/v1/templates/:id | Add deprecation |
+| getTemplate | GET | /api/v1/templates/:id | Add deprecation |
+| getTemplates | GET | /api/v1/templates | Add deprecation |
+| createDocumentFromTemplate | POST | /api/v1/templates/:templateId/create-document | Update existing deprecation message |
+| generateDocumentFromTemplate | POST | /api/v1/templates/:templateId/generate-document | Add deprecation |
+| sendDocument | POST | /api/v1/documents/:id/send | Add deprecation |
+| resendDocument | POST | /api/v1/documents/:id/resend | Add deprecation |
+| deleteDocument | DELETE | /api/v1/documents/:id | Add deprecation |
+| createRecipient | POST | /api/v1/documents/:id/recipients | Add deprecation |
+| updateRecipient | PATCH | /api/v1/documents/:id/recipients/:recipientId | Add deprecation |
+| deleteRecipient | DELETE | /api/v1/documents/:id/recipients/:recipientId | Add deprecation |
+| createField | POST | /api/v1/documents/:id/fields | Add deprecation |
+| updateField | PATCH | /api/v1/documents/:id/fields/:fieldId | Add deprecation |
+| deleteField | DELETE | /api/v1/documents/:id/fields/:fieldId | Add deprecation |
+
+## Changes Required
+
+### contract.ts Changes
+
+For each endpoint, add:
+```typescript
+deprecated: true,
+description: 'Deprecated. Please migrate to the V2 API.',
+```
+
+For endpoints that already have a description, prepend the deprecation notice.
+
+### openapi.ts Changes
+
+Update the info block description from:
+```typescript
+description: 'The Documenso API for retrieving, creating, updating and deleting documents.',
+```
+to:
+```typescript
+description: '[DEPRECATED] The Documenso API for retrieving, creating, updating and deleting documents. Please migrate to V2.',
+```
+
+## Notes
+
+- The `createDocumentFromTemplate` endpoint's existing deprecation message (pointing to `generateDocumentFromTemplate`) will be replaced with the generic V2 migration message
+- No sunset date is included - endpoints are marked deprecated but without a removal timeline
+- The V2 API is available and ready for users to migrate to

apps/documentation/pages/developers/public-api/index.mdx

@@ -31,6 +31,10 @@ Our new API V2 supports the following typed SDKs:
 
 ## API V1 - Deprecated
 
+<Callout type="warning">
+  v1 API is deprecated and will be removed in a future release. Please migrate to v2.
+</Callout>
+
 Check out the [API V1 documentation](https://app.documenso.com/api/v1/openapi) for details about the API endpoints, request parameters, response formats, and authentication methods.
 
 📖 [Documentation](https://documen.so/api-v2-docs)

apps/documentation/pages/developers/public-api/versioning.mdx

@@ -11,6 +11,8 @@ Documenso uses API versioning to manage changes to the public API. This allows u
 
 <Callout type="info">The current version of the API is `v2`.</Callout>
 
+<Callout type="warning">v1 API is deprecated. Please migrate to v2.</Callout>
+
 The API version is specified in the URL. For example, the base URL for the `v2` API is `https://app.documenso.com/api/v2`.
 
 We may make changes to the API without incrementing the version number. We will always try to avoid breaking changes, but in some cases, it may be necessary to make changes that are not backward compatible. In these cases, we will increment the version number and provide information about the changes in the release notes.

packages/api/v1/contract.ts

@@ -55,6 +55,8 @@ export const ApiContractV1 = c.router(
         404: ZUnsuccessfulResponseSchema,
       },
       summary: 'Get all documents',
+      deprecated: true,
+      description: 'Deprecated. Please migrate to the v2 API.',
     },
 
     getDocument: {
@@ -66,6 +68,8 @@ export const ApiContractV1 = c.router(
         404: ZUnsuccessfulResponseSchema,
       },
       summary: 'Get a single document',
+      deprecated: true,
+      description: 'Deprecated. Please migrate to the v2 API.',
     },
 
     downloadSignedDocument: {
@@ -78,6 +82,8 @@ export const ApiContractV1 = c.router(
         404: ZUnsuccessfulResponseSchema,
       },
       summary: 'Download a signed document when the storage transport is S3',
+      deprecated: true,
+      description: 'Deprecated. Please migrate to the v2 API.',
     },
 
     createDocument: {
@@ -90,6 +96,8 @@ export const ApiContractV1 = c.router(
         404: ZUnsuccessfulResponseSchema,
       },
       summary: 'Upload a new document and get a presigned URL',
+      deprecated: true,
+      description: 'Deprecated. Please migrate to the v2 API.',
     },
 
     createTemplate: {
@@ -102,6 +110,8 @@ export const ApiContractV1 = c.router(
         404: ZUnsuccessfulResponseSchema,
       },
       summary: 'Create a new template and get a presigned URL',
+      deprecated: true,
+      description: 'Deprecated. Please migrate to the v2 API.',
     },
 
     deleteTemplate: {
@@ -114,6 +124,8 @@ export const ApiContractV1 = c.router(
         404: ZUnsuccessfulResponseSchema,
       },
       summary: 'Delete a template',
+      deprecated: true,
+      description: 'Deprecated. Please migrate to the v2 API.',
     },
 
     getTemplate: {
@@ -125,6 +137,8 @@ export const ApiContractV1 = c.router(
         404: ZUnsuccessfulResponseSchema,
       },
       summary: 'Get a single template',
+      deprecated: true,
+      description: 'Deprecated. Please migrate to the v2 API.',
     },
 
     getTemplates: {
@@ -137,6 +151,8 @@ export const ApiContractV1 = c.router(
         404: ZUnsuccessfulResponseSchema,
       },
       summary: 'Get all templates',
+      deprecated: true,
+      description: 'Deprecated. Please migrate to the v2 API.',
     },
 
     createDocumentFromTemplate: {
@@ -150,7 +166,7 @@ export const ApiContractV1 = c.router(
       },
       summary: 'Create a new document from an existing template',
       deprecated: true,
-      description: `This has been deprecated in favour of "/api/v1/templates/:templateId/generate-document". You may face unpredictable behavior using this endpoint as it is no longer maintained.`,
+      description: 'Deprecated. Please migrate to the v2 API.',
     },
 
     generateDocumentFromTemplate: {
@@ -165,8 +181,9 @@ export const ApiContractV1 = c.router(
         500: ZUnsuccessfulResponseSchema,
       },
       summary: 'Create a new document from an existing template',
+      deprecated: true,
       description:
-        'Create a new document from an existing template. Passing in values for title and meta will override the original values defined in the template. If you do not pass in values for recipients, it will use the values defined in the template.',
+        'Deprecated. Please migrate to the v2 API.\n\nCreate a new document from an existing template. Passing in values for title and meta will override the original values defined in the template. If you do not pass in values for recipients, it will use the values defined in the template.',
     },
 
     sendDocument: {
@@ -181,9 +198,9 @@ export const ApiContractV1 = c.router(
         500: ZUnsuccessfulResponseSchema,
       },
       summary: 'Send a document for signing',
-      // I'm aware this should be in the variable itself, which it is, however it's difficult for users to find in our current UI.
+      deprecated: true,
       description:
-        'Notes\n\n`sendEmail` - Whether to send an email to the recipients asking them to action the document. If you disable this, you will need to manually distribute the document to the recipients using the generated signing links. Defaults to true',
+        'Deprecated. Please migrate to the v2 API.\n\nNotes\n\n`sendEmail` - Whether to send an email to the recipients asking them to action the document. If you disable this, you will need to manually distribute the document to the recipients using the generated signing links. Defaults to true',
     },
 
     resendDocument: {
@@ -198,6 +215,8 @@ export const ApiContractV1 = c.router(
         500: ZUnsuccessfulResponseSchema,
       },
       summary: 'Re-send a document for signing',
+      deprecated: true,
+      description: 'Deprecated. Please migrate to the v2 API.',
     },
 
     deleteDocument: {
@@ -210,6 +229,8 @@ export const ApiContractV1 = c.router(
         404: ZUnsuccessfulResponseSchema,
       },
       summary: 'Delete a document',
+      deprecated: true,
+      description: 'Deprecated. Please migrate to the v2 API.',
     },
 
     createRecipient: {
@@ -224,6 +245,8 @@ export const ApiContractV1 = c.router(
         500: ZUnsuccessfulResponseSchema,
       },
       summary: 'Create a recipient for a document',
+      deprecated: true,
+      description: 'Deprecated. Please migrate to the v2 API.',
     },
 
     updateRecipient: {
@@ -238,6 +261,8 @@ export const ApiContractV1 = c.router(
         500: ZUnsuccessfulResponseSchema,
       },
       summary: 'Update a recipient for a document',
+      deprecated: true,
+      description: 'Deprecated. Please migrate to the v2 API.',
     },
 
     deleteRecipient: {
@@ -252,6 +277,8 @@ export const ApiContractV1 = c.router(
         500: ZUnsuccessfulResponseSchema,
       },
       summary: 'Delete a recipient from a document',
+      deprecated: true,
+      description: 'Deprecated. Please migrate to the v2 API.',
     },
 
     createField: {
@@ -266,6 +293,8 @@ export const ApiContractV1 = c.router(
         500: ZUnsuccessfulResponseSchema,
       },
       summary: 'Create a field for a document',
+      deprecated: true,
+      description: 'Deprecated. Please migrate to the v2 API.',
     },
 
     updateField: {
@@ -280,6 +309,8 @@ export const ApiContractV1 = c.router(
         500: ZUnsuccessfulResponseSchema,
       },
       summary: 'Update a field for a document',
+      deprecated: true,
+      description: 'Deprecated. Please migrate to the v2 API.',
     },
 
     deleteField: {
@@ -294,6 +325,8 @@ export const ApiContractV1 = c.router(
         500: ZUnsuccessfulResponseSchema,
       },
       summary: 'Delete a field from a document',
+      deprecated: true,
+      description: 'Deprecated. Please migrate to the v2 API.',
     },
   },
   {

packages/api/v1/openapi.ts

@@ -11,7 +11,8 @@ export const OpenAPIV1 = Object.assign(
       info: {
         title: 'Documenso API',
         version: '1.0.0',
-        description: 'The Documenso API for retrieving, creating, updating and deleting documents.',
+        description:
+          '[DEPRECATED] The Documenso API for retrieving, creating, updating and deleting documents. Please migrate to the v2 API.',
       },
       servers: [
         {

packages/lib/client-only/hooks/use-element-scale-size.ts

@@ -1,5 +1,5 @@
 /* eslint-disable @typescript-eslint/consistent-type-assertions */
-import { RefObject, useEffect, useState } from 'react';
+import { useEffect, useState } from 'react';
 
 /**
  * Calculate the width and height of a text element.

packages/trpc/server/webhook-router/find-webhook-calls.ts

@@ -1,4 +1,4 @@
-import { Prisma, WebhookCallStatus, WebhookTriggerEvents } from '@prisma/client';
+import type { Prisma, WebhookCallStatus, WebhookTriggerEvents } from '@prisma/client';
 
 import { TEAM_MEMBER_ROLE_PERMISSIONS_MAP } from '@documenso/lib/constants/teams';
 import { AppError, AppErrorCode } from '@documenso/lib/errors/app-error';

packages/trpc/server/webhook-router/resend-webhook-call.ts

@@ -1,8 +1,7 @@
-import { Prisma, WebhookCallStatus, WebhookTriggerEvents } from '@prisma/client';
+import { Prisma, WebhookCallStatus } from '@prisma/client';
 
 import { TEAM_MEMBER_ROLE_PERMISSIONS_MAP } from '@documenso/lib/constants/teams';
 import { AppError, AppErrorCode } from '@documenso/lib/errors/app-error';
-import type { FindResultResponse } from '@documenso/lib/types/search-params';
 import { buildTeamWhereQuery } from '@documenso/lib/utils/teams';
 import { prisma } from '@documenso/prisma';
 

packages/trpc/server/webhook-router/resend-webhook-call.types.ts

@@ -1,4 +1,3 @@
-import { WebhookCallStatus, WebhookTriggerEvents } from '@prisma/client';
 import { z } from 'zod';
 
 import WebhookCallSchema from '@documenso/prisma/generated/zod/modelSchema/WebhookCallSchema';