### Handle E-IMZO Installation and Errors

Source: https://github.com/sanjarbarakayev/vue-esignature/blob/main/README.md

Provides an example of handling E-IMZO installation and potential errors using the `useESignature` composable. It checks the success of the installation and then conditionally displays prompts for installing E-IMZO or updating it based on specific error messages. Errors are cleared after handling.

```typescript
const { install, error, clearError } = useESignature()

const success = await install()

if (!success) {
  if (error.value?.includes('E-IMZO')) {
    // E-IMZO not installed
    showInstallPrompt()
  } else if (error.value?.includes('version')) {
    // Version too old
    showUpdatePrompt()
  }
  
  clearError()
}
```

--------------------------------

### TypeScript Configuration Example

Source: https://github.com/sanjarbarakayev/vue-esignature/blob/main/docs/guide/installation.md

Ensure your `tsconfig.json` includes necessary compiler options for optimal TypeScript integration with Vue E-Signature. This includes module resolution and strict type checking.

```json
{
  "compilerOptions": {
    "moduleResolution": "bundler",
    "strict": true
  }
}
```

--------------------------------

### Initialize E-IMZO Service

Source: https://github.com/sanjarbarakayev/vue-esignature/blob/main/docs/guide/quick-start.md

Initializes the E-IMZO service when the component is mounted. It sets the loading state, calls the `install` function, and fetches available certificates using `listKeys`. Error handling is included to log any initialization failures. This function relies on the `useESignature` composable.

```vue
<script setup lang="ts">
onMounted(async () => {
  try {
    loading.value = true
    await install()
    certificates.value = await listKeys()
  } catch (err) {
    console.error('Failed to initialize E-IMZO:', err)
  } finally {
    loading.value = false
  }
})
</script>
```

--------------------------------

### Initialize E-IMZO and Handle Installation

Source: https://github.com/sanjarbarakayev/vue-esignature/blob/main/docs/api/composable.md

Demonstrates how to initialize the E-IMZO service using the 'install' method and subsequently check the installation status and any errors. This is crucial for ensuring the digital signature environment is ready before proceeding with other operations.

```typescript
const { install, isInstalled, error } = useESignature()

await install()

if (error.value) {
  console.error('Failed:', error.value.message)
} else {
  console.log('Installed:', isInstalled.value)
}
```

--------------------------------

### Install Vue E-Signature Package

Source: https://github.com/sanjarbarakayev/vue-esignature/blob/main/docs/guide/installation.md

Install the Vue E-Signature package using your preferred package manager. This is the initial step to include the library in your project.

```bash
npm install @sanjarbarakayev/vue-esignature
```

```bash
pnpm add @sanjarbarakayev/vue-esignature
```

```bash
yarn add @sanjarbarakayev/vue-esignature
```

--------------------------------

### Example: Initialize EIMZOMobile

Source: https://github.com/sanjarbarakayev/vue-esignature/blob/main/docs/api/e-imzo-mobile.md

Provides a practical example of initializing the EIMZOMobile class with a specific site ID, an HTML element, the 'qrcode.js' library, and custom dimensions.

```typescript
import QRCode from 'qrcode.js'

const element = document.getElementById('qrcode')!
const mobile = new EIMZOMobile('SITE123', element, QRCode, {
  width: 256,
  height: 256
})
```

--------------------------------

### Install qrcode.js

Source: https://github.com/sanjarbarakayev/vue-esignature/blob/main/docs/api/e-imzo-mobile.md

Provides the npm command to install the 'qrcode.js' library, a compatible QR code generation library.

```bash
npm install qrcode.js
```

--------------------------------

### Start Playground Development Server (Bash)

Source: https://github.com/sanjarbarakayev/vue-esignature/blob/main/playground/README.md

Commands to start the interactive development environment for vue-esignature. This utilizes pnpm for package management and enables hot module replacement for rapid development.

```bash
pnpm playground

# Or from this directory
pnpm dev
```

--------------------------------

### Complete Vue Component Example

Source: https://github.com/sanjarbarakayev/vue-esignature/blob/main/docs/api/e-imzo-mobile.md

A full Vue 3 component using the Composition API that integrates EIMZOMobile for generating and displaying QR codes. It includes setup, mounting, unmounting, and regeneration logic.

```vue
<script setup lang="ts">
import { ref, onMounted, onUnmounted } from 'vue'
import { EIMZOMobile } from '@sanjarbarakayev/vue-esignature'
import QRCode from 'qrcode.js'

const props = defineProps({
  siteId: String,
  documentNumber: String,
  content: String
})

const qrElement = ref<HTMLElement | null>(null)
const mobile = ref<EIMZOMobile | null>(null)
const qrResult = ref<{ hash: string; code: string } | null>(null)

onMounted(() => {
  if (qrElement.value) {
    mobile.value = new EIMZOMobile(
      props.siteId,
      qrElement.value,
      QRCode,
      { width: 280, height: 280 }
    )

    const result = mobile.value.makeQRCode(
      props.documentNumber,
      props.content
    )

    if (result) {
      qrResult.value = {
        hash: result[0],
        code: result[1]
      }
    }
  }
})

onUnmounted(() => {
  mobile.value?.clear()
})

function regenerate() {
  const result = mobile.value?.makeQRCode(
    props.documentNumber,
    props.content
  )

  if (result) {
    qrResult.value = {
      hash: result[0],
      code: result[1]
    }
  }
}
</script>

<template>
  <div class="mobile-signing">
    <div ref="qrElement" class="qr-code" />

    <div v-if="qrResult" class="info">
      <p><strong>Document Hash:</strong></p>
      <code>{{ qrResult.hash }}</code>
    </div>

    <div class="instructions">
      <ol>
        <li>Open E-IMZO app on your phone</li>
        <li>Tap "Scan QR"</li>
        <li>Point camera at QR code</li>
        <li>Enter PIN and confirm</li>
      </ol>
    </div>

    <button @click="regenerate">Regenerate QR</button>
  </div>
</template>

```

