lemma-sdk 0.2.3 → 0.2.5

package/README.md

@@ -8,6 +8,12 @@ Official TypeScript SDK for Lemma APIs with pod-scoped namespaces, auth helpers,
 npm i lemma-sdk
 ```
 
+For local workspace development against the checked-out SDK instead of npm:
+
+```bash
+npm i file:../lemma-typescript
+```
+
 If you want to import as `lemma`, use npm aliasing:
 
 ```bash
@@ -39,6 +45,69 @@ const supportAssistant = await client.assistants.get("support_assistant");
 - `client.request(method, path, options)` escape hatch for endpoints not yet modeled.
 - `client.resources` for generic file resource APIs (`conversation`, `assistant`, `task`, etc.).
 - Ergonomic type aliases exported at top level: `Agent`, `Assistant`, `Conversation`, `Task`, `TaskMessage`, `CreateAgentInput`, `CreateAssistantInput`, etc.
+- `client.withPod(podId)` returns a pod-scoped client that shares auth state with the parent client.
+
+## Auth Helpers
+
+```ts
+import { LemmaClient, buildAuthUrl, resolveSafeRedirectUri } from "lemma-sdk";
+
+const client = new LemmaClient({
+  apiUrl: "https://api-next.asur.work",
+  authUrl: "https://auth.asur.work/auth",
+});
+
+// Build auth URLs (server/client)
+const loginUrl = buildAuthUrl(client.authUrl, { redirectUri: "https://app.asur.work/" });
+const signupUrl = buildAuthUrl(client.authUrl, { mode: "signup", redirectUri: "https://app.asur.work/" });
+
+// Redirect safety helper for auth route handlers
+const safeRedirect = resolveSafeRedirectUri("/pod/123", {
+  siteOrigin: "https://app.asur.work",
+  fallback: "/",
+});
+
+// Browser helpers
+await client.auth.checkAuth();
+await client.auth.signOut();
+const token = await client.auth.getAccessToken();
+const refreshed = await client.auth.refreshAccessToken();
+client.auth.redirectToAuth({ mode: "signup", redirectUri: safeRedirect });
+```
+
+### Browser Testing With Injected Token
+
+For desk and app testing, the SDK supports a fixed bearer token injected through localStorage.
+This is the only supported browser token-injection path.
+
+```ts
+import { LemmaClient, setTestingToken, clearTestingToken } from "lemma-sdk";
+
+setTestingToken("<access-token>");
+
+const client = new LemmaClient({
+  apiUrl: "/api",
+  authUrl: "http://localhost:4173",
+  podId: "<pod-id>",
+});
+
+await client.initialize();
+
+clearTestingToken();
+```
+
+Equivalent manual browser setup:
+
+```js
+localStorage.setItem("lemma_token", "<access-token>");
+window.location.reload();
+```
+
+Notes:
+
+- do not pass testing tokens in query parameters
+- prefer a same-origin dev proxy such as Vite `/api` during local browser testing to avoid CORS on `/users/me`
+- production auth should use the normal cookie/session flow
 
 ## Assistants + Agent Runs
 
@@ -104,6 +173,21 @@ Import from `lemma-sdk/react`:
 - `AuthGuard`
 - `useAgentRunStream(...)`
 - `useAssistantRun(...)`
+- `useAssistantSession(...)`
+- `useTaskSession(...)`
+- `useFunctionSession(...)`
+- `useFlowSession(...)`
+
+Core run helpers from `lemma-sdk`:
+
+- `normalizeRunStatus(...)`
+- `isTerminalTaskStatus(...)`
+- `isTerminalFunctionStatus(...)`
+- `isTerminalFlowStatus(...)`
+- `parseTaskStreamEvent(...)`
+- `upsertTaskMessage(...)`
+- `parseAssistantStreamEvent(...)`
+- `upsertConversationMessage(...)`
 
 Example:
 
@@ -120,6 +204,10 @@ const { sendMessage, stop, isStreaming } = useAssistantRun({
 });
 ```
 
+For the SDK consumption UI roadmap (AssistantChat / FunctionInvokeForm / FlowRunExperience / RunPanel), see:
+
+- `docs/sdk-consumption-ui-v2.md`
+
 ## File Resources
 
 ```ts

package/dist/assistant-events.d.ts

@@ -0,0 +1,7 @@
+import type { ConversationMessage } from "./types.js";
+export interface ParsedAssistantStreamEvent {
+    message?: ConversationMessage;
+    status?: string;
+}
+export declare function parseAssistantStreamEvent(value: unknown): ParsedAssistantStreamEvent;
+export declare function upsertConversationMessage(messages: ConversationMessage[], incoming: ConversationMessage): ConversationMessage[];

