@luxdb/sdk 1.3.0 → 1.4.2

package/README.md

@@ -0,0 +1,132 @@
+# @luxdb/sdk
+
+Official TypeScript SDK for Lux.
+
+Use the project client for browser, server, and SSR app code. Use the direct client when you want low-level Redis-compatible access to a Lux instance.
+
+## Install
+
+```bash
+bun i @luxdb/sdk
+```
+
+## Browser app client
+
+Use a publishable key in browser code. The browser client persists auth sessions in browser storage by default.
+
+```ts
+import { createBrowserClient } from "@luxdb/sdk";
+
+const lux = createBrowserClient(
+  "https://api.luxdb.dev/v1/my-project",
+  "lux_pub_..."
+);
+
+const { data: session, error } = await lux.auth.signInWithPassword({
+  email: "user@example.com",
+  password: "correct horse battery staple",
+});
+
+if (error) throw error;
+```
+
+## Tables
+
+Queries and mutations return a Supabase-style result object:
+
+```ts
+const { data: users, error } = await lux
+  .table<{ id: number; email: string; age: number }>("users")
+  .select()
+  .gt("age", 25)
+  .order("age", { ascending: false })
+  .limit(10);
+
+if (error) throw error;
+console.log(users);
+```
+
+```ts
+const { data: inserted, error: insertError } = await lux
+  .table("messages")
+  .insert({ body: "hello", channel: "general" });
+
+const { data: updated, error: updateError } = await lux
+  .table("messages")
+  .update({ body: "edited" })
+  .eq("id", inserted?.id);
+
+const { data: deleted, error: deleteError } = await lux
+  .table("messages")
+  .delete()
+  .eq("id", inserted?.id);
+```
+
+## OAuth
+
+```ts
+const { data, error } = await lux.auth.signInWithOAuth({
+  provider: "google",
+  redirectTo: "https://app.example.com/auth/callback",
+});
+
+if (error) throw error;
+```
+
+On your callback page:
+
+```ts
+const { data, error } = await lux.auth.consumeOAuthRedirect();
+
+if (error) throw error;
+console.log(data.user);
+```
+
+## Server client
+
+Use a secret key only from trusted server code.
+
+```ts
+import { createClient } from "@luxdb/sdk";
+
+const admin = createClient(
+  "https://api.luxdb.dev/v1/my-project",
+  process.env.LUX_SECRET_KEY!
+);
+
+const { data: users, error } = await admin.auth.listUsers();
+```
+
+## SSR client
+
+Use `createServerClient` with your framework's cookie methods to persist sessions on the server.
+
+```ts
+import { createServerClient } from "@luxdb/sdk";
+
+const lux = createServerClient(
+  "https://api.luxdb.dev/v1/my-project",
+  "lux_pub_...",
+  { cookies }
+);
+```
+
+## Direct Lux/Redis-compatible access
+
+Use direct access for trusted infrastructure that needs RESP commands, low-level primitives, or compatibility with Redis workflows. Do not ship database passwords to browsers.
+
+```ts
+import Lux from "@luxdb/sdk";
+
+const lux = new Lux("lux://:password@localhost:6379");
+
+await lux.set("hello", "world");
+const value = await lux.get("hello");
+```
+
+## Access model
+
+- `lux_pub_...` keys are safe for browser app calls.
+- `lux_sec_...` keys are server-only.
+- User sessions issue JWT access tokens.
+- Direct `lux://` or `rediss://` database access uses the database password and is for trusted infrastructure.

package/dist/cjs/auth.js

