SDK

Thư viện chính thức cho Node.js/TypeScript và Python, có kiểu đầy đủ. Mã sinh tự động từ /openapi.json nên luôn khớp API đang chạy, và chỉ gồm các tuyến API key gọi được.

Ngôn ngữ	Cài	Mã nguồn
Node.js ≥ 18 · TypeScript	`npm i @nextfarm/sdk`	nextfarm-sdk-node
Python ≥ 3.11	`pip install nextfarm-sdk`	nextfarm-sdk-python

Node.js / TypeScript

Đường dẫn, tham số và phản hồi đều có kiểu, trình soạn thảo gợi ý và chặn gọi sai ngay lúc viết. Chạy được trên Node, Deno, Bun và trình duyệt; hỗ trợ cả import lẫn require.

TypeScript

import { createNextFarmClient, SANDBOX_URL } from "@nextfarm/sdk";

const nf = createNextFarmClient({ apiKey: process.env.NEXTFARM_API_KEY!, baseUrl: SANDBOX_URL });

const { data, error } = await nf.GET("/api/v1/iot/devices", { params: { query: { page: 1, pageSize: 20 } } });
if (error) throw new Error(`${error.status} ${error.title}`);
for (const d of data.items ?? []) console.log(d.name);

Python

Mỗi tuyến là một mô-đun trong nextfarm_sdk.api.<phân hệ>, gồm sync, sync_detailed, asyncio và asyncio_detailed. Bản *_detailed trả thêm status code và header.

Python

import os
from nextfarm_sdk import create_client, SANDBOX_URL
from nextfarm_sdk.api.iot import get_api_v1_iot_devices

nf = create_client(api_key=os.environ["NEXTFARM_API_KEY"], base_url=SANDBOX_URL)

page = get_api_v1_iot_devices.sync(client=nf, page=1, page_size=20)
for d in page.items or []:
    print(d.name)

Những điều nên biết

Mặc định gọi prod. Thử nghiệm thì dùng SANDBOX_URL với khoá sandbox, xem sandbox.
Lỗi theo RFC 7807. Node trả trong error, không ném ngoại lệ; Python ném UnexpectedStatus với mã ngoài tài liệu. Bảng mã: Error code.
Gọi ghi nên kèm Idempotency-Key để retry an toàn:

TypeScript

await nf.POST("/api/v1/harvest/harvest-records", {
  body: { /* … */ },
  headers: { "Idempotency-Key": crypto.randomUUID() }, // gửi lại an toàn, không tạo trùng
});

Không đưa API key ra trình duyệt của người dùng cuối. Ứng dụng phía máy khách dùng access token OAuth.

Phiên bản

SDK đánh số theo semver, tách khỏi /api/v1. Mức tăng do máy so OpenAPI cũ và mới quyết định; thay đổi phá vỡ phải được người duyệt trước khi phát hành.

Thay đổi	Từ 1.0	Giai đoạn 0.x
Phá vỡ: gỡ tuyến/trường, đổi kiểu, thêm tham số bắt buộc	2.0.0	0.2.0
Thêm mới tương thích	1.1.0	0.1.1
Chỉ đổi mô tả	1.0.1	0.1.1

Kênh	npm	PyPI
Ổn định — khớp API prod	`@nextfarm/sdk`	`nextfarm-sdk`
Xem trước — có thể đổi bất kỳ lúc nào	`@nextfarm/sdk@beta`	`pip install --pre nextfarm-sdk`

Tuyến hoặc trường sắp gỡ được đánh dấu deprecated ít nhất 90 ngày trước, xem Phiên bản & ngừng hỗ trợ.

Kiểm gói chính chủ

Mọi bản được dựng và đăng từ GitHub Actions của kho công khai bằng trusted publishing, không có khoá đăng dài hạn nào. Mỗi bản kèm chứng nhận nguồn gốc trỏ đúng commit đã dựng.

Shell

npm audit signatures            # npm: verify signature + provenance
pip download nextfarm-sdk --no-deps && sha256sum -c SHA256SUMS   # PyPI: so với SHA256SUMS ở GitHub Release