@luxdb/sdk 1.4.1 → 1.4.3

package/README.md

@@ -0,0 +1,205 @@
+# @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
+interface User {
+  id: number;
+  email: string;
+  age: number;
+}
+
+interface Message {
+  id: string;
+  body: string;
+  embedding: number[];
+}
+
+const { data: users, error } = await lux
+  .table<User[]>("users")
+  .select()
+  .gt("age", 25)
+  .order("age", { ascending: false })
+  .limit(10);
+
+if (error) throw error;
+console.log(users);
+```
+
+`table<T>()` accepts either a row type or an array type. `table<User>("users")`
+and `table<User[]>("users")` both infer `User` rows; the array form is useful
+when you want the generic to read like the returned data.
+
+For computed projections, pass the projection shape to `select<T>()`:
+
+```ts
+import type { LuxAggregateRow, LuxNearRow } from "@luxdb/sdk";
+
+type TeamStats = { team_id: number } & LuxAggregateRow<"member_count" | "avg_age">;
+
+const { data: teamStats } = await lux
+  .table<User>("members")
+  .select<TeamStats>("team_id,COUNT(*) AS member_count,AVG(age) AS avg_age")
+  .group("team_id");
+
+const { data: matches } = await lux
+  .table<Message>("messages")
+  .select<LuxNearRow<Message>>("id,body,_similarity")
+  .near("embedding", queryEmbedding, { k: 10, threshold: 0.8 });
+```
+
+```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);
+```
+
+## Live tables
+
+Browser clients can subscribe to table queries over Lux Live. The SDK opens a WebSocket to the project live endpoint, and Lux core sends a snapshot followed by insert/update/delete events for rows matching the query.
+
+```ts
+const sub = lux
+  .table<{ id: string; channel_id: string; body: string }>("messages")
+  .eq("channel_id", "general")
+  .live()
+  .on("snapshot", (event) => {
+    console.log(event.rows);
+  })
+  .on("insert", (event) => {
+    console.log(event.new);
+  })
+  .on("update", (event) => {
+    console.log(event.old, event.new);
+  })
+  .on("delete", (event) => {
+    console.log(event.old);
+  });
+
+await sub.unsubscribe();
+```
+
+## 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);
+```
+
+Auth types are exported for app code and system table reads:
+
+```ts
+import type { LuxUser, LuxAuthTables } from "@luxdb/sdk";
+
+type AuthUserRow = LuxAuthTables["auth.users"];
+
+function renderUser(user: LuxUser, row: AuthUserRow) {
+  return row.email ?? user.email;
+}
+```
+
+## 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.
+- Browser live subscriptions use the project publishable key plus the signed-in user's JWT.
+- Table `select()` accepts Lux's constrained projection grammar, not arbitrary SQL.
+- Direct `lux://` or `rediss://` database access uses the database password and is for trusted infrastructure.

package/dist/cjs/index.js