@@ -0,0 +1,504 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LuxAuthClient = void 0;
+const utils_1 = require("./utils");
+class LuxAuthClient {
+    constructor(options = {}) {
+        this.currentSession = null;
+        this.loadedSession = false;
+        this.refreshTimer = null;
+        this.listeners = new Set();
+        this.httpUrl = options.httpUrl?.replace(/\/+$/, '');
+        this.apiKey = options.apiKey;
+        this.authToken = options.authToken;
+        this.fetchImpl = resolveFetch(options.fetch);
+        this.persistSession = options.persistSession ?? false;
+        this.autoRefreshToken = options.autoRefreshToken ?? this.persistSession;
+        this.storage = options.storage === undefined ? defaultBrowserStorage() : options.storage;
+        this.storageKey = options.storageKey ?? 'lux.auth.session';
+        this.refreshMarginSeconds = options.refreshMarginSeconds ?? 60;
+        if (this.authToken) {
+            this.currentSession = null;
+        }
+    }
+    async getSession() {
+        try {
+            return (0, utils_1.ok)({ session: await this.getSessionValue() });
+        }
+        catch (error) {
+            return (0, utils_1.err)('LUX_AUTH_SESSION_ERROR', 'Failed to get auth session', (0, utils_1.toLuxError)(error));
+        }
+    }
+    async getSessionValue() {
+        await this.loadStoredSession();
+        if (this.currentSession && isExpired(this.currentSession, this.refreshMarginSeconds)) {
+            if (this.autoRefreshToken && this.currentSession.refresh_token) {
+                const refreshed = await this.refreshSession(this.currentSession.refresh_token);
+                return refreshed.data?.session ?? null;
+            }
+            await this.clearSessionValue();
+            return null;
+        }
+        return this.currentSession;
+    }
+    async getAccessToken() {
+        const session = await this.getSessionValue();
+        return session?.access_token ?? this.authToken;
+    }
+    async setSession(session) {
+        try {
+            return (0, utils_1.ok)({ session: await this.setSessionValue(session) });
+        }
+        catch (error) {
+            return (0, utils_1.err)('LUX_AUTH_SESSION_ERROR', 'Failed to set auth session', (0, utils_1.toLuxError)(error));
+        }
+    }
+    async setSessionValue(session) {
+        if (typeof session === 'string') {
+            this.authToken = session;
+            this.currentSession = null;
+            return null;
+        }
+        if (!session) {
+            await this.clearSessionValue();
+            return null;
+        }
+        await this.saveSession(normalizeSession(session), 'SESSION_UPDATED');
+        return this.currentSession;
+    }
+    async clearSession() {
+        try {
+            await this.clearSessionValue();
+            return (0, utils_1.ok)(null);
+        }
+        catch (error) {
+            return (0, utils_1.err)('LUX_AUTH_SESSION_ERROR', 'Failed to clear auth session', (0, utils_1.toLuxError)(error));
+        }
+    }
+    async clearSessionValue() {
+        this.authToken = undefined;
+        this.currentSession = null;
+        this.loadedSession = true;
+        this.clearRefreshTimer();
+        if (this.persistSession && this.storage) {
+            await this.storage.removeItem(this.storageKey);
+        }
+        this.emit('SIGNED_OUT', null);
+    }
+    onAuthStateChange(callback) {
+        this.listeners.add(callback);
+        void this.getSessionValue().then((session) => callback('INITIAL_SESSION', session));
+        return {
+            unsubscribe: () => {
+                this.listeners.delete(callback);
+            },
+        };
+    }
+    async signUp(options) {
+        try {
+            const session = await this.requestRaw('/auth/v1/signup', {
+                method: 'POST',
+                body: JSON.stringify({
+                    email: options.email,
+                    password: options.password,
+                    data: options.data,
+                }),
+                apiKey: true,
+            });
+            await this.saveSession(normalizeSession(session), 'SIGNED_IN');
+            return (0, utils_1.ok)({ session: this.currentSession, user: this.currentSession.user });
+        }
+        catch (error) {
+            return (0, utils_1.err)('LUX_AUTH_SIGNUP_ERROR', 'Failed to sign up', (0, utils_1.toLuxError)(error));
+        }
+    }
+    async signInWithPassword(options) {
+        try {
+            const session = await this.requestRaw('/auth/v1/token', {
+                method: 'POST',
+                body: JSON.stringify({
+                    grant_type: 'password',
+                    email: options.email,
+                    password: options.password,
+                }),
+                apiKey: true,
+            });
+            await this.saveSession(normalizeSession(session), 'SIGNED_IN');
+            return (0, utils_1.ok)({ session: this.currentSession, user: this.currentSession.user });
+        }
+        catch (error) {
+            return (0, utils_1.err)('LUX_AUTH_SIGNIN_ERROR', 'Failed to sign in', (0, utils_1.toLuxError)(error));
+        }
+    }
+    async signInWithOAuth(options) {
+        try {
+            if (!this.httpUrl) {
+                throw new Error('Lux auth requires httpUrl');
+            }
+            const redirectTo = options.redirectTo ?? browserLocation();
+            const url = new URL(`${this.httpUrl}/auth/v1/authorize`);
+            url.searchParams.set('provider', options.provider);
+            if (redirectTo)
+                url.searchParams.set('redirect_to', redirectTo);
+            const target = url.toString();
+            if (!options.skipRedirect && typeof globalThis !== 'undefined') {
+                const location = globalThis.location;
+                if (location?.assign)
+                    location.assign(target);
+            }
+            return (0, utils_1.ok)({ url: target });
+        }
+        catch (error) {
+            return (0, utils_1.err)('LUX_AUTH_OAUTH_ERROR', 'Failed to start OAuth sign in', (0, utils_1.toLuxError)(error));
+        }
+    }
+    async consumeOAuthRedirect(url = browserLocation()) {
+        try {
+            if (!url)
+                return (0, utils_1.ok)({ session: null, user: null });
+            const parsed = new URL(url);
+            const params = new URLSearchParams(parsed.hash.replace(/^#/, ''));
+            const accessToken = params.get('access_token');
+            const refreshToken = params.get('refresh_token');
+            if (!accessToken || !refreshToken)
+                return (0, utils_1.ok)({ session: null, user: null });
+            const session = normalizeSession({
+                access_token: accessToken,
+                refresh_token: refreshToken,
+                expires_in: Number(params.get('expires_in') || 0),
+                token_type: 'bearer',
+                user: { id: '', email: '' },
+            });
+            if (this.httpUrl) {
+                const user = await this.getUser(accessToken);
+                if (user.error)
+                    return user;
+                if (!user.data?.user) {
+                    return (0, utils_1.err)('LUX_AUTH_USER_ERROR', 'OAuth redirect token did not resolve to a user');
+                }
+                session.user = user.data.user;
+            }
+            await this.saveSession(session, 'SIGNED_IN');
+            return (0, utils_1.ok)({ session: this.currentSession, user: this.currentSession?.user ?? null });
+        }
+        catch (error) {
+            return (0, utils_1.err)('LUX_AUTH_OAUTH_ERROR', 'Failed to consume OAuth redirect', (0, utils_1.toLuxError)(error));
+        }
+    }
+    async refreshSession(refreshToken) {
+        try {
+            const session = await this.requestRaw('/auth/v1/token', {
+                method: 'POST',
+                body: JSON.stringify({
+                    grant_type: 'refresh_token',
+                    refresh_token: refreshToken,
+                }),
+                apiKey: true,
+            });
+            await this.saveSession(normalizeSession(session), 'TOKEN_REFRESHED');
+            return (0, utils_1.ok)({ session: this.currentSession, user: this.currentSession.user });
+        }
+        catch (error) {
+            return (0, utils_1.err)('LUX_AUTH_REFRESH_ERROR', 'Failed to refresh auth session', (0, utils_1.toLuxError)(error));
+        }
+    }
+    async getUser(session) {
+        if (!session) {
+            await this.getSessionValue();
+        }
+        try {
+            return (0, utils_1.ok)(await this.requestRaw('/auth/v1/user', {
+                method: 'GET',
+                token: this.tokenFrom(session),
+            }));
+        }
+        catch (error) {
+            return (0, utils_1.err)('LUX_AUTH_USER_ERROR', 'Failed to get auth user', (0, utils_1.toLuxError)(error));
+        }
+    }
+    async logout(sessionOrRefreshToken) {
+        if (!sessionOrRefreshToken) {
+            sessionOrRefreshToken = await this.getSessionValue() ?? undefined;
+        }
+        const token = typeof sessionOrRefreshToken === 'string'
+            ? sessionOrRefreshToken
+            : sessionOrRefreshToken?.access_token;
+        const refreshToken = typeof sessionOrRefreshToken === 'string'
+            ? undefined
+            : sessionOrRefreshToken?.refresh_token;
+        try {
+            await this.requestRaw('/auth/v1/logout', {
+                method: 'POST',
+                token,
+                body: JSON.stringify(refreshToken ? { refresh_token: refreshToken } : {}),
+            });
+            await this.clearSessionValue();
+            return (0, utils_1.ok)(null);
+        }
+        catch (error) {
+            return (0, utils_1.err)('LUX_AUTH_LOGOUT_ERROR', 'Failed to log out', (0, utils_1.toLuxError)(error));
+        }
+    }
+    async signOut() {
+        return this.logout();
+    }
+    async listUsers() {
+        try {
+            const result = await this.requestRaw('/auth/v1/admin/users', {
+                method: 'GET',
+                secret: true,
+            });
+            return (0, utils_1.ok)(result.users);
+        }
+        catch (error) {
+            return (0, utils_1.err)('LUX_AUTH_ADMIN_ERROR', 'Failed to list auth users', (0, utils_1.toLuxError)(error));
+        }
+    }
+    async grantCapability(userId, capability) {
+        try {
+            const result = await this.requestRaw('/auth/v1/admin/grants', {
+                method: 'POST',
+                secret: true,
+                body: JSON.stringify({ user_id: userId, capability }),
+            });
+            return (0, utils_1.ok)(result.grant);
+        }
+        catch (error) {
+            return (0, utils_1.err)('LUX_AUTH_ADMIN_ERROR', 'Failed to grant capability', (0, utils_1.toLuxError)(error));
+        }
+    }
+    async listUserGrants(userId) {
+        try {
+            const result = await this.requestRaw(`/auth/v1/admin/users/${encodeURIComponent(userId)}/grants`, {
+                method: 'GET',
+                secret: true,
+            });
+            return (0, utils_1.ok)(result.grants);
+        }
+        catch (error) {
+            return (0, utils_1.err)('LUX_AUTH_ADMIN_ERROR', 'Failed to list user grants', (0, utils_1.toLuxError)(error));
+        }
+    }
+    async revokeGrant(grantId) {
+        try {
+            await this.requestRaw(`/auth/v1/admin/grants/${encodeURIComponent(grantId)}`, {
+                method: 'DELETE',
+                secret: true,
+            });
+            return (0, utils_1.ok)(null);
+        }
+        catch (error) {
+            return (0, utils_1.err)('LUX_AUTH_ADMIN_ERROR', 'Failed to revoke grant', (0, utils_1.toLuxError)(error));
+        }
+    }
+    async listApiKeys() {
+        try {
+            const result = await this.requestRaw('/auth/v1/admin/keys', {
+                method: 'GET',
+                secret: true,
+            });
+            return (0, utils_1.ok)(result.keys);
+        }
+        catch (error) {
+            return (0, utils_1.err)('LUX_AUTH_ADMIN_ERROR', 'Failed to list API keys', (0, utils_1.toLuxError)(error));
+        }
+    }
+    async listProviders() {
+        try {
+            const result = await this.requestRaw('/auth/v1/admin/providers', {
+                method: 'GET',
+                secret: true,
+            });
+            return (0, utils_1.ok)(result.providers);
+        }
+        catch (error) {
+            return (0, utils_1.err)('LUX_AUTH_ADMIN_ERROR', 'Failed to list auth providers', (0, utils_1.toLuxError)(error));
+        }
+    }
+    async upsertProvider(options) {
+        try {
+            const result = await this.requestRaw(`/auth/v1/admin/providers/${encodeURIComponent(options.provider)}`, {
+                method: 'PUT',
+                secret: true,
+                body: JSON.stringify(options),
+            });
+            return (0, utils_1.ok)(result.provider);
+        }
+        catch (error) {
+            return (0, utils_1.err)('LUX_AUTH_ADMIN_ERROR', 'Failed to update auth provider', (0, utils_1.toLuxError)(error));
+        }
+    }
+    async createApiKey(options) {
+        try {
+            return (0, utils_1.ok)(await this.requestRaw('/auth/v1/admin/keys', {
+                method: 'POST',
+                secret: true,
+                body: JSON.stringify(options),
+            }));
+        }
+        catch (error) {
+            return (0, utils_1.err)('LUX_AUTH_ADMIN_ERROR', 'Failed to create API key', (0, utils_1.toLuxError)(error));
+        }
+    }
+    async revokeApiKey(keyId) {
+        try {
+            await this.requestRaw(`/auth/v1/admin/keys/${encodeURIComponent(keyId)}`, {
+                method: 'DELETE',
+                secret: true,
+            });
+            return (0, utils_1.ok)(null);
+        }
+        catch (error) {
+            return (0, utils_1.err)('LUX_AUTH_ADMIN_ERROR', 'Failed to revoke API key', (0, utils_1.toLuxError)(error));
+        }
+    }
+    async get(path, session) {
+        return this.requestResult(path, { method: 'GET', token: this.tokenFrom(session) });
+    }
+    async post(path, body, session) {
+        return this.requestResult(path, {
+            method: 'POST',
+            token: this.tokenFrom(session),
+            body: body == null ? undefined : JSON.stringify(body),
+        });
+    }
+    async put(path, body, session) {
+        return this.requestResult(path, {
+            method: 'PUT',
+            token: this.tokenFrom(session),
+            body: body == null ? undefined : JSON.stringify(body),
+        });
+    }
+    async delete(path, session) {
+        return this.requestResult(path, { method: 'DELETE', token: this.tokenFrom(session) });
+    }
+    tokenFrom(session) {
+        return typeof session === 'string' ? session : session?.access_token ?? this.authToken;
+    }
+    async loadStoredSession() {
+        if (this.loadedSession)
+            return;
+        this.loadedSession = true;
+        if (!this.persistSession || !this.storage)
+            return;
+        const raw = await this.storage.getItem(this.storageKey);
+        if (!raw)
+            return;
+        try {
+            const session = normalizeSession(JSON.parse(raw));
+            this.currentSession = session;
+            this.authToken = session.access_token;
+            this.scheduleRefresh(session);
+        }
+        catch {
+            await this.storage.removeItem(this.storageKey);
+        }
+    }
+    async saveSession(session, event) {
+        this.currentSession = session;
+        this.authToken = session.access_token;
+        this.loadedSession = true;
+        if (this.persistSession && this.storage) {
+            await this.storage.setItem(this.storageKey, JSON.stringify(session));
+        }
+        this.scheduleRefresh(session);
+        this.emit(event, session);
+    }
+    scheduleRefresh(session) {
+        this.clearRefreshTimer();
+        if (!this.autoRefreshToken || !session.refresh_token || !session.expires_at)
+            return;
+        const delayMs = Math.max(0, (session.expires_at - this.refreshMarginSeconds) * 1000 - Date.now());
+        this.refreshTimer = setTimeout(() => {
+            void this.refreshSession(session.refresh_token).catch(() => {
+                void this.clearSessionValue();
+            });
+        }, delayMs);
+    }
+    clearRefreshTimer() {
+        if (this.refreshTimer) {
+            clearTimeout(this.refreshTimer);
+            this.refreshTimer = null;
+        }
+    }
+    emit(event, session) {
+        for (const listener of this.listeners) {
+            listener(event, session);
+        }
+    }
+    async requestResult(path, init) {
+        try {
+            return (0, utils_1.ok)(await this.requestRaw(path, init));
+        }
+        catch (error) {
+            return (0, utils_1.err)('LUX_AUTH_REQUEST_ERROR', 'Lux auth request failed', (0, utils_1.toLuxError)(error));
+        }
+    }
+    async requestRaw(path, init) {
+        if (!this.httpUrl) {
+            throw new Error('Lux auth requires httpUrl');
+        }
+        const headers = {
+            Accept: 'application/json',
+        };
+        if (init.body != null) {
+            headers['Content-Type'] = 'application/json';
+        }
+        const token = init.token ?? this.authToken;
+        if (token) {
+            headers.Authorization = `Bearer ${token}`;
+        }
+        if ((init.apiKey || init.secret) && this.apiKey) {
+            headers.apikey = this.apiKey;
+        }
+        const response = await this.fetchImpl(`${this.httpUrl}${path}`, {
+            method: init.method,
+            headers,
+            body: init.body,
+        });
+        const text = await response.text();
+        const payload = text ? JSON.parse(text) : {};
+        if (!response.ok) {
+            const message = payload?.error || `Lux auth request failed with HTTP ${response.status}`;
+            throw new Error(message);
+        }
+        return payload;
+    }
+}
+exports.LuxAuthClient = LuxAuthClient;
+function normalizeSession(session) {
+    return {
+        ...session,
+        expires_at: session.expires_at ?? Math.floor(Date.now() / 1000) + Number(session.expires_in || 0),
+    };
+}
+function isExpired(session, marginSeconds = 0) {
+    return Boolean(session.expires_at && session.expires_at <= Math.floor(Date.now() / 1000) + marginSeconds);
+}
+function defaultBrowserStorage() {
+    if (typeof globalThis === 'undefined')
+        return null;
+    const storage = globalThis.localStorage;
+    if (!storage)
+        return null;
+    return {
+        getItem: (key) => storage.getItem(key),
+        setItem: (key, value) => storage.setItem(key, value),
+        removeItem: (key) => storage.removeItem(key),
+    };
+}
+function resolveFetch(fetchImpl) {
+    const candidate = fetchImpl ?? globalThis.fetch;
+    if (!candidate) {
+        throw new Error('Lux auth requires a fetch implementation');
+    }
+    if (typeof globalThis !== 'undefined' && candidate === globalThis.fetch) {
+        return candidate.bind(globalThis);
+    }
+    return candidate;
+}
+function browserLocation() {
+    if (typeof globalThis === 'undefined')
+        return '';
+    return String(globalThis.location?.href || '');
+}

package/dist/cjs/browser.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createBrowserClient = createBrowserClient;
+const project_1 = require("./project");
+function createBrowserClient(url, key, options = {}) {
+    return (0, project_1.createClient)(url, key, {
+        ...options,
+        auth: {
+            persistSession: true,
+            autoRefreshToken: true,
+            ...(options.auth ?? {}),
+        },
+    });
+}