@ubuligan/esign-utils

A production-ready TypeScript utility library for electronic signature operations with configurable baseUrl and optional toast notifications. This package provides a clean abstraction layer for interacting with electronic signature services.

🚀 Features

• TypeScript Support: Full TypeScript definitions with comprehensive interfaces
• Configurable Base URL: Easy configuration for different environments
• Error Handling: Built-in error handling with optional toast notifications
• Certificate Management: Read and manage digital certificates from store
• Document Signing: Full document signing capabilities with Edoc format
• Document Verification: Verify signed documents and extract files
• TSA Client Support: Time Stamp Authority client management
• Peer Dependencies: Optional react-toastify integration for user notifications

📦 Installation

npm install @ubuligan/esign-utils

Optional Dependencies

For toast notifications (recommended for React applications):

npm install react-toastify

🛠️ Quick Start

import { esign } from "@ubuligan/esign-utils";

// Configure the base URL for your e-signature service
esign.setBaseUrl("http://your-esign-server:18230/");

// Check if certificates are available
const hasCertificates = await esign.checkFlash();
console.log("Certificates available:", hasCertificates);

// Get service version
const version = await esign.checkVersion();
console.log("Service version:", version);

📚 API Reference

Configuration

setBaseUrl(url: string): void

Configure the base URL for the e-signature service.

esign.setBaseUrl("http://localhost:18230/");
// or for production
esign.setBaseUrl("https://your-production-server.com/");

Certificate Management

checkFlash(): Promise<boolean>

Check if digital certificates are available in the certificate store.

const hasCertificates = await esign.checkFlash();
if (hasCertificates) {
  console.log("Digital certificates found in store");
} else {
  console.log("No certificates available");
}

getCertificates(): Promise<CertificateResponse>

Retrieve all available certificates from the certificate store.

const response = await esign.getCertificates();
if (response.isSuccess) {
  response.output.certificates.forEach((cert) => {
    console.log(`Certificate: ${cert.subject} (Serial: ${cert.serialNumber})`);
  });
}

Service Information

checkVersion(): Promise<any>

Get the version information of the e-signature service.

const version = await esign.checkVersion();
console.log("Service version:", version);

getTsaClients(): Promise<any>

Retrieve available Time Stamp Authority (TSA) clients.

const tsaClients = await esign.getTsaClients();
console.log("Available TSA clients:", tsaClients);

Document Signing

getFullSign(request: SignCertAndFiles): Promise<FullSignResponse>

Sign documents with a specified certificate.

const signRequest = {
  signCertificateSerialNumber: "your-certificate-serial",
  files: [
    {
      name: "document.pdf",
      rawData: "base64-encoded-file-data",
    },
  ],
  tsaClientName: "Default",
  signFormat: "Edoc" as const,
};

const signResponse = await esign.getFullSign(signRequest);
if (signResponse.isSuccess) {
  console.log("Document signed successfully");
  signResponse.output.edocFile.forEach((file) => {
    console.log(`Signed file: ${file.name}`);
  });
}

getBasesign(body: any): Promise<any>

Perform base signing operation.

const baseSignResponse = await esign.getBasesign(signData);

Document Verification

verify(request: VerifyRequest): Promise<any>

Verify a signed document.

const verifyRequest = {
  signFormat: "Edoc" as const,
  rawData: "base64-encoded-signed-document",
};

const verificationResult = await esign.verify(verifyRequest);
console.log("Verification result:", verificationResult);

getFiles(request: VerifyRequest): Promise<any>

Extract files from a signed document.

const filesRequest = {
  signFormat: "Edoc" as const,
  rawData: "base64-encoded-signed-document",
};

const extractedFiles = await esign.getFiles(filesRequest);
console.log("Extracted files:", extractedFiles);

🔧 TypeScript Interfaces

Core Types

interface Certificate {
  serialNumber: string;
  subject: string;
}

interface SignFile {
  name: string;
  rawData: string;
}

interface ResultProperties {
  error: null | any;
  isSuccess: boolean;
}

Request Types

interface SignCertAndFiles {
  signCertificateSerialNumber: string;
  files: SignFile[];
  tsaClientName: string;
  signFormat: "Edoc";
}

interface VerifyRequest {
  signFormat: "Edoc";
  rawData: string;
}

Response Types

interface CertificateResponse extends ResultProperties {
  output: {
    certificates: Certificate[];
  };
}

interface FullSignResponse extends ResultProperties {
  output: {
    edocFile: SignFile[];
  };
}

🎯 Usage Examples

Complete Signing Workflow

import { esign } from "@ubuligan/esign-utils";

async function signDocument() {
  try {
    // 1. Configure service
    esign.setBaseUrl("http://localhost:18230/");

    // 2. Check if certificates are available
    const hasCerts = await esign.checkFlash();
    if (!hasCerts) {
      throw new Error("No certificates available");
    }

    // 3. Get available certificates
    const certResponse = await esign.getCertificates();
    if (
      !certResponse.isSuccess ||
      certResponse.output.certificates.length === 0
    ) {
      throw new Error("Failed to retrieve certificates");
    }

    // 4. Select first available certificate
    const selectedCert = certResponse.output.certificates[0];

    // 5. Prepare document for signing
    const signRequest = {
      signCertificateSerialNumber: selectedCert.serialNumber,
      files: [
        {
          name: "contract.pdf",
          rawData: "your-base64-encoded-document-data",
        },
      ],
      tsaClientName: "Default",
      signFormat: "Edoc" as const,
    };

    // 6. Sign the document
    const signResponse = await esign.getFullSign(signRequest);

    if (signResponse.isSuccess) {
      console.log("Document signed successfully!");
      return signResponse.output.edocFile[0];
    } else {
      throw new Error("Signing failed: " + signResponse.error);
    }
  } catch (error) {
    console.error("Signing process failed:", error);
    throw error;
  }
}

Document Verification Workflow

async function verifyDocument(signedDocumentData: string) {
  try {
    // Verify the signed document
    const verifyRequest = {
      signFormat: "Edoc" as const,
      rawData: signedDocumentData,
    };

    const verificationResult = await esign.verify(verifyRequest);
    console.log("Verification result:", verificationResult);

    // Extract original files if needed
    const extractedFiles = await esign.getFiles(verifyRequest);
    console.log("Extracted files:", extractedFiles);

    return {
      isValid: verificationResult.isSuccess,
      files: extractedFiles,
    };
  } catch (error) {
    console.error("Verification failed:", error);
    return { isValid: false, error };
  }
}

🔧 Error Handling

The package includes built-in error handling with optional toast notifications:

• With react-toastify: Errors are displayed as toast notifications
• Without react-toastify: Errors are logged to console
• Custom handling: All methods throw errors that can be caught and handled

try {
  const result = await esign.getCertificates();
} catch (error) {
  // Handle error appropriately
  console.error("Failed to get certificates:", error);
}

🌐 Environment Configuration

Development

esign.setBaseUrl("http://localhost:18230/");

Production

esign.setBaseUrl("https://your-production-esign-service.com/");

Docker/Container

esign.setBaseUrl("http://esign-service:18230/");

📋 Requirements

• Node.js: >= 14.0.0
• TypeScript: >= 4.0.0 (for TypeScript projects)
• Fetch API: Available in modern browsers and Node.js 18+

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

👨‍💻 Author

Javid Salimov

🔗 Repository

GitHub Repository

Note: This package is designed to work with electronic signature services that follow the Edoc format specification. Make sure your e-signature service is compatible with the expected API endpoints and data formats.