@luxdb/sdk 1.2.1 → 1.4.1

package/dist/esm/realtime.js

@@ -0,0 +1,84 @@
+export class LuxRealtimeManager {
+    constructor(client) {
+        this.connection = null;
+        this.initPromise = null;
+        this.nextHandlerId = 1;
+        this.handlersByPattern = new Map();
+        this.client = client;
+    }
+    async ensureConnection() {
+        if (this.connection)
+            return;
+        if (this.initPromise)
+            return this.initPromise;
+        this.initPromise = (async () => {
+            const sub = this.client.duplicate();
+            sub.on('error', () => { });
+            const dispatch = (event) => {
+                const handlers = this.handlersByPattern.get(event.pattern);
+                if (!handlers)
+                    return;
+                for (const handler of handlers.values()) {
+                    handler(event);
+                }
+            };
+            const dataHandler = sub._dataHandler || sub.dataHandler;
+            if (dataHandler && dataHandler.returnReply) {
+                const origReturn = dataHandler.returnReply.bind(dataHandler);
+                dataHandler.returnReply = (reply) => {
+                    if (Array.isArray(reply) && reply.length === 4 && reply[0] === 'kmessage') {
+                        dispatch({ pattern: reply[1], key: reply[2], operation: reply[3] });
+                        return;
+                    }
+                    return origReturn(reply);
+                };
+            }
+            else {
+                const origEmit = sub.emit.bind(sub);
+                sub.emit = (event, ...args) => {
+                    if (event === 'error' && args[0]?.message?.includes('Command queue state error')) {
+                        const match = args[0].message.match(/Last reply: kmessage,([^,]+),([^,]+),(.+)/);
+                        if (match) {
+                            dispatch({ pattern: match[1], key: match[2], operation: match[3] });
+                            return true;
+                        }
+                    }
+                    return origEmit(event, ...args);
+                };
+            }
+            this.connection = sub;
+        })();
+        try {
+            await this.initPromise;
+        }
+        finally {
+            this.initPromise = null;
+        }
+    }
+    async subscribe(pattern, handler) {
+        await this.ensureConnection();
+        const id = this.nextHandlerId++;
+        let handlers = this.handlersByPattern.get(pattern);
+        const firstForPattern = !handlers;
+        if (!handlers) {
+            handlers = new Map();
+            this.handlersByPattern.set(pattern, handlers);
+        }
+        handlers.set(id, handler);
+        if (firstForPattern && this.connection) {
+            await this.connection.call('KSUB', pattern);
+        }
+        return () => {
+            const map = this.handlersByPattern.get(pattern);
+            if (!map)
+                return;
+            map.delete(id);
+            if (map.size === 0) {
+                this.handlersByPattern.delete(pattern);
+                if (this.connection) {
+                    this.connection.call('KUNSUB', pattern).catch(() => { });
+                }
+            }
+        };
+    }
+}

package/dist/esm/ssr.js

@@ -0,0 +1,37 @@
+import { createClient } from './project.js';
+const DEFAULT_COOKIE = 'lux-auth-session';
+export function createServerClient(url, key, options) {
+    const storageKey = options.auth?.storageKey ?? DEFAULT_COOKIE;
+    const cookieOptions = options.auth?.cookieOptions ?? {
+        path: '/',
+        sameSite: 'lax',
+    };
+    const { cookieOptions: _cookieOptions, ...authOptions } = options.auth ?? {};
+    return createClient(url, key, {
+        fetch: options.fetch,
+        auth: {
+            persistSession: true,
+            autoRefreshToken: false,
+            ...authOptions,
+            storageKey,
+            storage: cookieStorage(options.cookies, cookieOptions),
+        },
+    });
+}
+function cookieStorage(cookies, options) {
+    return {
+        async getItem(key) {
+            return await cookies.get(key) ?? null;
+        },
+        async setItem(key, value) {
+            if (!cookies.set)
+                return;
+            await cookies.set(key, value, options);
+        },
+        async removeItem(key) {
+            if (!cookies.remove)
+                return;
+            await cookies.remove(key, { ...options, maxAge: 0, expires: new Date(0) });
+        },
+    };
+}

