dolphin-client 1.0.0

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2026 Shankar Phuyal
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARDARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,100 @@
+# dolphin-client 🐬 — HTML is back!
+
+**Hookless, framework-agnostic, zero-dependency real-time reactive DOM-binding engine.** 
+
+Unleash the full power of modern native browser APIs and DolphinCSS without the heavy framework tax of React or Vue!
+
+---
+
+### 💌 Returning Home: A Love Letter to HTML
+
+Remember the early days of your coding journey? Writing a simple `index.html` in a plain text editor, double-clicking it, and watching it open instantly in the browser. No complex build pipelines, no `node_modules` weighing hundreds of megabytes, no state hooks, and no framework fatigue. Just a direct, pure, and magical relationship between your markup and the browser.
+
+Over the last decade, we treated HTML as a dead, passive mounting point (`<div id="root"></div>`) while building virtual universes in JavaScript. We spent 80% of our time debugging configurations and boilerplate, and only 20% building beautiful user experiences.
+
+**Dolphin Client is our way of coming home.**
+
+By breathing life back into standard HTML, we have resurrected the simplicity of standard markup and empowered it with the modern superpowers of WebSockets, IndexedDB, WebRTC, and hardware-accelerated CSS variables. It is the renaissance of the native web standards we all fell in love with. 
+
+*Because the best JavaScript is actually the code you never had to write.*
+
+---
+
+## Features
+
+- **Hookless Reactivity**: Bind topics to DOM elements via HTML data attributes—no React, Vue, or Angular state management required.
+- **Unified Event Binding**: Loop-based browser event handling for values (`data-rt-push`) and actions (`data-rt-[event]` / `data-api-[event]`).
+- **Context API/Prop drilling in Pure DOM**: Crawls up the DOM tree (`getClosestContext`) to fetch parent contexts and inject parameters.
+- **REST API + Realtime Hybrid Support**: Evaluates templates (`data-rt-template`) on initial HTTP fetches (`data-api-get`) and transitions seamlessly to real-time WebSockets on connection.
+- **WebRTC Intercom Signaling**: Built-in methods to handle peer connections, track negotiation, ICE candidates, and signaling.
+- **Ultralight weight**: Zero external dependencies, pure browser-native runtime APIs.
+
+### Method 1: NPM (For Modern Bundlers)
+```bash
+npm install dolphin-client
+```
+
+### Method 2: Direct Local Download (For No-Install / Plain HTML)
+Tired of the command line and `node_modules` clutter? We've got you covered!
+
+[![Download dolphin-client.js](https://img.shields.io/badge/Download-dolphin--client.js-F7DF1E?style=for-the-badge&logo=javascript&logoColor=black)](https://unpkg.com/dolphin-client/dist/dolphin-client.js) &nbsp;&nbsp; [![Download dolphin-bundle.zip](https://img.shields.io/badge/Download-dolphin--bundle.zip-4CAF50?style=for-the-badge&logo=archive&logoColor=white)](https://github.com/Phuyalshankar/dolphin-server-modules/releases/latest/download/dolphin-bundle.zip)
+
+*(Right-click on **dolphin-client.js** and select "Save Link As..." to save it directly to your project)*
+
+
+Extract the zip directly inside your project folder to get a clean local directory structure with pre-bundled assets:
+```
+my-project/
+├── css/
+│   └── dolphin-css.css   (DolphinCSS Premium Visuals Layer)
+├── js/
+│   └── dolphin-client.js  (Dolphin Reactivity Engine)
+└── index.html             (A ready-to-run skeleton template!)
+```
+Inside your HTML, simply link them locally:
+```html
+<link rel="stylesheet" href="css/dolphin-css.css">
+<script src="js/dolphin-client.js"></script>
+```
+
+## Basic Usage
+
+### 1. In Modern Bundlers (Next.js, Vite, React)
+
+```javascript
+import { DolphinClient } from 'dolphin-client';
+
+const dolphin = new DolphinClient('http://localhost:3000', 'ROOM_101');
+await dolphin.connect();
+```
+
+### 2. In Plain HTML (Static / Script Tag)
+
+```html
+<script src="node_modules/dolphin-client/dist/dolphin-client.js"></script>
+<script>
+  const dolphin = new DolphinModule.DolphinClient('http://localhost:3000', 'ROOM_101');
+  dolphin.connect();
+</script>
+```
+
+## HTML Directives
+
+### Pushing value changes
+```html
+<input name="chat" data-rt-push="chat/messages/ROOM_101" placeholder="Type..." />
+```
+
+### Directives & Templates
+```html
+<div data-api-get="/api/devices" data-rt-bind="devices/online" data-rt-template='
+  <div data-rt-type="context">
+    <h3>{{id}}</h3>
+    <button onclick="dialPeer(&apos;{{id}}&apos;)">Dial</button>
+  </div>
+'></div>
+```
+
+## License
+
+ISC License

package/dist/a11y.d.ts

@@ -0,0 +1 @@
+export declare function attachA11y(clientProto: any): void;

package/dist/animation.d.ts

@@ -0,0 +1 @@
+export declare function attachAnimations(clientProto: any): void;

package/dist/api.d.ts

@@ -0,0 +1,30 @@
+export declare class APIHandler {
+    client: any;
+    /** @param {DolphinClient} client */
+    constructor(client: any);
+    /** @private */
+    _createProxy(pathParts: any): {
+        (options: any): any;
+        get(pathOrOptions: any, options: any): any;
+        post(pathOrBody: any, bodyOrOptions: any, options: any): any;
+        put(pathOrBody: any, bodyOrOptions: any, options: any): any;
+        patch(pathOrBody: any, bodyOrOptions: any, options: any): any;
+        del(pathOrOptions: any, options: any): any;
+        request(method: any, subPath: any, body: any, options: any): any;
+        requestDirect(method: any, path: any, body: any, options: any): any;
+    };
+    /**
+     * Intercept request for offline-first caching and queuing.
+     */
+    request(method: string, path: string, body?: any, options?: any): any;
+    /**
+     * Make an HTTP request with timeout + auto token refresh.
+     * @param {string}      method
+     * @param {string}      path
+     * @param {any}         [body]
+     * @param {RequestInit} [options]
+     * @param {boolean}     [_isRetry=false]   — internal: prevent infinite refresh loop
+     * @returns {Promise<any>}
+     */
+    requestDirect(method: any, path: any, body?: any, options?: any): any;
+}

package/dist/api.js

@@ -0,0 +1,112 @@
+export class APIHandler {
+    /** @param {DolphinClient} client */
+    constructor(client) {
+        this.client = client;
+        return this._createProxy([]);
+    }
+    /** @private */
+    _createProxy(pathParts) {
+        const joined = pathParts.join('/');
+        const target = (options) => this.request('GET', joined, null, options);
+        target.get = (pathOrOptions, options) => typeof pathOrOptions === 'string'
+            ? this.request('GET', pathOrOptions, null, options)
+            : this.request('GET', joined, null, pathOrOptions);
+        target.post = (pathOrBody, bodyOrOptions, options) => typeof pathOrBody === 'string'
+            ? this.request('POST', pathOrBody, bodyOrOptions, options)
+            : this.request('POST', joined, pathOrBody, bodyOrOptions);
+        target.put = (pathOrBody, bodyOrOptions, options) => typeof pathOrBody === 'string'
+            ? this.request('PUT', pathOrBody, bodyOrOptions, options)
+            : this.request('PUT', joined, pathOrBody, bodyOrOptions);
+        target.patch = (pathOrBody, bodyOrOptions, options) => typeof pathOrBody === 'string'
+            ? this.request('PATCH', pathOrBody, bodyOrOptions, options)
+            : this.request('PATCH', joined, pathOrBody, bodyOrOptions);
+        target.del = (pathOrOptions, options) => typeof pathOrOptions === 'string'
+            ? this.request('DELETE', pathOrOptions, null, options)
+            : this.request('DELETE', joined, null, pathOrOptions);
+        target.request = (method, subPath, body, options) => {
+            const finalPath = subPath
+                ? `${joined}/${subPath.startsWith('/') ? subPath.slice(1) : subPath}`
+                : joined;
+            return this.request(method, finalPath, body, options);
+        };
+        const methods = ['get', 'post', 'put', 'patch', 'del', 'request'];
+        return new Proxy(target, {
+            get: (t, prop) => {
+                if (typeof prop === 'string' && !methods.includes(prop)) {
+                    return this._createProxy([...pathParts, prop]);
+                }
+                return t[prop];
+            }
+        });
+    }
+    /**
+     * Make an HTTP request with timeout + auto token refresh.
+     * @param {string}      method
+     * @param {string}      path
+     * @param {any}         [body]
+     * @param {RequestInit} [options]
+     * @param {boolean}     [_isRetry=false]   — internal: prevent infinite refresh loop
+     * @returns {Promise<any>}
+     */
+    async request(method, path, body = null, options = {}) {
+        const _isRetry = options._isRetry === true;
+        const url = `${this.client.httpUrl}${path.startsWith('/') ? path : '/' + path}`;
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), this.client.options.timeout);
+        const headers = {
+            'Content-Type': 'application/json',
+            ...(options.headers || {}),
+        };
+        if (this.client.accessToken) {
+            headers['Authorization'] = `Bearer ${this.client.accessToken}`;
+        }
+        const fetchOptions = { ...options };
+        delete fetchOptions._isRetry;
+        try {
+            const response = await fetch(url, {
+                method,
+                headers,
+                signal: controller.signal,
+                ...(body ? { body: JSON.stringify(body) } : {}),
+                ...fetchOptions,
+            });
+            clearTimeout(timeoutId);
+            // Auto-refresh: 401 + not a retry + autoRefreshToken enabled
+            if (response.status === 401 &&
+                !_isRetry &&
+                this.client.options.autoRefreshToken) {
+                const refreshed = await this.client.auth._silentRefresh();
+                if (refreshed) {
+                    return this.request(method, path, body, { ...options, _isRetry: true });
+                }
+            }
+            const contentType = response.headers.get('content-type') || '';
+            const data = contentType.includes('application/json')
+                ? await response.json()
+                : await response.text();
+            if (!response.ok)
+                throw { status: response.status, data };
+            // Hookless auth token auto-save
+            if (data && typeof data === 'object') {
+                if (data.accessToken) {
+                    this.client.setToken(data.accessToken);
+                    if (data.user)
+                        this.client.auth.user = data.user;
+                }
+            }
+            // Auto-broadcast data changes
+            if (this.client.options.autoBroadcast && ['POST', 'PUT', 'PATCH', 'DELETE'].includes(method.toUpperCase())) {
+                const cleanPath = path.startsWith('/') ? path.substring(1) : path;
+                this.client.publish(cleanPath, { method: method.toUpperCase(), payload: body, result: data });
+            }
+            return data;
+        }
+        catch (err) {
+            clearTimeout(timeoutId);
+            if (err.name === 'AbortError') {
+                throw { status: 408, data: { error: 'Request timed out' } };
+            }
+            throw err;
+        }
+    }
+}