package/dist/assistant-events.js

@@ -0,0 +1,78 @@
+function isRecord(value) {
+    return !!value && typeof value === "object" && !Array.isArray(value);
+}
+function normalizeStatus(status) {
+    if (typeof status !== "string")
+        return undefined;
+    const normalized = status.trim().toUpperCase();
+    return normalized.length > 0 ? normalized : undefined;
+}
+function toConversationMessage(value) {
+    if (!isRecord(value))
+        return undefined;
+    if (typeof value.id !== "string")
+        return undefined;
+    if (typeof value.role !== "string")
+        return undefined;
+    if (!("content" in value))
+        return undefined;
+    const message = {
+        id: value.id,
+        role: value.role,
+        content: value.content,
+        created_at: typeof value.created_at === "string" ? value.created_at : new Date().toISOString(),
+        metadata: isRecord(value.metadata) ? value.metadata : null,
+    };
+    return message;
+}
+function extractPayload(record) {
+    if ("data" in record)
+        return record.data;
+    if ("payload" in record)
+        return record.payload;
+    return undefined;
+}
+function extractStatus(payload) {
+    if (isRecord(payload)) {
+        return normalizeStatus(payload.status)
+            ?? normalizeStatus(payload.conversation_status)
+            ?? normalizeStatus(payload.run_status)
+            ?? (isRecord(payload.conversation) ? normalizeStatus(payload.conversation.status) : undefined);
+    }
+    return normalizeStatus(payload);
+}
+export function parseAssistantStreamEvent(value) {
+    const directMessage = toConversationMessage(value);
+    if (directMessage) {
+        return { message: directMessage };
+    }
+    if (!isRecord(value)) {
+        return {};
+    }
+    const eventType = typeof value.type === "string" ? value.type.toLowerCase() : "";
+    const payload = extractPayload(value);
+    if (eventType === "message" || eventType === "message_added") {
+        const message = toConversationMessage(payload);
+        return message ? { message } : {};
+    }
+    if (eventType === "status"
+        || eventType === "conversation_status"
+        || eventType === "conversation_updated"
+        || eventType === "run_status") {
+        const status = extractStatus(payload);
+        return status ? { status } : {};
+    }
+    return {};
+}
+export function upsertConversationMessage(messages, incoming) {
+    const next = [...messages];
+    const index = next.findIndex((message) => message.id === incoming.id);
+    if (index >= 0) {
+        next[index] = incoming;
+    }
+    else {
+        next.push(incoming);
+    }
+    next.sort((a, b) => new Date(a.created_at).getTime() - new Date(b.created_at).getTime());
+    return next;
+}

package/dist/auth.d.ts

@@ -3,11 +3,10 @@
  * for agent/dev testing.
  *
  * Auth resolution order on init:
- * 1. ?lemma_token=<token> query param  (stored in memory for session)
- * 2. localStorage.getItem("lemma_token")
- * 3. Session cookie (credentials: "include") — production path
+ * 1. localStorage.getItem("lemma_token")
+ * 2. Session cookie (credentials: "include") — production path
  *
- * If a token is found in (1) or (2), all requests use Authorization: Bearer <token>.
+ * If a token is found in (1), all requests use Authorization: Bearer <token>.
  * Otherwise requests rely on cookies, and the server must set the session cookie
  * after the user authenticates at the auth service. In cookie mode we initialise
  * the SuperTokens browser SDK so fetch/XHR automatically handles anti-CSRF and
@@ -28,6 +27,30 @@ export interface AuthState {
     user: UserInfo | null;
 }
 export type AuthListener = (state: AuthState) => void;