--------------------------------

### Complete Vue Component for E-Signature

Source: https://github.com/sanjarbarakayev/vue-esignature/blob/main/docs/guide/quick-start.md

A comprehensive Vue 3 component that utilizes the useESignature composable to handle digital signing. It includes UI elements for certificate selection, document input, and displaying the generated signature. It also manages loading states and error handling, and provides a fallback to download the E-IMZO application if it's not installed.

```vue
<script setup lang="ts">
import { ref, onMounted } from 'vue'
import { useESignature } from '@sanjarbarakayev/vue-esignature'
import type { Certificate } from '@sanjarbarakayev/vue-esignature'

const { install, listKeys, loadKey, signData, isInstalled, error } = useESignature()

const certificates = ref<Certificate[]>([])
const selectedCert = ref<Certificate | null>(null)
const documentContent = ref('This is the document content to be signed.')
const signature = ref('')
const loading = ref(false)

onMounted(async () => {
  try {
    loading.value = true
    await install()
    certificates.value = await listKeys()
  } catch (err) {
    console.error('Failed to initialize:', err)
  } finally {
    loading.value = false
  }
})

async function handleSign() {
  if (!selectedCert.value) return

  try {
    loading.value = true
    const { id } = await loadKey(selectedCert.value)
    const result = await signData(id, documentContent.value)
    signature.value = typeof result === 'string' ? result : result.pkcs7_64
  } catch (err) {
    alert('Error: ' + (err as Error).message)
  } finally {
    loading.value = false
  }
}
</script>

<template>
  <div class="esignature-demo">
    <h2>Digital Signature Demo</h2>

    <div v-if="loading" class="loading">
      <span>Loading...</span>
    </div>

    <div v-else-if="error" class="error">
      {{ error.message }}
    </div>

    <div v-else-if="isInstalled" class="content">
      <div class="form-group">
        <label for="cert">Certificate:</label>
        <select id="cert" v-model="selectedCert">
          <option :value="null">Select a certificate</option>
          <option
            v-for="cert in certificates"
            :key="cert.serialNumber"
            :value="cert"
          >
            {{ cert.CN }} - {{ cert.type.toUpperCase() }}
          </option>
        </select>
      </div>

      <div class="form-group">
        <label for="content">Document Content:</label>
        <textarea
          id="content"
          v-model="documentContent"
          rows="4"
        />
      </div>

      <button @click="handleSign" :disabled="!selectedCert || loading">
        {{ loading ? 'Signing...' : 'Sign Document' }}
      </button>

      <div v-if="signature" class="result">
        <label>PKCS#7 Signature:</label>
        <textarea readonly :value="signature" rows="8" />
      </div>
    </div>

    <div v-else class="not-installed">
      <p>E-IMZO is not installed.</p>
      <a
        href="https://e-imzo.soliq.uz/download/"
        target="_blank"
        class="download-btn"
      >
        Download E-IMZO
      </a>
    </div>
  </div>
</template>

<style scoped>
.esignature-demo {
  max-width: 600px;
  margin: 0 auto;
  padding: 20px;
}

.form-group {
  margin-bottom: 16px;
}

label {
  display: block;
  margin-bottom: 4px;
  font-weight: 500;
}

select, textarea {
  width: 100%;
  padding: 8px;
  border: 1px solid #ccc;
  border-radius: 4px;
}

button {
  background: #3eaf7c;
  color: white;
  border: none;
  padding: 10px 20px;
  border-radius: 4px;
  cursor: pointer;
}

button:disabled {
  background: #ccc;
  cursor: not-allowed;
}

.error {
  color: #e74c3c;
  padding: 12px;
  background: #fdeaea;
  border-radius: 4px;
}

.result {
  margin-top: 20px;
}

.result textarea {
  font-family: monospace;
  font-size: 12px;
}

.download-btn {
  display: inline-block;
  background: #3498db;
  color: white;
  padding: 10px 20px;
  border-radius: 4px;
  text-decoration: none;
}
</style>
```

--------------------------------

### Example: Using generateQRCodeData

Source: https://github.com/sanjarbarakayev/vue-esignature/blob/main/docs/api/e-imzo-mobile.md

Shows how to use the static `generateQRCodeData` method and then use the resulting QR code string with a custom rendering function.

```typescript
const result = EIMZOMobile.generateQRCodeData(
  'SITE123',
  'DOC-001',
  'Document content'
)

if (result) {
  // Use your own QR rendering
  renderQRCode(result.code)
}
```

--------------------------------

### Complete Vue 3 E-Signature Example

Source: https://github.com/sanjarbarakayev/vue-esignature/blob/main/docs/api/composable.md

A comprehensive Vue 3 component example using the 'useESignature' composable. It demonstrates initializing E-IMZO, listing certificates, selecting a certificate, signing content, and displaying the signature or errors.

