@techfinityedge/koolbase-react-native 1.7.0 → 1.9.0

package/README.md

@@ -1,18 +1,6 @@
-# Koolbase React Native SDK
+# @techfinityedge/koolbase-react-native
 
-⚠️ ## This package has moved
-
-This package is deprecated.
-
-👉 Install the official version:
-
-```bash
-npm install @techfinityedge/koolbase-react-native
-```
-
----
-
-[![npm](https://img.shields.io/npm/v/koolbase-react-native.svg)](https://www.npmjs.com/package/koolbase-react-native)
+[![npm](https://img.shields.io/npm/v/@techfinityedge/koolbase-react-native.svg)](https://www.npmjs.com/package/@techfinityedge/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.
@@ -30,15 +18,15 @@ Auth, database, storage, realtime, functions, feature flags, remote config, vers
 3. Add the SDK:
 
 ```bash
-npm install koolbase-react-native
+npm install @techfinityedge/koolbase-react-native@^1.8.0
 # or
-yarn add koolbase-react-native
+yarn add @techfinityedge/koolbase-react-native@^1.8.0
 ```
 
 **4. Initialize at app startup:**
 
 ```typescript
-import { Koolbase } from 'koolbase-react-native';
+import { Koolbase } from '@techfinityedge/koolbase-react-native';
 
 await Koolbase.initialize({
   publicKey: 'pk_live_xxxx',
@@ -52,6 +40,8 @@ That's it. Every feature below is now available via `Koolbase.*`.
 
 ## Authentication
 
+Email + password, Google, Apple, and phone + OTP — out of the box.
+
 ```typescript
 // Register
 await Koolbase.auth.register({ email: 'user@example.com', password: 'password' });
@@ -69,6 +59,50 @@ await Koolbase.auth.logout();
 await Koolbase.auth.forgotPassword('user@example.com');
 ```
 
+### OAuth — Google & Apple
+
+```typescript
+// Google
+await Koolbase.auth.signInWithGoogle({ idToken: googleIdToken });
+```
+
+Apple uses the native authentication flow via `@invertase/react-native-apple-authentication` as a peer dependency:
+
+```typescript
+import { KoolbaseAppleAuth } from '@techfinityedge/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],
+  });
+});
+```
+
+Full setup guide at [docs.koolbase.com/auth/oauth](https://docs.koolbase.com/auth/oauth).
+
+### Phone + OTP
+
+```typescript
+// Send a one-time code
+await Koolbase.auth.sendOtp({ phoneE164: '+233200000000' });
+
+// Verify and sign in
+await Koolbase.auth.verifyOtp({
+  phoneE164: '+233200000000',
+  code: '123456',
+});
+
+// Or link a phone to an existing account
+await Koolbase.auth.linkPhone({
+  phoneE164: '+233200000000',
+  code: '123456',
+});
+```
+
+Configure your SMS provider (Twilio, Africa's Talking, or Hubtel) in the dashboard under Phone Auth.
+
 ---
 
 ## Database
@@ -86,7 +120,7 @@ const { records } = await Koolbase.db.query('posts', {
 });
 
 // Populate related records
-const { records } = await Koolbase.db.query('posts', {
+const { records: postsWithAuthor } = await Koolbase.db.query('posts', {
   populate: ['author_id:users'],
 });
 
@@ -134,10 +168,40 @@ unsubscribe();
 
 ---
 
+## Functions
+
+Invoke deployed serverless functions. When a user is signed in via `Koolbase.auth`, their access token is automatically forwarded — the function receives the caller's identity via `ctx.auth`. No token handling on the client side.
+
+```typescript
+// Invoke a deployed function
+const result = await Koolbase.functions.invoke('send-welcome-email', {
+  userId: '123',
+});
+
+if (result.success) console.log(result.data);
+```
+
+Inside the function (Deno runtime), read the caller:
+
+```typescript
+export async function handler(ctx) {
+  const userId = ctx.auth?.user_id;
+  if (!userId) {
+    return { error: { code: 'AUTH_REQUIRED' }, status: 401 };
+  }
+  // Authenticated logic here
+  return { ok: true };
+}
+```
+
+Token refresh is transparent — the SDK reads the current token fresh on every invoke. Full docs at [docs.koolbase.com/functions/authentication](https://docs.koolbase.com/functions/authentication).
+
+---
+
 ## Feature Flags & Remote Config
 
 ```typescript
