@aerostack/sdk-web 0.8.7 → 0.8.9

package/src/realtime.ts

@@ -1,456 +0,0 @@
-/**
- * Aerostack Realtime Client for Web/Browser SDK
- */
-export type RealtimeEvent = 'INSERT' | 'UPDATE' | 'DELETE' | '*' | string;
-
-export interface RealtimeMessage {
-    type: string;
-    topic: string;
-    [key: string]: any;
-}
-
-export interface RealtimeSubscriptionOptions {
-    event?: RealtimeEvent;
-    filter?: Record<string, any>;
-}
-
-export type RealtimeCallback<T = any> = (payload: RealtimePayload<T>) => void;
-
-/** Typed payload for realtime events */
-export interface RealtimePayload<T = any> {
-    type: 'db_change' | 'chat_message' | 'event';
-    topic: string;
-    operation?: RealtimeEvent;
-    event?: string;
-    data: T;
-    old?: T;
-    userId?: string;
-    timestamp?: number | string;
-    [key: string]: any;
-}
-
-/** Chat history message returned from REST API */
-export interface HistoryMessage {
-    id: string;
-    room_id: string;
-    user_id: string;
-    event: string;
-    data: any;
-    created_at: number;
-}
-
-export class RealtimeSubscription<T = any> {
-    private client: RealtimeClient;
-    topic: string;
-    private options: RealtimeSubscriptionOptions;
-    private callbacks: Map<string, Set<RealtimeCallback<T>>> = new Map();
-    private isSubscribed: boolean = false;
-
-    constructor(client: RealtimeClient, topic: string, options: RealtimeSubscriptionOptions = {}) {
-        this.client = client;
-        this.topic = topic;
-        this.options = options;
-    }
-
-    /** Listen for DB change events (INSERT/UPDATE/DELETE/*) or custom named events */
-    on(event: RealtimeEvent | string, callback: RealtimeCallback<T>): this {
-        if (!this.callbacks.has(event)) {
-            this.callbacks.set(event, new Set());
-        }
-        this.callbacks.get(event)!.add(callback);
-        return this;
-    }
-
-    /** Remove a specific callback for an event */
-    off(event: RealtimeEvent | string, callback: RealtimeCallback<T>): this {
-        this.callbacks.get(event)?.delete(callback);
-        return this;
-    }
-
-    subscribe(): this {
-        if (this.isSubscribed) return this;
-        this.client._send({
-            type: 'subscribe',
-            topic: this.topic,
-            filter: this.options.filter
-        });
-        this.isSubscribed = true;
-        return this;
-    }
-
-    unsubscribe(): void {
-        if (!this.isSubscribed) return;
-        this.client._send({
-            type: 'unsubscribe',
-            topic: this.topic
-        });
-        this.isSubscribed = false;
-        this.callbacks.clear();
-        this.client._removeSubscription(this.topic);
-    }
-
-    // ─── Phase 1: Pub/Sub — Publish custom events ─────────────────────────
-    /** Publish a custom event to all subscribers on this channel */
-    publish(event: string, data: any, options?: { persist?: boolean }): void {
-        this.client._send({
-            type: 'publish',
-            topic: this.topic,
-            event,
-            data,
-            persist: options?.persist,
-            id: this.client._generateId(),
-        });
-    }
-
-    // ─── Phase 2: Chat History ────────────────────────────────────────────
-    /** Fetch persisted message history for this channel (requires persist: true on publish) */
-    async getHistory(limit: number = 50, before?: number): Promise<HistoryMessage[]> {
-        return this.client._fetchHistory(this.topic, limit, before);
-    }
-
-    // ─── Phase 3: Presence ────────────────────────────────────────────────
-    /** Track this user's presence state on this channel (auto-synced to subscribers) */
-    track(state: Record<string, any>): void {
-        this.client._send({
-            type: 'track',
-            topic: this.topic,
-            state,
-        });
-    }
-
-    /** Stop tracking presence on this channel */
-    untrack(): void {
-        this.client._send({
-            type: 'untrack',
-            topic: this.topic,
-        });
-    }
-
-    /** @internal */
-    _emit(payload: RealtimePayload<T>): void {
-        // DB change events (INSERT/UPDATE/DELETE)
-        if (payload.operation) {
-            const event = payload.operation as string;
-            this.callbacks.get(event)?.forEach(cb => cb(payload));
-        }
-        // Custom named events ('player-moved', 'presence:join', etc.)
-        if (payload.event) {
-            this.callbacks.get(payload.event)?.forEach(cb => cb(payload));
-        }
-        // Catch-all
-        this.callbacks.get('*')?.forEach(cb => cb(payload));
-    }
-}
-
-export type RealtimeStatus = 'idle' | 'connecting' | 'connected' | 'reconnecting' | 'disconnected';
-
-export interface RealtimeClientOptions {
-    baseUrl: string;
-    projectId: string;
-    token?: string;
-    userId?: string;
-    apiKey?: string;
-    /** Max reconnect attempts before giving up (default: Infinity) */
-    maxReconnectAttempts?: number;
-}
-
-export class RealtimeClient {
-    private baseUrl: string;
-    private projectId: string;
-    private token?: string;
-    private userId?: string;
-    private apiKey?: string;
-    private ws: WebSocket | null = null;
-    private subscriptions: Map<string, RealtimeSubscription> = new Map();
-    private reconnectTimer: any = null;
-    private heartbeatTimer: any = null;
-    private reconnectAttempts: number = 0;
-    private _sendQueue: any[] = [];
-    private _connectingPromise: Promise<void> | null = null;
-    private _status: RealtimeStatus = 'idle';
-    private _statusListeners: Set<(s: RealtimeStatus) => void> = new Set();
-    // HTTP base URL for REST endpoints (history, etc.)
-    private _httpBaseUrl: string;
-    // Pong tracking
-    private _lastPong: number = 0;
-    // Max reconnect attempts
-    private _maxReconnectAttempts: number;
-    private _maxRetriesListeners: Set<() => void> = new Set();
-
-    constructor(options: RealtimeClientOptions) {
-        const wsBase = options.baseUrl.replace(/\/v1\/?$/, '').replace(/^http/, 'ws');
-        this.baseUrl = `${wsBase}/api/realtime`;
-        this._httpBaseUrl = options.baseUrl.replace(/\/v1\/?$/, '');
-        this.projectId = options.projectId;
-        this.token = options.token;
-        this.userId = options.userId;
-        this.apiKey = options.apiKey;
-        this._maxReconnectAttempts = options.maxReconnectAttempts ?? Infinity;
-    }
-
-    get status(): RealtimeStatus { return this._status; }
-    get connected(): boolean { return this._status === 'connected'; }
-
-    /** Subscribe to connection status changes. Returns unsubscribe fn. */
-    onStatusChange(cb: (status: RealtimeStatus) => void): () => void {
-        this._statusListeners.add(cb);
-        return () => this._statusListeners.delete(cb);
-    }
-
-    /** Called when max reconnect attempts exceeded. Returns unsubscribe fn. */
-    onMaxRetriesExceeded(cb: () => void): () => void {
-        this._maxRetriesListeners.add(cb);
-        return () => this._maxRetriesListeners.delete(cb);
-    }
-
-    private _setStatus(s: RealtimeStatus) {
-        this._status = s;
-        this._statusListeners.forEach(cb => cb(s));
-    }
-
-    /** Update the auth token on a live connection */
-    setToken(newToken: string): void {
-        this.token = newToken;
-        this._send({ type: 'auth', token: newToken });
-    }
-
-    async connect(): Promise<void> {
-        if (this.ws && this.ws.readyState === WebSocket.OPEN) return Promise.resolve();
-        if (this._connectingPromise) return this._connectingPromise;
-        this._connectingPromise = this._doConnect().finally(() => {
-            this._connectingPromise = null;
-        });
-        return this._connectingPromise;
-    }
-
-    private _doConnect(): Promise<void> {
-        this._setStatus('connecting');
-        return new Promise((resolve, reject) => {
-            const url = new URL(this.baseUrl);
-            url.searchParams.set('projectId', this.projectId);
-            if (this.userId) url.searchParams.set('userId', this.userId);
-
-            // SECURITY: Pass credentials via Sec-WebSocket-Protocol header — never as URL query params
-            // (URL params appear in CDN logs, browser history, and Referer headers).
-            const protocols: string[] = [];
-            if (this.apiKey) protocols.push(`aerostack-key.${this.apiKey}`);
-            if (this.token) protocols.push(`aerostack-token.${this.token}`);
-            if (protocols.length > 0) protocols.push('aerostack-v1');
-
-            this.ws = protocols.length > 0
-                ? new WebSocket(url.toString(), protocols)
-                : new WebSocket(url.toString());
-
-            this.ws.onopen = () => {
-                this._setStatus('connected');
-                this.reconnectAttempts = 0;
-                this._lastPong = Date.now();
-                this.startHeartbeat();
-                this._setupOfflineDetection();
-                // Flush queued messages
-                while (this._sendQueue.length > 0) {
-                    this.ws!.send(JSON.stringify(this._sendQueue.shift()));
-                }
-                for (const sub of this.subscriptions.values()) {
-                    sub.subscribe();
-                }
-                resolve();
-            };
-
-            this.ws.onmessage = (event) => {
-                try {
-                    const data = JSON.parse(event.data);
-                    this.handleMessage(data);
-                } catch (e) {
-                    console.error('Realtime message parse error:', e);
-                }
-            };
-
-            this.ws.onclose = () => {
-                this._setStatus('reconnecting');
-                this.stopHeartbeat();
-                this.ws = null;
-                this.scheduleReconnect();
-            };
-
-            this.ws.onerror = (err) => {
-                console.error('Realtime connection error:', err);
-                this._setStatus('disconnected');
-                reject(err);
-            };
-        });
-    }
-
-    disconnect() {
-        this._setStatus('disconnected');
-        this.stopReconnect();
-        this.stopHeartbeat();
-        this._teardownOfflineDetection();
-        if (this.ws) {
-            this.ws.close();
-            this.ws = null;
-        }
-        this._sendQueue = [];
-    }
-
-    channel<T = any>(topic: string, options: RealtimeSubscriptionOptions = {}): RealtimeSubscription<T> {
-        let fullTopic: string;
-        if (!topic.includes('/')) {
-            fullTopic = `table/${topic}/${this.projectId}`;
-        } else if (this.projectId && topic.endsWith(`/${this.projectId}`)) {
-            fullTopic = topic; // already fully qualified
-        } else {
-            fullTopic = `${topic}/${this.projectId}`; // e.g. 'table/orders' → 'table/orders/<projectId>'
-        }
-        let sub = this.subscriptions.get(fullTopic);
-        if (!sub) {
-            sub = new RealtimeSubscription<T>(this, fullTopic, options);
-            this.subscriptions.set(fullTopic, sub);
-        }
-        return sub as RealtimeSubscription<T>;
-    }
-
-    /** Legacy: send a chat message (now persisted to DB) */
-    sendChat(roomId: string, text: string, metadata?: Record<string, any>): void {
-        this._send({ type: 'chat', roomId, text, metadata });
-    }
-
-    /** Legacy: get a chat room subscription */
-    chatRoom(roomId: string): RealtimeSubscription {
-        return this.channel(`chat/${roomId}/${this.projectId}`);
-    }
-
-    /** @internal — Generate unique message ID for ack tracking */
-    _generateId(): string {
-        return Math.random().toString(36).slice(2) + Date.now().toString(36);
-    }
-
-    /** @internal — Remove a subscription from the map (called on unsubscribe) */
-    _removeSubscription(topic: string): void {
-        this.subscriptions.delete(topic);
-    }
-
-    /** @internal */
-    _send(data: any) {
-        if (this.ws && this.ws.readyState === WebSocket.OPEN) {
-            this.ws.send(JSON.stringify(data));
-        } else {
-            this._sendQueue.push(data);
-        }
-    }
-
-    /** @internal — Fetch chat/event history via REST API */
-    async _fetchHistory(room: string, limit: number = 50, before?: number): Promise<HistoryMessage[]> {
-        const url = new URL(`${this._httpBaseUrl}/api/v1/public/realtime/history`);
-        url.searchParams.set('room', room);
-        url.searchParams.set('limit', String(limit));
-        if (before) url.searchParams.set('before', String(before));
-
-        const headers: Record<string, string> = {};
-        if (this.apiKey) headers['X-Aerostack-Key'] = this.apiKey;
-        if (this.token) headers['Authorization'] = `Bearer ${this.token}`;
-
-        const res = await fetch(url.toString(), { headers });
-        const json = await res.json() as any;
-        return json.messages || [];
-    }
-
-    private handleMessage(data: RealtimeMessage) {
-        // Track pong for liveness
-        if (data.type === 'pong') {
-            this._lastPong = Date.now();
-            return;
-        }
-
-        // Ack (fire-and-forget acknowledgment from server)
-        if (data.type === 'ack') {
-            return;
-        }
-
-        // Route to subscription: db_change, chat_message, event, presence:*
-        if (data.type === 'db_change' || data.type === 'chat_message' || data.type === 'event') {
-            const sub = this.subscriptions.get(data.topic);
-            if (sub) {
-                sub._emit(data as any);
-            }
-        }
-
-        // Re-key subscription on server-confirmed topic (for non-TS SDKs compatibility)
-        if (data.type === 'subscribed' && data.topic) {
-            for (const [origTopic, sub] of this.subscriptions.entries()) {
-                if (data.topic !== origTopic && data.topic.startsWith(origTopic)) {
-                    this.subscriptions.delete(origTopic);
-                    sub.topic = data.topic;
-                    this.subscriptions.set(data.topic, sub);
-                    break;
-                }
-            }
-        }
-    }
-
-    private startHeartbeat() {
-        this.heartbeatTimer = setInterval(() => {
-            this._send({ type: 'ping' });
-            if (this._lastPong > 0 && Date.now() - this._lastPong > 70000) {
-                console.warn('Realtime: no pong received, forcing reconnect');
-                this.ws?.close();
-            }
-        }, 30000);
-    }
-
-    private stopHeartbeat() {
-        if (this.heartbeatTimer) {
-            clearInterval(this.heartbeatTimer);
-            this.heartbeatTimer = null;
-        }
-    }
-
-    private scheduleReconnect() {
-        this.stopReconnect();
-        if (this.reconnectAttempts >= this._maxReconnectAttempts) {
-            this._setStatus('disconnected');
-            this._maxRetriesListeners.forEach(cb => cb());
-            return;
-        }
-        const delay = Math.min(1000 * Math.pow(2, this.reconnectAttempts), 30000);
-        const jitter = delay * 0.3 * Math.random();
-        this.reconnectAttempts++;
-        this.reconnectTimer = setTimeout(() => {
-            this.connect().catch(() => { });
-        }, delay + jitter);
-    }
-
-    private stopReconnect() {
-        if (this.reconnectTimer) {
-            clearTimeout(this.reconnectTimer);
-            this.reconnectTimer = null;
-        }
-    }
-
-    // Offline/online detection (browser only)
-    private _handleOnline = () => {
-        if (this._status !== 'connected') {
-            this.reconnectAttempts = 0;
-            this.connect().catch(() => { });
-        }
-    };
-
-    private _handleOffline = () => {
-        this.stopReconnect();
-        this._setStatus('disconnected');
-    };
-
-    private _setupOfflineDetection() {
-        if (typeof window !== 'undefined') {
-            window.addEventListener('online', this._handleOnline);
-            window.addEventListener('offline', this._handleOffline);
-        }
-    }
-
-    private _teardownOfflineDetection() {
-        if (typeof window !== 'undefined') {
-            window.removeEventListener('online', this._handleOnline);
-            window.removeEventListener('offline', this._handleOffline);
-        }
-    }
-}