```vue
<script setup lang="ts">
import { ref, onMounted, computed } from 'vue'
import { useESignature } from '@sanjarbarakayev/vue-esignature'
import type { Certificate } from '@sanjarbarakayev/vue-esignature'

const { 
  install,
  listKeys,
  loadKey,
  signData,
  isInstalled,
  isLoading,
  loadedKey,
  error
} = useESignature()

const certificates = ref<Certificate[]>([])
const selectedCert = ref<Certificate | null>(null)
const content = ref('Document to sign')
const signature = ref('')

const canSign = computed(() =>
  isInstalled.value &&
  selectedCert.value &&
  !isLoading.value
)

onMounted(async () => {
  await install()
  if (isInstalled.value) {
    certificates.value = await listKeys()
  }
})

async function handleSign() {
  if (!selectedCert.value) return

  const { id } = await loadKey(selectedCert.value)
  const result = await signData(id, content.value)
  signature.value = typeof result === 'string' ? result : result.pkcs7_64
}
</script>

<template>
  <div>
    <div v-if="error" class="error">
      {{ error.message }}
    </div>

    <div v-if="isLoading">Loading...</div>

    <div v-else-if="isInstalled">
      <select v-model="selectedCert">
        <option :value="null">Select certificate</option>
        <option v-for="cert in certificates" :key="cert.serialNumber" :value="cert">
          {{ cert.CN }}
        </option>
      </select>

      <textarea v-model="content" rows="4" />

      <button @click="handleSign" :disabled="!canSign">
        Sign
      </button>

      <div v-if="loadedKey">
        Signed with: {{ loadedKey.CN }}
      </div>

      <textarea v-if="signature" :value="signature" readonly rows="6" />
    </div>

    <div v-else>
      E-IMZO not available
    </div>
  </div>
</template>
```

--------------------------------

### Vue E-Signature UI Template

Source: https://github.com/sanjarbarakayev/vue-esignature/blob/main/docs/guide/quick-start.md

Renders the user interface for the Vue E-Signature component. It displays different states: loading, error, ready (with certificate selection and sign button), or E-IMZO not installed. The UI uses Vue's template syntax and conditional rendering based on component state and props.

```vue
<template>
  <div class="esignature-demo">
    <!-- Loading state -->
    <div v-if="loading">Initializing E-IMZO...</div>

    <!-- Error state -->
    <div v-else-if="error" class="error">
      {{ error.message }}
    </div>

    <!-- Ready state -->
    <div v-else-if="isInstalled">
      <!-- Certificate selection -->
      <div class="form-group">
        <label>Select Certificate:</label>
        <select v-model="selectedCert">
          <option :value="null">-- Select --</option>
          <option
            v-for="cert in certificates"
            :key="cert.serialNumber"
            :value="cert"
          >
            {{ cert.CN }} ({{ cert.O }})
          </option>
        </select>
      </div>

      <!-- Sign button -->
      <button
        @click="handleSign"
        :disabled="!selectedCert"
      >
        Sign Document
      </button>

      <!-- Signature result -->
      <div v-if="signature" class="result">
        <h4>Signature (PKCS#7):</h4>
        <textarea readonly :value="signature" rows="6" />
      </div>
    </div>

    <!-- Not installed state -->
    <div v-else>
      <p>E-IMZO is not installed or not running.</p>
      <a href="https://e-imzo.soliq.uz/download/" target="_blank">
        Download E-IMZO
      </a>
    </div>
  </div>
</template>
```

--------------------------------

### Example: Using makeQRCode

Source: https://github.com/sanjarbarakayev/vue-esignature/blob/main/docs/api/e-imzo-mobile.md

Illustrates how to use the `makeQRCode` method and handle its potential null return value. It logs the generated document hash and QR code data to the console.

```typescript
const result = mobile.makeQRCode('DOC-2024-001', 'Contract content...')

if (result) {
  const [textHash, qrCode] = result
  console.log('Document hash:', textHash)
  console.log('QR code data:', qrCode)
}
```

--------------------------------

### Vue E-Signature Plugin Installation

Source: https://github.com/sanjarbarakayev/vue-esignature/blob/main/README.md

Instructions on how to install the Vue E-Signature plugin using npm, yarn, or pnpm.

```APIDOC
## Installation

```bash
# npm
npm install @sanjarbarakayev/vue-esignature

# yarn
yarn add @sanjarbarakayev/vue-esignature

# pnpm
pnpm add @sanjarbarakayev/vue-esignature
```
```

--------------------------------

### Multi-Document Signing with Vue E-Signature

Source: https://github.com/sanjarbarakayev/vue-esignature/blob/main/docs/examples/index.md

This example demonstrates how to sign multiple documents concurrently using Vue E-Signature. It leverages the `useESignature` hook to install the library, load a certificate, and then signs each document in parallel. The function returns an array of signatures.

```typescript
async function signMultiple(documents: string[]): Promise<string[]> {
  const { install, listKeys, loadKey, signData } = useESignature()

  await install()
  const certs = await listKeys()
  const { id } = await loadKey(certs[0])

  return Promise.all(documents.map(doc => signData(id, doc)))
}
```

--------------------------------

### Example: Clearing QR Code

Source: https://github.com/sanjarbarakayev/vue-esignature/blob/main/docs/api/e-imzo-mobile.md

