@nublestation/client — NubleStation

@nublestation/client is the umbrella SDK: one factory call returns a single client that exposes every NubleStation service your app uses — Vault (storage), Identity (auth), and Blaze (database). If you’d rather pull in just one service, the per-service packages (@nublestation/vault, @nublestation/identity, @nublestation/blaze) work standalone — the unified client simply wraps them.

Installation

npm install @nublestation/client
# or
pnpm add @nublestation/client

This is the only package you install. @nublestation/vault, @nublestation/identity, and @nublestation/blaze are dependencies of the client and come down automatically — you never install them yourself unless you want exactly one service on its own (see below).

Creating a client

import { nubleClient } from "@nublestation/client";
import { schema } from "./schema";

const nuble = nubleClient(
  "nbl_<key_id>.<secret>",        // API key from the Console
  "http://api.clinic.local",      // NubleStation gateway URL
  { app: "bucket", schema },      // options (all optional)
);

const { vault, identity, blaze } = nuble;

Signature

nubleClient(apiKey: string, url: string, opts?: NubleOptions)

Argument	Description
`apiKey`	App-scoped API key from Console → Apps → your app → Settings
`url`	Your gateway base URL, `api.{org}.local`
`opts.app`	App slug — required for Identity session scoping
`opts.schema`	Your `defineSchema()` export — enables typed `blaze.<table>` access
`opts.identityUrl`	Direct Identity URL. Defaults to `url` with `api.` → `identity.`

Services

Destructure the three services from the returned instance:

Service	Accessor	Status
Vault — file storage	`nuble.vault`	Live
Identity — auth	`nuble.identity`	Live
Blaze — database	`nuble.blaze`	Live

// Vault — upload, list, and download files
await vault.upload("reports", "q1.pdf", file);
const files = await vault.listMine();

// Identity — who is the current user?
const session = await identity.getSession();

// Blaze — typed CRUD over your tables
await blaze.file_comments.create({ file_id, body, author_id, author_name });
const comments = await blaze.file_comments.list();

The full Vault method set is documented on the @nublestation/vault page — every method is identical when reached through nuble.vault.
The Blaze table client (list, get, create, update, delete) is documented on the @nublestation/blaze page.
Identity is documented on the @nublestation/identity page.

ℹ Note

Identity rides the organization’s shared SSO session cookie rather than the API key, which is why it needs opts.app (and optionally opts.identityUrl). The unified client wires all of that for you from the single url you pass.

Typed database access

Pass your schema to opts.schema and blaze becomes fully typed — table names, row shapes, and insert payloads all autocomplete:

// schema.ts
import { defineSchema, t } from "@nublestation/client";

export const schema = defineSchema({
  file_comments: t.model({
    file_id:     t.string().required(),
    body:        t.string().required(),
    author_id:   t.string().required(),
    author_name: t.string().required(),
  }),
});

defineSchema and t are re-exported from @nublestation/client, so you don’t need a separate @nublestation/blaze install just to declare a schema.

Error handling

Service calls throw a typed error on any non-2xx response. The Vault error class is re-exported from the client for convenience:

import { VaultError } from "@nublestation/client";

try {
  await vault.upload("docs", "report.pdf", bytes);
} catch (err) {
  if (err instanceof VaultError) {
    console.error(err.status, err.code); // e.g. 401 "unauthorized"
  }
}

Code	Status	Meaning
`unauthorized`	401	API key missing, invalid, or revoked
`forbidden`	403	No access to the resource
`not_found`	404	Resource does not exist
`internal_error`	500	Unexpected server error

Exports

import { nubleClient, createClient, VaultError } from "@nublestation/client";
import { defineSchema, t, serializeSchema } from "@nublestation/client";
import type {
  NubleOptions, NubleInstance,
  VaultClient, IdentityClient, BlazeClient,
  FileResult, Grant, GrantRole, IdentityUser, SerializedSchema,
} from "@nublestation/client";

✦ Tip

createClient({ url, apiKey, app }) is kept as a backward-compatible alias for nubleClient(apiKey, url, { app }). New code should prefer nubleClient.

When to use which package

@nublestation/client (recommended) — installs once and brings vault, identity, and blaze with it. Use it whenever you touch more than one service, or just to keep a single dependency and config. You do not add the per-service packages on top of it.
@nublestation/vault / @nublestation/identity / @nublestation/blaze — install one of these instead of the client when your app needs exactly one service and you want the smallest possible install.

Both approaches share the same method signatures and types, so moving between them is a one-line change.