lemma-sdk 0.2.0

package/README.md

@@ -0,0 +1,100 @@
+# Lemma TypeScript SDK
+
+Official TypeScript SDK for Lemma pod-scoped APIs.
+
+- High-level `LemmaClient` namespaces for common workflows
+- React helpers (`lemma-sdk/react`) for auth-gated apps
+- Re-exported generated OpenAPI services and model types
+- Browser standalone bundle (`dist/browser/lemma-client.js`)
+
+## Install
+
+```bash
+npm i lemma-sdk
+```
+
+If you want to import as `lemma`, use npm aliasing:
+
+```bash
+npm i lemma@npm:lemma-sdk
+```
+
+## Quick usage
+
+```ts
+import { LemmaClient } from "lemma-sdk";
+
+const client = new LemmaClient({
+  apiUrl: "/api",
+  authUrl: "http://localhost:4173",
+  podId: "<pod-id>",
+});
+
+await client.initialize();
+const todos = await client.records.list("default", "todos", { limit: 20 });
+```
+
+## Docs (Mintlify)
+
+Documentation is now in Mintlify format:
+
+- `docs/docs.json`
+- `docs/index.mdx`
+- `docs/quickstart.mdx`
+- `docs/configuration.mdx`
+- `docs/authentication.mdx`
+- `docs/namespaces.mdx`
+- `docs/react.mdx`
+- `docs/browser-bundle.mdx`
+- `docs/generated-api.mdx`
+- `docs/publishing.mdx`
+
+Run docs locally:
+
+```bash
+npm run docs:dev
+```
+
+Validate docs:
+
+```bash
+npm run docs:validate
+```
+
+## Development
+
+### Regenerate OpenAPI client
+
+```bash
+bash scripts/generate_openapi_client.sh
+```
+
+### Build SDK
+
+```bash
+npm run build
+```
+
+Output:
+
+- `dist/` npm package artifacts
+- `dist/browser/lemma-client.js` standalone browser bundle
+- `public/lemma-client.js` committed copy for static serving
+
+## Publishing
+
+As of March 26, 2026, npm package name `lemma` is already taken. This repo is configured to publish as `lemma-sdk`.
+
+Release check:
+
+```bash
+npm run release:check
+```
+
+Publish:
+
+```bash
+npm publish
+```
+
+`lemma-sdk` is unscoped, so npm publishes it as public by default.

