@skipphq/desk-web 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Skipp
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS IN CONTRACT OFFICERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,152 @@
+# @skipphq/desk-web
+
+Official JavaScript / TypeScript Web SDK for the **Skipp Desk** customer support chat widget.
+
+Easily integrate live chat, support tickets, and identity verification into React, Vue, Next.js, or plain HTML websites.
+
+---
+
+## 📦 Installation
+
+```sh
+npm install @skipphq/desk-web
+# or
+yarn add @skipphq/desk-web
+# or
+pnpm add @skipphq/desk-web
+```
+
+---
+
+## 🚀 Quick Start
+
+### 1. React / Next.js / Single Page Apps
+
+```ts
+import { SkippDesk } from '@skipphq/desk-web';
+import { useEffect } from 'react';
+
+export function SupportWidget() {
+  useEffect(() => {
+    // Initialize Skipp Desk
+    SkippDesk.init({
+      workspaceId: 'YOUR_WORKSPACE_ID',
+      // Optional pre-authenticated backend JWT identity token
+      identityToken: userJwtToken,
+      user: {
+        name: 'Timi Adesina',
+        email: 'adesinatim@gmail.com',
+      },
+    });
+
+    // Listen to events
+    const unsub = SkippDesk.on('unread-count-change', (count) => {
+      console.log('Unread messages:', count);
+    });
+
+    return () => unsub();
+  }, []);
+
+  return (
+    <button onClick={() => SkippDesk.open()}>
+      Need help? Chat with us
+    </button>
+  );
+}
+```
+
+---
+
+### 2. HTML Module Import
+
+```html
+<script type="module">
+  import { SkippDesk } from 'https://cdn.jsdelivr.net/npm/@skipphq/desk-web/+esm';
+
+  SkippDesk.init({
+    workspaceId: 'YOUR_WORKSPACE_ID',
+    user: { name: 'Alex' },
+  });
+</script>
+```
+
+---
+
+### 3. Standalone Script Tag (Alternative Embed)
+
+If you prefer not to use an NPM package or ESM import, you can embed the widget directly using a single `<script>` tag:
+
+```html
+<!-- Embedded Widget Script -->
+<script
+  src="https://cdn.skipp.cx/widget.js"
+  data-workspace-id="YOUR_WORKSPACE_ID"
+  data-position="right"
+  data-brand-color="#25282d">
+</script>
+
+<!-- Optional: Control widget via global window.SkippDesk -->
+<script>
+  window.addEventListener('DOMContentLoaded', () => {
+    // Open widget
+    window.SkippDesk.open();
+
+    // Set logged-in user JWT identity token
+    window.SkippDesk.setIdentityToken('USER_JWT_TOKEN');
+  });
+</script>
+```
+
+Both methods support identical runtime controls (`open`, `close`, `toggle`, `setIdentityToken`, `logout`).
+
+---
+
+## 📖 API Reference
+
+### `SkippDesk.init(config)`
+Initialize the widget on the page.
+
+```ts
+SkippDesk.init({
+  workspaceId: string;      // Required Workspace ID
+  identityToken?: string;   // Optional backend-signed JWT token
+  apiBaseUrl?: string;      // Custom API endpoint override
+  position?: 'left' | 'right'; // Position of launcher button
+  brandColor?: string;      // Brand color override (#176b57)
+  welcomeMessage?: string;  // Custom greeting message
+  user?: {
+    name?: string;
+    email?: string;
+    phone?: string;
+  };
+});
+```
+
+### Methods
+
+| Method | Description |
+| :--- | :--- |
+| `SkippDesk.open()` | Open the chat widget |
+| `SkippDesk.close()` | Minimize the chat widget |
+| `SkippDesk.toggle()` | Toggle open/closed state |
+| `SkippDesk.show()` | Show launcher button if hidden |
+| `SkippDesk.hide()` | Hide launcher button |
+| `SkippDesk.setUser(user)` | Identify or update logged-in user details |
+| `SkippDesk.setIdentityToken(token)` | Set/update JWT pre-auth token dynamically |
+| `SkippDesk.logout()` | Clear session and log out customer |
+| `SkippDesk.on(event, callback)` | Subscribe to events (`'ready'`, `'open'`, `'close'`, `'unread-count-change'`) |
+
+---
+
+## 🛡️ Pre-Authenticated Customer Identity
+
+For seamless cross-device continuity without requiring users to fill out contact forms:
+
+1. Generate a JWT identity token on your backend signed with your Workspace identity secret.
+2. Pass `identityToken` during `init()` or call `SkippDesk.setIdentityToken(jwtToken)` upon user login.
+
+---
+
+## 📄 License
+
+MIT © [Skipp](https://skipp.cx)

package/dist/index.d.ts

@@ -0,0 +1,66 @@
+import type { SkippDeskConfig, SkippDeskEvent, SkippDeskEventListener, SkippDeskPosition, SkippDeskUser } from "./types.js";
+export type { SkippDeskConfig, SkippDeskEvent, SkippDeskEventListener, SkippDeskPosition, SkippDeskUser, };
+declare class SkippDeskSDK {
+    private config;
+    private listeners;
+    private ready;
+    private messageHandlerAttached;
+    /**
+     * Initialize Skipp Desk on the page with workspace and identity settings.
+     */
+    init(config: SkippDeskConfig): Promise<void>;
+    /**
+     * Open the chat widget.
+     */
+    open(): void;
+    /**
+     * Close/minimize the chat widget.
+     */
+    close(): void;
+    /**
+     * Toggle open/close state of the chat widget.
+     */
+    toggle(): void;
+    /**
+     * Show the launcher button if hidden.
+     */
+    show(): void;
+    /**
+     * Hide the launcher button.
+     */
+    hide(): void;
+    /**
+     * Set or update backend-signed JWT identity token dynamically.
+     */
+    setIdentityToken(token: string): void;
+    /**
+     * Identify or update logged-in customer info dynamically.
+     */
+    setUser(user: SkippDeskUser): void;
+    /**
+     * Log out the current user and clear visitor session state.
+     */
+    logout(): Promise<void>;
+    /**
+     * Reset visitor session and clear local widget state.
+     */
+    reset(): Promise<void>;
+    /**
+     * Subscribe to widget lifecycle events.
+     */
+    on(event: SkippDeskEvent, callback: SkippDeskEventListener): () => void;
+    /**
+     * Unsubscribe from widget lifecycle events.
+     */
+    off(event: SkippDeskEvent, callback: SkippDeskEventListener): void;
+    /**
+     * Check whether Skipp Desk is initialized and ready.
+     */
+    isReady(): boolean;
+    private emit;
+    private dispatchCommand;
+    private ensureMessageHandler;
+    private injectScript;
+}
+export declare const SkippDesk: SkippDeskSDK;
+export default SkippDesk;

package/dist/index.js

@@ -0,0 +1,254 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SkippDesk = void 0;
+const DEFAULT_WIDGET_URL = "https://cdn.skipp.cx/widget.js";
+const DEFAULT_API_BASE_URL = "https://api.zirrodesk.com";
+const WIDGET_SCRIPT_ID = "skipp-desk-widget-script";
+class SkippDeskSDK {
+    config = null;
+    listeners = new Map();
+    ready = false;
+    messageHandlerAttached = false;
+    /**
+     * Initialize Skipp Desk on the page with workspace and identity settings.
+     */
+    async init(config) {
+        if (!config.workspaceId) {
+            throw new Error("SkippDesk.init requires a valid workspaceId.");
+        }
+        this.config = {
+            ...config,
+            apiBaseUrl: (config.apiBaseUrl || DEFAULT_API_BASE_URL).replace(/\/$/, ""),
+            widgetUrl: config.widgetUrl || DEFAULT_WIDGET_URL,
+        };
+        // Store pre-authenticated identity token if provided
+        if (this.config.identityToken && typeof window !== "undefined") {
+            try {
+                window.localStorage.setItem(`skipp-widget-identity-token:${this.config.workspaceId}`, this.config.identityToken);
+                window.localStorage.setItem(`zirro-desk-widget-identity-token:${this.config.workspaceId}`, this.config.identityToken);
+            }
+            catch {
+                // Ignore localStorage restrictions
+            }
+        }
+        // Attach window message listener for widget events
+        this.ensureMessageHandler();
+        // Inject widget script if not present
+        await this.injectScript();
+        // Notify listeners if widget is ready
+        if (this.ready) {
+            this.emit("ready", { workspaceId: this.config.workspaceId });
+        }
+        if (config.user) {
+            this.setUser(config.user);
+        }
+        if (config.autoOpen) {
+            this.open();
+        }
+    }
+    /**
+     * Open the chat widget.
+     */
+    open() {
+        this.dispatchCommand("open");
+    }
+    /**
+     * Close/minimize the chat widget.
+     */
+    close() {
+        this.dispatchCommand("close");
+    }
+    /**
+     * Toggle open/close state of the chat widget.
+     */
+    toggle() {
+        this.dispatchCommand("toggle");
+    }
+    /**
+     * Show the launcher button if hidden.
+     */
+    show() {
+        this.dispatchCommand("show");
+    }
+    /**
+     * Hide the launcher button.
+     */
+    hide() {
+        this.dispatchCommand("hide");
+    }
+    /**
+     * Set or update backend-signed JWT identity token dynamically.
+     */
+    setIdentityToken(token) {
+        if (!this.config)
+            return;
+        try {
+            window.localStorage.setItem(`skipp-widget-identity-token:${this.config.workspaceId}`, token);
+            window.localStorage.setItem(`zirro-desk-widget-identity-token:${this.config.workspaceId}`, token);
+        }
+        catch {
+            // Ignore
+        }
+        this.dispatchCommand("setIdentityToken", { token });
+    }
+    /**
+     * Identify or update logged-in customer info dynamically.
+     */
+    setUser(user) {
+        if (!this.config)
+            return;
+        this.dispatchCommand("setUser", user);
+    }
+    /**
+     * Log out the current user and clear visitor session state.
+     */
+    async logout() {
+        await this.reset();
+    }
+    /**
+     * Reset visitor session and clear local widget state.
+     */
+    async reset() {
+        if (this.config && typeof window !== "undefined") {
+            try {
+                window.localStorage.removeItem(`skipp-widget-identity-token:${this.config.workspaceId}`);
+                window.localStorage.removeItem(`zirro-desk-widget-identity-token:${this.config.workspaceId}`);
+                window.localStorage.removeItem(`zirro-desk-widget-visitor-token:${this.config.workspaceId}`);
+            }
+            catch {
+                // Ignore
+            }
+        }
+        this.dispatchCommand("logout");
+    }
+    /**
+     * Subscribe to widget lifecycle events.
+     */
+    on(event, callback) {
+        if (!this.listeners.has(event)) {
+            this.listeners.set(event, new Set());
+        }
+        this.listeners.get(event).add(callback);
+        return () => this.off(event, callback);
+    }
+    /**
+     * Unsubscribe from widget lifecycle events.
+     */
+    off(event, callback) {
+        const callbacks = this.listeners.get(event);
+        if (callbacks) {
+            callbacks.delete(callback);
+        }
+    }
+    /**
+     * Check whether Skipp Desk is initialized and ready.
+     */
+    isReady() {
+        return this.ready;
+    }
+    // Private helpers
+    emit(event, data) {
+        const callbacks = this.listeners.get(event);
+        if (callbacks) {
+            callbacks.forEach((cb) => {
+                try {
+                    cb(data);
+                }
+                catch (err) {
+                    console.error(`[SkippDesk] Error in '${event}' event listener:`, err);
+                }
+            });
+        }
+    }
+    dispatchCommand(action, data = {}) {
+        if (typeof window === "undefined")
+            return;
+        // Call window.SkippDesk if exposed by widget.js
+        const globalSkipp = window.SkippDesk;
+        if (globalSkipp && typeof globalSkipp[action] === "function") {
+            globalSkipp[action](data);
+            return;
+        }
+        // Fallback: postMessage to iframe or window
+        const messagePayload = {
+            source: "skipp-desk-sdk",
+            action,
+            workspaceId: this.config?.workspaceId,
+            ...data,
+        };
+        window.postMessage(messagePayload, "*");
+    }
+    ensureMessageHandler() {
+        if (this.messageHandlerAttached || typeof window === "undefined")
+            return;
+        window.addEventListener("message", (event) => {
+            if (!event.data)
+                return;
+            let payload = event.data;
+            if (typeof payload === "string") {
+                try {
+                    payload = JSON.parse(payload);
+                }
+                catch {
+                    return;
+                }
+            }
+            if (payload.source !== "skipp-desk" && payload.source !== "zirro-desk")
+                return;
+            switch (payload.type) {
+                case "ready":
+                    this.ready = true;
+                    this.emit("ready", payload);
+                    break;
+                case "open":
+                    this.emit("open");
+                    break;
+                case "close":
+                    this.emit("close");
+                    break;
+                case "unread_count_change":
+                case "unread-count-change":
+                    this.emit("unread-count-change", payload.unreadCount ?? payload.count ?? 0);
+                    break;
+                case "ticket_created":
+                case "ticket-created":
+                    this.emit("ticket-created", payload);
+                    break;
+                case "error":
+                    this.emit("error", new Error(payload.message || "Skipp Desk Widget Error"));
+                    break;
+            }
+        });
+        this.messageHandlerAttached = true;
+    }
+    injectScript() {
+        if (typeof document === "undefined" || !this.config)
+            return Promise.resolve();
+        if (document.getElementById(WIDGET_SCRIPT_ID)) {
+            return Promise.resolve();
+        }
+        return new Promise((resolve, reject) => {
+            const script = document.createElement("script");
+            script.id = WIDGET_SCRIPT_ID;
+            script.async = true;
+            script.src = this.config.widgetUrl || DEFAULT_WIDGET_URL;
+            script.dataset.workspaceId = this.config.workspaceId;
+            script.dataset.apiBaseUrl = this.config.apiBaseUrl;
+            if (this.config.position) {
+                script.dataset.position = this.config.position;
+            }
+            script.onload = () => {
+                this.ready = true;
+                resolve();
+            };
+            script.onerror = (err) => {
+                const error = new Error(`Failed to load Skipp Desk widget script from ${script.src}`);
+                this.emit("error", error);
+                reject(error);
+            };
+            document.head.appendChild(script);
+        });
+    }
+}
+exports.SkippDesk = new SkippDeskSDK();
+exports.default = exports.SkippDesk;

package/dist/types.d.ts

@@ -0,0 +1,52 @@
+export type SkippDeskPosition = "left" | "right";
+export type SkippDeskUser = {
+    id?: string;
+    name?: string;
+    email?: string;
+    phone?: string;
+};
+export type SkippDeskConfig = {
+    /**
+     * Your Skipp Desk Workspace ID (Required)
+     */
+    workspaceId: string;
+    /**
+     * Base URL for the Skipp Desk API (Defaults to production API if omitted)
+     */
+    apiBaseUrl?: string;
+    /**
+     * Hosted URL of the widget script (Defaults to https://cdn.skipp.cx/widget.js if omitted)
+     */
+    widgetUrl?: string;
+    /**
+     * Pre-authenticated JWT identity token issued by your backend
+     */
+    identityToken?: string;
+    /**
+     * User identity information
+     */
+    user?: SkippDeskUser;
+    /**
+     * Position of the chat widget button
+     */
+    position?: SkippDeskPosition;
+    /**
+     * Primary brand color override (hex format)
+     */
+    brandColor?: string;
+    /**
+     * Custom welcome message override
+     */
+    welcomeMessage?: string;
+    /**
+     * Auto-open widget after initialization
+     */
+    autoOpen?: boolean;
+};
+export type SkippDeskEvent = "ready" | "open" | "close" | "unread-count-change" | "ticket-created" | "error";
+export type SkippDeskEventListener = (data?: Record<string, unknown> | number | string | Error) => void;
+export type SkippDeskCommand = ["init", SkippDeskConfig] | ["open"] | ["close"] | ["toggle"] | ["show"] | ["hide"] | ["setIdentityToken", string] | ["setUser", SkippDeskUser] | ["logout"] | ["reset"] | ["on", SkippDeskEvent, SkippDeskEventListener] | ["off", SkippDeskEvent, SkippDeskEventListener];
+export interface SkippDeskGlobalQueue {
+    q?: SkippDeskCommand[];
+    (...args: SkippDeskCommand): void;
+}

package/dist/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@skipphq/desk-web",
+  "version": "0.3.0",
+  "description": "Web SDK for Skipp Desk support widget",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "module": "dist/index.js",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "npm run build && node --test tests/*.test.cjs",
+    "prepack": "npm run build",
+    "publish:check": "npm pack --dry-run"
+  },
+  "homepage": "https://www.npmjs.com/package/@skipphq/desk-web",
+  "keywords": [
+    "skipp",
+    "skipp-desk",
+    "customer-support",
+    "help-desk",
+    "chat-widget",
+    "web-sdk",
+    "typescript"
+  ],
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "typescript": "~5.9.3"
+  },
+  "license": "MIT"
+}