@stvor/sdk 2.4.0 → 3.0.0

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

@@ -0,0 +1,154 @@
+/**
+ * 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;
+    }
+    /**
+     * 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 {
+            Authorization: `Bearer ${this.appToken}`,
+        };
+    }
+    connect() {
+        if (this.connectPromise)
+            return this.connectPromise;
+        if (this.ws)
+            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)
+            return;
+        this.reconnecting = true;
+        setTimeout(() => {
+            this.reconnecting = false;
+            this.connect();
+            this.backoff = Math.min(this.backoff * 2, 30000);
+        }, this.backoff);
+    }
+    doSend(obj) {
+        const data = JSON.stringify(obj);
+        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 && this.handshakeComplete;
+    }
+    isAuthenticated() {
+        return this.handshakeComplete && !this.authFailed;
+    }
+}

package/dist/src/facade/types.cjs

@@ -0,0 +1,29 @@
+'use strict';
+
+// Auto-generated CommonJS wrapper for src/facade/types.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/types.d.ts

@@ -0,0 +1,50 @@
+/**
+ * STVOR DX Facade - Type Definitions
+ */
+/**
+ * AppToken from developer dashboard
+ * Replaces "API key" terminology for better DX
+ */
+export type AppToken = string;
+/**
+ * Configuration for SDK initialization
+ */
+export interface StvorAppConfig {
+    /** AppToken from STVOR developer dashboard */
+    appToken: string;
+    /** Relay server URL (optional, defaults to stvor.io) */
+    relayUrl?: string;
+    /** Connection timeout in ms (optional, default 10000) */
+    timeout?: number;
+}
+/**
+ * User identifier in your application
+ * Can be email, username, or UUID
+ */
+export type UserId = string;
+/**
+ * Message content - text or binary data
+ */
+export type MessageContent = string | Uint8Array;
+/**
+ * Result of receiving a decrypted message
+ */
+export interface DecryptedMessage {
+    /** Unique message identifier */
+    id: string;
+    /** Sender's user ID */
+    senderId: UserId;
+    /** Decrypted content */
+    content: MessageContent;
+    /** Timestamp when message was sent */
+    timestamp: Date;
+}
+/**
+ * Sealed payload for encrypting files/binary data
+ */
+export interface SealedPayload {
+    /** Encrypted ciphertext */
+    ciphertext: Uint8Array;
+    /** Nonce used for encryption */
+    nonce: Uint8Array;
+}

package/dist/src/facade/types.js

@@ -0,0 +1,4 @@
+/**
+ * STVOR DX Facade - Type Definitions
+ */
+export {};

package/dist/src/index.cjs

@@ -0,0 +1,29 @@
+'use strict';
+
+// Auto-generated CommonJS wrapper for src/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/index.d.ts

@@ -0,0 +1,2 @@
+export * from '../legacy.js';
+export * from '../facade/index.js';

package/dist/src/index.js

@@ -0,0 +1,2 @@
+export * from '../legacy.js';
+export * from '../facade/index.js';

package/dist/src/legacy.cjs

@@ -0,0 +1,29 @@
+'use strict';
+
+// Auto-generated CommonJS wrapper for src/legacy.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/legacy.js

@@ -0,0 +1 @@
+// ...existing code from packages/sdk/legacy.ts...

package/dist/src/mock-relay-server.cjs

@@ -0,0 +1,29 @@
+'use strict';
+
+// Auto-generated CommonJS wrapper for src/mock-relay-server.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/mock-relay-server.d.ts

@@ -0,0 +1,30 @@
+#!/usr/bin/env node
+/**
+ * STVOR Mock Relay Server
+ *
+ * A lightweight local development server that emulates the production
+ * STVOR relay over WebSocket. Run it locally to develop and test
+ * without internet access or a production relay.
+ *
+ * Usage:
+ *   npx @stvor/sdk mock-relay                   # via npx
+ *   npm run mock-relay                           # from SDK root
+ *   node dist/mock-relay-server.js               # direct
+ *   PORT=9000 node dist/mock-relay-server.js     # custom port
+ *   STVOR_MOCK_VERBOSE=1 node dist/mock-relay-server.js  # verbose
+ *
+ * Accepts any AppToken starting with "stvor_" for easy local testing.
+ *
+ * Protocol:
+ *   Connection: ws://localhost:PORT with Authorization header
+ *   Handshake:  Server sends { type: 'handshake', status: 'ok' }
+ *   Announce:   { type: 'announce', user: string, pub: string }
+ *   Message:    { type: 'message', to: string, from: string, payload: any }
+ *   Ack:        { type: 'ack', id: string }
+ *   Error:      { type: 'error', code: string, message: string }
+ */
+import http from 'node:http';
+declare const PORT: number;
+declare const httpServer: http.Server<typeof http.IncomingMessage, typeof http.ServerResponse>;
+declare const wss: any;
+export { PORT, wss, httpServer };