package/dist/auth.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Auth module — cookie-based auth (production) with Bearer token fallback
+ * 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
+ *
+ * If a token is found in (1) or (2), 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
+ * refresh-token flows for mutating requests.
+ *
+ * Auth state is determined by calling GET /users/me (user.current.get).
+ * 401 → unauthenticated. 200 → authenticated.
+ */
+export interface UserInfo {
+    id: string;
+    email: string;
+    name?: string;
+    [key: string]: unknown;
+}
+export type AuthStatus = "loading" | "authenticated" | "unauthenticated";
+export interface AuthState {
+    status: AuthStatus;
+    user: UserInfo | null;
+}
+export type AuthListener = (state: AuthState) => void;
+export declare class AuthManager {
+    private readonly apiUrl;
+    private readonly authUrl;
+    private injectedToken;
+    private state;
+    private listeners;
+    constructor(apiUrl: string, authUrl: string);
+    /** Whether requests will use an injected Bearer token (testing mode). */
+    get isTokenMode(): boolean;
+    /** The current injected Bearer token, if token-mode auth is active. */
+    getBearerToken(): string | null;
+    /** The current auth state. */
+    getState(): AuthState;
+    /** True if currently authenticated (status === "authenticated"). */
+    isAuthenticated(): boolean;
+    /** Subscribe to auth state changes. Returns an unsubscribe function. */
+    subscribe(listener: AuthListener): () => void;
+    private notify;
+    private setState;
+    /**
+     * Build request headers for an API call.
+     * Uses Bearer token if one was injected, otherwise omits Authorization
+     * and lets cookies carry the session.
+     */
+    getRequestInit(init?: RequestInit): RequestInit;
+    /**
+     * Call GET /users/me to determine auth state.
+     * Sets internal state and notifies listeners.
+     */
+    checkAuth(): Promise<AuthState>;
+    /**
+     * Mark the session as unauthenticated (e.g. after a 401 response).
+     * Does NOT redirect — call redirectToAuth() explicitly if desired.
+     */
+    markUnauthenticated(): void;
+    /**
+     * 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;
+}

package/dist/auth.js

@@ -0,0 +1,166 @@
+/**
+ * Auth module — cookie-based auth (production) with Bearer token fallback
+ * 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
+ *
+ * If a token is found in (1) or (2), 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
+ * refresh-token flows for mutating requests.
+ *
+ * Auth state is determined by calling GET /users/me (user.current.get).
+ * 401 → unauthenticated. 200 → authenticated.
+ */
+import { ensureCookieSessionSupport } from "./supertokens.js";
+const LOCALSTORAGE_TOKEN_KEY = "lemma_token";
+const QUERY_PARAM_TOKEN_KEY = "lemma_token";
+function detectInjectedToken() {
+    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;
+        }
+    }
+    catch { /* ignore */ }
+    // 2. sessionStorage — survives HMR and same-tab navigation
+    try {
+        const stored = sessionStorage.getItem(LOCALSTORAGE_TOKEN_KEY);
+        if (stored)
+            return stored;
+    }
+    catch { /* ignore */ }
+    // 3. localStorage — set manually by dev/agent for persistent testing
+    try {
+        const stored = localStorage.getItem(LOCALSTORAGE_TOKEN_KEY);
+        if (stored)
+            return stored;
+    }
+    catch { /* ignore */ }
+    return null;
+}
+export class AuthManager {
+    apiUrl;
+    authUrl;
+    injectedToken;
+    state = { status: "loading", user: null };
+    listeners = new Set();
+    constructor(apiUrl, authUrl) {
+        this.apiUrl = apiUrl;
+        this.authUrl = authUrl;
+        this.injectedToken = detectInjectedToken();
+        if (!this.injectedToken) {
+            ensureCookieSessionSupport(this.apiUrl, () => this.markUnauthenticated());
+        }
+    }
+    /** Whether requests will use an injected Bearer token (testing mode). */
+    get isTokenMode() {
+        return this.injectedToken !== null;
+    }
+    /** The current injected Bearer token, if token-mode auth is active. */
+    getBearerToken() {
+        return this.injectedToken;
+    }
+    /** The current auth state. */
+    getState() {
+        return this.state;
+    }
+    /** True if currently authenticated (status === "authenticated"). */
+    isAuthenticated() {
+        return this.state.status === "authenticated";
+    }
+    /** Subscribe to auth state changes. Returns an unsubscribe function. */
+    subscribe(listener) {
+        this.listeners.add(listener);
+        return () => this.listeners.delete(listener);
+    }
+    notify() {
+        this.listeners.forEach((l) => l(this.state));
+    }
+    setState(state) {
+        this.state = state;
+        this.notify();
+    }
+    /**
+     * Build request headers for an API call.
+     * Uses Bearer token if one was injected, otherwise omits Authorization
+     * and lets cookies carry the session.
+     */
+    getRequestInit(init = {}) {
+        const headers = {
+            "Content-Type": "application/json",
+            Accept: "application/json",
+            ...init.headers,
+        };
+        if (this.injectedToken) {
+            headers["Authorization"] = `Bearer ${this.injectedToken}`;
+        }
+        return {
+            ...init,
+            credentials: this.injectedToken ? "omit" : "include",
+            headers,
+        };
+    }
+    /**
+     * Call GET /users/me to determine auth state.
+     * Sets internal state and notifies listeners.
+     */
+    async checkAuth() {
+        this.setState({ status: "loading", user: null });
+        try {
+            const response = await fetch(`${this.apiUrl}/users/me`, this.getRequestInit({ method: "GET" }));
+            // Only 401 means not authenticated — 403 means authenticated but forbidden
+            if (response.status === 401) {
+                const next = { status: "unauthenticated", user: null };
+                this.setState(next);
+                return next;
+            }
+            if (!response.ok) {
+                // For non-401 errors on /users/me, treat as unauthenticated (conservative)
+                const next = { status: "unauthenticated", user: null };
+                this.setState(next);
+                return next;
+            }
+            const user = (await response.json());
+            const next = { status: "authenticated", user };
+            this.setState(next);
+            return next;
+        }
+        catch {
+            const next = { status: "unauthenticated", user: null };
+            this.setState(next);
+            return next;
+        }
+    }
+    /**
+     * Mark the session as unauthenticated (e.g. after a 401 response).
+     * Does NOT redirect — call redirectToAuth() explicitly if desired.
+     */
+    markUnauthenticated() {
+        this.setState({ status: "unauthenticated", user: null });
+    }
+    /**
+     * 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() {
+        if (typeof window === "undefined") {
+            return;
+        }
+        const redirectUri = encodeURIComponent(window.location.href);
+        window.location.href = `${this.authUrl}?redirect_uri=${redirectUri}`;
+    }
+}