@nextxai/sdk 0.1.2 → 0.2.0

package/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 Theo [Semantic Versioning](https://semver.org/lang/vi/). Chính sách phiên bản: [VERSIONING.md](VERSIONING.md).
 
+## 0.2.0 (2026-10-30)
+
+### Thêm mới
+
+- `@nextxai/sdk/phone` (chỉ Node): `NextXPhone` — nhúng softphone NextX vào phần mềm của bạn trên trình duyệt (`init`, `call`, `hangup`, `logout`, `destroy`, sự kiện `ready` · `auth-required` · `status` · `incoming` · `answered` · `ended` · `error`). Cùng mã với bản `<script src="https://developers.nextx.vn/phone/v1/phone.js">`.
+
 ## 0.1.2 (2026-10-30)
 
 ### Thêm mới

package/dist/cjs/phone.d.ts

@@ -0,0 +1,84 @@
+/**
+ * NextX Phone — nhúng softphone NextX vào phần mềm của bạn (chạy trên trình duyệt).
+ *
+ *   import { NextXPhone } from "@nextxai/sdk/phone";
+ *   const phone = NextXPhone.init({ clientId: "app_…" });
+ *   phone.on("incoming", (c) => openCustomer(c.from));
+ *   phone.call("0901234567");
+ *
+ * Hoặc thẻ script: <script src="https://developers.nextx.vn/phone/v1/phone.js"></script> ⇒ `window.NextXPhone`.
+ *
+ * Softphone chạy trong iframe do NextX phục vụ; tổng đài viên đăng nhập NextX trong cửa sổ bật lên. Trang của bạn chỉ
+ * nhận sự kiện cuộc gọi — không bao giờ nhận token hay thông tin máy lẻ. Tên miền trang của bạn phải được khai trong
+ * developers.nextx.vn › Ứng dụng của tôi › Cài đặt › Softphone nhúng.
+ */
+export declare const PHONE_PROTOCOL = "nxphone/1";
+export interface NextXPhoneOptions {
+    /** client_id của ứng dụng của bạn trên developers.nextx.vn. */
+    clientId: string;
+    /** Ngôn ngữ giao diện. Mặc định "vi". */
+    lang?: "vi" | "en";
+    /** Workspace NextX muốn đăng nhập (bỏ trống = workspace mặc định của tổng đài viên). */
+    workspaceId?: string;
+    /** Góc màn hình. Mặc định "bottom-right". */
+    position?: "bottom-right" | "bottom-left";
+    /** Khoảng cách tới mép (px). Mặc định 0. */
+    offset?: number;
+    /** Bắt số trong các phần tử có `data-nextx-call="<số>"` (bấm là gọi). Mặc định true. */
+    clickToDial?: boolean;
+    /** Ghi đè địa chỉ ứng dụng (vd sandbox: "https://app-dev.nextx.vn"). */
+    appUrl?: string;
+}
+export interface PhoneCallEvent {
+    callId: string;
+    from?: string;
+    to?: string;
+    direction?: string;
+    status?: string;
+    talkSec?: number;
+}
+export interface PhoneEvents {
+    ready: {
+        loggedIn: boolean;
+    };
+    "auth-required": Record<string, never>;
+    status: {
+        registered: boolean;
+        extension?: string | null;
+    };
+    incoming: PhoneCallEvent;
+    answered: PhoneCallEvent;
+    ended: PhoneCallEvent;
+    error: {
+        code: string;
+        message?: string;
+    };
+}
+type Handler<K extends keyof PhoneEvents> = (payload: PhoneEvents[K]) => void;
+export declare class NextXPhone {
+    private readonly options;
+    private readonly iframe;
+    private readonly origin;
+    private readonly handlers;
+    private readonly queue;
+    private ready;
+    private readonly onMessage;
+    private readonly onClick;
+    private constructor();
+    /** Tạo và gắn NextX Phone vào trang. */
+    static init(options: NextXPhoneOptions): NextXPhone;
+    /** Nghe sự kiện. Trả hàm huỷ đăng ký. */
+    on<K extends keyof PhoneEvents>(event: K, handler: Handler<K>): () => void;
+    /** Gọi ra từ máy lẻ của tổng đài viên đang đăng nhập. */
+    call(number: string, opts?: {
+        contactRef?: string;
+    }): void;
+    /** Gác cuộc gọi đang diễn ra. */
+    hangup(): void;
+    /** Đăng xuất NextX trong khung softphone. */
+    logout(): void;
+    /** Gỡ softphone khỏi trang. */
+    destroy(): void;
+    private send;
+}
+export default NextXPhone;

package/dist/cjs/phone.js

@@ -0,0 +1,127 @@
+"use strict";
+/// <reference lib="dom" />
+/**
+ * NextX Phone — nhúng softphone NextX vào phần mềm của bạn (chạy trên trình duyệt).
+ *
+ *   import { NextXPhone } from "@nextxai/sdk/phone";
+ *   const phone = NextXPhone.init({ clientId: "app_…" });
+ *   phone.on("incoming", (c) => openCustomer(c.from));
+ *   phone.call("0901234567");
+ *
+ * Hoặc thẻ script: <script src="https://developers.nextx.vn/phone/v1/phone.js"></script> ⇒ `window.NextXPhone`.
+ *
+ * Softphone chạy trong iframe do NextX phục vụ; tổng đài viên đăng nhập NextX trong cửa sổ bật lên. Trang của bạn chỉ
+ * nhận sự kiện cuộc gọi — không bao giờ nhận token hay thông tin máy lẻ. Tên miền trang của bạn phải được khai trong
+ * developers.nextx.vn › Ứng dụng của tôi › Cài đặt › Softphone nhúng.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NextXPhone = exports.PHONE_PROTOCOL = void 0;
+exports.PHONE_PROTOCOL = "nxphone/1";
+const DEFAULT_APP_URL = "https://app.nextx.vn";
+const INITIAL = { width: 96, height: 96 };
+class NextXPhone {
+    constructor(options) {
+        this.options = options;
+        this.handlers = new Map();
+        this.queue = [];
+        this.ready = false;
+        if (!options?.clientId)
+            throw new Error("NextXPhone: thiếu clientId");
+        const appUrl = (options.appUrl ?? DEFAULT_APP_URL).replace(/\/+$/, "");
+        this.origin = new URL(appUrl).origin;
+        const q = new URLSearchParams({ client_id: options.clientId });
+        if (options.workspaceId)
+            q.set("workspace_id", options.workspaceId);
+        const f = document.createElement("iframe");
+        f.src = `${appUrl}/${options.lang ?? "vi"}/phone/embed?${q}`;
+        f.title = "NextX Phone";
+        f.allow = "microphone; autoplay";
+        f.setAttribute("allowtransparency", "true");
+        const side = options.position === "bottom-left" ? "left" : "right";
+        const off = `${options.offset ?? 0}px`;
+        Object.assign(f.style, {
+            position: "fixed",
+            bottom: off,
+            [side]: off,
+            width: `${INITIAL.width}px`,
+            height: `${INITIAL.height}px`,
+            border: "0",
+            background: "transparent",
+            colorScheme: "normal",
+            zIndex: "2147483000",
+        });
+        this.iframe = f;
+        this.onMessage = (e) => {
+            if (e.origin !== this.origin || e.source !== f.contentWindow)
+                return;
+            const msg = e.data;
+            if (!msg || msg.protocol !== exports.PHONE_PROTOCOL || !msg.event)
+                return;
+            const { type, ...payload } = msg.event;
+            if (type === "resize") {
+                const w = Math.max(64, Math.min(Number(payload.width) || INITIAL.width, window.innerWidth));
+                const h = Math.max(64, Math.min(Number(payload.height) || INITIAL.height, window.innerHeight));
+                f.style.width = `${w}px`;
+                f.style.height = `${h}px`;
+                return;
+            }
+            if (type === "ready" && !this.ready) {
+                this.ready = true;
+                for (const c of this.queue.splice(0))
+                    this.send(c);
+            }
+            this.handlers.get(type)?.forEach((h) => h(payload));
+        };
+        this.onClick = (e) => {
+            const el = e.target?.closest?.("[data-nextx-call]");
+            const number = el?.getAttribute("data-nextx-call");
+            if (!number)
+                return;
+            e.preventDefault();
+            this.call(number, { contactRef: el?.getAttribute("data-nextx-contact-ref") ?? undefined });
+        };
+        window.addEventListener("message", this.onMessage);
+        if (options.clickToDial !== false)
+            document.addEventListener("click", this.onClick);
+        (document.body ?? document.documentElement).appendChild(f);
+    }
+    /** Tạo và gắn NextX Phone vào trang. */
+    static init(options) {
+        return new NextXPhone(options);
+    }
+    /** Nghe sự kiện. Trả hàm huỷ đăng ký. */
+    on(event, handler) {
+        const set = this.handlers.get(event) ?? new Set();
+        set.add(handler);
+        this.handlers.set(event, set);
+        return () => set.delete(handler);
+    }
+    /** Gọi ra từ máy lẻ của tổng đài viên đang đăng nhập. */
+    call(number, opts = {}) {
+        this.send({ type: "call", number: String(number), contactRef: opts.contactRef });
+    }
+    /** Gác cuộc gọi đang diễn ra. */
+    hangup() {
+        this.send({ type: "hangup" });
+    }
+    /** Đăng xuất NextX trong khung softphone. */
+    logout() {
+        this.send({ type: "logout" });
+    }
+    /** Gỡ softphone khỏi trang. */
+    destroy() {
+        window.removeEventListener("message", this.onMessage);
+        document.removeEventListener("click", this.onClick);
+        this.iframe.remove();
+        this.handlers.clear();
+    }
+    send(command) {
+        if (!this.ready || !this.iframe.contentWindow) {
+            this.queue.push(command);
+            return;
+        }
+        this.iframe.contentWindow.postMessage({ protocol: exports.PHONE_PROTOCOL, command }, this.origin);
+    }
+}
+exports.NextXPhone = NextXPhone;
+exports.default = NextXPhone;