A simple example demonstrating how to call the `clear` method on an EIMZOMobile instance to remove the QR code.

```typescript
mobile.clear()
```

--------------------------------

### Quick Sign with Vue E-Signature

Source: https://github.com/sanjarbarakayev/vue-esignature/blob/main/docs/examples/index.md

Demonstrates the simplest signing flow using Vue E-Signature. It initializes the library, lists available certificates, loads a key, and signs provided content. Dependencies include the '@sanjarbarakayev/vue-esignature' package.

```typescript
import { useESignature } from '@sanjarbarakayev/vue-esignature'

const { install, listKeys, loadKey, signData } = useESignature()

async function quickSign(content: string): Promise<string> {
  await install()
  const certs = await listKeys()
  const { id } = await loadKey(certs[0])
  const result = await signData(id, content)
  return typeof result === 'string' ? result : result.pkcs7_64
}
```

--------------------------------

### Directly Import Vue E-Signature Class

Source: https://github.com/sanjarbarakayev/vue-esignature/blob/main/docs/guide/installation.md

Instantiate the `ESignature` class directly for class-based usage. This approach is suitable when you prefer object-oriented programming patterns.

```typescript
import { ESignature } from '@sanjarbarakayev/vue-esignature'

const esignature = new ESignature()
```

--------------------------------

### Detect E-IMZO Software Installation and Status

Source: https://context7.com/sanjarbarakayev/vue-esignature/llms.txt

Checks if the E-IMZO software is installed and running on the user's system. It provides functions to get the status, download URL, and WebSocket URL. This is crucial for ensuring E-IMZO operations can proceed.

```typescript
import {
  detectEIMZO,
  isEIMZOAvailable,
  getEIMZODownloadUrl,
  getEIMZOWebSocketUrl,
  type EIMZOStatus
} from '@sanjarbarakayev/vue-esignature'

// Full status detection
const status: EIMZOStatus = await detectEIMZO()
console.log('Status:', {
  isInstalled: status.isInstalled,    // E-IMZO software present
  isRunning: status.isRunning,        // Service currently running
  port: status.port,                   // Port number (64443 or 64646)
  browserSupported: status.browserSupported  // WebSocket support
})

if (!status.browserSupported) {
  console.error('Browser does not support WebSocket')
} else if (!status.isRunning) {
  console.log('Please install E-IMZO:', getEIMZODownloadUrl())
} else {
  console.log(`E-IMZO running on port ${status.port}`)
}

// Quick availability check
const available = await isEIMZOAvailable()
if (available) {
  // Proceed with signing operations
}

// Debug: Get WebSocket URL being used
const wsUrl = getEIMZOWebSocketUrl()
console.log('WebSocket URL:', wsUrl)
// HTTPS pages: wss://127.0.0.1:64443/service/cryptapi
// HTTP pages:  ws://127.0.0.1:64646/service/cryptapi
```

--------------------------------

### Install Vue E-Signature Package

Source: https://github.com/sanjarbarakayev/vue-esignature/blob/main/docs/index.md

Installs the Vue E-Signature package using npm. This is the first step to integrate digital signatures into your Vue 3 application.

```bash
npm install @sanjarbarakayev/vue-esignature
```

--------------------------------

### Add Custom API Key to ESignature Instance

Source: https://github.com/sanjarbarakayev/vue-esignature/blob/main/docs/guide/installation.md

Add custom API keys to an ESignature instance programmatically. This is useful for authorizing specific domains in production environments.

```typescript
import { ESignature } from '@sanjarbarakayev/vue-esignature'

const esignature = new ESignature()

// Add your production API key
esignature.addApiKey('yourdomain.com', 'YOUR_PRODUCTION_API_KEY')
```

--------------------------------

### ESignatureWidget Component Setup (Vue.js)

Source: https://github.com/sanjarbarakayev/vue-esignature/blob/main/docs/examples/vue-component.md

This script setup block defines the ESignatureWidget component in Vue.js using TypeScript. It imports necessary functions and types from the '@sanjarbarakayev/vue-esignature' library, defines props and emits, manages component state, and implements the core logic for electronic signing, including hardware detection and certificate selection.

