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,74 @@
+export interface DocusignAuthOptions {
+	accessToken: string;
+	accountId: string;
+	baseUri?: string;
+}
+
+export class DocusignClient {
+	private accessToken: string;
+	private accountId: string;
+	private baseUri: string;
+
+	constructor(options: DocusignAuthOptions) {
+		this.accessToken = options.accessToken;
+		this.accountId = options.accountId;
+		this.baseUri = this.resolveAndValidateBaseUri(options.baseUri);
+	}
+
+	private resolveAndValidateBaseUri(baseUri?: string): string {
+		const raw = baseUri || 'https://demo.docusign.net/restapi/v2.1';
+		const url = new URL(raw.startsWith('http') ? raw : `https://${raw}`);
+
+		if (url.protocol !== 'https:') {
+			throw new Error('DocuSign baseUri must use HTTPS.');
+		}
+
+		const host = url.hostname.toLowerCase();
+		const isAllowedHost =
+			host === 'docusign.com' ||
+			host.endsWith('.docusign.com') ||
+			host === 'docusign.net' ||
+			host.endsWith('.docusign.net');
+
+		if (!isAllowedHost) {
+			throw new Error(
+				`Untrusted DocuSign baseUri host: "${host}". Must be a valid *.docusign.com or *.docusign.net domain.`,
+			);
+		}
+
+		let path = url.pathname.replace(/\/+$/, '');
+		if (!path.includes('/restapi/v2.1')) {
+			path = `${path}/restapi/v2.1`;
+		}
+		if (!path.includes(`/accounts/${this.accountId}`)) {
+			path = `${path}/accounts/${this.accountId}`;
+		}
+
+		return `${url.origin}${path}`;
+	}
+
+	async request<T = unknown>(
+		endpoint: string,
+		options: RequestInit = {},
+	): Promise<T> {
+		const path = endpoint.startsWith('/') ? endpoint : `/${endpoint}`;
+		const url = `${this.baseUri}${path}`;
+
+		const response = await fetch(url, {
+			...options,
+			headers: {
+				Authorization: `Bearer ${this.accessToken}`,
+				'Content-Type': 'application/json',
+				Accept: 'application/json',
+				...options.headers,
+			},
+		});
+
+		if (!response.ok) {
+			const errorBody = await response.text();
+			throw new Error(`DocuSign API error (${response.status}): ${errorBody}`);
+		}
+
+		return response.json() as Promise<T>;
+	}
+}

packages/docusign/endpoints/envelopes.ts

@@ -0,0 +1,91 @@
+import { DocusignClient } from '../client';
+import type {
+	CreateEnvelopeParams,
+	CreateRecipientViewUrlParams,
+	DocusignExecutionContext,
+	GetEnvelopeParams,
+	SendEnvelopeParams,
+} from './types';
+
+function resolveClient(
+	contextOrClient: DocusignExecutionContext | unknown,
+): DocusignClient {
+	if (contextOrClient instanceof DocusignClient) {
+		return contextOrClient;
+	}
+	if (
+		contextOrClient &&
+		typeof contextOrClient === 'object' &&
+		'client' in contextOrClient &&
+		(contextOrClient as { client: unknown }).client
+	) {
+		const candidate = (contextOrClient as { client: unknown }).client;
+		if (
+			candidate instanceof DocusignClient ||
+			typeof (candidate as { request?: unknown }).request === 'function'
+		) {
+			return candidate as DocusignClient;
+		}
+	}
+	if (
+		contextOrClient &&
+		typeof (contextOrClient as { request?: unknown }).request === 'function'
+	) {
+		return contextOrClient as DocusignClient;
+	}
+	throw new Error(
+		'Invalid execution context: DocuSign client is not initialized or accessible.',
+	);
+}
+
+export const createEnvelope = async (
+	ctxOrClient: DocusignExecutionContext,
+	params: CreateEnvelopeParams,
+) => {
+	const client = resolveClient(ctxOrClient);
+	return client.request('/envelopes', {
+		method: 'POST',
+		body: JSON.stringify(params),
+	});
+};
+
+export const getEnvelope = async (
+	ctxOrClient: DocusignExecutionContext,
+	params: GetEnvelopeParams,
+) => {
+	const client = resolveClient(ctxOrClient);
+	return client.request(`/envelopes/${params.envelopeId}`);
+};
+
+export const sendEnvelope = async (
+	ctxOrClient: DocusignExecutionContext,
+	params: SendEnvelopeParams,
+) => {
+	const client = resolveClient(ctxOrClient);
+	return client.request(`/envelopes/${params.envelopeId}`, {
+		method: 'PUT',
+		body: JSON.stringify({ status: 'sent' }),
+	});
+};
+
+export const createRecipientViewUrl = async (
+	ctxOrClient: DocusignExecutionContext,
+	params: CreateRecipientViewUrlParams,
+) => {
+	const client = resolveClient(ctxOrClient);
+	const {
+		envelopeId,
+		authenticationMethod = 'none',
+		recipientId = '1',
+		...rest
+	} = params;
+
+	return client.request(`/envelopes/${envelopeId}/views/recipient`, {
+		method: 'POST',
+		body: JSON.stringify({
+			authenticationMethod,
+			recipientId,
+			...rest,
+		}),
+	});
+};