package/dist/auth.d.ts

@@ -0,0 +1,56 @@
+export declare class AuthHandler {
+    client: any;
+    user: any;
+    _refreshing: boolean;
+    /** @param {DolphinClient} client */
+    constructor(client: any);
+    /**
+     * Login with email + password.
+     * @param {string} email
+     * @param {string} password
+     */
+    login(email: any, password: any): Promise<any>;
+    /**
+     * Register a new account.
+     * @param {{ email: string, password: string, [key: string]: any }} data
+     */
+    register(data: any): Promise<any>;
+    /** Get current user profile. */
+    me(): Promise<any>;
+    /** Logout and clear token. */
+    logout(): Promise<void>;
+    /**
+     * Manually refresh the access token using the httpOnly refresh-token cookie.
+     * Called automatically on 401 if autoRefreshToken is enabled.
+     * @returns {Promise<boolean>} — true if refresh succeeded
+     */
+    refresh(): Promise<boolean>;
+    /** @private */
+    _silentRefresh(): Promise<boolean>;
+    /**
+     * Verify a 2FA TOTP code after login.
+     * @param {string} code     — 6-digit TOTP code
+     * @param {string} [email]  — email (if not already in user)
+     */
+    verify2FA(code: any, email: any): Promise<any>;
+    /**
+     * Enable 2FA — returns QR code URL and secret.
+     */
+    enable2FA(): Promise<any>;
+    /**
+     * Disable 2FA.
+     * @param {string} code — current TOTP code to confirm
+     */
+    disable2FA(code: any): Promise<any>;
+    /**
+     * Request a password reset email.
+     * @param {string} email
+     */
+    forgotPassword(email: any): Promise<any>;
+    /**
+     * Reset password using the token from email.
+     * @param {string} token
+     * @param {string} newPassword
+     */
+    resetPassword(token: any, newPassword: any): Promise<any>;
+}

