appilot 0.0.1 → 0.1.1

package/dist/widget/boot.js

@@ -0,0 +1,313 @@
+/**
+ * Appilot widget boot: load the embeddable assistant into a host app with an
+ * identified user token, and keep it authenticated for the life of the page.
+ *
+ * The host app owns identity: it exposes a backend RELAY endpoint that mints an
+ * identified widget token (so the widget key never sees the end user's
+ * credentials), and this boot loader POSTs to it, then loads the widget bundle
+ * with the returned token.
+ *
+ * Design guarantees:
+ * - Boot does not latch on failure: a failed relay or bundle load returns
+ *   availability to 'unavailable' and a later bootAppilotWidget() call retries
+ *   from scratch (one hiccup never permanently disables the assistant).
+ * - The widget token (TTL ~3600s) is re-relayed at ~80% of its TTL and handed
+ *   to the live instance through `window.Appilot.setUserToken`, so a long-lived
+ *   tab never starts 401ing on a healthy host session. The refreshed token is
+ *   NOT written back to the DOM (see "The token and the DOM" below).
+ * - The widget can request an out-of-band refresh by dispatching
+ *   'appilot:identity-refresh-requested' on window (it does so when its
+ *   federated identity is rejected); the loader re-relays immediately.
+ * - When the host supplies `getBearer` and it returns null (the host session
+ *   is gone), the scheduled refresh does NOT call the relay: relaying without
+ *   a bearer would mint whatever fallback identity the endpoint assigns,
+ *   silently swapping the signed-in user for a default persona. The loader
+ *   retries until the host session is back.
+ * - The relay call carries a bearer supplied by the host (`getBearer`) when one
+ *   exists, so a logged-in user federates as themselves; without it the relay
+ *   falls back to whatever identity the endpoint assigns.
+ * - Availability is observable (getWidgetAvailability / subscribeWidgetAvailability)
+ *   so pages can render an honest "assistant unavailable" state. Pairs with
+ *   React useSyncExternalStore(subscribeWidgetAvailability, getWidgetAvailability).
+ *
+ * ## The token and the DOM
+ *
+ * `data-user-token` is a bearer token for the end user. Anything that can read
+ * the host page's DOM can read it and act as that person against the Appilot
+ * backend, so it must not live there.
+ *
+ * Two changes follow. The refresh no longer writes the rotated token back to
+ * the tag: `window.Appilot.setUserToken` already feeds the live instance, and a
+ * later re-boot re-relays a fresh token anyway, so the DOM write bought a
+ * hypothetical reboot path at the price of a token sitting in the page for the
+ * life of the tab, being renewed there every ~48 minutes.
+ *
+ * The boot token still passes through the attribute, because that is the only
+ * channel the shipped widget bundle reads its configuration from, and it is
+ * removed as soon as the bundle has consumed it (`releaseBootToken`). That
+ * shrinks the exposure from the lifetime of the page to the interval between
+ * appending the script and the bundle parsing its config. Closing it entirely
+ * needs the widget to accept a non-DOM handoff; until then, treat the boot
+ * token as short-lived and keep the relay's TTL short.
+ */
+const DEFAULT_APPILOT_API_URL = 'http://localhost:6001';
+/** Dispatched by the widget when its federated identity is rejected (401),
+ *  asking the loader for an immediate re-relay instead of waiting for the
+ *  scheduled ~80%-TTL refresh. Mirror of the widget's WidgetSDK constant. */
+const IDENTITY_REFRESH_REQUESTED_EVENT = 'appilot:identity-refresh-requested';
+const DEFAULT_TOKEN_ENDPOINT = '/api/widget/token';
+const DEFAULT_TOKEN_TTL_SECONDS = 3600;
+const TOKEN_REFRESH_FRACTION = 0.8;
+const REFRESH_RETRY_MS = 60_000;
+const DEFAULT_BOOT_TIMEOUT_MS = 10_000;
+let availability = 'unknown';
+const listeners = new Set();
+let scriptEl = null;
+let refreshTimer = null;
+let bootTimer = null;
+let bootAbortController = null;
+let activeAttempt = 0;
+let warnedMissingConfig = false;
+let refreshRequestListener = null;
+/**
+ * Marks OUR loader tag without naming the token. The tag was previously found
+ * by `[data-user-token]`, which stops working the moment the token is removed,
+ * and this attribute is deliberately not one the widget's config parser matches
+ * (it looks for the exact names `data-api-key`, `data-user-token`,
+ * `data-appilot`).
+ */
+const LOADER_MARKER_ATTR = 'data-appilot-loader';
+/**
+ * Drop the boot token from the DOM once the widget has read its config.
+ *
+ * The bundle parses its config at module evaluation, which is over by the time
+ * `load` fires. The one exception is a document still parsing when the script
+ * executes: the widget then defers its auto-init to DOMContentLoaded, so this
+ * defers with it. Our listener is registered from inside the load handler,
+ * after the bundle registered its own, and DOMContentLoaded listeners run in
+ * registration order.
+ */
+function releaseBootToken(script) {
+    const drop = () => script.removeAttribute('data-user-token');
+    if (document.readyState === 'loading') {
+        document.addEventListener('DOMContentLoaded', drop, { once: true });
+        return;
+    }
+    drop();
+}
+function detachRefreshRequestListener() {
+    if (refreshRequestListener) {
+        window.removeEventListener(IDENTITY_REFRESH_REQUESTED_EVENT, refreshRequestListener);
+        refreshRequestListener = null;
+    }
+}
+function attachRefreshRequestListener(options) {
+    detachRefreshRequestListener();
+    refreshRequestListener = () => {
+        clearRefreshTimer();
+        void refreshWidgetToken(options);
+    };
+    window.addEventListener(IDENTITY_REFRESH_REQUESTED_EVENT, refreshRequestListener);
+}
+function setAvailability(next) {
+    if (availability === next)
+        return;
+    availability = next;
+    for (const listener of listeners)
+        listener(next);
+}
+export function getWidgetAvailability() {
+    return availability;
+}
+/** Subscribe to availability changes. Returns the unsubscribe function. */
+export function subscribeWidgetAvailability(listener) {
+    listeners.add(listener);
+    return () => {
+        listeners.delete(listener);
+    };
+}
+async function relayWidgetToken(options, signal) {
+    const endpoint = options.tokenEndpoint ?? DEFAULT_TOKEN_ENDPOINT;
+    // The host bearer lets the relay federate the LOGGED-IN user instead of a
+    // default identity; without it the relay assigns whatever identity it wants.
+    const bearer = options.getBearer?.() ?? null;
+    const response = await fetch(endpoint, {
+        method: 'POST',
+        signal,
+        headers: {
+            ...(bearer ? { Authorization: `Bearer ${bearer}` } : {}),
+            ...(options.tokenBody !== undefined ? { 'Content-Type': 'application/json' } : {}),
+        },
+        ...(options.tokenBody !== undefined ? { body: JSON.stringify(options.tokenBody) } : {}),
+    });
+    if (!response.ok) {
+        throw new Error(`widget token relay responded ${response.status}`);
+    }
+    return (await response.json());
+}
+function clearRefreshTimer() {
+    if (refreshTimer !== null) {
+        clearTimeout(refreshTimer);
+        refreshTimer = null;
+    }
+}
+function clearBootTimer() {
+    if (bootTimer !== null) {
+        clearTimeout(bootTimer);
+        bootTimer = null;
+    }
+}
+function hasRequiredWidgetApi() {
+    return typeof window.Appilot?.open === 'function';
+}
+function cleanFailedAttempt(attempt, script) {
+    if (attempt !== activeAttempt) {
+        script?.remove();
+        return;
+    }
+    activeAttempt += 1;
+    clearBootTimer();
+    clearRefreshTimer();
+    detachRefreshRequestListener();
+    bootAbortController?.abort();
+    bootAbortController = null;
+    const target = script ?? scriptEl;
+    target?.remove();
+    if (!target || scriptEl === target)
+        scriptEl = null;
+    setAvailability('unavailable');
+}
+function scheduleTokenRefresh(expiresIn, options) {
+    clearRefreshTimer();
+    const ttl = expiresIn && expiresIn > 0 ? expiresIn : DEFAULT_TOKEN_TTL_SECONDS;
+    refreshTimer = setTimeout(() => {
+        void refreshWidgetToken(options);
+    }, ttl * TOKEN_REFRESH_FRACTION * 1000);
+}
+async function refreshWidgetToken(options) {
+    // Host session gone: do NOT hit the relay bearerless. The relay would fall
+    // back to its default identity (dev personas in development), silently
+    // swapping the federated user on the next token. Wait for the session to
+    // come back (login) and retry; the widget shows its own identity-expired
+    // state in the meantime.
+    if (options.getBearer && !options.getBearer()) {
+        clearRefreshTimer();
+        refreshTimer = setTimeout(() => {
+            void refreshWidgetToken(options);
+        }, REFRESH_RETRY_MS);
+        return;
+    }
+    try {
+        const relayed = await relayWidgetToken(options);
+        // The rotated token goes to the live instance ONLY. Writing it back to
+        // the loader tag put a live bearer token for the signed-in user in the
+        // host page's DOM, readable by every script on the page, and refreshed
+        // there for as long as the tab stayed open.
+        // (`window.Appilot.setUserToken`, widget >= 2026-08-25.)
+        const appilot = window.Appilot;
+        appilot?.setUserToken?.(relayed.token);
+        scheduleTokenRefresh(relayed.expiresIn, options);
+    }
+    catch (error) {
+        console.warn('[appilot] widget token refresh failed; retrying shortly', error);
+        clearRefreshTimer();
+        refreshTimer = setTimeout(() => {
+            void refreshWidgetToken(options);
+        }, REFRESH_RETRY_MS);
+    }
+}
+export async function bootAppilotWidget(options) {
+    // Idempotent while healthy; 'unavailable' deliberately falls through so a
+    // later call retries after a failure.
+    if (availability === 'booting' || availability === 'ready')
+        return;
+    const label = options.surfaceLabel ?? 'assistant';
+    if (!options.widgetScriptUrl) {
+        if (!warnedMissingConfig) {
+            warnedMissingConfig = true;
+            console.warn(`[appilot] widget script URL is not configured; ${label} disabled`);
+        }
+        setAvailability('unavailable');
+        return;
+    }
+    setAvailability('booting');
+    const attempt = ++activeAttempt;
+    bootAbortController?.abort();
+    bootAbortController = new AbortController();
+    clearBootTimer();
+    bootTimer = setTimeout(() => {
+        if (attempt !== activeAttempt)
+            return;
+        console.warn(`[appilot] widget boot timed out; ${label} disabled`);
+        cleanFailedAttempt(attempt);
+    }, options.timeoutMs ?? DEFAULT_BOOT_TIMEOUT_MS);
+    let relayed;
+    try {
+        relayed = await relayWidgetToken(options, bootAbortController.signal);
+    }
+    catch (error) {
+        if (attempt !== activeAttempt)
+            return;
+        console.warn(`[appilot] widget token relay unavailable; ${label} disabled`, error);
+        cleanFailedAttempt(attempt);
+        return;
+    }
+    if (attempt !== activeAttempt)
+        return;
+    const script = document.createElement('script');
+    script.src = options.widgetScriptUrl;
+    script.async = true;
+    script.setAttribute(LOADER_MARKER_ATTR, '');
+    if (options.widgetKey)
+        script.dataset.apiKey = options.widgetKey;
+    script.dataset.apiUrl = options.appilotApiUrl || DEFAULT_APPILOT_API_URL;
+    script.dataset.userToken = relayed.token;
+    if (options.brandName)
+        script.dataset.brandName = options.brandName;
+    script.dataset.position = options.position ?? 'bottom-right';
+    script.dataset.theme = options.theme ?? 'host';
+    script.dataset.language = options.language ?? 'en';
+    script.addEventListener('load', () => {
+        if (attempt !== activeAttempt) {
+            script.remove();
+            return;
+        }
+        if (!hasRequiredWidgetApi()) {
+            console.warn(`[appilot] widget bundle loaded without its panel API; ${label} disabled`);
+            cleanFailedAttempt(attempt, script);
+            return;
+        }
+        clearBootTimer();
+        bootAbortController = null;
+        setAvailability('ready');
+        // The bundle has its config; the token has no further reason to be in
+        // the page.
+        releaseBootToken(script);
+        scheduleTokenRefresh(relayed.expiresIn, options);
+        attachRefreshRequestListener(options);
+    });
+    script.addEventListener('error', () => {
+        if (attempt !== activeAttempt) {
+            script.remove();
+            return;
+        }
+        console.warn(`[appilot] widget bundle failed to load; ${label} disabled`);
+        cleanFailedAttempt(attempt, script);
+    });
+    document.head.appendChild(script);
+    scriptEl = script;
+}
+/** Test-only: reset module state between tests. Never call from app code. */
+export function __resetAppilotWidgetForTests() {
+    activeAttempt += 1;
+    clearBootTimer();
+    bootAbortController?.abort();
+    bootAbortController = null;
+    clearRefreshTimer();
+    detachRefreshRequestListener();
+    scriptEl?.remove();
+    scriptEl = null;
+    listeners.clear();
+    availability = 'unknown';
+    warnedMissingConfig = false;
+}

