Norbix TypeScript SDK

The MCP-native Backend-as-a-Service for the agentic era.

Quickstart · Website · Docs · Examples · Blog · X · YouTube · Discord

↑ 90-second demo — watch on YouTube

What is Norbix?

Norbix is a Backend-as-a-Service built for the agentic era. One platform exposes everything an app needs — auth, database, file storage, email, push, payments, code functions, logging — as both a typed SDK and an MCP server, so a developer and their agent can call the same backend the same way.

It runs three ways: as a fully managed cloud at cloud.norbix.ai (zero DevOps), self-hosted on your own machine or server, or as enterprise in your VPC. Same modules, same APIs, same SDKs — pick the runway, not the runtime.

This repo is the TypeScript SDK — one package on npm (@norbix.ai/ts) that exposes both the runtime API and the configuration Hub as separate import paths so you only ship the surface you actually use. Plus a third surface, the Norbix MCP server, that exposes the same modules to your IDE. Works in Node 18+ and modern browsers.

Two surfaces in one package — API or Hub?

Norbix has two surfaces, and each is its own import path. The npm package is one (@norbix.ai/ts), but tree-shaking is per-subpath — pick the one that matches what your code is doing. Most apps need only the API in production code; the Hub is for admin tooling, internal dashboards, and infrastructure-as-code.

	`@norbix.ai/ts/api`	`@norbix.ai/ts/hub`
Surface	Runtime — what your app does at request time	Control plane — how Norbix is configured
Scope	Project-scoped data	Project & account configuration
Default base URL	`https://api.norbix.ai`	`https://hub.norbix.ai`
Typical caller	Your app's backend, your mobile app, your AI agent	Your admin UI, your CLI, your IaC scripts
Examples	Sign in users · query collections · send transactional email · charge a card · invoke a function · run an AI chat	Define schemas · configure an SMTP provider · invite a teammate · open a billing portal · set up a webhook

# One install — pick the import path you need
npm install @norbix.ai/ts

// App / runtime code
import { Norbix } from '@norbix.ai/ts';

// Both surfaces are reachable from one client:
norbix.api.database.find({ collectionName: 'orders' });
norbix.hub.database.getAllDatabaseSchemas();

Both surfaces share the same authentication model, the same error model, and the same configuration shape. Want a third option that's not a package at all? See Norbix MCP — same modules, exposed to your IDE.

Getting started

The Getting Started examples below use the API surface because that's what most apps need first. The Hub follows the same shape — see Hub example below.

Install

npm install @norbix.ai/ts

Three real things in 30 lines

The examples below assume an API key from the Norbix Cloud Dashboard and a project ID. The same code works against self-hosted and enterprise deployments — only the base URL changes (see Authentication & configuration).

1. Register a user

import { Norbix } from '@norbix.ai/ts';

const norbix = new Norbix({
  apiKey: process.env.NORBIX_API_KEY,
  projectId: 'proj_123',
});

const user = await norbix.api.membership.saveEmailUser({
  email: 'ada@example.com',
  password: 'correct-horse-battery-staple',
  firstName: 'Ada',
  lastName: 'Lovelace',
});

console.log(user.id);

2. Insert a record

const order = await norbix.api.database.insertOne({
  collectionName: 'orders',
  document: {
    userId: user.id,
    amount: 4900,
    currency: 'EUR',
    status: 'pending',
    items: [
      { sku: 'NBX-T-SHIRT', qty: 1, price: 2900 },
      { sku: 'NBX-MUG', qty: 1, price: 2000 },
    ],
    createdAt: new Date().toISOString(),
  },
});

console.log(order.id);

3. Ask the AI

const answer = await norbix.api.chat.askChat({
  messages: [
    { role: 'system', content: 'You are a concise sales assistant.' },
    { role: 'user', content: `Summarise order ${order.id} in one sentence.` },
  ],
});

console.log(answer.content);

That's the loop — auth, data, AI — using three real modules behind one client. The same modules are exposed as MCP tools, so any MCP-native agent can drive the same flow. Email/push/payments and other configurable surfaces live on the Hub — see Hub example.

Want it in your language? See the Norbix SDKs family below — every SDK exposes the same module names and method shapes.