package/dist/auth.js

@@ -0,0 +1,120 @@
+export class AuthHandler {
+    /** @param {DolphinClient} client */
+    constructor(client) {
+        this.client = client;
+        /** @type {any|null} */
+        this.user = null;
+        this._refreshing = false;
+    }
+    /**
+     * Login with email + password.
+     * @param {string} email
+     * @param {string} password
+     */
+    async login(email, password) {
+        const res = await this.client.api.post('/api/auth/login', { email, password });
+        if (res.accessToken) {
+            this.client.setToken(res.accessToken);
+            this.user = res.user || null;
+        }
+        return res;
+    }
+    /**
+     * Register a new account.
+     * @param {{ email: string, password: string, [key: string]: any }} data
+     */
+    async register(data) {
+        return this.client.api.post('/api/auth/register', data);
+    }
+    /** Get current user profile. */
+    async me() {
+        const res = await this.client.api.get('/api/auth/me');
+        if (res.success)
+            this.user = res.data;
+        return res;
+    }
+    /** Logout and clear token. */
+    async logout() {
+        try {
+            await this.client.api.post('/api/auth/logout');
+        }
+        catch { }
+        this.client.setToken(null);
+        this.user = null;
+    }
+    /**
+     * Manually refresh the access token using the httpOnly refresh-token cookie.
+     * Called automatically on 401 if autoRefreshToken is enabled.
+     * @returns {Promise<boolean>} — true if refresh succeeded
+     */
+    async refresh() {
+        return this._silentRefresh();
+    }
+    /** @private */
+    async _silentRefresh() {
+        if (this._refreshing)
+            return false;
+        this._refreshing = true;
+        try {
+            const res = await this.client.api.post('/api/auth/refresh', null, { _isRetry: true });
+            if (res.accessToken) {
+                this.client.setToken(res.accessToken);
+                return true;
+            }
+            return false;
+        }
+        catch {
+            this.client.setToken(null);
+            return false;
+        }
+        finally {
+            this._refreshing = false;
+        }
+    }
+    /**
+     * Verify a 2FA TOTP code after login.
+     * @param {string} code     — 6-digit TOTP code
+     * @param {string} [email]  — email (if not already in user)
+     */
+    async verify2FA(code, email) {
+        const payload = {
+            code,
+            email: email || this.user?.email,
+        };
+        const res = await this.client.api.post('/api/auth/2fa/verify', payload);
+        if (res.accessToken) {
+            this.client.setToken(res.accessToken);
+            if (res.user)
+                this.user = res.user;
+        }
+        return res;
+    }
+    /**
+     * Enable 2FA — returns QR code URL and secret.
+     */
+    async enable2FA() {
+        return this.client.api.post('/api/auth/2fa/enable');
+    }
+    /**
+     * Disable 2FA.
+     * @param {string} code — current TOTP code to confirm
+     */
+    async disable2FA(code) {
+        return this.client.api.post('/api/auth/2fa/disable', { code });
+    }
+    /**
+     * Request a password reset email.
+     * @param {string} email
+     */
+    async forgotPassword(email) {
+        return this.client.api.post('/api/auth/forgot-password', { email });
+    }
+    /**
+     * Reset password using the token from email.
+     * @param {string} token
+     * @param {string} newPassword
+     */
+    async resetPassword(token, newPassword) {
+        return this.client.api.post('/api/auth/reset-password', { token, newPassword });
+    }
+}

