feat(plugins): add DocuSign eSignature integration plugin

packages/corsair/core/constants.ts

@@ -101,6 +101,7 @@ export const BaseProviders = [
 	'digitalocean',
 	'discord',
 	'dockerhub',
+	'docusign',
 	'dodopayments',
 	'doppler',
 	'dropbox',
@@ -296,6 +297,7 @@ export const ProviderDisplayNames = {
 	digitalocean: 'DigitalOcean',
 	discord: 'Discord',
 	dockerhub: 'Docker Hub',
+	docusign: 'Docusign',
 	dodopayments: 'Dodo Payments',
 	doppler: 'Doppler',
 	dropbox: 'Dropbox',
@@ -498,6 +500,7 @@ export type AllProviders =
 	| 'digitalocean'
 	| 'discord'
 	| 'dockerhub'
+	| 'docusign'
 	| 'dodopayments'
 	| 'doppler'
 	| 'dropbox'

packages/docusign/client.ts

@@ -0,0 +1,38 @@
+export interface DocusignAuthOptions {
+	accessToken: string;
+	accountId: string;
+	baseUri?: string;
+}
+
+export class DocusignClient {
+	public baseUri: string;
+	public accountId: string;
+	private token: string;
+
+	constructor(options: DocusignAuthOptions) {
+		this.accountId = options.accountId;
+		this.token = options.accessToken;
+		const root = options.baseUri || 'https://demo.docusign.net/restapi';
+		this.baseUri = `${root.replace(/\/+$/, '')}/v2.1/accounts/${this.accountId}`;
+	}
+
+	async request<T = any>(endpoint: string, options: RequestInit = {}): Promise<T> {
+		const url = `${this.baseUri}${endpoint.startsWith('/') ? endpoint : `/${endpoint}`}`;
+		const response = await fetch(url, {
+			...options,
+			headers: {
+				Authorization: `Bearer ${this.token}`,
+				'Content-Type': 'application/json',
+				Accept: 'application/json',
+				...options.headers,
+			},
+		});
+
+		if (!response.ok) {
+			const errorText = await response.text();
+			throw new Error(`DocuSign API Error (${response.status}): ${errorText}`);
+		}
+
+		return response.json() as Promise<T>;
+	}
+}

packages/docusign/endpoints/envelopes.ts

@@ -0,0 +1,68 @@
+import { DocusignClient } from '../client';
+
+export interface CreateEnvelopeParams {
+    templateId?: string;
+    emailSubject: string;
+    status: 'sent' | 'created';
+    templateRoles?: Array<{
+        email: string;
+        name: string;
+        roleName: string;
+    }>;
+    documents?: Array<{
+        documentId: string;
+        name: string;
+        fileExtension?: string;
+        documentBase64?: string;
+    }>;
+    recipients?: {
+        signers?: Array<{
+            email: string;
+            name: string;
+            recipientId: string;
+            routingOrder?: string;
+        }>;
+    };
+}
+
+export const createEnvelope = async (client: DocusignClient, params: CreateEnvelopeParams) => {
+    return client.request('/envelopes', {
+        method: 'POST',
+        body: JSON.stringify(params),
+    });
+};
+
+export const getEnvelope = async (client: DocusignClient, { envelopeId }: { envelopeId: string }) => {
+    return client.request(`/envelopes/${envelopeId}`);
+};
+
+export const sendEnvelope = async (client: DocusignClient, { envelopeId }: { envelopeId: string }) => {
+    return client.request(`/envelopes/${envelopeId}`, {
+        method: 'PUT',
+        body: JSON.stringify({ status: 'sent' }),
+    });
+};
+
+export const createRecipientViewUrl = async (
+    client: DocusignClient,
+    {
+        envelopeId,
+        ...params
+    }: {
+        envelopeId: string;
+        userName: string;
+        email: string;
+        returnUrl: string;
+        authenticationMethod?: string;
+        recipientId?: string;
+    }
+) => {
+    return client.request(`/envelopes/${envelopeId}/views/recipient`, {
+        method: 'POST',
+        body: JSON.stringify({
+            authenticationMethod: 'none',
+            recipientId: '1',
+            ...params,
+        }),
+    });
+};

packages/docusign/endpoints/index.ts

@@ -0,0 +1,34 @@
+import { DocusignClient } from '../client';
+import type { CreateEnvelopeParams, GetEnvelopeParams, ListTemplatesParams } from './types';
+
+export const createEnvelope = async (client: DocusignClient, params: CreateEnvelopeParams) => {
+	return client.request('/envelopes', {
+		method: 'POST',
+		body: JSON.stringify(params),
+	});
+};
+
+export const getEnvelope = async (client: DocusignClient, params: GetEnvelopeParams) => {
+	return client.request(`/envelopes/${params.envelopeId}`);
+};
+
+export const sendEnvelope = async (client: DocusignClient, params: GetEnvelopeParams) => {
+	return client.request(`/envelopes/${params.envelopeId}`, {
+		method: 'PUT',
+		body: JSON.stringify({ status: 'sent' }),
+	});
+};
+
+export const listTemplates = async (client: DocusignClient, params?: ListTemplatesParams) => {
+	const query = new URLSearchParams();
+	if (params?.count) query.append('count', String(params.count));
+	if (params?.startPosition) query.append('start_position', String(params.startPosition));
+	const qs = query.toString() ? `?${query.toString()}` : '';
+	return client.request(`/templates${qs}`);
+};
+
+export const getTemplate = async (client: DocusignClient, params: { templateId: string }) => {
+	return client.request(`/templates/${params.templateId}`);
+};
+
+export * from './types';

packages/docusign/endpoints/templates.ts

@@ -0,0 +1,16 @@
+import { DocusignClient } from '../client';
+
+export const listTemplates = async (
+    client: DocusignClient,
+    params?: { count?: number; startPosition?: number }
+) => {
+    const query = new URLSearchParams();
+    if (params?.count) query.append('count', String(params.count));
+    if (params?.startPosition) query.append('start_position', String(params.startPosition));
+    const qs = query.toString() ? `?${query.toString()}` : '';
+    return client.request(`/templates${qs}`);
+};
+
+export const getTemplate = async (client: DocusignClient, { templateId }: { templateId: string }) => {
+    return client.request(`/templates/${templateId}`);
+};

packages/docusign/endpoints/types.ts

@@ -0,0 +1,19 @@
+export interface CreateEnvelopeParams {
+	templateId?: string;
+	emailSubject: string;
+	status: 'sent' | 'created';
+	templateRoles?: Array<{
+		email: string;
+		name: string;
+		roleName: string;
+	}>;
+}
+
+export interface GetEnvelopeParams {
+	envelopeId: string;
+}
+
+export interface ListTemplatesParams {
+	count?: number;
+	startPosition?: number;
+}

packages/docusign/error-handlers.ts

@@ -0,0 +1,31 @@
+import { ApiError } from 'corsair/http';
+import type { CorsairErrorHandler } from 'corsair/core';
+
+export const errorHandlers = {
+	RATE_LIMIT_ERROR: {
+		match: (error: Error) => {
+			if (error instanceof ApiError && error.status === 429) return true;
+			const msg = error.message.toLowerCase();
+			return msg.includes('rate_limited') || msg.includes('429');
+		},
+		handler: async (error: Error) => {
+			let retryAfterMs: number | undefined;
+			if (error instanceof ApiError && error.retryAfter !== undefined) {
+				retryAfterMs = error.retryAfter;
+			}
+			return { maxRetries: 5, headersRetryAfterMs: retryAfterMs };
+		},
+	},
+	AUTH_ERROR: {
+		match: (error: Error) => {
+			if (error instanceof ApiError && error.status === 401) return true;
+			const msg = error.message.toLowerCase();
+			return msg.includes('unauthorized') || msg.includes('invalid_auth');
+		},
+		handler: async () => ({ maxRetries: 0 }),
+	},
+	DEFAULT: {
+		match: () => true,
+		handler: async () => ({ maxRetries: 0 }),
+	},
+} satisfies CorsairErrorHandler;

packages/docusign/index.ts

@@ -0,0 +1,56 @@
+import { DocusignClient, type DocusignAuthOptions } from './client';
+import * as endpoints from './endpoints';
+import * as schema from './schema';
+import * as webhooks from './webhooks';
+
+export * from './client';
+export * from './endpoints';
+export * from './schema';
+export * from './webhooks';
+
+export const docusignEndpointsNested = {
+	createEnvelope: endpoints.createEnvelope,
+	getEnvelope: endpoints.getEnvelope,
+	sendEnvelope: endpoints.sendEnvelope,
+	listTemplates: endpoints.listTemplates,
+	getTemplate: endpoints.getTemplate,
+};
+
+export const docusignWebhooksNested = {
+	handleWebhook: webhooks.handleWebhook,
+};
+
+export const docusignEndpointMeta = {
+	createEnvelope: {
+		description: 'Creates a signing envelope from a pre-existing DocuSign template.',
+	},
+	getEnvelope: {
+		description: 'Gets the status and basic information about an envelope from DocuSign.',
+	},
+	sendEnvelope: {
+		description: 'Sends a draft envelope by updating its status to sent.',
+	},
+	listTemplates: {
+		description: 'Gets the definition of templates in the specified account.',
+	},
+	getTemplate: {
+		description: 'Gets a template definition from the specified account.',
+	},
+};
+
+export const docusignPlugin = {
+	id: 'docusign',
+	name: 'DocuSign',
+	description: 'DocuSign eSignature REST API integration for agreements, envelopes, and templates.',
+	auth: {
+		type: 'oauth2' as const,
+		fields: ['accessToken', 'accountId', 'baseUri'],
+	},
+	createClient: (options: DocusignAuthOptions) => new DocusignClient(options),
+	endpoints: docusignEndpointsNested,
+	webhooks: docusignWebhooksNested,
+	endpointMeta: docusignEndpointMeta,
+	schema,
+};
+
+export default docusignPlugin;

packages/docusign/jest.config.cjs

@@ -0,0 +1,55 @@
+module.exports = {
+	preset: 'ts-jest',
+	testEnvironment: 'node',
+	roots: ['<rootDir>'],
+	testMatch: [
+		'**/*.test.ts',
+		'**/tests/**/*.test.ts',
+		'**/plugins/**/*.test.ts',
+		'**/setup/**/*.test.ts',
+	],
+	collectCoverageFrom: [
+		'**/*.ts',
+		'!**/*.d.ts',
+		'!**/node_modules/**',
+		'!**/dist/**',
+		'!jest.config.ts',
+		'!tests/**',
+	],
+	moduleFileExtensions: ['ts', 'tsx', 'js', 'jsx', 'json'],
+	transform: {
+		'^.+\\.yaml$': '<rootDir>/../corsair/jest-yaml-transform.cjs',
+		'^.+\\.ts$': [
+			'ts-jest',
+			{
+				useESM: true,
+				tsconfig: {
+					esModuleInterop: true,
+					allowSyntheticDefaultImports: true,
+					verbatimModuleSyntax: false,
+					module: 'ESNext',
+					moduleResolution: 'Bundler',
+				},
+			},
+		],
+		'.*\\.js$': [
+			'ts-jest',
+			{
+				useESM: true,
+				tsconfig: {
+					esModuleInterop: true,
+					allowSyntheticDefaultImports: true,
+				},
+			},
+		],
+	},
+	moduleNameMapper: {
+		'^corsair/core$': '<rootDir>/../corsair/core.ts',
+		'^corsair/http$': '<rootDir>/../corsair/http.ts',
+		'^(\\.\\.?/.*)\\.js$': '$1',
+	},
+	transformIgnorePatterns: ['node_modules/(?!.*uuid.*)'],
+	extensionsToTreatAsEsm: ['.ts'],
+	testTimeout: 30000,
+	verbose: true,
+};