```vue
<script setup lang="ts">
import { ref, computed, onMounted, watch } from 'vue'
import { 
  useESignature, 
  setLocale, 
  getErrorMessage, 
  type SupportedLocale 
} from '@sanjarbarakayev/vue-esignature'
import type { Certificate } from '@sanjarbarakayev/vue-esignature'

// Props
const props = withDefaults(defineProps<{ 
  content: string
  documentTitle?: string
  locale?: SupportedLocale
  showPreview?: boolean
  allowMultiple?: boolean
}>(), {
  documentTitle: 'Document',
  locale: 'en',
  showPreview: true,
  allowMultiple: false
})

// Emits
const emit = defineEmits<{ 
  signed: [signature: string, certificate: Certificate]
  error: [error: Error]
  cancel: []
}>()

// Set locale
watch(() => props.locale, (newLocale) => {
  setLocale(newLocale)
}, { immediate: true })

// Composable
const { 
  install, 
  listKeys, 
  loadKey, 
  signData, 
  isIDCardPlugged, 
  isBAIKTokenPlugged, 
  signWithUSB, 
  signWithBAIK, 
  isInstalled, 
  isLoading, 
  error 
} = useESignature()

// State
type Step = 'init' | 'select' | 'confirm' | 'password' | 'signing' | 'success' | 'error'
const step = ref<Step>('init')
const certificates = ref<Certificate[]>([])
const selectedCert = ref<Certificate | null>(null)
const signature = ref('')
const hardwareAvailable = ref({ idCard: false, baik: false })
const signingMethod = ref<'certificate' | 'idcard' | 'baik'>('certificate')

// Computed
const canSign = computed(() => {
  if (signingMethod.value === 'certificate') {
    return selectedCert.value !== null
  }
  return hardwareAvailable.value.idCard || hardwareAvailable.value.baik
})

const stepTitle = computed(() => {
  const titles: Record<Step, string> = {
    init: 'Initializing...', 
    select: 'Select Certificate', 
    confirm: 'Confirm Signing', 
    password: 'Enter Password', 
    signing: 'Signing...', 
    success: 'Signed Successfully', 
    error: 'Error'
  }
  return titles[step.value]
})

// Initialize
onMounted(async () => {
  try {
    await install()
    await detectHardware()
    certificates.value = await listKeys()
    step.value = 'select'
  } catch (err) {
    step.value = 'error'
    emit('error', err as Error)
  }
})

async function detectHardware() {
  const [idCard, baik] = await Promise.all([
    isIDCardPlugged().catch(() => false),
    isBAIKTokenPlugged().catch(() => false)
  ])
  hardwareAvailable.value = { idCard, baik }
}

function selectCertificate(cert: Certificate) {
  selectedCert.value = cert
  signingMethod.value = 'certificate'
}

function useHardware(type: 'idcard' | 'baik') {
  signingMethod.value = type
  selectedCert.value = null
}

function goToConfirm() {
  if (!canSign.value) return
  step.value = 'confirm'
}

function goBack() {
  step.value = 'select'
}

async function performSigning() {
  try {
    step.value = signingMethod.value === 'certificate' ? 'password' : 'signing'

    let sig: string

    if (signingMethod.value === 'idcard') {
      sig = await signWithUSB(props.content)
    } else if (signingMethod.value === 'baik') {
      sig = await signWithBAIK(props.content)
    } else if (selectedCert.value) {
      const { id } = await loadKey(selectedCert.value)
      step.value = 'signing'
      const result = await signData(id, props.content)
      sig = typeof result === 'string' ? result : result.pkcs7_64
    } else {
      throw new Error('No signing method selected')
    }

    signature.value = sig
    step.value = 'success'
    emit('signed', sig, selectedCert.value!)
  } catch (err) {
    step.value = 'error'
    emit('error', err as Error)
  }
}

function reset() {
  step.value = 'select'
  selectedCert.value = null
  signature.value = ''
}

function cancel() {
  emit('cancel')
}

function downloadSignature() {
  if (!signature.value) return
  const blob = new Blob([atob(signature.value)], { type: 'application/pkcs7-signature' })
  const url = URL.createObjectURL(blob)
  const a = document.createElement('a')
  a.href = url
  a.download = `${props.documentTitle.replace(/\s+/g, '_')}.p7s`
  a.click()
  URL.revokeObjectURL(url)
}
</script>
```

--------------------------------

### Complete ESignature Usage Example

Source: https://github.com/sanjarbarakayev/vue-esignature/blob/main/docs/api/esignature.md

A comprehensive example demonstrating the typical workflow of using the ESignature class, from initialization to signing a document.

```APIDOC
## Complete Example

```ts
import { ESignature } from '@sanjarbarakayev/vue-esignature'

async function signDocument(content: string) {
  const esign = new ESignature()

  // Add production API key
  esign.addApiKey('myapp.com', 'MY_API_KEY')

  // Initialize
  await esign.install()

  // List certificates
  const certs = await esign.listAllUserKeys()
  if (certs.length === 0) {
    throw new Error('No certificates found')
  }

  // Load first certificate
  const { id } = await esign.loadKey(certs[0])

  // Sign content
  const signature = await esign.createPkcs7(id, content)

  return typeof signature === 'string'
    ? signature
    : signature.pkcs7_64
}
```
```

--------------------------------

### Complete ESignature Example

Source: https://github.com/sanjarbarakayev/vue-esignature/blob/main/docs/api/esignature.md

A comprehensive example demonstrating the typical workflow of signing a document using the ESignature class. It includes initialization, adding API keys, loading a certificate, and creating a PKCS#7 signature.

```typescript
import { ESignature } from '@sanjarbarakayev/vue-esignature'

async function signDocument(content: string) {
  const esign = new ESignature()

  // Add production API key
  esign.addApiKey('myapp.com', 'MY_API_KEY')

  // Initialize
  await esign.install()

  // List certificates
  const certs = await esign.listAllUserKeys()
  if (certs.length === 0) {
    throw new Error('No certificates found')
  }

  // Load first certificate
  const { id } = await esign.loadKey(certs[0])

  // Sign content
  const signature = await esign.createPkcs7(id, content)

  return typeof signature === 'string'
    ? signature
    : signature.pkcs7_64
}
```

--------------------------------

### Using qrcode.js with EIMZOMobile

Source: https://github.com/sanjarbarakayev/vue-esignature/blob/main/docs/guide/mobile.md

Example of how to integrate the qrcode.js library with the EIMZOMobile instance. Ensure the library is imported correctly and passed during instantiation.

