SDK

Node.js / TypeScript

Paths, parameters and responses are typed, so your editor autocompletes and rejects wrong calls as you type. Runs on Node, Deno, Bun and browsers; supports both import and require.

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

Each route is a module in nextfarm_sdk.api.<module> with sync, sync_detailed, asyncio and asyncio_detailed. The *_detailed variants also return status code and headers.

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)

Good to know

• Defaults to production. Use SANDBOX_URL with a sandbox key for testing — see sandbox.
• Errors follow RFC 7807. Node returns them in error rather than throwing; Python raises UnexpectedStatus for undocumented codes. Code list: Error codes.
• Send an Idempotency-Key with writes so retries are safe:

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
});

Versions

SDKs follow semver, independent of /api/v1. The bump is decided by machine-diffing the old and new OpenAPI; breaking changes need human approval before release.

Routes or fields to be removed are marked deprecated at least 90 days ahead — see Versioning.

Verify the packages

Every release is built and published from the public repository's GitHub Actions via trusted publishing — no long-lived publish tokens. Each release carries a provenance attestation pointing at the exact commit it was built from.

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