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,48 @@
+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;
+
+		let root = options.baseUri?.trim() || 'https://demo.docusign.net/restapi';
+		while (root.endsWith('/')) {
+			root = root.slice(0, -1);
+		}
+
+		this.baseUri = `${root}/v2.1/accounts/${this.accountId}`;
+	}
+
+	async request<T = any>(
+		endpoint: string,
+		options: RequestInit = {},
+	): Promise<T> {
+		const cleanPath = endpoint.startsWith('/') ? endpoint : `/${endpoint}`;
+		const url = `${this.baseUri}${cleanPath}`;
+
+		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,77 @@
+import type { 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,54 @@
+import type { 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,20 @@
+import type { 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 type { CorsairErrorHandler } from 'corsair/core';
+import { ApiError } from 'corsair/http';
+
+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,66 @@
+import type { DocusignAuthOptions } from './client';
+import { DocusignClient } 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,
+};
+
+// Plugin factory function for corsair.ts plugins list
+export const docusign = (config?: any) => ({
+	...docusignPlugin,
+	...(config && { config }),
+});
+
+export default docusign;