```typescript
import QRCode from 'qrcode.js'

const mobile = new EIMZOMobile(SITE_ID, element, QRCode)
```

--------------------------------

### Initialize ESignature Class (TypeScript)

Source: https://github.com/sanjarbarakayev/vue-esignature/blob/main/docs/api/index.md

Shows how to instantiate and install the `ESignature` class for usage outside of Vue components or for class-based programming. This provides a direct way to access the signing functionalities.

```typescript
import { ESignature } from '@sanjarbarakayev/vue-esignature'

const esign = new ESignature()
await esign.install()
```

--------------------------------

### Vue E-Signature: Import and Setup

Source: https://github.com/sanjarbarakayev/vue-esignature/blob/main/docs/examples/basic-signing.md

This snippet demonstrates how to import necessary functions and types from the '@sanjarbarakayev/vue-esignature' library. It includes setting the locale and initializing the core composable `useESignature` to access its functionalities.

```typescript
import { useESignature, setLocale } from '@sanjarbarakayev/vue-esignature'
import type { Certificate } from '@sanjarbarakayev/vue-esignature'

setLocale('en') // Optional: set language

const { install, listKeys, loadKey, signData, isInstalled, isLoading, error } = useESignature()
```

--------------------------------

### Initialize E-IMZO Connection

Source: https://github.com/sanjarbarakayev/vue-esignature/blob/main/docs/api/esignature.md

Asynchronously initializes the connection to the E-IMZO service. This method must be called before any other ESignature operations. It throws an error if E-IMZO is not installed or the version is outdated.

```typescript
async install(): Promise<void>
```

```typescript
try {
  await esign.install()
  console.log('E-IMZO initialized')
} catch (error) {
  console.error('Failed to initialize:', error)
}
```

--------------------------------

### Vue E-Signature: Initialize E-IMZO

Source: https://github.com/sanjarbarakayev/vue-esignature/blob/main/docs/examples/basic-signing.md

This code snippet shows how to initialize the E-IMZO connection within a Vue component's `onMounted` lifecycle hook. It calls the `install()` function to establish the connection and then fetches the available certificates using `listKeys()`.

```typescript
onMounted(async () => {
  await install()
  certificates.value = await listKeys()
})
```

--------------------------------

### Vue ESignatureWidget Usage Example

Source: https://github.com/sanjarbarakayev/vue-esignature/blob/main/docs/demo/signing.md

Demonstrates how to integrate and use the ESignatureWidget component in a Vue.js application. It shows how to bind document content, handle signed events, and manage errors.

```vue
<script setup lang="ts">
import { ref } from 'vue'
import {
  ESignatureWidget,
  type Certificate
} from '@sanjarbarakayev/vue-esignature'

const documentContent = ref('Contract content to sign...')

function handleSigned(signature: string, certificate: Certificate) {
  console.log('Signed by:', certificate.CN)
  // Send signature to server
}

function handleError(error: Error) {
  console.error('Signing failed:', error.message)
}
</script>

<template>
  <ESignatureWidget
    :content="documentContent"
    document-title="Employment Contract"
    locale="en"
    :show-preview="true"
    :allow-multiple="false"
    @signed="handleSigned"
    @error="handleError"
    @cancel="handleCancel"
  />
</template>
```

--------------------------------

### Check E-IMZO Version

Source: https://github.com/sanjarbarakayev/vue-esignature/blob/main/docs/api/esignature.md

Asynchronously checks the installed version of E-IMZO. It returns a VersionInfo object containing major and minor version numbers. An error is thrown if the version is below the minimum required (3.37).

```typescript
async checkVersion(): Promise<VersionInfo>
```

```typescript
const version = await esign.checkVersion()
console.log(`E-IMZO v${version.major}.${version.minor}`)
```

--------------------------------

### Directly Import Vue E-Signature Composable

Source: https://github.com/sanjarbarakayev/vue-esignature/blob/main/docs/guide/installation.md

Import the `useESignature` composable directly within your Vue components' script setup. This allows for localized access to the signature functionalities.

```vue
<script setup lang="ts">
import { useESignature } from '@sanjarbarakayev/vue-esignature'

const esignature = useESignature()
</script>
```

--------------------------------

### Instantiate EIMZOMobile Constructor

Source: https://github.com/sanjarbarakayev/vue-esignature/blob/main/docs/api/e-imzo-mobile.md

Demonstrates how to create a new instance of the EIMZOMobile class. It requires a site ID, an HTML element for rendering, a QR code library constructor, and optional configuration options.

```typescript
new EIMZOMobile(
  siteId: string,
  element: HTMLElement,
  QRCodeLib: IQRCodeConstructor,
  options?: EIMZOMobileOptions
)
```

--------------------------------

### Configure API Keys via Plugin Options

Source: https://github.com/sanjarbarakayev/vue-esignature/blob/main/docs/guide/installation.md

Configure custom API keys for multiple domains when registering the Vue E-Signature plugin. This centralizes API key management for your application.

```typescript
app.use(VueESignature, {
  apiKeys: [
    { domain: 'yourdomain.com', key: 'YOUR_PRODUCTION_API_KEY' },
    { domain: 'staging.yourdomain.com', key: 'YOUR_STAGING_API_KEY' }
  ]
})
```

--------------------------------

### Register Vue E-Signature as a Vue Plugin

Source: https://github.com/sanjarbarakayev/vue-esignature/blob/main/docs/guide/installation.md