Authentication & configuration

Both surfaces share the same configuration shape. The only difference is the default base URL: the API surface points at https://api.norbix.ai, the Hub surface points at https://hub.norbix.ai.

Auth modes

The SDK supports two auth modes. Both are sent as Authorization: Bearer <token>. If both are configured, the JWT wins. With neither configured, the SDK throws NORBIX_NOT_AUTHENTICATED on the first call.

Mode	When to use	How
API key	Server-to-server, scripts, scheduled jobs, IaC	`apiKey: '...'` or `NORBIX_API_KEY` env
JWT bearer	Logged-in user session	`bearerToken: '...'`, `NORBIX_BEARER_TOKEN` env, or `await norbix.login(...)`

// Service mode — long-lived API key
const norbix = new Norbix({ apiKey: '<api_key>', projectId: 'proj_123' });

// User mode — exchange credentials for a JWT
const norbix = new Norbix({ projectId: 'proj_123' });
await norbix.login({ userName: 'alice@team.io', password: 'secret' });

Default base URLs

When you install the package, no base URL is required — the SDK points at Norbix Cloud by default.

Surface	Default base URL
`norbix.api`	`https://api.norbix.ai`
`norbix.hub`	`https://hub.norbix.ai`

Overriding the base URL

Override the base URL when you self-host Norbix on your own infrastructure or run it locally. Pass it as a constructor option, or set the corresponding env var. Two real-world examples:

// Self-hosted on your company domain
const norbix = new Norbix({
  apiKey: process.env.NORBIX_API_KEY,
  projectId: 'proj_123',
  apiBaseUrl: 'https://api.norbix.isidos.lt',
  hubBaseUrl: 'https://hub.norbix.isidos.lt',
});

// Local development against a Norbix instance on localhost
const norbix = new Norbix({
  apiKey: 'sk_dev_local',
  projectId: 'proj_dev',
  apiBaseUrl: 'http://localhost:5000',
  hubBaseUrl: 'http://localhost:5001',
});

Or via environment variables (no code change required):

NORBIX_API_KEY=sk_live_...
NORBIX_PROJECT_ID=proj_123
NORBIX_ACCOUNT_ID=acc_456            # optional, unlocks Hub account-scoped endpoints
NORBIX_REGION=nb-eu-germany          # optional, pins requests to a Norbix region (see Regions)
NORBIX_API_URL=https://api.norbix.ai            # override for self-hosted, e.g. https://api.norbix.isidos.lt
NORBIX_HUB_URL=https://hub.norbix.ai            # override for self-hosted, e.g. https://hub.norbix.isidos.lt

const norbix = new Norbix(); // reads everything from env, including the overridden URLs

The SDK does not load .env files itself — use node --env-file=.env (Node 20+) or import 'dotenv/config' in your app's bootstrap. In the browser (where process doesn't exist) env loading is a silent no-op.

Regions

Norbix Cloud is multi-region. A region is identified by a region code such as nb-eu-germany, and the SDK lets you pin requests to one in three ways — constructor option, environment variable, or at runtime:

// 1. Constructor option
const norbix = new Norbix({
  apiKey: process.env.NORBIX_API_KEY,
  projectId: 'proj_123',
  region: 'nb-eu-germany',
});

// 2. NORBIX_REGION env var — picked up when the option is not set
//    NORBIX_REGION=nb-eu-germany
const norbix = new Norbix();

// 3. Switch at runtime
norbix.setRegion('nb-us-east');
norbix.getRegion(); // 'nb-us-east'
norbix.setRegion(undefined); // clear — back to no region

And a fourth way: every endpoint method accepts a per-call region override on its second argument, just like bearerToken and timeoutMs:

await norbix.api.database.find(
  { collectionName: 'orders' },
  { region: 'nb-us-east' },
);

await norbix.hub.account.getProjects({}, { region: 'nb-us-east' });

How a region affects the request. The resolved region (per-call override → client region → NORBIX_REGION) is sent as the nb-region header. There is no default region — when nothing is set, no header is sent and the backend routes to the project's primary region. Self-hosted deployments are unaffected: no region configured means requests are byte-identical to the pre-regions behavior.