package/src/sdk.ts

@@ -1,197 +0,0 @@
-import * as gen from './_generated/index.js';
-import { RealtimeClient } from './realtime.js';
-
-export interface SDKOptions {
-    /** 
-     * Aerostack API Key. 
-     * Use a Public Key for client-side environments.
-     */
-    apiKey?: string;
-    /** Alias for apiKey for backward compatibility */
-    apiKeyAuth?: string;
-    serverUrl?: string;
-    /** Alias for serverUrl for backward compatibility */
-    serverURL?: string;
-    maxReconnectAttempts?: number;
-    projectId?: string;
-}
-
-/** 
- * Compatibility wrapper for Database API 
- */
-class DatabaseFacade {
-    constructor(private api: gen.DatabaseApi) { }
-
-    /**
-     * Run a SQL query against your project database
-     */
-    async dbQuery(params: {
-        dbQueryRequest?: gen.DbQueryRequest,
-        requestBody?: gen.DbQueryRequest,
-        xSDKVersion?: string,
-        xRequestID?: string
-    }) {
-        return this.api.dbQuery({
-            dbQueryRequest: params.dbQueryRequest || params.requestBody!,
-            xSDKVersion: params.xSDKVersion,
-            xRequestID: params.xRequestID
-        });
-    }
-}
-
-/**
- * Aerostack SDK Facade for Web/Browser.
- * Provides a clean, ergonomic API for client-safe Aerostack services.
- */
-export class SDK {
-    public readonly auth: gen.AuthenticationApi;
-    public readonly ai: gen.AIApi;
-    public readonly storage: gen.StorageApi;
-    public readonly realtime: RealtimeClient;
-    public readonly database: DatabaseFacade;
-
-    private config: gen.Configuration;
-
-    constructor(options: SDKOptions = {}) {
-        const serverUrl = options.serverUrl || options.serverURL || 'https://api.aerostack.dev/v1';
-        const apiKey = options.apiKey || options.apiKeyAuth;
-
-        this.config = new gen.Configuration({
-            basePath: serverUrl,
-            headers: apiKey ? { 'X-Aerostack-Key': apiKey } : {},
-            apiKey: apiKey,
-        });
-
-        this.auth = new gen.AuthenticationApi(this.config);
-        this.ai = new gen.AIApi(this.config);
-        this.storage = new gen.StorageApi(this.config);
-        this.database = new DatabaseFacade(new gen.DatabaseApi(this.config));
-
-        this.realtime = new RealtimeClient({
-            baseUrl: serverUrl,
-            apiKey: apiKey,
-            projectId: options.projectId || '',
-            maxReconnectAttempts: options.maxReconnectAttempts
-        });
-    }
-
-    /**
-     * Stream a gateway chat completion with token-by-token callbacks.
-     *
-     * @example
-     * await sdk.streamGateway({
-     *   apiSlug: 'my-chatbot',
-     *   messages: [{ role: 'user', content: 'Hello' }],
-     *   consumerKey: 'ask_live_...',
-     *   onToken: (delta) => process.stdout.write(delta),
-     * });
-     */
-    async streamGateway(opts: {
-        apiSlug: string;
-        messages: Array<{ role: 'user' | 'assistant' | 'system'; content: string }>;
-        consumerKey?: string;
-        token?: string;
-        systemPrompt?: string;
-        onToken?: (delta: string) => void;
-        onDone?: (usage: { tokensUsed: number }) => void;
-        onError?: (error: Error) => void;
-        signal?: AbortSignal;
-    }): Promise<{ text: string; tokensUsed: number }> {
-        const baseUrl = this.config.basePath.replace(/\/v1\/?$/, '');
-        const endpoint = `${baseUrl}/api/gateway/${opts.apiSlug}/v1/chat/completions`;
-
-        const headers: Record<string, string> = { 'Content-Type': 'application/json' };
-        if (opts.consumerKey) {
-            headers['Authorization'] = `Bearer ${opts.consumerKey}`;
-        } else if (opts.token) {
-            headers['Authorization'] = `Bearer ${opts.token}`;
-        }
-
-        const messages = opts.systemPrompt
-            ? [{ role: 'system' as const, content: opts.systemPrompt }, ...opts.messages]
-            : opts.messages;
-
-        let text = '';
-        let totalTokens = 0;
-        let estimatedTokens = 0;
-
-        try {
-            const response = await fetch(endpoint, {
-                method: 'POST',
-                headers,
-                body: JSON.stringify({ messages, stream: true, stream_options: { include_usage: true } }),
-                signal: opts.signal,
-            });
-
-            if (!response.ok) {
-                const err = await response.json().catch(() => ({ error: 'Request failed' }));
-                throw new Error((err as any).error || `HTTP ${response.status}`);
-            }
-            if (!response.body) throw new Error('No response body');
-
-            const reader = response.body.getReader();
-            const decoder = new TextDecoder();
-            let buffer = '';
-
-            while (true) {
-                const { done, value } = await reader.read();
-                if (done) break;
-                buffer += decoder.decode(value, { stream: true });
-                const lines = buffer.split('\n');
-                buffer = lines.pop() || '';
-
-                for (const line of lines) {
-                    if (!line.startsWith('data: ')) continue;
-                    const payload = line.slice(6).trim();
-                    if (payload === '[DONE]') {
-                        reader.cancel();
-                        const result = { text, tokensUsed: totalTokens || estimatedTokens };
-                        opts.onDone?.(result);
-                        return result;
-                    }
-                    try {
-                        const parsed = JSON.parse(payload);
-                        const delta = parsed.choices?.[0]?.delta?.content;
-                        if (delta) {
-                            text += delta;
-                            opts.onToken?.(delta);
-                            estimatedTokens += Math.ceil(delta.length / 4);
-                        }
-                        if (parsed.usage?.total_tokens) totalTokens = parsed.usage.total_tokens;
-                        else if (parsed.usage?.completion_tokens) totalTokens = parsed.usage.completion_tokens;
-                    } catch { /* skip malformed frames */ }
-                }
-            }
-
-            const result = { text, tokensUsed: totalTokens || estimatedTokens };
-            opts.onDone?.(result);
-            return result;
-        } catch (err: any) {
-            if (err.name === 'AbortError') return { text, tokensUsed: totalTokens || estimatedTokens };
-            const error = err instanceof Error ? err : new Error(String(err));
-            opts.onError?.(error);
-            throw error;
-        }
-    }
-
-    /**
-     * Update the API key for subsequent requests.
-     */
-    setApiKey(apiKey: string): void {
-        this.config = new gen.Configuration({
-            ...this.config,
-            headers: { ...this.config.headers, 'X-Aerostack-Key': apiKey },
-            apiKey,
-        });
-        (this as any).auth = new gen.AuthenticationApi(this.config);
-        (this as any).ai = new gen.AIApi(this.config);
-        (this as any).storage = new gen.StorageApi(this.config);
-        (this as any).database = new DatabaseFacade(new gen.DatabaseApi(this.config));
-    }
-}
-
-/** @deprecated Use SDK instead */
-export const Aerostack = SDK;
-
-// Export a default instance factory or just the class
-export const createClient = (options: SDKOptions) => new SDK(options);

