@stvor/sdk 2.4.1 → 3.0.0

package/dist/ratchet/tofu.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Generate a SHA-256 fingerprint for a given public key.
+ * @param publicKey - The public key to fingerprint.
+ * @returns The fingerprint as a hex string.
+ */
+export declare function generateFingerprint(publicKey: Uint8Array): string;
+/**
+ * Store the fingerprint in the database.
+ * @param userId - The user ID associated with the fingerprint.
+ * @param fingerprint - The fingerprint to store.
+ */
+export declare function storeFingerprint(userId: string, fingerprint: string): Promise<void>;
+/**
+ * Verify the fingerprint against the stored value.
+ * @param userId - The user ID associated with the fingerprint.
+ * @param fingerprint - The fingerprint to verify.
+ * @returns True if the fingerprint matches, false otherwise.
+ */
+export declare function verifyFingerprint(userId: string, fingerprint: string): Promise<boolean>;
+/**
+ * Honest TOFU Limitations
+ *
+ * 1. First-session MITM risk: The first connection assumes trust.
+ * 2. Fingerprint mismatches result in hard failure.
+ * 3. No automatic recovery from key substitution attacks.
+ */
+export declare function handleFingerprintMismatch(userId: string): void;

package/dist/ratchet/tofu.js

@@ -0,0 +1,62 @@
+import { createHash } from 'crypto';
+import { Pool } from 'pg';
+// PostgreSQL connection pool
+const pool = new Pool({
+    connectionString: process.env.DATABASE_URL, // Ensure DATABASE_URL is set in the environment
+});
+/**
+ * Generate a SHA-256 fingerprint for a given public key.
+ * @param publicKey - The public key to fingerprint.
+ * @returns The fingerprint as a hex string.
+ */
+export function generateFingerprint(publicKey) {
+    const hash = createHash('sha256');
+    hash.update(publicKey);
+    return hash.digest('hex');
+}
+/**
+ * Store the fingerprint in the database.
+ * @param userId - The user ID associated with the fingerprint.
+ * @param fingerprint - The fingerprint to store.
+ */
+export async function storeFingerprint(userId, fingerprint) {
+    const client = await pool.connect();
+    try {
+        await client.query('INSERT INTO fingerprints (user_id, fingerprint) VALUES ($1, $2) ON CONFLICT (user_id) DO UPDATE SET fingerprint = $2', [userId, fingerprint]);
+    }
+    finally {
+        client.release();
+    }
+}
+/**
+ * Verify the fingerprint against the stored value.
+ * @param userId - The user ID associated with the fingerprint.
+ * @param fingerprint - The fingerprint to verify.
+ * @returns True if the fingerprint matches, false otherwise.
+ */
+export async function verifyFingerprint(userId, fingerprint) {
+    const client = await pool.connect();
+    try {
+        const result = await client.query('SELECT fingerprint FROM fingerprints WHERE user_id = $1', [userId]);
+        if (result.rows.length === 0) {
+            // First use: store the fingerprint
+            await storeFingerprint(userId, fingerprint);
+            return true;
+        }
+        return result.rows[0].fingerprint === fingerprint;
+    }
+    finally {
+        client.release();
+    }
+}
+/**
+ * Honest TOFU Limitations
+ *
+ * 1. First-session MITM risk: The first connection assumes trust.
+ * 2. Fingerprint mismatches result in hard failure.
+ * 3. No automatic recovery from key substitution attacks.
+ */
+export function handleFingerprintMismatch(userId) {
+    console.error(`SECURITY ALERT: Fingerprint mismatch detected for user ${userId}`);
+    throw new Error('Fingerprint mismatch detected. Connection aborted.');
+}

package/dist/src/facade/app.cjs

@@ -0,0 +1,29 @@
+'use strict';
+
+// Auto-generated CommonJS wrapper for src/facade/app.js
+// This allows `require('@stvor/sdk')` to work alongside ESM `import`.
+
+const mod = require('module');
+const url = require('url');
+
+// Use dynamic import to load the ESM module
+let _cached;
+async function _load() {
+  if (!_cached) {
+    _cached = await import(url.pathToFileURL(__filename.replace(/\.cjs$/, '.js')).href);
+  }
+  return _cached;
+}
+
+// For simple CJS usage, expose a promise-based loader
+module.exports = new Proxy({ load: _load }, {
+  get(target, prop) {
+    if (prop === '__esModule') return true;
+    if (prop === 'then') return undefined; // prevent treating as thenable
+    if (prop === 'load') return _load;
+    if (prop === 'default') {
+      return _load().then(m => m.default);
+    }
+    return _load().then(m => m[prop]);
+  }
+});

