SDK Overview

Complete reference for the haex-vault SDK APIs and framework integrations.

Overview

The haex-vault SDK provides a complete API for building extensions. It includes database access, storage, filesystem operations, web requests, and more.

Database API

Query and mutate SQLite data with migrations and Drizzle ORM

Storage API

Simple key-value storage for settings and preferences

Filesystem API

Save and open files through native dialogs

Web API

Make HTTP requests to external APIs

Installation

Install the SDK using your preferred package manager:

npm install @haex-space/vault-sdk

Framework Setup

The SDK provides adapters for popular frameworks. Choose your framework below:

Setup

<script setup lang="ts">
import { useHaexVaultSdk } from '@haex-space/vault-sdk/vue'
import manifest from '../haextension/manifest.json'

// Initialize SDK with manifest
const { client, context, extensionInfo, getTableName } = useHaexVaultSdk({
  manifest,
  debug: globalThis._importMeta_.env.DEV
})

// Watch for context changes (theme/locale)
watch(() => context.value, (ctx) => {
  if (ctx) {
    document.documentElement.classList.toggle('dark', ctx.theme === 'dark')
  }
}, { immediate: true })
</script>

Usage

<script setup lang="ts">
import { useHaexVaultSdk } from '@haex-space/vault-sdk/vue'

const { client, context, getTableName } = useHaexVaultSdk()

// Access context - reactive refs
const theme = computed(() => context.value?.theme)     // 'light' | 'dark'
const locale = computed(() => context.value?.locale)   // 'en', 'de', etc.
const platform = computed(() => context.value?.platform) // 'linux', 'windows', 'macos', 'android', 'ios', etc.

// Database operations with namespaced table names
async function loadData() {
  const tableName = getTableName('users')
  const users = await client.query(`SELECT * FROM ${tableName}`)
  console.log(users)
}
</script>

Client API Overview

The client provides access to all SDK features:

const { client, extensionInfo, context, getTableName } = useHaexVaultSdk()

// Extension info (reactive in Vue/React/Svelte)
extensionInfo          // { publicKey, name, version }
getTableName('users')  // Prefixed table name

// Context (reactive)
context.theme          // 'light' | 'dark'
context.locale         // 'en', 'de', etc.
context.platform       // 'linux', 'windows', 'macos', 'android', 'ios'

// Database
await client.query(sql, params)
await client.execute(sql, params)
await client.database.insert(table, data)
await client.database.update(table, data, where, whereParams)
await client.database.delete(table, where, whereParams)

// Storage
await client.storage.get(key)
await client.storage.set(key, value)
await client.storage.remove(key)

// Filesystem
await client.filesystem.saveFileAsync(data, options)
await client.filesystem.openFileAsync(options)

// Web
await client.web.fetchAsync(url, options)
await client.web.openAsync(url)

// Permissions
await client.permissions.checkDatabaseAsync(table, operation)
await client.permissions.checkFilesystemAsync(path, operation)
await client.permissions.checkWebAsync(url)

Application Context

Access the current theme, locale, and platform. The context updates automatically when the user changes settings.

const { context } = useHaexVaultSdk()

// Access current context (reactive ref in Vue)
const ctx = context.value

// Available properties
ctx.theme    // 'light' | 'dark'
ctx.locale   // 'en' | 'de' | ...
ctx.platform // 'linux' | 'windows' | 'macos' | 'android' | 'ios'

// React to context changes (Vue)
watch(() => context.value?.theme, (theme) => {
  console.log('Theme changed:', theme)
  document.documentElement.classList.toggle('dark', theme === 'dark')
})

watch(() => context.value?.platform, (platform) => {
  console.log('Platform:', platform)
  // Adapt UI for mobile/desktop
})

theme

Current theme: light, dark, or system

locale

Current locale code (en, de, etc.)

platform

Operating system: windows, macos, linux, ios, android

Events

Listen for events from haex-vault:

import { HAEXTENSION_EVENTS, EXTERNAL_EVENTS } from '@haex-space/vault-sdk'

const { client } = useHaexVaultSdk()

// Listen for context changes
client.on(HAEXTENSION_EVENTS.CONTEXT_CHANGED, (event) => {
  const { theme, locale, platform } = event.data.context
  console.log('Context updated:', { theme, locale, platform })
})

// Listen for search requests (if extension supports search)
client.on(HAEXTENSION_EVENTS.SEARCH_REQUEST, async (event) => {
  const { query, requestId } = event.data

  // Perform search
  const results = await performSearch(query)

  // Send results back
  await client.respondToSearch(requestId, results)
})

// Listen for external requests (from browser extensions, CLI tools, etc.)
client.on(EXTERNAL_EVENTS.REQUEST, async (event) => {
  const { clientId, action, payload, requestId } = event.data

  // Handle the external request
  const response = await handleExternalRequest(action, payload)

  // Send response back
  await client.respondToExternalRequest(requestId, response)
})

←Publishing Database API→