@sovaria/sdk 0.0.0-stage → 0.4.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,180 @@
-# 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 })
+```
+
+### 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()
+```
+
+### 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
+})
+await ch.send({ type: 'review', rating: 5 })
+ch.close()
+```
+
+## 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`
+
+## 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/client.d.ts

@@ -0,0 +1,146 @@
+import type { Bucket, ColumnDefinition, DocumentGetResponse, DocumentPutResponse, DocumentScanResult, FunctionDeployResponse, FunctionInvokeResponse, NodeResponse, RealtimeCallback, RealtimeSubscription, SovariaClientOptions, StorageObject, TimelineJumpResponse, TimelineLogResponse, TokenResponse, UserProfile } from "./types.js";
+/**
+ * Async TypeScript client for the Sovaria API Gateway.
+ *
+ * @deprecated Use {@link SovariaSDK} from `./index`. This legacy client is retained
+ * for in-repo tests only and is not a public package export.
+ *
+ * All requests flow through the gateway; engines are never called directly.
+ * Token refresh is automatic and transparent.
+ *
+ * @example
+ * ```ts
+ * const sov = new SovariaClient("https://api.sovaria.in");
+ * await sov.auth.login("user@example.com", "password"); // deprecated; posts to /console/login
+ * sov.setContext("org-123", "proj-456");
+ *
+ * const rows = await sov.data.sql.query("SELECT * FROM users LIMIT 10");
+ * await sov.auth.logout();
+ * ```
+ */
+export declare class SovariaClient {
+    private readonly baseUrl;
+    private accessToken;
+    private refreshToken;
+    private expiresAt;
+    private orgId;
+    private projectId;
+    private envId;
+    private refreshPromise;
+    private onTokenRefresh?;
+    readonly auth: AuthModule;
+    readonly org: OrgModule;
+    readonly data: DataModule;
+    readonly storage: StorageModule;
+    readonly functions: FunctionsModule;
+    readonly realtime: RealtimeModule;
+    readonly chrono: ChronoModule;
+    constructor(baseUrl: string, options?: SovariaClientOptions);
+    /**
+     * Bind org/project context for multi-tenant headers.
+     * These are injected as `X-Sovaria-Org-ID` and `X-Sovaria-Project-ID`
+     * on every subsequent request.
+     */
+    setContext(orgId: string, projectId: string, envId?: string): void;
+    clearContext(): void;
+    /** @internal */
+    _setTokens(tokens: TokenResponse): void;
+    /** @internal */
+    _clearTokens(): void;
+    /** @internal */
+    get _refreshToken(): string | null;
+    /** @internal */
+    get _isAuthenticated(): boolean;
+    /**
+     * Execute an HTTP request with automatic auth injection, token refresh, and
+     * exponential back-off with jitter on transient failures.
+     *
+     * @internal
+     */
+    _request<T = unknown>(method: string, path: string, options?: {
+        body?: unknown;
+        params?: Record<string, string>;
+        requiresAuth?: boolean;
+        headers?: Record<string, string>;
+    }): Promise<T>;
+    private ensureTokenFresh;
+    private doRefresh;
+    /**
+     * Build a WebSocket URL from the base URL, converting http(s) to ws(s).
+     * @internal
+     */
+    _wsUrl(path: string): string;
+    /** @internal */
+    _issueRealtimeWsTicket(channel: string): Promise<string>;
+    /** @internal */
+    get _accessToken(): string | null;
+}
+declare class AuthModule {
+    private readonly client;
+    constructor(client: SovariaClient);
+    login(email: string, password: string): Promise<TokenResponse>;
+    register(email: string, password: string, name: string): Promise<TokenResponse>;
+    logout(): Promise<void>;
+    me(): Promise<UserProfile>;
+}
+declare class OrgModule {
+    private readonly client;
+    constructor(client: SovariaClient);
+    list(): Promise<NodeResponse[]>;
+    get(id: string): Promise<NodeResponse>;
+    create(type: string, name: string, metadata?: Record<string, unknown>): Promise<NodeResponse>;
+    children(id: string): Promise<NodeResponse[]>;
+}
+declare class SqlSubmodule {
+    private readonly client;
+    constructor(client: SovariaClient);
+    createTable(tableName: string, columns: ColumnDefinition[]): Promise<Record<string, unknown>>;
+    query(sql: string, params?: Record<string, unknown>): Promise<Record<string, unknown>[]>;
+    dropTable(name: string): Promise<Record<string, unknown>>;
+}
+declare class DocSubmodule {
+    private readonly client;
+    constructor(client: SovariaClient);
+    put(collection: string, key: string, data: Record<string, unknown>): Promise<DocumentPutResponse>;
+    get(collection: string, key: string): Promise<DocumentGetResponse>;
+    scan(collection: string, filter?: Record<string, unknown>): Promise<DocumentScanResult>;
+}
+declare class DataModule {
+    readonly sql: SqlSubmodule;
+    readonly doc: DocSubmodule;
+    constructor(client: SovariaClient);
+}
+declare class StorageModule {
+    private readonly client;
+    constructor(client: SovariaClient);
+    listBuckets(): Promise<Bucket[]>;
+    createBucket(name: string, isPublic?: boolean): Promise<Bucket>;
+    listObjects(bucket: string): Promise<StorageObject[]>;
+    uploadObject(bucket: string, path: string, body: string | Blob | ArrayBuffer | ReadableStream, contentType?: string): Promise<StorageObject>;
+    deleteObject(bucket: string, path: string): Promise<void>;
+}
+declare class FunctionsModule {
+    private readonly client;
+    constructor(client: SovariaClient);
+    deploy(name: string, code: string, runtime: string, entrypoint?: string): Promise<FunctionDeployResponse>;
+    invoke(name: string, payload?: unknown): Promise<FunctionInvokeResponse>;
+}
+declare class RealtimeModule {
+    private readonly client;
+    constructor(client: SovariaClient);
+    /**
+     * Subscribe to a realtime channel via WebSocket.
+     *
+     * Uses a short-lived ticket so JWTs are never placed in WebSocket URLs.
+     *
+     * Returns a subscription handle with an `unsubscribe()` method.
+     */
+    subscribe(channel: string, callback: RealtimeCallback): RealtimeSubscription;
+}
+declare class ChronoModule {
+    private readonly client;
+    constructor(client: SovariaClient);
+    log(timelineName: string): Promise<TimelineLogResponse>;
+    jump(timelineName: string, targetHex: string): Promise<TimelineJumpResponse>;
+}
+export {};