Regional base URLs. When the client uses the SDK's built-in default base URLs, setting a client-level region also composes the regional URL by prefixing the region code as a subdomain — https://api.norbix.dev becomes https://nb-eu-germany.api.norbix.dev (and likewise for the Hub URL). setRegion(...) re-composes the URL, and setRegion(undefined) restores the defaults. Two rules to remember:

A custom baseUrl (or NORBIX_API_URL / NORBIX_HUB_URL) is never rewritten — with a region set, only the nb-region header is added.
A per-call region override affects the header only — it never changes the request URL.

Managing a project's regions. The Hub's regions module lists the regions available to the account and updates the set of regions a project spans (one primary + any additional):

// List available regions — each item carries { id, continent, name }
const { items } = await norbix.hub.regions.list();

// Change the project's primary region / the regions it spans
await norbix.hub.regions.updateProjectRegions({
  projectId: 'proj_123',
  primaryRegion: 'nb-eu-germany',
  additionalRegions: ['nb-us-east'],
});

hub.account.createProject accepts the same primaryRegion / additionalRegions fields, project DTOs report primaryRegion, additionalRegions, and the combined regions[], and the echo endpoint lists the regions a deployment exposes with their regional endpoints. Full reference: docs/hub/regions.md.

SSR / multi-tenant safe usage

For per-request scoping (different bearer tokens per request), pass the token as a per-call override on the second argument instead of mutating a shared singleton with setBearerToken(...):

await norbix.api.database.find(
  { collectionName: 'orders' },
  { bearerToken: requestUserToken, timeoutMs: 5_000 },
);

Every generated endpoint method accepts the same { bearerToken?, timeoutMs?, env?, region? } options as its second argument.

Project vs account scope. projectId is required by the API surface. accountId is required by the Hub surface for endpoints that act on the account (team invite, billing portal, account verify). Calling those without accountId throws NORBIX_ACCOUNT_SCOPE_REQUIRED before the request leaves your machine.

Modules

The SDK is a thin client over the Norbix gateway. Every module below resolves to a typed namespace on the client and an MCP tool group, so the same surface is reachable from code or from an agent. Per-module reference pages live in /docs and on docs.norbix.ai.

`norbix.api` — runtime, project-scoped

Default base URL: https://api.norbix.ai. 8 modules · 66 endpoints.

Module	Purpose	Reference
🔐 `auth`	Sign-in flows. Most apps prefer `norbix.login(...)`.	`docs/api/auth.md`
👤 `membership`	User CRUD, registration, login, passkeys, email verification, magic links, roles, preferences	`docs/api/membership.md`
🗄️ `database`	Collections, find/insert/update/delete, aggregate, taxonomies	`docs/api/database.md`
📁 `files`	Signed upload URLs, download, file info, listing	`docs/api/files.md`
🤖 `chat`	AI chat completion	`docs/api/chat.md`
🔑 `apikeys`	List + regenerate per-environment API keys	`docs/api/apikeys.md`
🪪 `accessToken`	Refresh-token exchange	`docs/api/access_token.md`
🩺 `echo`	Gateway smoke check	`docs/api/echo.md`

Email/push/SMS notifications, payments, and code execution are configured on the Hub surface and surfaced at runtime through integration triggers — they are not separate API modules. File storage now has its own files API module: it issues signed upload URLs so clients upload binary content directly to storage, never streaming bytes through the Norbix API.

→ Full API index

`norbix.hub` — control plane, configuration

Default base URL: https://hub.norbix.ai. 18 modules · 315 endpoints.

