@datarealiser/api-client

A zero-dependency, browser-native client for the kernel-api REST API — plain fetch under the hood, every method returns a Promise, no bundler required. Built for Observable notebooks, but works in any modern browser or ESM-capable runtime.

Publish

Published as @datarealiser/api-client on npm. To ship a new version, bump version in package.json first, then from this directory:

npm login   # if you haven't already
./publish.sh --dry-run   # sanity-check without uploading anything
./publish.sh

publish.sh checks you're logged in to npm, smoke-tests that the module loads and exports DatarealiserApiClient/ApiError, confirms the current package.json version isn't already published, asks for confirmation, then runs npm publish. --tag <tag> publishes under a dist-tag other than latest; --yes/-y skips the confirmation prompt (for CI); --dry-run runs every check plus npm publish --dry-run without actually uploading.

Equivalent by hand, without the script:

npm publish

(publishConfig.access: "public" is already set in package.json, so a scoped package publishes publicly without needing --access public on the command line.)

Publishing under the @datarealiser scope requires that scope to exist as your npm username or an npm Organization you belong to (it already does, since this package is live under it) — if you're setting this up fresh under a different scope, create your own org at npmjs.com first, or change the name in package.json to a scope you own.

Use in Observable

New-style notebooks / Observable Framework (import ... from "npm:..." cells resolve straight from the npm registry):

import {DatarealiserApiClient} from "npm:@datarealiser/api-client";

Classic notebooks, via jsDelivr's +esm endpoint and a dynamic import() expression — not a static import {X} from "url" declaration cell. That declaration syntax is reserved for notebook-to-notebook references (import {foo} from "@user/notebook"); pointed at an arbitrary URL it fails silently, leaving the name unbound (X is not defined in any cell that references it), because Observable's parser treats the URL as a notebook reference rather than fetching it as an ES module. Use the dynamic form instead, as its own cell:

DatarealiserApiClient = (await import("https://cdn.jsdelivr.net/npm/@datarealiser/api-client@1/+esm")).DatarealiserApiClient

(Observable's own docs point to Skypack for this pattern instead of jsDelivr — skip it: cdn.skypack.dev 404s for packages it hasn't already indexed, which as of this writing includes this one. jsDelivr works and is what this package's own CDN links above already use.)

Then, in any cell:

client = new DatarealiserApiClient({
  baseUrl: "https://your-deployed-kernel-api.example.com",
  apiKey: apiKeyInput // e.g. from a viewof text input cell
})

me = client.me()

domains = client.listDomains()

// A file input cell: viewof upload = Inputs.file({label: "CSV or JSON"})
result = client.importTable("events", upload)                                   // lands in schema "public"
result = client.importTable("events", upload, {schema: "reporting"})            // or a different schema

// viewof upload = Inputs.file({label: "File to process"})
result = client.processFile("stock", upload)   // response shape is whatever the "stock" processor returns

rows = client.runQuery("users_by_domain", {emailPattern: "%@example.com", limit: 10})

Observable resolves promise-valued cells automatically — no await or .then() needed at the top level of a cell.

API

Mirrors the server's routes and the CLI's commands one-for-one:

client = new DatarealiserApiClient({ baseUrl, accessToken, refreshToken, apiKey })

// Auth — register/login store the returned tokens on the client instance
await client.register(email, password)  // also emails a 6-digit code; account is usable immediately either way
await client.login(email, password)
await client.refresh()      // rotates client.refreshToken
await client.logout()       // revokes + clears tokens
await client.me()           // JWT only, per the server's route auth — includes emailVerified

// Email verification — neither call needs a JWT; both take the email directly
await client.verifyEmail(email, code)        // code: the 6-digit string from the email; expires after 15 minutes
await client.resendVerificationCode(email)   // always resolves, whether or not the email is registered/already verified

// API keys — accepts a JWT or an API key
await client.createApiKey(name, permissions)  // permissions optional; omit (or ["*"]) for full access
await client.listApiKeys()
await client.getApiKey(id)                    // own key, or (for an admin) any key in the system
await client.revokeApiKey(id)
await client.deleteApiKeyPermanently(id)      // unlike revoke, the record itself is gone, not just disabled

// API keys: admin only, and reaches any key in the system, not just the
// caller's own — e.g. to dial back a leaked or over-broad key without
// revoking it. "*" grants everything; [] is a full lockdown short of
// revoking the key. Takes effect on that key's very next request.
await client.updateApiKeyPermissions(id, permissions)

// Admin: registration domain whitelist — accepts a JWT or an API key, resolved account must be an admin
await client.listDomains()
await client.addDomain(domain)
await client.removeDomain(domain)

// Admin: user accounts — same auth as above
await client.listUsers()                          // never includes password_hash or verification_code_hash
await client.setUserEmailVerified(id, true)        // admin override, either direction — no code needed/consumed
await client.deleteUser(id)                        // permanent; cascades to the user's own refresh tokens and API keys

// Bulk table import — admin only. Creates the schema (default "public")
// and/or table automatically (types inferred from the data, plus an auto
// `id` primary key) if either doesn't already exist; inserts into it if
// it does. schema can't be "kernel" or "pipelines" — those hold real app data.
await client.importTable(table, file, { schema, filename, format })  // file: a File/Blob

// File processing — admin only. Response shape is defined by the
// processor itself (e.g. "test" returns { columns, rowCount, ... },
// "stock" returns { rows, symbols, minPrice, maxPrice, avgPrice, ... }).
await client.processFile('test', file)                 // file: a File/Blob
await client.processFile('stock', file, { filename: 'prices.csv' })

// Saved queries: define/manage — admin only
await client.listQueries()
await client.getQuery(name)
await client.createQuery(name, sql)   // sql must start with SELECT or WITH; params in it as {{name}} (e.g. {{emailPattern}})
await client.updateQuery(name, sql)   // full replace; 404s if it doesn't exist yet
await client.removeQuery(name)

// Saved queries: run — any authenticated user, NOT admin-only
await client.runQuery(name, params)  // always executes read-only server-side, regardless of the query's SQL

// WebSocket publications — any authenticated user can subscribe; only an
// admin (or a publish:write API key) can publish
const handle = await client.subscribe('my_channel', (data, raw) => {
  console.log('received', data, 'at', raw.publishedAt);
});
// ... later, when done:
handle.close();

await client.publish('my_channel', { anything: 'JSON-serializable' })  // { channel, delivered }

// Misc
await client.health()       // no auth — liveness only
await client.healthReady()  // no auth — also confirms the server can reach Postgres
await client.ping()         // JWT or API key

Errors throw ApiError (also exported), with .status and a .message built from the server's { error, details } response shape.

CORS

The server must allow the notebook's origin. CORS_ORIGINS defaults to * (see the root README), which is sufficient for this to work out of the box against a fresh deploy; tighten it to specific origins (https://observablehq.com, your published notebook's domain, etc.) if you lock that down later.

Credentials in a public notebook

Don't hardcode a real password or API key into a notebook you plan to publish or share — anyone who opens it can read the cell source. Use a secret or a viewof input the viewer fills in themselves, not a literal in your code.