package/dist/esm/table.js

@@ -0,0 +1,391 @@
+import { err, ok, toLuxError } from './utils.js';
+export class TableSubscription {
+    constructor(client, table, selectArgsBuilder, initError = null) {
+        this.handlers = {
+            change: [],
+            insert: [],
+            update: [],
+            delete: [],
+            error: [],
+        };
+        this.knownRows = new Map();
+        this.unsubscribeFn = null;
+        this.client = client;
+        this.table = table;
+        this.selectArgsBuilder = selectArgsBuilder;
+        this.initError = initError;
+        void this.start();
+    }
+    on(event, handler) {
+        this.handlers[event].push(handler);
+        return this;
+    }
+    async unsubscribe() {
+        if (this.unsubscribeFn) {
+            this.unsubscribeFn();
+            this.unsubscribeFn = null;
+        }
+    }
+    emitError(error) {
+        for (const handler of this.handlers.error) {
+            handler({ type: 'error', table: this.table, error });
+        }
+    }
+    emitChange(event) {
+        for (const handler of this.handlers.change)
+            handler(event);
+        for (const handler of this.handlers[event.type])
+            handler(event);
+    }
+    extractPkFromKey(key) {
+        const prefix = `_t:${this.table}:row:`;
+        if (!key.startsWith(prefix))
+            return null;
+        return key.slice(prefix.length);
+    }
+    async fetchMatches(extra) {
+        const args = this.selectArgsBuilder(extra);
+        const rows = await this.client._tselect(args);
+        return rows;
+    }
+    async start() {
+        if (this.initError) {
+            this.emitError(this.initError);
+            return;
+        }
+        try {
+            const initial = await this.fetchMatches();
+            for (const row of initial) {
+                if (row.id == null)
+                    continue;
+                this.knownRows.set(String(row.id), row);
+            }
+            const pattern = `_t:${this.table}:row:*`;
+            this.unsubscribeFn = await this.client._subscribePattern(pattern, (raw) => {
+                void this.handleRawChange(raw);
+            });
+        }
+        catch (error) {
+            this.emitError(toLuxError(error, 'LUX_SUBSCRIBE_INIT_ERROR'));
+        }
+    }
+    async handleRawChange(raw) {
+        const pk = this.extractPkFromKey(raw.key);
+        if (!pk)
+            return;
+        try {
+            const previous = this.knownRows.get(pk) ?? null;
+            const rows = await this.fetchMatches([{ field: 'id', op: '=', value: pk }]);
+            const next = rows[0] ?? null;
+            if (!previous && !next)
+                return;
+            if (!previous && next) {
+                this.knownRows.set(pk, next);
+                this.emitChange({
+                    type: 'insert',
+                    table: this.table,
+                    pk,
+                    operation: raw.operation,
+                    new: next,
+                    old: null,
+                    raw,
+                });
+                return;
+            }
+            if (previous && !next) {
+                this.knownRows.delete(pk);
+                this.emitChange({
+                    type: 'delete',
+                    table: this.table,
+                    pk,
+                    operation: raw.operation,
+                    new: null,
+                    old: previous,
+                    raw,
+                });
+                return;
+            }
+            if (!previous || !next)
+                return;
+            this.knownRows.set(pk, next);
+            const changed = Object.keys(next).filter((key) => previous[key] !== next[key]);
+            this.emitChange({
+                type: 'update',
+                table: this.table,
+                pk,
+                operation: raw.operation,
+                new: next,
+                old: previous,
+                changed,
+                raw,
+            });
+        }
+        catch (error) {
+            this.emitError(toLuxError(error, 'LUX_SUBSCRIBE_EVENT_ERROR'));
+        }
+    }
+}
+export class TableQueryBuilder {
+    constructor(client, name, options) {
+        this.conditions = [];
+        this.selectClause = '*';
+        this.expectSingle = false;
+        this.client = client;
+        this.name = name;
+        this.schema = options?.schema;
+    }
+    validateRow(row) {
+        if (!this.schema)
+            return row;
+        if (this.schema.safeParse) {
+            const parsed = this.schema.safeParse(row);
+            if (!parsed.success) {
+                throw new Error('row failed schema validation');
+            }
+            return parsed.data;
+        }
+        if (this.schema.parse) {
+            return this.schema.parse(row);
+        }
+        return row;
+    }
+    buildSelectArgs(extra) {
+        const args = [this.selectClause, 'FROM', this.name];
+        const allConditions = extra ? [...this.conditions, ...extra] : this.conditions;
+        if (this.joinClause) {
+            args.push('JOIN', this.joinClause.table, this.joinClause.alias, 'ON', this.joinClause.onLeft, '=', this.joinClause.onRight);
+        }
+        if (allConditions.length) {
+            args.push('WHERE');
+            for (let i = 0; i < allConditions.length; i++) {
+                const cond = allConditions[i];
+                args.push(cond.field, cond.op, String(cond.value));
+                if (i < allConditions.length - 1) {
+                    args.push('AND');
+                }
+            }
+        }
+        if (this.orderField) {
+            args.push('ORDER', 'BY', this.orderField, this.orderDir || 'ASC');
+        }
+        if (this.limitCount != null) {
+            args.push('LIMIT', String(this.limitCount));
+        }
+        if (this.offsetCount != null) {
+            args.push('OFFSET', String(this.offsetCount));
+        }
+        return args;
+    }
+    select(columns = '*') {
+        this.selectClause = columns;
+        return this;
+    }
+    single() {
+        this.expectSingle = true;
+        if (this.limitCount == null) {
+            this.limitCount = 1;
+        }
+        return this;
+    }
+    where(field, op, value) {
+        this.conditions.push({ field, op, value });
+        return this;
+    }
+    eq(field, value) {
+        return this.where(field, '=', value);
+    }
+    neq(field, value) {
+        return this.where(field, '!=', value);
+    }
+    gt(field, value) {
+        return this.where(field, '>', value);
+    }
+    gte(field, value) {
+        return this.where(field, '>=', value);
+    }
+    lt(field, value) {
+        return this.where(field, '<', value);
+    }
+    lte(field, value) {
+        return this.where(field, '<=', value);
+    }
+    orderBy(field, dir = 'asc') {
+        this.orderField = field;
+        this.orderDir = dir.toUpperCase();
+        return this;
+    }
+    order(field, options = {}) {
+        return this.orderBy(field, options.ascending === false ? 'desc' : 'asc');
+    }
+    limit(n) {
+        this.limitCount = n;
+        return this;
+    }
+    offset(n) {
+        this.offsetCount = n;
+        return this;
+    }
+    join(table, alias, onLeft, onRight) {
+        this.joinClause = { table, alias, onLeft, onRight };
+        return this;
+    }
+    similar(field, vector, options) {
+        this.similarityClause = {
+            field,
+            vector,
+            k: options.k,
+            filter: options.filter,
+        };
+        return this;
+    }
+    parseSimilarityPk(result, field) {
+        const metadata = result.metadata;
+        if (metadata && typeof metadata === 'object') {
+            for (const key of ['id', 'pk', 'row_id']) {
+                const value = metadata[key];
+                if (value != null)
+                    return String(value);
+            }
+        }
+        const expectedPrefix = `${this.name}:${field}:`;
+        if (result.key.startsWith(expectedPrefix)) {
+            return result.key.slice(expectedPrefix.length);
+        }
+        const segments = result.key.split(':');
+        if (segments.length > 0) {
+            return segments[segments.length - 1] || null;
+        }
+        return null;
+    }
+    async run() {
+        try {
+            let rows = [];
+            if (this.similarityClause) {
+                if (this.joinClause) {
+                    return err('SIMILAR_JOIN_UNSUPPORTED', 'similar(...) cannot be combined with join(...) yet');
+                }
+                const similarResults = await this.client.vsearch(this.similarityClause.vector, {
+                    k: this.similarityClause.k,
+                    filter: this.similarityClause.filter,
+                    meta: true,
+                });
+                for (const match of similarResults) {
+                    const pk = this.parseSimilarityPk(match, this.similarityClause.field);
+                    if (!pk)
+                        continue;
+                    const args = this.buildSelectArgs([{ field: 'id', op: '=', value: pk }]);
+                    const one = await this.client._tselect(args);
+                    if (one.length === 0)
+                        continue;
+                    rows.push({ ...one[0], _similarity: match.similarity });
+                }
+                if (this.offsetCount != null || this.limitCount != null) {
+                    const start = this.offsetCount ?? 0;
+                    const end = this.limitCount != null ? start + this.limitCount : undefined;
+                    rows = rows.slice(start, end);
+                }
+            }
+            else {
+                rows = await this.client._tselect(this.buildSelectArgs());
+            }
+            const validated = rows.map((row) => this.validateRow(row));
+            if (this.expectSingle) {
+                if (validated.length === 0) {
+                    return err('NOT_FOUND', `No rows found in table '${this.name}'`);
+                }
+                return ok(validated[0]);
+            }
+            return ok(validated);
+        }
+        catch (error) {
+            return err('TSELECT_ERROR', `Failed to query table '${this.name}'`, toLuxError(error));
+        }
+    }
+    then(onfulfilled, onrejected) {
+        return this.run().then(onfulfilled, onrejected);
+    }
+    async insert(data) {
+        try {
+            if (this.schema) {
+                this.validateRow(data);
+            }
+            const args = [this.name];
+            for (const [k, v] of Object.entries(data)) {
+                args.push(k, String(v));
+            }
+            const result = await this.client.call('TINSERT', ...args);
+            return ok(parseInt(result, 10) || 0);
+        }
+        catch (error) {
+            return err('TINSERT_ERROR', `Failed to insert into '${this.name}'`, toLuxError(error));
+        }
+    }
+    async update(idOrData, data) {
+        try {
+            const hasExplicitId = data !== undefined;
+            const patch = hasExplicitId ? data : idOrData;
+            if (!hasExplicitId && this.conditions.length === 0) {
+                return err('MISSING_WHERE', 'update requires at least one filter');
+            }
+            const args = [this.name, 'SET'];
+            for (const [k, v] of Object.entries(patch)) {
+                args.push(k, String(v));
+            }
+            args.push('WHERE');
+            if (hasExplicitId) {
+                args.push('id', '=', String(idOrData));
+            }
+            else {
+                for (let i = 0; i < this.conditions.length; i++) {
+                    const cond = this.conditions[i];
+                    args.push(cond.field, cond.op, String(cond.value));
+                    if (i < this.conditions.length - 1) {
+                        args.push('AND');
+                    }
+                }
+            }
+            const result = await this.client.call('TUPDATE', ...args);
+            return ok(Number(result) || 0);
+        }
+        catch (error) {
+            return err('TUPDATE_ERROR', `Failed to update '${this.name}'`, toLuxError(error));
+        }
+    }
+    async delete(...ids) {
+        try {
+            if (ids.length === 0) {
+                if (this.conditions.length === 0) {
+                    return err('MISSING_WHERE', 'delete requires at least one filter');
+                }
+                const args = ['FROM', this.name, 'WHERE'];
+                for (let i = 0; i < this.conditions.length; i++) {
+                    const cond = this.conditions[i];
+                    args.push(cond.field, cond.op, String(cond.value));
+                    if (i < this.conditions.length - 1) {
+                        args.push('AND');
+                    }
+                }
+                const result = await this.client.call('TDELETE', ...args);
+                return ok(Number(result) || 0);
+            }
+            let deleted = 0;
+            for (const id of ids) {
+                const result = await this.client.call('TDELETE', 'FROM', this.name, 'WHERE', 'id', '=', String(id));
+                deleted += Number(result) || 0;
+            }
+            return ok(deleted);
+        }
+        catch (error) {
+            return err('TDELETE_ERROR', `Failed to delete from '${this.name}'`, toLuxError(error));
+        }
+    }
+    subscribe() {
+        if (this.similarityClause) {
+            return new TableSubscription(this.client, this.name, (extra) => this.buildSelectArgs(extra), {
+                code: 'SIMILAR_SUBSCRIBE_UNSUPPORTED',
+                message: 'subscribe() is not supported on similar(...) queries yet',
+            });
+        }
+        return new TableSubscription(this.client, this.name, (extra) => this.buildSelectArgs(extra));
+    }
+}

