@haex-space/vault-sdk 1.0.0

package/dist/client-O_JEOzfx.d.ts

@@ -0,0 +1,491 @@
+import { SqliteRemoteDatabase } from 'drizzle-orm/sqlite-proxy';
+
+/**
+ * Central event name definitions for HaexHub extensions
+ *
+ * Event Naming Schema: haextension:{subject}:{predicate}
+ *
+ * IMPORTANT: Tauri event names can only contain:
+ * - Alphanumeric characters (a-z, A-Z, 0-9)
+ * - Hyphens (-)
+ * - Slashes (/)
+ * - Colons (:)
+ * - Underscores (_)
+ *
+ * NO dots (.) allowed!
+ */
+declare const HAEXTENSION_EVENTS: {
+    /** Context (theme, locale, platform) has changed */
+    readonly CONTEXT_CHANGED: "haextension:context:changed";
+    /** Search request from HaexHub */
+    readonly SEARCH_REQUEST: "haextension:search:request";
+};
+type HaextensionEvent = typeof HAEXTENSION_EVENTS[keyof typeof HAEXTENSION_EVENTS];
+
+declare const DEFAULT_TIMEOUT = 30000;
+declare const TABLE_SEPARATOR = "__";
+interface HaexHubRequest {
+    method: string;
+    params: Record<string, unknown>;
+    timestamp: number;
+}
+interface HaexHubResponse<T = unknown> {
+    id: string;
+    result?: T;
+    error?: HaexHubError;
+}
+interface ExtensionInfo {
+    publicKey: string;
+    name: string;
+    version: string;
+    displayName?: string;
+    namespace?: string;
+}
+interface ApplicationContext {
+    theme: "light" | "dark" | "system";
+    locale: string;
+    platform: "linux" | "macos" | "ios" | "freebsd" | "dragonfly" | "netbsd" | "openbsd" | "solaris" | "android" | "windows" | undefined;
+}
+interface SearchQuery {
+    query: string;
+    filters?: Record<string, unknown>;
+    limit?: number;
+}
+interface SearchResult {
+    id: string;
+    title: string;
+    description?: string;
+    type: string;
+    data?: Record<string, unknown>;
+    score?: number;
+}
+declare enum PermissionStatus {
+    GRANTED = "granted",
+    DENIED = "denied",
+    ASK = "ask"
+}
+interface PermissionResponse {
+    status: PermissionStatus;
+    permanent: boolean;
+}
+interface DatabasePermission {
+    extensionId: string;
+    resource: string;
+    operation: "read" | "write";
+    path: string;
+}
+interface DatabasePermissionRequest {
+    resource: string;
+    operation: "read" | "write";
+    reason?: string;
+}
+interface DatabaseQueryParams {
+    query: string;
+    params?: unknown[];
+}
+interface DatabaseQueryResult {
+    rows: unknown[];
+    columns?: string[];
+    rowsAffected: number;
+    lastInsertId?: number;
+}
+interface DatabaseExecuteParams {
+    statements: string[];
+}
+interface DatabaseTableInfo {
+    name: string;
+    columns: DatabaseColumnInfo[];
+}
+interface DatabaseColumnInfo {
+    name: string;
+    type: string;
+    notNull: boolean;
+    defaultValue?: unknown;
+    primaryKey: boolean;
+}
+interface HaexHubEvent {
+    type: string;
+    data: unknown;
+    timestamp: number;
+}
+interface ContextChangedEvent extends HaexHubEvent {
+    type: typeof HAEXTENSION_EVENTS.CONTEXT_CHANGED;
+    data: {
+        context: ApplicationContext;
+    };
+}
+interface SearchRequestEvent extends HaexHubEvent {
+    type: typeof HAEXTENSION_EVENTS.SEARCH_REQUEST;
+    data: {
+        query: SearchQuery;
+        requestId: string;
+    };
+}
+type EventCallback = (event: HaexHubEvent) => void;
+interface ExtensionManifest {
+    name: string;
+    version: string;
+    author?: string | null;
+    entry?: string | null;
+    icon?: string | null;
+    publicKey: string;
+    signature: string;
+    permissions: {
+        database?: any[];
+        filesystem?: any[];
+        http?: any[];
+        shell?: any[];
+    };
+    homepage?: string | null;
+    description?: string | null;
+    singleInstance?: boolean | null;
+    displayMode?: "auto" | "window" | "iframe" | null;
+}
+interface HaexHubConfig {
+    debug?: boolean;
+    timeout?: number;
+    /** Extension manifest data (auto-injected by framework integrations) */
+    manifest?: ExtensionManifest;
+}
+interface WebRequestOptions {
+    method?: "GET" | "POST" | "PUT" | "DELETE" | "PATCH" | "HEAD" | "OPTIONS";
+    headers?: Record<string, string>;
+    body?: string | ArrayBuffer | Blob;
+    timeout?: number;
+}
+interface WebResponse {
+    status: number;
+    statusText: string;
+    headers: Record<string, string>;
+    body: ArrayBuffer;
+    url: string;
+}
+declare enum ErrorCode {
+    TIMEOUT = "TIMEOUT",
+    NOT_IN_IFRAME = "NOT_IN_IFRAME",
+    UNAUTHORIZED_ORIGIN = "UNAUTHORIZED_ORIGIN",
+    PERMISSION_DENIED = "PERMISSION_DENIED",
+    INVALID_PUBLIC_KEY = "INVALID_PUBLIC_KEY",
+    INVALID_EXTENSION_NAME = "INVALID_EXTENSION_NAME",
+    INVALID_TABLE_NAME = "INVALID_TABLE_NAME",
+    INVALID_PARAMS = "INVALID_PARAMS",
+    EXTENSION_NOT_INITIALIZED = "EXTENSION_NOT_INITIALIZED",
+    EXTENSION_INFO_UNAVAILABLE = "EXTENSION_INFO_UNAVAILABLE",
+    METHOD_NOT_FOUND = "METHOD_NOT_FOUND",
+    INTERNAL_ERROR = "INTERNAL_ERROR",
+    DATABASE_ERROR = "DATABASE_ERROR",
+    WEB_ERROR = "WEB_ERROR"
+}
+interface HaexHubError {
+    code: ErrorCode;
+    message: string;
+    details?: Record<string, unknown>;
+}
+declare class HaexHubError extends Error {
+    code: ErrorCode;
+    messageKey: string;
+    details?: Record<string, unknown> | undefined;
+    constructor(code: ErrorCode, messageKey: string, details?: Record<string, unknown> | undefined);
+    /**
+     * Get localized error message
+     * @param locale - Locale code (e.g., 'en', 'de')
+     * @param translations - Translation object
+     */
+    getLocalizedMessage(locale?: string, translations?: Record<string, Record<string, string>>): string;
+    toJSON(): {
+        code: ErrorCode;
+        message: string;
+        details: Record<string, unknown> | undefined;
+    };
+}
+
+declare class StorageAPI {
+    private client;
+    constructor(client: HaexVaultClient);
+    getItem(key: string): Promise<string | null>;
+    setItem(key: string, value: string): Promise<void>;
+    removeItem(key: string): Promise<void>;
+    clear(): Promise<void>;
+    keys(): Promise<string[]>;
+}
+
+declare class DatabaseAPI {
+    private client;
+    constructor(client: HaexVaultClient);
+    query<T>(query: string, params?: unknown[]): Promise<T[]>;
+    queryOne<T = unknown>(query: string, params?: unknown[]): Promise<T | null>;
+    execute(query: string, params?: unknown[]): Promise<DatabaseQueryResult>;
+    transaction(statements: string[]): Promise<void>;
+    createTable(tableName: string, columns: string): Promise<void>;
+    dropTable(tableName: string): Promise<void>;
+    /**
+     * Registers extension migrations with HaexVault for CRDT synchronization
+     * HaexVault will validate and execute these migrations, ensuring only
+     * tables with the correct prefix are manipulated
+     * @param extensionVersion - The version of the extension
+     * @param migrations - Array of migration objects with name and SQL content
+     * @returns Promise that resolves when migrations are registered
+     */
+    registerMigrationsAsync(extensionVersion: string, migrations: Array<{
+        name: string;
+        sql: string;
+    }>): Promise<void>;
+    insert(tableName: string, data: Record<string, unknown>): Promise<number>;
+    update(tableName: string, data: Record<string, unknown>, where: string, whereParams?: unknown[]): Promise<number>;
+    delete(tableName: string, where: string, whereParams?: unknown[]): Promise<number>;
+    count(tableName: string, where?: string, whereParams?: unknown[]): Promise<number>;
+}
+
+interface SaveFileOptions {
+    /**
+     * The default filename to suggest
+     */
+    defaultPath?: string;
+    /**
+     * The title of the save dialog
+     */
+    title?: string;
+    /**
+     * File filters for the dialog
+     */
+    filters?: Array<{
+        name: string;
+        extensions: string[];
+    }>;
+}
+interface SaveFileResult {
+    /**
+     * The path where the file was saved
+     */
+    path: string;
+    /**
+     * Whether the operation was successful
+     */
+    success: boolean;
+}
+interface OpenFileOptions {
+    /**
+     * The filename for the temporary file
+     */
+    fileName: string;
+    /**
+     * Optional MIME type for the file
+     */
+    mimeType?: string;
+}
+interface OpenFileResult {
+    /**
+     * Whether the operation was successful
+     */
+    success: boolean;
+}
+interface ShowImageOptions {
+    /**
+     * The data URL of the image (base64 encoded)
+     */
+    dataUrl: string;
+}
+interface ShowImageResult {
+    /**
+     * Whether the operation was successful
+     */
+    success: boolean;
+}
+declare class FilesystemAPI {
+    private client;
+    constructor(client: HaexVaultClient);
+    /**
+     * Opens a save file dialog and saves the provided data to the selected location
+     * @param data The file data as Uint8Array
+     * @param options Options for the save dialog
+     * @returns The path where the file was saved, or null if cancelled
+     */
+    saveFileAsync(data: Uint8Array, options?: SaveFileOptions): Promise<SaveFileResult | null>;
+    /**
+     * Opens a file with the system's default viewer
+     * @param data The file data as Uint8Array
+     * @param options Options for opening the file
+     * @returns The result of the operation
+     */
+    openFileAsync(data: Uint8Array, options: OpenFileOptions): Promise<OpenFileResult>;
+    /**
+     * Shows an image using a data URL (safe, read-only viewing)
+     * This is safe to use without special permissions as it only displays images
+     * and doesn't execute any code or open files with external applications
+     * @param options Options containing the data URL
+     * @returns The result of the operation
+     */
+    showImageAsync(options: ShowImageOptions): Promise<ShowImageResult>;
+}
+
+declare class WebAPI {
+    private client;
+    constructor(client: HaexVaultClient);
+    /**
+     * Performs a web request through the HaexHub host application
+     * @param url The URL to fetch
+     * @param options Request options (method, headers, body, timeout)
+     * @returns Promise resolving to the web response
+     */
+    fetchAsync(url: string, options?: WebRequestOptions): Promise<WebResponse>;
+    /**
+     * Convenience method for JSON requests
+     */
+    fetchJsonAsync<T = unknown>(url: string, options?: WebRequestOptions): Promise<T>;
+    /**
+     * Convenience method for text requests
+     */
+    fetchTextAsync(url: string, options?: WebRequestOptions): Promise<string>;
+    /**
+     * Convenience method for blob requests
+     */
+    fetchBlobAsync(url: string, options?: WebRequestOptions): Promise<Blob>;
+    /**
+     * Opens a URL in the user's default browser
+     * @param url The URL to open
+     */
+    openAsync(url: string): Promise<void>;
+    private arrayBufferToBase64;
+    private blobToBase64;
+    private base64ToArrayBuffer;
+}
+
+declare class PermissionsAPI {
+    private client;
+    constructor(client: HaexVaultClient);
+    /**
+     * Checks if the extension has permission for a database operation
+     * @param resource The database resource (table name or "*" for all tables)
+     * @param operation The operation type ("read" or "write")
+     * @returns Promise<boolean> indicating if permission is granted
+     */
+    checkDatabaseAsync(resource: string, operation: "read" | "write"): Promise<boolean>;
+    /**
+     * Checks if the extension has permission for a web request
+     * @param url The URL to check (e.g., "https://example.com/path")
+     * @returns Promise<boolean> indicating if permission is granted
+     * @note Method/operation is not checked - permissions apply to all HTTP methods
+     */
+    checkWebAsync(url: string): Promise<boolean>;
+    /**
+     * Checks if the extension has permission for a filesystem operation
+     * @param path The file or directory path
+     * @param operation The operation type ("read" or "write")
+     * @returns Promise<boolean> indicating if permission is granted
+     */
+    checkFilesystemAsync(path: string, operation: "read" | "write"): Promise<boolean>;
+}
+
+declare class HaexVaultClient {
+    private config;
+    private pendingRequests;
+    private eventListeners;
+    private messageHandler;
+    private initialized;
+    private requestCounter;
+    private _extensionInfo;
+    private _context;
+    private reactiveSubscribers;
+    private isNativeWindow;
+    private readyPromise;
+    private resolveReady;
+    private setupPromise;
+    private setupHook;
+    private _setupCompleted;
+    orm: SqliteRemoteDatabase<Record<string, unknown>> | null;
+    readonly storage: StorageAPI;
+    readonly database: DatabaseAPI;
+    readonly filesystem: FilesystemAPI;
+    readonly web: WebAPI;
+    readonly permissions: PermissionsAPI;
+    constructor(config?: HaexHubConfig);
+    /**
+     * Gibt ein Promise zurück, das aufgelöst wird, sobald der Client
+     * initialisiert ist und Extension-Infos empfangen hat.
+     */
+    ready(): Promise<void>;
+    /**
+     * Gibt zurück, ob das Setup bereits abgeschlossen wurde.
+     */
+    get setupCompleted(): boolean;
+    /**
+     * Registriert eine Setup-Funktion, die nach der Initialisierung ausgeführt wird.
+     * Diese Funktion sollte für Aufgaben wie Tabellenerstellung, Migrationen, etc. verwendet werden.
+     * @param setupFn Die Setup-Funktion, die ausgeführt werden soll
+     */
+    onSetup(setupFn: () => Promise<void>): void;
+    /**
+     * Gibt ein Promise zurück, das aufgelöst wird, sobald der Client vollständig eingerichtet ist.
+     * Dies umfasst die Initialisierung UND das Setup (z.B. Tabellenerstellung).
+     * Falls kein Setup-Hook registriert wurde, entspricht dies ready().
+     */
+    setupComplete(): Promise<void>;
+    private runSetupAsync;
+    /**
+     * Initialisiert die Drizzle-Datenbankinstanz.
+     * Muss nach der Definition des Schemas aufgerufen werden.
+     * @param schema Das Drizzle-Schemaobjekt (mit bereits geprefixten Tabellennamen).
+     * @returns Die typsichere Drizzle-Datenbankinstanz.
+     */
+    initializeDatabase<T extends Record<string, unknown>>(schema: T): SqliteRemoteDatabase<T>;
+    get extensionInfo(): ExtensionInfo | null;
+    get context(): ApplicationContext | null;
+    subscribe(callback: () => void): () => void;
+    private notifySubscribers;
+    getDependencies(): Promise<ExtensionInfo[]>;
+    getTableName(tableName: string): string;
+    getDependencyTableName(publicKey: string, extensionName: string, tableName: string): string;
+    parseTableName(fullTableName: string): {
+        publicKey: string;
+        extensionName: string;
+        tableName: string;
+    } | null;
+    /**
+     * Execute a raw SQL query (SELECT)
+     * Returns rows as an array of objects
+     */
+    query<T = Record<string, unknown>>(sql: string, params?: unknown[]): Promise<T[]>;
+    /**
+     * Alias for query() - more intuitive for SELECT statements
+     */
+    select<T = Record<string, unknown>>(sql: string, params?: unknown[]): Promise<T[]>;
+    /**
+     * Execute a raw SQL statement (INSERT, UPDATE, DELETE, CREATE, etc.)
+     * Returns rowsAffected and lastInsertId
+     */
+    execute(sql: string, params?: unknown[]): Promise<{
+        rowsAffected: number;
+        lastInsertId?: number;
+    }>;
+    /**
+     * Registers extension migrations with HaexVault for CRDT synchronization
+     * HaexVault will validate and execute these migrations
+     * @param extensionVersion - The version of the extension
+     * @param migrations - Array of migration objects with name and SQL content
+     * @returns Promise that resolves when migrations are registered
+     */
+    registerMigrationsAsync(extensionVersion: string, migrations: Array<{
+        name: string;
+        sql: string;
+    }>): Promise<void>;
+    requestDatabasePermission(request: DatabasePermissionRequest): Promise<PermissionResponse>;
+    checkDatabasePermission(resource: string, operation: "read" | "write"): Promise<boolean>;
+    respondToSearch(requestId: string, results: SearchResult[]): Promise<void>;
+    request<T = unknown>(method: string, params?: Record<string, unknown>): Promise<T>;
+    private postMessage;
+    private invoke;
+    on(eventType: string, callback: EventCallback): void;
+    off(eventType: string, callback: EventCallback): void;
+    destroy(): void;
+    private init;
+    private handleMessage;
+    private handleEvent;
+    private emitEvent;
+    private generateRequestId;
+    private validatePublicKey;
+    private validateExtensionName;
+    private validateTableName;
+    private log;
+}
+
+export { type ApplicationContext as A, type ContextChangedEvent as C, DatabaseAPI as D, type ExtensionInfo as E, FilesystemAPI as F, type HaexHubConfig as H, PermissionsAPI as P, StorageAPI as S, TABLE_SEPARATOR as T, WebAPI as W, HaexVaultClient as a, type HaexHubRequest as b, type HaexHubResponse as c, type HaexHubEvent as d, type EventCallback as e, type PermissionResponse as f, type DatabasePermission as g, type DatabasePermissionRequest as h, type DatabaseQueryParams as i, type DatabaseQueryResult as j, type DatabaseExecuteParams as k, type DatabaseTableInfo as l, type DatabaseColumnInfo as m, type SearchQuery as n, type SearchResult as o, type SearchRequestEvent as p, type WebRequestOptions as q, type WebResponse as r, PermissionStatus as s, ErrorCode as t, DEFAULT_TIMEOUT as u, HaexHubError as v, HAEXTENSION_EVENTS as w, type HaextensionEvent as x };