@@ -44,10 +44,7 @@ class Lux extends ioredis_1.default {
     constructor(options) {
         let authOptions = {};
         if (typeof options === 'string') {
-            if (options.startsWith('rediss://') || options.startsWith('luxs://')) {
-                throw new Error('TLS is not yet supported');
-            }
-            options = options.replace(/^lux:\/\//, 'redis://');
+            options = options.replace(/^luxs:\/\//, 'rediss://').replace(/^lux:\/\//, 'redis://');
         }
         else if (options) {
             const { httpUrl, apiKey, authToken, fetch: fetchImpl, ...redisOptions } = options;

package/dist/cjs/project.js

@@ -1,15 +1,19 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.LuxProjectMutationBuilder = exports.LuxProjectInsertBuilder = exports.LuxProjectSelectBuilder = exports.LuxProjectTable = exports.LuxProjectClient = void 0;
+exports.LuxProjectMutationBuilder = exports.LuxProjectInsertBuilder = exports.LuxProjectLiveSubscription = exports.LuxProjectSelectBuilder = exports.LuxProjectTable = exports.LuxProjectClient = void 0;
 exports.createProjectClient = createProjectClient;
 exports.createClient = createClient;
 const auth_1 = require("./auth");
 const utils_1 = require("./utils");
 class LuxProjectClient {
     constructor(options) {
+        this.liveSocket = null;
+        this.liveSubscriptions = new Map();
+        this.livePending = [];
         this.url = options.url.replace(/\/+$/, '');
         this.key = options.key;
         this.fetchImpl = resolveFetch(options.fetch);
+        this.WebSocketImpl = options.websocket;
         this.auth = new auth_1.LuxAuthClient({
             ...options.auth,
             httpUrl: this.url,
@@ -84,6 +88,96 @@ class LuxProjectClient {
             return (0, utils_1.err)('LUX_PROJECT_REQUEST_ERROR', 'Lux request failed', (0, utils_1.toLuxError)(error));
         }
     }
+    async _subscribeLive(spec, handler, error) {
+        const id = `sub_${Math.random().toString(36).slice(2)}_${Date.now().toString(36)}`;
+        const record = { id, spec, handler, error };
+        this.liveSubscriptions.set(id, record);
+        await this.ensureLiveSocket();
+        this.sendLive({
+            type: 'live.subscribe',
+            id,
+            spec,
+        });
+        return () => {
+            this.liveSubscriptions.delete(id);
+            this.sendLive({ type: 'live.unsubscribe', id });
+            if (this.liveSubscriptions.size === 0) {
+                this.liveSocket?.close();
+                this.liveSocket = null;
+            }
+        };
+    }
+    async ensureLiveSocket() {
+        const WebSocketImpl = resolveWebSocket(this.WebSocketImpl);
+        this.WebSocketImpl = WebSocketImpl;
+        if (this.liveSocket &&
+            (this.liveSocket.readyState === WebSocketImpl.OPEN ||
+                this.liveSocket.readyState === WebSocketImpl.CONNECTING)) {
+            return;
+        }
+        const accessToken = await this.auth.getAccessToken();
+        const url = new URL(`${this.url}/live`);
+        url.protocol = url.protocol === 'https:' ? 'wss:' : 'ws:';
+        url.searchParams.set('apikey', this.key);
+        if (accessToken)
+            url.searchParams.set('access_token', accessToken);
+        const socket = new WebSocketImpl(url.toString());
+        this.liveSocket = socket;
+        socket.onopen = () => {
+            for (const message of this.livePending.splice(0))
+                socket.send(message);
+        };
+        socket.onmessage = (event) => {
+            let message;
+            try {
+                message = JSON.parse(String(event.data));
+            }
+            catch {
+                return;
+            }
+            const subscription = typeof message.id === 'string' ? this.liveSubscriptions.get(message.id) : null;
+            if (message.type === 'live.event' && subscription) {
+                subscription.handler(message.event);
+                return;
+            }
+            if (message.type === 'live.error') {
+                const target = subscription ? [subscription] : [...this.liveSubscriptions.values()];
+                for (const sub of target) {
+                    sub.error(message.error || { code: 'LIVE_ERROR', message: 'Live subscription failed' });
+                }
+            }
+        };
+        socket.onerror = () => {
+            for (const subscription of this.liveSubscriptions.values()) {
+                subscription.error({ code: 'LIVE_SOCKET_ERROR', message: 'Live socket failed' });
+            }
+        };
+        socket.onclose = () => {
+            if (this.liveSocket === socket)
+                this.liveSocket = null;
+            if (this.liveSubscriptions.size > 0) {
+                for (const subscription of this.liveSubscriptions.values()) {
+                    this.livePending.push(JSON.stringify({
+                        type: 'live.subscribe',
+                        id: subscription.id,
+                        spec: subscription.spec,
+                    }));
+                }
+                setTimeout(() => {
+                    void this.ensureLiveSocket();
+                }, 1000);
+            }
+        };
+    }
+    sendLive(message) {
+        const payload = JSON.stringify(message);
+        const WebSocketImpl = this.WebSocketImpl;
+        if (WebSocketImpl && this.liveSocket?.readyState === WebSocketImpl.OPEN) {
+            this.liveSocket.send(payload);
+            return;
+        }
+        this.livePending.push(payload);
+    }
 }
 exports.LuxProjectClient = LuxProjectClient;
 class LuxProjectTable {
@@ -94,6 +188,33 @@ class LuxProjectTable {
     select(columns = '*') {
         return new LuxProjectSelectBuilder(this.client, this.name, columns);
     }
+    eq(column, value) {
+        return this.select().eq(column, value);
+    }
+    neq(column, value) {
+        return this.select().neq(column, value);
+    }
+    gt(column, value) {
+        return this.select().gt(column, value);
+    }
+    gte(column, value) {
+        return this.select().gte(column, value);
+    }
+    lt(column, value) {
+        return this.select().lt(column, value);
+    }
+    lte(column, value) {
+        return this.select().lte(column, value);
+    }
+    near(column, vector, options = {}) {
+        return this.select().near(column, vector, options);
+    }
+    is(column, value) {
+        return this.select().is(column, value);
+    }
+    live() {
+        return this.select().live();
+    }
     insert(rowOrRows) {
         return new LuxProjectInsertBuilder(this.client, this.name, rowOrRows);
     }
@@ -128,6 +249,9 @@ class LuxProjectFilterBuilder extends LuxProjectThenable {
         this.client = client;
         this.tableName = tableName;
         this.filters = [];
+        this.joins = [];
+        this.groupColumns = [];
+        this.havingFilters = [];
     }
     eq(column, value) {
         return this.addFilter(column, 'eq', value);
@@ -150,6 +274,24 @@ class LuxProjectFilterBuilder extends LuxProjectThenable {
     is(column, value) {
         return this.addFilter(column, 'is', value);
     }
+    join(table, alias, onLeft, onRight) {
+        this.joins.push({ type: 'inner', table, alias, onLeft, onRight });
+        return this;
+    }
+    leftJoin(table, alias, onLeft, onRight) {
+        this.joins.push({ type: 'left', table, alias, onLeft, onRight });
+        return this;
+    }
+    group(columns) {
+        this.groupColumns = Array.isArray(columns)
+            ? columns
+            : columns.split(',').map((column) => column.trim()).filter(Boolean);
+        return this;
+    }
+    having(column, operator, value) {
+        this.havingFilters.push({ column, operator, value });
+        return this;
+    }
     addFilter(column, operator, value) {
         this.filters.push({ column, operator, value });
         return this;
@@ -158,6 +300,22 @@ class LuxProjectFilterBuilder extends LuxProjectThenable {
         const params = new URLSearchParams();
         if (this.filters.length)
             params.set('where', filtersToWhere(this.filters));
+        for (const join of this.joins) {
+            const kind = join.type === 'left' ? ':left' : '';
+            params.append('join', `${join.table}:${join.alias}${kind}:on(${join.onLeft}=${join.onRight})`);
+        }
+        if (this.groupColumns.length)
+            params.set('group', this.groupColumns.join(','));
+        if (this.havingFilters.length)
+            params.set('having', havingToWhere(this.havingFilters));
+        if (this.nearQuery) {
+            params.set('near_field', this.nearQuery.field);
+            params.set('near_vector', `[${this.nearQuery.vector.join(',')}]`);
+            params.set('near_k', String(this.nearQuery.k));
+            if (this.nearQuery.threshold != null) {
+                params.set('near_threshold', String(this.nearQuery.threshold));
+            }
+        }
         if (this.orderBy) {
             params.set('order', `${this.orderBy.column} ${this.orderBy.ascending ? 'ASC' : 'DESC'}`);
         }
@@ -178,6 +336,15 @@ class LuxProjectSelectBuilder extends LuxProjectFilterBuilder {
         this.orderBy = { column, ascending: options.ascending ?? true };
         return this;
     }
+    near(column, vector, options = {}) {
+        this.nearQuery = {
+            field: column,
+            vector,
+            k: options.k ?? 10,
+            threshold: options.threshold,
+        };
+        return this;
+    }
     limit(count) {
         this.limitCount = count;
         return this;
@@ -210,8 +377,119 @@ class LuxProjectSelectBuilder extends LuxProjectFilterBuilder {
         }
         return (0, utils_1.ok)(rows[0]);
     }
+    live() {
+        return new LuxProjectLiveSubscription(this.client, this.tableName, this.columns, this.filters, this.nearQuery, this.orderBy, this.limitCount, this.offsetCount);
+    }
 }
 exports.LuxProjectSelectBuilder = LuxProjectSelectBuilder;
+class LuxProjectLiveSubscription {
+    constructor(client, table, columns, filters, nearQuery, orderBy, limitCount, offsetCount) {
+        this.client = client;
+        this.table = table;
+        this.columns = columns;
+        this.filters = filters;
+        this.nearQuery = nearQuery;
+        this.orderBy = orderBy;
+        this.limitCount = limitCount;
+        this.offsetCount = offsetCount;
+        this.handlers = {
+            snapshot: [],
+            insert: [],
+            update: [],
+            delete: [],
+            error: [],
+            change: [],
+        };
+        this.unsubscribeFn = null;
+        void this.start();
+    }
+    on(type, handler) {
+        this.handlers[type].push(handler);
+        return this;
+    }
+    async unsubscribe() {
+        this.unsubscribeFn?.();
+        this.unsubscribeFn = null;
+    }
+    async start() {
+        this.unsubscribeFn = await this.client._subscribeLive(this.spec(), (event) => this.handleEvent(event), (error) => this.emit({
+            type: 'error',
+            table: this.table,
+            new: null,
+            old: null,
+            error,
+        }));
+    }
+    spec() {
+        const spec = {
+            kind: 'table',
+            table: this.table,
+            select: this.columns,
+        };
+        if (this.filters.length) {
+            spec.where = this.filters.map((filter) => ({
+                field: filter.column,
+                op: filterOperatorToWhere(filter.operator),
+                value: filter.value,
+            }));
+        }
+        if (this.nearQuery) {
+            spec.near = {
+                field: this.nearQuery.field,
+                vector: this.nearQuery.vector,
+                k: this.nearQuery.k,
+                threshold: this.nearQuery.threshold,
+            };
+        }
+        if (this.orderBy) {
+            spec.orderBy = {
+                field: this.orderBy.column,
+                dir: this.orderBy.ascending ? 'asc' : 'desc',
+            };
+        }
+        if (this.limitCount != null)
+            spec.limit = this.limitCount;
+        if (this.offsetCount != null)
+            spec.offset = this.offsetCount;
+        return spec;
+    }
+    handleEvent(raw) {
+        if (!raw || typeof raw !== 'object')
+            return;
+        const event = raw;
+        if (event.kind === 'snapshot') {
+            this.emit({
+                type: 'snapshot',
+                table: this.table,
+                new: null,
+                old: null,
+                rows: Array.isArray(event.rows) ? event.rows : [],
+                raw,
+            });
+            return;
+        }
+        if (event.kind === 'insert' || event.kind === 'update' || event.kind === 'delete') {
+            this.emit({
+                type: event.kind,
+                table: this.table,
+                pk: event.pk == null ? undefined : String(event.pk),
+                new: event.row ?? null,
+                old: event.previous ?? null,
+                changed: Array.isArray(event.changed) ? event.changed : undefined,
+                raw,
+            });
+        }
+    }
+    emit(event) {
+        for (const handler of this.handlers[event.type])
+            handler(event);
+        if (event.type !== 'snapshot' && event.type !== 'error') {
+            for (const handler of this.handlers.change)
+                handler(event);
+        }
+    }
+}
+exports.LuxProjectLiveSubscription = LuxProjectLiveSubscription;
 class LuxProjectInsertBuilder extends LuxProjectThenable {
     constructor(client, tableName, rowOrRows) {
         super();
@@ -273,6 +551,12 @@ function filtersToWhere(filters) {
         return normalizeWhere(`${filter.column} ${op} ${formatWhereValue(filter.value)}`);
     }).join(' AND ');
 }
+function havingToWhere(filters) {
+    return filters.map((filter) => {
+        const op = filterOperatorToWhere(filter.operator);
+        return normalizeWhere(`${filter.column} ${op} ${formatWhereValue(filter.value)}`);
+    }).join(' AND ');
+}
 function filterOperatorToWhere(operator) {
     switch (operator) {
         case 'eq':
@@ -311,3 +595,10 @@ function resolveFetch(fetchImpl) {
     }
     return candidate;
 }
+function resolveWebSocket(websocketImpl) {
+    const candidate = websocketImpl ?? globalThis.WebSocket;
+    if (!candidate) {
+        throw new Error('Lux project live subscriptions require a WebSocket implementation');
+    }
+    return candidate;
+}