NubleStation ships one npm package per service, plus an umbrella package that bundles them behind a single client. Use the umbrella for convenience, or install one service for the smallest footprint.

Package	Service	What it does
@nublestation/client	All	Unified client — one config, nuble.vault.*, etc.
@nublestation/vault	Vault	File upload, download, sharing, public/private access
@nublestation/blaze	Blaze	Database queries on your app’s tables
@nublestation/identity	Identity	User sessions, SSO, and per-app authorization

Every package follows the same factory pattern — createClient({ ... }) (or createVaultClient, createIdentityClient) returns a typed client scoped to your app. Data-plane SDKs (Vault, Blaze) authenticate with an API key; @nublestation/identity is the exception — it rides the shared-cookie SSO session, so it takes no API key. See its page for details.

New to the SDK? Start with @nublestation/client — one install covers the data-plane services.

---

Quick start

# Install only the packages your app needs
npm install @nublestation/vault

import { createVaultClient } from "@nublestation/vault";

const vault = createVaultClient({
  url:    "http://api.clinic.local",   // NubleStation gateway URL
  apiKey: "nbl_<key_id>.<secret>",     // API key from the Console
});

await vault.upload("reports", "q1.pdf", file);
const files = await vault.list("reports");

---

Getting an API key

1. Open the Console at console.{org}.local
2. Go to Apps → your app → Settings
3. Click Generate API key
4. Copy the key — it is shown only once

The API key is scoped to one app. All requests made with it are isolated to that app’s data and files.

---

Error handling

All SDK packages throw a typed error class on non-2xx responses.

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

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

Common error codes across all packages:

Code	Status	Meaning
unauthorized	401	API key missing, invalid, or revoked
not_found	404	Resource does not exist
internal_error	500	Unexpected server error

---

How it works

The SDK sends plain HTTP requests to api.{org}.local with an Authorization: Bearer nbl_... header. The Gateway validates the key, resolves the app identity, and signs the forwarded request before it reaches the internal service. Your app never handles HMAC or internal secrets.

Your app
    │  Authorization: Bearer nbl_<key_id>.<secret>
    ▼
api.{org}.local  (Gateway)
    │  verify key → resolve app_id
    │  sign request with INTERNAL_HMAC_SECRET
    ▼
Internal service (Vault, Blaze, Identity)
    │  verify HMAC — reject if not from Gateway
    └  handle request

---

Packages

• @nublestation/client — unified client (start here)
• @nublestation/vault — file storage
• @nublestation/identity — auth, sessions, SSO
• Database queries — Blaze
• Real-time — SSE subscriptions (coming soon)