package/dist/src/facade/app.d.ts

@@ -0,0 +1,105 @@
+import type { StvorAppConfig, UserId, MessageContent } from './types.js';
+import { RelayClient } from './relay-client.js';
+type MessageHandler = (from: UserId, msg: string | Uint8Array) => void;
+type UserAvailableHandler = (userId: UserId) => void;
+export declare class StvorFacadeClient {
+    readonly userId: UserId;
+    private readonly relay;
+    private readonly defaultTimeout;
+    private crypto;
+    private handlers;
+    private userAvailableHandlers;
+    private knownPubKeys;
+    private pendingKeyResolvers;
+    constructor(userId: UserId, relay: RelayClient, defaultTimeout?: number);
+    private handleRelayMessage;
+    internalInitialize(): Promise<void>;
+    /**
+     * Check if a user's public key is available locally
+     */
+    isUserAvailable(userId: UserId): boolean;
+    /**
+     * Get list of all known users (whose public keys we have)
+     */
+    getAvailableUsers(): UserId[];
+    /**
+     * Wait until a specific user's public key becomes available.
+     * This is the recommended way to ensure you can send messages.
+     *
+     * @param userId - The user to wait for
+     * @param timeoutMs - Maximum time to wait (default: 10000ms)
+     * @throws StvorError with RECIPIENT_TIMEOUT if timeout expires
+     *
+     * @example
+     * ```typescript
+     * await alice.waitForUser('bob@example.com');
+     * await alice.send('bob@example.com', 'Hello!');
+     * ```
+     */
+    waitForUser(userId: UserId, timeoutMs?: number): Promise<void>;
+    /**
+     * Send an encrypted message to a recipient.
+     *
+     * If the recipient's public key is not yet available, this method will
+     * automatically wait up to `timeoutMs` for the key to arrive via the relay.
+     *
+     * @param recipientId - The recipient's user ID
+     * @param content - Message content (string or Uint8Array)
+     * @param options - Optional: { timeout: number, waitForRecipient: boolean }
+     * @throws StvorError with RECIPIENT_TIMEOUT if recipient key doesn't arrive in time
+     *
+     * @example
+     * ```typescript
+     * // Auto-waits for recipient (recommended)
+     * await alice.send('bob@example.com', 'Hello!');
+     *
+     * // Skip waiting (throws immediately if not available)
+     * await alice.send('bob@example.com', 'Hello!', { waitForRecipient: false });
+     * ```
+     */
+    send(recipientId: UserId, content: MessageContent, options?: {
+        timeout?: number;
+        waitForRecipient?: boolean;
+    }): Promise<void>;
+    /**
+     * Register a handler for incoming messages
+     */
+    onMessage(handler: MessageHandler): () => void;
+    /**
+     * Register a handler that fires when a new user becomes available.
+     * This is triggered when we receive a user's public key announcement.
+     *
+     * **Edge-triggered**: Fires only ONCE per user, on first key discovery.
+     * Will NOT fire again if user reconnects with same identity.
+     *
+     * @example
+     * ```typescript
+     * client.onUserAvailable((userId) => {
+     *   console.log(`${userId} is now available for messaging`);
+     * });
+     * ```
+     */
+    onUserAvailable(handler: UserAvailableHandler): () => void;
+}
+export declare class StvorApp {
+    private readonly config;
+    private clients;
+    constructor(config: StvorAppConfig);
+    connect(userId: UserId): Promise<StvorFacadeClient>;
+    /**
+     * Get a connected client by user ID
+     */
+    getClient(userId: UserId): StvorFacadeClient | undefined;
+    /**
+     * Check if a user is connected locally
+     */
+    isConnected(userId: UserId): boolean;
+    disconnect(userId?: UserId): Promise<void>;
+}
+export declare function init(config: StvorAppConfig): Promise<StvorApp>;
+export declare const createApp: typeof init;
+export declare const Stvor: {
+    init: typeof init;
+    createApp: typeof init;
+};
+export {};

package/dist/src/facade/app.js