package/dist/index.d.mts

@@ -0,0 +1,124 @@
+import { H as HaexHubConfig, a as HaexVaultClient } from './client-O_JEOzfx.mjs';
+export { A as ApplicationContext, C as ContextChangedEvent, u as DEFAULT_TIMEOUT, D as DatabaseAPI, m as DatabaseColumnInfo, k as DatabaseExecuteParams, g as DatabasePermission, h as DatabasePermissionRequest, i as DatabaseQueryParams, j as DatabaseQueryResult, l as DatabaseTableInfo, t as ErrorCode, e as EventCallback, E as ExtensionInfo, F as FilesystemAPI, w as HAEXTENSION_EVENTS, v as HaexHubError, d as HaexHubEvent, b as HaexHubRequest, c as HaexHubResponse, x as HaextensionEvent, f as PermissionResponse, s as PermissionStatus, P as PermissionsAPI, n as SearchQuery, p as SearchRequestEvent, o as SearchResult, T as TABLE_SEPARATOR, W as WebAPI, q as WebRequestOptions, r as WebResponse } from './client-O_JEOzfx.mjs';
+export { HaextensionConfig } from './node.mjs';
+import 'drizzle-orm/sqlite-proxy';
+
+/**
+ * localStorage Polyfill for HaexHub Extensions
+ *
+ * Provides an in-memory fallback when localStorage is blocked
+ * due to custom protocol restrictions (haex-extension://)
+ */
+declare function installLocalStoragePolyfill(): void;
+/**
+ * sessionStorage Polyfill for HaexHub Extensions
+ *
+ * Provides a no-op implementation as session state doesn't work
+ * reliably in custom protocol contexts
+ */
+declare function installSessionStoragePolyfill(): void;
+
+/**
+ * Cookie Polyfill for HaexHub Extensions
+ *
+ * Provides an in-memory cookie implementation when cookies are blocked
+ * due to custom protocol restrictions (haex-extension://)
+ */
+declare function installCookiePolyfill(): void;
+
+/**
+ * History API Polyfill for HaexHub Extensions
+ *
+ * Works around SecurityError when using pushState/replaceState
+ * in custom protocol contexts (haex-extension://)
+ *
+ * Falls back to hash-based routing when necessary
+ */
+declare function installHistoryPolyfill(): void;
+
+/**
+ * Base Tag Polyfill
+ * Dynamically injects <base> tag for SPA routing in custom protocol
+ */
+declare global {
+    interface Window {
+        __HAEXHUB_BASE_TAG_INSTALLING__?: boolean;
+    }
+}
+/**
+ * Installs the base tag by extracting the base path from window.location
+ * Works with haex-extension:// protocol URLs
+ */
+declare function installBaseTag(): void;
+
+/**
+ * HaexHub Extension Polyfills
+ *
+ * Auto-initializing polyfills for localStorage, cookies, and history API
+ * that work around restrictions in custom protocol contexts (haex-extension://)
+ *
+ * These polyfills are automatically installed when you import the SDK:
+ *
+ * ```typescript
+ * import { createHaexVaultClient } from '@haex-space/vault-sdk';
+ * // Polyfills are active!
+ * ```
+ *
+ * You can also install them manually:
+ *
+ * ```typescript
+ * import { installPolyfills } from '@haexhub/sdk/polyfills';
+ * installPolyfills();
+ * ```
+ */
+
+/**
+ * Install all HaexHub polyfills
+ *
+ * This function is called automatically when the SDK is imported.
+ * You usually don't need to call this manually.
+ */
+declare function installPolyfills(): void;
+
+/**
+ * Central request method name definitions for HaexHub SDK
+ *
+ * Request Naming Schema: haextension:{subject}:{action}
+ *
+ * These are used for client.request() calls between extensions and HaexHub
+ */
+declare const HAEXTENSION_METHODS: {
+    readonly context: {
+        readonly get: "haextension:context:get";
+    };
+    readonly database: {
+        readonly query: "haextension:database:query";
+        readonly execute: "haextension:database:execute";
+        readonly transaction: "haextension:database:transaction";
+        readonly registerMigrations: "haextension:database:register-migrations";
+    };
+    readonly filesystem: {
+        readonly saveFile: "haextension:filesystem:save-file";
+        readonly openFile: "haextension:filesystem:open-file";
+        readonly showImage: "haextension:filesystem:show-image";
+    };
+    readonly storage: {
+        readonly getItem: "haextension:storage:get-item";
+        readonly setItem: "haextension:storage:set-item";
+        readonly removeItem: "haextension:storage:remove-item";
+        readonly clear: "haextension:storage:clear";
+        readonly keys: "haextension:storage:keys";
+    };
+    readonly web: {
+        readonly fetch: "haextension:web:fetch";
+    };
+    readonly application: {
+        readonly open: "haextension:application:open";
+    };
+};
+type DeepValues<T> = T extends object ? T[keyof T] extends string ? T[keyof T] : T[keyof T] extends object ? DeepValues<T[keyof T]> : never : never;
+type HaextensionMethod = DeepValues<typeof HAEXTENSION_METHODS>;
+
+declare function createHaexVaultClient(config?: HaexHubConfig): HaexVaultClient;
+
+export { HAEXTENSION_METHODS, HaexHubConfig, HaexVaultClient, type HaextensionMethod, createHaexVaultClient, installBaseTag, installCookiePolyfill, installHistoryPolyfill, installLocalStoragePolyfill, installPolyfills, installSessionStoragePolyfill };