package/dist/esm/types.js

@@ -0,0 +1 @@
+export {};

package/dist/esm/utils.js

@@ -0,0 +1,12 @@
+export function ok(data) {
+    return { data, error: null };
+}
+export function err(code, message, details) {
+    return { data: null, error: { code, message, details } };
+}
+export function toLuxError(error, fallbackCode = 'LUX_SDK_ERROR') {
+    if (typeof error === 'object' && error && 'message' in error) {
+        return { code: fallbackCode, message: String(error.message), details: error };
+    }
+    return { code: fallbackCode, message: String(error) };
+}

package/dist/types/auth.d.ts

@@ -0,0 +1,163 @@
+import type { LuxResult } from './types';
+export interface LuxAuthUser {
+    id: string;
+    email: string;
+    phone?: string;
+    email_confirmed_at?: number | null;
+    phone_confirmed_at?: number | null;
+    last_sign_in_at?: number | null;
+    created_at?: number | null;
+    updated_at?: number | null;
+    user_metadata?: Record<string, unknown>;
+    app_metadata?: Record<string, unknown>;
+}
+export interface LuxAuthSession {
+    access_token: string;
+    token_type: 'bearer';
+    expires_in: number;
+    refresh_token: string;
+    user: LuxAuthUser;
+    expires_at?: number;
+}
+export interface LuxAuthSessionResult {
+    session: LuxAuthSession | null;
+    user: LuxAuthUser | null;
+}
+export interface LuxAuthKey {
+    id: string;
+    name: string;
+    kind: 'publishable' | 'secret';
+    prefix: string;
+    scopes: string[];
+    created_at?: number | null;
+    revoked_at?: number | null;
+    last_used_at?: number | null;
+}
+export interface LuxAuthOptions {
+    httpUrl?: string;
+    apiKey?: string;
+    authToken?: string;
+    fetch?: typeof fetch;
+    persistSession?: boolean;
+    autoRefreshToken?: boolean;
+    storage?: LuxAuthStorage | null;
+    storageKey?: string;
+    refreshMarginSeconds?: number;
+}
+export interface LuxSignUpOptions {
+    email: string;
+    password: string;
+    data?: Record<string, unknown>;
+}
+export interface LuxSignInOptions {
+    email: string;
+    password: string;
+}
+export type LuxOAuthProvider = 'google' | 'github';
+export interface LuxSignInWithOAuthOptions {
+    provider: LuxOAuthProvider;
+    redirectTo?: string;
+    skipRedirect?: boolean;
+}
+export interface LuxOAuthUrl {
+    url: string;
+}
+export interface LuxCreateApiKeyOptions {
+    kind: 'publishable' | 'secret';
+    name?: string;
+}
+export interface LuxAuthProvider {
+    provider: LuxOAuthProvider;
+    enabled: boolean;
+    client_id: string;
+    redirect_uri: string;
+    scopes: string;
+    has_client_secret: boolean;
+    created_at?: number | null;
+    updated_at?: number | null;
+}
+export interface LuxUpsertProviderOptions {
+    provider: LuxOAuthProvider;
+    client_id: string;
+    client_secret?: string;
+    redirect_uri: string;
+    scopes?: string;
+    enabled?: boolean;
+}
+export type LuxAuthChangeEvent = 'INITIAL_SESSION' | 'SIGNED_IN' | 'TOKEN_REFRESHED' | 'SIGNED_OUT' | 'SESSION_UPDATED';
+export interface LuxAuthStorage {
+    getItem(key: string): string | null | Promise<string | null>;
+    setItem(key: string, value: string): void | Promise<void>;
+    removeItem(key: string): void | Promise<void>;
+}
+export type LuxAuthStateChangeCallback = (event: LuxAuthChangeEvent, session: LuxAuthSession | null) => void;
+export interface LuxAuthSubscription {
+    unsubscribe(): void;
+}
+export declare class LuxAuthClient {
+    private httpUrl?;
+    private apiKey?;
+    private authToken?;
+    private fetchImpl;
+    private persistSession;
+    private autoRefreshToken;
+    private storage;
+    private storageKey;
+    private refreshMarginSeconds;
+    private currentSession;
+    private loadedSession;
+    private refreshTimer;
+    private listeners;
+    constructor(options?: LuxAuthOptions);
+    getSession(): Promise<LuxResult<{
+        session: LuxAuthSession | null;
+    }>>;
+    private getSessionValue;
+    getAccessToken(): Promise<string | undefined>;
+    setSession(session: LuxAuthSession | string | null): Promise<LuxResult<{
+        session: LuxAuthSession | null;
+    }>>;
+    private setSessionValue;
+    clearSession(): Promise<LuxResult<null>>;
+    private clearSessionValue;
+    onAuthStateChange(callback: LuxAuthStateChangeCallback): LuxAuthSubscription;
+    signUp(options: LuxSignUpOptions): Promise<LuxResult<LuxAuthSessionResult>>;
+    signInWithPassword(options: LuxSignInOptions): Promise<LuxResult<LuxAuthSessionResult>>;
+    signInWithOAuth(options: LuxSignInWithOAuthOptions): Promise<LuxResult<LuxOAuthUrl>>;
+    consumeOAuthRedirect(url?: string): Promise<LuxResult<LuxAuthSessionResult>>;
+    refreshSession(refreshToken: string): Promise<LuxResult<LuxAuthSessionResult>>;
+    getUser(session?: Pick<LuxAuthSession, 'access_token'> | string): Promise<LuxResult<{
+        user: LuxAuthUser | null;
+    }>>;
+    logout(sessionOrRefreshToken?: Pick<LuxAuthSession, 'access_token' | 'refresh_token'> | string): Promise<LuxResult<null>>;
+    signOut(): Promise<LuxResult<null>>;
+    listUsers(): Promise<LuxResult<LuxAuthUser[]>>;
+    grantCapability(userId: string, capability: string): Promise<LuxResult<{
+        id: string;
+        user_id: string;
+        capability: string;
+        created_at: string;
+    }>>;
+    listUserGrants(userId: string): Promise<LuxResult<string[]>>;
+    revokeGrant(grantId: string): Promise<LuxResult<null>>;
+    listApiKeys(): Promise<LuxResult<LuxAuthKey[]>>;
+    listProviders(): Promise<LuxResult<LuxAuthProvider[]>>;
+    upsertProvider(options: LuxUpsertProviderOptions): Promise<LuxResult<LuxAuthProvider>>;
+    createApiKey(options: LuxCreateApiKeyOptions): Promise<LuxResult<{
+        key: LuxAuthKey;
+        plain_key: string;
+    }>>;
+    revokeApiKey(keyId: string): Promise<LuxResult<null>>;
+    get<T = unknown>(path: string, session?: Pick<LuxAuthSession, 'access_token'> | string): Promise<LuxResult<T>>;
+    post<T = unknown>(path: string, body?: unknown, session?: Pick<LuxAuthSession, 'access_token'> | string): Promise<LuxResult<T>>;
+    put<T = unknown>(path: string, body?: unknown, session?: Pick<LuxAuthSession, 'access_token'> | string): Promise<LuxResult<T>>;
+    delete<T = unknown>(path: string, session?: Pick<LuxAuthSession, 'access_token'> | string): Promise<LuxResult<T>>;
+    private tokenFrom;
+    private loadStoredSession;
+    private saveSession;
+    private scheduleRefresh;
+    private clearRefreshTimer;
+    private emit;
+    private requestResult;
+    private requestRaw;
+}

package/dist/types/browser.d.ts

@@ -0,0 +1,4 @@
+import { type LuxProjectOptions } from './project';
+export interface LuxBrowserClientOptions extends Omit<LuxProjectOptions, 'url' | 'key'> {
+}
+export declare function createBrowserClient(url: string, key: string, options?: LuxBrowserClientOptions): import("./project").LuxProjectClient;