@hasna/connectors 1.3.0 → 1.3.2

package/connectors/connect-yousign/node_modules/undici-types/websocket.d.ts

@@ -0,0 +1,186 @@
+/// <reference types="node" />
+
+import type { Blob } from 'node:buffer'
+import type { ReadableStream, WritableStream } from 'node:stream/web'
+import type { MessagePort } from 'node:worker_threads'
+import {
+  EventInit,
+  EventListenerOptions,
+  AddEventListenerOptions,
+  EventListenerOrEventListenerObject
+} from './patch'
+import Dispatcher from './dispatcher'
+import { HeadersInit } from './fetch'
+
+export type BinaryType = 'blob' | 'arraybuffer'
+
+interface WebSocketEventMap {
+  close: CloseEvent
+  error: ErrorEvent
+  message: MessageEvent
+  open: Event
+}
+
+interface WebSocket extends EventTarget {
+  binaryType: BinaryType
+
+  readonly bufferedAmount: number
+  readonly extensions: string
+
+  onclose: ((this: WebSocket, ev: WebSocketEventMap['close']) => any) | null
+  onerror: ((this: WebSocket, ev: WebSocketEventMap['error']) => any) | null
+  onmessage: ((this: WebSocket, ev: WebSocketEventMap['message']) => any) | null
+  onopen: ((this: WebSocket, ev: WebSocketEventMap['open']) => any) | null
+
+  readonly protocol: string
+  readonly readyState: number
+  readonly url: string
+
+  close(code?: number, reason?: string): void
+  send(data: string | ArrayBufferLike | Blob | ArrayBufferView): void
+
+  readonly CLOSED: number
+  readonly CLOSING: number
+  readonly CONNECTING: number
+  readonly OPEN: number
+
+  addEventListener<K extends keyof WebSocketEventMap>(
+    type: K,
+    listener: (this: WebSocket, ev: WebSocketEventMap[K]) => any,
+    options?: boolean | AddEventListenerOptions
+  ): void
+  addEventListener(
+    type: string,
+    listener: EventListenerOrEventListenerObject,
+    options?: boolean | AddEventListenerOptions
+  ): void
+  removeEventListener<K extends keyof WebSocketEventMap>(
+    type: K,
+    listener: (this: WebSocket, ev: WebSocketEventMap[K]) => any,
+    options?: boolean | EventListenerOptions
+  ): void
+  removeEventListener(
+    type: string,
+    listener: EventListenerOrEventListenerObject,
+    options?: boolean | EventListenerOptions
+  ): void
+}
+
+export declare const WebSocket: {
+  prototype: WebSocket
+  new (url: string | URL, protocols?: string | string[] | WebSocketInit): WebSocket
+  readonly CLOSED: number
+  readonly CLOSING: number
+  readonly CONNECTING: number
+  readonly OPEN: number
+}
+
+interface CloseEventInit extends EventInit {
+  code?: number
+  reason?: string
+  wasClean?: boolean
+}
+
+interface CloseEvent extends Event {
+  readonly code: number
+  readonly reason: string
+  readonly wasClean: boolean
+}
+
+export declare const CloseEvent: {
+  prototype: CloseEvent
+  new (type: string, eventInitDict?: CloseEventInit): CloseEvent
+}
+
+interface MessageEventInit<T = any> extends EventInit {
+  data?: T
+  lastEventId?: string
+  origin?: string
+  ports?: MessagePort[]
+  source?: MessagePort | null
+}
+
+interface MessageEvent<T = any> extends Event {
+  readonly data: T
+  readonly lastEventId: string
+  readonly origin: string
+  readonly ports: readonly MessagePort[]
+  readonly source: MessagePort | null
+  initMessageEvent(
+    type: string,
+    bubbles?: boolean,
+    cancelable?: boolean,
+    data?: any,
+    origin?: string,
+    lastEventId?: string,
+    source?: MessagePort | null,
+    ports?: MessagePort[]
+  ): void;
+}
+
+export declare const MessageEvent: {
+  prototype: MessageEvent
+  new<T>(type: string, eventInitDict?: MessageEventInit<T>): MessageEvent<T>
+}
+
+interface ErrorEventInit extends EventInit {
+  message?: string
+  filename?: string
+  lineno?: number
+  colno?: number
+  error?: any
+}
+
+interface ErrorEvent extends Event {
+  readonly message: string
+  readonly filename: string
+  readonly lineno: number
+  readonly colno: number
+  readonly error: Error
+}
+
+export declare const ErrorEvent: {
+  prototype: ErrorEvent
+  new (type: string, eventInitDict?: ErrorEventInit): ErrorEvent
+}
+
+interface WebSocketInit {
+  protocols?: string | string[],
+  dispatcher?: Dispatcher,
+  headers?: HeadersInit
+}
+
+interface WebSocketStreamOptions {
+  protocols?: string | string[]
+  signal?: AbortSignal
+}
+
+interface WebSocketCloseInfo {
+  closeCode: number
+  reason: string
+}
+
+interface WebSocketStream {
+  closed: Promise<WebSocketCloseInfo>
+  opened: Promise<{
+    extensions: string
+    protocol: string
+    readable: ReadableStream
+    writable: WritableStream
+  }>
+  url: string
+}
+
+export declare const WebSocketStream: {
+  prototype: WebSocketStream
+  new (url: string | URL, options?: WebSocketStreamOptions): WebSocketStream
+}
+
+interface WebSocketError extends Event, WebSocketCloseInfo {}
+
+export declare const WebSocketError: {
+  prototype: WebSocketError
+  new (type: string, init?: WebSocketCloseInfo): WebSocketError
+}
+
+export declare const ping: (ws: WebSocket, body?: Buffer) => void

