@hasna/connectors 1.0.0 → 1.0.1

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

@@ -0,0 +1,131 @@
+import type { HelloSignConfig, OutputFormat } from '../types';
+import { HelloSignApiError } from '../types';
+
+// HelloSign API base URL
+const DEFAULT_BASE_URL = 'https://api.hellosign.com/v3';
+
+export interface RequestOptions {
+  method?: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
+  params?: Record<string, string | number | boolean | undefined>;
+  body?: Record<string, unknown> | unknown[] | string | FormData;
+  headers?: Record<string, string>;
+  format?: OutputFormat;
+}
+
+export class HelloSignClient {
+  private readonly apiKey: string;
+  private readonly baseUrl: string;
+
+  constructor(config: HelloSignConfig) {
+    if (!config.apiKey) {
+      throw new Error('API key is required');
+    }
+    this.apiKey = config.apiKey;
+    this.baseUrl = config.baseUrl || DEFAULT_BASE_URL;
+  }
+
+  private buildUrl(path: string, params?: Record<string, string | number | boolean | undefined>): string {
+    const url = new URL(`${this.baseUrl}${path}`);
+
+    if (params) {
+      Object.entries(params).forEach(([key, value]) => {
+        if (value !== undefined && value !== null && value !== '') {
+          url.searchParams.append(key, String(value));
+        }
+      });
+    }
+
+    return url.toString();
+  }
+
+  /**
+   * Make an authenticated request to the API
+   * HelloSign uses Basic auth with API key as username (no password)
+   */
+  async request<T>(path: string, options: RequestOptions = {}): Promise<T> {
+    const { method = 'GET', params, body, headers = {} } = options;
+
+    const url = this.buildUrl(path, params);
+
+    // HelloSign uses Basic auth: base64(api_key:)
+    const authString = Buffer.from(`${this.apiKey}:`).toString('base64');
+
+    const requestHeaders: Record<string, string> = {
+      'Authorization': `Basic ${authString}`,
+      'Accept': 'application/json',
+      ...headers,
+    };
+
+    const fetchOptions: RequestInit = {
+      method,
+      headers: requestHeaders,
+    };
+
+    if (body && ['POST', 'PUT', 'PATCH'].includes(method)) {
+      if (body instanceof FormData) {
+        // Don't set Content-Type for FormData - browser will set it with boundary
+        fetchOptions.body = body;
+      } else {
+        requestHeaders['Content-Type'] = 'application/json';
+        fetchOptions.body = typeof body === 'string' ? body : JSON.stringify(body);
+      }
+    }
+
+    const response = await fetch(url, fetchOptions);
+
+    // Handle 204 No Content
+    if (response.status === 204) {
+      return {} as T;
+    }
+
+    // Parse response
+    let data: unknown;
+    const contentType = response.headers.get('content-type') || '';
+
+    if (contentType.includes('application/json')) {
+      const text = await response.text();
+      if (text) {
+        try {
+          data = JSON.parse(text);
+        } catch {
+          data = text;
+        }
+      }
+    } else {
+      data = await response.text();
+    }
+
+    // Handle errors
+    if (!response.ok) {
+      const errorMessage = typeof data === 'object' && data !== null
+        ? JSON.stringify(data)
+        : String(data || response.statusText);
+      throw new HelloSignApiError(errorMessage, response.status);
+    }
+
+    return data as T;
+  }
+
+  async get<T>(path: string, params?: Record<string, string | number | boolean | undefined>): Promise<T> {
+    return this.request<T>(path, { method: 'GET', params });
+  }
+
+  async post<T>(path: string, body?: Record<string, unknown> | unknown[] | string | FormData, params?: Record<string, string | number | boolean | undefined>): Promise<T> {
+    return this.request<T>(path, { method: 'POST', body, params });
+  }
+
+  async put<T>(path: string, body?: Record<string, unknown> | FormData, params?: Record<string, string | number | boolean | undefined>): Promise<T> {
+    return this.request<T>(path, { method: 'PUT', body, params });
+  }
+
+  async delete<T>(path: string, params?: Record<string, string | number | boolean | undefined>): Promise<T> {
+    return this.request<T>(path, { method: 'DELETE', params });
+  }
+
+  getApiKeyPreview(): string {
+    if (this.apiKey.length > 10) {
+      return `${this.apiKey.substring(0, 6)}...${this.apiKey.substring(this.apiKey.length - 4)}`;
+    }
+    return '***';
+  }
+}

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