package/dist/cjs/version.d.ts

@@ -1 +1 @@
-export declare const VERSION = "0.1.2";
+export declare const VERSION = "0.2.0";

package/dist/cjs/version.js

@@ -1,4 +1,4 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.VERSION = void 0;
-exports.VERSION = "0.1.2";
+exports.VERSION = "0.2.0";

package/dist/esm/phone.d.ts

@@ -0,0 +1,84 @@
+/**
+ * NextX Phone — nhúng softphone NextX vào phần mềm của bạn (chạy trên trình duyệt).
+ *
+ *   import { NextXPhone } from "@nextxai/sdk/phone";
+ *   const phone = NextXPhone.init({ clientId: "app_…" });
+ *   phone.on("incoming", (c) => openCustomer(c.from));
+ *   phone.call("0901234567");
+ *
+ * Hoặc thẻ script: <script src="https://developers.nextx.vn/phone/v1/phone.js"></script> ⇒ `window.NextXPhone`.
+ *
+ * Softphone chạy trong iframe do NextX phục vụ; tổng đài viên đăng nhập NextX trong cửa sổ bật lên. Trang của bạn chỉ
+ * nhận sự kiện cuộc gọi — không bao giờ nhận token hay thông tin máy lẻ. Tên miền trang của bạn phải được khai trong
+ * developers.nextx.vn › Ứng dụng của tôi › Cài đặt › Softphone nhúng.
+ */
+export declare const PHONE_PROTOCOL = "nxphone/1";
+export interface NextXPhoneOptions {
+    /** client_id của ứng dụng của bạn trên developers.nextx.vn. */
+    clientId: string;
+    /** Ngôn ngữ giao diện. Mặc định "vi". */
+    lang?: "vi" | "en";
+    /** Workspace NextX muốn đăng nhập (bỏ trống = workspace mặc định của tổng đài viên). */
+    workspaceId?: string;
+    /** Góc màn hình. Mặc định "bottom-right". */
+    position?: "bottom-right" | "bottom-left";
+    /** Khoảng cách tới mép (px). Mặc định 0. */
+    offset?: number;
+    /** Bắt số trong các phần tử có `data-nextx-call="<số>"` (bấm là gọi). Mặc định true. */
+    clickToDial?: boolean;
+    /** Ghi đè địa chỉ ứng dụng (vd sandbox: "https://app-dev.nextx.vn"). */
+    appUrl?: string;
+}
+export interface PhoneCallEvent {
+    callId: string;
+    from?: string;
+    to?: string;
+    direction?: string;
+    status?: string;
+    talkSec?: number;
+}
+export interface PhoneEvents {
+    ready: {
+        loggedIn: boolean;
+    };
+    "auth-required": Record<string, never>;
+    status: {
+        registered: boolean;
+        extension?: string | null;
+    };
+    incoming: PhoneCallEvent;
+    answered: PhoneCallEvent;
+    ended: PhoneCallEvent;
+    error: {
+        code: string;
+        message?: string;
+    };
+}
+type Handler<K extends keyof PhoneEvents> = (payload: PhoneEvents[K]) => void;
+export declare class NextXPhone {
+    private readonly options;
+    private readonly iframe;
+    private readonly origin;
+    private readonly handlers;
+    private readonly queue;
+    private ready;
+    private readonly onMessage;
+    private readonly onClick;
+    private constructor();
+    /** Tạo và gắn NextX Phone vào trang. */
+    static init(options: NextXPhoneOptions): NextXPhone;
+    /** Nghe sự kiện. Trả hàm huỷ đăng ký. */
+    on<K extends keyof PhoneEvents>(event: K, handler: Handler<K>): () => void;
+    /** Gọi ra từ máy lẻ của tổng đài viên đang đăng nhập. */
+    call(number: string, opts?: {
+        contactRef?: string;
+    }): void;
+    /** Gác cuộc gọi đang diễn ra. */
+    hangup(): void;
+    /** Đăng xuất NextX trong khung softphone. */
+    logout(): void;
+    /** Gỡ softphone khỏi trang. */
+    destroy(): void;
+    private send;
+}
+export default NextXPhone;

