@nextxai/sdk 0.2.1-beta.29 → 0.3.0

package/CHANGELOG.md

@@ -2,10 +2,12 @@
 
 Theo [Semantic Versioning](https://semver.org/lang/vi/). Chính sách phiên bản: [VERSIONING.md](VERSIONING.md).
 
-## 0.2.1 (2026-10-31)
+## 0.3.0 (2026-10-31)
 
 ### Thêm mới
 
+- Kiểm chữ ký webhook theo chuẩn Standard Webhooks: Node `@nextxai/sdk/webhooks` (`verifyWebhook`, `signWebhook`, kiểu sự kiện `call.*` · `agent.status_changed`), Python `nextx_sdk.webhooks` (`verify_webhook`, `sign_webhook`).
+- `NextXPhone.answer()`: nhấc cuộc đang đổ chuông từ phần mềm của bạn (ví dụ nút "Nghe" trên màn khách hàng khi nhận sự kiện `incoming`). Chuyển máy dùng REST `POST /api/v1/call/partner/calls/{id}/transfer`.
 - `GET /api/v1/call/calls/{id}/transcript`: Transcript STT
 - `GET /api/v1/call/calls/{id}/summary`: AI summary + sentiment
 - `POST /api/v1/call/partner/calls`: Bấm gọi thay tổng đài viên (click-to-call)

package/README.md

@@ -31,6 +31,32 @@ for (const c of data.items ?? []) console.log(c.fullName);
 const nx = createNextXClient({ accessToken: () => tokenStore.current() });
 ```
 
+## Nhận webhook
+
+Kiểm chữ ký theo chuẩn [Standard Webhooks](https://www.standardwebhooks.com) (chỉ chạy trên máy chủ). Truyền thân gốc, không phải JSON đã parse:
+
+```ts
+import { verifyWebhook } from "@nextxai/sdk/webhooks";
+
+app.post("/nextx/webhook", express.raw({ type: "application/json" }), (req, res) => {
+  const event = verifyWebhook(req.body, req.headers, process.env.NEXTX_WEBHOOK_SECRET!);
+  if (event.type === "call.completed") console.log(event.data.object.talkSec, event.data.object.contactRef);
+  res.sendStatus(204);
+});
+```
+
+Sai chữ ký hoặc lệch giờ quá 5 phút thì ném `WebhookVerificationError`. Dùng `event.id` để bỏ qua lần giao trùng.
+
+## Softphone nhúng (trình duyệt)
+
+```ts
+import { NextXPhone } from "@nextxai/sdk/phone";
+
+const phone = NextXPhone.init({ clientId: "nxa_…" });
+phone.on("incoming", (c) => openCustomer(c.from));
+phone.call("0901234567");   // phone.answer() · phone.hangup()
+```
+
 ## Ghi chú
 
 - Mặc định client gọi môi trường production. Khi thử nghiệm, dùng `SANDBOX_URL` với khoá sandbox.

package/dist/cjs/phone.d.ts

@@ -73,6 +73,8 @@ export declare class NextXPhone {
     call(number: string, opts?: {
         contactRef?: string;
     }): void;
+    /** Nhấc cuộc đang đổ chuông (sự kiện `incoming`) — y như tổng đài viên bấm "Nghe" trong khung. */
+    answer(): void;
     /** Gác cuộc gọi đang diễn ra. */
     hangup(): void;
     /** Đăng xuất NextX trong khung softphone. */

package/dist/cjs/phone.js

@@ -100,6 +100,10 @@ class NextXPhone {
     call(number, opts = {}) {
         this.send({ type: "call", number: String(number), contactRef: opts.contactRef });
     }
+    /** Nhấc cuộc đang đổ chuông (sự kiện `incoming`) — y như tổng đài viên bấm "Nghe" trong khung. */
+    answer() {
+        this.send({ type: "answer" });
+    }
     /** Gác cuộc gọi đang diễn ra. */
     hangup() {
         this.send({ type: "hangup" });

package/dist/cjs/version.d.ts

@@ -1 +1 @@
-export declare const VERSION = "0.2.1-beta.29";
+export declare const VERSION = "0.3.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.2.1-beta.29";
+exports.VERSION = "0.3.0";

package/dist/cjs/webhooks.d.ts

@@ -0,0 +1,92 @@
+/** Hai lần giao cách nhau quá ngưỡng này (giây) bị coi là phát lại. */
+export declare const DEFAULT_TOLERANCE_SEC = 300;
+/** Tổng đài viên trong dữ liệu công khai. */
+export interface WebhookAgent {
+    id: string;
+    userId: string;
+    name: string | null;
+    email: string | null;
+    extension: string;
+}
+/** `data.object` của các sự kiện `call.*` — cùng hình dạng với `GET /api/v1/call/partner/calls/{id}`. */
+export interface WebhookCall {
+    callId: string;
+    /** 1 = ringing · 2 = answered · 3 = completed/missed · 4 = recording_ready · 5 = summary_ready — sắp xếp khi tới lệch thứ tự. */
+    sequence: number;
+    /** queued · initiated · ringing · in-progress · completed · busy · no-answer · failed · canceled · abandoned */
+    status: string;
+    direction: "inbound" | "outbound";
+    /** E.164 khi chuẩn hoá được. */
+    from: string;
+    to: string;
+    agent: WebhookAgent | null;
+    queueId: string | null;
+    queueName: string | null;
+    startedAt: string | null;
+    answeredAt: string | null;
+    endedAt: string | null;
+    durationSec: number | null;
+    talkSec: number | null;
+    waitSec: number | null;
+    /** Mã Q.850 (16 = gác bình thường, 17 = bận, 19 = không trả lời, 41 = lỗi tạm thời…). */
+    hangupCause: number | null;
+    hangupCauseName: string | null;
+    /** `contactRef` bạn gửi lúc gọi ra — trả lại nguyên văn. */
+    contactRef: string | null;
+    /** `metadata` bạn gửi lúc gọi ra — trả lại nguyên văn. */
+    metadata: Record<string, string> | null;
+    crmContactId: string | null;
+    hasRecording: boolean;
+    hasSummary: boolean;
+    /** Tóm tắt AI — có từ sự kiện `call.summary_ready` (null trước đó). */
+    summary: string | null;
+}
+/** `data.object` của `agent.status_changed`. */
+export interface WebhookAgentStatus {
+    agent: WebhookAgent;
+    from: string;
+    to: string;
+    reason: string | null;
+    changedAt: string;
+}
+export interface WebhookObjectMap {
+    "call.ringing": WebhookCall;
+    "call.answered": WebhookCall;
+    "call.completed": WebhookCall;
+    "call.missed": WebhookCall;
+    "call.recording_ready": WebhookCall;
+    "call.summary_ready": WebhookCall;
+    "agent.status_changed": WebhookAgentStatus;
+}
+interface Envelope<K extends string, T> {
+    id: string;
+    type: K;
+    api_version: string;
+    created_at: string;
+    workspace_id: string;
+    livemode: boolean;
+    data: {
+        object: T;
+    };
+    metadata?: Record<string, unknown>;
+}
+/** Sự kiện đã kiểm chữ ký. Thu hẹp kiểu bằng `event.type`. Loại sự kiện khác (CRM, Bán hàng…) có `data.object` là `unknown`. */
+export type WebhookEvent = {
+    [K in keyof WebhookObjectMap]: Envelope<K, WebhookObjectMap[K]>;
+}[keyof WebhookObjectMap] | Envelope<string & {}, unknown>;
+export declare class WebhookVerificationError extends Error {
+    constructor(message: string);
+}
+type HeaderBag = Headers | Record<string, string | string[] | undefined>;
+/** Ký một thân webhook — dùng để viết test cho phần nhận webhook của bạn. */
+export declare function signWebhook(secret: string, id: string, timestamp: number, body: string | Buffer): string;
+/**
+ * Kiểm `webhook-id` / `webhook-timestamp` / `webhook-signature` rồi trả sự kiện đã parse.
+ * Ném {@link WebhookVerificationError} khi thiếu header, chữ ký sai, hoặc lệch giờ quá `toleranceSec`.
+ * Dùng `webhook-id` (cũng là `event.id`) để bỏ qua lần giao trùng — NextX giao lại khi bạn không trả 2xx.
+ */
+export declare function verifyWebhook(body: string | Buffer | Uint8Array, headers: HeaderBag, secret: string, options?: {
+    toleranceSec?: number;
+    now?: Date;
+}): WebhookEvent;
+export {};

package/dist/cjs/webhooks.js

@@ -0,0 +1,81 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WebhookVerificationError = exports.DEFAULT_TOLERANCE_SEC = void 0;
+exports.signWebhook = signWebhook;
+exports.verifyWebhook = verifyWebhook;
+/// <reference types="node" />
+/**
+ * Kiểm chữ ký webhook NextX theo chuẩn mở Standard Webhooks (https://www.standardwebhooks.com) — chỉ chạy trên máy chủ.
+ *
+ *   import { verifyWebhook } from "@nextxai/sdk/webhooks";
+ *
+ *   app.post("/nextx/webhook", express.raw({ type: "application/json" }), (req, res) => {
+ *     const event = verifyWebhook(req.body, req.headers, process.env.NEXTX_WEBHOOK_SECRET!);
+ *     if (event.type === "call.completed") saveCall(event.data.object);
+ *     res.sendStatus(204);
+ *   });
+ *
+ * Phải truyền THÂN GỐC (Buffer/chuỗi đúng từng byte) — JSON đã parse rồi stringify lại sẽ lệch chữ ký.
+ * Bí mật dạng `whsec_…` lấy ở developers.nextx.vn › Webhooks (xoay khoá ⇒ header có nhiều chữ ký, khớp một là đủ).
+ */
+const node_crypto_1 = require("node:crypto");
+/** Hai lần giao cách nhau quá ngưỡng này (giây) bị coi là phát lại. */
+exports.DEFAULT_TOLERANCE_SEC = 300;
+class WebhookVerificationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "WebhookVerificationError";
+    }
+}
+exports.WebhookVerificationError = WebhookVerificationError;
+function header(headers, name) {
+    if (typeof headers.get === "function")
+        return headers.get(name) ?? undefined;
+    const bag = headers;
+    const hit = Object.keys(bag).find((k) => k.toLowerCase() === name);
+    const v = hit === undefined ? undefined : bag[hit];
+    return Array.isArray(v) ? v[0] : v;
+}
+function keyOf(secret) {
+    if (!secret?.startsWith("whsec_"))
+        throw new WebhookVerificationError("secret phải có dạng whsec_…");
+    const key = Buffer.from(secret.slice(6), "base64");
+    if (key.length < 24 || key.length > 64)
+        throw new WebhookVerificationError("secret không hợp lệ");
+    return key;
+}
+/** Ký một thân webhook — dùng để viết test cho phần nhận webhook của bạn. */
+function signWebhook(secret, id, timestamp, body) {
+    const mac = (0, node_crypto_1.createHmac)("sha256", keyOf(secret));
+    mac.update(`${id}.${timestamp}.`);
+    mac.update(body);
+    return `v1,${mac.digest("base64")}`;
+}
+/**
+ * Kiểm `webhook-id` / `webhook-timestamp` / `webhook-signature` rồi trả sự kiện đã parse.
+ * Ném {@link WebhookVerificationError} khi thiếu header, chữ ký sai, hoặc lệch giờ quá `toleranceSec`.
+ * Dùng `webhook-id` (cũng là `event.id`) để bỏ qua lần giao trùng — NextX giao lại khi bạn không trả 2xx.
+ */
+function verifyWebhook(body, headers, secret, options = {}) {
+    const id = header(headers, "webhook-id");
+    const ts = header(headers, "webhook-timestamp");
+    const sig = header(headers, "webhook-signature");
+    if (!id || !ts || !sig)
+        throw new WebhookVerificationError("thiếu header webhook-id / webhook-timestamp / webhook-signature");
+    const timestamp = Number(ts);
+    const now = Math.floor((options.now ?? new Date()).getTime() / 1000);
+    if (!Number.isInteger(timestamp) || Math.abs(now - timestamp) > (options.toleranceSec ?? exports.DEFAULT_TOLERANCE_SEC))
+        throw new WebhookVerificationError("webhook-timestamp lệch quá ngưỡng");
+    const raw = typeof body === "string" ? Buffer.from(body, "utf8") : Buffer.from(body);
+    const expected = Buffer.from(signWebhook(secret, id, timestamp, raw));
+    const ok = sig
+        .split(" ")
+        .filter(Boolean)
+        .some((s) => {
+        const candidate = Buffer.from(s);
+        return candidate.length === expected.length && (0, node_crypto_1.timingSafeEqual)(candidate, expected);
+    });
+    if (!ok)
+        throw new WebhookVerificationError("chữ ký không khớp");
+    return JSON.parse(raw.toString("utf8"));
+}

package/dist/esm/phone.d.ts

@@ -73,6 +73,8 @@ export declare class NextXPhone {
     call(number: string, opts?: {
         contactRef?: string;
     }): void;
+    /** Nhấc cuộc đang đổ chuông (sự kiện `incoming`) — y như tổng đài viên bấm "Nghe" trong khung. */
+    answer(): void;
     /** Gác cuộc gọi đang diễn ra. */
     hangup(): void;
     /** Đăng xuất NextX trong khung softphone. */

package/dist/esm/phone.js

@@ -97,6 +97,10 @@ export class NextXPhone {
     call(number, opts = {}) {
         this.send({ type: "call", number: String(number), contactRef: opts.contactRef });
     }
+    /** Nhấc cuộc đang đổ chuông (sự kiện `incoming`) — y như tổng đài viên bấm "Nghe" trong khung. */
+    answer() {
+        this.send({ type: "answer" });
+    }
     /** Gác cuộc gọi đang diễn ra. */
     hangup() {
         this.send({ type: "hangup" });

package/dist/esm/version.d.ts

@@ -1 +1 @@
-export declare const VERSION = "0.2.1-beta.29";
+export declare const VERSION = "0.3.0";

package/dist/esm/version.js

@@ -1 +1 @@
-export const VERSION = "0.2.1-beta.29";
+export const VERSION = "0.3.0";

package/dist/esm/webhooks.d.ts

@@ -0,0 +1,92 @@
+/** Hai lần giao cách nhau quá ngưỡng này (giây) bị coi là phát lại. */
+export declare const DEFAULT_TOLERANCE_SEC = 300;
+/** Tổng đài viên trong dữ liệu công khai. */
+export interface WebhookAgent {
+    id: string;
+    userId: string;
+    name: string | null;
+    email: string | null;
+    extension: string;
+}
+/** `data.object` của các sự kiện `call.*` — cùng hình dạng với `GET /api/v1/call/partner/calls/{id}`. */
+export interface WebhookCall {
+    callId: string;
+    /** 1 = ringing · 2 = answered · 3 = completed/missed · 4 = recording_ready · 5 = summary_ready — sắp xếp khi tới lệch thứ tự. */
+    sequence: number;
+    /** queued · initiated · ringing · in-progress · completed · busy · no-answer · failed · canceled · abandoned */
+    status: string;
+    direction: "inbound" | "outbound";
+    /** E.164 khi chuẩn hoá được. */
+    from: string;
+    to: string;
+    agent: WebhookAgent | null;
+    queueId: string | null;
+    queueName: string | null;
+    startedAt: string | null;
+    answeredAt: string | null;
+    endedAt: string | null;
+    durationSec: number | null;
+    talkSec: number | null;
+    waitSec: number | null;
+    /** Mã Q.850 (16 = gác bình thường, 17 = bận, 19 = không trả lời, 41 = lỗi tạm thời…). */
+    hangupCause: number | null;
+    hangupCauseName: string | null;
+    /** `contactRef` bạn gửi lúc gọi ra — trả lại nguyên văn. */
+    contactRef: string | null;
+    /** `metadata` bạn gửi lúc gọi ra — trả lại nguyên văn. */
+    metadata: Record<string, string> | null;
+    crmContactId: string | null;
+    hasRecording: boolean;
+    hasSummary: boolean;
+    /** Tóm tắt AI — có từ sự kiện `call.summary_ready` (null trước đó). */
+    summary: string | null;
+}
+/** `data.object` của `agent.status_changed`. */
+export interface WebhookAgentStatus {
+    agent: WebhookAgent;
+    from: string;
+    to: string;
+    reason: string | null;
+    changedAt: string;
+}
+export interface WebhookObjectMap {
+    "call.ringing": WebhookCall;
+    "call.answered": WebhookCall;
+    "call.completed": WebhookCall;
+    "call.missed": WebhookCall;
+    "call.recording_ready": WebhookCall;
+    "call.summary_ready": WebhookCall;
+    "agent.status_changed": WebhookAgentStatus;
+}
+interface Envelope<K extends string, T> {
+    id: string;
+    type: K;
+    api_version: string;
+    created_at: string;
+    workspace_id: string;
+    livemode: boolean;
+    data: {
+        object: T;
+    };
+    metadata?: Record<string, unknown>;
+}
+/** Sự kiện đã kiểm chữ ký. Thu hẹp kiểu bằng `event.type`. Loại sự kiện khác (CRM, Bán hàng…) có `data.object` là `unknown`. */
+export type WebhookEvent = {
+    [K in keyof WebhookObjectMap]: Envelope<K, WebhookObjectMap[K]>;
+}[keyof WebhookObjectMap] | Envelope<string & {}, unknown>;
+export declare class WebhookVerificationError extends Error {
+    constructor(message: string);
+}
+type HeaderBag = Headers | Record<string, string | string[] | undefined>;
+/** Ký một thân webhook — dùng để viết test cho phần nhận webhook của bạn. */
+export declare function signWebhook(secret: string, id: string, timestamp: number, body: string | Buffer): string;
+/**
+ * Kiểm `webhook-id` / `webhook-timestamp` / `webhook-signature` rồi trả sự kiện đã parse.
+ * Ném {@link WebhookVerificationError} khi thiếu header, chữ ký sai, hoặc lệch giờ quá `toleranceSec`.
+ * Dùng `webhook-id` (cũng là `event.id`) để bỏ qua lần giao trùng — NextX giao lại khi bạn không trả 2xx.
+ */
+export declare function verifyWebhook(body: string | Buffer | Uint8Array, headers: HeaderBag, secret: string, options?: {
+    toleranceSec?: number;
+    now?: Date;
+}): WebhookEvent;
+export {};

package/dist/esm/webhooks.js

@@ -0,0 +1,75 @@
+/// <reference types="node" />
+/**
+ * Kiểm chữ ký webhook NextX theo chuẩn mở Standard Webhooks (https://www.standardwebhooks.com) — chỉ chạy trên máy chủ.
+ *
+ *   import { verifyWebhook } from "@nextxai/sdk/webhooks";
+ *
+ *   app.post("/nextx/webhook", express.raw({ type: "application/json" }), (req, res) => {
+ *     const event = verifyWebhook(req.body, req.headers, process.env.NEXTX_WEBHOOK_SECRET!);
+ *     if (event.type === "call.completed") saveCall(event.data.object);
+ *     res.sendStatus(204);
+ *   });
+ *
+ * Phải truyền THÂN GỐC (Buffer/chuỗi đúng từng byte) — JSON đã parse rồi stringify lại sẽ lệch chữ ký.
+ * Bí mật dạng `whsec_…` lấy ở developers.nextx.vn › Webhooks (xoay khoá ⇒ header có nhiều chữ ký, khớp một là đủ).
+ */
+import { createHmac, timingSafeEqual } from "node:crypto";
+/** Hai lần giao cách nhau quá ngưỡng này (giây) bị coi là phát lại. */
+export const DEFAULT_TOLERANCE_SEC = 300;
+export class WebhookVerificationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "WebhookVerificationError";
+    }
+}
+function header(headers, name) {
+    if (typeof headers.get === "function")
+        return headers.get(name) ?? undefined;
+    const bag = headers;
+    const hit = Object.keys(bag).find((k) => k.toLowerCase() === name);
+    const v = hit === undefined ? undefined : bag[hit];
+    return Array.isArray(v) ? v[0] : v;
+}
+function keyOf(secret) {
+    if (!secret?.startsWith("whsec_"))
+        throw new WebhookVerificationError("secret phải có dạng whsec_…");
+    const key = Buffer.from(secret.slice(6), "base64");
+    if (key.length < 24 || key.length > 64)
+        throw new WebhookVerificationError("secret không hợp lệ");
+    return key;
+}
+/** Ký một thân webhook — dùng để viết test cho phần nhận webhook của bạn. */
+export function signWebhook(secret, id, timestamp, body) {
+    const mac = createHmac("sha256", keyOf(secret));
+    mac.update(`${id}.${timestamp}.`);
+    mac.update(body);
+    return `v1,${mac.digest("base64")}`;
+}
+/**
+ * Kiểm `webhook-id` / `webhook-timestamp` / `webhook-signature` rồi trả sự kiện đã parse.
+ * Ném {@link WebhookVerificationError} khi thiếu header, chữ ký sai, hoặc lệch giờ quá `toleranceSec`.
+ * Dùng `webhook-id` (cũng là `event.id`) để bỏ qua lần giao trùng — NextX giao lại khi bạn không trả 2xx.
+ */
+export function verifyWebhook(body, headers, secret, options = {}) {
+    const id = header(headers, "webhook-id");
+    const ts = header(headers, "webhook-timestamp");
+    const sig = header(headers, "webhook-signature");
+    if (!id || !ts || !sig)
+        throw new WebhookVerificationError("thiếu header webhook-id / webhook-timestamp / webhook-signature");
+    const timestamp = Number(ts);
+    const now = Math.floor((options.now ?? new Date()).getTime() / 1000);
+    if (!Number.isInteger(timestamp) || Math.abs(now - timestamp) > (options.toleranceSec ?? DEFAULT_TOLERANCE_SEC))
+        throw new WebhookVerificationError("webhook-timestamp lệch quá ngưỡng");
+    const raw = typeof body === "string" ? Buffer.from(body, "utf8") : Buffer.from(body);
+    const expected = Buffer.from(signWebhook(secret, id, timestamp, raw));
+    const ok = sig
+        .split(" ")
+        .filter(Boolean)
+        .some((s) => {
+        const candidate = Buffer.from(s);
+        return candidate.length === expected.length && timingSafeEqual(candidate, expected);
+    });
+    if (!ok)
+        throw new WebhookVerificationError("chữ ký không khớp");
+    return JSON.parse(raw.toString("utf8"));
+}

package/package.json

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