@spheredata/sdk

The SPHERE client SDK — the single integration surface for the SPHERE metered AI backend. One client for the web portal, the Electron desktop app, and the CLI; surfaces differ only in where the token is stored and which tools run locally.

The product/brand is SPHERE — this package is published under the @spheredata npm scope.

Install

npm i @spheredata/sdk

Quick start

import { createSphere } from "@spheredata/sdk";

const sphere = createSphere({ portal: "adrc" }); // web: sessionStorage by default

await sphere.signIn({ email, password });
const res = await sphere.streamAgent({ messages, tools }); // SSE Response, one turn/call
const balance = await sphere.getBalance();

The portal slug is sent as ?portal=<slug> on every metered request so the backend applies that client's config (model, margin) and tags usage.

createSphere(options)

| Option | Default | Purpose | | --- | --- | --- | | portal | "adrc" | Attribution slug; sets server-side config + usage tag. | | tokenStore | sessionStorage (else in-memory) | Sync string KV { get, set, clear }. Inject safeStorage (desktop) or a file store (CLI). | | onAuthInvalid | no-op | Called on any hard auth failure (store is cleared) — drop to a login screen. | | fetch | globalThis.fetch | Override the fetch implementation. | | apiBase, appId | SPHERE defaults | Point at a different backend / app. |

Token store contract: operations must be synchronous and atomic — single-flight refresh relies on the rotated bundle being persisted before the next read. The SDK refreshes transparently (proactive near-expiry, retry-once-on-401).

Client methods

createSphere() returns:

• Auth: signUp, signIn, signOut, oauthUrl, isSignedIn()
• Agent: ask, streamAgent(payload, signal) → Response (SSE, one model turn per call)
• Account / wallet: getAccount, getBalance, listCredits, buyCredits, redeem
• Metering: charge({ bytes, op, tag }) — pre-charge before a data op; returns { ok:false, insufficient:true, ... } on a 402 (an expected business outcome, not thrown). When charging is gated off server-side, returns { ok:true, charged:false, cost_usd:0 }.
• Identity: portal, appId, apiBase

A ready-made default instance for the ADRC portal is also exported:

import { sphere } from "@spheredata/sdk";

Pairs with

@spheredata/embed — the <sphere-agent> web component. Pass the client in via el.sphere = sphere.

License

MIT