Module	Purpose	Reference
🏢 `account`	Account profile, status, projects, regions, team, billing, verification	`docs/hub/account.md`
🌍 `regions`	List available Norbix regions, update the regions a project spans	`docs/hub/regions.md`
🗄️ `database`	Schemas, integrations, saved aggregates, taxonomies, triggers	`docs/hub/database.md`
📁 `files`	File-storage integrations, triggers, module settings	`docs/hub/files.md`
📧 `notifications`	Email, push & SMS templates, integrations, campaigns, contacts, devices	`docs/hub/notifications.md`
📨 `email`	Email module switches	`docs/hub/email.md`
💳 `payments`	Payment integrations, triggers, tests, module settings	`docs/hub/payments.md`
🤖 `ai`	LLM and MCP integration configuration and tests	`docs/hub/ai.md`
📊 `logs`	Logging integrations and module settings	`docs/hub/logs.md`
👥 `membership`	Roles, policies, users, preferences, integrations, triggers	`docs/hub/membership.md`
⏰ `scheduler`	Scheduler module and task management	`docs/hub/scheduler.md`
🪝 `webhooks`	Webhook integrations, destinations, tests, module settings	`docs/hub/webhooks.md`
📥 `webhooks` (receiver)	Verify & handle inbound Norbix webhook POSTs at your endpoint	`docs/webhooks-receiver.md`
🔐 `auth`	Hub-side sign-in flows	`docs/hub/auth.md`
🔑 `apikeys`	List + regenerate Hub API keys	`docs/hub/apikeys.md`
🪪 `accessToken`	Refresh-token exchange	`docs/hub/access_token.md`
🩺 `echo`	Gateway smoke check	`docs/hub/echo.md`
🛠️ `internal`	Internal helpers	`docs/hub/internal.md`
📦 `resources`	Resolve resource references	`docs/hub/resources.md`

→ Full Hub index

Hub example

The Hub surface follows the same shape as the API surface — same constructor, same auth, same client. Use it from admin tooling, internal dashboards, or IaC scripts.

import { Norbix } from '@norbix.ai/ts';

const norbix = new Norbix({
  apiKey: process.env.NORBIX_API_KEY,
  accountId: 'acc_456',
});

// Define a database schema for a new collection
await norbix.hub.database.saveDatabaseSchema({
  collectionName: 'orders',
  fields: [
    { name: 'userId', type: 'string', required: true, indexed: true },
    { name: 'amount', type: 'integer', required: true },
    { name: 'currency', type: 'string', required: true },
    { name: 'status', type: 'string', required: true, enum: ['pending', 'paid', 'refunded'] },
    { name: 'createdAt', type: 'datetime', required: true },
  ],
});

// Invite a teammate
await norbix.hub.account.sendInviteToTeamMember({
  email: 'maya@team.io',
  role: 'developer',
});

Inbound webhooks

When Norbix POSTs signed events to your endpoint, use @norbix.ai/ts/webhooks — not hub.webhooks (that module configures destinations).

import {
  NORBIX_WEBHOOK_EVENT_NAMES,
  NorbixWebhookEvents,
  NorbixWebhookReceiver,
} from '@norbix.ai/ts/webhooks';

const receiver = new NorbixWebhookReceiver(); // NORBIX_WEBHOOK_SIGNING_SECRET from env

receiver.on(NorbixWebhookEvents.Membership.UserRegistered, (user, event) => {
  console.log('registered', user.email ?? user.userName);
});

receiver.onAll(NORBIX_WEBHOOK_EVENT_NAMES, (e) => console.log(e));

await receiver.handle({ rawBody: req.rawBody, headers: req.headers });

→ docs/webhooks-receiver.md

Norbix MCP — same modules, agent-native

Norbix ships an MCP (Model Context Protocol) server that exposes every API and Hub module as agent-callable tools. Same surface as this SDK, just over a different transport — when you connect the Norbix MCP to your IDE, the agent in your editor can read your project, run scripts, and call Norbix the same way your app does.

What it gives you:

Total SDK & API knowledge. The Norbix MCP knows every module, every method, every request/response type — across all Norbix SDKs (TypeScript, .NET, Python, Dart, Kotlin, Swift) and the underlying gateway. Ask "how do I send a templated email from the .NET SDK?" in your IDE chat and the agent answers from the same source the docs are generated from.
Code-aware actions. Connect it to your repo and the agent can update project constants, regenerate types after a Hub schema change, scaffold a new module integration, run a Norbix CLI command, or open a PR — without leaving the chat. Run a script or talk to it; same surface, two interaction modes.
Drop-in IDE setup. One config block in your IDE's MCP settings and you're done. The MCP server runs locally and proxies to your Cloud / self-hosted / enterprise Norbix instance using the same NORBIX_API_URL / NORBIX_HUB_URL env vars as the SDK.