package/connectors/connect-yousign/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@hasna/connect-yousign",
+  "version": "0.0.1",
+  "description": "Yousign connector - eIDAS-compliant electronic signature API (v3)",
+  "type": "module",
+  "bin": {
+    "connect-yousign": "./bin/index.js"
+  },
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "scripts": {
+    "build": "bun build ./src/index.ts --outdir ./dist --target bun && bun build ./src/cli/index.ts --outdir ./bin --target bun",
+    "dev": "bun run ./src/cli/index.ts",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "bun run build"
+  },
+  "keywords": [
+    "yousign",
+    "esignature",
+    "electronic-signature",
+    "eidas",
+    "signature-request",
+    "document-signing",
+    "connector",
+    "cli",
+    "typescript",
+    "bun"
+  ],
+  "author": "Hasna",
+  "license": "Apache-2.0",
+  "devDependencies": {
+    "@types/bun": "latest",
+    "typescript": "^5"
+  },
+  "dependencies": {
+    "commander": "^12.1.0",
+    "chalk": "^5.3.0"
+  },
+  "engines": {
+    "bun": ">=1.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hasna/open-connectors.git"
+  }
+}

package/connectors/connect-yousign/src/api/client.ts

@@ -0,0 +1,119 @@
+import type { YouSignConfig } from '../types';
+import { YouSignApiError } from '../types';
+
+const BASE_URLS = {
+  sandbox: 'https://api.sandbox.yousign.app/v3',
+  production: 'https://api.yousign.app/v3',
+};
+
+export interface RequestOptions {
+  method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+  params?: Record<string, string | number | boolean | undefined>;
+  body?: Record<string, unknown> | unknown[] | FormData;
+  headers?: Record<string, string>;
+}
+
+export class YouSignClient {
+  private readonly apiKey: string;
+  private readonly baseUrl: string;
+
+  constructor(config: YouSignConfig) {
+    if (!config.apiKey) {
+      throw new Error('Yousign API key is required');
+    }
+    this.apiKey = config.apiKey;
+    this.baseUrl = BASE_URLS[config.environment || 'sandbox'];
+  }
+
+  private buildUrl(path: string, params?: Record<string, string | number | boolean | undefined>): string {
+    const url = new URL(`${this.baseUrl}${path}`);
+    if (params) {
+      for (const [key, value] of Object.entries(params)) {
+        if (value !== undefined && value !== null && value !== '') {
+          url.searchParams.append(key, String(value));
+        }
+      }
+    }
+    return url.toString();
+  }
+
+  async request<T>(path: string, options: RequestOptions = {}): Promise<T> {
+    const { method = 'GET', params, body, headers = {} } = options;
+    const url = this.buildUrl(path, params);
+
+    const requestHeaders: Record<string, string> = {
+      'Authorization': `Bearer ${this.apiKey}`,
+      ...headers,
+    };
+
+    const isFormData = body instanceof FormData;
+    if (body && !isFormData && ['POST', 'PUT', 'PATCH'].includes(method)) {
+      requestHeaders['Content-Type'] = 'application/json';
+    }
+
+    requestHeaders['Accept'] = 'application/json';
+
+    const fetchOptions: RequestInit = {
+      method,
+      headers: requestHeaders,
+    };
+
+    if (body) {
+      if (isFormData) {
+        fetchOptions.body = body;
+      } else if (['POST', 'PUT', 'PATCH'].includes(method)) {
+        fetchOptions.body = JSON.stringify(body);
+      }
+    }
+
+    const response = await fetch(url, fetchOptions);
+
+    if (response.status === 204) {
+      return {} as T;
+    }
+
+    // For binary downloads (PDF, etc.)
+    const contentType = response.headers.get('content-type') || '';
+    if (contentType.includes('application/pdf') || contentType.includes('application/octet-stream')) {
+      if (!response.ok) {
+        const text = await response.text();
+        throw new YouSignApiError(response.status, response.statusText, text);
+      }
+      return response.arrayBuffer() as unknown as T;
+    }
+
+    let data: unknown;
+    const text = await response.text();
+    try {
+      data = text ? JSON.parse(text) : {};
+    } catch {
+      data = text;
+    }
+
+    if (!response.ok) {
+      throw new YouSignApiError(response.status, response.statusText, data);
+    }
+
+    return data as T;
+  }
+
+  async get<T>(path: string, params?: Record<string, string | number | boolean | undefined>): Promise<T> {
+    return this.request<T>(path, { params });
+  }
+
+  async post<T>(path: string, body?: Record<string, unknown> | unknown[] | FormData): Promise<T> {
+    return this.request<T>(path, { method: 'POST', body });
+  }
+
+  async patch<T>(path: string, body?: Record<string, unknown>): Promise<T> {
+    return this.request<T>(path, { method: 'PATCH', body });
+  }
+
+  async put<T>(path: string, body?: Record<string, unknown>): Promise<T> {
+    return this.request<T>(path, { method: 'PUT', body });
+  }
+
+  async delete<T>(path: string): Promise<T> {
+    return this.request<T>(path, { method: 'DELETE' });
+  }
+}