-if (Koolbase.isEnabled('new_checkout')) { ... }
+if (Koolbase.isEnabled('new_checkout')) { /* ... */ }
 
 const timeout = Koolbase.configNumber('timeout_seconds', 30);
 const apiUrl = Koolbase.configString('api_url', 'https://api.myapp.com');
@@ -159,6 +223,8 @@ if (result.status === 'force_update') {
 
 ## Code Push
 
+Push config overrides, feature flag overrides, and directive-driven behaviour without a store release.
+
 ```typescript
 await Koolbase.initialize({
   publicKey: 'pk_live_xxxx',
@@ -180,10 +246,13 @@ Koolbase.codePush.applyDirectives();
 
 ## Logic Engine
 
+Define conditional app behavior as data in your Runtime Bundle — no code changes required.
+
 ```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 });
+const result = Koolbase.executeFlow('on_checkout_tap', {
+  plan: user.plan,
+  usage: user.usage,
+});
 
 if (result.hasEvent) {
   switch (result.eventName) {
@@ -193,10 +262,16 @@ if (result.hasEvent) {
 }
 ```
 
+**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).
+
 ---
 
 ## Analytics
 
+Track screen views, custom events, and user behaviour. View DAU, WAU, MAU, funnels, and retention in the Koolbase dashboard.
+
 ```typescript
 await Koolbase.initialize({
   publicKey: 'pk_live_xxxx',
@@ -248,43 +323,22 @@ await Koolbase.messaging.send({
 
 ---
 
-## 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).
+## What's included
+
+| Feature | Koolbase | Firebase | Supabase |
+| --- | --- | --- | --- |
+| TypeScript SDK | Yes | Yes | Yes |
+| Feature flags | Yes | — | — |
+| Remote config | Yes | Yes | — |
+| Version enforcement | Yes | — | — |
+| Offline-first database | Yes | Yes | — |
+| Code push | Yes | — | — |
+| Logic engine (flows OTA) | Yes | — | — |
+| Analytics | Yes | Yes | — |
+| Cloud Messaging | Yes | Yes | — |
+| Sign in with Apple | Yes | Yes | Yes |
+| Phone + OTP | Yes | Yes | Yes |
+| Authenticated functions (`ctx.auth`) | Yes | Yes | Yes |
 
 ---
 
@@ -300,7 +354,7 @@ Manage your projects at [app.koolbase.com](https://app.koolbase.com)
 
 - [GitHub Issues](https://github.com/kennedyowusu/koolbase-react-native/issues)
 - [docs.koolbase.com](https://docs.koolbase.com)
-- Email: hello@koolbase.com
+- Email: <hello@koolbase.com>
 
 ## License
 

package/dist/auth-errors.d.ts

@@ -1,7 +1,78 @@
+/**
+ * Base error type for all Koolbase auth errors. Catchable via
+ * `instanceof KoolbaseAuthError` to handle any auth-related failure
+ * generically; subclasses let you handle specific cases.
+ */
 export declare class KoolbaseAuthError extends Error {
     code?: string;
     constructor(message: string, code?: string);
 }
+export declare class InvalidCredentialsError extends KoolbaseAuthError {
+    constructor();
+}
+export declare class EmailAlreadyInUseError extends KoolbaseAuthError {
+    constructor();
+}
+export declare class UserDisabledError extends KoolbaseAuthError {
+    constructor();
+}
+export declare class WeakPasswordError extends KoolbaseAuthError {
+    constructor();
+}
+export declare class SessionExpiredError extends KoolbaseAuthError {
+    constructor();
+}
+/**
+ * Thrown when the access token references a session that has been revoked
+ * centrally — either by the user (sessions endpoint) or an administrator.
+ * Distinct from {@link SessionExpiredError} which indicates the access
+ * token TTL elapsed without a successful refresh.
+ *
+ * Forward-compatible: matches multiple server message patterns so it stays
+ * accurate as the server's revocation signaling evolves.
+ */
+export declare class TokenRevokedError extends KoolbaseAuthError {
+    constructor();
+}
+/**
+ * Thrown when the account is temporarily locked due to too many failed
+ * login attempts. The server uses progressive 5/10/20-attempt lockouts;
+ * if an unlock email was issued (level 2+), the user can clear the lock
+ * by passing that token to {@link KoolbaseAuth.unlock}.
+ *
+ * [lockedUntil] is currently null — the server returns a generic 429 but
+ * does not yet include the unlock timestamp in the response body. Field
+ * is forward-compatible for when the server adds it.
+ */
+export declare class AccountLockedError extends KoolbaseAuthError {
+    lockedUntil?: Date;
+    constructor(lockedUntil?: Date);
+}
+/**
+ * Thrown when the unlock token from a brute-force unlock email is
+ * invalid, expired, or already consumed. Unlock tokens are one-shot.
+ */
+export declare class UnlockTokenInvalidError extends KoolbaseAuthError {
+    constructor();
+}
+/**
+ * Thrown when the server rate-limits a non-phone authentication endpoint
+ * (HTTP 429 without the "account temporarily locked" marker). Phone OTP
+ * endpoints throw {@link OtpRateLimitError} instead — they hit a
+ * separate server-side rate-limiter.
+ */
+export declare class RateLimitError extends KoolbaseAuthError {
+    constructor(message?: string);
+}
+/**
+ * Generic network error. The SDK does NOT throw this directly — fetch
+ * failures (DNS, no connection, timeout) propagate as native TypeErrors.
+ * This class exists for consumer code that wants to construct or
+ * `instanceof`-check a typed network error from their own retry logic.
+ */
+export declare class NetworkError extends KoolbaseAuthError {
+    constructor();
+}
 export declare class InvalidPhoneNumberError extends KoolbaseAuthError {
     constructor();
 }

package/dist/auth-errors.js

@@ -1,6 +1,11 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SmsConfigMissingError = exports.PhoneAlreadyLinkedError = exports.OtpRateLimitError = exports.OtpMaxAttemptsError = exports.OtpInvalidError = exports.OtpExpiredError = exports.InvalidPhoneNumberError = exports.KoolbaseAuthError = void 0;
+exports.SmsConfigMissingError = exports.PhoneAlreadyLinkedError = exports.OtpRateLimitError = exports.OtpMaxAttemptsError = exports.OtpInvalidError = exports.OtpExpiredError = exports.InvalidPhoneNumberError = exports.NetworkError = exports.RateLimitError = exports.UnlockTokenInvalidError = exports.AccountLockedError = exports.TokenRevokedError = exports.SessionExpiredError = exports.WeakPasswordError = exports.UserDisabledError = exports.EmailAlreadyInUseError = exports.InvalidCredentialsError = exports.KoolbaseAuthError = void 0;
+/**
+ * Base error type for all Koolbase auth errors. Catchable via
+ * `instanceof KoolbaseAuthError` to handle any auth-related failure
+ * generically; subclasses let you handle specific cases.
+ */
 class KoolbaseAuthError extends Error {
     constructor(message, code) {
         super(message);
@@ -10,6 +15,127 @@ class KoolbaseAuthError extends Error {
     }
 }
 exports.KoolbaseAuthError = KoolbaseAuthError;
+// ─── Credentials / Registration ────────────────────────────────────────────
+class InvalidCredentialsError extends KoolbaseAuthError {
+    constructor() {
+        super('Invalid email or password', 'invalid_credentials');
+        this.name = 'InvalidCredentialsError';
+        Object.setPrototypeOf(this, InvalidCredentialsError.prototype);
+    }
+}
+exports.InvalidCredentialsError = InvalidCredentialsError;
+class EmailAlreadyInUseError extends KoolbaseAuthError {
+    constructor() {
+        super('Email is already in use', 'email_taken');
+        this.name = 'EmailAlreadyInUseError';
+        Object.setPrototypeOf(this, EmailAlreadyInUseError.prototype);
+    }
+}
+exports.EmailAlreadyInUseError = EmailAlreadyInUseError;
+class UserDisabledError extends KoolbaseAuthError {
+    constructor() {
+        super('This account has been disabled', 'user_disabled');
+        this.name = 'UserDisabledError';
+        Object.setPrototypeOf(this, UserDisabledError.prototype);
+    }
+}
+exports.UserDisabledError = UserDisabledError;
+class WeakPasswordError extends KoolbaseAuthError {
+    constructor() {
+        super('Password must be at least 8 characters', 'weak_password');
+        this.name = 'WeakPasswordError';
+        Object.setPrototypeOf(this, WeakPasswordError.prototype);
+    }
+}
+exports.WeakPasswordError = WeakPasswordError;
+// ─── Session lifecycle ─────────────────────────────────────────────────────
+class SessionExpiredError extends KoolbaseAuthError {
+    constructor() {
+        super('Session expired, please log in again', 'session_expired');
+        this.name = 'SessionExpiredError';
+        Object.setPrototypeOf(this, SessionExpiredError.prototype);
+    }
+}
+exports.SessionExpiredError = SessionExpiredError;
+/**
+ * Thrown when the access token references a session that has been revoked
+ * centrally — either by the user (sessions endpoint) or an administrator.
+ * Distinct from {@link SessionExpiredError} which indicates the access
+ * token TTL elapsed without a successful refresh.
+ *
+ * Forward-compatible: matches multiple server message patterns so it stays
+ * accurate as the server's revocation signaling evolves.
+ */
+class TokenRevokedError extends KoolbaseAuthError {
+    constructor() {
+        super('Session has been revoked, please log in again', 'token_revoked');
+        this.name = 'TokenRevokedError';
+        Object.setPrototypeOf(this, TokenRevokedError.prototype);
+    }
+}
+exports.TokenRevokedError = TokenRevokedError;
+// ─── Brute-force protection ────────────────────────────────────────────────
+/**
+ * Thrown when the account is temporarily locked due to too many failed
+ * login attempts. The server uses progressive 5/10/20-attempt lockouts;
+ * if an unlock email was issued (level 2+), the user can clear the lock
+ * by passing that token to {@link KoolbaseAuth.unlock}.
+ *
+ * [lockedUntil] is currently null — the server returns a generic 429 but
+ * does not yet include the unlock timestamp in the response body. Field
+ * is forward-compatible for when the server adds it.
+ */
+class AccountLockedError extends KoolbaseAuthError {
+    constructor(lockedUntil) {
+        super('Account temporarily locked due to too many failed attempts', 'account_locked');
+        this.lockedUntil = lockedUntil;
+        this.name = 'AccountLockedError';
+        Object.setPrototypeOf(this, AccountLockedError.prototype);
+    }
+}
+exports.AccountLockedError = AccountLockedError;
+/**
+ * Thrown when the unlock token from a brute-force unlock email is
+ * invalid, expired, or already consumed. Unlock tokens are one-shot.
+ */
+class UnlockTokenInvalidError extends KoolbaseAuthError {
+    constructor() {
+        super('Unlock link is invalid or has expired', 'unlock_token_invalid');
+        this.name = 'UnlockTokenInvalidError';
+        Object.setPrototypeOf(this, UnlockTokenInvalidError.prototype);
+    }
+}
+exports.UnlockTokenInvalidError = UnlockTokenInvalidError;
+/**
+ * Thrown when the server rate-limits a non-phone authentication endpoint
+ * (HTTP 429 without the "account temporarily locked" marker). Phone OTP
+ * endpoints throw {@link OtpRateLimitError} instead — they hit a
+ * separate server-side rate-limiter.
+ */
+class RateLimitError extends KoolbaseAuthError {
+    constructor(message) {
+        super(message ?? 'Too many requests, please wait before trying again', 'rate_limit');
+        this.name = 'RateLimitError';
+        Object.setPrototypeOf(this, RateLimitError.prototype);
+    }
+}
+exports.RateLimitError = RateLimitError;
+// ─── Network ───────────────────────────────────────────────────────────────
+/**
+ * Generic network error. The SDK does NOT throw this directly — fetch
+ * failures (DNS, no connection, timeout) propagate as native TypeErrors.
+ * This class exists for consumer code that wants to construct or
+ * `instanceof`-check a typed network error from their own retry logic.
+ */
+class NetworkError extends KoolbaseAuthError {
+    constructor() {
+        super('Network error, please check your connection', 'network_error');
+        this.name = 'NetworkError';
+        Object.setPrototypeOf(this, NetworkError.prototype);
+    }
+}
+exports.NetworkError = NetworkError;
+// ─── Phone OTP (unchanged from earlier releases) ───────────────────────────
 class InvalidPhoneNumberError extends KoolbaseAuthError {
     constructor() {
         super('Phone number must be in E.164 format (e.g. +233XXXXXXXXX)', 'invalid_phone');

package/dist/auth-storage.d.ts

@@ -0,0 +1,26 @@
+import { KoolbaseAuthStorage, KoolbaseSession } from './types';
+/**
+ * Probe whether react-native-keychain is installed without throwing.
+ * Used by KoolbaseAuth to decide whether to instantiate a default
+ * SecureAuthStorage or proceed without persistence.
+ */
+export declare function isKeychainAvailable(): boolean;
+/**
+ * Default secure storage implementation backed by `react-native-keychain`.
+ *
+ * - iOS: Keychain (encrypted, never synced via iCloud by default)
+ * - Android: Android Keystore-backed encryption
+ *
+ * Requires `react-native-keychain` as a peer dependency. Apps that prefer a
+ * different secure backend (e.g. `expo-secure-store`,
+ * `react-native-encrypted-storage`, an in-memory mock for testing, or a
+ * compliance-grade encryption layer) should implement the
+ * {@link KoolbaseAuthStorage} interface and pass it via
+ * `KoolbaseConfig.authStorage`.
+ */
+export declare class SecureAuthStorage implements KoolbaseAuthStorage {
+    private static readonly SERVICE;
+    saveSession(session: KoolbaseSession): Promise<void>;
+    readSession(): Promise<KoolbaseSession | null>;
+    clear(): Promise<void>;
+}

package/dist/auth-storage.js

@@ -0,0 +1,105 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SecureAuthStorage = void 0;
+exports.isKeychainAvailable = isKeychainAvailable;
+// Lazy-load react-native-keychain so apps without it installed (e.g. Expo Go,
+// or those providing a custom adapter) can still import this module without
+// crashing. The default SecureAuthStorage will throw a clear error on first
+// use if the peer dependency is missing.
+let _keychain = null;
+let _keychainAttempted = false;
+function loadKeychain() {
+    if (!_keychainAttempted) {
+        _keychainAttempted = true;
+        try {
+            // eslint-disable-next-line @typescript-eslint/no-var-requires
+            _keychain = require('react-native-keychain');
+        }
+        catch {
+            _keychain = null;
+        }
+    }
+    if (!_keychain) {
+        throw new Error('[Koolbase] SecureAuthStorage requires react-native-keychain. ' +
+            'Install it with:\n  npm install react-native-keychain\n' +
+            'Or provide your own storage adapter via ' +
+            'KoolbaseConfig.authStorage. For Expo Go (where ' +
+            'react-native-keychain is unavailable), implement KoolbaseAuthStorage ' +
+            'with expo-secure-store and pass it via authStorage.');
+    }
+    return _keychain;
+}
+/**
+ * Probe whether react-native-keychain is installed without throwing.
+ * Used by KoolbaseAuth to decide whether to instantiate a default
+ * SecureAuthStorage or proceed without persistence.
+ */
+function isKeychainAvailable() {
+    if (!_keychainAttempted) {
+        _keychainAttempted = true;
+        try {
+            // eslint-disable-next-line @typescript-eslint/no-var-requires
+            _keychain = require('react-native-keychain');
+        }
+        catch {
+            _keychain = null;
+        }
+    }
+    return _keychain !== null;
+}
+/**
+ * Default secure storage implementation backed by `react-native-keychain`.
+ *
+ * - iOS: Keychain (encrypted, never synced via iCloud by default)
+ * - Android: Android Keystore-backed encryption
+ *
+ * Requires `react-native-keychain` as a peer dependency. Apps that prefer a
+ * different secure backend (e.g. `expo-secure-store`,
+ * `react-native-encrypted-storage`, an in-memory mock for testing, or a
+ * compliance-grade encryption layer) should implement the
+ * {@link KoolbaseAuthStorage} interface and pass it via
+ * `KoolbaseConfig.authStorage`.
+ */
+class SecureAuthStorage {
+    async saveSession(session) {
+        const Keychain = loadKeychain();
+        await Keychain.setGenericPassword('session', JSON.stringify(session), { service: SecureAuthStorage.SERVICE });
+    }
+    async readSession() {
+        let Keychain;
+        try {
+            Keychain = loadKeychain();
+        }
+        catch {
+            // Peer dep missing — caller will fall back to no persistence.
+            return null;
+        }
+        try {
+            const credentials = await Keychain.getGenericPassword({
+                service: SecureAuthStorage.SERVICE,
+            });
+            if (!credentials || !credentials.password)
+                return null;
+            return JSON.parse(credentials.password);
+        }
+        catch {
+            // Corrupt data, schema mismatch, or platform-level keychain error.
+            // Treat as no session — caller will trigger fresh login.
+            return null;
+        }
+    }
+    async clear() {
+        let Keychain;
+        try {
+            Keychain = loadKeychain();
+        }
+        catch {
+            return; // No-op if peer dep missing.
+        }
+        await Keychain.resetGenericPassword({
+            service: SecureAuthStorage.SERVICE,
+        });
+    }
+}
+exports.SecureAuthStorage = SecureAuthStorage;
+SecureAuthStorage.SERVICE = 'koolbase_session_v1';