@stvor/sdk 2.3.0 → 2.3.2

package/dist/facade/app.d.ts

@@ -69,6 +69,9 @@ export declare class StvorFacadeClient {
      * 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) => {

package/dist/facade/app.js

@@ -175,6 +175,9 @@ export class StvorFacadeClient {
      * 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) => {
@@ -201,6 +204,8 @@ export class StvorApp {
         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);

package/dist/facade/errors.d.ts

@@ -1,5 +1,6 @@
 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";

package/dist/facade/errors.js

@@ -1,5 +1,6 @@
 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',

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

@@ -9,16 +9,28 @@ export declare class RelayClient {
     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 {};

package/dist/facade/relay-client.js

@@ -1,18 +1,32 @@
 /**
  * STVOR DX Facade - Relay Client
  */
+import { Errors, StvorError } from './errors.js';
 import * as WS from 'ws';
 export class RelayClient {
     constructor(relayUrl, appToken, timeout = 10000) {
         this.connected = false;
+        this.handshakeComplete = false;
         this.backoff = 1000;
         this.queue = [];
         this.handlers = [];
         this.reconnecting = false;
+        this.authFailed = false;
         this.relayUrl = relayUrl.replace(/^http/, 'ws');
         this.appToken = appToken;
         this.timeout = timeout;
-        this.connect();
+    }
+    /**
+     * Initialize the connection and wait for handshake.
+     * Throws StvorError if API key is rejected.
+     */
+    async init() {
+        if (this.authFailed) {
+            throw new StvorError(Errors.INVALID_API_KEY, 'Relay rejected connection: invalid API key');
+        }
+        if (this.handshakeComplete)
+            return;
+        await this.connect();
     }
     getAuthHeaders() {
         return {
@@ -20,39 +34,88 @@ export class RelayClient {
         };
     }
     connect() {
+        if (this.connectPromise)
+            return this.connectPromise;
         if (this.ws)
-            return;
-        const WSClass = WS.default ?? WS;
-        this.ws = new WSClass(this.relayUrl, { headers: this.getAuthHeaders() });
-        this.ws.on('open', () => {
-            this.connected = true;
-            this.backoff = 1000;
-            // flush queue
-            while (this.queue.length) {
-                const m = this.queue.shift();
-                this.send(m);
-            }
-        });
-        this.ws.on('message', (data) => {
-            try {
-                const json = JSON.parse(data.toString());
-                for (const h of this.handlers)
-                    h(json);
-            }
-            catch (e) {
-                // ignore
-            }
-        });
-        this.ws.on('close', () => {
-            this.connected = false;
-            this.ws = undefined;
-            this.scheduleReconnect();
-        });
-        this.ws.on('error', () => {
-            this.connected = false;
-            this.ws = undefined;
-            this.scheduleReconnect();
+            return Promise.resolve();
+        this.connectPromise = new Promise((resolve, reject) => {
+            this.connectResolve = resolve;
+            this.connectReject = reject;
+            const WSClass = WS.default ?? WS;
+            this.ws = new WSClass(this.relayUrl, { headers: this.getAuthHeaders() });
+            // Timeout for handshake
+            const handshakeTimeout = setTimeout(() => {
+                if (!this.handshakeComplete) {
+                    this.ws?.close();
+                    reject(new StvorError(Errors.RELAY_UNAVAILABLE, 'Relay handshake timeout'));
+                }
+            }, this.timeout);
+            this.ws.on('open', () => {
+                this.connected = true;
+                this.backoff = 1000;
+                // Don't flush queue yet - wait for handshake
+            });
+            this.ws.on('message', (data) => {
+                try {
+                    const json = JSON.parse(data.toString());
+                    // Handle handshake response
+                    if (json.type === 'handshake') {
+                        clearTimeout(handshakeTimeout);
+                        if (json.status === 'ok') {
+                            this.handshakeComplete = true;
+                            // Now flush the queue
+                            while (this.queue.length) {
+                                const m = this.queue.shift();
+                                this.doSend(m);
+                            }
+                            this.connectResolve?.();
+                        }
+                        else {
+                            // Handshake rejected
+                            this.authFailed = true;
+                            this.ws?.close();
+                            const err = new StvorError(Errors.INVALID_API_KEY, `Relay rejected connection: ${json.reason || 'invalid API key'}`);
+                            this.connectReject?.(err);
+                        }
+                        return;
+                    }
+                    // Regular message
+                    for (const h of this.handlers)
+                        h(json);
+                }
+                catch (e) {
+                    // ignore parse errors
+                }
+            });
+            this.ws.on('close', (code) => {
+                this.connected = false;
+                this.handshakeComplete = false;
+                this.ws = undefined;
+                this.connectPromise = undefined;
+                // If auth failed, don't reconnect
+                if (this.authFailed) {
+                    return;
+                }
+                // 401/403 close codes mean auth failure
+                if (code === 4001 || code === 4003) {
+                    this.authFailed = true;
+                    this.connectReject?.(new StvorError(Errors.INVALID_API_KEY, 'Relay rejected connection: invalid API key'));
+                    return;
+                }
+                this.scheduleReconnect();
+            });
+            this.ws.on('error', (err) => {
+                this.connected = false;
+                this.handshakeComplete = false;
+                this.ws = undefined;
+                this.connectPromise = undefined;
+                if (this.authFailed) {
+                    return;
+                }
+                this.scheduleReconnect();
+            });
         });
+        return this.connectPromise;
     }
     scheduleReconnect() {
         if (this.reconnecting)
@@ -64,19 +127,28 @@ export class RelayClient {
             this.backoff = Math.min(this.backoff * 2, 30000);
         }, this.backoff);
     }
-    send(obj) {
+    doSend(obj) {
         const data = JSON.stringify(obj);
-        if (this.connected && this.ws) {
+        if (this.connected && this.ws && this.handshakeComplete) {
             this.ws.send(data);
         }
         else {
             this.queue.push(obj);
         }
     }
+    send(obj) {
+        if (this.authFailed) {
+            throw new StvorError(Errors.INVALID_API_KEY, 'Cannot send: relay rejected connection due to invalid API key');
+        }
+        this.doSend(obj);
+    }
     onMessage(h) {
         this.handlers.push(h);
     }
     isConnected() {
-        return this.connected;
+        return this.connected && this.handshakeComplete;
+    }
+    isAuthenticated() {
+        return this.handshakeComplete && !this.authFailed;
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stvor/sdk",
-  "version": "2.3.0",
+  "version": "2.3.2",
   "description": "Stvor DX Facade - Simple E2EE SDK for client-side encryption",
   "type": "module",
   "main": "./dist/index.js",