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()

// Identity & context (reactive in Vue / React / Svelte adapters)
extensionInfo          // { publicKey, name, version, displayName }
context.theme          // 'light' | 'dark'
context.locale         // 'de' | 'en' | ...
context.platform       // 'linux' | 'windows' | 'macos' | 'android' | 'ios'

// Table naming
getTableName('users')
client.getDependencyTableName(publicKey, extensionName, 'users')
client.parseTableName(fullTableName)

// Database (shortcuts and full DatabaseAPI)
await client.query(sql, params)
await client.execute(sql, params)
await client.database.queryOne(sql, params)
await client.database.transaction([{ sql, params }, ...])
await client.database.insert(table, data)
await client.database.update(table, data, where, whereParams)
await client.database.delete(table, where, whereParams)
await client.registerMigrationsAsync(extensionVersion, migrations)

// Drizzle ORM
const db = client.initializeDatabase({ users })
await db.select().from(users)

// Storage (key-value, scoped to the extension)
await client.storage.getItem(key)
await client.storage.setItem(key, value)
await client.storage.removeItem(key)
await client.storage.keys()
await client.storage.clear()

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

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

// Permissions (SDK boundary uses 'read' | 'write')
await client.permissions.checkDatabaseAsync(resource, 'read' | 'write')
await client.permissions.checkFilesystemAsync(path,    'read' | 'write')
await client.permissions.checkWebAsync(url)

// External requests (browser ext / CLI / external apps)
client.onExternalRequest('my-action', async (req) => ({ ok: true }))
await client.respondToExternalRequest(response)

// Lifecycle
client.onSetup(async () => { /* run migrations etc. */ })
await client.setupComplete()

Application Context

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

// In a Vue / React / Svelte adapter, `context` is reactive.
// In the plain JS client it's a plain getter (`client.context`).

const { context } = useHaexVaultSdk()

// Vue: context is a Ref<ApplicationContext | null>
const ctx = context.value

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

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

// In plain JS:
//   const client = createHaexVaultSdk()
//   await client.ready()
//   console.log(client.context?.theme)
//   client.on('haextension:context:changed', (e) => { /* ... */ })

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 (theme / locale / platform)
client.on(HAEXTENSION_EVENTS.CONTEXT_CHANGED, (event) => {
  const { theme, locale, platform } = event.data.context
  console.log('Context updated:', { theme, locale, platform })
})

// Sync notification: tables relevant to this extension have new data
client.on(HAEXTENSION_EVENTS.SYNC_TABLES_UPDATED, async (event) => {
  const tables = event.data?.tables ?? []
  const ourPrefix = client.getTableName('') // '<pubKey>__<extName>__'
  if (tables.some(t => t.startsWith(ourPrefix))) {
    await reloadDataAsync()
  }
})

// Search requests (when haex-vault routes a search to this extension)
client.on(HAEXTENSION_EVENTS.SEARCH_REQUEST, async (event) => {
  const { query, requestId } = event.data
  const results = await performSearch(query)
  await client.respondToSearch(requestId, results)
})

// External requests (from browser extension, CLI, other apps)
client.on(EXTERNAL_EVENTS.REQUEST, async (event) => {
  const { requestId, action, payload, publicKey } = event.data
  const data = await handle(action, payload)
  await client.respondToExternalRequest({ requestId, success: true, data })
})

←Publishing Database API→