@apteva/web-sdk 0.5.5 → 0.7.0

package/dist/client.js

@@ -1,3 +1,4 @@
+import { loadAppFrontend } from "./frontend.js";
 import { AptevaError } from "./errors.js";
 const DEFAULT_TIMEOUT_MS = 30_000;
 export class AptevaClient {
@@ -8,6 +9,9 @@ export class AptevaClient {
     fetchImpl;
     onUnauthorized;
     timeoutMs;
+    refreshTokenHook;
+    credentialRevision = 0;
+    pendingTokenRefresh;
     pendingChatResolutions = new Map();
     constructor(opts) {
         this.baseURL = opts.baseURL.replace(/\/+$/, "");
@@ -17,11 +21,13 @@ export class AptevaClient {
         this.fetchImpl = opts.fetch ?? globalThis.fetch.bind(globalThis);
         this.onUnauthorized = opts.onUnauthorized;
         this.timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+        this.refreshTokenHook = opts.refreshAccessToken;
     }
     // Swap the API key at runtime. An accessToken, when configured, continues
     // to take precedence. Pass undefined to fall back to access-token/cookie auth.
     setApiKey(key) {
         this.apiKey = key;
+        this.credentialRevision++;
     }
     getApiKey() {
         return this.apiKey;
@@ -31,10 +37,48 @@ export class AptevaClient {
     // Pass undefined to fall back to apiKey, then cookie auth.
     setAccessToken(token) {
         this.accessToken = token;
+        this.credentialRevision++;
     }
     getAccessToken() {
         return this.accessToken;
     }
+    /** Refresh once for concurrent callers. Undefined leaves credentials unchanged. */
+    async refreshAccessToken() {
+        if (!this.refreshTokenHook)
+            return false;
+        if (this.pendingTokenRefresh)
+            return this.pendingTokenRefresh;
+        const revision = this.credentialRevision;
+        const refresh = Promise.resolve().then(() => this.refreshTokenHook()).then((token) => {
+            // A login/logout/token replacement while refreshing always wins.
+            if (this.credentialRevision !== revision)
+                return false;
+            if (!token || token === this.accessToken)
+                return false;
+            this.setAccessToken(token);
+            return true;
+        });
+        this.pendingTokenRefresh = refresh;
+        try {
+            return await refresh;
+        }
+        finally {
+            if (this.pendingTokenRefresh === refresh)
+                this.pendingTokenRefresh = undefined;
+        }
+    }
+    async renewAfterUnauthorized(revision) {
+        if (revision !== this.credentialRevision)
+            return Boolean(this.bearerToken());
+        try {
+            return await this.refreshAccessToken();
+        }
+        catch {
+            // Preserve the original 401; callers can observe refresh errors by
+            // invoking refreshAccessToken() directly or inside their own hook.
+            return false;
+        }
+    }
     // Auth surface. Maps 1:1 onto /api/auth/*. login() sets a cookie
     // on the server side that subsequent requests pick up automatically
     // when credentials: "include" is sent.
@@ -266,30 +310,74 @@ export class AptevaClient {
     // MCP tool surface (/api/apps/<name>/mcp). T is the default return
     // type for typed route helpers — defaults to unknown so callers
     // either pass a per-call generic or stick to `unknown`.
-    app(name) {
+    app(name, scope = {}) {
+        const explicitProjectId = scope.projectId?.trim();
+        const projectId = explicitProjectId || this.projectId;
+        const installId = scope.installId;
+        if (installId !== undefined && (!Number.isSafeInteger(installId) || installId <= 0)) {
+            throw new AptevaError(0, "installId must be a positive safe integer");
+        }
         const base = `/api/apps/${encodeURIComponent(name)}`;
+        const scopedPath = (path) => {
+            if (!path.startsWith("/") || path.startsWith("//")) {
+                throw new AptevaError(0, "app paths must start with a single slash");
+            }
+            const url = new URL(base + path, "http://_");
+            if (!url.pathname.startsWith(base + "/")) {
+                throw new AptevaError(0, "app path must stay within the app");
+            }
+            // An explicit handle scope wins over per-request query parameters.
+            // Preserve legacy query overrides when only the client default is set.
+            if (explicitProjectId)
+                url.searchParams.set("project_id", projectId);
+            else if (projectId && !url.searchParams.has("project_id"))
+                url.searchParams.set("project_id", projectId);
+            if (installId !== undefined)
+                url.searchParams.set("install_id", String(installId));
+            return url.pathname + url.search;
+        };
         return {
             name,
-            get: (path) => this.get(this.appPath(base + path)),
-            post: (path, body) => this.post(this.appPath(base + path), body),
-            put: (path, body) => this.put(this.appPath(base + path), body),
-            patch: (path, body) => this.patch(this.appPath(base + path), body),
-            del: (path) => this.del(this.appPath(base + path)),
-            tool: (toolName, args = {}) => this.callTool(name, toolName, args),
+            projectId,
+            installId,
+            get: (path, init) => this.get(scopedPath(path), init),
+            post: (path, body, init) => this.post(scopedPath(path), body, init),
+            put: (path, body, init) => this.put(scopedPath(path), body, init),
+            patch: (path, body, init) => this.patch(scopedPath(path), body, init),
+            del: (path, init) => this.del(scopedPath(path), init),
+            tool: async (toolName, args = {}, init) => {
+                const env = await this.post(scopedPath("/mcp"), {
+                    jsonrpc: "2.0", id: 1, method: "tools/call",
+                    params: { name: toolName, arguments: args },
+                }, init);
+                return unwrapMCP(env);
+            },
+            subscribe: (path, onEvent, opts) => this.subscribe(scopedPath(path), undefined, onEvent, opts),
             mcpURL: (queryParams) => {
-                const u = new URL(this.baseURL + this.appPath(base + "/mcp"), "http://_");
-                if (queryParams) {
-                    for (const [k, v] of Object.entries(queryParams)) {
-                        u.searchParams.set(k, v);
-                    }
-                }
-                return this.baseURL ? this.baseURL + u.pathname + u.search : u.pathname + u.search;
+                const url = new URL(scopedPath("/mcp"), "http://_");
+                for (const [key, value] of Object.entries(queryParams ?? {}))
+                    url.searchParams.set(key, value);
+                return this.baseURL + scopedPath(`/mcp${url.search}`);
             },
         };
     }
+    /** Create an extension instance. Retain it in the host; use() does not cache. */
+    use(extension, scope) {
+        return extension.create({ app: this.app(extension.app, scope) });
+    }
+    apps = {
+        /** Load an installed app’s bundled client and optional React UI. */
+        load: (name, options) => loadAppFrontend(this.app(name, options), options),
+        /** Requires the platform's existing app-list permission. No auth bypass. */
+        list: (scope = {}, init) => {
+            const projectId = scope.projectId ?? this.projectId;
+            const query = projectId ? `?project_id=${encodeURIComponent(projectId)}` : "";
+            return this.get(`/api/apps${query}`, init);
+        },
+    };
     // Lower-level direct MCP call. Most callers should use
     // client.app("name").tool("name", args) which routes through this.
-    async callTool(appName, toolName, args) {
+    async callTool(appName, toolName, args, init) {
         const path = this.appPath(`/api/apps/${encodeURIComponent(appName)}/mcp`);
         const body = {
             jsonrpc: "2.0",
@@ -297,7 +385,7 @@ export class AptevaClient {
             method: "tools/call",
             params: { name: toolName, arguments: args },
         };
-        const env = await this.post(path, body);
+        const env = await this.post(path, body, init);
         return unwrapMCP(env);
     }
     // --- raw HTTP helpers (exposed so consumers can hit endpoints the
@@ -346,14 +434,30 @@ export class AptevaClient {
     // Node note: needs a global EventSource (Node 22+, browsers, Deno, Bun)
     // or an injected one via opts.EventSource.
     subscribe(path, params, onEvent, opts) {
+        if (opts?.signal?.aborted)
+            return { close() { } };
+        if (opts?.reconnectDelayMs !== undefined && (!Number.isFinite(opts.reconnectDelayMs) || opts.reconnectDelayMs < 0)) {
+            throw new AptevaError(0, "reconnectDelayMs must be a non-negative finite number");
+        }
+        if (opts?.deduplicationWindow !== undefined && (!Number.isSafeInteger(opts.deduplicationWindow) || opts.deduplicationWindow < 1)) {
+            throw new AptevaError(0, "deduplicationWindow must be a positive safe integer");
+        }
+        if (opts?.cursorParam && ["project_id", "install_id", "api_key", "access_token"].includes(opts.cursorParam)) {
+            throw new AptevaError(0, "cursorParam must not override routing or credentials");
+        }
+        if (opts?.lastEventId && /[\r\n\0]/.test(opts.lastEventId)) {
+            throw new AptevaError(0, "lastEventId must not contain CR, LF or NUL");
+        }
         // A supplied EventSource is an explicit transport choice for cookie/sk-
         // clients (and is useful for tests/polyfills). Access tokens always use
         // fetch because they must stay in the Authorization header. Prefix-based
         // detection remains only as a compatibility fallback for legacy callers
         // that passed a delegated token through apiKey.
         const bearerToken = this.bearerToken();
-        if (bearerToken && (this.isAccessTokenCredential() || !opts?.EventSource)) {
-            return this.subscribeWithFetch(path, params, onEvent, opts);
+        if (opts?.transport === "fetch" || opts?.lastEventId !== undefined || opts?.cursorParam ||
+            opts?.deduplicate || opts?.reconnectDelayMs !== undefined ||
+            (bearerToken && (this.isAccessTokenCredential() || !opts?.EventSource))) {
+            return this.bindAbortSignal(this.subscribeWithFetch(path, params, onEvent, opts), opts?.signal);
         }
         const Ctor = opts?.EventSource ??
             globalThis.EventSource;
@@ -362,6 +466,7 @@ export class AptevaClient {
         }
         const url = this.sseURL(path, params);
         const es = new Ctor(url, { withCredentials: true });
+        let closed = false;
         // Default event name "message" handles unnamed (default) frames.
         // Servers that emit named events (`event: foo\n`) need their
         // names listed in opts.eventTypes — EventSource won't deliver
@@ -369,6 +474,8 @@ export class AptevaClient {
         // example sends StreamFrame as `event: stream`.
         const eventTypes = opts?.eventTypes ?? ["message"];
         const handle = (ev) => {
+            if (closed)
+                return;
             const data = ev?.data;
             if (typeof data !== "string" || data === "")
                 return;
@@ -379,18 +486,26 @@ export class AptevaClient {
             catch {
                 return; // drop malformed frame
             }
-            onEvent(parsed);
+            const event = ev;
+            onEvent(parsed, { event: event.type || "message", id: event.lastEventId || undefined });
         };
         for (const name of eventTypes) {
             es.addEventListener(name, handle);
         }
         if (opts?.onOpen) {
-            es.addEventListener("open", opts.onOpen);
+            es.addEventListener("open", () => { if (!closed)
+                opts.onOpen?.(); });
         }
         if (opts?.onError) {
-            es.addEventListener("error", opts.onError);
+            es.addEventListener("error", (error) => { if (!closed)
+                opts.onError?.(error); });
         }
-        return { close: () => es.close() };
+        return this.bindAbortSignal({ close: () => {
+                if (closed)
+                    return;
+                closed = true;
+                es.close();
+            } }, opts?.signal);
     }
     subscribeWithFetch(path, params, onEvent, opts) {
         let closed = false;
@@ -398,10 +513,31 @@ export class AptevaClient {
         let reader;
         let reconnectTimer;
         let wakeReconnect;
+        let lastEventId = opts?.lastEventId ?? "";
+        let renewedSinceOpen = false;
+        const delivered = new Set();
         const eventTypes = new Set(opts?.eventTypes ?? ["message"]);
+        const close = () => {
+            if (closed)
+                return;
+            closed = true;
+            void reader?.cancel().catch(() => undefined);
+            controller?.abort();
+            if (reconnectTimer !== undefined)
+                clearTimeout(reconnectTimer);
+            wakeReconnect?.();
+        };
+        const reportError = (error) => {
+            try {
+                opts?.onError?.(error);
+            }
+            catch {
+                close();
+            }
+        };
         const waitToReconnect = () => new Promise((resolve) => {
             wakeReconnect = resolve;
-            reconnectTimer = setTimeout(resolve, 1_000);
+            reconnectTimer = setTimeout(resolve, opts?.reconnectDelayMs ?? 1_000);
         }).finally(() => {
             reconnectTimer = undefined;
             wakeReconnect = undefined;
@@ -409,85 +545,150 @@ export class AptevaClient {
         const run = async () => {
             while (!closed) {
                 controller = new AbortController();
+                const revision = this.credentialRevision;
                 try {
                     const url = new URL(this.baseURL + path, "http://_");
-                    if (params) {
-                        for (const [key, value] of Object.entries(params)) {
-                            if (value !== undefined && value !== "") {
-                                url.searchParams.set(key, String(value));
-                            }
-                        }
+                    for (const [key, value] of Object.entries(params ?? {})) {
+                        if (value !== undefined && value !== "")
+                            url.searchParams.set(key, String(value));
                     }
-                    const requestURL = this.baseURL
-                        ? this.baseURL + url.pathname + url.search
-                        : url.pathname + url.search;
+                    if (opts?.cursorParam && lastEventId)
+                        url.searchParams.set(opts.cursorParam, lastEventId);
                     const headers = new Headers({ Accept: "text/event-stream" });
                     const bearerToken = this.bearerToken();
                     if (bearerToken)
                         headers.set("Authorization", `Bearer ${bearerToken}`);
-                    const response = await this.fetchImpl(requestURL, {
-                        method: "GET",
-                        headers,
+                    if (lastEventId)
+                        headers.set("Last-Event-ID", lastEventId);
+                    const response = await this.fetchImpl(this.baseURL + url.pathname + url.search, {
+                        method: "GET", headers,
                         credentials: this.isAccessTokenCredential() ? "omit" : "include",
                         signal: controller.signal,
                     });
+                    if (closed) {
+                        await response.body?.cancel();
+                        break;
+                    }
                     if (!response.ok) {
-                        if (response.status === 401)
+                        await response.body?.cancel();
+                        if (response.status === 401) {
+                            const renewed = !renewedSinceOpen && await this.renewAfterUnauthorized(revision);
+                            renewedSinceOpen = renewed;
+                            if (closed)
+                                break;
                             this.onUnauthorized?.();
+                            reportError(new AptevaError(401, "SSE connection failed (401)"));
+                            if (!renewed) {
+                                close();
+                                break;
+                            }
+                            continue;
+                        }
+                        if (response.status === 403) {
+                            reportError(new AptevaError(403, "SSE connection failed (403)"));
+                            close();
+                            break;
+                        }
                         throw new AptevaError(response.status, `SSE connection failed (${response.status})`);
                     }
+                    if (response.status === 204) {
+                        await response.body?.cancel();
+                        close();
+                        break;
+                    }
                     if (!response.body)
                         throw new AptevaError(0, "SSE response has no body");
-                    opts?.onOpen?.();
+                    renewedSinceOpen = false;
                     reader = response.body.getReader();
+                    try {
+                        opts?.onOpen?.();
+                    }
+                    catch (error) {
+                        reportError(error);
+                        close();
+                        break;
+                    }
                     const decoder = new TextDecoder();
                     let buffer = "";
+                    let skipLF = false;
                     let eventName = "message";
+                    let frameId;
                     let dataLines = [];
                     const dispatch = () => {
-                        if (dataLines.length === 0) {
-                            eventName = "message";
-                            return;
-                        }
+                        const name = eventName;
+                        const id = frameId;
                         const data = dataLines.join("\n");
+                        const hasData = dataLines.length > 0;
                         dataLines = [];
-                        const name = eventName;
                         eventName = "message";
-                        if (!eventTypes.has(name))
+                        frameId = undefined;
+                        if (id !== undefined)
+                            lastEventId = id;
+                        if (!hasData || !eventTypes.has(name) || closed)
                             return;
+                        let payload;
                         try {
-                            onEvent(JSON.parse(data));
+                            payload = JSON.parse(data);
                         }
                         catch {
-                            // One malformed frame must not end a best-effort stream.
+                            return;
+                        }
+                        if (opts?.deduplicate && id && delivered.has(id))
+                            return;
+                        // IDs identify individual events only when the app promises that.
+                        if (opts?.deduplicate && id) {
+                            delivered.add(id);
+                            if (delivered.size > (opts.deduplicationWindow ?? 1000)) {
+                                delivered.delete(delivered.values().next().value);
+                            }
+                        }
+                        try {
+                            onEvent(payload, { event: name, id: lastEventId || undefined });
+                        }
+                        catch (error) {
+                            reportError(error);
+                            close();
                         }
                     };
+                    const line = (value) => {
+                        if (!value) {
+                            dispatch();
+                            return;
+                        }
+                        if (value.startsWith(":"))
+                            return;
+                        const separator = value.indexOf(":");
+                        const field = separator < 0 ? value : value.slice(0, separator);
+                        let content = separator < 0 ? "" : value.slice(separator + 1);
+                        if (content.startsWith(" "))
+                            content = content.slice(1);
+                        if (field === "event")
+                            eventName = content || "message";
+                        if (field === "data")
+                            dataLines.push(content);
+                        if (field === "id" && !content.includes("\0"))
+                            frameId = content;
+                    };
                     while (!closed) {
                         const chunk = await reader.read();
-                        if (chunk.done)
+                        if (chunk.done || closed)
                             break;
-                        buffer += decoder.decode(chunk.value, { stream: true });
-                        let newline = buffer.indexOf("\n");
-                        while (newline >= 0) {
-                            let line = buffer.slice(0, newline);
-                            buffer = buffer.slice(newline + 1);
-                            if (line.endsWith("\r"))
-                                line = line.slice(0, -1);
-                            if (line === "") {
-                                dispatch();
+                        // Handles LF, CRLF and CR, including CRLF split across chunks.
+                        for (const char of decoder.decode(chunk.value, { stream: true })) {
+                            if (closed)
+                                break;
+                            if (skipLF && char === "\n") {
+                                skipLF = false;
+                                continue;
                             }
-                            else if (!line.startsWith(":")) {
-                                const separator = line.indexOf(":");
-                                const field = separator >= 0 ? line.slice(0, separator) : line;
-                                let value = separator >= 0 ? line.slice(separator + 1) : "";
-                                if (value.startsWith(" "))
-                                    value = value.slice(1);
-                                if (field === "event")
-                                    eventName = value || "message";
-                                if (field === "data")
-                                    dataLines.push(value);
+                            skipLF = false;
+                            if (char === "\r" || char === "\n") {
+                                line(buffer);
+                                buffer = "";
+                                skipLF = char === "\r";
                             }
-                            newline = buffer.indexOf("\n");
+                            else
+                                buffer += char;
                         }
                     }
                     if (!closed)
@@ -495,12 +696,18 @@ export class AptevaClient {
                 }
                 catch (error) {
                     if (closed)
-                        return;
-                    opts?.onError?.(error);
+                        break;
+                    reportError(error);
                 }
                 finally {
-                    reader?.releaseLock();
-                    reader = undefined;
+                    if (reader) {
+                        try {
+                            await reader.cancel();
+                        }
+                        catch { /* network already closed */ }
+                        reader.releaseLock();
+                        reader = undefined;
+                    }
                     controller = undefined;
                 }
                 if (!closed)
@@ -508,25 +715,16 @@ export class AptevaClient {
             }
         };
         void run();
-        return {
-            close: () => {
-                if (closed)
-                    return;
-                closed = true;
-                const activeReader = reader;
-                void activeReader?.cancel().catch(() => undefined);
-                controller?.abort();
-                if (reconnectTimer !== undefined)
-                    clearTimeout(reconnectTimer);
-                wakeReconnect?.();
-            },
-        };
+        return { close };
     }
     // --- internals ---
     bindAbortSignal(handle, signal) {
         if (!signal)
             return handle;
-        const abort = () => handle.close();
+        const abort = () => {
+            signal.removeEventListener("abort", abort);
+            handle.close();
+        };
         if (signal.aborted) {
             handle.close();
             return handle;
@@ -556,6 +754,7 @@ export class AptevaClient {
     }
     async request(method, path, body, init) {
         const url = this.baseURL + path;
+        const revision = this.credentialRevision;
         const headers = new Headers(init?.headers);
         if (!headers.has("Accept"))
             headers.set("Accept", "application/json");
@@ -567,12 +766,16 @@ export class AptevaClient {
             headers.set("Authorization", `Bearer ${bearerToken}`);
         }
         const ac = this.timeoutMs > 0 ? new AbortController() : undefined;
+        const abort = () => ac?.abort(init?.signal?.reason);
+        if (init?.signal?.aborted)
+            abort();
+        else
+            init?.signal?.addEventListener("abort", abort, { once: true });
         const timer = ac
             ? setTimeout(() => ac.abort(), this.timeoutMs)
             : undefined;
-        let res;
         try {
-            res = await this.fetchImpl(url, {
+            const res = await this.fetchImpl(url, {
                 method,
                 credentials: this.isAccessTokenCredential() ? "omit" : "include",
                 ...init,
@@ -580,33 +783,39 @@ export class AptevaClient {
                 body: body === undefined ? init?.body : JSON.stringify(body),
                 signal: ac?.signal ?? init?.signal,
             });
+            if (res.status === 401) {
+                const text = await readBody(res);
+                // Renew for subsequent calls, but never replay an HTTP operation.
+                if (!new Headers(init?.headers).has("Authorization"))
+                    await this.renewAfterUnauthorized(revision);
+                this.onUnauthorized?.();
+                throw new AptevaError(401, text || "unauthorized");
+            }
+            if (!res.ok) {
+                const text = await readBody(res);
+                throw new AptevaError(res.status, text || res.statusText);
+            }
+            if (res.status === 204)
+                return undefined;
+            const ct = res.headers.get("Content-Type") ?? "";
+            if (ct.includes("application/json"))
+                return (await res.json());
+            return (await res.text());
         }
         catch (err) {
-            if (timer)
-                clearTimeout(timer);
-            if (err instanceof Error && err.name === "AbortError") {
+            if (err instanceof AptevaError)
+                throw err;
+            if (init?.signal?.aborted)
+                throw new AptevaError(0, "request aborted");
+            if (ac?.signal.aborted)
                 throw new AptevaError(0, `request timeout after ${this.timeoutMs}ms`);
-            }
             throw new AptevaError(0, err instanceof Error ? err.message : String(err));
         }
-        if (timer)
-            clearTimeout(timer);
-        if (res.status === 401) {
-            this.onUnauthorized?.();
-            const text = await readBody(res);
-            throw new AptevaError(401, text || "unauthorized");
-        }
-        if (!res.ok) {
-            const text = await readBody(res);
-            throw new AptevaError(res.status, text || res.statusText);
-        }
-        const ct = res.headers.get("Content-Type") ?? "";
-        if (res.status === 204)
-            return undefined;
-        if (ct.includes("application/json")) {
-            return (await res.json());
+        finally {
+            if (timer)
+                clearTimeout(timer);
+            init?.signal?.removeEventListener("abort", abort);
         }
-        return (await res.text());
     }
 }
 async function readBody(res) {