Setup in your IDE:

IDE	Setup guide
Claude Code	`docs.norbix.ai/mcp/claude-code`
Cursor	`docs.norbix.ai/mcp/cursor`
Windsurf	`docs.norbix.ai/mcp/windsurf`
Codex	`docs.norbix.ai/mcp/codex`
Claude Desktop	`docs.norbix.ai/mcp/claude-desktop`
VS Code (Continue)	`docs.norbix.ai/mcp/vscode`
Zed	`docs.norbix.ai/mcp/zed`

→ Full MCP documentation · Why MCP? · Self-hosted MCP

Norbix SDKs

Same modules, same method shapes, every language. Each row links to the repo for that language. Package shape varies per language ecosystem norm — TypeScript, Python, Dart, and Kotlin ship a single package; .NET and Swift ship two surfaces (NuGet packages / SwiftPM library products) inside one repo.

Language	Package	Repo	Status
TypeScript / Node	`@norbix.ai/ts`	norbix-code/sdk-ts	✅ Stable
.NET	`Norbix.Api` + `Norbix.Hub`	norbix-dev/norbix-net	✅ Stable
Python	`norbix`	norbix-dev/norbix-python	🚧 In progress
Dart / Flutter	`norbix`	norbix-dev/norbix-dart	🚧 In progress
Kotlin	`dev.norbix:norbix`	norbix-dev/norbix-kotlin	🚧 In progress
Swift	`Norbix` (libs: `NorbixApi`, `NorbixHub`)	norbix-dev/norbix-swift	🚧 In progress

Install Norbix

Three ways to run the backend this SDK talks to. Pick by who owns the infrastructure and how strict the compliance bar is.

A. Try it on Norbix Cloud — fastest