package/dist/collab.d.ts

@@ -0,0 +1 @@
+export declare function attachCollab(clientProto: any): void;

package/dist/core.d.ts

@@ -0,0 +1,119 @@
+export declare class DolphinClient {
+    host: string;
+    httpUrl: string;
+    deviceId: string;
+    options: any;
+    socket: any;
+    storage: any;
+    accessToken: string | null;
+    api: any;
+    auth: any;
+    store: any;
+    handlers: Map<string, Set<any>>;
+    signalHandlers: Set<any>;
+    fileHandlers: Set<any>;
+    _offlineQueue: string[];
+    reconnectAttempts: number;
+    _attachedListeners: {
+        target: any;
+        event: string;
+        cb: any;
+    }[];
+    constructor(url?: string, deviceId?: string, options?: {});
+    /** Save or clear the access token */
+    setToken(token: any): void;
+    /** Connect to the Dolphin realtime server */
+    connect(): Promise<void>;
+    /** Disconnect cleanly */
+    disconnect(): void;
+    /** @private */
+    _handleMessage(data: any): void;
+    /** @private */
+    _dispatch(pattern: any, payload: any, topic?: any): void;
+    /** @private */
+    _sendRaw(msg: any): void;
+    /** Flush buffered messages after reconnect @private */
+    _flushOfflineQueue(): void;
+    /** @private */
+    _sendAck(to: any, msgId: any): void;
+    /** MQTT wildcard topic matching @private */
+    _matchTopic(pattern: any, topic: any): boolean;
+    /** @private */
+    _maybeReconnect(): void;
+    /**
+     * Subscribe to a topic (MQTT wildcards supported: + and #).
+     * @param {string}        topic
+     * @param {TopicCallback} callback
+     */
+    subscribe(topic: any, callback: any): void;
+    /**
+     * Unsubscribe from a topic.
+     * @param {string}        topic
+     * @param {TopicCallback} callback
+     */
+    unsubscribe(topic: any, callback: any): void;
+    /**
+     * Publish a message to a topic. Queued if offline.
+     * @param {string} topic
+     * @param {any}    payload
+     */
+    publish(topic: any, payload: any): void;
+    /**
+     * High-frequency data push (IoT sensors).
+     * @param {string} topic
+     * @param {any}    payload
+     */
+    pubPush(topic: any, payload: any): void;
+    /**
+     * Request historical data from a topic.
+     * @param {string} topic
+     * @param {number} [count=10]
+     */
+    subPull(topic: any, count?: number): void;
+    /**
+     * Upload a file to the server in chunks.
+     * @param {string}   fileId
+     * @param {Blob|ArrayBuffer|Uint8Array} fileData
+     * @param {string}   [filename]
+     * @param {function(number): void} [onProgress]  — progress callback (0-100)
+     * @returns {Promise<void>}
+     */
+    pubFile(fileId: any, fileData: any, filename: string, onProgress: any): Promise<void>;
+    /** @private */
+    _uint8ToBase64(uint8: any): string;
+    /**
+     * Download a file from the server by chunks.
+     * @param {string} fileId
+     * @param {number} [startChunk=0]
+     */
+    subFile(fileId: any, startChunk?: number): void;
+    /**
+     * Resume a file download from saved progress.
+     * @param {string} fileId
+     */
+    resumeFile(fileId: any): void;
+    /**
+     * Save download chunk progress.
+     * @param {string} fileId
+     * @param {number} chunkIndex
+     */
+    saveFileProgress(fileId: any, chunkIndex: any): void;
+    /**
+     * @param {function(SignalMessage): void} handler
+     */
+    onSignal(handler: any): void;
+    /**
+     * @param {function(SignalMessage): void} handler
+     */
+    offSignal(handler: any): void;
+    /**
+     * @param {function(FileMetadata): void} handler
+     */
+    onFileAvailable(handler: any): void;
+    /**
+     * @param {function(FileMetadata): void} handler
+     */
+    offFileAvailable(handler: any): void;
+    addDomListener(target: any, event: string, cb: any): void;
+    cleanupDomListeners(): void;
+}