lemma-sdk 0.2.2 → 0.2.4

package/README.md

@@ -39,6 +39,35 @@ 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 });
+```
 
 ## Assistants + Agent Runs
 

package/dist/auth.d.ts

@@ -28,6 +28,27 @@ 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 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 +68,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 +101,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

@@ -16,7 +16,9 @@
  * 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() {
@@ -51,6 +53,79 @@ function detectInjectedToken() {
     catch { /* ignore */ }
     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 +168,109 @@ 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;
+        if (typeof window === "undefined")
+            return;
+        try {
+            sessionStorage.removeItem(LOCALSTORAGE_TOKEN_KEY);
+        }
+        catch {
+            // ignore storage errors
+        }
+        try {
+            localStorage.removeItem(LOCALSTORAGE_TOKEN_KEY);
+        }
+        catch {
+            // ignore storage errors
+        }
+    }
+    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 +329,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 });
     }
 }