@@ -0,0 +1,245 @@
+import { Errors, StvorError } from './errors.js';
+import { RelayClient } from './relay-client.js';
+import { CryptoSession } from './crypto.js';
+/** Default timeout for waiting for recipient keys (ms) */
+const DEFAULT_RECIPIENT_TIMEOUT = 10000;
+/** Polling interval for key resolution (ms) */
+const KEY_POLL_INTERVAL = 100;
+export class StvorFacadeClient {
+    constructor(userId, relay, defaultTimeout = DEFAULT_RECIPIENT_TIMEOUT) {
+        this.userId = userId;
+        this.relay = relay;
+        this.defaultTimeout = defaultTimeout;
+        this.handlers = [];
+        this.userAvailableHandlers = [];
+        this.knownPubKeys = new Map();
+        this.pendingKeyResolvers = new Map();
+        this.crypto = new CryptoSession();
+        // listen relay messages
+        this.relay.onMessage((m) => this.handleRelayMessage(m));
+        // announce our public key
+        this.relay.send({ type: 'announce', user: this.userId, pub: this.crypto.exportPublic() });
+    }
+    async handleRelayMessage(m) {
+        if (!m || typeof m !== 'object')
+            return;
+        if (m.type === 'announce' && m.user && m.pub) {
+            const wasKnown = this.knownPubKeys.has(m.user);
+            this.knownPubKeys.set(m.user, m.pub);
+            // Notify pending resolvers
+            const resolvers = this.pendingKeyResolvers.get(m.user);
+            if (resolvers) {
+                resolvers.forEach(resolve => resolve());
+                this.pendingKeyResolvers.delete(m.user);
+            }
+            // Notify user available handlers (only for new users)
+            if (!wasKnown) {
+                for (const h of this.userAvailableHandlers) {
+                    try {
+                        h(m.user);
+                    }
+                    catch { }
+                }
+            }
+            return;
+        }
+        if (m.type === 'message' && m.to === this.userId && m.payload) {
+            const payload = m.payload;
+            const sender = m.from;
+            try {
+                const plain = this.crypto.decrypt(payload, payload.senderPub);
+                const text = new TextDecoder().decode(plain);
+                for (const h of this.handlers)
+                    h(sender, text);
+            }
+            catch (e) {
+                // ignore decryption errors
+            }
+        }
+    }
+    async internalInitialize() {
+        // nothing for now; announce already sent in constructor
+    }
+    /**
+     * Check if a user's public key is available locally
+     */
+    isUserAvailable(userId) {
+        return this.knownPubKeys.has(userId);
+    }
+    /**
+     * Get list of all known users (whose public keys we have)
+     */
+    getAvailableUsers() {
+        return Array.from(this.knownPubKeys.keys()).filter(id => id !== this.userId);
+    }
+    /**
+     * Wait until a specific user's public key becomes available.
+     * This is the recommended way to ensure you can send messages.
+     *
+     * @param userId - The user to wait for
+     * @param timeoutMs - Maximum time to wait (default: 10000ms)
+     * @throws StvorError with RECIPIENT_TIMEOUT if timeout expires
+     *
+     * @example
+     * ```typescript
+     * await alice.waitForUser('bob@example.com');
+     * await alice.send('bob@example.com', 'Hello!');
+     * ```
+     */
+    async waitForUser(userId, timeoutMs = this.defaultTimeout) {
+        // Already available
+        if (this.knownPubKeys.has(userId)) {
+            return;
+        }
+        return new Promise((resolve, reject) => {
+            const timeout = setTimeout(() => {
+                // Remove from pending
+                const resolvers = this.pendingKeyResolvers.get(userId);
+                if (resolvers) {
+                    const idx = resolvers.indexOf(resolveHandler);
+                    if (idx >= 0)
+                        resolvers.splice(idx, 1);
+                    if (resolvers.length === 0)
+                        this.pendingKeyResolvers.delete(userId);
+                }
+                reject(new StvorError(Errors.RECIPIENT_TIMEOUT, `Timed out waiting for user "${userId}" after ${timeoutMs}ms. ` +
+                    `The user may not be connected to the relay. ` +
+                    `Ensure both parties are online before sending messages.`, 'Verify the recipient is connected, or increase timeout', true));
+            }, timeoutMs);
+            const resolveHandler = () => {
+                clearTimeout(timeout);
+                resolve();
+            };
+            // Add to pending resolvers
+            if (!this.pendingKeyResolvers.has(userId)) {
+                this.pendingKeyResolvers.set(userId, []);
+            }
+            this.pendingKeyResolvers.get(userId).push(resolveHandler);
+        });
+    }
+    /**
+     * Send an encrypted message to a recipient.
+     *
+     * If the recipient's public key is not yet available, this method will
+     * automatically wait up to `timeoutMs` for the key to arrive via the relay.
+     *
+     * @param recipientId - The recipient's user ID
+     * @param content - Message content (string or Uint8Array)
+     * @param options - Optional: { timeout: number, waitForRecipient: boolean }
+     * @throws StvorError with RECIPIENT_TIMEOUT if recipient key doesn't arrive in time
+     *
+     * @example
+     * ```typescript
+     * // Auto-waits for recipient (recommended)
+     * await alice.send('bob@example.com', 'Hello!');
+     *
+     * // Skip waiting (throws immediately if not available)
+     * await alice.send('bob@example.com', 'Hello!', { waitForRecipient: false });
+     * ```
+     */
+    async send(recipientId, content, options) {
+        const { timeout = this.defaultTimeout, waitForRecipient = true } = options ?? {};
+        // Try to resolve recipient key
+        let recipientPub = this.knownPubKeys.get(recipientId);
+        if (!recipientPub) {
+            if (!waitForRecipient) {
+                throw new StvorError(Errors.RECIPIENT_NOT_FOUND, `Recipient "${recipientId}" is not available. ` +
+                    `Their public key has not been announced to the relay. ` +
+                    `Use waitForUser() or enable waitForRecipient option.`, 'Call waitForUser(recipientId) before sending, or ensure recipient is connected', false);
+            }
+            // Wait for recipient key with timeout
+            await this.waitForUser(recipientId, timeout);
+            recipientPub = this.knownPubKeys.get(recipientId);
+            if (!recipientPub) {
+                // Should not happen, but safety check
+                throw new StvorError(Errors.RECIPIENT_NOT_FOUND, `Recipient "${recipientId}" key resolution failed unexpectedly.`, 'This is an internal error, please report it', false);
+            }
+        }
+        const plain = typeof content === 'string' ? new TextEncoder().encode(content) : content;
+        const payload = this.crypto.encrypt(plain, recipientPub);
+        const msg = { type: 'message', to: recipientId, from: this.userId, payload };
+        this.relay.send(msg);
+    }
+    /**
+     * Register a handler for incoming messages
+     */
+    onMessage(handler) {
+        this.handlers.push(handler);
+        return () => {
+            const i = this.handlers.indexOf(handler);
+            if (i >= 0)
+                this.handlers.splice(i, 1);
+        };
+    }
+    /**
+     * Register a handler that fires when a new user becomes available.
+     * This is triggered when we receive a user's public key announcement.
+     *
+     * **Edge-triggered**: Fires only ONCE per user, on first key discovery.
+     * Will NOT fire again if user reconnects with same identity.
+     *
+     * @example
+     * ```typescript
+     * client.onUserAvailable((userId) => {
+     *   console.log(`${userId} is now available for messaging`);
+     * });
+     * ```
+     */
+    onUserAvailable(handler) {
+        this.userAvailableHandlers.push(handler);
+        return () => {
+            const i = this.userAvailableHandlers.indexOf(handler);
+            if (i >= 0)
+                this.userAvailableHandlers.splice(i, 1);
+        };
+    }
+}
+export class StvorApp {
+    constructor(config) {
+        this.config = config;
+        this.clients = new Map();
+    }
+    async connect(userId) {
+        const existing = this.clients.get(userId);
+        if (existing)
+            return existing;
+        const relay = new RelayClient(this.config.relayUrl ?? 'wss://stvor.xyz/relay', this.config.appToken, this.config.timeout ?? 10000);
+        // Wait for relay handshake - throws if API key is invalid
+        await relay.init();
+        const client = new StvorFacadeClient(userId, relay, this.config.timeout ?? 10000);
+        await client.internalInitialize();
+        this.clients.set(userId, client);
+        return client;
+    }
+    /**
+     * Get a connected client by user ID
+     */
+    getClient(userId) {
+        return this.clients.get(userId);
+    }
+    /**
+     * Check if a user is connected locally
+     */
+    isConnected(userId) {
+        return this.clients.has(userId);
+    }
+    async disconnect(userId) {
+        if (userId) {
+            this.clients.delete(userId);
+            return;
+        }
+        this.clients.clear();
+    }
+}
+export async function init(config) {
+    if (!config.appToken.startsWith('stvor_')) {
+        throw new StvorError(Errors.INVALID_APP_TOKEN, 'Invalid app token');
+    }
+    return new StvorApp(config);
+}
+// Alias for createApp
+export const createApp = init;
+export const Stvor = {
+    init,
+    createApp,
+};