package/dist/src/mock-relay-server.js

@@ -0,0 +1,236 @@
+#!/usr/bin/env node
+/**
+ * STVOR Mock Relay Server
+ *
+ * A lightweight local development server that emulates the production
+ * STVOR relay over WebSocket. Run it locally to develop and test
+ * without internet access or a production relay.
+ *
+ * Usage:
+ *   npx @stvor/sdk mock-relay                   # via npx
+ *   npm run mock-relay                           # from SDK root
+ *   node dist/mock-relay-server.js               # direct
+ *   PORT=9000 node dist/mock-relay-server.js     # custom port
+ *   STVOR_MOCK_VERBOSE=1 node dist/mock-relay-server.js  # verbose
+ *
+ * Accepts any AppToken starting with "stvor_" for easy local testing.
+ *
+ * Protocol:
+ *   Connection: ws://localhost:PORT with Authorization header
+ *   Handshake:  Server sends { type: 'handshake', status: 'ok' }
+ *   Announce:   { type: 'announce', user: string, pub: string }
+ *   Message:    { type: 'message', to: string, from: string, payload: any }
+ *   Ack:        { type: 'ack', id: string }
+ *   Error:      { type: 'error', code: string, message: string }
+ */
+import * as WS from 'ws';
+import http from 'node:http';
+const { WebSocketServer } = WS;
+// ── Configuration ────────────────────────────────────────────────────
+const PORT = parseInt(process.env.STVOR_MOCK_PORT || process.env.PORT || '4444', 10);
+const VERBOSE = process.env.STVOR_MOCK_VERBOSE === '1';
+// ── In-memory state ──────────────────────────────────────────────────
+/** userId → WebSocket */
+const clients = new Map();
+/** userId → public key (base64) */
+const pubkeys = new Map();
+/** userId → pending messages (for offline delivery) */
+const mailboxes = new Map();
+let totalConnections = 0;
+let totalMessages = 0;
+// ── Helpers ──────────────────────────────────────────────────────────
+function log(...args) {
+    if (VERBOSE)
+        console.log('[mock-relay]', new Date().toISOString(), ...args);
+}
+function validateAuth(req) {
+    const auth = req.headers.authorization;
+    if (!auth)
+        return false;
+    const token = auth.replace(/^Bearer\s+/i, '');
+    return token.startsWith('stvor_');
+}
+function broadcast(obj, exceptWs) {
+    const data = JSON.stringify(obj);
+    for (const ws of clients.values()) {
+        if (ws !== exceptWs && ws.readyState === 1 /* OPEN */) {
+            ws.send(data);
+        }
+    }
+}
+// ── HTTP server for health check (and future REST endpoints) ─────────
+const httpServer = http.createServer((req, res) => {
+    const url = new URL(req.url || '/', `http://localhost:${PORT}`);
+    // CORS
+    res.setHeader('Access-Control-Allow-Origin', '*');
+    res.setHeader('Access-Control-Allow-Headers', 'Content-Type, Authorization');
+    res.setHeader('Access-Control-Allow-Methods', 'GET, POST, OPTIONS');
+    if (req.method === 'OPTIONS') {
+        res.writeHead(204);
+        return res.end();
+    }
+    if (url.pathname === '/health') {
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        return res.end(JSON.stringify({
+            status: 'ok',
+            server: 'stvor-mock-relay',
+            version: '1.0.0',
+            uptime: process.uptime(),
+            connectedUsers: clients.size,
+            totalConnections,
+            totalMessages,
+        }));
+    }
+    // GET /status/:userId - check if user is online
+    const statusMatch = url.pathname.match(/^\/status\/(.+)$/);
+    if (statusMatch) {
+        const userId = decodeURIComponent(statusMatch[1]);
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        return res.end(JSON.stringify({
+            userId,
+            online: clients.has(userId),
+            hasPublicKey: pubkeys.has(userId),
+        }));
+    }
+    // GET /usage - mock unlimited usage
+    if (url.pathname === '/usage') {
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        return res.end(JSON.stringify({ used: 0, limit: -1 }));
+    }
+    res.writeHead(404, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify({ error: 'Not Found' }));
+});
+// ── WebSocket server ─────────────────────────────────────────────────
+const wss = new WebSocketServer({ server: httpServer });
+wss.on('connection', (ws, req) => {
+    totalConnections++;
+    // ── Auth check ───────────────────────────────────────────────────
+    if (!validateAuth(req)) {
+        log('Auth failed for connection');
+        ws.send(JSON.stringify({
+            type: 'handshake',
+            status: 'error',
+            reason: 'Invalid AppToken. Token must start with "stvor_".',
+        }));
+        ws.close(4001, 'Unauthorized');
+        return;
+    }
+    // ── Successful handshake ─────────────────────────────────────────
+    ws.send(JSON.stringify({ type: 'handshake', status: 'ok' }));
+    log('Client connected (auth OK)');
+    // Send all known user announcements to the new client
+    for (const [user, pub] of pubkeys.entries()) {
+        try {
+            ws.send(JSON.stringify({ type: 'announce', user, pub }));
+        }
+        catch {
+            // ignore
+        }
+    }
+    // ── Message handler ──────────────────────────────────────────────
+    ws.on('message', (data) => {
+        let msg;
+        try {
+            msg = JSON.parse(data.toString());
+        }
+        catch {
+            return;
+        }
+        // ── Announce: register user + broadcast public key ────────────
+        if (msg.type === 'announce' && msg.user) {
+            const oldWs = clients.get(msg.user);
+            clients.set(msg.user, ws);
+            if (msg.pub) {
+                pubkeys.set(msg.user, msg.pub);
+            }
+            log(`User announced: ${msg.user}`);
+            // Broadcast announce to all other clients
+            broadcast({ type: 'announce', user: msg.user, pub: msg.pub }, ws);
+            // Deliver any pending messages
+            const pending = mailboxes.get(msg.user) || [];
+            if (pending.length > 0) {
+                log(`Delivering ${pending.length} pending messages to ${msg.user}`);
+                for (const m of pending) {
+                    try {
+                        ws.send(JSON.stringify(m));
+                    }
+                    catch {
+                        // ignore
+                    }
+                }
+                mailboxes.set(msg.user, []);
+            }
+            return;
+        }
+        // ── Message: route to recipient ──────────────────────────────
+        if (msg.type === 'message' && msg.to) {
+            totalMessages++;
+            const target = clients.get(msg.to);
+            if (target && target.readyState === 1 /* OPEN */) {
+                // Deliver immediately
+                target.send(JSON.stringify(msg));
+                log(`Message delivered: ${msg.from} → ${msg.to}`);
+                // ACK back to sender
+                if (msg.from && ws.readyState === 1 /* OPEN */) {
+                    ws.send(JSON.stringify({ type: 'ack', id: msg.id ?? null }));
+                }
+            }
+            else {
+                // Store for later delivery
+                if (!mailboxes.has(msg.to)) {
+                    mailboxes.set(msg.to, []);
+                }
+                mailboxes.get(msg.to).push(msg);
+                log(`Message queued: ${msg.from} → ${msg.to} (recipient offline)`);
+                // Notify sender that message is queued
+                if (ws.readyState === 1 /* OPEN */) {
+                    ws.send(JSON.stringify({
+                        type: 'queued',
+                        id: msg.id ?? null,
+                        to: msg.to,
+                        message: 'Recipient is offline. Message queued for delivery.',
+                    }));
+                }
+            }
+            return;
+        }
+        log('Unknown message type:', msg.type);
+    });
+    // ── Disconnect ───────────────────────────────────────────────────
+    ws.on('close', () => {
+        for (const [user, sock] of clients.entries()) {
+            if (sock === ws) {
+                log(`User disconnected: ${user}`);
+                clients.delete(user);
+                // Keep public key so reconnecting users can still be found
+                // pubkeys.delete(user);  // intentionally NOT deleted
+            }
+        }
+    });
+    ws.on('error', (err) => {
+        log('WebSocket error:', err.message);
+    });
+});
+// ── Start server ─────────────────────────────────────────────────────
+httpServer.listen(PORT, () => {
+    console.log('');
+    console.log('  ╔══════════════════════════════════════════════════════╗');
+    console.log('  ║          STVOR Mock Relay Server v1.0.0             ║');
+    console.log('  ╠══════════════════════════════════════════════════════╣');
+    console.log(`  ║  WebSocket: ws://localhost:${String(PORT).padEnd(27)}║`);
+    console.log(`  ║  Health:    http://localhost:${String(PORT).padEnd(22)}║`);
+    console.log('  ║  Auth:      Any token starting with "stvor_"        ║');
+    console.log('  ║  Data:      In-memory (resets on restart)           ║');
+    console.log('  ╚══════════════════════════════════════════════════════╝');
+    console.log('');
+    console.log('  Usage in your app:');
+    console.log('');
+    console.log("    const app = await Stvor.init({");
+    console.log("      appToken: 'stvor_dev_test123',");
+    console.log(`      relayUrl: 'ws://localhost:${PORT}'`);
+    console.log("    });");
+    console.log('');
+    console.log('  Set STVOR_MOCK_VERBOSE=1 for detailed logging.');
+    console.log('');
+});
+export { PORT, wss, httpServer };