packages/docusign/endpoints/index.ts

@@ -0,0 +1,78 @@
+import type { DocusignClient } from '../client';
+import type {
+	CreateEnvelopeParams,
+	CreateRecipientViewUrlParams,
+	GetEnvelopeParams,
+	GetTemplateParams,
+	ListTemplatesParams,
+	SendEnvelopeParams,
+} 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: SendEnvelopeParams,
+) => {
+	return client.request(`/envelopes/${params.envelopeId}`, {
+		method: 'PUT',
+		body: JSON.stringify({ status: 'sent' }),
+	});
+};
+
+export const createRecipientViewUrl = async (
+	client: DocusignClient,
+	params: CreateRecipientViewUrlParams,
+) => {
+	const {
+		envelopeId,
+		authenticationMethod = 'none',
+		recipientId = '1',
+		...rest
+	} = params;
+
+	return client.request(`/envelopes/${envelopeId}/views/recipient`, {
+		method: 'POST',
+		body: JSON.stringify({
+			authenticationMethod,
+			recipientId,
+			...rest,
+		}),
+	});
+};
+
+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: GetTemplateParams,
+) => {
+	return client.request(`/templates/${params.templateId}`);
+};
+
+export * from './types';

packages/docusign/endpoints/templates.ts

@@ -0,0 +1,58 @@
+import { DocusignClient } from '../client';
+import type {
+	DocusignExecutionContext,
+	GetTemplateParams,
+	ListTemplatesParams,
+} from './types';
+
+function resolveClient(
+	contextOrClient: DocusignExecutionContext | unknown,
+): DocusignClient {
+	if (contextOrClient instanceof DocusignClient) {
+		return contextOrClient;
+	}
+	if (
+		contextOrClient &&
+		typeof contextOrClient === 'object' &&
+		'client' in contextOrClient &&
+		(contextOrClient as { client: unknown }).client
+	) {
+		const candidate = (contextOrClient as { client: unknown }).client;
+		if (
+			candidate instanceof DocusignClient ||
+			typeof (candidate as { request?: unknown }).request === 'function'
+		) {
+			return candidate as DocusignClient;
+		}
+	}
+	if (
+		contextOrClient &&
+		typeof (contextOrClient as { request?: unknown }).request === 'function'
+	) {
+		return contextOrClient as DocusignClient;
+	}
+	throw new Error(
+		'Invalid execution context: DocuSign client is not initialized or accessible.',
+	);
+}
+
+export const listTemplates = async (
+	ctxOrClient: DocusignExecutionContext,
+	params?: ListTemplatesParams,
+) => {
+	const client = resolveClient(ctxOrClient);
+	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 (
+	ctxOrClient: DocusignExecutionContext,
+	params: GetTemplateParams,
+) => {
+	const client = resolveClient(ctxOrClient);
+	return client.request(`/templates/${params.templateId}`);
+};