package/dist/src/facade/crypto.cjs

@@ -0,0 +1,29 @@
+'use strict';
+
+// Auto-generated CommonJS wrapper for src/facade/crypto.js
+// This allows `require('@stvor/sdk')` to work alongside ESM `import`.
+
+const mod = require('module');
+const url = require('url');
+
+// Use dynamic import to load the ESM module
+let _cached;
+async function _load() {
+  if (!_cached) {
+    _cached = await import(url.pathToFileURL(__filename.replace(/\.cjs$/, '.js')).href);
+  }
+  return _cached;
+}
+
+// For simple CJS usage, expose a promise-based loader
+module.exports = new Proxy({ load: _load }, {
+  get(target, prop) {
+    if (prop === '__esModule') return true;
+    if (prop === 'then') return undefined; // prevent treating as thenable
+    if (prop === 'load') return _load;
+    if (prop === 'default') {
+      return _load().then(m => m.default);
+    }
+    return _load().then(m => m[prop]);
+  }
+});

package/dist/src/facade/errors.cjs

@@ -0,0 +1,29 @@
+'use strict';
+
+// Auto-generated CommonJS wrapper for src/facade/errors.js
+// This allows `require('@stvor/sdk')` to work alongside ESM `import`.
+
+const mod = require('module');
+const url = require('url');
+
+// Use dynamic import to load the ESM module
+let _cached;
+async function _load() {
+  if (!_cached) {
+    _cached = await import(url.pathToFileURL(__filename.replace(/\.cjs$/, '.js')).href);
+  }
+  return _cached;
+}
+
+// For simple CJS usage, expose a promise-based loader
+module.exports = new Proxy({ load: _load }, {
+  get(target, prop) {
+    if (prop === '__esModule') return true;
+    if (prop === 'then') return undefined; // prevent treating as thenable
+    if (prop === 'load') return _load;
+    if (prop === 'default') {
+      return _load().then(m => m.default);
+    }
+    return _load().then(m => m[prop]);
+  }
+});

