@nextxai/sdk 0.0.0-stage → 0.1.0-beta.5

package/CHANGELOG.md

@@ -0,0 +1,7 @@
+# Nhật ký thay đổi
+
+Theo [Semantic Versioning](https://semver.org/lang/vi/). Chính sách phiên bản và bỏ dần: [VERSIONING.md](VERSIONING.md).
+
+## 0.1.0 — 2026-10-28
+
+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ử.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 NextX
+
+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 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

@@ -1,3 +1,33 @@
-# Temporary Holding Version
+# @nextxai/sdk
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+> 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).
+
+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)
+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.
+
+```sh
+npm i @nextxai/sdk
+```
+
+```ts
+import { createNextXClient, SANDBOX_URL } from "@nextxai/sdk";
+
+// Khoá API của workspace (tạo trong phần mềm NextX) — gửi ở header X-Api-Key
+const nx = createNextXClient({ apiKey: process.env.NEXTX_API_KEY!, baseUrl: SANDBOX_URL });
+
+const { data, error } = await nx.GET("/api/v1/crm/contacts", { params: { query: { pageSize: 20 } } });
+if (error) throw new Error(`${error.status} ${error.title}`);
+for (const c of data.items ?? []) console.log(c.fullName);
+```
+
+Ứ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):
+`createNextXClient({ accessToken: () => tokenStore.current() })`.
+
+- Node.js ≥ 18, Deno, Bun và trình duyệt (dùng `fetch` chuẩn). Hỗ trợ cả ESM (`import`) và CommonJS (`require`).
+- Mặc định gọi prod (`PROD_URL`). Thử nghiệm thì dùng `SANDBOX_URL` với khoá sandbox.
+- Lỗi theo RFC 7807, trả trong `error` (`status`, `title`, `detail`), không ném ngoại lệ.
+- Gọi ghi (POST/PUT/PATCH) nên gửi kèm `Idempotency-Key` để thử lại an toàn:
+  `nx.POST(path, { body, headers: { "Idempotency-Key": crypto.randomUUID() } })`.
+- 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.
+
+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

package/dist/cjs/index.d.ts

@@ -0,0 +1,43 @@
+/**
+ * NextX SDK cho Node.js/TypeScript. Kiểu `paths` sinh từ https://developers.nextx.vn/openapi.json — 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, tham số và hình dạng phản hồi.
+ *
+ *   const nx = createNextXClient({ apiKey: process.env.NEXTX_API_KEY! });
+ *   const { data, error } = await nx.GET("/api/v1/crm/contacts", { params: { query: { pageSize: 20 } } });
+ */
+import { type Client } from "openapi-fetch";
+import type { paths } from "./schema.js";
+import { VERSION } from "./version.js";
+export type { paths, components, operations } from "./schema.js";
+export { VERSION };
+export declare const PROD_URL = "https://api.nextx.vn";
+export declare const SANDBOX_URL = "https://api-dev.nextx.vn";
+export type NextXOptions = {
+    /** Mặc định prod; thử nghiệm dùng `SANDBOX_URL` (khoá sandbox không gọi được prod và ngược lại). */
+    baseUrl?: string;
+    /** Ngôn ngữ thông báo lỗi: `vi` (mặc định) hoặc `en`. */
+    language?: "vi" | "en";
+    /** Thay fetch (proxy, đo đạc, kiểm thử). */
+    fetch?: typeof globalThis.fetch;
+} & (
+/** Khoá API của workspace (`nxk_…`) — gửi ở header `X-Api-Key`. */
+{
+    apiKey: string;
+    accessToken?: never;
+}
+/** 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. */
+ | {
+    accessToken: string | (() => string | Promise<string>);
+    apiKey?: never;
+});
+export type NextXClient = Client<paths>;
+/** Lỗi theo RFC 7807 mà API trả về khi `error` khác rỗng. */
+export interface NextXProblem {
+    type?: string;
+    title?: string;
+    status?: number;
+    detail?: string;
+    traceId?: string;
+    errors?: Record<string, string[]> | string[] | null;
+}
+export declare function createNextXClient(opts: NextXOptions): NextXClient;

package/dist/cjs/index.js

@@ -0,0 +1,42 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SANDBOX_URL = exports.PROD_URL = exports.VERSION = void 0;
+exports.createNextXClient = createNextXClient;
+/**
+ * NextX SDK cho Node.js/TypeScript. Kiểu `paths` sinh từ https://developers.nextx.vn/openapi.json — 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, tham số và hình dạng phản hồi.
+ *
+ *   const nx = createNextXClient({ apiKey: process.env.NEXTX_API_KEY! });
+ *   const { data, error } = await nx.GET("/api/v1/crm/contacts", { params: { query: { pageSize: 20 } } });
+ */
+const openapi_fetch_1 = require("openapi-fetch");
+const version_js_1 = require("./version.js");
+Object.defineProperty(exports, "VERSION", { enumerable: true, get: function () { return version_js_1.VERSION; } });
+exports.PROD_URL = "https://api.nextx.vn";
+exports.SANDBOX_URL = "https://api-dev.nextx.vn";
+function createNextXClient(opts) {
+    const { baseUrl = exports.PROD_URL, language = "vi", fetch } = opts;
+    if (!opts.apiKey && !opts.accessToken)
+        throw new Error("NextX SDK: cần apiKey hoặc accessToken");
+    const client = (0, openapi_fetch_1.default)({
+        baseUrl: baseUrl.replace(/\/+$/, ""),
+        fetch,
+        headers: {
+            "Accept-Language": language,
+            // Trình duyệt tự bỏ User-Agent nên chỉ có tác dụng phía máy chủ.
+            "User-Agent": `nextx-sdk-node/${version_js_1.VERSION}`,
+            ...(opts.apiKey ? { "X-Api-Key": opts.apiKey } : {}),
+        },
+    });
+    const token = opts.accessToken;
+    if (token) {
+        const auth = {
+            async onRequest({ request }) {
+                request.headers.set("Authorization", `Bearer ${typeof token === "function" ? await token() : token}`);
+                return request;
+            },
+        };
+        client.use(auth);
+    }
+    return client;
+}

package/dist/cjs/package.json

@@ -0,0 +1 @@
+{"type":"commonjs"}