@synapseone/sdk 0.7.0 → 0.7.1-dev.56

package/README.md

@@ -15,7 +15,7 @@ npm install @synapseone/sdk
 ```ts
 import { SynapseOneClient } from '@synapseone/sdk';
 
-const c = new SynapseOneClient({ baseUrl: 'http://localhost:8080' });
+const c = new SynapseOneClient(); // defaults to https://synapseone.space (or $SYNAPSEONE_BASE_URL)
 const { accessToken, user } = await c.iam.login('demo@acme.local');
 c.setToken(accessToken);
 

package/dist/_http.d.ts

@@ -1,9 +1,34 @@
+/** Public API gateway origin. The console/marketing host is NOT the API. */
+export declare const DEFAULT_BASE_URL = "https://api.synapseone.space";
+/** Default per-request timeout. Long-running namespaces override it. */
+export declare const DEFAULT_TIMEOUT_MS = 15000;
+/** Inference/LLM calls routinely exceed 15s; keep in sync with the gateway route. */
+export declare const INFERENCE_TIMEOUT_MS = 120000;
+/** Public inbound webhooks can run up to the workflow 300s budget. */
+export declare const WEBHOOK_TIMEOUT_MS = 300000;
 export interface SynapseOneClientOptions {
-    baseUrl: string;
+    baseUrl?: string;
     token?: string;
     apiKey?: string;
     tenant?: string;
     timeoutMs?: number;
+    /** Max attempts for idempotent requests on 429/502/503/504 (default 3, 1 = no retry). */
+    maxAttempts?: number;
+    /** Base backoff in ms for retries (exponential, default 200). */
+    retryBaseMs?: number;
+}
+/** Per-call transport options. */
+export interface RequestOptions {
+    /** Override the client/namespace timeout for this call. */
+    timeoutMs?: number;
+    /** Caller-supplied abort signal. */
+    signal?: AbortSignal;
+    /** Max total attempts for this call (1 disables retries). */
+    maxAttempts?: number;
+    /** Force retry eligibility (defaults to idempotent methods). */
+    retryable?: boolean;
+    /** Extra headers for this call. */
+    headers?: Record<string, string>;
 }
 /** All SDK failures surface as SynapseOneError (network or HTTP). */
 export declare class SynapseOneError extends Error {
@@ -11,9 +36,15 @@ export declare class SynapseOneError extends Error {
     status?: number;
     /** Parsed error body when the response carried JSON. */
     body?: unknown;
+    /** Machine-readable error code (when known). */
+    code?: string;
+    /** Base URL the request was sent to (diagnoses console-vs-API misconfiguration). */
+    baseUrl?: string;
     constructor(message: string, opts?: {
         status?: number;
         body?: unknown;
+        code?: string;
+        baseUrl?: string;
     });
 }
 /**
@@ -31,12 +62,34 @@ export declare class HttpClient {
     apiKey?: string;
     tenant?: string;
     timeoutMs: number;
-    constructor(opts: SynapseOneClientOptions);
+    maxAttempts: number;
+    retryBaseMs: number;
+    constructor(opts?: SynapseOneClientOptions);
     setToken(t: string): void;
     setApiKey(k: string): void;
     setTenant(t: string | undefined): void;
     headers(extra?: Record<string, string>): Record<string, string>;
-    req<T>(path: string, init?: RequestInit): Promise<T>;
+    /** Low-level fetch with timeout, caller signal and bounded retries. */
+    private fetchOnce;
+    req<T>(path: string, init?: RequestInit, options?: RequestOptions): Promise<T>;
+    /** Upload a binary body and parse the JSON response. */
+    upload<T>(path: string, body: Uint8Array | string, options?: RequestOptions & {
+        method?: string;
+        contentType?: string;
+    }): Promise<T>;
+    /** HEAD request; returns response headers (no body). */
+    head(path: string, options?: RequestOptions): Promise<Record<string, string>>;
+    /** Fetch a binary body (bytes). Used by object storage/file downloads. */
+    reqBinary(path: string, init?: RequestInit, options?: RequestOptions): Promise<Uint8Array>;
+    /**
+     * Stream a Server-Sent-Events response as parsed `{event, data}` records.
+     * The transport is not buffered; each event is yielded as soon as a blank
+     * line terminates it. Pass an AbortSignal to cancel.
+     */
+    stream(path: string, init?: RequestInit, options?: RequestOptions): AsyncGenerator<{
+        event: string;
+        data: string;
+    }>;
     /** Generic escape hatch (forward-compat with endpoints added after this SDK). */
-    call(method: string, path: string, body?: unknown): Promise<unknown>;
+    call(method: string, path: string, body?: unknown, options?: RequestOptions): Promise<unknown>;
 }

package/dist/_http.js

@@ -1,23 +1,39 @@
 "use strict";
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: 2026 VKU.VIC
 /*
  * Copyright 2026 SynapseOne Contributors
  * Licensed under the Apache License, Version 2.0 (the "License");
  * Shared fetch-based HTTP plumbing for the synapseone JavaScript SDK.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.HttpClient = exports.SynapseDXError = exports.SynapseOneError = void 0;
+exports.HttpClient = exports.SynapseDXError = exports.SynapseOneError = exports.WEBHOOK_TIMEOUT_MS = exports.INFERENCE_TIMEOUT_MS = exports.DEFAULT_TIMEOUT_MS = exports.DEFAULT_BASE_URL = void 0;
 exports.warnDeprecated = warnDeprecated;
+/** Public API gateway origin. The console/marketing host is NOT the API. */
+exports.DEFAULT_BASE_URL = 'https://api.synapseone.space';
+/** Default per-request timeout. Long-running namespaces override it. */
+exports.DEFAULT_TIMEOUT_MS = 15_000;
+/** Inference/LLM calls routinely exceed 15s; keep in sync with the gateway route. */
+exports.INFERENCE_TIMEOUT_MS = 120_000;
+/** Public inbound webhooks can run up to the workflow 300s budget. */
+exports.WEBHOOK_TIMEOUT_MS = 300_000;
 /** All SDK failures surface as SynapseOneError (network or HTTP). */
 class SynapseOneError extends Error {
     /** HTTP status code when the failure came from a response, undefined for network errors. */
     status;
     /** Parsed error body when the response carried JSON. */
     body;
+    /** Machine-readable error code (when known). */
+    code;
+    /** Base URL the request was sent to (diagnoses console-vs-API misconfiguration). */
+    baseUrl;
     constructor(message, opts = {}) {
         super(message);
         this.name = 'SynapseOneError';
         this.status = opts.status;
         this.body = opts.body;
+        this.code = opts.code;
+        this.baseUrl = opts.baseUrl;
     }
 }
 exports.SynapseOneError = SynapseOneError;
@@ -32,18 +48,44 @@ function warnDeprecated(name, replacement) {
         console.warn(message);
     }
 }
+const RETRYABLE_STATUS = new Set([429, 502, 503, 504]);
+const IDEMPOTENT_METHODS = new Set(['GET', 'HEAD', 'OPTIONS', 'PUT', 'DELETE']);
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/** Retry-After is either delta-seconds or an HTTP date. Clamp to a sane max. */
+function retryAfterMs(value) {
+    if (!value)
+        return undefined;
+    const secs = Number(value);
+    if (Number.isFinite(secs) && secs >= 0)
+        return Math.min(secs * 1000, 30_000);
+    const when = Date.parse(value);
+    if (Number.isFinite(when))
+        return Math.min(Math.max(when - Date.now(), 0), 30_000);
+    return undefined;
+}
+function isHtml(body) {
+    const head = body.slice(0, 256).trimStart().toLowerCase();
+    return head.startsWith('<!doctype html') || head.startsWith('<html');
+}
 class HttpClient {
     baseUrl;
     token;
     apiKey;
     tenant;
     timeoutMs;
-    constructor(opts) {
-        this.baseUrl = opts.baseUrl.replace(/\/$/, '');
+    maxAttempts;
+    retryBaseMs;
+    constructor(opts = {}) {
+        const raw = opts.baseUrl ?? (typeof process !== 'undefined' ? (process.env?.SYNAPSEONE_BASE_URL || process.env?.SYNAPSEDX_BASE_URL) : undefined) ?? exports.DEFAULT_BASE_URL;
+        this.baseUrl = raw.replace(/\/$/, '');
         this.token = opts.token;
         this.apiKey = opts.apiKey;
         this.tenant = opts.tenant;
-        this.timeoutMs = opts.timeoutMs ?? 15000;
+        this.timeoutMs = opts.timeoutMs ?? exports.DEFAULT_TIMEOUT_MS;
+        this.maxAttempts = Math.max(1, Math.floor(opts.maxAttempts ?? 3));
+        this.retryBaseMs = Math.max(0, Math.floor(opts.retryBaseMs ?? 200));
     }
     setToken(t) { this.token = t; }
     setApiKey(k) { this.apiKey = k; }
@@ -58,35 +100,129 @@ class HttpClient {
             h['x-synapseone-tenant'] = this.tenant;
         return h;
     }
-    async req(path, init) {
-        let r;
+    /** Low-level fetch with timeout, caller signal and bounded retries. */
+    async fetchOnce(path, init, opts, timeoutMs) {
         const ctl = new AbortController();
-        const to = setTimeout(() => ctl.abort(), this.timeoutMs);
+        const onAbort = () => ctl.abort();
+        if (opts.signal) {
+            if (opts.signal.aborted)
+                ctl.abort();
+            else
+                opts.signal.addEventListener('abort', onAbort, { once: true });
+        }
+        const to = timeoutMs > 0 ? setTimeout(() => ctl.abort(), timeoutMs) : undefined;
         try {
-            r = await fetch(`${this.baseUrl}${path}`, {
+            return await fetch(`${this.baseUrl}${path}`, {
                 ...init,
-                signal: init?.signal ?? ctl.signal,
-                headers: this.headers(init?.headers || {}),
+                signal: ctl.signal,
+                headers: this.headers({ ...init?.headers, ...(opts.headers || {}) }),
             });
         }
-        catch (e) {
-            throw new SynapseOneError(`synapseone network ${path}: ${e?.message || e}`);
-        }
         finally {
-            clearTimeout(to);
+            if (to)
+                clearTimeout(to);
+            if (opts.signal)
+                opts.signal.removeEventListener('abort', onAbort);
         }
-        if (!r.ok) {
-            const text = (await r.text()).slice(0, 2000);
-            let body;
+    }
+    async req(path, init, options = {}) {
+        const method = String(init?.method || 'GET').toUpperCase();
+        const timeoutMs = options.timeoutMs ?? this.timeoutMs;
+        const maxAttempts = Math.max(1, Math.floor(options.maxAttempts ?? this.maxAttempts));
+        const retryable = options.retryable ?? IDEMPOTENT_METHODS.has(method);
+        let attempt = 0;
+        let lastErr;
+        for (;;) {
+            attempt++;
+            let r;
             try {
-                body = JSON.parse(text);
+                r = await this.fetchOnce(path, init, options, timeoutMs);
+            }
+            catch (e) {
+                if (e?.name === 'AbortError') {
+                    throw new SynapseOneError(`synapseone timeout ${path} after ${timeoutMs}ms (base ${this.baseUrl})`, {
+                        code: 'timeout',
+                        baseUrl: this.baseUrl,
+                    });
+                }
+                lastErr = new SynapseOneError(`synapseone network ${path}: ${e?.message || e} (base ${this.baseUrl})`, {
+                    code: 'network_error',
+                    baseUrl: this.baseUrl,
+                });
+                if (retryable && attempt < maxAttempts) {
+                    await sleep(this.retryBaseMs * 2 ** (attempt - 1) + Math.random() * this.retryBaseMs);
+                    continue;
+                }
+                throw lastErr;
+            }
+            if (!r.ok) {
+                const text = (await r.text()).slice(0, 2000);
+                let body;
+                try {
+                    body = JSON.parse(text);
+                }
+                catch {
+                    body = undefined;
+                }
+                const err = new SynapseOneError(`synapseone ${r.status} ${path}: ${text} (base ${this.baseUrl})`, {
+                    status: r.status,
+                    body,
+                    code: body?.error,
+                    baseUrl: this.baseUrl,
+                });
+                if (retryable && RETRYABLE_STATUS.has(r.status) && attempt < maxAttempts) {
+                    const wait = retryAfterMs(r.headers?.get?.('retry-after') ?? null)
+                        ?? this.retryBaseMs * 2 ** (attempt - 1) + Math.random() * this.retryBaseMs;
+                    await sleep(wait);
+                    lastErr = err;
+                    continue;
+                }
+                throw err;
+            }
+            const contentType = String(r.headers?.get?.('content-type') || '').toLowerCase();
+            const text = await r.text();
+            if (!text)
+                return null;
+            if (contentType.includes('text/html') || isHtml(text)) {
+                // A 200 SPA/HTML response means the base URL points at the console host,
+                // not the API gateway — surface it instead of returning HTML as data.
+                throw new SynapseOneError(`synapseone expected JSON from ${this.baseUrl}${path} but received HTML (status ${r.status}). `
+                    + `The base URL looks like the console/marketing host; use ${exports.DEFAULT_BASE_URL}.`, { status: r.status, code: 'non_json_response', baseUrl: this.baseUrl });
+            }
+            try {
+                return JSON.parse(text);
             }
             catch {
-                body = undefined;
+                return text;
             }
-            throw new SynapseOneError(`synapseone ${r.status} ${path}: ${text}`, { status: r.status, body });
         }
+    }
+    /** Upload a binary body and parse the JSON response. */
+    async upload(path, body, options = {}) {
+        const timeoutMs = options.timeoutMs ?? this.timeoutMs;
+        const r = await this.fetchOnce(path, {
+            method: options.method || 'PUT',
+            body: body,
+            headers: {
+                'Content-Type': options.contentType || 'application/octet-stream',
+                ...(options.headers || {}),
+            },
+        }, options, timeoutMs);
         const text = await r.text();
+        if (!r.ok) {
+            let parsed;
+            try {
+                parsed = JSON.parse(text);
+            }
+            catch {
+                parsed = undefined;
+            }
+            throw new SynapseOneError(`synapseone ${r.status} ${path}: ${text.slice(0, 500)} (base ${this.baseUrl})`, {
+                status: r.status,
+                body: parsed,
+                baseUrl: this.baseUrl,
+            });
+        }
         if (!text)
             return null;
         try {
@@ -96,13 +232,124 @@ class HttpClient {
             return text;
         }
     }
+    /** HEAD request; returns response headers (no body). */
+    async head(path, options = {}) {
+        const timeoutMs = options.timeoutMs ?? this.timeoutMs;
+        const r = await this.fetchOnce(path, { method: 'HEAD' }, options, timeoutMs);
+        if (!r.ok) {
+            throw new SynapseOneError(`synapseone ${r.status} ${path} (base ${this.baseUrl})`, {
+                status: r.status,
+                baseUrl: this.baseUrl,
+            });
+        }
+        const out = {};
+        r.headers?.forEach?.((v, k) => { out[k.toLowerCase()] = v; });
+        return out;
+    }
+    /** Fetch a binary body (bytes). Used by object storage/file downloads. */
+    async reqBinary(path, init, options = {}) {
+        const timeoutMs = options.timeoutMs ?? this.timeoutMs;
+        const r = await this.fetchOnce(path, init, options, timeoutMs);
+        if (!r.ok) {
+            const text = (await r.text()).slice(0, 2000);
+            throw new SynapseOneError(`synapseone ${r.status} ${path}: ${text} (base ${this.baseUrl})`, {
+                status: r.status,
+                baseUrl: this.baseUrl,
+            });
+        }
+        return new Uint8Array(await r.arrayBuffer());
+    }
+    /**
+     * Stream a Server-Sent-Events response as parsed `{event, data}` records.
+     * The transport is not buffered; each event is yielded as soon as a blank
+     * line terminates it. Pass an AbortSignal to cancel.
+     */
+    async *stream(path, init, options = {}) {
+        const timeoutMs = options.timeoutMs ?? exports.INFERENCE_TIMEOUT_MS;
+        const r = await this.fetchOnce(path, init, options, timeoutMs);
+        if (!r.ok) {
+            const text = (await r.text()).slice(0, 2000);
+            let body;
+            try {
+                body = JSON.parse(text);
+            }
+            catch {
+                body = undefined;
+            }
+            throw new SynapseOneError(`synapseone ${r.status} ${path}: ${text} (base ${this.baseUrl})`, {
+                status: r.status,
+                body,
+                baseUrl: this.baseUrl,
+            });
+        }
+        const body = r.body;
+        if (!body || typeof body.getReader !== 'function') {
+            // Non-streaming environment: decode the whole payload and parse SSE lines.
+            const text = await r.text();
+            yield* parseSse(text);
+            return;
+        }
+        const reader = body.getReader();
+        const decoder = new TextDecoder();
+        let buffer = '';
+        try {
+            for (;;) {
+                const { done, value } = await reader.read();
+                if (done)
+                    break;
+                buffer += decoder.decode(value, { stream: true });
+                let idx;
+                while ((idx = buffer.search(/\r?\n\r?\n/)) >= 0) {
+                    const chunk = buffer.slice(0, idx);
+                    buffer = buffer.slice(idx).replace(/^\r?\n\r?\n/, '');
+                    for (const ev of parseSse(chunk))
+                        yield ev;
+                }
+            }
+            buffer += decoder.decode();
+            if (buffer.trim())
+                for (const ev of parseSse(buffer))
+                    yield ev;
+        }
+        finally {
+            try {
+                reader.releaseLock();
+            }
+            catch { /* already released */ }
+        }
+    }
     /** Generic escape hatch (forward-compat with endpoints added after this SDK). */
-    call(method, path, body) {
+    call(method, path, body, options = {}) {
         const m = String(method || 'GET').toUpperCase();
         return this.req(path.startsWith('/') ? path : `/${path}`, {
             method: m,
             body: body === undefined || m === 'GET' || m === 'HEAD' ? undefined : JSON.stringify(body),
-        });
+        }, options);
     }
 }
 exports.HttpClient = HttpClient;
+function* parseSse(text) {
+    let event = 'message';
+    const data = [];
+    for (const rawLine of text.split(/\r?\n/)) {
+        const line = rawLine.trimEnd();
+        if (!line) {
+            if (data.length)
+                yield { event, data: data.join('\n') };
+            event = 'message';
+            data.length = 0;
+            continue;
+        }
+        if (line.startsWith(':'))
+            continue;
+        const idx = line.indexOf(':');
+        const field = idx === -1 ? line : line.slice(0, idx);
+        const value = idx === -1 ? '' : line.slice(idx + 1).replace(/^ /, '');
+        if (field === 'event')
+            event = value;
+        else if (field === 'data')
+            data.push(value);
+    }
+    if (data.length)
+        yield { event, data: data.join('\n') };
+}

package/dist/ai.js

@@ -1,4 +1,6 @@
 "use strict";
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: 2026 VKU.VIC
 /*
  * Copyright 2026 SynapseOne Contributors
  * Licensed under the Apache License, Version 2.0 (the "License");

package/dist/base.d.ts

@@ -161,6 +161,17 @@ export declare class BaseService {
         limit?: number;
         offset?: number;
     }): Promise<Array<BaseDocument<T>>>;
+    /** Paginated listing with an exact total and next cursor (#29 envelope). */
+    listDocumentsPage<T = Record<string, unknown>>(collection: string, opts?: {
+        limit?: number;
+        offset?: number;
+    }): Promise<{
+        items: Array<BaseDocument<T>>;
+        total: number;
+        limit: number;
+        offset: number;
+        nextCursor: string | null;
+    }>;
     increment<T = Record<string, unknown>>(collection: string, id: string, body: {
         field: string;
         by?: number;

package/dist/base.js

@@ -1,4 +1,6 @@
 "use strict";
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: 2026 VKU.VIC
 /*
  * Copyright 2026 SynapseOne Contributors
  * Licensed under the Apache License, Version 2.0 (the "License");
@@ -206,6 +208,10 @@ class BaseService {
     listDocuments(collection, opts = {}) {
         return this.http.req(`/v1/base/collections/${encodeURIComponent(collection)}/documents${queryString({ limit: opts.limit, offset: opts.offset })}`);
     }
+    /** Paginated listing with an exact total and next cursor (#29 envelope). */
+    listDocumentsPage(collection, opts = {}) {
+        return this.http.req(`/v1/base/collections/${encodeURIComponent(collection)}/documents${queryString({ limit: opts.limit, offset: opts.offset, withTotal: 1 })}`);
+    }
     increment(collection, id, body) {
         return this.http.req(`/v1/base/collections/${encodeURIComponent(collection)}/documents/${encodeURIComponent(id)}/increment`, {
             method: 'POST',

package/dist/client.test.js

@@ -3,6 +3,8 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: 2026 VKU.VIC
 /*
  * Copyright 2026 SynapseOne Contributors
  * Licensed under the Apache License, Version 2.0 (the "License");
@@ -44,6 +46,22 @@ let server;
         strict_1.default.equal(index_1.SynapseDXClient, index_1.SynapseOneClient);
         strict_1.default.equal(index_1.SynapseDXError, index_1.SynapseOneError);
     });
+    (0, node_test_1.it)('defaults to the public API gateway, not the console host', () => {
+        const orig = process.env.SYNAPSEONE_BASE_URL;
+        const origLegacy = process.env.SYNAPSEDX_BASE_URL;
+        delete process.env.SYNAPSEONE_BASE_URL;
+        delete process.env.SYNAPSEDX_BASE_URL;
+        try {
+            const c = new index_1.SynapseOneClient();
+            strict_1.default.equal(c.baseUrl, 'https://api.synapseone.space');
+        }
+        finally {
+            if (orig !== undefined)
+                process.env.SYNAPSEONE_BASE_URL = orig;
+            if (origLegacy !== undefined)
+                process.env.SYNAPSEDX_BASE_URL = origLegacy;
+        }
+    });
     (0, node_test_1.it)('trims trailing slash', () => {
         const c = new index_1.SynapseOneClient({ baseUrl: 'http://x:8080/' });
         strict_1.default.equal(c.baseUrl, 'http://x:8080');

package/dist/example.js

@@ -1,12 +1,14 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: 2026 VKU.VIC
 /*
  * Copyright 2026 SynapseOne Contributors
  * Licensed under the Apache License, Version 2.0 (the "License");
  */
 const index_1 = require("./index");
 async function main() {
-    const c = new index_1.SynapseOneClient({ baseUrl: process.env.SYNAPSEONE_BASE_URL || 'http://localhost:8080' });
+    const c = new index_1.SynapseOneClient(); // defaults to https://synapseone.space or $SYNAPSEONE_BASE_URL
     const login = await c.login('demo@acme.local');
     console.log('login ok:', login.user?.email);
     c.setToken(login.accessToken);

package/dist/faststore.js

@@ -1,4 +1,6 @@
 "use strict";
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: 2026 VKU.VIC
 /*
  * Copyright 2026 SynapseOne Contributors
  * Licensed under the Apache License, Version 2.0 (the "License");

package/dist/health.d.ts

@@ -0,0 +1,54 @@
+import { HttpClient, RequestOptions } from './_http';
+export interface DependencyStatus {
+    name: string;
+    ok: boolean;
+    status?: number;
+    ms?: number;
+    version?: string;
+    error?: string;
+}
+export interface HealthResponse {
+    status: string;
+    service: string;
+    version: string;
+    time: string;
+    schemaVersion?: string;
+    dependencies?: DependencyStatus[];
+}
+export interface ReadyResponse {
+    status: 'ready' | 'degraded' | string;
+    service: string;
+    version: string;
+    upstreams: DependencyStatus[];
+    time: string;
+    schemaVersion?: string;
+}
+export interface StatusResponse {
+    ok: boolean;
+    tier1: {
+        status: string;
+        version?: string;
+        reachable: boolean;
+        httpStatus?: number;
+    };
+    upstreams: DependencyStatus[];
+    time?: string;
+}
+export interface ReadyOptions extends RequestOptions {
+    /** Throw on a degraded (503) response instead of returning it (default false). */
+    throwOnDegraded?: boolean;
+}
+export declare class HealthService {
+    private readonly http;
+    constructor(http: HttpClient);
+    /** Shallow gateway health (never throws on a degraded dependency). */
+    health(opts?: RequestOptions): Promise<HealthResponse>;
+    /**
+     * Aggregate readiness. A 503 means "degraded", not "unreachable": by default
+     * the parsed payload is returned so callers can project the upstream list.
+     * Set `throwOnDegraded: true` for strict probe semantics.
+     */
+    ready(opts?: ReadyOptions): Promise<ReadyResponse>;
+    /** Convenience projection used by Tier-2 `/ready` endpoints. */
+    status(opts?: ReadyOptions): Promise<StatusResponse>;
+}

package/dist/health.js

@@ -0,0 +1,58 @@
+"use strict";
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: 2026 VKU.VIC
+/*
+ * Copyright 2026 SynapseOne Contributors
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * Typed gateway health/readiness contract (issue #42).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HealthService = void 0;
+const _http_1 = require("./_http");
+class HealthService {
+    http;
+    constructor(http) {
+        this.http = http;
+    }
+    /** Shallow gateway health (never throws on a degraded dependency). */
+    health(opts = {}) {
+        return this.http.req('/health', undefined, { maxAttempts: 1, ...opts });
+    }
+    /**
+     * Aggregate readiness. A 503 means "degraded", not "unreachable": by default
+     * the parsed payload is returned so callers can project the upstream list.
+     * Set `throwOnDegraded: true` for strict probe semantics.
+     */
+    async ready(opts = {}) {
+        try {
+            return await this.http.req('/ready', undefined, { maxAttempts: 1, ...opts });
+        }
+        catch (e) {
+            if (e instanceof _http_1.SynapseOneError && e.status === 503 && e.body && !opts.throwOnDegraded) {
+                return e.body;
+            }
+            throw e;
+        }
+    }
+    /** Convenience projection used by Tier-2 `/ready` endpoints. */
+    async status(opts = {}) {
+        const [health, ready] = await Promise.all([
+            this.health(opts).catch((e) => ({ error: e })),
+            this.ready(opts).catch((e) => ({ error: e })),
+        ]);
+        const upstreams = Array.isArray(ready?.upstreams) ? ready.upstreams : [];
+        const reachable = !!health?.status && !health?.error;
+        return {
+            ok: reachable && ready?.status === 'ready',
+            tier1: {
+                status: health?.status || 'unreachable',
+                version: health?.version,
+                reachable,
+                httpStatus: health?.error?.status,
+            },
+            upstreams,
+            time: ready?.time,
+        };
+    }
+}
+exports.HealthService = HealthService;