package/tsconfig.json

@@ -1,41 +0,0 @@
-{
-  "compilerOptions": {
-    "incremental": false,
-    "target": "ES2020",
-    "lib": [
-      "ES2022",
-      "DOM",
-      "DOM.Iterable"
-    ],
-    "jsx": "react-jsx",
-    "module": "Node16",
-    "moduleResolution": "Node16",
-    "allowJs": true,
-    "declaration": true,
-    "declarationMap": true,
-    "sourceMap": true,
-    "outDir": ".",
-    // https://github.com/tsconfig/bases/blob/a1bf7c0fa2e094b068ca3e1448ca2ece4157977e/bases/strictest.json
-    "strict": true,
-    "allowUnusedLabels": false,
-    "allowUnreachableCode": false,
-    "noImplicitOverride": false,
-    "noImplicitReturns": true,
-    "noPropertyAccessFromIndexSignature": true,
-    "noUncheckedIndexedAccess": true,
-    "noUnusedLocals": false,
-    "noUnusedParameters": false,
-    "exactOptionalPropertyTypes": false,
-    "isolatedModules": true,
-    "checkJs": true,
-    "esModuleInterop": true,
-    "skipLibCheck": true,
-    "forceConsistentCasingInFileNames": true
-  },
-  "include": [
-    "src"
-  ],
-  "exclude": [
-    "node_modules"
-  ]
-}