package/dist/esm/phone.js

@@ -0,0 +1,123 @@
+/// <reference lib="dom" />
+/**
+ * NextX Phone — nhúng softphone NextX vào phần mềm của bạn (chạy trên trình duyệt).
+ *
+ *   import { NextXPhone } from "@nextxai/sdk/phone";
+ *   const phone = NextXPhone.init({ clientId: "app_…" });
+ *   phone.on("incoming", (c) => openCustomer(c.from));
+ *   phone.call("0901234567");
+ *
+ * Hoặc thẻ script: <script src="https://developers.nextx.vn/phone/v1/phone.js"></script> ⇒ `window.NextXPhone`.
+ *
+ * Softphone chạy trong iframe do NextX phục vụ; tổng đài viên đăng nhập NextX trong cửa sổ bật lên. Trang của bạn chỉ
+ * nhận sự kiện cuộc gọi — không bao giờ nhận token hay thông tin máy lẻ. Tên miền trang của bạn phải được khai trong
+ * developers.nextx.vn › Ứng dụng của tôi › Cài đặt › Softphone nhúng.
+ */
+export const PHONE_PROTOCOL = "nxphone/1";
+const DEFAULT_APP_URL = "https://app.nextx.vn";
+const INITIAL = { width: 96, height: 96 };
+export class NextXPhone {
+    constructor(options) {
+        this.options = options;
+        this.handlers = new Map();
+        this.queue = [];
+        this.ready = false;
+        if (!options?.clientId)
+            throw new Error("NextXPhone: thiếu clientId");
+        const appUrl = (options.appUrl ?? DEFAULT_APP_URL).replace(/\/+$/, "");
+        this.origin = new URL(appUrl).origin;
+        const q = new URLSearchParams({ client_id: options.clientId });
+        if (options.workspaceId)
+            q.set("workspace_id", options.workspaceId);
+        const f = document.createElement("iframe");
+        f.src = `${appUrl}/${options.lang ?? "vi"}/phone/embed?${q}`;
+        f.title = "NextX Phone";
+        f.allow = "microphone; autoplay";
+        f.setAttribute("allowtransparency", "true");
+        const side = options.position === "bottom-left" ? "left" : "right";
+        const off = `${options.offset ?? 0}px`;
+        Object.assign(f.style, {
+            position: "fixed",
+            bottom: off,
+            [side]: off,
+            width: `${INITIAL.width}px`,
+            height: `${INITIAL.height}px`,
+            border: "0",
+            background: "transparent",
+            colorScheme: "normal",
+            zIndex: "2147483000",
+        });
+        this.iframe = f;
+        this.onMessage = (e) => {
+            if (e.origin !== this.origin || e.source !== f.contentWindow)
+                return;
+            const msg = e.data;
+            if (!msg || msg.protocol !== PHONE_PROTOCOL || !msg.event)
+                return;
+            const { type, ...payload } = msg.event;
+            if (type === "resize") {
+                const w = Math.max(64, Math.min(Number(payload.width) || INITIAL.width, window.innerWidth));
+                const h = Math.max(64, Math.min(Number(payload.height) || INITIAL.height, window.innerHeight));
+                f.style.width = `${w}px`;
+                f.style.height = `${h}px`;
+                return;
+            }
+            if (type === "ready" && !this.ready) {
+                this.ready = true;
+                for (const c of this.queue.splice(0))
+                    this.send(c);
+            }
+            this.handlers.get(type)?.forEach((h) => h(payload));
+        };
+        this.onClick = (e) => {
+            const el = e.target?.closest?.("[data-nextx-call]");
+            const number = el?.getAttribute("data-nextx-call");
+            if (!number)
+                return;
+            e.preventDefault();
+            this.call(number, { contactRef: el?.getAttribute("data-nextx-contact-ref") ?? undefined });
+        };
+        window.addEventListener("message", this.onMessage);
+        if (options.clickToDial !== false)
+            document.addEventListener("click", this.onClick);
+        (document.body ?? document.documentElement).appendChild(f);
+    }
+    /** Tạo và gắn NextX Phone vào trang. */
+    static init(options) {
+        return new NextXPhone(options);
+    }
+    /** Nghe sự kiện. Trả hàm huỷ đăng ký. */
+    on(event, handler) {
+        const set = this.handlers.get(event) ?? new Set();
+        set.add(handler);
+        this.handlers.set(event, set);
+        return () => set.delete(handler);
+    }
+    /** Gọi ra từ máy lẻ của tổng đài viên đang đăng nhập. */
+    call(number, opts = {}) {
+        this.send({ type: "call", number: String(number), contactRef: opts.contactRef });
+    }
+    /** Gác cuộc gọi đang diễn ra. */
+    hangup() {
+        this.send({ type: "hangup" });
+    }
+    /** Đăng xuất NextX trong khung softphone. */
+    logout() {
+        this.send({ type: "logout" });
+    }
+    /** Gỡ softphone khỏi trang. */
+    destroy() {
+        window.removeEventListener("message", this.onMessage);
+        document.removeEventListener("click", this.onClick);
+        this.iframe.remove();
+        this.handlers.clear();
+    }
+    send(command) {
+        if (!this.ready || !this.iframe.contentWindow) {
+            this.queue.push(command);
+            return;
+        }
+        this.iframe.contentWindow.postMessage({ protocol: PHONE_PROTOCOL, command }, this.origin);
+    }
+}
+export default NextXPhone;

package/dist/esm/version.d.ts

@@ -1 +1 @@
-export declare const VERSION = "0.1.2";
+export declare const VERSION = "0.2.0";

package/dist/esm/version.js

@@ -1 +1 @@
-export const VERSION = "0.1.2";
+export const VERSION = "0.2.0";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nextxai/sdk",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "description": "Official Node.js and TypeScript client for the NextX API",
   "keywords": [
     "nextx",
@@ -35,6 +35,16 @@
         "default": "./dist/cjs/index.js"
       }
     },
+    "./phone": {
+      "import": {
+        "types": "./dist/esm/phone.d.ts",
+        "default": "./dist/esm/phone.js"
+      },
+      "require": {
+        "types": "./dist/cjs/phone.d.ts",
+        "default": "./dist/cjs/phone.js"
+      }
+    },
     "./package.json": "./package.json"
   },
   "files": [