@sovaria/sdk 0.0.0-stage → 0.5.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sovaria
+
+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

@@ -1,3 +1,249 @@
-# Temporary Holding Version
+# Sovaria TypeScript SDK
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+TypeScript SDK for Sovaria gateway APIs.
+
+## Install
+
+```bash
+npm install @sovaria/sdk
+```
+
+Works in browsers, React Native and Node 18+ (realtime in Node needs Node 22+ or a global `WebSocket`).
+Docs: <https://sovaria.in/docs/javascript-setup> · Reference: <https://sovaria.in/docs/javascript-reference>
+
+For local workspace development:
+
+```bash
+npm install
+npm run --workspace @sovaria/sdk build
+```
+
+## Quick Start (an app)
+
+Copy the project URL and anon key from the console's **Connect** panel:
+
+```ts
+import { createClient } from '@sovaria/sdk'
+
+const sov = createClient('https://<ref>.sovarias.in', '<anon-key>')
+
+await sov.auth.signIn('reader@example.com', 'password')   // session is saved in localStorage
+const { rows } = await sov.data.sql('select id, title from books order by title')
+```
+
+Or link the folder with the CLI (`sov link`) and build the client from `sovaria.config.json`:
+
+```ts
+import config from './sovaria.config.json'
+import { createClientFromProjectConfig } from '@sovaria/sdk'
+
+const sov = createClientFromProjectConfig(config, { publishableKey: import.meta.env.VITE_SOVARIA_ANON_KEY })
+```
+
+### Your Postgres functions
+
+`data.rpc` calls a database function over `POST /rest/v1/rpc/{name}` with the arguments by name. A function
+that returns one value resolves to it; one that returns rows resolves to an array. App users need an access
+policy that allows `fn:<name>`.
+
+```ts
+const count = await sov.data.rpc<number>('post_count', { u: userId })
+await sov.data.rpc('transfer_points', { from_user: a, to_user: b, amount: 50 })
+
+// Read-only functions over GET, with PostgREST parameters for functions that return rows
+const top = await sov.data.rpc('top_posts', { days: 7 }, { get: true, query: { select: 'id,title', limit: 10 } })
+```
+
+### Sessions
+
+In a browser the signed-in session is kept across reloads (`persistSession: false` turns it off;
+`{ storage, key }` stores it elsewhere). Expired access tokens are refreshed automatically; when the
+refresh token is revoked the user is signed out.
+
+```ts
+const stop = sov.auth.onAuthStateChange((event, session) => {
+  // INITIAL_SESSION | SIGNED_IN | TOKEN_REFRESHED | SIGNED_OUT
+})
+sov.auth.getSession()   // { access_token, refresh_token?, expires_at } | null
+await sov.auth.signOut()
+```
+
+### Passkeys
+
+Users add a passkey after signing in, then sign in with it (Face ID, Touch ID, Windows Hello, a security
+key). Set the project up under **Users › Passkeys** first.
+
+```ts
+if (sov.auth.passkeys.isSupported()) {
+  await sov.auth.passkeys.register('MacBook')         // signed in: the browser creates the passkey
+}
+const tokens = await sov.auth.passkeys.signIn()        // later: no email or password needed
+tokens.aal                                             // 'aal2' when the device checked the user
+await sov.auth.passkeys.list()                         // and .remove(id)
+```
+
+`startRegistration` / `finishRegistration` and `startSignIn` / `finishSignIn` take and return WebAuthn JSON
+for environments with their own WebAuthn API (React Native, an embedded browser).
+
+### Errors you can show to users
+
+Every failed call throws `SovariaError`. Its `message` is written for end users ("You don't have
+permission to do that.") and never contains policy names, SQL or table names. Branch on `code`;
+the server's own text is in `technicalMessage` / `detail` for logs.
+
+```ts
+import { SovariaError, userMessageFor } from '@sovaria/sdk'
+
+try { await sov.data.sql('delete from reviews where id = $1', [id]) }
+catch (e) {
+  if (e instanceof SovariaError && e.code === 'UNAUTHENTICATED') goToSignIn()
+  toast(userMessageFor(e))
+  console.debug(e instanceof SovariaError ? e.technicalMessage : e)
+}
+```
+
+Codes: `NETWORK_ERROR`, `UNAUTHENTICATED`, `PERMISSION_DENIED`, `NOT_FOUND`, `CONFLICT`,
+`INVALID_INPUT`, `PAYLOAD_TOO_LARGE`, `RATE_LIMITED`, `PLAN_LIMIT_REACHED`, `PLAN_FEATURE_REQUIRED`,
+`PLAN_QUOTA_EXHAUSTED`, `SERVICE_UNAVAILABLE`, `SERVER_ERROR`, `BAD_REQUEST`, `CONFIG_ERROR`.
+
+### Realtime
+
+```ts
+const ch = sov.realtime.channel('book:42', {
+  onMessage: (payload) => render(payload),
+  onStatus: (s) => setStatus(s),          // connecting | live | reconnecting | closed
+  onGap: () => reload(),                  // missed messages that couldn't be recovered
+})
+await ch.send({ type: 'review', rating: 5 })
+ch.close()
+```
+
+After a reconnect the channel first delivers what was published while it was offline (from the channel's
+replay history, in order, each message once), then live messages. `catchUp: false` turns that off.
+
+## Local development (`sov start`)
+
+`sov start` runs the Sovaria stack on your machine (Docker) and writes `.env.local` with the URL and the well-known local keys, which work only against that stack. Guide: <https://sovaria.in/docs/local-development>.
+
+```ts
+// .env.local: VITE_SOVARIA_URL=http://localhost:54321, VITE_SOVARIA_ANON_KEY=svr_local_anon_5a0f1c8e2b7d4e6f9a3c1b5d7e9f0a2c
+const sov = createClient(import.meta.env.VITE_SOVARIA_URL, import.meta.env.VITE_SOVARIA_ANON_KEY)
+```
+
+Plain `http://localhost:54321` is the local project; `http://<ref>.localhost:54321` names it explicitly. Only the two variables change between the local stack and the cloud.
+
+## Quick Start (operators and scripts)
+
+```ts
+import { SovariaSDK } from '@sovaria/sdk'
+
+const sdk = new SovariaSDK({ baseUrl: 'https://api.sovaria.in' })
+await sdk.auth.consoleLogin('you@example.com', 'password')
+sdk.setScope({ orgId: '<org-uuid>', projectId: '<project-uuid>' })
+console.log(await sdk.system.enginesHealth())
+```
+
+## Supabase-Style Bootstrap (Portal Config)
+
+```ts
+import { createClient } from '@sovaria/sdk'
+
+const sdk = createClient({
+  url: 'https://api.sovaria.in',
+  orgId: '11111111-1111-1111-1111-111111111111',
+  projectId: '22222222-2222-2222-2222-222222222222',
+  envId: '33333333-3333-3333-3333-333333333333',
+  publishableKey: '<token>',
+})
+```
+
+Or bootstrap from environment variables:
+
+```ts
+const sdk = SovariaSDK.fromEnv(process.env)
+```
+
+Supported environment variables:
+- `SOVARIA_URL` (also `NEXT_PUBLIC_SOVARIA_URL`, `VITE_SOVARIA_URL`)
+- `SOVARIA_ORG_ID`
+- `SOVARIA_PROJECT_ID`
+- `SOVARIA_ENV_ID`
+- `SOVARIA_ACCESS_TOKEN` or `SOVARIA_PUBLISHABLE_KEY` or `SOVARIA_ANON_KEY`
+
+## AI: knowledge bases (RAG) and agents
+
+Put documents in a knowledge base on your project's own Postgres and search them with citations; only
+passages the signed-in user may read come back.
+
+```ts
+await sov.knowledge.addFile('support_docs', file)              // PDF, DOCX, HTML, Markdown, TXT, CSV, JSON
+await sov.knowledge.addUrl('support_docs', 'https://example.com/faq')
+const { results, citations } = await sov.knowledge.search('support_docs', 'refund window', { k: 5 })
+```
+
+Talk to your project's agents from the app (an agent the team opened to app users). The answer streams;
+pass `threadId` to continue the conversation.
+
+```ts
+const reply = await sov.agents.run(agentId, { message: 'Where is my order?', onEvent: (e) => render(e) })
+await sov.agents.run(agentId, { message: 'And the invoice?', threadId: reply.threadId })
+for await (const event of sov.agents.stream(agentId, { message: 'Summarise my plan' })) { /* text_delta, tool_call, done */ }
+```
+
+Managing knowledge bases and the embedding model (your own OpenAI/Gemini/compatible key, or Sovaria's):
+`sov.api.knowledge.*` and `sov.api.embeddings.*` (`getSettings`, `setSettings`, `usage` in tokens and dollars).
+
+## Auth lanes
+
+| Method | Path | Lane | Session KEK |
+| --- | --- | --- | --- |
+| `auth.login` (**deprecated**) | `/auth/console/login` unscoped, `/auth/project/login` when scoped | compatibility | derived when `argon2_salt` + password |
+| `auth.consoleLogin` / `auth.loginConsole` | `/auth/console/login` | console operator | derived when salt present |
+| `auth.projectLogin` / `auth.loginProduct` | `/auth/project/login` | product user | derived when salt present |
+| `auth.register` | `/auth/register` | depends on scope | derived when tokens + salt returned |
+| `auth.verifyOtp` / `auth.verifyMagicLink` / `auth.oauthHandoff` | passwordless | product/console | **not** derived unless you pass `password` |
+| `auth.listUsers` (**deprecated**) | warns; product-users paths | n/a | n/a |
+| `auth.consoleMembers.list` | `/org/{orgId}/members` | console member admin | n/a |
+| `auth.listConsoleProductUsers` | `/auth/product-users` | console operator | n/a |
+| `auth.productUsers.list` | `/projects/{id}/auth/users` | project admin + `setScope` | n/a |
+
+`auth.logout(refreshToken?)` defaults to the stored refresh token, sends Bearer,
+and always clears tokens/KEK (even when HTTP logout fails). Default
+`onTokenRefresh` omits `refresh_token`; use `onTokenRefreshSensitive` only if you
+must persist it.
+
+Refresh has two supported modes. Do not mix them:
+
+- **SDK / CLI:** JSON body `{"refresh_token": "..."}`.
+- **Console / browser:** empty JSON body plus the HttpOnly refresh cookie.
+
+E2EE (`hash-wasm` 4.12.0, pinned) needs CSP `wasm-unsafe-eval` in browsers.
+
+## Coverage
+
+- Axis: auth, context, graph
+- Atlas-Doc: doc put/get/delete/scan
+- Atlas-Rel: SQL + table lifecycle
+- Pulse: stream + e2ee + websocket URL helper
+- Guard: policies
+- Echo: audit + simulation
+- Chrono: timeline/snapshot/variance APIs
+- Gateway: engines health
+
+## Escape Hatch
+
+```ts
+await sdk.request('GET', '/api/v1/system/engines/health', { requiresAuth: false })
+```
+
+## Functions + Storage Pass-Through
+
+```ts
+// Forge
+const deployStatus = await sdk.functions.status('deploy-123')
+
+// Vault
+await sdk.storage.putJson('kv/app/settings', { theme: 'light' })
+const settings = await sdk.storage.get('kv/app/settings')
+await sdk.storage.delete('kv/app/settings')
+```

package/dist/analytics.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Product analytics: events from your app, stored next to your project and queryable in the console
+ * (Analytics), the CLI (`sov analytics`) and Sovariq.
+ *
+ * ```ts
+ * sov.analytics.track('purchase', { amount: 20, plan: 'pro' })
+ * sov.analytics.screen('Checkout')
+ * sov.analytics.identify({ plan: 'pro', team_size: 4 })     // user properties
+ * await sov.analytics.setEnabled(false)                       // the user opted out (stops collection everywhere)
+ * ```
+ *
+ * Events are queued (persisted when you pass a storage), sent in batches every 10 seconds or 20 events, and
+ * kept while offline. The signed-in user comes from the request's token on the server — never from the event.
+ * A new session (and `$session_start`) begins after 30 minutes without events; the first event of a run sends
+ * `$app_open`. Properties are flat scalars; emails, secret-looking keys and long digit runs are dropped server-side.
+ */
+import type { OfflineStorage } from './offline.js';
+export type AnalyticsProps = Record<string, string | number | boolean | null>;
+export interface AnalyticsEvent {
+    name: string;
+    ts: string;
+    props?: AnalyticsProps;
+    user_props?: AnalyticsProps;
+    session_id?: string;
+}
+export interface AnalyticsOptions {
+    /** Where the queue, device id and opt-out survive restarts (indexedDbStorage(), keyValueStorage(AsyncStorage)…). */
+    storage?: OfflineStorage;
+    flushIntervalMs?: number;
+    batchSize?: number;
+    /** `$session_start` / `$app_open` events (default true). */
+    autoSessions?: boolean;
+    appVersion?: string;
+    platform?: string;
+    /** Start disabled until the user agrees (for consent-first apps). */
+    enabled?: boolean;
+    maxQueue?: number;
+}
+type Send = (body: {
+    events: AnalyticsEvent[];
+    context: Record<string, unknown>;
+}) => Promise<unknown>;
+type Consent = (granted: boolean, anonId: string, erase: boolean) => Promise<unknown>;
+export declare class Analytics {
+    private readonly send;
+    private readonly consent;
+    private options;
+    private queue;
+    private timer?;
+    private sessionId;
+    private lastEventAt;
+    private opened;
+    private enabled;
+    private deviceId;
+    private loaded?;
+    private minute;
+    private sentThisMinute;
+    private sending;
+    constructor(send: Send, consent: Consent);
+    /** Optional: persistence, intervals, app version. Call before the first `track` to restore a saved queue. */
+    configure(options: AnalyticsOptions): void;
+    /** The device id sent as `anon_id` (stable per install when a storage is configured). */
+    get anonId(): string;
+    private restore;
+    private persist;
+    /** Record an event. Returns false when it was dropped (disabled, bad name, or over 300 a minute). */
+    track(name: string, props?: AnalyticsProps): boolean;
+    /** Record a screen or page view (`$screen`). */
+    screen(name: string, props?: AnalyticsProps): boolean;
+    /** Set user properties (`$identify`); merged with what the user already has. */
+    identify(userProps: AnalyticsProps): boolean;
+    /** One `$exposure` per experiment and session (the remote config client calls this). */
+    private exposed;
+    trackExposure(experiment: string, variant: string): void;
+    private push;
+    private schedule;
+    /** Send everything queued now (also on page hide / app background). Network errors keep the events. */
+    flush(): Promise<void>;
+    /**
+     * Turn collection on or off for this user (DPDP / GDPR consent). Off also tells the server, so the user's
+     * events are dropped on every device; `erase` deletes what was already stored.
+     */
+    setEnabled(enabled: boolean, opts?: {
+        erase?: boolean;
+    }): Promise<void>;
+    isEnabled(): boolean;
+    /** Forget the device id and session (on sign-out); the next event starts a new anonymous identity. */
+    reset(): Promise<void>;
+    /** Events waiting to be sent. */
+    pending(): number;
+}
+export {};

package/dist/analytics.js

@@ -0,0 +1,236 @@
+/**
+ * Product analytics: events from your app, stored next to your project and queryable in the console
+ * (Analytics), the CLI (`sov analytics`) and Sovariq.
+ *
+ * ```ts
+ * sov.analytics.track('purchase', { amount: 20, plan: 'pro' })
+ * sov.analytics.screen('Checkout')
+ * sov.analytics.identify({ plan: 'pro', team_size: 4 })     // user properties
+ * await sov.analytics.setEnabled(false)                       // the user opted out (stops collection everywhere)
+ * ```
+ *
+ * Events are queued (persisted when you pass a storage), sent in batches every 10 seconds or 20 events, and
+ * kept while offline. The signed-in user comes from the request's token on the server — never from the event.
+ * A new session (and `$session_start`) begins after 30 minutes without events; the first event of a run sends
+ * `$app_open`. Properties are flat scalars; emails, secret-looking keys and long digit runs are dropped server-side.
+ */
+const SESSION_GAP_MS = 30 * 60 * 1000;
+const KEY_QUEUE = 'sovaria.analytics.queue';
+const KEY_DEVICE = 'sovaria.analytics.device';
+const KEY_OPTOUT = 'sovaria.analytics.optout';
+const MAX_PER_MINUTE = 300;
+function randomId() {
+    const c = globalThis.crypto;
+    if (c?.randomUUID)
+        return c.randomUUID();
+    return 'd' + Math.random().toString(36).slice(2) + Date.now().toString(36);
+}
+function detectPlatform() {
+    const g = globalThis;
+    if (g.navigator?.product === 'ReactNative')
+        return 'react-native';
+    if (typeof g.window !== 'undefined' && typeof g.document !== 'undefined')
+        return 'web';
+    if (g.process?.versions?.node)
+        return 'server';
+    return 'other';
+}
+export class Analytics {
+    send;
+    consent;
+    options = {};
+    queue = [];
+    timer;
+    sessionId = '';
+    lastEventAt = 0;
+    opened = false;
+    enabled = true;
+    deviceId = '';
+    loaded;
+    minute = 0;
+    sentThisMinute = 0;
+    sending = false;
+    constructor(send, consent) {
+        this.send = send;
+        this.consent = consent;
+    }
+    /** Optional: persistence, intervals, app version. Call before the first `track` to restore a saved queue. */
+    configure(options) {
+        this.options = { ...this.options, ...options };
+        if (options.enabled !== undefined)
+            this.enabled = options.enabled;
+        this.loaded = this.restore();
+    }
+    /** The device id sent as `anon_id` (stable per install when a storage is configured). */
+    get anonId() {
+        if (!this.deviceId)
+            this.deviceId = randomId();
+        return this.deviceId;
+    }
+    async restore() {
+        const s = this.options.storage;
+        if (!s)
+            return;
+        try {
+            const [q, d, o] = await Promise.all([s.get(KEY_QUEUE), s.get(KEY_DEVICE), s.get(KEY_OPTOUT)]);
+            if (d)
+                this.deviceId = d;
+            else
+                await s.set(KEY_DEVICE, this.anonId);
+            if (o === '1')
+                this.enabled = false;
+            if (q)
+                this.queue = [...JSON.parse(q), ...this.queue].slice(-(this.options.maxQueue ?? 1000));
+        }
+        catch {
+            /* storage is best effort */
+        }
+    }
+    async persist() {
+        try {
+            await this.options.storage?.set(KEY_QUEUE, JSON.stringify(this.queue));
+        }
+        catch {
+            /* best effort */
+        }
+    }
+    /** Record an event. Returns false when it was dropped (disabled, bad name, or over 300 a minute). */
+    track(name, props) {
+        if (!this.enabled || !name || name.length > 64)
+            return false;
+        return this.push({ name, props });
+    }
+    /** Record a screen or page view (`$screen`). */
+    screen(name, props) {
+        if (!this.enabled)
+            return false;
+        return this.push({ name: '$screen', props: { ...(props ?? {}), screen: String(name).slice(0, 200) } });
+    }
+    /** Set user properties (`$identify`); merged with what the user already has. */
+    identify(userProps) {
+        if (!this.enabled)
+            return false;
+        return this.push({ name: '$identify', user_props: userProps });
+    }
+    /** One `$exposure` per experiment and session (the remote config client calls this). */
+    exposed = new Set();
+    trackExposure(experiment, variant) {
+        const key = `${experiment}:${variant}`;
+        if (this.exposed.has(key) && Date.now() - this.lastEventAt <= SESSION_GAP_MS)
+            return;
+        this.exposed.add(key);
+        this.push({ name: '$exposure', props: { experiment, variant } });
+    }
+    push(event) {
+        const now = Date.now();
+        const minute = Math.floor(now / 60_000);
+        if (minute !== this.minute) {
+            this.minute = minute;
+            this.sentThisMinute = 0;
+        }
+        if (this.sentThisMinute >= MAX_PER_MINUTE)
+            return false;
+        this.sentThisMinute++;
+        if (!this.sessionId || now - this.lastEventAt > SESSION_GAP_MS) {
+            this.sessionId = randomId();
+            if (event.name !== '$exposure')
+                this.exposed.clear();
+            if (this.options.autoSessions !== false && !event.name.startsWith('$session')) {
+                this.queue.push({ name: '$session_start', ts: new Date(now).toISOString(), session_id: this.sessionId });
+                if (!this.opened) {
+                    this.opened = true;
+                    this.queue.push({ name: '$app_open', ts: new Date(now).toISOString(), session_id: this.sessionId });
+                }
+            }
+        }
+        this.lastEventAt = now;
+        this.queue.push({ ...event, ts: new Date(now).toISOString(), session_id: this.sessionId });
+        const max = this.options.maxQueue ?? 1000;
+        if (this.queue.length > max)
+            this.queue.splice(0, this.queue.length - max);
+        void this.persist();
+        if (this.queue.length >= (this.options.batchSize ?? 20))
+            void this.flush();
+        else
+            this.schedule();
+        return true;
+    }
+    schedule() {
+        if (this.timer)
+            return;
+        this.timer = setTimeout(() => {
+            this.timer = undefined;
+            void this.flush();
+        }, this.options.flushIntervalMs ?? 10_000);
+    }
+    /** Send everything queued now (also on page hide / app background). Network errors keep the events. */
+    async flush() {
+        await this.loaded;
+        if (this.timer) {
+            clearTimeout(this.timer);
+            this.timer = undefined;
+        }
+        if (this.sending || !this.enabled)
+            return;
+        this.sending = true;
+        try {
+            while (this.queue.length) {
+                const batch = this.queue.slice(0, 100);
+                try {
+                    await this.send({ events: batch, context: { anon_id: this.anonId, platform: this.options.platform ?? detectPlatform(),
+                            app_version: this.options.appVersion } });
+                }
+                catch (error) {
+                    const status = error.statusCode ?? 0;
+                    if (status === 0 || status === 429 || status >= 500) {
+                        this.schedule(); // offline or throttled: keep them and try later
+                        return;
+                    }
+                    // 4xx: the server refused this batch (bad data, disabled): drop it, never loop
+                }
+                this.queue.splice(0, batch.length);
+                await this.persist();
+            }
+        }
+        finally {
+            this.sending = false;
+        }
+    }
+    /**
+     * Turn collection on or off for this user (DPDP / GDPR consent). Off also tells the server, so the user's
+     * events are dropped on every device; `erase` deletes what was already stored.
+     */
+    async setEnabled(enabled, opts = {}) {
+        this.enabled = enabled;
+        if (!enabled) {
+            this.queue = [];
+            await this.persist();
+        }
+        try {
+            await this.options.storage?.set(KEY_OPTOUT, enabled ? '0' : '1');
+        }
+        catch {
+            /* best effort */
+        }
+        await this.consent(enabled, this.anonId, Boolean(opts.erase));
+    }
+    isEnabled() {
+        return this.enabled;
+    }
+    /** Forget the device id and session (on sign-out); the next event starts a new anonymous identity. */
+    async reset() {
+        this.deviceId = randomId();
+        this.sessionId = '';
+        this.exposed.clear();
+        try {
+            await this.options.storage?.set(KEY_DEVICE, this.deviceId);
+        }
+        catch {
+            /* best effort */
+        }
+    }
+    /** Events waiting to be sent. */
+    pending() {
+        return this.queue.length;
+    }
+}