Zero DevOps. Spin up a managed project on cloud.norbix.ai, grab an API key, point the SDK at it. The default base URLs (https://api.norbix.ai and https://hub.norbix.ai) already point at Cloud — no override needed. 7-day free trial, no credit card.

# 1. Sign up at https://cloud.norbix.ai
# 2. Create a project, copy the API key + project ID
export NORBIX_API_KEY=sk_live_...
export NORBIX_PROJECT_ID=proj_...
# 3. Run any of the examples above. You're done.

→ Sign up · Cloud docs

B. Self-host on your machine or your server

Run Norbix on Docker, Kamal, Terraform, AWS CDK, Kubernetes, DigitalOcean, a VPS, or bare metal. Issue a license from the Cloud Dashboard, then deploy with one command. Override the SDK's base URL to point at your deployment.

1. Get a self-hosted license. Sign in at cloud.norbix.ai, open the Self-Hosted tab, generate a license key.

2. Deploy. Build your install in the Cloud Dashboard's installer UI or clone the install repo:

# Quickest — Docker Compose
git clone https://github.com/norbix-code/install
cd install/docker-compose
NORBIX_LICENSE_KEY=lic_... docker compose up -d
# Norbix is up at http://localhost:5000 (API) and http://localhost:5001 (Hub) by default

Other deployment paths (each in a sibling folder of the install repo):

Method	Folder	Best for
🐳 Docker	`docker-compose/`	Local dev, single VM
🚢 Kamal	`kamal/`	One-server deploys, Rails-style
🏗️ Terraform	`terraform/`	Multi-cloud IaC
☁️ AWS CDK	`aws-cdk/`	AWS-native
⎈ Kubernetes	`kubernetes/`	k3s / k8s at scale
🌊 DigitalOcean	`digitalocean/`	Droplets + DO Kubernetes
🖥️ VPS / bare metal	`vps/`	Any provider, total control
🏢 On-premises	`on-prem/`	Air-gapped or private DC

3. Point the SDK at it. Two patterns — pick whichever fits.

# Local development on your machine
export NORBIX_API_URL=http://localhost:5000
export NORBIX_HUB_URL=http://localhost:5001

# Self-hosted on your company's domain
export NORBIX_API_URL=https://api.norbix.isidos.lt
export NORBIX_HUB_URL=https://hub.norbix.isidos.lt

→ Install repo · Self-host docs

C. Enterprise — your cloud, your compliance

Run Norbix in your VPC or dedicated infrastructure. SOC2-ready, GDPR/HIPAA-compatible, full audit trails, custom SLA, dedicated support, deployment review with the Norbix team. Same APIs as Cloud and Self-Hosted — just behind your perimeter. Override the SDK's base URL to your private endpoint.

→ Contact sales · Enterprise docs

Error handling

import { NorbixError } from '@norbix.ai/ts';

try {
  await norbix.api.database.find({ collectionName: 'orders' });
} catch (err) {
  if (err instanceof NorbixError) {
    console.log(err.status, err.code, err.fieldErrors);
  }
  throw err;
}

Code	Meaning
`NORBIX_NOT_AUTHENTICATED`	No `apiKey`, `bearerToken`, or env var, and `login()` not called.
`NORBIX_ACCOUNT_SCOPE_REQUIRED`	Account-scoped Hub endpoint called without `accountId`.
`NORBIX_MISSING_PATH_PARAM`	A `{token}` in the route was not provided on the request.
`NORBIX_NETWORK_ERROR`	Fetch failed (network, CORS, timeout).

Community & support

Documentation. Best for: building, integrating, and reference.
GitHub Discussions. Best for: technical Q&A, feature requests, sharing what you built.
GitHub Issues. Best for: bugs and reproducible errors in this SDK.
Discord. Best for: real-time chat with the team and the community.
Email support. Best for: account, billing, and infrastructure issues that aren't public.

Resources

Website · Cloud Dashboard · Docs · API · Hub · MCP · Blog · Discord · X · YouTube · LinkedIn

Development

npm install
npm run lint
npm run typecheck
npm test
npm run build

Conventional commits are required. Use npm run commit for a guided flow. Pushes to main are released to npm by semantic-release with provenance enabled. next and beta branches publish prereleases.

The SDK module classes (src/api/*, src/hub/*), their tests, and per-module docs are generated from the gateway DTOs by an internal maintenance workflow. Generated artifacts are committed to git and consumed by CI as-is — CI never regenerates. The generation scripts themselves are dev-only and gitignored (see .gitignore).

Security

Found something? Don't open a public issue. See SECURITY.md and email security@norbix.ai. We respond within one business day.

Contributing

Issues, PRs, and design partners welcome. Start with CONTRIBUTING.md for branching, local dev, and how to add a module. Bigger ideas land in Discussions before they land in code.

License

MIT © Norbix

The MCP-native Backend-as-a-Service for the agentic era.

norbix.ai · cloud.norbix.ai · docs.norbix.ai · MCP · Discord · X · YouTube

Name		Name	Last commit message	Last commit date
Latest commit History 27 Commits
.github		.github
.husky		.husky
docs		docs
src		src
tests		tests
.commitlintrc.json		.commitlintrc.json
.editorconfig		.editorconfig
.gitignore		.gitignore
.npmignore		.npmignore
.prettierrc		.prettierrc
.releaserc.json		.releaserc.json
ArchitectOverview.md		ArchitectOverview.md
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
eslint.config.js		eslint.config.js
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json
tsup.config.ts		tsup.config.ts
vitest.config.ts		vitest.config.ts

Uh oh!

Folders and files

Latest commit

History

Repository files navigation

Norbix TypeScript SDK

What is Norbix?

Two surfaces in one package — API or Hub?

Getting started

Install

Three real things in 30 lines

1. Register a user

2. Insert a record

3. Ask the AI

Authentication & configuration

Auth modes

Default base URLs

Overriding the base URL

Regions

SSR / multi-tenant safe usage

Modules

norbix.api — runtime, project-scoped

norbix.hub — control plane, configuration

Hub example

Inbound webhooks

Norbix MCP — same modules, agent-native

Norbix SDKs

Install Norbix

A. Try it on Norbix Cloud — fastest

B. Self-host on your machine or your server

C. Enterprise — your cloud, your compliance

Error handling

Community & support

Resources

Development

Security

Contributing

License

About

Resources

Contributing

Stars

Watchers

Forks

Releases

Packages

Used by

Contributors

Languages

`norbix.api` — runtime, project-scoped

`norbix.hub` — control plane, configuration