clefbase 1.0.0

package/dist/auth/index.js

@@ -0,0 +1,271 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Auth = void 0;
+/**
+ * Stores the session in memory and optionally in localStorage (browser).
+ * On Node.js localStorage is not available so only in-memory is used.
+ */
+class SessionStore {
+    constructor() {
+        this.session = null;
+        this.STORAGE_KEY = "cfb_session";
+    }
+    get ls() {
+        try {
+            return typeof localStorage !== "undefined" ? localStorage : null;
+        }
+        catch {
+            return null;
+        }
+    }
+    save(s) {
+        this.session = s;
+        try {
+            this.ls?.setItem(this.STORAGE_KEY, JSON.stringify(s));
+        }
+        catch { /* quota exceeded or private mode */ }
+    }
+    load() {
+        if (this.session)
+            return this.session;
+        try {
+            const raw = this.ls?.getItem(this.STORAGE_KEY);
+            if (raw) {
+                const parsed = JSON.parse(raw);
+                if (new Date(parsed.expiresAt) > new Date()) {
+                    this.session = parsed;
+                    return this.session;
+                }
+                // Expired — clean up
+                this.ls?.removeItem(this.STORAGE_KEY);
+            }
+        }
+        catch { /* corrupted data */ }
+        return null;
+    }
+    clear() {
+        this.session = null;
+        try {
+            this.ls?.removeItem(this.STORAGE_KEY);
+        }
+        catch { /* ignore */ }
+    }
+}
+/**
+ * Authentication service. Obtain via `getAuth(app)`.
+ *
+ * @example
+ * import { initClefbase, getAuth } from "clefbase";
+ * const app = initClefbase({ serverUrl, projectId, apiKey });
+ * const auth = getAuth(app);
+ *
+ * const { user } = await auth.signUp("alice@example.com", "secret123");
+ * const { user } = await auth.signIn("alice@example.com", "secret123");
+ * console.log(auth.currentUser);
+ * await auth.signOut();
+ *
+ * const unsub = auth.onAuthStateChanged((u) => console.log(u));
+ * unsub(); // stop listening
+ */
+class Auth {
+    constructor(http) {
+        this.http = http;
+        this.store = new SessionStore();
+        this.listeners = [];
+        // Attempt to restore a persisted session on startup
+        this.store.load();
+    }
+    // ─── Internal ──────────────────────────────────────────────────────────────
+    notify(user) {
+        for (const cb of this.listeners) {
+            try {
+                cb(user);
+            }
+            catch { /* don't let a listener crash the SDK */ }
+        }
+    }
+    handleResult(result) {
+        this.store.save({
+            token: result.token,
+            expiresAt: result.session.expiresAt,
+            user: result.user,
+        });
+        this.notify(result.user);
+        return result;
+    }
+    /** @internal Used by Storage to attach the auth token to upload requests. */
+    getAuthHeaders() {
+        const session = this.store.load();
+        return session ? { Authorization: `Bearer ${session.token}` } : {};
+    }
+    // ─── Public API ─────────────────────────────────────────────────────────────
+    /** The currently signed-in user, or null if no session exists. */
+    get currentUser() {
+        return this.store.load()?.user ?? null;
+    }
+    /** The raw bearer token for the active session, or null. */
+    get currentToken() {
+        return this.store.load()?.token ?? null;
+    }
+    /**
+     * Create a new account with email + password.
+     *
+     * @example
+     * const { user } = await auth.signUp("alice@example.com", "pass123", {
+     *   displayName: "Alice",
+     *   metadata: { role: "admin" },
+     * });
+     */
+    async signUp(email, password, profile) {
+        const result = await this.http.post("/auth/signup", {
+            email,
+            password,
+            ...profile,
+        });
+        return this.handleResult(result);
+    }
+    /**
+     * Sign in with email + password.
+     *
+     * @example
+     * const { user, token } = await auth.signIn("alice@example.com", "pass123");
+     */
+    async signIn(email, password) {
+        const result = await this.http.post("/auth/signin", {
+            email,
+            password,
+        });
+        return this.handleResult(result);
+    }
+    /**
+     * Sign out the current user and clear the local session.
+     */
+    async signOut() {
+        const token = this.currentToken;
+        if (token) {
+            try {
+                await this.http.post("/auth/signout", undefined, {
+                    Authorization: `Bearer ${token}`,
+                });
+            }
+            catch {
+                // Always clear locally even if the server call fails
+            }
+        }
+        this.store.clear();
+        this.notify(null);
+    }
+    /**
+     * Re-fetch the current user's profile from the server and update the cache.
+     * Useful after an admin changes the user's data server-side.
+     */
+    async refreshCurrentUser() {
+        const token = this.currentToken;
+        if (!token)
+            return null;
+        try {
+            const user = await this.http.get("/auth/me", {
+                Authorization: `Bearer ${token}`,
+            });
+            const session = this.store.load();
+            if (session)
+                this.store.save({ ...session, user });
+            this.notify(user);
+            return user;
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Update the signed-in user's profile.
+     *
+     * @example
+     * await auth.updateProfile({ displayName: "Bob", metadata: { theme: "dark" } });
+     */
+    async updateProfile(updates) {
+        const token = this.currentToken;
+        if (!token)
+            throw new Error("No user is currently signed in.");
+        const user = await this.http.patch("/auth/me", updates, {
+            Authorization: `Bearer ${token}`,
+        });
+        const session = this.store.load();
+        if (session)
+            this.store.save({ ...session, user });
+        this.notify(user);
+        return user;
+    }
+    /**
+     * Change the signed-in user's password.
+     * All other active sessions are invalidated on the server.
+     */
+    async changePassword(currentPassword, newPassword) {
+        const token = this.currentToken;
+        if (!token)
+            throw new Error("No user is currently signed in.");
+        await this.http.post("/auth/change-password", { currentPassword, newPassword }, { Authorization: `Bearer ${token}` });
+    }
+    /**
+     * Request a password-reset email. Safe to call even if the address
+     * is not registered (server returns the same response either way).
+     */
+    async sendPasswordResetEmail(email) {
+        await this.http.post("/auth/forgot-password", { email });
+    }
+    /**
+     * Complete a password reset with the token from the reset email.
+     */
+    async confirmPasswordReset(resetToken, newPassword) {
+        await this.http.post("/auth/reset-password", {
+            token: resetToken,
+            newPassword,
+        });
+    }
+    /**
+     * Send an email verification code to the currently signed-in user.
+     */
+    async sendEmailVerification() {
+        const token = this.currentToken;
+        if (!token)
+            throw new Error("No user is currently signed in.");
+        await this.http.post("/auth/send-verification", undefined, {
+            Authorization: `Bearer ${token}`,
+        });
+    }
+    /**
+     * Verify the current user's email with the code they received.
+     *
+     * @example
+     * const user = await auth.verifyEmail("ABC123");
+     */
+    async verifyEmail(code) {
+        return this.http.post("/auth/verify-email", { code });
+    }
+    /**
+     * Subscribe to auth state changes.
+     * The callback fires immediately with the current user, then on every change.
+     * Returns an unsubscribe function.
+     *
+     * @example
+     * const unsubscribe = auth.onAuthStateChanged((user) => {
+     *   if (user) console.log("signed in:", user.email);
+     *   else console.log("signed out");
+     * });
+     * // Later:
+     * unsubscribe();
+     */
+    onAuthStateChanged(callback) {
+        this.listeners.push(callback);
+        // Emit the current state immediately
+        try {
+            callback(this.currentUser);
+        }
+        catch { /* don't crash on listener error */ }
+        return () => {
+            this.listeners = this.listeners.filter((cb) => cb !== callback);
+        };
+    }
+}
+exports.Auth = Auth;
+//# sourceMappingURL=index.js.map

package/dist/auth/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/auth/index.ts"],"names":[],"mappings":"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"}

package/dist/db/index.d.ts

@@ -0,0 +1,165 @@
+import { HttpClient } from "../http";
+import type { ClefbaseDocument, QueryResult, WhereClause } from "../types";
+export type { WhereClause, WhereValue } from "../types";
+/**
+ * A typed reference to a single document.
+ *
+ * @example
+ * const ref = db.collection("users").doc("abc123");
+ * const user = await ref.get();            // T | null
+ * await ref.update({ name: "Alice" });     // merge patch
+ * await ref.set({ name: "Alice", age: 30 }); // full overwrite
+ * await ref.delete();
+ *
+ * // Subcollection
+ * const comments = ref.subcollection("comments");
+ */
+export declare class DocumentReference<T extends ClefbaseDocument = ClefbaseDocument> {
+    private readonly http;
+    /** Full collection path, e.g. "users" or "users/uid/posts" */
+    readonly collectionPath: string;
+    readonly id: string;
+    constructor(http: HttpClient, 
+    /** Full collection path, e.g. "users" or "users/uid/posts" */
+    collectionPath: string, id: string);
+    /** Fetch this document. Returns null when it does not exist. */
+    get(): Promise<T | null>;
+    /**
+     * Patch this document.
+     * By default fields are merged; pass `{ merge: false }` to fully replace.
+     *
+     * @example
+     * await ref.update({ score: 42 });
+     * await ref.update({ score: 42 }, { merge: false }); // replaces whole doc
+     */
+    update(data: Partial<Omit<T, "_id" | "_createdAt" | "_updatedAt">>, opts?: {
+        merge?: boolean;
+    }): Promise<T>;
+    /**
+     * Overwrite this document entirely (no merge).
+     *
+     * @example
+     * await ref.set({ name: "Bob", age: 25 });
+     */
+    set(data: Omit<T, "_id" | "_createdAt" | "_updatedAt">): Promise<T>;
+    /** Delete this document (and all its subcollections on the server). */
+    delete(): Promise<void>;
+    /**
+     * Access a subcollection nested under this document.
+     *
+     * @example
+     * const comments = db.collection("posts").doc("p1").subcollection("comments");
+     * await comments.add({ text: "Great!" });
+     */
+    subcollection<S extends ClefbaseDocument = ClefbaseDocument>(name: string): CollectionReference<S>;
+}
+/**
+ * A chainable query builder.
+ *
+ * @example
+ * const docs = await db.collection("orders")
+ *   .where({ status: "pending", total: { $gt: 50 } })
+ *   .orderBy("_createdAt", "desc")
+ *   .limit(20)
+ *   .offset(0)
+ *   .getDocs();
+ */
+export declare class Query<T extends ClefbaseDocument = ClefbaseDocument> {
+    protected readonly http: HttpClient;
+    protected readonly path: string;
+    protected _filter: Record<string, unknown>;
+    protected _sort?: {
+        field: string;
+        dir: "asc" | "desc";
+    };
+    protected _limit: number;
+    protected _offset: number;
+    constructor(http: HttpClient, path: string);
+    /**
+     * Filter documents by field values or operators.
+     * Multiple calls are merged together (AND logic).
+     *
+     * @example
+     * .where({ published: true })
+     * .where({ views: { $gte: 100 } })
+     */
+    where(clauses: WhereClause): this;
+    /** Sort by a field. Default direction is ascending. */
+    orderBy(field: string, dir?: "asc" | "desc"): this;
+    /** Cap results at n (server maximum: 500). */
+    limit(n: number): this;
+    /** Skip the first n results (for pagination). */
+    offset(n: number): this;
+    /** Execute and return the full paginated result object. */
+    query(): Promise<QueryResult<T>>;
+    /** Execute and return just the document array. */
+    getDocs(): Promise<T[]>;
+}
+/**
+ * A reference to a collection (or subcollection path).
+ *
+ * @example
+ * const col = db.collection("users");
+ *
+ * // Add
+ * const user = await col.add({ name: "Alice", age: 30 });
+ *
+ * // List (no filter)
+ * const { data, total } = await col.list({ limit: 20 });
+ *
+ * // Query (with filter / sort)
+ * const adults = await col.where({ age: { $gte: 18 } }).orderBy("name").getDocs();
+ */
+export declare class CollectionReference<T extends ClefbaseDocument = ClefbaseDocument> extends Query<T> {
+    constructor(http: HttpClient, path: string);
+    /** Return a DocumentReference for a given ID without fetching. */
+    doc(id: string): DocumentReference<T>;
+    /** Add a new document with a server-generated ID. */
+    add(data: Omit<T, "_id" | "_createdAt" | "_updatedAt">): Promise<T>;
+    /**
+     * Fetch documents without any query filter — useful for simple pagination.
+     * For filtering/sorting use the inherited `.where()` / `.orderBy()` chain.
+     *
+     * @example
+     * const { data, total } = await col.list({ limit: 10, offset: 20 });
+     */
+    list(opts?: {
+        limit?: number;
+        offset?: number;
+    }): Promise<QueryResult<T>>;
+}
+/**
+ * Top-level database service.
+ * Obtain via `getDatabase(app)`.
+ *
+ * @example
+ * import { initClefbase, getDatabase } from "clefbase";
+ * const app = initClefbase({ serverUrl, projectId, apiKey });
+ * const db = getDatabase(app);
+ *
+ * // Reference-based API
+ * const post = await db.collection("posts").doc("p1").get();
+ *
+ * // Convenience helpers
+ * const user = await db.getDoc("users", "uid-123");
+ * const newDoc = await db.addDoc("logs", { action: "login" });
+ * await db.updateDoc("users", "uid-123", { lastSeen: new Date().toISOString() });
+ * await db.deleteDoc("users", "uid-123");
+ */
+export declare class Database {
+    private readonly http;
+    constructor(http: HttpClient);
+    /** Return a CollectionReference for a top-level collection. */
+    collection<T extends ClefbaseDocument = ClefbaseDocument>(name: string): CollectionReference<T>;
+    /** Fetch a single document by collection name and ID. Returns null if not found. */
+    getDoc<T extends ClefbaseDocument = ClefbaseDocument>(collectionName: string, id: string): Promise<T | null>;
+    /** Add a document to a collection and return it with server-set fields. */
+    addDoc<T extends ClefbaseDocument = ClefbaseDocument>(collectionName: string, data: Omit<T, "_id" | "_createdAt" | "_updatedAt">): Promise<T>;
+    /** Patch a document. Merges by default; pass `{ merge: false }` to overwrite. */
+    updateDoc<T extends ClefbaseDocument = ClefbaseDocument>(collectionName: string, id: string, data: Partial<Omit<T, "_id" | "_createdAt" | "_updatedAt">>, opts?: {
+        merge?: boolean;
+    }): Promise<T>;
+    /** Delete a document. */
+    deleteDoc(collectionName: string, id: string): Promise<void>;
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/db/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/db/index.ts"],"names":[],"mappings":"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"}

package/dist/db/index.js

@@ -0,0 +1,230 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Database = exports.CollectionReference = exports.Query = exports.DocumentReference = void 0;
+// ─── DocumentReference ────────────────────────────────────────────────────────
+/**
+ * A typed reference to a single document.
+ *
+ * @example
+ * const ref = db.collection("users").doc("abc123");
+ * const user = await ref.get();            // T | null
+ * await ref.update({ name: "Alice" });     // merge patch
+ * await ref.set({ name: "Alice", age: 30 }); // full overwrite
+ * await ref.delete();
+ *
+ * // Subcollection
+ * const comments = ref.subcollection("comments");
+ */
+class DocumentReference {
+    constructor(http, 
+    /** Full collection path, e.g. "users" or "users/uid/posts" */
+    collectionPath, id) {
+        this.http = http;
+        this.collectionPath = collectionPath;
+        this.id = id;
+    }
+    /** Fetch this document. Returns null when it does not exist. */
+    async get() {
+        try {
+            return await this.http.get(`/${this.collectionPath}/${this.id}`);
+        }
+        catch (err) {
+            const status = err.status;
+            if (status === 404)
+                return null;
+            throw err;
+        }
+    }
+    /**
+     * Patch this document.
+     * By default fields are merged; pass `{ merge: false }` to fully replace.
+     *
+     * @example
+     * await ref.update({ score: 42 });
+     * await ref.update({ score: 42 }, { merge: false }); // replaces whole doc
+     */
+    async update(data, opts) {
+        const merge = opts?.merge ?? true;
+        return this.http.put(`/${this.collectionPath}/${this.id}?merge=${String(merge)}`, data);
+    }
+    /**
+     * Overwrite this document entirely (no merge).
+     *
+     * @example
+     * await ref.set({ name: "Bob", age: 25 });
+     */
+    async set(data) {
+        return this.http.put(`/${this.collectionPath}/${this.id}?merge=false`, data);
+    }
+    /** Delete this document (and all its subcollections on the server). */
+    async delete() {
+        await this.http.delete(`/${this.collectionPath}/${this.id}`);
+    }
+    /**
+     * Access a subcollection nested under this document.
+     *
+     * @example
+     * const comments = db.collection("posts").doc("p1").subcollection("comments");
+     * await comments.add({ text: "Great!" });
+     */
+    subcollection(name) {
+        return new CollectionReference(this.http, `${this.collectionPath}/${this.id}/${name}`);
+    }
+}
+exports.DocumentReference = DocumentReference;
+// ─── Query ────────────────────────────────────────────────────────────────────
+/**
+ * A chainable query builder.
+ *
+ * @example
+ * const docs = await db.collection("orders")
+ *   .where({ status: "pending", total: { $gt: 50 } })
+ *   .orderBy("_createdAt", "desc")
+ *   .limit(20)
+ *   .offset(0)
+ *   .getDocs();
+ */
+class Query {
+    constructor(http, path) {
+        this.http = http;
+        this.path = path;
+        this._filter = {};
+        this._limit = 50;
+        this._offset = 0;
+    }
+    /**
+     * Filter documents by field values or operators.
+     * Multiple calls are merged together (AND logic).
+     *
+     * @example
+     * .where({ published: true })
+     * .where({ views: { $gte: 100 } })
+     */
+    where(clauses) {
+        this._filter = { ...this._filter, ...clauses };
+        return this;
+    }
+    /** Sort by a field. Default direction is ascending. */
+    orderBy(field, dir = "asc") {
+        this._sort = { field, dir };
+        return this;
+    }
+    /** Cap results at n (server maximum: 500). */
+    limit(n) {
+        this._limit = Math.min(n, 500);
+        return this;
+    }
+    /** Skip the first n results (for pagination). */
+    offset(n) {
+        this._offset = n;
+        return this;
+    }
+    /** Execute and return the full paginated result object. */
+    async query() {
+        const body = {
+            filter: Object.keys(this._filter).length > 0 ? this._filter : undefined,
+            sort: this._sort,
+            limit: this._limit,
+            offset: this._offset,
+        };
+        return this.http.post(`/${this.path}/query`, body);
+    }
+    /** Execute and return just the document array. */
+    async getDocs() {
+        const result = await this.query();
+        return result.data;
+    }
+}
+exports.Query = Query;
+// ─── CollectionReference ──────────────────────────────────────────────────────
+/**
+ * A reference to a collection (or subcollection path).
+ *
+ * @example
+ * const col = db.collection("users");
+ *
+ * // Add
+ * const user = await col.add({ name: "Alice", age: 30 });
+ *
+ * // List (no filter)
+ * const { data, total } = await col.list({ limit: 20 });
+ *
+ * // Query (with filter / sort)
+ * const adults = await col.where({ age: { $gte: 18 } }).orderBy("name").getDocs();
+ */
+class CollectionReference extends Query {
+    constructor(http, path) {
+        super(http, path);
+    }
+    /** Return a DocumentReference for a given ID without fetching. */
+    doc(id) {
+        return new DocumentReference(this.http, this.path, id);
+    }
+    /** Add a new document with a server-generated ID. */
+    async add(data) {
+        return this.http.post(`/${this.path}`, data);
+    }
+    /**
+     * Fetch documents without any query filter — useful for simple pagination.
+     * For filtering/sorting use the inherited `.where()` / `.orderBy()` chain.
+     *
+     * @example
+     * const { data, total } = await col.list({ limit: 10, offset: 20 });
+     */
+    async list(opts) {
+        const limit = Math.min(opts?.limit ?? 50, 500);
+        const offset = opts?.offset ?? 0;
+        const qs = new URLSearchParams({
+            limit: String(limit),
+            offset: String(offset),
+        });
+        return this.http.get(`/${this.path}?${qs}`);
+    }
+}
+exports.CollectionReference = CollectionReference;
+// ─── Database ─────────────────────────────────────────────────────────────────
+/**
+ * Top-level database service.
+ * Obtain via `getDatabase(app)`.
+ *
+ * @example
+ * import { initClefbase, getDatabase } from "clefbase";
+ * const app = initClefbase({ serverUrl, projectId, apiKey });
+ * const db = getDatabase(app);
+ *
+ * // Reference-based API
+ * const post = await db.collection("posts").doc("p1").get();
+ *
+ * // Convenience helpers
+ * const user = await db.getDoc("users", "uid-123");
+ * const newDoc = await db.addDoc("logs", { action: "login" });
+ * await db.updateDoc("users", "uid-123", { lastSeen: new Date().toISOString() });
+ * await db.deleteDoc("users", "uid-123");
+ */
+class Database {
+    constructor(http) {
+        this.http = http;
+    }
+    /** Return a CollectionReference for a top-level collection. */
+    collection(name) {
+        return new CollectionReference(this.http, name);
+    }
+    /** Fetch a single document by collection name and ID. Returns null if not found. */
+    async getDoc(collectionName, id) {
+        return this.collection(collectionName).doc(id).get();
+    }
+    /** Add a document to a collection and return it with server-set fields. */
+    async addDoc(collectionName, data) {
+        return this.collection(collectionName).add(data);
+    }
+    /** Patch a document. Merges by default; pass `{ merge: false }` to overwrite. */
+    async updateDoc(collectionName, id, data, opts) {
+        return this.collection(collectionName).doc(id).update(data, opts);
+    }
+    /** Delete a document. */
+    async deleteDoc(collectionName, id) {
+        return this.collection(collectionName).doc(id).delete();
+    }
+}
+exports.Database = Database;
+//# sourceMappingURL=index.js.map