package/dist/src/facade/errors.d.ts

@@ -0,0 +1,19 @@
+export declare const Errors: {
+    readonly INVALID_APP_TOKEN: "INVALID_APP_TOKEN";
+    readonly INVALID_API_KEY: "INVALID_API_KEY";
+    readonly RELAY_UNAVAILABLE: "RELAY_UNAVAILABLE";
+    readonly DELIVERY_FAILED: "DELIVERY_FAILED";
+    readonly RECIPIENT_NOT_FOUND: "RECIPIENT_NOT_FOUND";
+    readonly RECIPIENT_TIMEOUT: "RECIPIENT_TIMEOUT";
+    readonly MESSAGE_INTEGRITY_FAILED: "MESSAGE_INTEGRITY_FAILED";
+    readonly RECEIVE_TIMEOUT: "RECEIVE_TIMEOUT";
+    readonly RECEIVE_IN_PROGRESS: "RECEIVE_IN_PROGRESS";
+    readonly NOT_CONNECTED: "NOT_CONNECTED";
+};
+export type ErrorCode = (typeof Errors)[keyof typeof Errors];
+export declare class StvorError extends Error {
+    code: ErrorCode;
+    action?: string;
+    retryable?: boolean;
+    constructor(code: ErrorCode, message: string, action?: string, retryable?: boolean);
+}

package/dist/src/facade/errors.js

@@ -0,0 +1,21 @@
+export const Errors = {
+    INVALID_APP_TOKEN: 'INVALID_APP_TOKEN',
+    INVALID_API_KEY: 'INVALID_API_KEY',
+    RELAY_UNAVAILABLE: 'RELAY_UNAVAILABLE',
+    DELIVERY_FAILED: 'DELIVERY_FAILED',
+    RECIPIENT_NOT_FOUND: 'RECIPIENT_NOT_FOUND',
+    RECIPIENT_TIMEOUT: 'RECIPIENT_TIMEOUT',
+    MESSAGE_INTEGRITY_FAILED: 'MESSAGE_INTEGRITY_FAILED',
+    RECEIVE_TIMEOUT: 'RECEIVE_TIMEOUT',
+    RECEIVE_IN_PROGRESS: 'RECEIVE_IN_PROGRESS',
+    NOT_CONNECTED: 'NOT_CONNECTED',
+};
+export class StvorError extends Error {
+    constructor(code, message, action, retryable) {
+        super(message);
+        this.code = code;
+        this.action = action;
+        this.retryable = retryable;
+        this.name = 'StvorError';
+    }
+}