Register Vue E-Signature as a Vue plugin to make its functionalities globally available. This involves importing the plugin and optionally configuring API keys and auto-installation behavior.

```typescript
// main.ts
import { createApp } from 'vue'
import { VueESignature } from '@sanjarbarakayev/vue-esignature'
import App from './App.vue'

const app = createApp(App)

app.use(VueESignature, {
  // Optional: Add custom API keys for your domain
  apiKeys: [
    { domain: 'yourdomain.com', key: 'YOUR_API_KEY' }
  ],
  // Optional: Auto-initialize on plugin registration
  autoInstall: false
})

app.mount('#app')
```

--------------------------------

### Integrate qrcode.js with EIMZOMobile

Source: https://github.com/sanjarbarakayev/vue-esignature/blob/main/docs/api/e-imzo-mobile.md

Shows how to import and use the 'qrcode.js' library as the `QRCodeLib` when initializing EIMZOMobile.

```typescript
import QRCode from 'qrcode.js'

const mobile = new EIMZOMobile(siteId, element, QRCode)
```

--------------------------------

### Handle Document Signing with Vue E-Signature

Source: https://github.com/sanjarbarakayev/vue-esignature/blob/main/docs/guide/quick-start.md

Handles the document signing process when the 'Sign Document' button is clicked. It first loads the selected certificate (prompting for a password), then signs the document content using `signData`, and finally updates the signature state with the resulting PKCS#7 string. Includes loading and error handling.

```vue
<script setup lang="ts">
async function handleSign() {
  if (!selectedCert.value) return

  try {
    loading.value = true

    // Load the certificate (prompts for password)
    const { id } = await loadKey(selectedCert.value)

    // Sign the document
    const result = await signData(id, 'Document content to sign')
    signature.value = typeof result === 'string' ? result : result.pkcs7_64

  } catch (err) {
    console.error('Signing failed:', err)
    alert('Signing failed: ' + (err as Error).message)
  } finally {
    loading.value = false
  }
}
</script>
```

--------------------------------

### Server-Side API Endpoints for E-IMZO Signatures

Source: https://github.com/sanjarbarakayev/vue-esignature/blob/main/docs/examples/mobile-qr.md

This section provides examples of server-side API endpoints required for handling E-IMZO signatures. It includes a GET endpoint to retrieve existing signatures based on a document number and a POST endpoint to receive and store new signatures and their hashes after mobile confirmation.

```typescript
// /api/signatures/:documentNumber (GET)
app.get('/api/signatures/:documentNumber', async (req, res) => {
  const { documentNumber } = req.params

  const signature = await db.signatures.findOne({ documentNumber })

  res.json({
    signature: signature?.pkcs7 || null
  })
})

// E-IMZO callback endpoint
app.post('/api/eimzo/callback', async (req, res) => {
  const { documentNumber, signature, hash } = req.body

  // Verify signature
  // Store in database
  await db.signatures.create({
    documentNumber,
    pkcs7: signature,
    hash,
    signedAt: new Date()
  })

  res.json({ success: true })
})
```

--------------------------------

### Build and Preview Playground (Bash)

Source: https://github.com/sanjarbarakayev/vue-esignature/blob/main/playground/README.md

Commands to build the Vue E-Signature Playground for production and preview the built version. These commands use pnpm to manage the build and preview processes.

```bash
# Build the playground
pnpm playground:build

# Preview the built version
pnpm playground:preview
```

--------------------------------

### Install QR Code Libraries for Vue E-Signature

Source: https://github.com/sanjarbarakayev/vue-esignature/blob/main/docs/guide/mobile.md

Install a QR code generation library compatible with Vue E-Signature. Supported libraries include qrcode.js and qrcode. You can install them using npm.

```bash
npm install qrcode.js
```

```bash
npm install qrcode
```

--------------------------------

### Run Project Tests and Build (Bash)

Source: https://github.com/sanjarbarakayev/vue-esignature/blob/main/UPSTREAM.md

Commands to execute type checking, run tests, and build the project using pnpm. These commands are part of the verification process after updating TypeScript conversions.

```bash
pnpm typecheck
pnpm test:run
pnpm build
```

--------------------------------

### Create EIMZOMobile Instance with QR Code Library

Source: https://github.com/sanjarbarakayev/vue-esignature/blob/main/docs/guide/mobile.md

Instantiate the EIMZOMobile class, providing your site ID, the HTML element for the QR code, and your chosen QR code library. The library must conform to the IQRCode interface. Options for QR code dimensions can also be provided.

```typescript
import { EIMZOMobile } from '@sanjarbarakayev/vue-esignature'
import QRCode from 'qrcode.js' // or your preferred library

// Get your site ID from E-IMZO registration
const SITE_ID = 'YOUR_SITE_ID'

// Create instance with QR code element and library
const qrElement = document.getElementById('qrcode')!
const mobile = new EIMZOMobile(SITE_ID, qrElement, QRCode, {
  width: 256,
  height: 256
})
```

--------------------------------

### Initialize and Use ESignature Class

Source: https://github.com/sanjarbarakayev/vue-esignature/blob/main/README.md

Demonstrates direct usage of the ESignature class for signing operations. This includes initializing the class, adding API keys, installing the service, listing user keys, loading a key, and creating a PKCS7 signature. It's suitable for scenarios where the composable approach is not preferred.

