flit-baas 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Flit Technologies
+
+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,177 @@
+# flit-baas
+
+Official TypeScript & JavaScript Client SDK for **Flit BaaS** (Backend-as-a-Service) and **Mobile Money** payments across Africa.
+
+[![npm version](https://img.shields.io/npm/v/flit-baas.svg)](https://www.npmjs.com/package/flit-baas)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+
+---
+
+## Features
+
+- ⚡ **Zero-Config Database**: Instant document store powered by ACID PostgreSQL.
+- 📱 **Native Mobile Money**: Orange Money, MTN MoMo, Wave, Airtel Money, Moov, M-Pesa.
+- 🔒 **Zero-Leak Security**: Authenticate with public Anon Keys or private Service Role keys.
+- 🍪 **HttpOnly Encrypted Cookies**: AES-256-GCM authenticated session encryption (immunized against XSS).
+- 📦 **Universal Runtime**: Works in Browser (React, Vue, Svelte), Node.js, Next.js, and Edge runtimes.
+- 🚀 **Zero Dependencies**: Lightweight (< 22 KB), built on modern standard `fetch`.
+
+---
+
+## Installation
+
+```bash
+npm install flit-baas
+# or
+pnpm add flit-baas
+# or
+yarn add flit-baas
+```
+
+---
+
+## Quickstart
+
+### 1. Initialize the client
+
+```typescript
+import { createClient } from 'flit-baas';
+
+export const flit = createClient({
+  appId: process.env.NEXT_PUBLIC_FLIT_APP_ID!,
+  apiKey: process.env.NEXT_PUBLIC_FLIT_API_KEY!,
+  // endpoint: 'https://api.flit.site' (default)
+});
+```
+
+### 2. Database Operations (Collections)
+
+```typescript
+interface Product {
+  id: string;
+  name: string;
+  price: number;
+  category: string;
+  stock: number;
+}
+
+const products = flit.collection<Product>('products');
+
+// Query documents
+const items = await products.find({ category: 'shoes' }, { limit: 20, orderBy: 'price', order: 'desc' });
+
+// Get a single document by ID
+const shoe = await products.findById('rec_abc123');
+
+// Insert a new document
+const newItem = await products.insert({
+  name: 'Sneakers Pro',
+  price: 35000,
+  category: 'shoes',
+  stock: 10,
+});
+
+// Update a document
+await products.update(newItem.id, {
+  stock: 9,
+});
+
+// Delete a document
+await products.delete(newItem.id);
+```
+
+### 3. Mobile Money Payments (STK Push)
+
+Trigger instant Mobile Money payment prompts directly on customer smartphones in Central and West Africa:
+
+```typescript
+// Initiate STK Push payment
+const payment = await flit.payments.initiate({
+  operator: 'ORANGE', // 'ORANGE' | 'MTN' | 'WAVE' | 'AIRTEL' | 'MOOV' | 'MPESA'
+  phone: '+237690000000',
+  amount: 35000,
+  currency: 'XAF', // 'XAF' | 'XOF' | 'KES' | 'GHS' | 'USD'
+  title: 'Commande #1042',
+  customerName: 'Jean Dupont',
+  metadata: { orderId: 'ord_1042' },
+});
+
+console.log('Transaction started:', payment.transactionId);
+
+// Option A: Check status on demand
+const status = await flit.payments.getStatus(payment.transactionId);
+
+// Option B: Poll until user enters PIN and payment completes
+const finalResult = await flit.payments.waitForStatus(payment.transactionId, {
+  timeoutMs: 60000, // wait up to 1 minute
+  intervalMs: 3000,  // check every 3 seconds
+});
+
+if (finalResult.status === 'SUCCESS') {
+  console.log('Payment completed successfully!');
+}
+```
+
+### 4. User Authentication
+
+```typescript
+// Register a new customer
+const { user, session } = await flit.auth.signUp({
+  email: 'client@example.com',
+  password: 'SecurePassword123!',
+  name: 'Moussa Diop',
+  phone: '+221770000000',
+});
+
+// Sign in
+await flit.auth.signInWithPassword({
+  email: 'client@example.com',
+  password: 'SecurePassword123!',
+});
+
+// Get current session
+const currentUser = flit.auth.getUser();
+```
+
+### 5. Secure Session Management with Encrypted HttpOnly Cookies
+
+To protect against XSS (Cross-Site Scripting) and CSRF attacks, Flit SDK provides native server-side helpers for **AES-256-GCM encrypted `HttpOnly` cookies**:
+
+```typescript
+// In a Next.js 15 Route Handler, Server Action, or Node.js server:
+
+// 1. Create an encrypted HttpOnly Set-Cookie header upon login
+const setCookieHeader = await flit.auth.createSessionCookie(session);
+// Response header: flit_session=<aes-256-gcm-cipher>; Path=/; HttpOnly; Secure; SameSite=Lax
+
+// 2. Decrypt and verify session on incoming requests
+const sessionPayload = await flit.auth.verifySessionCookie(req.headers.get('cookie'));
+if (sessionPayload) {
+  console.log('Authenticated user:', sessionPayload.userId);
+}
+
+// 3. Destroy cookie upon logout
+const clearHeader = flit.auth.clearSessionCookie();
+```
+
+In browser environments, the client automatically configures `credentials: 'include'` on all requests, so `HttpOnly` cookies are forwarded transparently without ever exposing tokens to `document.cookie` or `localStorage`.
+
+---
+
+## Deployment & VPS Hosting
+
+When exporting your application from Flit to your personal VPS or GitHub:
+
+1. Add your credentials to `.env`:
+   ```env
+   NEXT_PUBLIC_FLIT_APP_ID="your-application-uuid"
+   NEXT_PUBLIC_FLIT_API_KEY="flit_pk_live_your_public_key"
+   ```
+2. Run your project natively with `npm run dev` or `docker compose up -d`.
+3. Your data and payment processing remain active without needing to configure or maintain your own PostgreSQL server.
+
+---
+
+## License
+
+MIT © [Flit Platform](https://flit.site)