postbase 0.1.0

package/README.md

@@ -0,0 +1,211 @@
+[<img src="https://i.imgur.com/oRFWBv7.png" height="80px" />](https://buymeacoffee.com/umrashrf)
+
+![Home Page Screenshot](assets/img/HomePageScreenshot.png)
+
+<img alt="Node.js" src="https://github.com/umrashrf/postbase/raw/main/assets/img/node.js_logo.png?raw=true" height="100"> <img alt="Express.js" src="https://github.com/umrashrf/postbase/raw/main/assets/img/expresjs.png?raw=true" height="100"> <img alt="PostgreSQL" src="https://github.com/umrashrf/postbase/raw/main/assets/img/postgres.png?raw=true" height="100"> <img alt="Better-Auth" src="https://github.com/umrashrf/postbase/raw/main/assets/img/better-auth-logo-light.4b03f444.png?raw=true" height="100"> <img alt="Let's Encrypt" src="https://github.com/umrashrf/postbase/raw/main/assets/img/letsencrypt-logo-horizontal.png?raw=true" height="100">
+
+# Postbase
+
+Drop-in replacement for Firebase, production grade, open source, localhost first and self-hosted using Node.js, Express.js, BetterAuth and PostgreSQL (JSONB)
+
+Firebase 💔 | Supabase 💔 | Postbase ❤️
+
+Demo Preact app is included !
+
+## Features
+
+### Authentication Features
+
+- [x] Sign Up ➕👤
+- [x] Sign In 🔑
+- [x] Sign in with Google/Facebook/Apple etc. ➕👤
+- [x] Forgot Password ❓🔐
+- [x] Reset Password ♻️🔐
+- [x] Email Verification Email ✉️✔️
+- [x] Phone Verification Codes 📱✔️
+- [x] Delete User 👤❌
+
+Special thanks to [@better-auth/better-auth](https://github.com/better-auth/better-auth)
+
+### Database Features
+
+- [x] NoSQL Document Storage 🗄️
+- [x] Collections 📁
+- [x] Query functions 🔍
+- [x] CRUD Functions 🛠️
+- [x] Security Rules 🛡️
+- [x] Database Migrations 🛢️ → 🛢️
+
+### File Upload / Storage
+
+- [x] File Upload (https) 📄⬆️
+- [x] File Serving (https) 📄⬇️
+- [x] Security Rules 🛡️
+
+### Admin & System
+
+- [x] Admin SDK 👑🗄️
+- [x] Nginx Config 🧱
+- [x] Systemd Service ⚙️
+- [x] Git Push Deployment ⬆️🐙
+
+## Disclaimer !!!
+
+Brand new project launched 02 Nov 2025, this is boiler plate but working! Expect heavy changes coming every few hours until stable
+
+The project started with the help of LLMs but over time heavy use of LLMs stopped due to large uncontrolled changes.
+
+## Getting Started
+
+To create a new project with Postbase, all you have to do is clone this repo.
+
+```
+git clone https://github.com/umrashrf/postbase.git
+```
+
+then start backend and frontend servers and modify as needed!
+
+Both backend/ and frontend/ folders have their own README.md
+
+## Vision
+
+Make a drop-in replacement library for Firebase (keep same naming convention). So users can switch between Firebase and Postbase as they please.
+
+## Docs
+
+### Getting Started
+
+```javascript
+import { initializeApp } from "../lib/postbase/compat/firebase/app";
+import { getFirestore } from "../lib/postbase/compat/firebase/firestore/lite";
+import { getStorage } from "../lib/postbase/compat/firebase/storage";
+import { getDatabase } from "../lib/postbase/compat/firebase/database";
+
+const firebaseConfig = {
+    baseUrl: import.meta.env.VITE_API_BASE,
+};
+
+const app = initializeApp(firebaseConfig);
+
+export const db = getFirestore(app);
+export const storage = getStorage(app);
+export const rtdbClient = getDatabase(app);
+```
+
+### Authentication (Firebase Like API)
+
+#### Sign Up
+
+```javascript
+import { getAuth, createUserWithEmailAndPassword } from "./auth";
+
+const auth = getAuth();
+
+const userCredential = await createUserWithEmailAndPassword(auth, 'email', 'password');
+```
+
+#### Sign In
+
+```javascript
+import { getAuth, signInWithEmailAndPassword } from "./auth";
+
+const auth = getAuth();
+
+const userCredential = await signInWithEmailAndPassword(auth, 'email', 'password');
+```
+
+#### auth.onAuthStateChanged, auth.currentUser and auth.currentUser.getIdToken()
+
+```javascript
+import { auth } from './auth';
+
+auth.onAuthStateChanged(user => {
+    // user
+    auth.currentUser === user // true
+});
+
+const token = auth.currentUser.getIdToken();
+// token for API authentication and rules engine
+```
+
+Tip: Add this link https://email.riamu.io to your Sign Up page for your users to get a free email address
+
+### Document Storage (Firestore Like API)
+
+#### Collections, get/set/where/orderBy/limit/delete
+
+```javascript
+import { db } from "./postbase";
+
+const data = await db.collection('users').doc('docId').get();
+// getDoc(collection(db, 'users'), 'docId')
+
+await db.collection('users').set({ name: "Umair" }, { merge: true });
+// getDoc(collection(db, 'users'), 'docId')
+
+const reference = db.collection('users')
+    .where('name', '==', 'Umair')
+    .orderBy('createdAt')
+    .limit(5);
+// const reference = getDocs(query(collection(db, 'users'), where('name', '==', 'Umair'), orderBy('createdAt')))
+
+const docs = await reference.get();
+// const docs = await getDocs(reference);
+
+reference.onSnapshot(docs => {
+    // use docs
+});
+// onSnapshot(reference, docs => {
+// 
+// })
+```
+
+#### Admin Client
+
+```javascript
+import { createAdminClient } from './lib/postbase/compat/admin.js';
+import { authClient } from './admin/auth.js';
+
+const admin = createAdminClient({ authClient });
+
+const user = await admin.auth().getUser(userId);
+
+const doc = await admin.firestore().collection('collection').doc('docId').get();
+```
+
+### Todo
+- [ ] Firebase Functions Replacement (Backend API can be used for now)
+
+Important functions to replicate:
+
+```
+# https://firebase.google.com/docs/functions/schedule-functions
+const { onSchedule } = require("firebase-functions/scheduler");
+
+# https://firebase.google.com/docs/functions/callable
+const { onCall } = require("firebase-functions/https");
+
+# https://firebase.google.com/docs/functions/get-started
+const { onRequest } = require("firebase-functions/https");
+```
+
+- [ ] Firebase Storage Replacement (Support S3 and other backend)
+
+### In Progress
+- [ ] Testing
+
+### Done
+- [x] Firebase Authentication Replacement
+- [x] Firebase Firestore Replacement
+- [x] Firebase Storage Replacement (Filebased Only)
+- [x] Firebase Storage Replacement (HTTPS Based Upload)
+
+## Star History
+
+<a href="https://star-history.com/#umrashrf/postbase&Date">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=umrashrf/postbase&type=Date&theme=dark" />
+    <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=umrashrf/postbase&type=Date" />
+    <img alt="Star History Chart" src="https://api.star-history.com/svg?repos=umrashrf/postbase&type=Date" />
+  </picture>
+</a>

package/admin/404.html

@@ -0,0 +1,33 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+    <title>Page Not Found</title>
+
+    <style media="screen">
+      body { background: #ECEFF1; color: rgba(0,0,0,0.87); font-family: Roboto, Helvetica, Arial, sans-serif; margin: 0; padding: 0; }
+      #message { background: white; max-width: 360px; margin: 100px auto 16px; padding: 32px 24px 16px; border-radius: 3px; }
+      #message h3 { color: #888; font-weight: normal; font-size: 16px; margin: 16px 0 12px; }
+      #message h2 { color: #ffa100; font-weight: bold; font-size: 16px; margin: 0 0 8px; }
+      #message h1 { font-size: 22px; font-weight: 300; color: rgba(0,0,0,0.6); margin: 0 0 16px;}
+      #message p { line-height: 140%; margin: 16px 0 24px; font-size: 14px; }
+      #message a { display: block; text-align: center; background: #039be5; text-transform: uppercase; text-decoration: none; color: white; padding: 16px; border-radius: 4px; }
+      #message, #message a { box-shadow: 0 1px 3px rgba(0,0,0,0.12), 0 1px 2px rgba(0,0,0,0.24); }
+      #load { color: rgba(0,0,0,0.4); text-align: center; font-size: 13px; }
+      @media (max-width: 600px) {
+        body, #message { margin-top: 0; background: white; box-shadow: none; }
+        body { border-top: 16px solid #ffa100; }
+      }
+    </style>
+  </head>
+  <body>
+    <div id="message">
+      <h2>404</h2>
+      <h1>Page Not Found</h1>
+      <p>The specified file was not found on this website. Please check the URL for mistakes and try again.</p>
+      <h3>Why am I seeing this?</h3>
+      <p>This page was generated by the Firebase Command-Line Interface. To modify it, edit the <code>404.html</code> file in your project's configured <code>public</code> directory.</p>
+    </div>
+  </body>
+</html>

package/admin/README.md

@@ -0,0 +1,21 @@
+# Admin Panel
+
+This directory contains working but incomplete version of admin panel. It's work in progress. PRs are welcome!
+
+![Admin Panel Demo Screenshot](public/assets/img/admin-ui.png)
+
+## Install
+
+```
+cd admin
+cp template.env .env
+npm insall
+```
+
+Make sure your backend is running and double check admin/.env file is accurate.
+
+## Run
+
+```
+npm run dev
+```

package/admin/index.html

@@ -0,0 +1,15 @@
+<!doctype html>
+<html>
+
+<head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width,initial-scale=1" />
+    <title>Postbase Demo</title>
+</head>
+
+<body>
+    <div id="app"></div>
+    <script type="module" src="/src/main.jsx"></script>
+</body>
+
+</html>

package/admin/jsconfig.json

@@ -0,0 +1,20 @@
+{
+	"compilerOptions": {
+		"target": "ES2020",
+		"module": "ESNext",
+		"moduleResolution": "bundler",
+		"noEmit": true,
+		"allowJs": true,
+		"checkJs": true,
+
+		/* Preact Config */
+		"jsx": "react-jsx",
+		"jsxImportSource": "preact",
+		"skipLibCheck": true,
+		"paths": {
+			"react": ["./node_modules/preact/compat/"],
+			"react-dom": ["./node_modules/preact/compat/"]
+		}
+	},
+	"include": ["node_modules/vite/client.d.ts", "**/*"]
+}

package/admin/lib/postbase.js

@@ -0,0 +1,222 @@
+// Minimal client SDK for the generic CRUD API.
+// Usage example:
+//   import { getDB } from './postbase.js';
+//   const db = getDB({ baseUrl: 'https://api.example.com/api' });
+//   const posts = db.collection('posts');
+//   await posts.addDoc({ title: 'hi' });
+//   const doc = await posts.doc('123').get();
+
+function toJsonOrThrow(res) {
+    if (!res.ok) {
+        return res.json().then(j => { throw j; });
+    }
+    return res.json();
+}
+
+export function getDB({
+    baseUrl = '/api',
+    defaultHeaders = {},
+    getAuthToken = null, // 👈 optional async token resolver
+} = {}) {
+    return new Database(baseUrl.replace(/\/$/, ''), defaultHeaders, getAuthToken);
+}
+
+class Database {
+    constructor(baseUrl, defaultHeaders, getAuthToken) {
+        this.baseUrl = baseUrl;
+        this.defaultHeaders = defaultHeaders;
+        this.getAuthToken = getAuthToken;
+    }
+
+    collection(name) {
+        return new CollectionReference(this, name);
+    }
+
+    async getHeaders() {
+        const headers = { ...this.defaultHeaders };
+        if (typeof this.getAuthToken === 'function') {
+            try {
+                const token = await this.getAuthToken();
+                if (token) headers['Authorization'] = `Bearer ${token}`;
+            } catch (err) {
+                console.warn('getAuthToken failed', err);
+            }
+        }
+        return headers;
+    }
+}
+
+class CollectionReference {
+    constructor(db, name, parentPath = null) {
+        this.db = db;
+        this.name = name;
+        this.parentPath = parentPath; // e.g., "users/u1"
+    }
+
+    /** Build full collection path */
+    get fullPath() {
+        return this.parentPath ? `${this.parentPath}/${this.name}` : this.name;
+    }
+
+    /** Return a DocumentReference inside this collection */
+    doc(id) {
+        return new DocumentReference(this.db, this.name, id, this.parentPath);
+    }
+
+    /** Allow chaining subcollections under this collection — for convenience */
+    collection(subName) {
+        // Enables chaining like: db.collection('orgs').collection('users')
+        // Useful for root-level logical grouping (not subcollections of docs)
+        return new CollectionReference(this.db, subName, this.fullPath);
+    }
+
+    // POST /:collection
+    async addDoc(data) {
+        const url = `${this.db.baseUrl}/${encodeURIComponent(this.fullPath)}`;
+        const headers = await this.db.getHeaders();
+        const res = await fetch(url, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json', ...headers },
+            body: JSON.stringify(data)
+        });
+        const json = await toJsonOrThrow(res);
+        return json.data;
+    }
+
+    // POST /:collection/query
+    async getDocs(query = {}) {
+        const url = `${this.db.baseUrl}/${encodeURIComponent(this.fullPath)}/query`;
+        const headers = await this.db.getHeaders();
+        const res = await fetch(url, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json', ...headers },
+            body: JSON.stringify(query)
+        });
+        const json = await toJsonOrThrow(res);
+        return json.data || [];
+    }
+
+    where(field, op, value) {
+        return new QueryBuilder(this.fullPath).where(field, op, value);
+    }
+}
+
+class DocumentReference {
+    constructor(db, collectionName, id, parentPath = null) {
+        this.db = db;
+        this.collectionName = collectionName;
+        this.id = id;
+        this.parentPath = parentPath;
+    }
+
+    /** Full document path, e.g. "users/u1/posts/p2" */
+    get fullPath() {
+        const base = this.parentPath ? `${this.parentPath}/${this.collectionName}` : this.collectionName;
+        return `${base}/${this.id}`;
+    }
+
+    /** Allow chaining subcollections under this document */
+    collection(subName) {
+        return new CollectionReference(this.db, subName, this.fullPath);
+    }
+
+    async get() {
+        const url = `${this.db.baseUrl}/${encodeURIComponent(this.fullPath)}`;
+        const headers = await this.db.getHeaders();
+        const res = await fetch(url, { headers });
+        const json = await toJsonOrThrow(res);
+        return json.data;
+    }
+
+    async set(data) {
+        const url = `${this.db.baseUrl}/${encodeURIComponent(this.fullPath)}`;
+        const headers = await this.db.getHeaders();
+        const res = await fetch(url, {
+            method: 'PUT',
+            headers: { 'content-type': 'application/json', ...headers },
+            body: JSON.stringify(data),
+        });
+        const json = await toJsonOrThrow(res);
+        return json.data;
+    }
+
+    async update(data) {
+        const url = `${this.db.baseUrl}/${encodeURIComponent(this.fullPath)}`;
+        const headers = await this.db.getHeaders();
+        const res = await fetch(url, {
+            method: 'PATCH',
+            headers: { 'content-type': 'application/json', ...headers },
+            body: JSON.stringify(data),
+        });
+        const json = await toJsonOrThrow(res);
+        return json.data;
+    }
+
+    async delete() {
+        const url = `${this.db.baseUrl}/${encodeURIComponent(this.fullPath)}`;
+        const headers = await this.db.getHeaders();
+        const res = await fetch(url, { method: 'DELETE', headers });
+        const json = await toJsonOrThrow(res);
+        return json.data;
+    }
+}
+
+/* Query builder helpers */
+export function query(collectionRef, ...clauses) {
+    // returns a structured query object for backend: { filters: [...], order: [...], limit, offset }
+    const q = new QueryBuilder(collectionRef);
+    for (const c of clauses) {
+        if (c instanceof QueryBuilder) q.mergeFrom(c);
+    }
+    return q;
+}
+
+class QueryBuilder {
+    constructor(collectionNameOrRef) {
+        this.collection = (collectionNameOrRef && collectionNameOrRef.name) || collectionNameOrRef;
+        this._filters = [];
+        this._order = [];
+        this._limit = undefined;
+        this._offset = undefined;
+    }
+    where(field, op, value) {
+        this._filters.push({ field, op, value });
+        return this;
+    }
+    orderBy(field, dir = 'asc') {
+        this._order.push({ field, dir });
+        return this;
+    }
+    limit(n) { this._limit = n; return this; }
+    offset(n) { this._offset = n; return this; }
+    build() {
+        const out = {};
+        if (this._filters.length) out.filters = this._filters;
+        if (this._order.length) out.order = this._order;
+        if (typeof this._limit !== 'undefined') out.limit = this._limit;
+        if (typeof this._offset !== 'undefined') out.offset = this._offset;
+        return out;
+    }
+    mergeFrom(other) {
+        this._filters.push(...(other._filters || []));
+        this._order.push(...(other._order || []));
+        if (other._limit) this._limit = other._limit;
+        if (other._offset) this._offset = other._offset;
+        return this;
+    }
+}
+
+/* Basic helpers similar to Firestore types */
+export const Timestamp = {
+    now: () => ({ _type: 'timestamp', iso: new Date().toISOString() }),
+    fromDate: (d) => ({ _type: 'timestamp', iso: d.toISOString() })
+};
+
+export const FieldValue = {
+    increment: (by = 1) => ({ _op: 'increment', by }),
+    serverTimestamp: () => ({ _op: 'serverTimestamp' }),
+};
+
+export const FieldPath = (path) => ({ _fieldPath: path });
+
+export const documentId = (id) => ({ _documentId: id });