@byteplus-iga-pages/data

Server-only lightweight data SDK for BytePlus IGA Pages. It provides five project-scoped operations: create, get, list, update, and remove.

Installation

npm install @byteplus-iga-pages/data

The SDK is only available in Pages projects; Agent projects are not supported. It requires Node.js 20+ and an BytePlus IGA Pages server runtime. Use it from an api/ handler, a framework server route, a Server Action, or other server-only code. Do not import it from browser code or a "use client" module.

For local development:

bp-iga login
bp-iga pages link
bp-iga pages dev

BytePlus IGA Pages supplies the current project's Page SDK Token. Application code does not configure an endpoint or read the token.

The CLI rejects direct Data SDK dependencies when creating an Agent project (including agents link) and before Agent local startup, build, or deployment. These CLI checks do not replace backend authorization: the data service must validate that the token belongs to a Pages project.

Usage

import {
  create,
  get,
  list,
  update,
  remove,
} from "@byteplus-iga-pages/data";

const { ID } = await create({
  title: "Write PRD",
  status: "todo",
});

const record = await get(ID);
const page = await list({
  filter: { status: "todo" },
  pageNumber: 1,
  pageSize: 20,
});

await update(ID, { status: "done" });
await remove(ID);

Business fields are sent flat. The backend manages project/account scope, record IDs, and timestamps. Public record fields follow the backend contract: ID, CreatedAt, and UpdatedAt.

Errors

Failures throw DataError. toJSON() returns:

{
  code: string;
  status?: number;
  message: string;
}

HTTP and business failures prefer the upstream message (or string error), with a log_id appended when available. Credentials are redacted and messages are limited to 2048 characters. Upstream business codes and response bodies are not exposed. code is the SDK classification: HTTP failures use status-based codes, HTTP-success business failures use BusinessError, malformed responses use InvalidResponse, missing runtime configuration uses ConfigurationError, and connection failures use ConnectionError. Cancellation and timeout use AbortError and TimeoutError; invalid or non-serializable input uses BadRequest.

Use error.message or error.toJSON() in server-side diagnostics. Applications should return their own user-facing error messages to browsers.

License

See LICENSE in the published package.