edmaxlabs-core 1.0.0

package/README.md

@@ -0,0 +1,99 @@
+# edmaxlabs-core
+
+**edmaxlabs-core** is the official runtime SDK for building applications on the **EdmaxLabs platform**.
+
+It provides a unified, developer-friendly interface to EdmaxLabs services such as **Database**, **Storage**, **Authentication**, and **Cloud Functions**, enabling you to build modern applications faster across web, server, and future platforms.
+
+🌐 Learn more at **[https://edmaxlabs.com](https://edmaxlabs.com)**
+
+---
+
+## ✨ What is edmaxlabs-core?
+
+`edmaxlabs-core` is designed to be used **inside your applications** (React, vanilla JavaScript, Node.js, and more).
+It acts as the bridge between your app and EdmaxLabs infrastructure, handling communication, real-time updates, and security-aware access patterns.
+
+This package focuses on:
+
+- Clean APIs
+- Minimal footprint
+- Cross-platform compatibility
+- Long-term API stability
+
+---
+
+## 🚀 Features
+
+- 🔐 **Authentication** – Secure user sign-in and session handling
+- 🗄️ **Database** – Read and write structured data with real-time capabilities
+- 📦 **Storage** – Upload, download, and manage files
+- ⚡ **Cloud Functions** – Call server-side logic from your app
+- 🔄 **Realtime** – Subscribe to live data updates
+- 🧩 **Framework-agnostic** – Works with React, plain HTML/JS, Node.js, and more
+
+---
+
+## 📦 Installation
+
+```bash
+npm install edmaxlabs-core
+```
+
+---
+
+## 🧠 Example Usage
+
+```ts
+import { EdmaxLabs } from "edmaxlabs-core";
+
+const edmax = new EdmaxLabs({
+  projectId: "your-project-id",
+  apiKey: "your-public-api-key",
+});
+
+const data = await edmax.db.collection("messages").get();
+console.log(data);
+```
+
+---
+
+## 🎯 Who is this for?
+
+- Frontend developers (React, Vite, Next.js, HTML)
+- Backend developers (Node.js)
+- Teams building SaaS, dashboards, or real-time apps
+- Anyone using EdmaxLabs services in production apps
+
+---
+
+## 🔐 Security Philosophy
+
+`edmaxlabs-core` assumes:
+
+- Client keys are **public**
+- Access is enforced by **rules and server validation**
+- The client SDK provides **convenience**, not trust
+
+All sensitive operations are validated server-side.
+
+---
+
+## 🧱 Ecosystem
+
+- **edmaxlabs-tools** → management CLI for projects, hosting, rules and more.
+- **edmaxlabs-core** → Runtime SDK for apps
+- More SDKs and integrations coming soon
+
+---
+
+## 📜 License
+
+MIT © EdmaxLabs
+
+---
+
+## 🧠 Vision
+
+> Build once. Scale everywhere. Stay in control.
+
+`edmaxlabs-core` is built to power applications today — and grow with you tomorrow.

package/dist/index.d.mts

@@ -0,0 +1,250 @@
+import * as idb from 'idb';
+import * as _socket_io_component_emitter from '@socket.io/component-emitter';
+import { Socket } from 'socket.io-client';
+
+interface TimestampData {
+    seconds: number;
+    nanoseconds: number;
+}
+interface TimestampJSON {
+    _type: "timestamp";
+    seconds: number;
+    nanoseconds: number;
+}
+declare class Timestamp implements TimestampData {
+    seconds: number;
+    nanoseconds: number;
+    constructor(seconds: number, nanoseconds?: number);
+    static now(): Timestamp;
+    static fromDate(date: Date): Timestamp;
+    static fromMillis(ms: number): Timestamp;
+    static fromMongo(dateObj: Date): Timestamp;
+    static fromJSON(obj: Record<string, number>): Timestamp;
+    toDate(): Date;
+    toMillis(): number;
+    sinceEpoch(): number;
+    toMongo(): Date;
+    format(pattern?: string): string;
+    compare(other: Timestamp): number;
+    relative(fmt?: string): string;
+    add({ seconds, minutes, hours, days, }: {
+        seconds?: number;
+        minutes?: number;
+        hours?: number;
+        days?: number;
+    }): Timestamp;
+    weekdayName(): string;
+    toJSON(): TimestampJSON;
+    toString(): string;
+}
+
+interface DisplayInfo {
+    firstname: string;
+    lastname: string;
+    surname: string;
+    profile: string;
+    email: string;
+    phone: string;
+}
+declare class Credentials {
+    uid: string;
+    displayInfo: DisplayInfo;
+    createdAt: Timestamp;
+    updatedAt: Timestamp;
+    lastLogged: Timestamp;
+    private constructor();
+    static fromMap(map: Record<string, any>): Credentials;
+    toMap(): Record<string, any>;
+}
+
+declare class Authentication {
+    static instance: Authentication | null;
+    private eUser?;
+    private client;
+    private app;
+    constructor();
+    private init;
+    private saveCredentials;
+    currentUser: () => Credentials | undefined;
+    authState: ({ onChange, onSignOut, onDeleted, }: {
+        onChange: (data: Credentials) => void;
+        onDeleted?: () => void;
+        onSignOut?: () => void;
+    }) => void;
+    createUserWithEmailAndPassword: ({ email, password, }: {
+        email: string;
+        password: string;
+    }) => Promise<Credentials | null>;
+    signInWithEmailAndPassword: ({ email, password, }: {
+        email: string;
+        password: string;
+    }) => Promise<Credentials | null>;
+    deleteUser: () => Promise<void>;
+    signOut: () => Promise<void>;
+}
+
+declare class ArraySnapshot {
+    id?: string;
+    data: Record<string, any>;
+    dt: Timestamp;
+    private constructor();
+    static fromMap(map: Record<string, any>): ArraySnapshot;
+    toMap(): Record<string, any>;
+}
+
+declare class Array {
+    db: EdmaxLabs;
+    collection: string;
+    key: string;
+    docID: string;
+    constructor(db: EdmaxLabs, collection: string, key: string, id: string);
+    show(): Promise<ArraySnapshot[]>;
+    push(data: any, id?: string): Promise<ArraySnapshot | null>;
+    update(position: number, data: any, id?: string): Promise<ArraySnapshot | null>;
+    insert(position: number, data: any, id?: string): Promise<ArraySnapshot | null>;
+    get(position: number): Promise<ArraySnapshot | null>;
+    remove(position: number): Promise<ArraySnapshot | null>;
+}
+
+declare class DocumentSnapshot {
+    id: string;
+    data: Record<string, any>;
+    private constructor();
+    static fromMap(map: Record<string, any>): DocumentSnapshot;
+    toMap(): Record<string, any>;
+}
+
+declare class DocumentRef {
+    db: EdmaxLabs;
+    collection: string;
+    id: string;
+    constructor(db: EdmaxLabs, collection: string, id: string);
+    get(): Promise<DocumentSnapshot | null>;
+    set(data: any): Promise<DocumentSnapshot | null>;
+    update(data: any): Promise<DocumentSnapshot | null>;
+    delete(): Promise<DocumentSnapshot | null>;
+    array(key: string): Array;
+    /**
+     * Realtime listener for a single document
+     */
+    onSnapshot(callback: (snapshot: DocumentSnapshot, change: string) => void): () => void;
+}
+
+declare class CollectionRef$1 {
+    db: EdmaxLabs;
+    constructor(db: EdmaxLabs);
+    getIDB: (collection: string) => Promise<idb.IDBPDatabase<unknown>>;
+    syncPendingWrite(id: string, collection?: string): Promise<boolean | undefined>;
+    syncPendingWrites(collection: string): Promise<void>;
+}
+
+type FilterExpression = {
+    key: string;
+    op: "==" | "===" | "!=" | "<" | "<=" | ">" | ">=" | "in" | "nin" | "contains";
+    value: any;
+};
+declare class Query {
+    db: EdmaxLabs;
+    collection: string;
+    private filter;
+    constructor(db: EdmaxLabs, collection: string);
+    where(expression: FilterExpression): this;
+    private buildFilter;
+    get(): Promise<DocumentSnapshot[]>;
+    update(): Promise<DocumentSnapshot[]>;
+    onSnapshot(callback: (snapshot: DocumentSnapshot, change: string) => void): () => void;
+}
+
+declare class CollectionRef {
+    db: EdmaxLabs;
+    collection: string;
+    persistence: CollectionRef$1;
+    constructor(db: EdmaxLabs, collection: string);
+    doc(id: string): DocumentRef;
+    get query(): Query;
+    get(): Promise<DocumentSnapshot[]>;
+    add(data: any): Promise<DocumentSnapshot | null>;
+    /**
+     * Realtime listener for entire collection
+     */
+    onSnapshot(callback: (snapshot: DocumentSnapshot, change: string) => void): () => void;
+}
+
+declare class Batch {
+    app: EdmaxLabs;
+    ops: any[];
+    constructor(app: EdmaxLabs);
+    set(docRef: DocumentRef, data: any): this;
+    update(docRef: DocumentRef, data: any): this;
+    delete(docRef: DocumentRef): this;
+    commit(): Promise<any>;
+}
+
+declare class Database {
+    app: EdmaxLabs;
+    constructor(app: EdmaxLabs);
+    collection(name: string): CollectionRef;
+    doc(path: string): DocumentRef;
+    batch(): Batch;
+    runTransaction(transactionFn: (tx: {
+        ops: any[];
+        get: (docRef: DocumentRef) => Promise<any>;
+        set: (docRef: DocumentRef, data: any) => void;
+        update: (docRef: DocumentRef, data: any) => void;
+        delete: (docRef: DocumentRef) => void;
+    }) => Promise<void>): Promise<any>;
+}
+
+declare class Realtime {
+    db: EdmaxLabs;
+    socket: Socket | null;
+    events: string[];
+    constructor(db: EdmaxLabs);
+    connect(): Socket<_socket_io_component_emitter.DefaultEventsMap, _socket_io_component_emitter.DefaultEventsMap>;
+    on(event: string, cb: (...args: any[]) => void): void;
+    off(event: string, cb?: (...args: any[]) => void): void;
+    emit(event: string, data: any): void;
+    /**
+     * Realtime listener for entire collection
+     */
+    subscribeToCollection(collection: string, callback: (snapshot: DocumentSnapshot, change: string) => void, filter?: Record<string, any>): () => void;
+    /**
+     * Realtime listener for a single document
+     */
+    subscribeToDocument(collection: string, id: string, callback: (snapshot: DocumentSnapshot, change: string) => void): () => void;
+}
+
+declare class Functions {
+    app: EdmaxLabs;
+    constructor(app: EdmaxLabs);
+    call(functionName: string, data?: Record<string, any>): Promise<any>;
+}
+
+interface EdmaxLabsConfig {
+    token: string;
+    authToken: string;
+}
+declare class EdmaxLabs {
+    static instance: EdmaxLabs | null;
+    private baseUrl;
+    private socketUrl;
+    private auth;
+    private _db;
+    private realtime;
+    private persistence;
+    private persistence_worker;
+    constructor({ token, authToken }: EdmaxLabsConfig);
+    static allowPersistence(enable: boolean): void;
+    static initialize(config: EdmaxLabsConfig): EdmaxLabs;
+    get getPersistence(): boolean;
+    get getAuth(): Record<string, any>;
+    get getBaseUrl(): string;
+    get getSocketUrl(): string;
+    get database(): Database;
+    get functions(): Functions;
+    get rtdb(): Realtime;
+    sync(id: string, collection?: string): Promise<boolean | undefined>;
+    get authentication(): Authentication;
+}
+
+export { ArraySnapshot, Credentials, DisplayInfo, DocumentSnapshot, Timestamp, EdmaxLabs as default };

package/dist/index.d.ts

@@ -0,0 +1,250 @@
+import * as idb from 'idb';
+import * as _socket_io_component_emitter from '@socket.io/component-emitter';
+import { Socket } from 'socket.io-client';
+
+interface TimestampData {
+    seconds: number;
+    nanoseconds: number;
+}
+interface TimestampJSON {
+    _type: "timestamp";
+    seconds: number;
+    nanoseconds: number;
+}
+declare class Timestamp implements TimestampData {
+    seconds: number;
+    nanoseconds: number;
+    constructor(seconds: number, nanoseconds?: number);
+    static now(): Timestamp;
+    static fromDate(date: Date): Timestamp;
+    static fromMillis(ms: number): Timestamp;
+    static fromMongo(dateObj: Date): Timestamp;
+    static fromJSON(obj: Record<string, number>): Timestamp;
+    toDate(): Date;
+    toMillis(): number;
+    sinceEpoch(): number;
+    toMongo(): Date;
+    format(pattern?: string): string;
+    compare(other: Timestamp): number;
+    relative(fmt?: string): string;
+    add({ seconds, minutes, hours, days, }: {
+        seconds?: number;
+        minutes?: number;
+        hours?: number;
+        days?: number;
+    }): Timestamp;
+    weekdayName(): string;
+    toJSON(): TimestampJSON;
+    toString(): string;
+}
+
+interface DisplayInfo {
+    firstname: string;
+    lastname: string;
+    surname: string;
+    profile: string;
+    email: string;
+    phone: string;
+}
+declare class Credentials {
+    uid: string;
+    displayInfo: DisplayInfo;
+    createdAt: Timestamp;
+    updatedAt: Timestamp;
+    lastLogged: Timestamp;
+    private constructor();
+    static fromMap(map: Record<string, any>): Credentials;
+    toMap(): Record<string, any>;
+}
+
+declare class Authentication {
+    static instance: Authentication | null;
+    private eUser?;
+    private client;
+    private app;
+    constructor();
+    private init;
+    private saveCredentials;
+    currentUser: () => Credentials | undefined;
+    authState: ({ onChange, onSignOut, onDeleted, }: {
+        onChange: (data: Credentials) => void;
+        onDeleted?: () => void;
+        onSignOut?: () => void;
+    }) => void;
+    createUserWithEmailAndPassword: ({ email, password, }: {
+        email: string;
+        password: string;
+    }) => Promise<Credentials | null>;
+    signInWithEmailAndPassword: ({ email, password, }: {
+        email: string;
+        password: string;
+    }) => Promise<Credentials | null>;
+    deleteUser: () => Promise<void>;
+    signOut: () => Promise<void>;
+}
+
+declare class ArraySnapshot {
+    id?: string;
+    data: Record<string, any>;
+    dt: Timestamp;
+    private constructor();
+    static fromMap(map: Record<string, any>): ArraySnapshot;
+    toMap(): Record<string, any>;
+}
+
+declare class Array {
+    db: EdmaxLabs;
+    collection: string;
+    key: string;
+    docID: string;
+    constructor(db: EdmaxLabs, collection: string, key: string, id: string);
+    show(): Promise<ArraySnapshot[]>;
+    push(data: any, id?: string): Promise<ArraySnapshot | null>;
+    update(position: number, data: any, id?: string): Promise<ArraySnapshot | null>;
+    insert(position: number, data: any, id?: string): Promise<ArraySnapshot | null>;
+    get(position: number): Promise<ArraySnapshot | null>;
+    remove(position: number): Promise<ArraySnapshot | null>;
+}
+
+declare class DocumentSnapshot {
+    id: string;
+    data: Record<string, any>;
+    private constructor();
+    static fromMap(map: Record<string, any>): DocumentSnapshot;
+    toMap(): Record<string, any>;
+}
+
+declare class DocumentRef {
+    db: EdmaxLabs;
+    collection: string;
+    id: string;
+    constructor(db: EdmaxLabs, collection: string, id: string);
+    get(): Promise<DocumentSnapshot | null>;
+    set(data: any): Promise<DocumentSnapshot | null>;
+    update(data: any): Promise<DocumentSnapshot | null>;
+    delete(): Promise<DocumentSnapshot | null>;
+    array(key: string): Array;
+    /**
+     * Realtime listener for a single document
+     */
+    onSnapshot(callback: (snapshot: DocumentSnapshot, change: string) => void): () => void;
+}
+
+declare class CollectionRef$1 {
+    db: EdmaxLabs;
+    constructor(db: EdmaxLabs);
+    getIDB: (collection: string) => Promise<idb.IDBPDatabase<unknown>>;
+    syncPendingWrite(id: string, collection?: string): Promise<boolean | undefined>;
+    syncPendingWrites(collection: string): Promise<void>;
+}
+
+type FilterExpression = {
+    key: string;
+    op: "==" | "===" | "!=" | "<" | "<=" | ">" | ">=" | "in" | "nin" | "contains";
+    value: any;
+};
+declare class Query {
+    db: EdmaxLabs;
+    collection: string;
+    private filter;
+    constructor(db: EdmaxLabs, collection: string);
+    where(expression: FilterExpression): this;
+    private buildFilter;
+    get(): Promise<DocumentSnapshot[]>;
+    update(): Promise<DocumentSnapshot[]>;
+    onSnapshot(callback: (snapshot: DocumentSnapshot, change: string) => void): () => void;
+}
+
+declare class CollectionRef {
+    db: EdmaxLabs;
+    collection: string;
+    persistence: CollectionRef$1;
+    constructor(db: EdmaxLabs, collection: string);
+    doc(id: string): DocumentRef;
+    get query(): Query;
+    get(): Promise<DocumentSnapshot[]>;
+    add(data: any): Promise<DocumentSnapshot | null>;
+    /**
+     * Realtime listener for entire collection
+     */
+    onSnapshot(callback: (snapshot: DocumentSnapshot, change: string) => void): () => void;
+}
+
+declare class Batch {
+    app: EdmaxLabs;
+    ops: any[];
+    constructor(app: EdmaxLabs);
+    set(docRef: DocumentRef, data: any): this;
+    update(docRef: DocumentRef, data: any): this;
+    delete(docRef: DocumentRef): this;
+    commit(): Promise<any>;
+}
+
+declare class Database {
+    app: EdmaxLabs;
+    constructor(app: EdmaxLabs);
+    collection(name: string): CollectionRef;
+    doc(path: string): DocumentRef;
+    batch(): Batch;
+    runTransaction(transactionFn: (tx: {
+        ops: any[];
+        get: (docRef: DocumentRef) => Promise<any>;
+        set: (docRef: DocumentRef, data: any) => void;
+        update: (docRef: DocumentRef, data: any) => void;
+        delete: (docRef: DocumentRef) => void;
+    }) => Promise<void>): Promise<any>;
+}
+
+declare class Realtime {
+    db: EdmaxLabs;
+    socket: Socket | null;
+    events: string[];
+    constructor(db: EdmaxLabs);
+    connect(): Socket<_socket_io_component_emitter.DefaultEventsMap, _socket_io_component_emitter.DefaultEventsMap>;
+    on(event: string, cb: (...args: any[]) => void): void;
+    off(event: string, cb?: (...args: any[]) => void): void;
+    emit(event: string, data: any): void;
+    /**
+     * Realtime listener for entire collection
+     */
+    subscribeToCollection(collection: string, callback: (snapshot: DocumentSnapshot, change: string) => void, filter?: Record<string, any>): () => void;
+    /**
+     * Realtime listener for a single document
+     */
+    subscribeToDocument(collection: string, id: string, callback: (snapshot: DocumentSnapshot, change: string) => void): () => void;
+}
+
+declare class Functions {
+    app: EdmaxLabs;
+    constructor(app: EdmaxLabs);
+    call(functionName: string, data?: Record<string, any>): Promise<any>;
+}
+
+interface EdmaxLabsConfig {
+    token: string;
+    authToken: string;
+}
+declare class EdmaxLabs {
+    static instance: EdmaxLabs | null;
+    private baseUrl;
+    private socketUrl;
+    private auth;
+    private _db;
+    private realtime;
+    private persistence;
+    private persistence_worker;
+    constructor({ token, authToken }: EdmaxLabsConfig);
+    static allowPersistence(enable: boolean): void;
+    static initialize(config: EdmaxLabsConfig): EdmaxLabs;
+    get getPersistence(): boolean;
+    get getAuth(): Record<string, any>;
+    get getBaseUrl(): string;
+    get getSocketUrl(): string;
+    get database(): Database;
+    get functions(): Functions;
+    get rtdb(): Realtime;
+    sync(id: string, collection?: string): Promise<boolean | undefined>;
+    get authentication(): Authentication;
+}
+
+export { ArraySnapshot, Credentials, DisplayInfo, DocumentSnapshot, Timestamp, EdmaxLabs as default };