@spheredata/sdk 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Josh Zhang, Zihuai He
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,71 @@
+# @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
+
+```sh
+npm i @spheredata/sdk
+```
+
+## Quick start
+
+```js
+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:
+
+```js
+import { sphere } from "@spheredata/sdk";
+```
+
+## Pairs with
+
+[`@spheredata/embed`](https://www.npmjs.com/package/@spheredata/embed) — the
+`<sphere-agent>` web component. Pass the client in via `el.sphere = sphere`.
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "@spheredata/sdk",
+  "version": "0.0.1",
+  "publishConfig": { "access": "public" },
+  "description": "SPHERE client SDK — talks to the SPHERE backend (auth, metered agent, account).",
+  "keywords": ["sphere", "spheredata", "sdk", "ai", "agent", "metering", "wallet", "synthetic-data"],
+  "homepage": "https://github.com/statzihuai/sphere-app-dev/tree/main/packages/sdk#readme",
+  "repository": { "type": "git", "url": "git+https://github.com/statzihuai/sphere-app-dev.git", "directory": "packages/sdk" },
+  "contributors": ["Josh Zhang", "Zihuai He"],
+  "type": "module",
+  "main": "sphere-client.js",
+  "module": "sphere-client.js",
+  "exports": { ".": "./sphere-client.js" },
+  "scripts": {
+    "test": "node --test"
+  },
+  "files": ["sphere-client.js"],
+  "license": "MIT"
+}

package/sphere-client.js

@@ -0,0 +1,332 @@
+// SPHERE client SDK — the single integration surface every surface drops in.
+//
+// One client for the web portal, the Electron desktop app, and the CLI. Each
+// integrates identically; surfaces differ only in *where the token is stored*
+// (inject `tokenStore`) and *which tools run locally*:
+//
+//   import { createSphere } from "@spheredata/sdk";
+//   const sphere = createSphere({ portal: "adrc" });                 // web (sessionStorage)
+//   createSphere({ portal: "desktop", tokenStore: safeStorageAdapter });
+//   createSphere({ portal: "cli", tokenStore: fileAdapter });
+//
+// 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.
+//
+// Auth model (Butterbase native): login/refresh return
+//   { access_token, refresh_token, expires_in, user }
+// access_token ~1h, refresh_token rotating. The SDK persists the full bundle via
+// the injected `tokenStore` and refreshes transparently (single-flight, proactive
+// near-expiry, retry-once on 401). On ANY hard auth failure it clears the store
+// and calls `onAuthInvalid` so the surface can drop to a login screen.
+
+const DEFAULTS = {
+  apiBase: "https://api.butterbase.ai",
+  appId: "app_wvujnt4zpp55",
+  portal: "adrc",
+};
+
+// Refresh this many ms BEFORE the access token's expiry, to avoid a guaranteed
+// 401 mid-call (and, for streams, mid-body where we cannot retry).
+const REFRESH_SKEW_MS = 60_000;
+
+// A token store is a tiny string KV: { get(): string|null, set(v: string), clear() }.
+// CONTRACT: its operations MUST be synchronous and atomic — single-flight refresh
+// relies on a rotated bundle being persisted before the next read. Sync adapters
+// are always feasible: Electron `safeStorage` is synchronous, and a CLI file store
+// can use `readFileSync`/`writeFileSync`. The SDK serializes the full bundle to/from
+// JSON, so stores stay dumb. Default: sessionStorage when present, else in-memory —
+// so importing the SDK in Node never throws.
+function defaultTokenStore(key) {
+  const ss = typeof globalThis !== "undefined" ? globalThis.sessionStorage : undefined;
+  if (ss && typeof ss.getItem === "function") {
+    return {
+      get: () => ss.getItem(key),
+      set: (v) => ss.setItem(key, v),
+      clear: () => ss.removeItem(key),
+    };
+  }
+  let mem = null;
+  return {
+    get: () => mem,
+    set: (v) => { mem = v; },
+    clear: () => { mem = null; },
+  };
+}
+
+export function createSphere(opts = {}) {
+  const { apiBase, appId, portal } = { ...DEFAULTS, ...opts };
+  const doFetch = opts.fetch || globalThis.fetch;
+  const onAuthInvalid = typeof opts.onAuthInvalid === "function" ? opts.onAuthInvalid : () => {};
+
+  const authBase = `${apiBase}/auth/${appId}`;
+  const fnBase = `${apiBase}/v1/${appId}/fn`;
+  const billingBase = `${apiBase}/v1/${appId}/billing`;
+  const q = `?portal=${encodeURIComponent(portal)}`;
+  const TOKEN_KEY = `sphere_token:${portal}`;
+
+  const tokenStore = opts.tokenStore || defaultTokenStore(TOKEN_KEY);
+
+  // --- bundle persistence ---------------------------------------------------
+  // Stored shape: { access_token, refresh_token, expires_at, user }.
+  function loadBundle() {
+    const raw = tokenStore.get();
+    if (!raw) return null;
+    if (typeof raw === "object") return raw; // tolerate a bundle-aware store (null excluded above)
+    try { return JSON.parse(raw); } catch { return null; }
+  }
+  function saveBundle(b) {
+    tokenStore.set(JSON.stringify(b)); // may throw (e.g. locked keychain) — callers route to hardFail
+  }
+  function bundleFromAuthResponse(data) {
+    const ttlSec = Number(data.expires_in);
+    const ttl = Number.isFinite(ttlSec) && ttlSec > 0 ? ttlSec : 3600; // seconds; ~1h fallback
+    return {
+      access_token: data.access_token,
+      refresh_token: data.refresh_token ?? null,
+      expires_at: Date.now() + ttl * 1000,
+      user: data.user ?? null,
+    };
+  }
+
+  // Any unrecoverable auth failure converges here: clear the store and signal the
+  // surface, then throw. clear() and onAuthInvalid() are each guarded so neither
+  // can suppress the other or the throw.
+  function hardFail(message) {
+    try { tokenStore.clear(); } catch { /* store may be unavailable; still signal */ }
+    try { onAuthInvalid(); } catch { /* surface callback must not mask the failure */ }
+    throw new Error(message);
+  }
+
+  // --- auth -----------------------------------------------------------------
+  async function signUp(email, password, displayName) {
+    const r = await doFetch(`${authBase}/signup`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ email, password, display_name: displayName }),
+    });
+    if (!r.ok) throw new Error(`signup failed: ${r.status}`); // don't echo the body (may reflect input)
+    return r.json();
+  }
+
+  async function signIn(email, password) {
+    const r = await doFetch(`${authBase}/login`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ email, password }),
+    });
+    if (!r.ok) throw new Error(`login failed: ${r.status}`);
+    const data = await r.json();
+    saveBundle(bundleFromAuthResponse(data));
+    return data.user;
+  }
+
+  // Single-flight refresh: concurrent callers share one in-flight promise so two
+  // 401s don't both rotate the refresh token and invalidate each other.
+  let refreshing = null;
+  async function refresh() {
+    if (refreshing) return refreshing;
+    refreshing = (async () => {
+      const b = loadBundle();
+      if (!b?.refresh_token) hardFail("session expired");
+      const r = await doFetch(`${authBase}/refresh`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ refresh_token: b.refresh_token }),
+      });
+      if (!r.ok) hardFail(`refresh failed: ${r.status}`);
+      const data = await r.json();
+      try {
+        saveBundle(bundleFromAuthResponse(data)); // persist the ROTATED pair
+      } catch {
+        // Rotation succeeded server-side but we can't persist it — the old refresh
+        // token is now consumed. Fail hard so the surface re-auths instead of
+        // silently replaying a dead token.
+        hardFail("token persist failed");
+      }
+      return data.access_token;
+    })();
+    try {
+      return await refreshing;
+    } finally {
+      refreshing = null;
+    }
+  }
+
+  // Return a valid access token, proactively refreshing within the skew window.
+  // - no session at all            -> throw "not signed in"
+  // - expired/near-expiry, can refresh -> refresh()
+  // - expired/near-expiry, cannot     -> hardFail (clear + signal)
+  // A missing expires_at is treated as expired (never "immortal").
+  async function validAccessToken() {
+    const b = loadBundle();
+    if (!b?.access_token) throw new Error("not signed in");
+    const stale = !b.expires_at || Date.now() > b.expires_at - REFRESH_SKEW_MS;
+    if (stale) {
+      if (b.refresh_token) return refresh();
+      hardFail("session expired");
+    }
+    return b.access_token;
+  }
+
+  // Authenticated fetch with retry-once-on-401. NOT for streams (see streamAgent).
+  async function authedFetch(url, init = {}) {
+    const token = await validAccessToken();
+    const withAuth = (t) => ({
+      ...init,
+      headers: { ...(init.headers || {}), Authorization: `Bearer ${t}` },
+    });
+    let r = await doFetch(url, withAuth(token));
+    if (r.status === 401) {
+      if (!loadBundle()?.refresh_token) hardFail("session expired");
+      const fresh = await refresh(); // throws + signals on hard failure
+      r = await doFetch(url, withAuth(fresh));
+    }
+    return r;
+  }
+
+  async function signOut() {
+    const b = loadBundle();
+    // Best-effort server-side revoke of the refresh token (network only in the try).
+    if (b?.access_token) {
+      try {
+        await doFetch(`${authBase}/logout`, {
+          method: "POST",
+          headers: { Authorization: `Bearer ${b.access_token}` },
+        });
+      } catch { /* ignore network/HTTP errors on logout */ }
+    }
+    tokenStore.clear();
+  }
+
+  // Build the hosted OAuth start URL; the surface opens it (web redirect or
+  // desktop/CLI loopback) and captures the returned tokens. `redirectTo` must be
+  // an absolute http(s) URL — reject other schemes (javascript:, data:, relative)
+  // to avoid handing the auth flow somewhere unintended. Host allow-listing is the
+  // backend's responsibility.
+  function oauthUrl(provider, redirectTo) {
+    const base = `${authBase}/oauth/${encodeURIComponent(provider)}`;
+    if (!redirectTo) return base;
+    let u;
+    try { u = new URL(redirectTo); } catch { throw new Error("oauthUrl: redirectTo must be an absolute URL"); }
+    if (u.protocol !== "http:" && u.protocol !== "https:") throw new Error("oauthUrl: redirectTo must be http(s)");
+    return `${base}?redirect_to=${encodeURIComponent(redirectTo)}`;
+  }
+
+  // --- AI -------------------------------------------------------------------
+  // Ask the model through SPHERE. Metered to the user's wallet under this portal.
+  async function ask(messages, { model, max_tokens } = {}) {
+    const r = await authedFetch(`${fnBase}/messages${q}`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        messages,
+        ...(model ? { model } : {}),
+        ...(max_tokens != null ? { max_tokens } : {}),
+      }),
+    });
+    const data = await r.json();
+    if (!r.ok) throw new Error(data?.error || `message failed: ${r.status}`);
+    return data; // { message, model, portal, usage, cost_usd, balance_usd }
+  }
+
+  // Open a streaming agent turn. Returns the raw Response (text/event-stream):
+  // OpenAI chat.completion.chunk lines + a trailing
+  // `data: {"sphere":{balance_usd,cost_usd,usage,portal}}` event. One model turn
+  // per call; the caller runs the tool loop, feeding tool results back.
+  //
+  // Pre-flight refresh + retry-once ONLY on the initial response status (body not
+  // yet read — safe to re-open). We never retry once the body is being consumed.
+  async function streamAgent(payload, signal) {
+    const open = (t) => doFetch(`${fnBase}/agent${q}`, {
+      method: "POST",
+      signal,
+      headers: { "Content-Type": "application/json", Authorization: `Bearer ${t}` },
+      body: JSON.stringify(payload),
+    });
+    let r = await open(await validAccessToken());
+    if (r.status === 401) {
+      if (!loadBundle()?.refresh_token) hardFail("session expired");
+      r = await open(await refresh());
+    }
+    return r;
+  }
+
+  // --- account / wallet -----------------------------------------------------
+  async function getAccount() {
+    const r = await authedFetch(`${fnBase}/account${q}`, {});
+    if (!r.ok) throw new Error(`account failed: ${r.status}`);
+    return r.json(); // { user, portal, wallet, recent_usage }
+  }
+
+  async function getBalance() {
+    const r = await authedFetch(`${fnBase}/balance`, {});
+    if (!r.ok) throw new Error(`balance failed: ${r.status}`);
+    return r.json();
+  }
+
+  // --- billing (credit purchase) --------------------------------------------
+  // NOTE: backend shapes are pending the Slice-1 billing spike; these wrappers
+  // follow the documented Butterbase Stripe Connect / SPHERE redeem contract.
+  async function listCredits() {
+    const r = await authedFetch(`${billingBase}/products`, {});
+    if (!r.ok) throw new Error(`listCredits failed: ${r.status}`);
+    return r.json(); // [{ productId, name, credit_usd, priceCents }]
+  }
+
+  async function buyCredits(productId, { successUrl, cancelUrl } = {}) {
+    const r = await authedFetch(`${billingBase}/purchase`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ productId, ...(successUrl ? { successUrl } : {}), ...(cancelUrl ? { cancelUrl } : {}) }),
+    });
+    const data = await r.json();
+    if (!r.ok) throw new Error(data?.error || `buyCredits failed: ${r.status}`);
+    return data; // { url, orderId }
+  }
+
+  async function redeem(orderId) {
+    const r = await authedFetch(`${fnBase}/redeem`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ orderId }),
+    });
+    const data = await r.json();
+    if (!r.ok) throw new Error(data?.error || `redeem failed: ${r.status}`);
+    return data; // { balance_usd }
+  }
+
+  // --- data-op metering -----------------------------------------------------
+  // Charge a local data operation (generate/evaluate/certify) by input dataset
+  // bytes, debited from the wallet under this portal/tag. Pricing is server-side.
+  // PRE-CHARGE: call this BEFORE running the op; if `ok` is false (insufficient
+  // credits) do NOT run it. A 402 is an expected business outcome (not thrown);
+  // other failures throw. When charging is gated off server-side, returns
+  // { ok:true, charged:false, cost_usd:0 } and never blocks.
+  async function charge({ bytes, op, tag } = {}) {
+    const r = await authedFetch(`${fnBase}/charge${q}`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ bytes, op, ...(tag ? { tag } : {}) }),
+    });
+    const data = await r.json().catch(() => ({}));
+    if (r.status === 402) {
+      return { ok: false, insufficient: true, ...data }; // { cost_usd, balance_usd, ... }
+    }
+    if (!r.ok) throw new Error(data?.error || `charge failed: ${r.status}`);
+    return data; // { ok:true, charged, op, bytes, cost_usd, balance_usd }
+  }
+
+  return {
+    portal, appId, apiBase,
+    signUp, signIn, signOut, oauthUrl,
+    ask, streamAgent,
+    getAccount, getBalance,
+    listCredits, buyCredits, redeem, charge,
+    // NOTE: reflects token PRESENCE, not validity — a present-but-expired token
+    // returns true here and is refreshed lazily on the next call.
+    isSignedIn: () => !!loadBundle()?.access_token,
+  };
+}
+
+// Default instance for the ADRC portal (safe to construct in any environment).
+export const sphere = createSphere();