nogbase-client-sdk

TypeScript client for the nogbase headless platform.

Modules

• /rest (v3.0+): typed REST client for every public-v1 backend endpoint
• /core: auth context primitives
• /metadata: schema introspection helpers
• /generate: codegen helpers (graphql via genql)

Quickstart — REST

import { RestClient } from "nogbase-client-sdk/rest";

const client = new RestClient({
  baseUrl: "https://api.nogbase.ae",
  auth: { type: "bearer", token: "nbat_..." },  // or { type: "user_jwt", token }
  entityId: "ent_123",
});

// Low-level
const result = await client.request<{ items: AppManifest[] }>({
  method: "GET",
  path: "/platform/apps/catalog",
});

// Namespaced (generator-emitted, with strict types from @workspace/api)
const apps = await client.namespaces.platformApps.listAllPlatformApps();

Errors

Every non-2xx response throws NogbaseApiError:

import { isNogbaseApiError } from "nogbase-client-sdk/rest";

try {
  await client.request({ method: "GET", path: "/platform/apps/missing" });
} catch (e) {
  if (isNogbaseApiError(e)) {
    console.error(e.status, e.errorCode, e.message);
    // e.errorCode is one of the registered v1 codes
    // (see backend/internal/errors/v1_codes.go)
  }
}

Auth modes

• bearer: opaque app token (nbat_* issued via POST /platform/credentials/token)
• user_jwt: end-user JWT (frontend session)
• none: anonymous (e.g., POST /platform/credentials/refresh is the credential)

Multi-tenancy

The entityId constructor argument sets X-Entity-Id on every request — required by tenant-scoped endpoints.

Versioning

This package is semantic-versioned. The /rest module covers exactly the endpoints classified public-v1 in docs/api/v1-endpoints.md. v2 endpoints, when introduced, will live alongside v1 — no breaking changes within a major version.

Existing modules

/core, /metadata, /generate retain their v2.x behavior. See the d.ts files for API.

Build

pnpm build

Test

pnpm test