@@ -0,0 +1,235 @@
+import type {
+  HelloSignConfig,
+  SignatureRequest,
+  SignatureRequestListResponse,
+  CreateSignatureRequestOptions,
+  CreateFromTemplateOptions,
+  Template,
+  TemplateListResponse,
+  Account,
+  Team,
+} from '../types';
+import { HelloSignClient } from './client';
+
+/**
+ * HelloSign (Dropbox Sign) API Client
+ * Electronic signature API with templates and teams
+ */
+export class HelloSign {
+  private readonly client: HelloSignClient;
+
+  constructor(config: HelloSignConfig) {
+    this.client = new HelloSignClient(config);
+  }
+
+  /**
+   * Create a client from environment variables
+   */
+  static fromEnv(): HelloSign {
+    const apiKey = process.env.HELLOSIGN_API_KEY;
+
+    if (!apiKey) {
+      throw new Error('HELLOSIGN_API_KEY environment variable is required');
+    }
+    return new HelloSign({ apiKey });
+  }
+
+  // ============================================
+  // Signature Request Methods
+  // ============================================
+
+  /**
+   * List signature requests
+   */
+  async listSignatureRequests(options?: {
+    page?: number;
+    page_size?: number;
+    account_id?: string;
+    query?: string;
+  }): Promise<SignatureRequestListResponse> {
+    const params: Record<string, string | number | undefined> = {
+      page: options?.page,
+      page_size: options?.page_size,
+      account_id: options?.account_id,
+      query: options?.query,
+    };
+    return this.client.get<SignatureRequestListResponse>('/signature_request/list', params);
+  }
+
+  /**
+   * Get a signature request by ID
+   */
+  async getSignatureRequest(signatureRequestId: string): Promise<{ signature_request: SignatureRequest }> {
+    return this.client.get<{ signature_request: SignatureRequest }>(`/signature_request/${signatureRequestId}`);
+  }
+
+  /**
+   * Send a signature request
+   */
+  async sendSignatureRequest(options: CreateSignatureRequestOptions): Promise<{ signature_request: SignatureRequest }> {
+    return this.client.post<{ signature_request: SignatureRequest }>('/signature_request/send', options as unknown as Record<string, unknown>);
+  }
+
+  /**
+   * Send a signature request from template
+   */
+  async sendFromTemplate(options: CreateFromTemplateOptions): Promise<{ signature_request: SignatureRequest }> {
+    return this.client.post<{ signature_request: SignatureRequest }>('/signature_request/send_with_template', options as unknown as Record<string, unknown>);
+  }
+
+  /**
+   * Send a reminder for a signature request
+   */
+  async sendReminder(signatureRequestId: string, emailAddress: string): Promise<{ signature_request: SignatureRequest }> {
+    return this.client.post<{ signature_request: SignatureRequest }>(`/signature_request/remind/${signatureRequestId}`, {
+      email_address: emailAddress,
+    });
+  }
+
+  /**
+   * Cancel a signature request
+   */
+  async cancelSignatureRequest(signatureRequestId: string): Promise<void> {
+    await this.client.post<void>(`/signature_request/cancel/${signatureRequestId}`);
+  }
+
+  /**
+   * Download files for a signature request
+   */
+  async getSignatureRequestFiles(signatureRequestId: string, fileType?: 'pdf' | 'zip'): Promise<string> {
+    return this.client.get<string>(`/signature_request/files/${signatureRequestId}`, {
+      file_type: fileType,
+    });
+  }
+
+  // ============================================
+  // Template Methods
+  // ============================================
+
+  /**
+   * List templates
+   */
+  async listTemplates(options?: {
+    page?: number;
+    page_size?: number;
+    account_id?: string;
+    query?: string;
+  }): Promise<TemplateListResponse> {
+    const params: Record<string, string | number | undefined> = {
+      page: options?.page,
+      page_size: options?.page_size,
+      account_id: options?.account_id,
+      query: options?.query,
+    };
+    return this.client.get<TemplateListResponse>('/template/list', params);
+  }
+
+  /**
+   * Get a template by ID
+   */
+  async getTemplate(templateId: string): Promise<{ template: Template }> {
+    return this.client.get<{ template: Template }>(`/template/${templateId}`);
+  }
+
+  /**
+   * Delete a template
+   */
+  async deleteTemplate(templateId: string): Promise<void> {
+    await this.client.post<void>(`/template/delete/${templateId}`);
+  }
+
+  // ============================================
+  // Account Methods
+  // ============================================
+
+  /**
+   * Get current account details
+   */
+  async getAccount(): Promise<{ account: Account }> {
+    return this.client.get<{ account: Account }>('/account');
+  }
+
+  /**
+   * Update account callback URL
+   */
+  async updateAccount(callbackUrl?: string): Promise<{ account: Account }> {
+    return this.client.post<{ account: Account }>('/account', {
+      callback_url: callbackUrl,
+    });
+  }
+
+  /**
+   * Verify account exists
+   */
+  async verifyAccount(emailAddress: string): Promise<{ account: Account }> {
+    return this.client.post<{ account: Account }>('/account/verify', {
+      email_address: emailAddress,
+    });
+  }
+
+  // ============================================
+  // Team Methods
+  // ============================================
+
+  /**
+   * Get team details
+   */
+  async getTeam(): Promise<{ team: Team }> {
+    return this.client.get<{ team: Team }>('/team');
+  }
+
+  /**
+   * Create a team
+   */
+  async createTeam(name: string): Promise<{ team: Team }> {
+    return this.client.post<{ team: Team }>('/team/create', { name });
+  }
+
+  /**
+   * Update team name
+   */
+  async updateTeam(name: string): Promise<{ team: Team }> {
+    return this.client.post<{ team: Team }>('/team', { name });
+  }
+
+  /**
+   * Delete team
+   */
+  async deleteTeam(): Promise<void> {
+    await this.client.post<void>('/team/destroy');
+  }
+
+  /**
+   * Add member to team
+   */
+  async addTeamMember(options: { email_address?: string; account_id?: string }): Promise<{ team: Team }> {
+    return this.client.post<{ team: Team }>('/team/add_member', options);
+  }
+
+  /**
+   * Remove member from team
+   */
+  async removeTeamMember(options: { email_address?: string; account_id?: string }): Promise<{ team: Team }> {
+    return this.client.post<{ team: Team }>('/team/remove_member', options);
+  }
+
+  // ============================================
+  // Utility Methods
+  // ============================================
+
+  /**
+   * Get a preview of the API key
+   */
+  getApiKeyPreview(): string {
+    return this.client.getApiKeyPreview();
+  }
+
+  /**
+   * Get the underlying client for direct API access
+   */
+  getClient(): HelloSignClient {
+    return this.client;
+  }
+}
+
+export { HelloSignClient } from './client';