package/dist/src/facade/index.cjs

@@ -0,0 +1,29 @@
+'use strict';
+
+// Auto-generated CommonJS wrapper for src/facade/index.js
+// This allows `require('@stvor/sdk')` to work alongside ESM `import`.
+
+const mod = require('module');
+const url = require('url');
+
+// Use dynamic import to load the ESM module
+let _cached;
+async function _load() {
+  if (!_cached) {
+    _cached = await import(url.pathToFileURL(__filename.replace(/\.cjs$/, '.js')).href);
+  }
+  return _cached;
+}
+
+// For simple CJS usage, expose a promise-based loader
+module.exports = new Proxy({ load: _load }, {
+  get(target, prop) {
+    if (prop === '__esModule') return true;
+    if (prop === 'then') return undefined; // prevent treating as thenable
+    if (prop === 'load') return _load;
+    if (prop === 'default') {
+      return _load().then(m => m.default);
+    }
+    return _load().then(m => m[prop]);
+  }
+});

package/dist/src/facade/index.d.ts

@@ -0,0 +1,8 @@
+export * from './app.js';
+export * from './errors.js';
+export * from './types.js';
+export type { DecryptedMessage, SealedPayload } from './types.js';
+export type { StvorAppConfig, AppToken, UserId, MessageContent } from './types.js';
+export { StvorError } from './errors.js';
+export { StvorApp, StvorFacadeClient, Stvor, init, createApp } from './app.js';
+export { ErrorCode as STVOR_ERRORS } from './errors.js';

package/dist/src/facade/index.js

@@ -0,0 +1,5 @@
+export * from './app.js';
+export * from './errors.js';
+export * from './types.js';
+export { StvorError } from './errors.js';
+export { StvorApp, StvorFacadeClient, Stvor, init, createApp } from './app.js';

package/dist/src/facade/relay-client.cjs

@@ -0,0 +1,29 @@
+'use strict';
+
+// Auto-generated CommonJS wrapper for src/facade/relay-client.js
+// This allows `require('@stvor/sdk')` to work alongside ESM `import`.
+
+const mod = require('module');
+const url = require('url');
+
+// Use dynamic import to load the ESM module
+let _cached;
+async function _load() {
+  if (!_cached) {
+    _cached = await import(url.pathToFileURL(__filename.replace(/\.cjs$/, '.js')).href);
+  }
+  return _cached;
+}
+
+// For simple CJS usage, expose a promise-based loader
+module.exports = new Proxy({ load: _load }, {
+  get(target, prop) {
+    if (prop === '__esModule') return true;
+    if (prop === 'then') return undefined; // prevent treating as thenable
+    if (prop === 'load') return _load;
+    if (prop === 'default') {
+      return _load().then(m => m.default);
+    }
+    return _load().then(m => m[prop]);
+  }
+});

package/dist/src/facade/relay-client.d.ts

@@ -0,0 +1,36 @@
+/**
+ * STVOR DX Facade - Relay Client
+ */
+type JSONable = Record<string, any>;
+export type RelayHandler = (msg: JSONable) => void;
+export declare class RelayClient {
+    private relayUrl;
+    private timeout;
+    private appToken;
+    private ws?;
+    private connected;
+    private handshakeComplete;
+    private backoff;
+    private queue;
+    private handlers;
+    private reconnecting;
+    private connectPromise?;
+    private connectResolve?;
+    private connectReject?;
+    private authFailed;
+    constructor(relayUrl: string, appToken: string, timeout?: number);
+    /**
+     * Initialize the connection and wait for handshake.
+     * Throws StvorError if API key is rejected.
+     */
+    init(): Promise<void>;
+    private getAuthHeaders;
+    private connect;
+    private scheduleReconnect;
+    private doSend;
+    send(obj: JSONable): void;
+    onMessage(h: RelayHandler): void;
+    isConnected(): boolean;
+    isAuthenticated(): boolean;
+}
+export {};