package/package.json

@@ -1,17 +1,52 @@
 {
-	"name": "appilot",
-	"version": "0.0.1",
-	"description": "Name reservation for the Appilot SDK. The published SDK will land here.",
-	"keywords": ["appilot", "webmcp", "agent", "assistant", "widget"],
-	"homepage": "https://appilot.space",
-	"license": "ISC",
-	"author": "BetterKnow GmbH",
-	"files": ["README.md"],
-	"publishConfig": {
-		"access": "public",
-		"registry": "https://registry.npmjs.org/"
-	},
-	"engines": {
-		"node": ">=18"
-	}
-}
+  "name": "appilot",
+  "version": "0.1.1",
+  "description": "Appilot SDK: the single developer-facing surface for building on Appilot. Boot the assistant (bootAppilotWidget), register client actions (registerTool, WebMCP-aligned), and run Focused Sessions (startFocusedSession). Browser-only, React-free, zero runtime dependencies.",
+  "homepage": "https://appilot.space",
+  "author": "BetterKnow GmbH",
+  "keywords": [
+    "appilot",
+    "webmcp",
+    "agent",
+    "assistant",
+    "widget",
+    "sdk"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./runtime": {
+      "types": "./dist/runtime.d.ts",
+      "default": "./dist/runtime.js"
+    }
+  },
+  "sideEffects": false,
+  "files": [
+    "dist"
+  ],
+  "devDependencies": {
+    "jsdom": "^26.1.0",
+    "typescript": "^5.5.0",
+    "vitest": "^2.0.0"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "license": "ISC",
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "type-check": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
+}