```typescript
import { ESignature } from '@sanjarbarakayev/vue-esignature'

const signer = new ESignature()

// Add custom API keys
signer.addApiKey('myapp.example.com', 'API_KEY')

// Initialize
await signer.install()

// List certificates
const certs = await signer.listAllUserKeys()

// Load and sign
const { id } = await signer.loadKey(cert)
const signature = await signer.createPkcs7(id, data)
```

--------------------------------

### Make QR Code Method

Source: https://github.com/sanjarbarakayev/vue-esignature/blob/main/docs/api/e-imzo-mobile.md

The `makeQRCode` method generates and displays a QR code for document signing. It takes a document number and text content as input and returns the document hash and the full QR code data.

```typescript
makeQRCode(docNum: string, text: string): [string, string] | null
```

--------------------------------

### Install Vue E-Signature Plugin

Source: https://github.com/sanjarbarakayev/vue-esignature/blob/main/README.md

Install the Vue E-Signature package using npm, yarn, or pnpm. This package provides the necessary tools to integrate E-IMZO functionality into your Vue 3 application.

```bash
# npm
npm install @sanjarbarakayev/vue-esignature

# yarn
yarn add @sanjarbarakayev/vue-esignature

# pnpm
pnpm add @sanjarbarakayev/vue-esignature
```

--------------------------------

### Vue Try-Catch for E-Signature Installation

Source: https://github.com/sanjarbarakayev/vue-esignature/blob/main/docs/guide/error-handling.md

Demonstrates a basic try-catch block in Vue.js for handling potential errors during the e-signature installation process. It utilizes a composable function `useESignature` and logs any caught errors to the console. The error is automatically managed by the `error.value` from the composable.

```typescript
const { install, error } = useESignature()

async function initialize() {
  try {
    await install()
  } catch (err) {
    // Error is automatically set in error.value
    console.error('Initialization failed:', err)
  }
}
```

--------------------------------

### Install Vue E-Signature Plugin with API Keys

Source: https://context7.com/sanjarbarakayev/vue-esignature/llms.txt

Register the Vue E-Signature plugin in your main application file. You can perform a basic installation or provide an array of API keys for domain authorization, which is necessary for certain E-IMZO functionalities.

```typescript
import { createApp } from 'vue'
import { VueESignature } from '@sanjarbarakayev/vue-esignature'
import App from './App.vue'

const app = createApp(App)

// Basic installation
app.use(VueESignature)

// With custom API keys for your domains
app.use(VueESignature, {
  apiKeys: [
    { domain: 'myapp.example.com', key: 'YOUR_API_KEY_HERE' },
    { domain: 'api.example.com', key: 'ANOTHER_API_KEY' }
  ]
})

app.mount('#app')
```

--------------------------------

### List Available Digital Certificates

Source: https://github.com/sanjarbarakayev/vue-esignature/blob/main/docs/api/composable.md

Shows how to retrieve a list of all available digital certificates using the 'listKeys' method. This is typically done after initializing E-IMZO to allow users to select a certificate for signing.

```typescript
const certs = await listKeys()
console.log(`Found ${certs.length} certificates`)
```

--------------------------------

### Handle Connection Errors in Vue E-Signature

Source: https://github.com/sanjarbarakayev/vue-esignature/blob/main/docs/guide/error-handling.md

This code snippet demonstrates how to catch and handle connection errors, which typically occur when the E-IMZO application is not running or not installed. It checks the error message for keywords related to connection issues and triggers a prompt to install the application if detected.

```typescript
try {
  await install()
} catch (error) {
  if (error.message.includes('Connection') || error.message.includes('соединения')) {
    // E-IMZO not installed or not running
    showInstallPrompt()
  }
}
```

--------------------------------

### Vue Global Error Handling Setup

Source: https://github.com/sanjarbarakayev/vue-esignature/blob/main/docs/guide/error-handling.md

Configures global error handling for a Vue.js application within the `main.ts` file. It assigns a custom error handler to `app.config.errorHandler`, which logs the error, component instance, and additional info to the console. This setup allows for centralized error logging and potential user notification.

```typescript
// main.ts
import { createApp } from 'vue'
import App from './App.vue'

const app = createApp(App)

app.config.errorHandler = (error, instance, info) => {
  // Log to monitoring service
  console.error('Global error:', error)
  console.error('Component:', instance)
  console.error('Info:', info)

  // Show user-friendly notification
  // ...
}

app.mount('#app')
```

--------------------------------

### ESignature Methods - Initialization and Version Check

Source: https://github.com/sanjarbarakayev/vue-esignature/blob/main/docs/api/esignature.md

Documentation for methods related to initializing the E-IMZO connection and checking its version.

```APIDOC
## Methods

### install()

```ts
async install(): Promise<void>
```

Initialize the E-IMZO connection. Must be called before any other operations.

**Throws:** Error if E-IMZO is not installed or version is outdated.

**Example:**
```ts
try {
  await esign.install()
  console.log('E-IMZO initialized')
} catch (error) {
  console.error('Failed to initialize:', error)
}
```

### checkVersion()

```ts
async checkVersion(): Promise<VersionInfo>
```

Check the installed E-IMZO version.

**Returns:** `VersionInfo` with `major` and `minor` properties.

**Throws:** Error if version is below minimum required (3.37).

**Example:**
```ts
const version = await esign.checkVersion()
console.log(`E-IMZO v${version.major}.${version.minor}`)
```
```