@techfinityedge/koolbase-react-native 1.6.1

package/README.md

@@ -0,0 +1,282 @@
+# koolbase-react-native
+
+[![npm](https://img.shields.io/npm/v/koolbase-react-native.svg)](https://www.npmjs.com/package/koolbase-react-native)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+
+React Native SDK for [Koolbase](https://koolbase.com) — Backend as a Service built for mobile developers.
+
+Auth, database, storage, realtime, functions, feature flags, remote config, version enforcement, code push, logic engine, analytics, and cloud messaging — one SDK, one `initialize()` call.
+
+---
+
+## Get started in 2 minutes
+
+**1. Create a free account at [app.koolbase.com](https://app.koolbase.com)**
+
+**2. Create a project and copy your public key from Environments**
+
+**3. Add the SDK:**
+```bash
+npm install koolbase-react-native
+# or
+yarn add koolbase-react-native
+```
+
+**4. Initialize at app startup:**
+```typescript
+import { Koolbase } from 'koolbase-react-native';
+
+await Koolbase.initialize({
+  publicKey: 'pk_live_xxxx',
+  baseUrl: 'https://api.koolbase.com',
+});
+```
+
+That's it. Every feature below is now available via `Koolbase.*`.
+
+---
+
+## Authentication
+```typescript
+// Register
+await Koolbase.auth.register({ email: 'user@example.com', password: 'password' });
+
+// Login
+const session = await Koolbase.auth.login({ email: 'user@example.com', password: 'password' });
+
+// Current user
+const me = Koolbase.auth.currentUser;
+
+// Logout
+await Koolbase.auth.logout();
+
+// Password reset
+await Koolbase.auth.forgotPassword('user@example.com');
+```
+
+---
+
+## Database
+```typescript
+// Insert
+await Koolbase.db.insert('posts', { title: 'Hello', published: true });
+
+// Query
+const { records } = await Koolbase.db.query('posts', {
+  filters: { published: true },
+  limit: 10,
+  orderBy: 'created_at',
+  orderDesc: true,
+});
+
+// Populate related records
+const { records } = await Koolbase.db.query('posts', {
+  populate: ['author_id:users'],
+});
+
+// Update / Delete
+await Koolbase.db.update('record-id', { title: 'Updated' });
+await Koolbase.db.delete('record-id');
+```
+
+### Offline-first
+```typescript
+const { records, isFromCache } = await Koolbase.db.query('posts', { limit: 20 });
+if (isFromCache) console.log('Served from local cache');
+
+await Koolbase.db.syncPendingWrites();
+```
+
+---
+
+## Storage
+```typescript
+const { url } = await Koolbase.storage.upload({
+  bucket: 'avatars',
+  path: `user-${userId}.jpg`,
+  file: { uri: imageUri, name: 'avatar.jpg', type: 'image/jpeg' },
+});
+
+const downloadUrl = await Koolbase.storage.getDownloadUrl('avatars', `user-${userId}.jpg`);
+await Koolbase.storage.delete('avatars', `user-${userId}.jpg`);
+```
+
+---
+
+## Realtime
+```typescript
+const unsubscribe = Koolbase.realtime.subscribe('messages', (event) => {
+  if (event.type === 'created') setMessages(prev => [event.record, ...prev]);
+});
+
+// Cleanup
+unsubscribe();
+```
+
+---
+
+## Feature Flags & Remote Config
+```typescript
+if (Koolbase.isEnabled('new_checkout')) { ... }
+
+const timeout = Koolbase.configNumber('timeout_seconds', 30);
+const apiUrl = Koolbase.configString('api_url', 'https://api.myapp.com');
+const dark = Koolbase.configBool('force_dark_mode', false);
+```
+
+---
+
+## Version Enforcement
+```typescript
+const result = Koolbase.checkVersion('1.2.3');
+if (result.status === 'force_update') {
+  // block and show update screen
+}
+```
+
+---
+
+## Code Push
+```typescript
+await Koolbase.initialize({
+  publicKey: 'pk_live_xxxx',
+  baseUrl: 'https://api.koolbase.com',
+  codePushChannel: 'stable',
+});
+
+// Bundle values override Remote Config + Feature Flags transparently
+const timeout = Koolbase.configNumber('api_timeout_ms', 3000);
+
+// Directive handlers
+Koolbase.codePush.onDirective('force_logout_all', (value) => {
+  if (value) Koolbase.auth.logout();
+});
+Koolbase.codePush.applyDirectives();
+```
+
+---
+
+## Logic Engine
+```typescript
+// Define flows in your bundle's flows.json
+// Execute from anywhere in your app
+const result = Koolbase.executeFlow('on_checkout_tap', { plan: user.plan });
+
+if (result.hasEvent) {
+  switch (result.eventName) {
+    case 'show_upgrade': navigation.navigate('Upgrade'); break;
+    case 'go_checkout': navigation.navigate('Checkout'); break;
+  }
+}
+```
+
+---
+
+## Analytics
+```typescript
+await Koolbase.initialize({
+  publicKey: 'pk_live_xxxx',
+  baseUrl: 'https://api.koolbase.com',
+  analyticsEnabled: true,
+  appVersion: '1.0.0',
+});
+
+// Custom events
+Koolbase.analytics.track('purchase', { value: 1200, currency: 'GHS' });
+
+// Screen views
+Koolbase.analytics.screenView('checkout');
+
+// User identity
+Koolbase.analytics.identify(user.id);
+Koolbase.analytics.setUserProperty('plan', 'pro');
+
+// On logout
+Koolbase.analytics.reset();
+```
+
+---
+
+## Cloud Messaging
+```typescript
+await Koolbase.initialize({
+  publicKey: 'pk_live_xxxx',
+  baseUrl: 'https://api.koolbase.com',
+  messagingEnabled: true,
+});
+
+// Register FCM token (after obtaining from @react-native-firebase/messaging)
+const fcmToken = await messaging().getToken();
+await Koolbase.messaging.registerToken({
+  token: fcmToken,
+  platform: 'android', // or 'ios'
+});
+
+// Send to a specific device
+await Koolbase.messaging.send({
+  to: deviceToken,
+  title: 'Your order is ready',
+  body: 'Pick up at counter 3',
+  data: { order_id: '123' },
+});
+```
+
+---
+
+## Logic Engine v2
+
+```typescript
+const result = Koolbase.executeFlow('on_checkout_tap', {
+  plan: user.plan,
+  usage: user.usage,
+});
+
+if (result.hasEvent) {
+  switch (result.eventName) {
+    case 'show_upgrade': navigation.navigate('Upgrade'); break;
+    case 'go_checkout': navigation.navigate('Checkout'); break;
+  }
+}
+```
+
+**v2 operators:** `eq`, `neq`, `gt`, `gte`, `lt`, `lte`, `contains`, `starts_with`, `ends_with`, `in_list`, `not_in_list`, `between`, `is_true`, `is_false`, `exists`, `not_exists`, `and`, `or`
+
+Full docs at [docs.koolbase.com/sdk/logic-engine](https://docs.koolbase.com/sdk/logic-engine).
+
+---
+
+## Sign in with Apple
+
+```typescript
+import { KoolbaseAppleAuth } from 'koolbase-react-native';
+import { appleAuth } from '@invertase/react-native-apple-authentication';
+
+const session = await KoolbaseAppleAuth.signIn(async () => {
+  return await appleAuth.performRequest({
+    requestedOperation: appleAuth.Operation.LOGIN,
+    requestedScopes: [appleAuth.Scope.EMAIL, appleAuth.Scope.FULL_NAME],
+  });
+});
+```
+
+Install `@invertase/react-native-apple-authentication` as a peer dependency. Full setup guide at [docs.koolbase.com/auth/oauth](https://docs.koolbase.com/auth/oauth).
+
+---
+
+## Documentation
+
+Full documentation at [docs.koolbase.com](https://docs.koolbase.com)
+
+## Dashboard
+
+Manage your projects at [app.koolbase.com](https://app.koolbase.com)
+
+## Support
+
+- [GitHub Issues](https://github.com/kennedyowusu/koolbase-react-native/issues)
+- [docs.koolbase.com](https://docs.koolbase.com)
+- Email: hello@koolbase.com
+
+## License
+
+MIT

package/dist/analytics.d.ts

@@ -0,0 +1,26 @@
+import { KoolbaseConfig } from './types';
+export declare class KoolbaseAnalytics {
+    private config;
+    private queue;
+    private deviceId;
+    private userId?;
+    private environmentId?;
+    private userProperties;
+    private sessionId;
+    private appVersion;
+    private flushTimer?;
+    private initialized;
+    constructor(config: KoolbaseConfig);
+    init(appVersion?: string): Promise<void>;
+    track(eventName: string, properties?: Record<string, unknown>): void;
+    screenView(screenName: string, properties?: Record<string, unknown>): void;
+    identify(userId: string): void;
+    setUserProperty(key: string, value: unknown): void;
+    setUserProperties(properties: Record<string, unknown>): void;
+    setEnvironment(environmentId: string): void;
+    reset(): void;
+    flush(): Promise<void>;
+    dispose(): Promise<void>;
+    private getOrCreateDeviceId;
+    private generateUUID;
+}

package/dist/analytics.js

@@ -0,0 +1,138 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.KoolbaseAnalytics = void 0;
+const async_storage_1 = __importDefault(require("@react-native-async-storage/async-storage"));
+const react_native_1 = require("react-native");
+// ─── KoolbaseAnalytics ───────────────────────────────────────────────────────
+const SDK_VERSION = '1.3.0';
+const DEVICE_ID_KEY = 'koolbase:device_id';
+const FLUSH_INTERVAL_MS = 30000;
+const MAX_BATCH_SIZE = 20;
+class KoolbaseAnalytics {
+    constructor(config) {
+        this.queue = [];
+        this.deviceId = '';
+        this.userProperties = {};
+        this.sessionId = '';
+        this.appVersion = '1.0.0';
+        this.initialized = false;
+        this.config = config;
+    }
+    // ─── Init ─────────────────────────────────────────────────────────────────
+    async init(appVersion) {
+        if (this.initialized)
+            return;
+        this.deviceId = await this.getOrCreateDeviceId();
+        this.sessionId = `${this.deviceId}-${Date.now()}`;
+        this.appVersion = appVersion ?? '1.0.0';
+        // Auto flush on app background
+        react_native_1.AppState.addEventListener('change', (state) => {
+            if (state === 'background' || state === 'inactive') {
+                this.flush();
+            }
+        });
+        // Periodic flush
+        this.flushTimer = setInterval(() => this.flush(), FLUSH_INTERVAL_MS);
+        // Auto track app_open
+        this.track('app_open');
+        this.initialized = true;
+    }
+    // ─── Public API ───────────────────────────────────────────────────────────
+    track(eventName, properties) {
+        const event = {
+            device_id: this.deviceId,
+            user_id: this.userId,
+            environment_id: this.environmentId,
+            event_name: eventName,
+            properties: properties ?? {},
+            user_properties: { ...this.userProperties },
+            platform: react_native_1.Platform.OS,
+            app_version: this.appVersion,
+            sdk_version: SDK_VERSION,
+            session_id: this.sessionId,
+            occurred_at: new Date().toISOString(),
+        };
+        this.queue.push(event);
+        if (this.queue.length >= MAX_BATCH_SIZE) {
+            this.flush();
+        }
+    }
+    screenView(screenName, properties) {
+        this.track('screen_view', {
+            screen_name: screenName,
+            ...properties,
+        });
+    }
+    identify(userId) {
+        this.userId = userId;
+    }
+    setUserProperty(key, value) {
+        this.userProperties[key] = value;
+    }
+    setUserProperties(properties) {
+        Object.assign(this.userProperties, properties);
+    }
+    setEnvironment(environmentId) {
+        this.environmentId = environmentId;
+    }
+    reset() {
+        this.userId = undefined;
+        this.userProperties = {};
+    }
+    // ─── Flush ────────────────────────────────────────────────────────────────
+    async flush() {
+        if (this.queue.length === 0)
+            return;
+        const batch = [...this.queue];
+        this.queue = [];
+        try {
+            const response = await fetch(`${this.config.baseUrl}/v1/analytics/events`, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    'x-api-key': this.config.publicKey,
+                },
+                body: JSON.stringify({ events: batch }),
+            });
+            if (!response.ok) {
+                // Re-queue on failure
+                this.queue.unshift(...batch.slice(0, MAX_BATCH_SIZE - this.queue.length));
+            }
+        }
+        catch {
+            // Re-queue on network error
+            this.queue.unshift(...batch.slice(0, MAX_BATCH_SIZE - this.queue.length));
+        }
+    }
+    async dispose() {
+        if (this.flushTimer)
+            clearInterval(this.flushTimer);
+        this.track('session_end');
+        await this.flush();
+    }
+    // ─── Device ID ────────────────────────────────────────────────────────────
+    async getOrCreateDeviceId() {
+        try {
+            const existing = await async_storage_1.default.getItem(DEVICE_ID_KEY);
+            if (existing)
+                return existing;
+            const newId = this.generateUUID();
+            await async_storage_1.default.setItem(DEVICE_ID_KEY, newId);
+            return newId;
+        }
+        catch {
+            return this.generateUUID();
+        }
+    }
+    generateUUID() {
+        return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, (c) => {
+            const r = (Math.random() * 16) | 0;
+            const v = c === 'x' ? r : (r & 0x3) | 0x8;
+            return v.toString(16);
+        });
+    }
+}
+exports.KoolbaseAnalytics = KoolbaseAnalytics;

package/dist/apple-auth.d.ts

@@ -0,0 +1,22 @@
+/**
+ * KoolbaseAppleAuth — Sign in with Apple for React Native
+ *
+ * Requires @invertase/react-native-apple-authentication
+ * Install: npm install @invertase/react-native-apple-authentication
+ *
+ * Usage:
+ * ```typescript
+ * import { KoolbaseAppleAuth } from 'koolbase-react-native';
+ * const session = await KoolbaseAppleAuth.signIn();
+ * ```
+ */
+export declare class KoolbaseAppleAuth {
+    static signIn(getAppleCredential: () => Promise<{
+        identityToken: string | null;
+        email: string | null;
+        fullName?: {
+            givenName?: string | null;
+            familyName?: string | null;
+        } | null;
+    }>): Promise<Record<string, unknown> | null>;
+}

package/dist/apple-auth.js

@@ -0,0 +1,74 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.KoolbaseAppleAuth = void 0;
+/**
+ * KoolbaseAppleAuth — Sign in with Apple for React Native
+ *
+ * Requires @invertase/react-native-apple-authentication
+ * Install: npm install @invertase/react-native-apple-authentication
+ *
+ * Usage:
+ * ```typescript
+ * import { KoolbaseAppleAuth } from 'koolbase-react-native';
+ * const session = await KoolbaseAppleAuth.signIn();
+ * ```
+ */
+class KoolbaseAppleAuth {
+    static async signIn(getAppleCredential) {
+        try {
+            const { Koolbase } = await Promise.resolve().then(() => __importStar(require('./index')));
+            const credential = await getAppleCredential();
+            if (!credential.identityToken) {
+                console.warn('[KoolbaseAppleAuth] No identity token returned');
+                return null;
+            }
+            const name = [credential.fullName?.givenName, credential.fullName?.familyName]
+                .filter(Boolean)
+                .join(' ');
+            return await Koolbase.auth.oauthLogin({
+                provider: 'apple',
+                token: credential.identityToken,
+                email: credential.email ?? '',
+                name,
+            });
+        }
+        catch (error) {
+            console.error('[KoolbaseAppleAuth] Sign in failed:', error);
+            return null;
+        }
+    }
+}
+exports.KoolbaseAppleAuth = KoolbaseAppleAuth;

package/dist/auth.d.ts

@@ -0,0 +1,24 @@
+import { KoolbaseConfig, KoolbaseSession, KoolbaseUser, LoginParams, RegisterParams } from './types';
+export declare class KoolbaseAuth {
+    private config;
+    private session;
+    constructor(config: KoolbaseConfig);
+    private get headers();
+    private get authHeaders();
+    private request;
+    register(params: RegisterParams): Promise<KoolbaseUser>;
+    login(params: LoginParams): Promise<KoolbaseSession>;
+    logout(): Promise<void>;
+    forgotPassword(email: string): Promise<void>;
+    resetPassword(token: string, password: string): Promise<void>;
+    get currentUser(): KoolbaseUser | null;
+    get accessToken(): string | null;
+    setSession(session: KoolbaseSession | null): void;
+    oauthLogin({ provider, token, email, name, avatarUrl, }: {
+        provider: string;
+        token: string;
+        email?: string;
+        name?: string;
+        avatarUrl?: string;
+    }): Promise<Record<string, unknown> | null>;
+}

package/dist/auth.js

@@ -0,0 +1,85 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.KoolbaseAuth = void 0;
+class KoolbaseAuth {
+    constructor(config) {
+        this.session = null;
+        this.config = config;
+    }
+    get headers() {
+        return { 'Content-Type': 'application/json' };
+    }
+    get authHeaders() {
+        return {
+            'Content-Type': 'application/json',
+            ...(this.session
+                ? { Authorization: `Bearer ${this.session.accessToken}` }
+                : {}),
+        };
+    }
+    async request(method, path, body, auth = false) {
+        const res = await fetch(`${this.config.baseUrl}${path}`, {
+            method,
+            headers: auth ? this.authHeaders : this.headers,
+            body: body ? JSON.stringify(body) : undefined,
+        });
+        const data = await res.json();
+        if (!res.ok) {
+            throw new Error(data.error ?? `Request failed: ${res.status}`);
+        }
+        return data;
+    }
+    async register(params) {
+        const data = await this.request('POST', '/v1/sdk/auth/register', params);
+        return data.user;
+    }
+    async login(params) {
+        const data = await this.request('POST', '/v1/sdk/auth/login', params);
+        this.session = data;
+        return data;
+    }
+    async logout() {
+        if (!this.session)
+            return;
+        try {
+            await this.request('POST', '/v1/sdk/auth/logout', {}, true);
+        }
+        finally {
+            this.session = null;
+        }
+    }
+    async forgotPassword(email) {
+        await this.request('POST', '/v1/sdk/auth/forgot-password', { email });
+    }
+    async resetPassword(token, password) {
+        await this.request('POST', '/v1/sdk/auth/reset-password', {
+            token,
+            password,
+        });
+    }
+    get currentUser() {
+        return this.session?.user ?? null;
+    }
+    get accessToken() {
+        return this.session?.accessToken ?? null;
+    }
+    setSession(session) {
+        this.session = session;
+    }
+    async oauthLogin({ provider, token, email = '', name = '', avatarUrl = '', }) {
+        try {
+            const response = await fetch(`${this.config.baseUrl}/v1/auth/oauth`, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({ provider, token, email, name, avatar_url: avatarUrl }),
+            });
+            if (response.ok)
+                return response.json();
+            return null;
+        }
+        catch {
+            return null;
+        }
+    }
+}
+exports.KoolbaseAuth = KoolbaseAuth;

package/dist/cache-store.d.ts

@@ -0,0 +1,11 @@
+import { KoolbaseRecord, PendingWrite, QueryResult } from './types';
+export declare function hashQuery(collection: string, options: Record<string, unknown>): string;
+export declare function getCached(userId: string, collection: string, queryHash: string): Promise<QueryResult | null>;
+export declare function setCached(userId: string, collection: string, queryHash: string, result: QueryResult): Promise<void>;
+export declare function invalidateCache(userId: string, collection: string): Promise<void>;
+export declare function clearUserCache(userId: string): Promise<void>;
+export declare function getWriteQueue(userId: string): Promise<PendingWrite[]>;
+export declare function addToWriteQueue(userId: string, write: Omit<PendingWrite, 'retries' | 'createdAt'>): Promise<void>;
+export declare function removeFromWriteQueue(userId: string, writeId: string): Promise<void>;
+export declare function incrementWriteRetry(userId: string, writeId: string): Promise<void>;
+export declare function optimisticallyInsert(userId: string, collection: string, record: KoolbaseRecord): Promise<void>;