package/connectors/connect-yousign/src/api/index.ts

@@ -0,0 +1,221 @@
+import type {
+  YouSignConfig,
+  SignatureRequest,
+  CreateSignatureRequestOptions,
+  UpdateSignatureRequestOptions,
+  Document,
+  Signer,
+  AddSignerOptions,
+  Approver,
+  AddApproverOptions,
+  SignatureField,
+  CreateSignatureFieldOptions,
+  AuditTrail,
+  Webhook,
+  CreateWebhookOptions,
+  PaginatedResponse,
+} from '../types';
+import { YouSignClient } from './client';
+
+/**
+ * Yousign API v3 Client
+ * eIDAS-compliant electronic signature API
+ */
+export class YouSign {
+  private readonly client: YouSignClient;
+
+  constructor(config: YouSignConfig) {
+    this.client = new YouSignClient(config);
+  }
+
+  static fromEnv(): YouSign {
+    const apiKey = process.env.YOUSIGN_API_KEY;
+    if (!apiKey) {
+      throw new Error('YOUSIGN_API_KEY environment variable is required');
+    }
+    const environment = (process.env.YOUSIGN_ENV || 'sandbox') as 'sandbox' | 'production';
+    return new YouSign({ apiKey, environment });
+  }
+
+  // ============================================
+  // Signature Requests
+  // ============================================
+
+  async createSignatureRequest(options: CreateSignatureRequestOptions): Promise<SignatureRequest> {
+    return this.client.post<SignatureRequest>('/signature_requests', options as unknown as Record<string, unknown>);
+  }
+
+  async listSignatureRequests(options?: {
+    status?: string;
+    external_id?: string;
+    after?: string;
+    limit?: number;
+  }): Promise<PaginatedResponse<SignatureRequest>> {
+    return this.client.get<PaginatedResponse<SignatureRequest>>('/signature_requests', options as Record<string, string | number | boolean | undefined>);
+  }
+
+  async getSignatureRequest(id: string): Promise<SignatureRequest> {
+    return this.client.get<SignatureRequest>(`/signature_requests/${id}`);
+  }
+
+  async updateSignatureRequest(id: string, options: UpdateSignatureRequestOptions): Promise<SignatureRequest> {
+    return this.client.patch<SignatureRequest>(`/signature_requests/${id}`, options as unknown as Record<string, unknown>);
+  }
+
+  async cancelSignatureRequest(id: string, reason?: string): Promise<SignatureRequest> {
+    return this.client.post<SignatureRequest>(`/signature_requests/${id}/cancel`, reason ? { reason } : undefined);
+  }
+
+  async activateSignatureRequest(id: string): Promise<SignatureRequest> {
+    return this.client.post<SignatureRequest>(`/signature_requests/${id}/activate`);
+  }
+
+  // ============================================
+  // Documents
+  // ============================================
+
+  async uploadDocument(signatureRequestId: string, file: Blob | ArrayBuffer, filename: string, options?: {
+    nature?: 'signable_document' | 'attachment';
+    parse_anchors?: boolean;
+    password?: string;
+  }): Promise<Document> {
+    const formData = new FormData();
+    const blob = file instanceof Blob ? file : new Blob([file], { type: 'application/pdf' });
+    formData.append('file', blob, filename);
+    formData.append('nature', options?.nature || 'signable_document');
+    if (options?.parse_anchors !== undefined) {
+      formData.append('parse_anchors', String(options.parse_anchors));
+    }
+    if (options?.password) {
+      formData.append('password', options.password);
+    }
+    return this.client.post<Document>(`/signature_requests/${signatureRequestId}/documents`, formData);
+  }
+
+  async listDocuments(signatureRequestId: string): Promise<Document[]> {
+    return this.client.get<Document[]>(`/signature_requests/${signatureRequestId}/documents`);
+  }
+
+  async getDocument(signatureRequestId: string, documentId: string): Promise<Document> {
+    return this.client.get<Document>(`/signature_requests/${signatureRequestId}/documents/${documentId}`);
+  }
+
+  async deleteDocument(signatureRequestId: string, documentId: string): Promise<void> {
+    await this.client.delete(`/signature_requests/${signatureRequestId}/documents/${documentId}`);
+  }
+
+  async downloadSignedDocument(signatureRequestId: string, documentId: string): Promise<ArrayBuffer> {
+    return this.client.get<ArrayBuffer>(`/signature_requests/${signatureRequestId}/documents/${documentId}/download`);
+  }
+
+  async downloadAuditTrailPdf(signatureRequestId: string): Promise<ArrayBuffer> {
+    return this.client.get<ArrayBuffer>(`/signature_requests/${signatureRequestId}/audit_trails/download`);
+  }
+
+  // ============================================
+  // Signers
+  // ============================================
+
+  async addSigner(signatureRequestId: string, options: AddSignerOptions): Promise<Signer> {
+    return this.client.post<Signer>(`/signature_requests/${signatureRequestId}/signers`, options as unknown as Record<string, unknown>);
+  }
+
+  async listSigners(signatureRequestId: string): Promise<Signer[]> {
+    const req = await this.getSignatureRequest(signatureRequestId);
+    return req.signers || [];
+  }
+
+  async getSigner(signatureRequestId: string, signerId: string): Promise<Signer> {
+    return this.client.get<Signer>(`/signature_requests/${signatureRequestId}/signers/${signerId}`);
+  }
+
+  async updateSigner(signatureRequestId: string, signerId: string, options: Partial<AddSignerOptions>): Promise<Signer> {
+    return this.client.patch<Signer>(`/signature_requests/${signatureRequestId}/signers/${signerId}`, options as unknown as Record<string, unknown>);
+  }
+
+  async deleteSigner(signatureRequestId: string, signerId: string): Promise<void> {
+    await this.client.delete(`/signature_requests/${signatureRequestId}/signers/${signerId}`);
+  }
+
+  async sendOtp(signatureRequestId: string, signerId: string): Promise<void> {
+    await this.client.post(`/signature_requests/${signatureRequestId}/signers/${signerId}/send_otp`);
+  }
+
+  async sendSignerInvitation(signatureRequestId: string, signerId: string): Promise<void> {
+    await this.client.post(`/signature_requests/${signatureRequestId}/signers/${signerId}/send_reminder`);
+  }
+
+  // ============================================
+  // Approvers
+  // ============================================
+
+  async addApprover(signatureRequestId: string, options: AddApproverOptions): Promise<Approver> {
+    return this.client.post<Approver>(`/signature_requests/${signatureRequestId}/approvers`, options as unknown as Record<string, unknown>);
+  }
+
+  async deleteApprover(signatureRequestId: string, approverId: string): Promise<void> {
+    await this.client.delete(`/signature_requests/${signatureRequestId}/approvers/${approverId}`);
+  }
+
+  async sendApproverInvitation(signatureRequestId: string, approverId: string): Promise<void> {
+    await this.client.post(`/signature_requests/${signatureRequestId}/approvers/${approverId}/send_reminder`);
+  }
+
+  // ============================================
+  // Signature Fields
+  // ============================================
+
+  async addSignatureField(signatureRequestId: string, signerId: string, options: CreateSignatureFieldOptions): Promise<SignatureField> {
+    return this.client.post<SignatureField>(
+      `/signature_requests/${signatureRequestId}/signers/${signerId}/fields`,
+      options as unknown as Record<string, unknown>
+    );
+  }
+
+  async listSignatureFields(signatureRequestId: string, signerId: string): Promise<SignatureField[]> {
+    return this.client.get<SignatureField[]>(`/signature_requests/${signatureRequestId}/signers/${signerId}/fields`);
+  }
+
+  async updateSignatureField(signatureRequestId: string, signerId: string, fieldId: string, options: Partial<CreateSignatureFieldOptions>): Promise<SignatureField> {
+    return this.client.patch<SignatureField>(
+      `/signature_requests/${signatureRequestId}/signers/${signerId}/fields/${fieldId}`,
+      options as unknown as Record<string, unknown>
+    );
+  }
+
+  async deleteSignatureField(signatureRequestId: string, signerId: string, fieldId: string): Promise<void> {
+    await this.client.delete(`/signature_requests/${signatureRequestId}/signers/${signerId}/fields/${fieldId}`);
+  }
+
+  // ============================================
+  // Audit Trail
+  // ============================================
+
+  async getAuditTrail(signatureRequestId: string): Promise<AuditTrail> {
+    return this.client.get<AuditTrail>(`/signature_requests/${signatureRequestId}/audit_trails`);
+  }
+
+  // ============================================
+  // Webhooks
+  // ============================================
+
+  async createWebhook(options: CreateWebhookOptions): Promise<Webhook> {
+    return this.client.post<Webhook>('/webhooks', options as unknown as Record<string, unknown>);
+  }
+
+  async listWebhooks(): Promise<Webhook[]> {
+    return this.client.get<Webhook[]>('/webhooks');
+  }
+
+  async getWebhook(webhookId: string): Promise<Webhook> {
+    return this.client.get<Webhook>(`/webhooks/${webhookId}`);
+  }
+
+  async updateWebhook(webhookId: string, options: Partial<CreateWebhookOptions>): Promise<Webhook> {
+    return this.client.put<Webhook>(`/webhooks/${webhookId}`, options as unknown as Record<string, unknown>);
+  }
+
+  async deleteWebhook(webhookId: string): Promise<void> {
+    await this.client.delete(`/webhooks/${webhookId}`);
+  }
+}