moa-db-sdk

A high-privacy, modular TypeScript and Go SDK designed for the Secure Go-Firebase (SGF) platform. This SDK mimics the modern Firebase v9+ functional API, enabling tree-shaking, smaller bundle sizes, and an easy developer experience.

📦 Installation

TypeScript / Node.js

If you are using the SDK locally, you can install it via the file path:

npm install moa-db-sdk

yarn add moa-db-sdk

Or link it for development:

cd moa-db-sdk && npm link
cd your-project && npm link moa-db-sdk

🚀 Quick Start

1. Initialize the App

The FirebaseApp instance acts as the central hub, managing your configuration and global JWT session.

import { initializeApp } from "moa-db-sdk/app";

const app = initializeApp({
  authUrl: "http://localhost:4001",
  firestoreUrl: "http://localhost:4002",
  realtimeUrl: "http://localhost:4003", // Use http, SDK converts to ws internally
  storageUrl: "http://localhost:4004"
});

🔐 Authentication (/auth)

Handles user registration, login, and session persistence.

import { getAuth, signInWithEmailAndPassword, onAuthStateChanged } from "moa-db-sdk/auth";

const auth = getAuth(app);

// Listen for login/logout
onAuthStateChanged(auth, (user) => {
  if (user) console.log("Logged in as:", user.uid);
  else console.log("User is signed out");
});

// Sign In
const userCred = await signInWithEmailAndPassword(auth, "[email protected]", "password123");

🔥 Firestore (/firestore)

Persistent, document-based storage. All documents are encrypted on-disk by the Go backend.

import { getFirestore, doc, setDoc, updateDoc, arrayUnion } from "moa-db-sdk/firestore";

const db = getFirestore(app);

// Create or Overwrite
await setDoc(doc(db, "users", "uid_123"), {
  name: "Amine",
  location: "Dublin"
});

// Update with Array Union (Atomic)
await updateDoc(doc(db, "users", "uid_123"), {
  tags: arrayUnion("golang", "typescript"),
  updatedAt: new Date().toISOString()
});

📡 Realtime Database (/database)

WebSocket-based live synchronization.

import { getDatabase, ref, onValue, set, push } from "moa-db-sdk/database";

const rtdb = getDatabase(app);
const chatRef = ref(rtdb, "chats/room1");

// Listen for live updates
const unsubscribe = onValue(chatRef, (snapshot) => {
  console.log("New message in room:", snapshot.val());
});

// Push new data with unique ID
const newMsgRef = push(chatRef);
await set(newMsgRef, { text: "Hello world!" });

// Stop listening
// unsubscribe();

📦 Cloud Storage (/storage)

Binary file management for images, videos, and documents.

import { getStorage, ref, uploadBytes, getDownloadURL } from "moa-db-sdk/storage";

const storage = getStorage(app);
const fileRef = ref(storage, "avatars/me.png");

// Upload a Blob or File
await uploadBytes(fileRef, myFileBlob);

// Get persistent download URL
const url = getDownloadURL(fileRef);
document.querySelector('img').src = url;

🛠️ API Reference

Modular Imports

This SDK is built to be modular. Only import the functions you use:

| Module | Purpose | | :--- | :--- | | moa-db-sdk/app | Core configuration and app lifecycle. | | moa-db-sdk/auth | Login, Signup, Reset, Custom Tokens. | | moa-db-sdk/firestore | Encrypted persistent JSON documents. | | moa-db-sdk/database | WebSocket-based realtime state. | | moa-db-sdk/storage | Encrypted binary file storage. |

Key Differences from Official Firebase

1. Protocol: Firestore and Storage use standard HTTP, while Database uses WebSockets.
2. Encryption: All data is encrypted using AES-256-GCM on the server. The SDK automatically handles the Bearer token headers for you.
3. Local-First: Designed to work with the Secure Go-Firebase Emulators running locally or in a private cloud.

📜 Build and Develop

To build the SDK from source:

npm install
npm run build

The build generates:

• dist/index.js (ESM)
• dist/index.cjs (CommonJS)
• dist/index.d.ts (TypeScript Definitions)

Secure Go-Firebase SDK | Created for high-privacy local-first applications.