@nextxai/sdk 0.1.0-beta.5 → 0.1.1-beta.11

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (11) hide show
  1. package/CHANGELOG.md +7 -3
  2. package/README.md +27 -12
  3. package/dist/cjs/index.d.ts +7 -8
  4. package/dist/cjs/index.js +2 -4
  5. package/dist/cjs/version.d.ts +1 -1
  6. package/dist/cjs/version.js +1 -1
  7. package/dist/esm/index.d.ts +7 -8
  8. package/dist/esm/index.js +2 -4
  9. package/dist/esm/version.d.ts +1 -1
  10. package/dist/esm/version.js +1 -1
  11. package/package.json +2 -2
package/CHANGELOG.md CHANGED
@@ -1,7 +1,11 @@
1
1
  # Nhật ký thay đổi
2
2
 
3
- Theo [Semantic Versioning](https://semver.org/lang/vi/). Chính sách phiên bản và bỏ dần: [VERSIONING.md](VERSIONING.md).
3
+ Theo [Semantic Versioning](https://semver.org/lang/vi/). Chính sách phiên bản: [VERSIONING.md](VERSIONING.md).
4
4
 
5
- ## 0.1.0 — 2026-10-28
5
+ ## 0.1.1 (2026-10-28)
6
6
 
7
- Bản đầu tiên (beta). Phủ 10 phân hệ NextX: CRM, Bán hàng, Chat đa kênh, Tổng đài, DMS, Nhân sự, Marketing, Office, Thanh toán, Hoá đơn điện tử.
7
+ - Viết lại README, VERSIONING, CONTRIBUTING và SECURITY cho dễ đọc. Mã không đổi so với 0.1.0.
8
+
9
+ ## 0.1.0 (2026-10-28)
10
+
11
+ - Bản đầu tiên. Hỗ trợ 10 nhóm API: CRM, Bán hàng, Chat đa kênh, Tổng đài, DMS, Nhân sự, Marketing, Office, Thanh toán, Hoá đơn điện tử.
package/README.md CHANGED
@@ -1,18 +1,23 @@
1
1
  # @nextxai/sdk
2
2
 
3
- > Mã trong kho này được sinh tự động từ [OpenAPI công khai](https://developers.nextx.vn/openapi.json). Đừng sửa tay — xem [CONTRIBUTING.md](CONTRIBUTING.md).
3
+ Thư viện chính thức để gọi NextX API từ Node.js và TypeScript.
4
4
 
5
- Gọi NextX API từ Node.js và TypeScript, có kiểu đầy đủ. Kiểu sinh từ [`/openapi.json`](https://developers.nextx.vn/openapi.json)
6
- và chỉ gồm các tuyến đối tác gọi được, nên trình soạn thảo gợi đúng đường dẫn, tham số và hình dạng phản hồi.
5
+ Mã trong kho này được sinh tự động từ [OpenAPI của NextX](https://developers.nextx.vn/openapi.json). Vui lòng không sửa trực tiếp, xem [CONTRIBUTING.md](CONTRIBUTING.md).
6
+
7
+ ## Cài đặt
7
8
 
8
9
  ```sh
9
10
  npm i @nextxai/sdk
10
11
  ```
11
12
 
13
+ Yêu cầu Node.js 18 trở lên. Gói hỗ trợ cả `import` và `require`, chạy được trên Deno, Bun và trình duyệt.
14
+
15
+ ## Bắt đầu
16
+
12
17
  ```ts
13
18
  import { createNextXClient, SANDBOX_URL } from "@nextxai/sdk";
14
19
 
15
- // Khoá API của workspace (tạo trong phần mềm NextX) — gửi ở header X-Api-Key
20
+ // Khoá API của workspace, tạo trong phần mềm NextX, gửi ở header X-Api-Key
16
21
  const nx = createNextXClient({ apiKey: process.env.NEXTX_API_KEY!, baseUrl: SANDBOX_URL });
17
22
 
18
23
  const { data, error } = await nx.GET("/api/v1/crm/contacts", { params: { query: { pageSize: 20 } } });
@@ -20,14 +25,24 @@ if (error) throw new Error(`${error.status} ${error.title}`);
20
25
  for (const c of data.items ?? []) console.log(c.fullName);
21
26
  ```
22
27
 
23
- Ứng dụng đối tác dùng OAuth 2.0 thì truyền access token (có thể là hàm để lấy token mới mỗi lần gọi):
24
- `createNextXClient({ accessToken: () => tokenStore.current() })`.
28
+ Ứng dụng đối tác dùng OAuth 2.0 thì truyền access token. Có thể truyền một hàm để lấy token mới cho mỗi lần gọi:
25
29
 
26
- - Node.js ≥ 18, Deno, Bun và trình duyệt (dùng `fetch` chuẩn). Hỗ trợ cả ESM (`import`) và CommonJS (`require`).
27
- - Mặc định gọi prod (`PROD_URL`). Thử nghiệm thì dùng `SANDBOX_URL` với khoá sandbox.
28
- - Lỗi theo RFC 7807, trả trong `error` (`status`, `title`, `detail`), không ném ngoại lệ.
29
- - Gọi ghi (POST/PUT/PATCH) nên gửi kèm `Idempotency-Key` để thử lại an toàn:
30
+ ```ts
31
+ const nx = createNextXClient({ accessToken: () => tokenStore.current() });
32
+ ```
33
+
34
+ ## Ghi chú
35
+
36
+ - Mặc định client gọi môi trường production. Khi thử nghiệm, dùng `SANDBOX_URL` với khoá sandbox.
37
+ - Lỗi trả về theo chuẩn RFC 7807 trong `error` (`status`, `title`, `detail`), không ném ngoại lệ.
38
+ - Với các lệnh ghi (POST, PUT, PATCH), nên gửi `Idempotency-Key` để thử lại an toàn:
30
39
  `nx.POST(path, { body, headers: { "Idempotency-Key": crypto.randomUUID() } })`.
31
- - Không đưa khoá API ra trình duyệt của người dùng cuối. Phía máy khách, dùng access token OAuth của ứng dụng.
40
+ - Không đưa khoá API vào mã chạy trên trình duyệt của người dùng cuối. Ứng dụng phía máy khách nên dùng access token OAuth.
41
+
42
+ ## Tài liệu
43
+
44
+ - Hướng dẫn: https://developers.nextx.vn/docs/sdk
45
+ - Phiên bản và chính sách ngừng hỗ trợ: [VERSIONING.md](VERSIONING.md)
46
+ - Nhật ký thay đổi: [CHANGELOG.md](CHANGELOG.md)
32
47
 
33
- Tài liệu: https://developers.nextx.vn/docs/sdk · Phiên bản và bỏ dần: [VERSIONING.md](https://github.com/nextx-organization/nextx-sdk-node/blob/main/VERSIONING.md) · Giấy phép MIT
48
+ Giấy phép MIT.
package/dist/cjs/index.d.ts CHANGED
@@ -1,6 +1,5 @@
1
1
  /**
2
- * NextX SDK cho Node.js/TypeScript. Kiểu `paths` sinh từ https://developers.nextx.vn/openapi.json — chỉ gồm các tuyến
3
- * đối tác gọi được — nên trình soạn thảo gợi đúng đường, tham số và hình dạng phản hồi.
2
+ * NextX SDK for Node.js and TypeScript. Types are generated from https://developers.nextx.vn/openapi.json.
4
3
  *
5
4
  * const nx = createNextXClient({ apiKey: process.env.NEXTX_API_KEY! });
6
5
  * const { data, error } = await nx.GET("/api/v1/crm/contacts", { params: { query: { pageSize: 20 } } });
@@ -13,25 +12,25 @@ export { VERSION };
13
12
  export declare const PROD_URL = "https://api.nextx.vn";
14
13
  export declare const SANDBOX_URL = "https://api-dev.nextx.vn";
15
14
  export type NextXOptions = {
16
- /** Mặc định prod; thử nghiệm dùng `SANDBOX_URL` (khoá sandbox không gọi được prod và ngược lại). */
15
+ /** Defaults to production. Use `SANDBOX_URL` with a sandbox key for testing. */
17
16
  baseUrl?: string;
18
- /** Ngôn ngữ thông báo lỗi: `vi` (mặc định) hoặc `en`. */
17
+ /** Language of error messages: `vi` (default) or `en`. */
19
18
  language?: "vi" | "en";
20
- /** Thay fetch (proxy, đo đạc, kiểm thử). */
19
+ /** Custom fetch implementation. */
21
20
  fetch?: typeof globalThis.fetch;
22
21
  } & (
23
- /** Khoá API của workspace (`nxk_…`) — gửi ở header `X-Api-Key`. */
22
+ /** Workspace API key (`nxk_...`), sent as the `X-Api-Key` header. */
24
23
  {
25
24
  apiKey: string;
26
25
  accessToken?: never;
27
26
  }
28
- /** Access token OAuth 2.0 của ứng dụng đối tác — gửi `Authorization: Bearer`; có thể là hàm để lấy token mới mỗi lần gọi. */
27
+ /** OAuth 2.0 access token, sent as `Authorization: Bearer`. May be a function that returns a fresh token per request. */
29
28
  | {
30
29
  accessToken: string | (() => string | Promise<string>);
31
30
  apiKey?: never;
32
31
  });
33
32
  export type NextXClient = Client<paths>;
34
- /** Lỗi theo RFC 7807 mà API trả về khi `error` khác rỗng. */
33
+ /** RFC 7807 problem details returned in `error`. */
35
34
  export interface NextXProblem {
36
35
  type?: string;
37
36
  title?: string;
package/dist/cjs/index.js CHANGED
@@ -3,8 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
3
3
  exports.SANDBOX_URL = exports.PROD_URL = exports.VERSION = void 0;
4
4
  exports.createNextXClient = createNextXClient;
5
5
  /**
6
- * NextX SDK cho Node.js/TypeScript. Kiểu `paths` sinh từ https://developers.nextx.vn/openapi.json — chỉ gồm các tuyến
7
- * đối tác gọi được — nên trình soạn thảo gợi đúng đường, tham số và hình dạng phản hồi.
6
+ * NextX SDK for Node.js and TypeScript. Types are generated from https://developers.nextx.vn/openapi.json.
8
7
  *
9
8
  * const nx = createNextXClient({ apiKey: process.env.NEXTX_API_KEY! });
10
9
  * const { data, error } = await nx.GET("/api/v1/crm/contacts", { params: { query: { pageSize: 20 } } });
@@ -17,13 +16,12 @@ exports.SANDBOX_URL = "https://api-dev.nextx.vn";
17
16
  function createNextXClient(opts) {
18
17
  const { baseUrl = exports.PROD_URL, language = "vi", fetch } = opts;
19
18
  if (!opts.apiKey && !opts.accessToken)
20
- throw new Error("NextX SDK: cần apiKey hoặc accessToken");
19
+ throw new Error("NextX SDK: apiKey or accessToken is required");
21
20
  const client = (0, openapi_fetch_1.default)({
22
21
  baseUrl: baseUrl.replace(/\/+$/, ""),
23
22
  fetch,
24
23
  headers: {
25
24
  "Accept-Language": language,
26
- // Trình duyệt tự bỏ User-Agent nên chỉ có tác dụng phía máy chủ.
27
25
  "User-Agent": `nextx-sdk-node/${version_js_1.VERSION}`,
28
26
  ...(opts.apiKey ? { "X-Api-Key": opts.apiKey } : {}),
29
27
  },
package/dist/cjs/version.d.ts CHANGED
@@ -1 +1 @@
1
- export declare const VERSION = "0.1.0-beta.5";
1
+ export declare const VERSION = "0.1.1-beta.11";
package/dist/cjs/version.js CHANGED
@@ -1,4 +1,4 @@
1
1
  "use strict";
2
2
  Object.defineProperty(exports, "__esModule", { value: true });
3
3
  exports.VERSION = void 0;
4
- exports.VERSION = "0.1.0-beta.5";
4
+ exports.VERSION = "0.1.1-beta.11";
package/dist/esm/index.d.ts CHANGED
@@ -1,6 +1,5 @@
1
1
  /**
2
- * NextX SDK cho Node.js/TypeScript. Kiểu `paths` sinh từ https://developers.nextx.vn/openapi.json — chỉ gồm các tuyến
3
- * đối tác gọi được — nên trình soạn thảo gợi đúng đường, tham số và hình dạng phản hồi.
2
+ * NextX SDK for Node.js and TypeScript. Types are generated from https://developers.nextx.vn/openapi.json.
4
3
  *
5
4
  * const nx = createNextXClient({ apiKey: process.env.NEXTX_API_KEY! });
6
5
  * const { data, error } = await nx.GET("/api/v1/crm/contacts", { params: { query: { pageSize: 20 } } });
@@ -13,25 +12,25 @@ export { VERSION };
13
12
  export declare const PROD_URL = "https://api.nextx.vn";
14
13
  export declare const SANDBOX_URL = "https://api-dev.nextx.vn";
15
14
  export type NextXOptions = {
16
- /** Mặc định prod; thử nghiệm dùng `SANDBOX_URL` (khoá sandbox không gọi được prod và ngược lại). */
15
+ /** Defaults to production. Use `SANDBOX_URL` with a sandbox key for testing. */
17
16
  baseUrl?: string;
18
- /** Ngôn ngữ thông báo lỗi: `vi` (mặc định) hoặc `en`. */
17
+ /** Language of error messages: `vi` (default) or `en`. */
19
18
  language?: "vi" | "en";
20
- /** Thay fetch (proxy, đo đạc, kiểm thử). */
19
+ /** Custom fetch implementation. */
21
20
  fetch?: typeof globalThis.fetch;
22
21
  } & (
23
- /** Khoá API của workspace (`nxk_…`) — gửi ở header `X-Api-Key`. */
22
+ /** Workspace API key (`nxk_...`), sent as the `X-Api-Key` header. */
24
23
  {
25
24
  apiKey: string;
26
25
  accessToken?: never;
27
26
  }
28
- /** Access token OAuth 2.0 của ứng dụng đối tác — gửi `Authorization: Bearer`; có thể là hàm để lấy token mới mỗi lần gọi. */
27
+ /** OAuth 2.0 access token, sent as `Authorization: Bearer`. May be a function that returns a fresh token per request. */
29
28
  | {
30
29
  accessToken: string | (() => string | Promise<string>);
31
30
  apiKey?: never;
32
31
  });
33
32
  export type NextXClient = Client<paths>;
34
- /** Lỗi theo RFC 7807 mà API trả về khi `error` khác rỗng. */
33
+ /** RFC 7807 problem details returned in `error`. */
35
34
  export interface NextXProblem {
36
35
  type?: string;
37
36
  title?: string;
package/dist/esm/index.js CHANGED
@@ -1,6 +1,5 @@
1
1
  /**
2
- * NextX SDK cho Node.js/TypeScript. Kiểu `paths` sinh từ https://developers.nextx.vn/openapi.json — chỉ gồm các tuyến
3
- * đối tác gọi được — nên trình soạn thảo gợi đúng đường, tham số và hình dạng phản hồi.
2
+ * NextX SDK for Node.js and TypeScript. Types are generated from https://developers.nextx.vn/openapi.json.
4
3
  *
5
4
  * const nx = createNextXClient({ apiKey: process.env.NEXTX_API_KEY! });
6
5
  * const { data, error } = await nx.GET("/api/v1/crm/contacts", { params: { query: { pageSize: 20 } } });
@@ -13,13 +12,12 @@ export const SANDBOX_URL = "https://api-dev.nextx.vn";
13
12
  export function createNextXClient(opts) {
14
13
  const { baseUrl = PROD_URL, language = "vi", fetch } = opts;
15
14
  if (!opts.apiKey && !opts.accessToken)
16
- throw new Error("NextX SDK: cần apiKey hoặc accessToken");
15
+ throw new Error("NextX SDK: apiKey or accessToken is required");
17
16
  const client = createClient({
18
17
  baseUrl: baseUrl.replace(/\/+$/, ""),
19
18
  fetch,
20
19
  headers: {
21
20
  "Accept-Language": language,
22
- // Trình duyệt tự bỏ User-Agent nên chỉ có tác dụng phía máy chủ.
23
21
  "User-Agent": `nextx-sdk-node/${VERSION}`,
24
22
  ...(opts.apiKey ? { "X-Api-Key": opts.apiKey } : {}),
25
23
  },
package/dist/esm/version.d.ts CHANGED
@@ -1 +1 @@
1
- export declare const VERSION = "0.1.0-beta.5";
1
+ export declare const VERSION = "0.1.1-beta.11";
package/dist/esm/version.js CHANGED
@@ -1 +1 @@
1
- export const VERSION = "0.1.0-beta.5";
1
+ export const VERSION = "0.1.1-beta.11";
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@nextxai/sdk",
3
- "version": "0.1.0-beta.5",
4
- "description": "NextX API cho Node.js và TypeScript — kiểu đầy đủ sinh từ OpenAPI công khai",
3
+ "version": "0.1.1-beta.11",
4
+ "description": "Official Node.js and TypeScript client for the NextX API",
5
5
  "keywords": [
6
6
  "nextx",
7
7
  "crm",