+export type AuthRedirectMode = "login" | "signup";
+export interface BuildAuthUrlOptions {
+    /** Optional auth path segment relative to authUrl pathname, e.g. "callback" -> /auth/callback. */
+    path?: string;
+    /** Adds signup mode query, preserving existing params. */
+    mode?: AuthRedirectMode;
+    /** Redirect URI passed to auth service. */
+    redirectUri?: string;
+    /** Additional query parameters appended to auth URL. */
+    params?: Record<string, string | number | boolean | Array<string | number | boolean> | null | undefined>;
+}
+export interface ResolveSafeRedirectUriOptions {
+    /** Origin for resolving relative paths. */
+    siteOrigin: string;
+    /** Fallback path or URL when input is empty/invalid/blocked. Defaults to "/". */
+    fallback?: string;
+    /** Local paths blocked as redirect targets to avoid auth loops. */
+    blockedPaths?: string[];
+}
+export declare function setTestingToken(token: string): void;
+export declare function getTestingToken(): string | null;
+export declare function clearTestingToken(): void;
+export declare function buildAuthUrl(authUrl: string, options?: BuildAuthUrlOptions): string;
+export declare function resolveSafeRedirectUri(rawValue: string | null | undefined, options: ResolveSafeRedirectUriOptions): string;
 export declare class AuthManager {
     private readonly apiUrl;
     private readonly authUrl;
@@ -47,6 +70,23 @@ export declare class AuthManager {
     subscribe(listener: AuthListener): () => void;
     private notify;
     private setState;
+    private assertBrowserContext;
+    private getCookie;
+    private clearInjectedToken;
+    private rawSignOutViaBackend;
+    /**
+     * Check whether a cookie-backed session is active without mutating auth state.
+     */
+    isAuthenticatedViaCookie(): Promise<boolean>;
+    /**
+     * Return a browser access token from the session layer.
+     * Throws if no token is available.
+     */
+    getAccessToken(): Promise<string>;
+    /**
+     * Force a refresh-token flow and return the new access token.
+     */
+    refreshAccessToken(): Promise<string>;
     /**
      * Build request headers for an API call.
      * Uses Bearer token if one was injected, otherwise omits Authorization
@@ -63,10 +103,21 @@ export declare class AuthManager {
      * Does NOT redirect — call redirectToAuth() explicitly if desired.
      */
     markUnauthenticated(): void;
+    /**
+     * Sign out the current user session.
+     * Returns true when the session is no longer active.
+     */
+    signOut(): Promise<boolean>;
+    /**
+     * Build auth URL for login/signup/custom auth sub-path.
+     */
+    getAuthUrl(options?: BuildAuthUrlOptions): string;
     /**
      * Redirect to the auth service, passing the current URL as redirect_uri.
      * After the user authenticates, the auth service should redirect back to
      * the original URL and set the session cookie.
      */
-    redirectToAuth(): void;
+    redirectToAuth(options?: Omit<BuildAuthUrlOptions, "redirectUri"> & {
+        redirectUri?: string;
+    }): void;
 }

package/dist/auth.js

@@ -3,11 +3,10 @@
  * for agent/dev testing.
  *
  * Auth resolution order on init:
- * 1. ?lemma_token=<token> query param  (stored in memory for session)
- * 2. localStorage.getItem("lemma_token")
- * 3. Session cookie (credentials: "include") — production path
+ * 1. localStorage.getItem("lemma_token")
+ * 2. Session cookie (credentials: "include") — production path
  *
- * If a token is found in (1) or (2), all requests use Authorization: Bearer <token>.
+ * If a token is found in (1), all requests use Authorization: Bearer <token>.
  * Otherwise requests rely on cookies, and the server must set the session cookie
  * after the user authenticates at the auth service. In cookie mode we initialise
  * the SuperTokens browser SDK so fetch/XHR automatically handles anti-CSRF and
@@ -16,41 +15,131 @@
  * Auth state is determined by calling GET /users/me (user.current.get).
  * 401 → unauthenticated. 200 → authenticated.
  */
+import Session from "supertokens-web-js/recipe/session";
 import { ensureCookieSessionSupport } from "./supertokens.js";
+const DEFAULT_BLOCKED_REDIRECT_PATHS = ["/login", "/signup", "/auth"];
 const LOCALSTORAGE_TOKEN_KEY = "lemma_token";
-const QUERY_PARAM_TOKEN_KEY = "lemma_token";
-function detectInjectedToken() {
+function readStorageToken() {
     if (typeof window === "undefined")
         return null;
-    // 1. Query param — highest priority, persist to sessionStorage for this session
     try {
-        const params = new URLSearchParams(window.location.search);
-        const qpToken = params.get(QUERY_PARAM_TOKEN_KEY);
-        if (qpToken) {
-            try {
-                sessionStorage.setItem(LOCALSTORAGE_TOKEN_KEY, qpToken);
-            }
-            catch { /* ignore */ }
-            return qpToken;
-        }
+        return localStorage.getItem(LOCALSTORAGE_TOKEN_KEY);
+    }
+    catch {
+        return null;
     }
-    catch { /* ignore */ }
-    // 2. sessionStorage — survives HMR and same-tab navigation
+}
+function writeStorageToken(token) {
+    if (typeof window === "undefined")
+        return;
     try {
-        const stored = sessionStorage.getItem(LOCALSTORAGE_TOKEN_KEY);
-        if (stored)
-            return stored;
+        localStorage.setItem(LOCALSTORAGE_TOKEN_KEY, token);
+    }
+    catch {
+        // ignore storage errors
     }
-    catch { /* ignore */ }
-    // 3. localStorage — set manually by dev/agent for persistent testing
+}
+function removeStorageToken() {
+    if (typeof window === "undefined")
+        return;
     try {
-        const stored = localStorage.getItem(LOCALSTORAGE_TOKEN_KEY);
-        if (stored)
-            return stored;
+        localStorage.removeItem(LOCALSTORAGE_TOKEN_KEY);
     }
-    catch { /* ignore */ }
+    catch {
+        // ignore storage errors
+    }
+}
+export function setTestingToken(token) {
+    writeStorageToken(token);
+}
+export function getTestingToken() {
+    return readStorageToken();
+}
+export function clearTestingToken() {
+    removeStorageToken();
+}
+function detectInjectedToken() {
+    if (typeof window === "undefined")
+        return null;
+    // 1. localStorage — the only supported browser testing path
+    const localToken = readStorageToken();
+    if (localToken)
+        return localToken;
     return null;
 }
+function normalizePath(path) {
+    const trimmed = path.trim();
+    if (!trimmed)
+        return "/";
+    if (trimmed === "/")
+        return "/";
+    const withLeadingSlash = trimmed.startsWith("/") ? trimmed : `/${trimmed}`;
+    return withLeadingSlash.endsWith("/") ? withLeadingSlash.slice(0, -1) : withLeadingSlash;
+}
+function resolveAuthPath(basePath, path) {
+    const normalizedBase = normalizePath(basePath);
+    if (!path || !path.trim()) {
+        return normalizedBase;
+    }
+    const segment = path.trim().replace(/^\/+/, "");
+    if (!segment) {
+        return normalizedBase;
+    }
+    return `${normalizedBase}/${segment}`.replace(/\/{2,}/g, "/");
+}
+function isBlockedLocalPath(pathname, blockedPaths) {
+    const normalizedPathname = normalizePath(pathname);
+    return blockedPaths.some((rawBlockedPath) => {
+        const blockedPath = normalizePath(rawBlockedPath);
+        return normalizedPathname === blockedPath || normalizedPathname.startsWith(`${blockedPath}/`);
+    });
+}
+function normalizeOrigin(rawOrigin) {
+    const parsed = new URL(rawOrigin);
+    return parsed.origin;
+}
+export function buildAuthUrl(authUrl, options = {}) {
+    const url = new URL(authUrl);
+    url.pathname = resolveAuthPath(url.pathname, options.path);
+    for (const [key, value] of Object.entries(options.params ?? {})) {
+        if (value === null || value === undefined)
+            continue;
+        if (Array.isArray(value)) {
+            url.searchParams.delete(key);
+            for (const item of value) {
+                url.searchParams.append(key, String(item));
+            }
+            continue;
+        }
+        url.searchParams.set(key, String(value));
+    }
+    if (options.mode === "signup") {
+        url.searchParams.set("show", "signup");
+    }
+    if (options.redirectUri && options.redirectUri.trim()) {
+        url.searchParams.set("redirect_uri", options.redirectUri);
+    }
+    return url.toString();
+}
+export function resolveSafeRedirectUri(rawValue, options) {
+    const siteOrigin = normalizeOrigin(options.siteOrigin);
+    const blockedPaths = options.blockedPaths ?? DEFAULT_BLOCKED_REDIRECT_PATHS;
+    const fallbackTarget = options.fallback ?? "/";
+    const fallback = new URL(fallbackTarget, siteOrigin).toString();
+    if (!rawValue || !rawValue.trim()) {
+        return fallback;
+    }
+    try {
+        const parsed = new URL(rawValue, siteOrigin);
+        if (parsed.origin === siteOrigin && isBlockedLocalPath(parsed.pathname, blockedPaths)) {
+            return fallback;
+        }
+        return parsed.toString();
+    }
+    catch {
+        return fallback;
+    }
+}
 export class AuthManager {
     apiUrl;
     authUrl;
@@ -93,6 +182,96 @@ export class AuthManager {
         this.state = state;
         this.notify();
     }
+    assertBrowserContext() {
+        if (typeof window === "undefined") {
+            throw new Error("This auth method is only available in browser environments.");
+        }
+    }
+    getCookie(name) {
+        if (typeof document === "undefined")
+            return undefined;
+        const escaped = name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+        const match = document.cookie.match(new RegExp(`(?:^|; )${escaped}=([^;]*)`));
+        return match ? decodeURIComponent(match[1]) : undefined;
+    }
+    clearInjectedToken() {
+        this.injectedToken = null;
+        clearTestingToken();
+    }
+    async rawSignOutViaBackend() {
+        const antiCsrf = this.getCookie("sAntiCsrf");
+        const headers = {
+            Accept: "application/json",
+            "Content-Type": "application/json",
+            rid: "anti-csrf",
+            "fdi-version": "4.2",
+            "st-auth-mode": "cookie",
+        };
+        if (antiCsrf) {
+            headers["anti-csrf"] = antiCsrf;
+        }
+        const separator = this.apiUrl.includes("?") ? "&" : "?";
+        const signOutUrl = `${this.apiUrl.replace(/\/$/, "")}/st/auth/signout${separator}superTokensDoNotDoInterception=true`;
+        await fetch(signOutUrl, {
+            method: "POST",
+            credentials: "include",
+            headers,
+        });
+    }
+    /**
+     * Check whether a cookie-backed session is active without mutating auth state.
+     */
+    async isAuthenticatedViaCookie() {
+        if (this.injectedToken) {
+            return this.isAuthenticated();
+        }
+        try {
+            const response = await fetch(`${this.apiUrl}/users/me`, {
+                method: "GET",
+                credentials: "include",
+                headers: { Accept: "application/json" },
+            });
+            return response.status !== 401;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Return a browser access token from the session layer.
+     * Throws if no token is available.
+     */
+    async getAccessToken() {
+        if (this.injectedToken) {
+            return this.injectedToken;
+        }
+        this.assertBrowserContext();
+        ensureCookieSessionSupport(this.apiUrl, () => this.markUnauthenticated());
+        const token = await Session.getAccessToken();
+        if (!token) {
+            throw new Error("Token unavailable");
+        }
+        return token;
+    }
+    /**
+     * Force a refresh-token flow and return the new access token.
+     */
+    async refreshAccessToken() {
+        if (this.injectedToken) {
+            return this.injectedToken;
+        }
+        this.assertBrowserContext();
+        ensureCookieSessionSupport(this.apiUrl, () => this.markUnauthenticated());
+        const refreshed = await Session.attemptRefreshingSession();
+        if (!refreshed) {
+            throw new Error("Session refresh failed");
+        }
+        const token = await Session.getAccessToken();
+        if (!token) {
+            throw new Error("Token unavailable");
+        }
+        return token;
+    }
     /**
      * Build request headers for an API call.
      * Uses Bearer token if one was injected, otherwise omits Authorization
@@ -151,16 +330,54 @@ export class AuthManager {
     markUnauthenticated() {
         this.setState({ status: "unauthenticated", user: null });
     }
+    /**
+     * Sign out the current user session.
+     * Returns true when the session is no longer active.
+     */
+    async signOut() {
+        if (this.injectedToken) {
+            this.clearInjectedToken();
+            this.markUnauthenticated();
+            return true;
+        }
+        this.assertBrowserContext();
+        ensureCookieSessionSupport(this.apiUrl, () => this.markUnauthenticated());
+        try {
+            await Session.signOut();
+        }
+        catch {
+            // continue with raw fallback
+        }
+        if (await this.isAuthenticatedViaCookie()) {
+            try {
+                await this.rawSignOutViaBackend();
+            }
+            catch {
+                // best effort fallback only
+            }
+        }
+        const isAuthenticated = await this.isAuthenticatedViaCookie();
+        if (!isAuthenticated) {
+            this.markUnauthenticated();
+        }
+        return !isAuthenticated;
+    }
+    /**
+     * Build auth URL for login/signup/custom auth sub-path.
+     */
+    getAuthUrl(options = {}) {
+        return buildAuthUrl(this.authUrl, options);
+    }
     /**
      * Redirect to the auth service, passing the current URL as redirect_uri.
      * After the user authenticates, the auth service should redirect back to
      * the original URL and set the session cookie.
      */
-    redirectToAuth() {
+    redirectToAuth(options = {}) {
         if (typeof window === "undefined") {
             return;
         }
-        const redirectUri = encodeURIComponent(window.location.href);
-        window.location.href = `${this.authUrl}?redirect_uri=${redirectUri}`;
+        const redirectUri = options.redirectUri ?? window.location.href;
+        window.location.href = this.getAuthUrl({ ...options, redirectUri });
     }
 }