@sovaria/sdk 0.0.0-stage → 0.4.0

package/dist/client.js

@@ -0,0 +1,583 @@
+import { SovariaError } from "./types.js";
+import { newTraceId, traceparentFor } from "./errors.js";
+// ── Constants ────────────────────────────────────────────────────────────────
+const MAX_RETRIES = 4;
+const RETRYABLE_STATUSES = new Set([429, 500, 502, 503, 504]);
+const SAFE_RETRY_METHODS = new Set(["GET", "HEAD", "OPTIONS"]);
+const MUTATING_METHODS = new Set(["POST", "PUT", "PATCH", "DELETE"]);
+const REFRESH_MARGIN_MS = 60_000;
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function getHeaderCaseInsensitive(headers, headerName) {
+    const wanted = headerName.toLowerCase();
+    for (const [key, value] of Object.entries(headers)) {
+        if (key.toLowerCase() === wanted) {
+            return value;
+        }
+    }
+    return undefined;
+}
+function generateIdempotencyKey() {
+    const cryptoObj = globalThis.crypto;
+    if (typeof cryptoObj?.randomUUID === "function") {
+        return cryptoObj.randomUUID();
+    }
+    if (typeof cryptoObj?.getRandomValues === "function") {
+        const bytes = new Uint8Array(16);
+        cryptoObj.getRandomValues(bytes);
+        return Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("");
+    }
+    throw SovariaError.config("No CSPRNG available for idempotency key generation", 500);
+}
+function existingIdempotencyKey(headers) {
+    const existing = getHeaderCaseInsensitive(headers, "Idempotency-Key")
+        ?? getHeaderCaseInsensitive(headers, "X-Idempotency-Key");
+    return existing?.trim() || undefined;
+}
+function parseRetryAfterMs(retryAfterHeader) {
+    if (!retryAfterHeader) {
+        return null;
+    }
+    const seconds = Number.parseFloat(retryAfterHeader);
+    if (Number.isFinite(seconds) && seconds >= 0) {
+        return Math.floor(seconds * 1000);
+    }
+    const retryAtMs = Date.parse(retryAfterHeader);
+    if (Number.isNaN(retryAtMs)) {
+        return null;
+    }
+    return Math.max(0, retryAtMs - Date.now());
+}
+function computeRetryDelayMs(attempt, retryAfterMs = null) {
+    const jitterBackoffMs = Math.min(10_000, 100 * Math.pow(2, attempt) * Math.random());
+    if (retryAfterMs === null) {
+        return jitterBackoffMs;
+    }
+    return Math.max(jitterBackoffMs, Math.min(60_000, retryAfterMs));
+}
+// ── SovariaClient ────────────────────────────────────────────────────────────
+/**
+ * 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 class SovariaClient {
+    baseUrl;
+    accessToken;
+    refreshToken;
+    expiresAt = 0;
+    orgId = null;
+    projectId = null;
+    envId = null;
+    refreshPromise = null;
+    onTokenRefresh;
+    auth;
+    org;
+    data;
+    storage;
+    functions;
+    realtime;
+    chrono;
+    constructor(baseUrl, options) {
+        this.baseUrl = baseUrl.replace(/\/+$/, "");
+        this.accessToken = options?.accessToken ?? null;
+        this.refreshToken = options?.refreshToken ?? null;
+        this.onTokenRefresh = options?.onTokenRefresh;
+        this.auth = new AuthModule(this);
+        this.org = new OrgModule(this);
+        this.data = new DataModule(this);
+        this.storage = new StorageModule(this);
+        this.functions = new FunctionsModule(this);
+        this.realtime = new RealtimeModule(this);
+        this.chrono = new ChronoModule(this);
+    }
+    /**
+     * 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, projectId, envId) {
+        this.orgId = orgId;
+        this.projectId = projectId;
+        this.envId = envId?.trim() || null;
+    }
+    clearContext() {
+        this.orgId = null;
+        this.projectId = null;
+        this.envId = null;
+    }
+    // ── Token management (used internally by AuthModule) ───────────────────────
+    /** @internal */
+    _setTokens(tokens) {
+        this.accessToken = tokens.access_token;
+        this.refreshToken = tokens.refresh_token;
+        this.expiresAt = Date.now() + tokens.expires_in * 1000;
+        this.onTokenRefresh?.(tokens);
+    }
+    /** @internal */
+    _clearTokens() {
+        this.accessToken = null;
+        this.refreshToken = null;
+        this.expiresAt = 0;
+    }
+    /** @internal */
+    get _refreshToken() {
+        return this.refreshToken;
+    }
+    /** @internal */
+    get _isAuthenticated() {
+        return this.accessToken !== null;
+    }
+    // ── Core request method ────────────────────────────────────────────────────
+    /**
+     * Execute an HTTP request with automatic auth injection, token refresh, and
+     * exponential back-off with jitter on transient failures.
+     *
+     * @internal
+     */
+    async _request(method, path, options) {
+        const normalizedMethod = method.toUpperCase();
+        const requiresAuth = options?.requiresAuth ?? true;
+        const baseHeaders = { ...(options?.headers ?? {}) };
+        // One Idempotency-Key for every attempt of a write (the caller's, or a fresh one): if the first
+        // try was applied but its response was lost, the retry gets the stored answer instead of
+        // running the change twice.
+        const idempotencyKey = existingIdempotencyKey(baseHeaders) ??
+            (MUTATING_METHODS.has(normalizedMethod) ? generateIdempotencyKey() : undefined);
+        if (idempotencyKey) {
+            for (const name of Object.keys(baseHeaders)) {
+                if (name.toLowerCase() === "idempotency-key")
+                    delete baseHeaders[name];
+            }
+            baseHeaders["Idempotency-Key"] = idempotencyKey;
+        }
+        const canRetry = SAFE_RETRY_METHODS.has(normalizedMethod) || MUTATING_METHODS.has(normalizedMethod);
+        const traceId = getHeaderCaseInsensitive(baseHeaders, "traceparent")?.split("-")[1] ?? newTraceId();
+        for (let attempt = 0; attempt < MAX_RETRIES; attempt++) {
+            if (requiresAuth) {
+                await this.ensureTokenFresh();
+            }
+            const headers = {
+                Accept: "application/json",
+                ...(getHeaderCaseInsensitive(baseHeaders, "traceparent") ? {} : { traceparent: traceparentFor(traceId) }),
+                ...baseHeaders,
+            };
+            const contentType = headers["Content-Type"] ?? headers["content-type"];
+            const rawBody = Boolean(contentType && !contentType.includes("application/json")) ||
+                (typeof FormData !== "undefined" && options?.body instanceof FormData);
+            if (!rawBody && !contentType) {
+                headers["Content-Type"] = "application/json";
+            }
+            if (typeof FormData !== "undefined" && options?.body instanceof FormData) {
+                delete headers["Content-Type"];
+                delete headers["content-type"];
+            }
+            if (requiresAuth && this.accessToken) {
+                headers["Authorization"] = `Bearer ${this.accessToken}`;
+            }
+            if (this.orgId) {
+                headers["X-Sovaria-Org-ID"] = this.orgId;
+            }
+            if (this.projectId) {
+                headers["X-Sovaria-Project-ID"] = this.projectId;
+            }
+            if (this.envId) {
+                headers["X-Sovaria-Env-ID"] = this.envId;
+            }
+            let url = `${this.baseUrl}${path}`;
+            if (options?.params) {
+                const qs = new URLSearchParams(options.params).toString();
+                if (qs)
+                    url += `?${qs}`;
+            }
+            const fetchInit = { method: normalizedMethod, headers };
+            if (options?.body !== undefined) {
+                fetchInit.body = rawBody
+                    ? options.body
+                    : JSON.stringify(options.body);
+            }
+            let response;
+            try {
+                response = await fetch(url, fetchInit);
+            }
+            catch (err) {
+                if (!canRetry || attempt >= MAX_RETRIES - 1) {
+                    throw new SovariaError(0, `Network error: ${err instanceof Error ? err.message : String(err)}`);
+                }
+                if (attempt < MAX_RETRIES - 1) {
+                    await sleep(computeRetryDelayMs(attempt));
+                    continue;
+                }
+            }
+            if (!response) {
+                throw new SovariaError(0, "Network error: request failed before receiving a response");
+            }
+            if (response.ok) {
+                const text = await response.text();
+                if (!text)
+                    return {};
+                try {
+                    return JSON.parse(text);
+                }
+                catch {
+                    return {};
+                }
+            }
+            // Auto-refresh on 401 and retry once
+            if (response.status === 401 && requiresAuth && this.refreshToken && attempt === 0) {
+                try {
+                    await this.doRefresh();
+                    continue;
+                }
+                catch {
+                    // Refresh failed — fall through to error
+                }
+            }
+            let detail;
+            try {
+                detail = await response.json();
+            }
+            catch {
+                detail = response.statusText;
+            }
+            // "The same Idempotency-Key is still being processed": wait, then the retry gets the first
+            // try's stored answer instead of running the change twice.
+            const inProgress = response.status === 409 && detail?.code === "IDEMPOTENCY_IN_PROGRESS";
+            if (canRetry && (RETRYABLE_STATUSES.has(response.status) || inProgress) && attempt < MAX_RETRIES - 1) {
+                const retryAfterMs = response.status === 429 || inProgress
+                    ? parseRetryAfterMs(response.headers.get("Retry-After"))
+                    : null;
+                await sleep(computeRetryDelayMs(attempt, retryAfterMs));
+                continue;
+            }
+            throw new SovariaError(response.status, detail).withTraceId(response.headers.get("X-Request-ID") ?? traceId);
+        }
+        throw new SovariaError(0, "Max retries exceeded");
+    }
+    // ── Token refresh internals ────────────────────────────────────────────────
+    async ensureTokenFresh() {
+        if (!this.accessToken)
+            return;
+        if (Date.now() < this.expiresAt - REFRESH_MARGIN_MS)
+            return;
+        if (!this.refreshToken)
+            return;
+        // Deduplicate concurrent refresh calls
+        if (!this.refreshPromise) {
+            this.refreshPromise = this.doRefresh().finally(() => {
+                this.refreshPromise = null;
+            });
+        }
+        await this.refreshPromise;
+    }
+    async doRefresh() {
+        if (!this.refreshToken) {
+            throw new SovariaError(401, "No refresh token available — please log in again");
+        }
+        const response = await fetch(`${this.baseUrl}/api/v1/auth/refresh`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({ refresh_token: this.refreshToken }),
+        });
+        if (!response.ok) {
+            this._clearTokens();
+            let detail;
+            try {
+                const errBody = await response.json();
+                detail = errBody.detail ?? "Refresh failed";
+            }
+            catch {
+                detail = "Refresh failed";
+            }
+            throw new SovariaError(response.status, detail);
+        }
+        const tokens = await response.json();
+        this._setTokens(tokens);
+    }
+    /**
+     * Build a WebSocket URL from the base URL, converting http(s) to ws(s).
+     * @internal
+     */
+    _wsUrl(path) {
+        const base = this.baseUrl
+            .replace(/^https:\/\//, "wss://")
+            .replace(/^http:\/\//, "ws://");
+        return `${base}${path}`;
+    }
+    /** @internal */
+    async _issueRealtimeWsTicket(channel) {
+        if (!this.orgId || !this.projectId) {
+            throw SovariaError.config("Realtime websocket tickets require org/project context; call setContext() first");
+        }
+        const safeChannel = channel.trim();
+        if (!safeChannel) {
+            throw SovariaError.config("channel is required for realtime websocket tickets");
+        }
+        const response = await this._request("POST", "/api/v1/auth/ws-ticket", {
+            body: {
+                channel: safeChannel,
+                org_id: this.orgId,
+                project_id: this.projectId,
+                ...(this.envId ? { env_id: this.envId } : {}),
+            },
+        });
+        const ticket = response.ticket?.trim();
+        if (!ticket) {
+            throw new SovariaError(502, "Gateway did not return a websocket ticket");
+        }
+        return ticket;
+    }
+    /** @internal */
+    get _accessToken() {
+        return this.accessToken;
+    }
+}
+// ── Auth Module ──────────────────────────────────────────────────────────────
+class AuthModule {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    async login(email, password) {
+        console.warn("SovariaClient.auth.login() is deprecated; use SovariaSDK.auth.consoleLogin() or auth.projectLogin(). This legacy client posts to /api/v1/auth/console/login (not /api/v1/auth/login).");
+        const tokens = await this.client._request("POST", "/api/v1/auth/console/login", { body: { email, password }, requiresAuth: false });
+        this.client._setTokens(tokens);
+        return tokens;
+    }
+    async register(email, password, name) {
+        const tokens = await this.client._request("POST", "/api/v1/auth/register", { body: { email, password, name }, requiresAuth: false });
+        this.client._setTokens(tokens);
+        return tokens;
+    }
+    async logout() {
+        if (this.client._isAuthenticated && this.client._refreshToken) {
+            try {
+                await this.client._request("POST", "/api/v1/auth/logout", {
+                    body: { refresh_token: this.client._refreshToken },
+                });
+            }
+            catch {
+                // Best-effort: local tokens are cleared regardless
+            }
+        }
+        this.client._clearTokens();
+    }
+    async me() {
+        return this.client._request("GET", "/api/v1/auth/me");
+    }
+}
+// ── Org Module ───────────────────────────────────────────────────────────────
+class OrgModule {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    async list() {
+        const result = await this.client._request("GET", "/api/v1/org");
+        return Array.isArray(result) ? result : result.nodes ?? [];
+    }
+    async get(id) {
+        return this.client._request("GET", `/api/v1/org/${encodeURIComponent(id)}`);
+    }
+    async create(type, name, metadata) {
+        return this.client._request("POST", "/api/v1/org", {
+            body: { type, name, metadata: metadata ?? {} },
+        });
+    }
+    async children(id) {
+        const result = await this.client._request("GET", `/api/v1/org/${encodeURIComponent(id)}/children`);
+        return Array.isArray(result) ? result : result.children ?? [];
+    }
+}
+// ── Data Module ──────────────────────────────────────────────────────────────
+class SqlSubmodule {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    async createTable(tableName, columns) {
+        return this.client._request("POST", "/api/v1/data/rel/create", {
+            body: { table_name: tableName, columns },
+        });
+    }
+    async query(sql, params) {
+        const result = await this.client._request("POST", "/api/v1/sql/query", { body: { sql, params: params ?? {} } });
+        return Array.isArray(result) ? result : result.rows ?? [];
+    }
+    async dropTable(name) {
+        return this.client._request("POST", "/api/v1/data/rel/drop", {
+            body: { table_name: name },
+        });
+    }
+}
+class DocSubmodule {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    async put(collection, key, data) {
+        return this.client._request("POST", `/api/v1/data/doc/${encodeURIComponent(collection)}/${encodeURIComponent(key)}`, { body: data });
+    }
+    async get(collection, key) {
+        return this.client._request("GET", `/api/v1/data/doc/${encodeURIComponent(collection)}/${encodeURIComponent(key)}`);
+    }
+    async scan(collection, filter) {
+        return this.client._request("POST", "/api/v1/data/query/scan", {
+            body: { prefix: collection, filter: filter ?? {} },
+        });
+    }
+}
+class DataModule {
+    sql;
+    doc;
+    constructor(client) {
+        this.sql = new SqlSubmodule(client);
+        this.doc = new DocSubmodule(client);
+    }
+}
+// ── Storage Module ───────────────────────────────────────────────────────────
+class StorageModule {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    async listBuckets() {
+        const result = await this.client._request("GET", "/api/v1/store/buckets");
+        return Array.isArray(result) ? result : result.buckets ?? [];
+    }
+    async createBucket(name, isPublic = false) {
+        return this.client._request("POST", "/api/v1/store/buckets", {
+            body: { name, public: isPublic },
+        });
+    }
+    async listObjects(bucket) {
+        const result = await this.client._request("GET", `/api/v1/store/objects/${encodeURIComponent(bucket)}`);
+        return Array.isArray(result) ? result : result.objects ?? [];
+    }
+    async uploadObject(bucket, path, body, contentType = "application/octet-stream") {
+        const encodedPath = path
+            .split("/")
+            .map((s) => encodeURIComponent(s))
+            .join("/");
+        return this.client._request("POST", `/api/v1/store/objects/${encodeURIComponent(bucket)}/${encodedPath}`, {
+            body,
+            headers: { "Content-Type": contentType },
+        });
+    }
+    async deleteObject(bucket, path) {
+        const encodedPath = path
+            .split("/")
+            .map((s) => encodeURIComponent(s))
+            .join("/");
+        await this.client._request("DELETE", `/api/v1/store/objects/${encodeURIComponent(bucket)}/${encodedPath}`);
+    }
+}
+// ── Functions Module ─────────────────────────────────────────────────────────
+class FunctionsModule {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    async deploy(name, code, runtime, entrypoint) {
+        return this.client._request("POST", "/api/v1/fn/deploy", { body: { name, code, runtime, entrypoint } });
+    }
+    async invoke(name, payload) {
+        return this.client._request("POST", `/api/v1/fn/${encodeURIComponent(name)}/invoke`, { body: payload ?? {} });
+    }
+}
+// ── Realtime Module ──────────────────────────────────────────────────────────
+class RealtimeModule {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    /**
+     * 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, callback) {
+        let ws = null;
+        let unsubscribed = false;
+        void (async () => {
+            try {
+                const ticket = await this.client._issueRealtimeWsTicket(channel);
+                if (unsubscribed) {
+                    return;
+                }
+                const params = new URLSearchParams({ ticket });
+                const wsUrl = this.client._wsUrl(`/api/v1/rt/ws/${encodeURIComponent(channel)}?${params.toString()}`);
+                ws = new WebSocket(wsUrl);
+                ws.onmessage = (event) => {
+                    try {
+                        const parsed = JSON.parse(String(event.data));
+                        callback(parsed);
+                    }
+                    catch {
+                        callback({ type: "message", channel, payload: event.data });
+                    }
+                };
+                ws.onerror = (event) => {
+                    callback({
+                        type: "error",
+                        channel,
+                        payload: event,
+                    });
+                };
+                ws.onclose = (event) => {
+                    callback({
+                        type: "close",
+                        channel,
+                        payload: { code: event.code, reason: event.reason },
+                    });
+                };
+            }
+            catch (error) {
+                callback({
+                    type: "error",
+                    channel,
+                    payload: error,
+                });
+            }
+        })();
+        return {
+            unsubscribe: () => {
+                unsubscribed = true;
+                if (ws
+                    && (ws.readyState === WebSocket.OPEN || ws.readyState === WebSocket.CONNECTING)) {
+                    ws.close();
+                }
+            },
+        };
+    }
+}
+// ── Chrono Module ────────────────────────────────────────────────────────────
+class ChronoModule {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    async log(timelineName) {
+        return this.client._request("GET", `/api/v1/chrono/timelines/${encodeURIComponent(timelineName)}/history`);
+    }
+    async jump(timelineName, targetHex) {
+        return this.client._request("POST", `/api/v1/chrono/timelines/${encodeURIComponent(timelineName)}/jump`, { body: { target_hex: targetHex } });
+    }
+}