gramobase 1.0.0

package/CODE_OF_CONDUCT.md

@@ -0,0 +1,132 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in the
+**gramobase** community a harassment-free experience for everyone, regardless of
+age, body size, visible or invisible disability, ethnicity, sex characteristics,
+gender identity and expression, level of experience, education, socio-economic
+status, nationality, personal appearance, race, caste, color, religion, or
+sexual identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+---
+
+## Our Standards
+
+**Examples of behavior that contributes to a positive environment:**
+
+- Using welcoming and inclusive language
+- Being respectful of differing viewpoints and experiences
+- Gracefully accepting constructive criticism
+- Focusing on what is best for the community
+- Showing empathy towards other community members
+- Giving credit where credit is due
+
+**Examples of unacceptable behavior:**
+
+- The use of sexualized language or imagery, and sexual attention or advances of any kind
+- Trolling, insulting or derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information, such as a physical or email address, without explicit permission
+- Deliberate intimidation, stalking, or following
+- Other conduct which could reasonably be considered inappropriate in a professional setting
+
+---
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+---
+
+## Scope
+
+This Code of Conduct applies within all community spaces — including the GitHub
+repository, issue tracker, pull requests, discussions, and any other official
+communication channels — and also applies when an individual is officially
+representing the community in public spaces.
+
+---
+
+## Reporting
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported by opening a **private** GitHub issue or contacting the maintainers
+directly. All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+---
+
+## Enforcement Guidelines
+
+Community leaders will follow these guidelines in determining the consequences
+for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Impact:** Use of inappropriate language or other behavior deemed unprofessional.
+
+**Consequence:** A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Impact:** A violation through a single incident or series of actions.
+
+**Consequence:** A warning with consequences for continued behavior. No
+interaction with the people involved — including unsolicited interaction with
+those enforcing the Code of Conduct — for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or permanent
+ban.
+
+### 3. Temporary Ban
+
+**Impact:** A serious violation of community standards, including sustained
+inappropriate behavior.
+
+**Consequence:** A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved — including unsolicited interaction
+with those enforcing the Code of Conduct — is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Impact:** Demonstrating a pattern of violation of community standards,
+including sustained inappropriate behavior, harassment of an individual, or
+aggression toward or disparagement of classes of individuals.
+
+**Consequence:** A permanent ban from any sort of public interaction within the
+community.
+
+---
+
+## Attribution
+
+This Code of Conduct is adapted from the
+[Contributor Covenant](https://www.contributor-covenant.org), version 2.1,
+available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html](https://www.contributor-covenant.org/version/2/1/code_of_conduct.html).
+
+Community Impact Guidelines were inspired by
+[Mozilla's code of conduct enforcement ladder](https://github.com/mozilla/diversity).
+
+For answers to common questions about this code of conduct, see the FAQ at
+[https://www.contributor-covenant.org/faq](https://www.contributor-covenant.org/faq).
+Translations are available at
+[https://www.contributor-covenant.org/translations](https://www.contributor-covenant.org/translations).

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 gramobase contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,314 @@
+# gramobase
+
+[![Build Status](https://img.shields.io/github/actions/workflow/status/besaoct/gramobase/build.yml?branch=main&style=flat-square)](https://github.com/besaoct/gramobase/actions)
+[![NPM Version](https://img.shields.io/npm/v/gramobase?color=blue&style=flat-square)](https://www.npmjs.com/package/gramobase)
+[![License](https://img.shields.io/github/license/besaoct/gramobase?style=flat-square)](https://github.com/besaoct/gramobase/blob/main/LICENSE)
+[![Tests Status](https://img.shields.io/badge/tests-33%20passed-brightgreen?style=flat-square)](https://github.com/besaoct/gramobase/actions)
+[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square)](https://makeapullrequest.com)
+
+**Telegram as a free, infinite, production-grade backend database.**
+
+Every Telegram channel is a collection. Every message is a document. Zero infrastructure needed — all you need is a free Telegram account.
+
+```ts
+import { createClient } from 'gramobase';
+import { z } from 'zod';
+
+const db = await createClient({
+  botToken: process.env.BOT_TOKEN!,
+  channelId: process.env.CHANNEL_ID!,
+}).connect();
+
+const users = db.collection('users', {
+  schema: z.object({ name: z.string(), email: z.string().email() }),
+});
+
+await users.insertOne({ name: 'Aarav', email: 'aarav@example.com' });
+const user = await users.findOne({ name: { $eq: 'Aarav' } });
+```
+
+---
+
+## Why gramobase?
+
+| Feature | gramobase | Firebase free | Supabase free |
+|---|---|---|---|
+| Storage | **Unlimited** | 1GB | 500MB |
+| Reads/writes | 30/s per bot, scales with bot count | 50K/day | 500MB bandwidth |
+| Auth | ✓ built-in | ✓ | ✓ |
+| File storage | **2GB per file** | 1GB total | 1GB total |
+| Realtime | ✓ SSE/webhook | ✓ | ✓ |
+| Infra needed | **None** | Firebase project | Supabase project |
+| Cost | **$0 forever** | Free tier | Free tier |
+
+---
+
+## Installation
+
+```bash
+npm install gramobase
+```
+
+### Running Tests
+
+To run the suite of 33 unit tests checking the ORM, caching, queue/worker pooling, and authentication:
+
+```bash
+npm run test
+```
+
+### Setup
+
+```bash
+npx gramobase init
+```
+
+This walks you through entering your bot token and channel ID, creates `.env` and `gramobase.config.ts`.
+
+**Prerequisites:**
+1. Create a bot via [@BotFather](https://t.me/BotFather) on Telegram — takes 30 seconds
+2. Create a private Telegram channel
+3. Add your bot as an **Administrator** with full permissions to the channel
+4. Get your channel ID (forward a message to @userinfobot)
+
+---
+
+## Core API
+
+### Collections (MongoDB-like ORM)
+
+```ts
+const PostSchema = z.object({
+  title: z.string(),
+  body: z.string(),
+  views: z.number().default(0),
+  tags: z.array(z.string()).default([]),
+  published: z.boolean().default(false),
+});
+
+const posts = db.collection('posts', {
+  schema: PostSchema,
+  indexes: ['title'],   // bloom filter index
+  encrypt: true,        // AES-256 field-level encryption
+});
+
+// Insert
+const post = await posts.insertOne({ title: 'Hello', body: 'World' });
+await posts.insertMany([...]);
+
+// Find
+const all = await posts.find();
+const published = await posts.find({ filter: { published: { $eq: true } } });
+const recent = await posts.find({
+  filter: { views: { $gte: 100 } },
+  sort: { views: -1 },
+  limit: 10,
+  skip: 0,
+});
+
+// Operators: $eq $ne $gt $gte $lt $lte $in $nin $regex $exists $and $or $not
+
+// Update
+await posts.findByIdAndUpdate(post._id, {
+  $set: { published: true },
+  $inc: { views: 1 },
+  $push: { tags: 'featured' },
+});
+await posts.updateMany({ published: { $eq: false } }, { $set: { published: true } });
+
+// Delete
+await posts.deleteById(post._id);
+await posts.deleteMany({ views: { $eq: 0 } });
+await posts.count({ published: { $eq: true } });
+```
+
+### Authentication
+
+```ts
+const auth = db.createAuth({
+  jwtSecret: process.env.JWT_SECRET!,
+  jwtExpiresIn: '7d',
+  bcryptRounds: 12,
+});
+
+const { user, session } = await auth.register('user@example.com', 'password', ['user']);
+const { session: s2 } = await auth.login('user@example.com', 'password');
+
+const verified = auth.verifyToken(s2.token);
+auth.requireRole(verified, 'admin');         // throws if not admin
+auth.requireAnyRole(verified, ['mod', 'admin']);
+
+await auth.changePassword(user._id, 'old', 'new');
+await auth.updateRoles(user._id, ['user', 'pro']);
+
+// Express middleware
+app.use('/api', auth.middleware());
+app.post('/admin', auth.middleware(), auth.requireRoleMiddleware('admin'), handler);
+```
+
+### File Storage
+
+```ts
+// Upload any file — images, PDFs, videos up to 2GB (via MTProto)
+const file = await db.uploadFile(buffer, {
+  fileName: 'profile.jpg',
+  mimeType: 'image/jpeg',
+  metadata: { userId: '123' },
+});
+
+console.log(file.fileId); // stable Telegram file reference
+console.log(file.url);    // CDN-served download URL
+```
+
+### Realtime
+
+```ts
+// Subscribe to collection events
+const unsub = db.realtime.onInsert('orders', (order) => {
+  console.log('New order:', order);
+});
+
+db.realtime.onUpdate('products', (id, changes, doc) => {
+  console.log('Updated:', id, changes);
+});
+
+db.realtime.onDelete('posts', (id) => {
+  console.log('Deleted:', id);
+});
+
+// Server-Sent Events for browser clients
+app.get('/stream', db.realtime.sseHandler('orders'));
+
+// Frontend:
+const es = new EventSource('/stream');
+es.onmessage = (e) => console.log(JSON.parse(e.data));
+```
+
+### Migrations
+
+```ts
+const migrations = [
+  {
+    version: 1,
+    name: 'add-slug-field',
+    async up(db) {
+      const posts = db.collection('posts', { schema: PostSchema });
+      const all = await posts.find();
+      for (const post of all) {
+        await posts.findByIdAndUpdate(post._id, {
+          $set: { slug: post.title.toLowerCase().replace(/ /g, '-') },
+        });
+      }
+    },
+    async down(db) {
+      await db.collection('posts', { schema: PostSchema })
+        .updateMany({}, { $unset: { slug: '' } });
+    },
+  },
+];
+
+await db.migrate(migrations);
+```
+
+### Anti-flood bot pool
+
+```ts
+// Pass multiple bot tokens — gramobase round-robins and backs off per token
+const db = await createClient({
+  botToken: [
+    process.env.BOT_TOKEN_1!,
+    process.env.BOT_TOKEN_2!,
+    process.env.BOT_TOKEN_3!,
+  ],
+  channelId: process.env.CHANNEL_ID!,
+}).connect();
+
+// 3 tokens × 30 req/s = effectively 90 writes/s sustained
+```
+
+---
+
+## Architecture
+
+```
+Developer API (ORM, Auth, Files, Realtime)
+         │
+    Hot Cache (LRU, 64MB+, O(1) reads)
+         │
+    State Manager (reactive, optimistic writes)
+         │
+   Write-Ahead Log (crash recovery, sequence IDs)
+         │
+ Registry (distributed lease, heartbeat, single writer)
+         │
+  Bot Worker Pool (round-robin, 429 backoff, retry)
+         │
+  Telegram Bot API ─────────────────────────────────┐
+         │                                          │
+  Private Channel              File Storage      Realtime
+  (messages = docs,        (sendDocument,       (webhook +
+   pinned = index)          file_id refs)       SSE bridge)
+```
+
+### Storage model
+
+- Each collection maps to a private Telegram channel (or shares one via namespaced message tags)
+- A **pinned index message** stores `{ id → msgId }` for O(1) lookups
+- The **Write-Ahead Log** channel stores operation logs for crash recovery
+- A **registry message** acts as a distributed write lock across processes
+
+### Limits
+
+| Limit | Value |
+|---|---|
+| Telegram rate limit | 30 req/s per bot token (scales with pool size) |
+| Message size | 4096 bytes per message (large docs auto-chunked) |
+| File size (Bot API) | 50MB send, 20MB receive |
+| File size (MTProto/TDLib) | 2GB |
+| Channel message history | Unlimited |
+| Cost | $0 |
+
+---
+
+## CLI
+
+```bash
+npx gramobase init                   # interactive setup wizard
+npx gramobase status                 # check bot + channel connectivity
+npx gramobase migrate                # run pending migrations
+npx gramobase migrate --rollback 1   # rollback last migration
+npx gramobase migrate --status       # show migration history
+npx gramobase generate post --fields "title:string,views:number"
+npx gramobase studio                 # open browser UI (v0.2)
+```
+
+---
+
+## Configuration
+
+```ts
+const db = createClient({
+  botToken: string | string[],  // single token or pool
+  channelId: string,            // main storage channel
+  walChannelId?: string,        // separate WAL channel (optional)
+  indexChannelId?: string,      // separate index channel (optional)
+  encryptionKey?: string,       // AES-256 key for encryption at rest
+  cacheMaxBytes?: number,       // default 64MB
+  cacheTtlMs?: number,          // default 60s
+  concurrency?: number,         // max concurrent requests per token, default 25
+  webhookUrl?: string,          // enables webhook mode for realtime
+  debug?: boolean,
+});
+```
+
+---
+
+## Disclaimer
+
+gramobase is designed for prototypes, hobby projects, and small-to-medium applications. It is not a replacement for PostgreSQL or MongoDB in high-traffic production systems. Data lives on Telegram's infrastructure — do not store sensitive PII without encryption.
+
+---
+
+## License
+
+MIT

package/dist/BotWorkerPool-9ndHQt2g.d.cts

@@ -0,0 +1,201 @@
+import { z } from 'zod';
+import TelegramBot from 'node-telegram-bot-api';
+import EventEmitter from 'eventemitter3';
+
+interface GramoBaseDocument {
+    _id: string;
+    _collection: string;
+    _msgId: number;
+    _createdAt: string;
+    _updatedAt: string;
+    [key: string]: unknown;
+}
+type WithId<T> = T & GramoBaseDocument;
+interface CollectionConfig<T extends z.ZodType> {
+    schema: T;
+    /** Channel override — uses the default if omitted */
+    channelId?: string | undefined;
+    /** Bloom-filter field list for fast-miss short-circuit */
+    indexes?: string[] | undefined;
+    /** Encrypt all documents in this collection with AES-256 */
+    encrypt?: boolean | undefined;
+    /** TTL seconds — documents are automatically expired after this many seconds */
+    ttl?: number | undefined;
+}
+type ElemOf<T> = T extends (infer U)[] ? U : T;
+type ComparisonOperator<T> = {
+    $eq?: T | ElemOf<T> | undefined;
+    $ne?: T | ElemOf<T> | undefined;
+    $gt?: T | ElemOf<T> | number | undefined;
+    $gte?: T | ElemOf<T> | number | undefined;
+    $lt?: T | ElemOf<T> | number | undefined;
+    $lte?: T | ElemOf<T> | number | undefined;
+    $in?: (T | ElemOf<T>)[] | undefined;
+    $nin?: (T | ElemOf<T>)[] | undefined;
+    $exists?: boolean | undefined;
+    $regex?: RegExp | string | undefined;
+};
+type Filter<T> = {
+    [K in keyof T]?: T[K] | ElemOf<T[K]> | ComparisonOperator<T[K]> | undefined;
+} | {
+    $and?: Filter<T>[] | undefined;
+    $or?: Filter<T>[] | undefined;
+    $not?: Filter<T> | undefined;
+};
+interface FindOptions<T> {
+    filter?: Filter<T> | undefined;
+    sort?: Partial<Record<keyof T | string, 1 | -1>> | undefined;
+    limit?: number | undefined;
+    skip?: number | undefined;
+    projection?: Partial<Record<keyof T | string, 1 | 0>> | undefined;
+    useCache?: boolean | undefined;
+}
+interface UpdateOperators<T> {
+    $set?: (Partial<T> & Record<string, unknown>) | undefined;
+    $unset?: Partial<Record<keyof T | string, '' | true>> | undefined;
+    $inc?: Partial<Record<keyof T | string, number>> | undefined;
+    $push?: Partial<Record<keyof T | string, unknown>> | undefined;
+}
+type WalOpType = 'INSERT' | 'UPDATE' | 'DELETE';
+interface WalEntry {
+    seq: number;
+    op: WalOpType;
+    collection: string;
+    id: string;
+    data?: unknown;
+    timestamp: string;
+    checksum: string;
+}
+interface Lease {
+    instanceId: string;
+    acquiredAt: number;
+    expiresAt: number;
+    heartbeatInterval: ReturnType<typeof setInterval> | null;
+}
+interface User {
+    _id: string;
+    email: string;
+    passwordHash: string;
+    roles: string[];
+    metadata?: Record<string, unknown> | undefined;
+    createdAt: string;
+    updatedAt: string;
+}
+interface Session {
+    userId: string;
+    roles: string[];
+    expiresAt: number;
+    token: string;
+}
+interface AuthConfig {
+    jwtSecret: string;
+    jwtExpiresIn?: string | undefined;
+    bcryptRounds?: number | undefined;
+    onSignIn?: ((user: User) => Promise<void>) | undefined;
+    onSignOut?: ((userId: string) => Promise<void>) | undefined;
+}
+interface UploadOptions {
+    fileName?: string | undefined;
+    mimeType?: string | undefined;
+    metadata?: Record<string, unknown> | undefined;
+}
+interface FileRecord {
+    _id: string;
+    fileId: string;
+    fileName: string;
+    mimeType: string;
+    sizeBytes: number;
+    url?: string | undefined;
+    uploadedAt: string;
+    metadata?: Record<string, unknown> | undefined;
+}
+type GramoBaseEvent = {
+    type: 'insert';
+    collection: string;
+    doc: unknown;
+} | {
+    type: 'update';
+    collection: string;
+    id: string;
+    changes: unknown;
+    doc: unknown;
+} | {
+    type: 'delete';
+    collection: string;
+    id: string;
+} | {
+    type: 'worker:rotate';
+    tokenIndex: number;
+} | {
+    type: 'wal:flush';
+    entries: number;
+};
+interface Migration {
+    version: number;
+    name: string;
+    up(db: unknown): Promise<void>;
+    down(db: unknown): Promise<void>;
+}
+interface GramoBaseConfig {
+    /** Bot token or array of tokens for pool rotation */
+    botToken: string | string[];
+    /** Primary storage channel ID */
+    channelId: string;
+    /** Optional separate channel for WAL entries */
+    walChannelId?: string | undefined;
+    /** Optional separate channel for collection indexes */
+    indexChannelId?: string | undefined;
+    /** AES-256 encryption key for data at rest */
+    encryptionKey?: string | undefined;
+    /** LRU cache byte limit (default: 64MB) */
+    cacheMaxBytes?: number | undefined;
+    /** LRU cache TTL in milliseconds (default: 60s) */
+    cacheTtlMs?: number | undefined;
+    /** Max concurrent requests per bot token (default: 25) */
+    concurrency?: number | undefined;
+    /** Webhook URL for realtime events (optional — falls back to polling) */
+    webhookUrl?: string | undefined;
+    /** Enable verbose debug logging */
+    debug?: boolean | undefined;
+}
+
+interface WorkerStats {
+    tokenIndex: number;
+    requestCount: number;
+    errorCount: number;
+    lastUsed: number;
+    rateLimitHits: number;
+}
+/**
+ * BotWorkerPool manages a round-robin pool of Telegram bot tokens.
+ * Each token gets its own PQueue limited to 25 concurrent requests
+ * (safe under Telegram's 30 req/s flood limit with headroom).
+ * On 429 responses, the worker is cooled down and the next token takes over.
+ */
+declare class BotWorkerPool extends EventEmitter {
+    private bots;
+    private queues;
+    private stats;
+    private currentIndex;
+    private debug;
+    constructor(tokens: string[], concurrency?: number, debug?: boolean);
+    /**
+     * Execute a Telegram API call through the pool with automatic retry
+     * and token rotation on rate limits.
+     */
+    execute<T>(fn: (bot: TelegramBot) => Promise<T>, priority?: number): Promise<T>;
+    /**
+     * Round-robin with recency bias — prefer the worker that was least recently used.
+     */
+    private pickWorker;
+    private isFloodError;
+    private isRetryableError;
+    private extractRetryAfter;
+    getBot(index?: number): TelegramBot;
+    getStats(): WorkerStats[];
+    getQueueSizes(): number[];
+    private sleep;
+    destroy(): Promise<void>;
+}
+
+export { type AuthConfig as A, BotWorkerPool as B, type CollectionConfig as C, type FileRecord as F, type GramoBaseEvent as G, type Lease as L, type Migration as M, type Session as S, type UploadOptions as U, type WorkerStats as W, type GramoBaseConfig as a, type ComparisonOperator as b, type Filter as c, type FindOptions as d, type GramoBaseDocument as e, type UpdateOperators as f, type User as g, type WalEntry as h, type WalOpType as i, type WithId as j };