@hasna/connectors 1.3.0 → 1.3.2

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

@@ -0,0 +1,555 @@
+#!/usr/bin/env bun
+import { Command } from 'commander';
+import chalk from 'chalk';
+import { YouSign } from '../api';
+import {
+  getApiKey,
+  setApiKey,
+  getEnvironment,
+  setEnvironment,
+  getCurrentProfile,
+  setCurrentProfile,
+  listProfiles,
+  createProfile,
+  deleteProfile,
+  setProfileOverride,
+  profileExists,
+} from '../utils/config';
+import { writeFileSync } from 'fs';
+
+const program = new Command();
+
+program
+  .name('connect-yousign')
+  .description('Yousign API connector CLI — eIDAS-compliant electronic signatures')
+  .version('0.0.1')
+  .option('-p, --profile <profile>', 'Use a specific profile')
+  .option('-f, --format <format>', 'Output format: json|pretty', 'pretty')
+  .hook('preAction', (thisCommand) => {
+    const opts = thisCommand.opts();
+    if (opts.profile) {
+      if (!profileExists(opts.profile)) {
+        console.error(chalk.red('✗'), `Profile "${opts.profile}" does not exist`);
+        process.exit(1);
+      }
+      setProfileOverride(opts.profile);
+    }
+  });
+
+function requireAuth(): YouSign {
+  const apiKey = getApiKey();
+  if (!apiKey) {
+    console.error(chalk.red('✗'), 'API key not configured.');
+    console.error(chalk.blue('ℹ'), 'Run: connect-yousign config set-key <api-key>');
+    console.error(chalk.blue('ℹ'), 'Or set YOUSIGN_API_KEY environment variable.');
+    process.exit(1);
+  }
+  return new YouSign({ apiKey, environment: getEnvironment() });
+}
+
+function print(data: unknown, format?: string): void {
+  const fmt = format || program.opts().format || 'pretty';
+  if (fmt === 'json') {
+    console.log(JSON.stringify(data, null, 2));
+  } else {
+    console.log(JSON.stringify(data, null, 2));
+  }
+}
+
+// ============================================
+// Config commands
+// ============================================
+
+const configCmd = program.command('config').description('Manage configuration');
+
+configCmd
+  .command('set-key <key>')
+  .description('Set the Yousign API key')
+  .action((key: string) => {
+    setApiKey(key);
+    console.log(chalk.green('✓'), 'API key saved');
+  });
+
+configCmd
+  .command('set-env <env>')
+  .description('Set environment: sandbox or production')
+  .action((env: string) => {
+    if (env !== 'sandbox' && env !== 'production') {
+      console.error(chalk.red('✗'), 'Environment must be "sandbox" or "production"');
+      process.exit(1);
+    }
+    setEnvironment(env as 'sandbox' | 'production');
+    console.log(chalk.green('✓'), `Environment set to: ${env}`);
+  });
+
+configCmd
+  .command('show')
+  .description('Show current configuration')
+  .action(() => {
+    const key = getApiKey();
+    const env = getEnvironment();
+    const profile = getCurrentProfile();
+    console.log(chalk.blue('ℹ'), `Profile: ${chalk.green(profile)}`);
+    console.log(chalk.blue('ℹ'), `Environment: ${chalk.green(env)}`);
+    console.log(chalk.blue('ℹ'), `API key: ${key ? chalk.green(key.substring(0, 8) + '...') : chalk.red('not set')}`);
+  });
+
+// ============================================
+// Profile commands
+// ============================================
+
+const profilesCmd = program.command('profiles').description('Manage profiles');
+
+profilesCmd
+  .command('list')
+  .description('List all profiles')
+  .action(() => {
+    const profiles = listProfiles();
+    const current = getCurrentProfile();
+    if (profiles.length === 0) {
+      console.log(chalk.blue('ℹ'), 'No profiles found');
+    } else {
+      for (const p of profiles) {
+        const marker = p === current ? chalk.green(' (current)') : '';
+        console.log(`  ${p}${marker}`);
+      }
+    }
+  });
+
+profilesCmd
+  .command('create <name>')
+  .description('Create a new profile')
+  .action((name: string) => {
+    try {
+      const created = createProfile(name);
+      if (created) {
+        console.log(chalk.green('✓'), `Profile "${name}" created`);
+      } else {
+        console.error(chalk.red('✗'), `Profile "${name}" already exists`);
+      }
+    } catch (err) {
+      console.error(chalk.red('✗'), String(err));
+      process.exit(1);
+    }
+  });
+
+profilesCmd
+  .command('switch <name>')
+  .description('Switch to a different profile')
+  .action((name: string) => {
+    try {
+      setCurrentProfile(name);
+      console.log(chalk.green('✓'), `Switched to profile: ${name}`);
+    } catch (err) {
+      console.error(chalk.red('✗'), String(err));
+      process.exit(1);
+    }
+  });
+
+profilesCmd
+  .command('delete <name>')
+  .description('Delete a profile')
+  .action((name: string) => {
+    const deleted = deleteProfile(name);
+    if (deleted) {
+      console.log(chalk.green('✓'), `Profile "${name}" deleted`);
+    } else {
+      console.error(chalk.red('✗'), `Cannot delete profile "${name}"`);
+    }
+  });
+
+// ============================================
+// Signature Requests
+// ============================================
+
+const requestsCmd = program.command('requests').description('Manage signature requests');
+
+requestsCmd
+  .command('list')
+  .description('List signature requests')
+  .option('--status <status>', 'Filter by status (draft|ongoing|done|canceled|expired)')
+  .option('--limit <n>', 'Max results', '20')
+  .option('--after <cursor>', 'Pagination cursor')
+  .action(async (opts) => {
+    try {
+      const client = requireAuth();
+      const result = await client.listSignatureRequests({
+        status: opts.status,
+        after: opts.after,
+        limit: parseInt(opts.limit),
+      });
+      print(result);
+    } catch (err) {
+      console.error(chalk.red('✗'), String(err));
+      process.exit(1);
+    }
+  });
+
+requestsCmd
+  .command('get <id>')
+  .description('Get a signature request by ID')
+  .action(async (id: string) => {
+    try {
+      const client = requireAuth();
+      print(await client.getSignatureRequest(id));
+    } catch (err) {
+      console.error(chalk.red('✗'), String(err));
+      process.exit(1);
+    }
+  });
+
+requestsCmd
+  .command('create')
+  .description('Create a new signature request')
+  .requiredOption('-n, --name <name>', 'Request name')
+  .option('--delivery-mode <mode>', 'Delivery mode: email|none', 'email')
+  .option('--timezone <tz>', 'Timezone (e.g. Europe/Paris)')
+  .option('--expiration <date>', 'Expiration date (ISO 8601)')
+  .option('--ordered', 'Signers sign in order')
+  .option('--external-id <id>', 'External ID for tracking')
+  .option('--no-decline', 'Do not allow signers to decline')
+  .action(async (opts) => {
+    try {
+      const client = requireAuth();
+      const result = await client.createSignatureRequest({
+        name: opts.name,
+        delivery_mode: opts.deliveryMode as 'email' | 'none',
+        timezone: opts.timezone,
+        expiration_date: opts.expiration,
+        ordered_signers: opts.ordered || false,
+        external_id: opts.externalId,
+        signers_allowed_to_decline: !opts.noDecline,
+      });
+      console.log(chalk.green('✓'), `Signature request created: ${result.id}`);
+      print(result);
+    } catch (err) {
+      console.error(chalk.red('✗'), String(err));
+      process.exit(1);
+    }
+  });
+
+requestsCmd
+  .command('activate <id>')
+  .description('Activate a signature request (send to signers)')
+  .action(async (id: string) => {
+    try {
+      const client = requireAuth();
+      const result = await client.activateSignatureRequest(id);
+      console.log(chalk.green('✓'), `Signature request activated`);
+      print(result);
+    } catch (err) {
+      console.error(chalk.red('✗'), String(err));
+      process.exit(1);
+    }
+  });
+
+requestsCmd
+  .command('cancel <id>')
+  .description('Cancel a signature request')
+  .option('--reason <reason>', 'Cancellation reason')
+  .action(async (id: string, opts) => {
+    try {
+      const client = requireAuth();
+      await client.cancelSignatureRequest(id, opts.reason);
+      console.log(chalk.green('✓'), `Signature request cancelled`);
+    } catch (err) {
+      console.error(chalk.red('✗'), String(err));
+      process.exit(1);
+    }
+  });
+
+// ============================================
+// Documents
+// ============================================
+
+const docsCmd = program.command('documents').alias('docs').description('Manage documents');
+
+docsCmd
+  .command('upload <requestId> <filepath>')
+  .description('Upload a document to a signature request')
+  .option('--nature <nature>', 'Document nature: signable_document|attachment', 'signable_document')
+  .option('--parse-anchors', 'Parse anchor tags for auto-positioning fields')
+  .action(async (requestId: string, filepath: string, opts) => {
+    try {
+      const client = requireAuth();
+      const { readFileSync } = await import('fs');
+      const { basename } = await import('path');
+      const data = readFileSync(filepath).buffer as ArrayBuffer;
+      const filename = basename(filepath);
+      const result = await client.uploadDocument(requestId, data, filename, {
+        nature: opts.nature as 'signable_document' | 'attachment',
+        parse_anchors: opts.parseAnchors,
+      });
+      console.log(chalk.green('✓'), `Document uploaded: ${result.id}`);
+      print(result);
+    } catch (err) {
+      console.error(chalk.red('✗'), String(err));
+      process.exit(1);
+    }
+  });
+
+docsCmd
+  .command('list <requestId>')
+  .description('List documents in a signature request')
+  .action(async (requestId: string) => {
+    try {
+      const client = requireAuth();
+      print(await client.listDocuments(requestId));
+    } catch (err) {
+      console.error(chalk.red('✗'), String(err));
+      process.exit(1);
+    }
+  });
+
+docsCmd
+  .command('download <requestId> <documentId> [output]')
+  .description('Download a signed document')
+  .action(async (requestId: string, documentId: string, output?: string) => {
+    try {
+      const client = requireAuth();
+      const buffer = await client.downloadSignedDocument(requestId, documentId);
+      const outPath = output || `document_${documentId}.pdf`;
+      writeFileSync(outPath, Buffer.from(buffer));
+      console.log(chalk.green('✓'), `Document saved to: ${outPath}`);
+    } catch (err) {
+      console.error(chalk.red('✗'), String(err));
+      process.exit(1);
+    }
+  });
+
+docsCmd
+  .command('delete <requestId> <documentId>')
+  .description('Delete a document from a signature request')
+  .action(async (requestId: string, documentId: string) => {
+    try {
+      const client = requireAuth();
+      await client.deleteDocument(requestId, documentId);
+      console.log(chalk.green('✓'), 'Document deleted');
+    } catch (err) {
+      console.error(chalk.red('✗'), String(err));
+      process.exit(1);
+    }
+  });
+
+// ============================================
+// Signers
+// ============================================
+
+const signersCmd = program.command('signers').description('Manage signers');
+
+signersCmd
+  .command('add <requestId>')
+  .description('Add a signer to a signature request')
+  .requiredOption('--email <email>', 'Signer email')
+  .requiredOption('--first-name <name>', 'First name')
+  .requiredOption('--last-name <name>', 'Last name')
+  .option('--phone <phone>', 'Phone number (for SMS OTP)')
+  .option('--locale <locale>', 'Locale (e.g. en, fr)')
+  .option('--level <level>', 'Signature level: electronic_signature|advanced_electronic_signature', 'electronic_signature')
+  .action(async (requestId: string, opts) => {
+    try {
+      const client = requireAuth();
+      const result = await client.addSigner(requestId, {
+        info: {
+          email: opts.email,
+          first_name: opts.firstName,
+          last_name: opts.lastName,
+          phone_number: opts.phone,
+          locale: opts.locale,
+        },
+        signature_level: opts.level,
+      });
+      console.log(chalk.green('✓'), `Signer added: ${result.id}`);
+      print(result);
+    } catch (err) {
+      console.error(chalk.red('✗'), String(err));
+      process.exit(1);
+    }
+  });
+
+signersCmd
+  .command('list <requestId>')
+  .description('List signers for a signature request')
+  .action(async (requestId: string) => {
+    try {
+      const client = requireAuth();
+      print(await client.listSigners(requestId));
+    } catch (err) {
+      console.error(chalk.red('✗'), String(err));
+      process.exit(1);
+    }
+  });
+
+signersCmd
+  .command('delete <requestId> <signerId>')
+  .description('Remove a signer from a signature request')
+  .action(async (requestId: string, signerId: string) => {
+    try {
+      const client = requireAuth();
+      await client.deleteSigner(requestId, signerId);
+      console.log(chalk.green('✓'), 'Signer removed');
+    } catch (err) {
+      console.error(chalk.red('✗'), String(err));
+      process.exit(1);
+    }
+  });
+
+signersCmd
+  .command('remind <requestId> <signerId>')
+  .description('Send a reminder to a signer')
+  .action(async (requestId: string, signerId: string) => {
+    try {
+      const client = requireAuth();
+      await client.sendSignerInvitation(requestId, signerId);
+      console.log(chalk.green('✓'), 'Reminder sent');
+    } catch (err) {
+      console.error(chalk.red('✗'), String(err));
+      process.exit(1);
+    }
+  });
+
+// ============================================
+// Signature Fields
+// ============================================
+
+const fieldsCmd = program.command('fields').description('Manage signature fields');
+
+fieldsCmd
+  .command('add <requestId> <signerId>')
+  .description('Add a signature field for a signer on a document')
+  .requiredOption('--document-id <id>', 'Document ID')
+  .requiredOption('--page <n>', 'Page number')
+  .requiredOption('--x <x>', 'X coordinate')
+  .requiredOption('--y <y>', 'Y coordinate')
+  .option('--width <w>', 'Width')
+  .option('--height <h>', 'Height')
+  .option('--type <type>', 'Field type: signature|mention|text|checkbox', 'signature')
+  .option('--mention <text>', 'Mention text (for mention type)')
+  .action(async (requestId: string, signerId: string, opts) => {
+    try {
+      const client = requireAuth();
+      const result = await client.addSignatureField(requestId, signerId, {
+        type: opts.type,
+        document_id: opts.documentId,
+        page: parseInt(opts.page),
+        x: parseInt(opts.x),
+        y: parseInt(opts.y),
+        width: opts.width ? parseInt(opts.width) : undefined,
+        height: opts.height ? parseInt(opts.height) : undefined,
+        mention: opts.mention,
+      });
+      console.log(chalk.green('✓'), `Field added: ${result.id}`);
+      print(result);
+    } catch (err) {
+      console.error(chalk.red('✗'), String(err));
+      process.exit(1);
+    }
+  });
+
+fieldsCmd
+  .command('list <requestId> <signerId>')
+  .description('List signature fields for a signer')
+  .action(async (requestId: string, signerId: string) => {
+    try {
+      const client = requireAuth();
+      print(await client.listSignatureFields(requestId, signerId));
+    } catch (err) {
+      console.error(chalk.red('✗'), String(err));
+      process.exit(1);
+    }
+  });
+
+// ============================================
+// Audit Trail
+// ============================================
+
+const auditCmd = program.command('audit').description('Audit trail commands');
+
+auditCmd
+  .command('get <requestId>')
+  .description('Get audit trail for a signature request')
+  .action(async (requestId: string) => {
+    try {
+      const client = requireAuth();
+      print(await client.getAuditTrail(requestId));
+    } catch (err) {
+      console.error(chalk.red('✗'), String(err));
+      process.exit(1);
+    }
+  });
+
+auditCmd
+  .command('download <requestId> [output]')
+  .description('Download audit trail as PDF')
+  .action(async (requestId: string, output?: string) => {
+    try {
+      const client = requireAuth();
+      const buffer = await client.downloadAuditTrailPdf(requestId);
+      const outPath = output || `audit_trail_${requestId}.pdf`;
+      writeFileSync(outPath, Buffer.from(buffer));
+      console.log(chalk.green('✓'), `Audit trail saved to: ${outPath}`);
+    } catch (err) {
+      console.error(chalk.red('✗'), String(err));
+      process.exit(1);
+    }
+  });
+
+// ============================================
+// Webhooks
+// ============================================
+
+const webhooksCmd = program.command('webhooks').description('Manage webhooks');
+
+webhooksCmd
+  .command('list')
+  .description('List all webhooks')
+  .action(async () => {
+    try {
+      const client = requireAuth();
+      print(await client.listWebhooks());
+    } catch (err) {
+      console.error(chalk.red('✗'), String(err));
+      process.exit(1);
+    }
+  });
+
+webhooksCmd
+  .command('create')
+  .description('Create a webhook')
+  .requiredOption('--endpoint <url>', 'Webhook endpoint URL')
+  .option('--events <events>', 'Comma-separated events (default: all)', 'signature_request.done,signature_request.expired,signer.done')
+  .option('--secret <secret>', 'Signing secret for HMAC verification')
+  .option('--description <desc>', 'Webhook description')
+  .action(async (opts) => {
+    try {
+      const client = requireAuth();
+      const events = opts.events.split(',').map((e: string) => e.trim());
+      const result = await client.createWebhook({
+        endpoint: opts.endpoint,
+        subscriptions: events,
+        secret: opts.secret,
+        description: opts.description,
+      });
+      console.log(chalk.green('✓'), `Webhook created: ${result.id}`);
+      print(result);
+    } catch (err) {
+      console.error(chalk.red('✗'), String(err));
+      process.exit(1);
+    }
+  });
+
+webhooksCmd
+  .command('delete <id>')
+  .description('Delete a webhook')
+  .action(async (id: string) => {
+    try {
+      const client = requireAuth();
+      await client.deleteWebhook(id);
+      console.log(chalk.green('✓'), 'Webhook deleted');
+    } catch (err) {
+      console.error(chalk.red('✗'), String(err));
+      process.exit(1);
+    }
+  });
+
+program.parse(process.argv);

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

@@ -0,0 +1,21 @@
+// Yousign Connector
+// TypeScript wrapper for Yousign electronic signature API v3
+
+export { YouSign } from './api';
+export * from './types';
+export { YouSignClient } from './api/client';
+
+export {
+  getApiKey,
+  setApiKey,
+  getEnvironment,
+  setEnvironment,
+  getCurrentProfile,
+  setCurrentProfile,
+  listProfiles,
+  createProfile,
+  deleteProfile,
+  loadProfile,
+  saveProfile,
+  clearConfig,
+} from './utils/config';