@techfinityedge/koolbase-react-native 1.7.0 → 1.9.0

package/dist/device-metadata.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Koolbase React Native SDK version. Sent in the `x-koolbase-sdk-version`
+ * header on every authenticated request so the server can route
+ * version-conditional logic (deprecation warnings, schema migrations,
+ * feature flags). Must match the `version` field in package.json.
+ */
+export declare const koolbaseSdkVersion = "1.9.0";
+/**
+ * Builds device-identifying headers attached to every Koolbase auth
+ * request. Mirrors the Flutter SDK's `DeviceMetadata` for parity. Apps
+ * with privacy concerns can swap in a custom storage adapter to avoid
+ * persisting the device label.
+ *
+ * Headers emitted:
+ * - User-Agent: koolbase-react-native/<sdk> (<platform> <version>)
+ * - x-koolbase-sdk:              react-native
+ * - x-koolbase-sdk-version:      <koolbaseSdkVersion>
+ * - x-koolbase-platform:         ios | android | web | etc.
+ * - x-koolbase-platform-version: numeric SDK level or OS version string
+ * - x-koolbase-app-version:      from KoolbaseConfig.appVersion or 'unknown'
+ * - x-koolbase-device-label:     persistent UUID per install
+ */
+export declare class DeviceMetadata {
+    private cached;
+    private ephemeralLabel;
+    private readonly appVersion;
+    constructor(appVersion?: string);
+    /**
+     * Build (or return cached) device headers. The first call may perform
+     * an async keychain read to look up the persisted device label;
+     * subsequent calls return the in-memory cache synchronously via the
+     * returned Promise.
+     */
+    build(): Promise<Record<string, string>>;
+    private getOrCreateDeviceLabel;
+}

package/dist/device-metadata.js

@@ -0,0 +1,102 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DeviceMetadata = exports.koolbaseSdkVersion = void 0;
+const react_native_1 = require("react-native");
+const auth_storage_1 = require("./auth-storage");
+/**
+ * Koolbase React Native SDK version. Sent in the `x-koolbase-sdk-version`
+ * header on every authenticated request so the server can route
+ * version-conditional logic (deprecation warnings, schema migrations,
+ * feature flags). Must match the `version` field in package.json.
+ */
+exports.koolbaseSdkVersion = '1.9.0';
+/**
+ * Generate a UUIDv4-shaped string for use as a stable per-install
+ * device label. Not cryptographically secure — this is a label, not a
+ * security primitive. Avoids pulling in a crypto-grade UUID dependency.
+ */
+function generateDeviceLabel() {
+    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);
+    });
+}
+/**
+ * Builds device-identifying headers attached to every Koolbase auth
+ * request. Mirrors the Flutter SDK's `DeviceMetadata` for parity. Apps
+ * with privacy concerns can swap in a custom storage adapter to avoid
+ * persisting the device label.
+ *
+ * Headers emitted:
+ * - User-Agent: koolbase-react-native/<sdk> (<platform> <version>)
+ * - x-koolbase-sdk:              react-native
+ * - x-koolbase-sdk-version:      <koolbaseSdkVersion>
+ * - x-koolbase-platform:         ios | android | web | etc.
+ * - x-koolbase-platform-version: numeric SDK level or OS version string
+ * - x-koolbase-app-version:      from KoolbaseConfig.appVersion or 'unknown'
+ * - x-koolbase-device-label:     persistent UUID per install
+ */
+class DeviceMetadata {
+    constructor(appVersion) {
+        this.cached = null;
+        this.ephemeralLabel = null;
+        this.appVersion = appVersion ?? 'unknown';
+    }
+    /**
+     * Build (or return cached) device headers. The first call may perform
+     * an async keychain read to look up the persisted device label;
+     * subsequent calls return the in-memory cache synchronously via the
+     * returned Promise.
+     */
+    async build() {
+        if (this.cached)
+            return this.cached;
+        const platform = String(react_native_1.Platform.OS);
+        const platformVersion = String(react_native_1.Platform.Version);
+        const deviceLabel = await this.getOrCreateDeviceLabel();
+        const userAgent = `koolbase-react-native/${exports.koolbaseSdkVersion} (${platform} ${platformVersion})`;
+        this.cached = {
+            'User-Agent': userAgent,
+            'x-koolbase-sdk': 'react-native',
+            'x-koolbase-sdk-version': exports.koolbaseSdkVersion,
+            'x-koolbase-platform': platform,
+            'x-koolbase-platform-version': platformVersion,
+            'x-koolbase-app-version': this.appVersion,
+            'x-koolbase-device-label': deviceLabel,
+        };
+        return this.cached;
+    }
+    async getOrCreateDeviceLabel() {
+        // No keychain available → ephemeral per-session label.
+        // (Better than no label — still useful for in-session debugging.)
+        if (!(0, auth_storage_1.isKeychainAvailable)()) {
+            if (!this.ephemeralLabel) {
+                this.ephemeralLabel = generateDeviceLabel();
+            }
+            return this.ephemeralLabel;
+        }
+        // eslint-disable-next-line @typescript-eslint/no-var-requires
+        const Keychain = require('react-native-keychain');
+        const service = 'koolbase_device_label_v1';
+        try {
+            const existing = await Keychain.getGenericPassword({ service });
+            if (existing && existing.password) {
+                return existing.password;
+            }
+        }
+        catch {
+            // fall through to create
+        }
+        const newLabel = generateDeviceLabel();
+        try {
+            await Keychain.setGenericPassword('device', newLabel, { service });
+        }
+        catch {
+            // Persistence failed — return the generated label anyway, but
+            // don't cache it as ephemeral since future requests may persist.
+        }
+        return newLabel;
+    }
+}
+exports.DeviceMetadata = DeviceMetadata;

package/dist/functions.d.ts

@@ -1,7 +1,8 @@
 import { KoolbaseConfig, FunctionInvokeResult, DeployOptions, DeployResult } from './types';
 export declare class KoolbaseFunctions {
     private config;
-    constructor(config: KoolbaseConfig);
+    private getUserAccessToken?;
+    constructor(config: KoolbaseConfig, getUserAccessToken?: () => string | null);
     deploy(options: DeployOptions): Promise<DeployResult>;
     invoke(name: string, body?: Record<string, unknown>): Promise<FunctionInvokeResult>;
 }

package/dist/functions.js

@@ -3,8 +3,9 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.KoolbaseFunctions = void 0;
 const types_1 = require("./types");
 class KoolbaseFunctions {
-    constructor(config) {
+    constructor(config, getUserAccessToken) {
         this.config = config;
+        this.getUserAccessToken = getUserAccessToken;
     }
     // ─── Deploy ────────────────────────────────────────────────────────────────
     async deploy(options) {
@@ -40,12 +41,17 @@ class KoolbaseFunctions {
     }
     // ─── Invoke ────────────────────────────────────────────────────────────────
     async invoke(name, body) {
+        const headers = {
+            'Content-Type': 'application/json',
+            'x-api-key': this.config.publicKey,
+        };
+        const userToken = this.getUserAccessToken?.();
+        if (userToken) {
+            headers['Authorization'] = `Bearer ${userToken}`;
+        }
         const res = await fetch(`${this.config.baseUrl}/v1/sdk/functions/${name}`, {
             method: 'POST',
-            headers: {
-                'Content-Type': 'application/json',
-                'x-api-key': this.config.publicKey,
-            },
+            headers,
             body: JSON.stringify({ body: body ?? {} }),
         });
         const data = await res.json().catch(() => null);

package/dist/index.d.ts

@@ -36,3 +36,8 @@ export declare const Koolbase: {
     readonly messaging: KoolbaseMessaging;
     checkVersion(currentVersion: string): VersionCheckResult;
 };
+export { koolbaseSdkVersion } from './device-metadata';
+export { RestoreResult } from './types';
+export type { AuthStateListener, FetchLike, KoolbaseAuthStorage } from './types';
+export { SecureAuthStorage } from './auth-storage';
+export { KoolbaseAuthError, InvalidCredentialsError, EmailAlreadyInUseError, UserDisabledError, WeakPasswordError, SessionExpiredError, TokenRevokedError, AccountLockedError, UnlockTokenInvalidError, RateLimitError, NetworkError, InvalidPhoneNumberError, OtpExpiredError, OtpInvalidError, OtpMaxAttemptsError, OtpRateLimitError, PhoneAlreadyLinkedError, SmsConfigMissingError, } from './auth-errors';

package/dist/index.js

@@ -17,7 +17,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Koolbase = exports.KoolbaseStorage = exports.KoolbaseRealtime = exports.KoolbaseFunctions = exports.KoolbaseFlags = exports.KoolbaseDatabase = exports.KoolbaseAuth = exports.KoolbaseCodePush = exports.KoolbaseAnalytics = exports.KoolbaseAppleAuth = exports.KoolbaseMessaging = 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 = exports.SecureAuthStorage = exports.RestoreResult = exports.koolbaseSdkVersion = exports.Koolbase = exports.KoolbaseStorage = exports.KoolbaseRealtime = exports.KoolbaseFunctions = exports.KoolbaseFlags = exports.KoolbaseDatabase = exports.KoolbaseAuth = exports.KoolbaseCodePush = exports.KoolbaseAnalytics = exports.KoolbaseAppleAuth = exports.KoolbaseMessaging = void 0;
 const async_storage_1 = __importDefault(require("@react-native-async-storage/async-storage"));
 const auth_1 = require("./auth");
 Object.defineProperty(exports, "KoolbaseAuth", { enumerable: true, get: function () { return auth_1.KoolbaseAuth; } });
@@ -69,7 +69,7 @@ exports.Koolbase = {
         _db = new database_1.KoolbaseDatabase(config, () => _auth?.currentUser?.id ?? null);
         _storage = new storage_1.KoolbaseStorage(config, () => _auth?.accessToken ?? null);
         _realtime = new realtime_1.KoolbaseRealtime(config);
-        _functions = new functions_1.KoolbaseFunctions(config);
+        _functions = new functions_1.KoolbaseFunctions(config, () => _auth?.accessToken ?? null);
         _flags = new flags_1.KoolbaseFlags(config, 'rn-device');
         _codePush = new code_push_1.KoolbaseCodePush(config, config.codePushChannel ?? 'stable');
         // Initialize code push — loads cached bundle then checks in background
@@ -164,3 +164,29 @@ exports.Koolbase = {
         return _flags.checkVersion(currentVersion);
     },
 };
+// v1.9.0 additions
+var device_metadata_1 = require("./device-metadata");
+Object.defineProperty(exports, "koolbaseSdkVersion", { enumerable: true, get: function () { return device_metadata_1.koolbaseSdkVersion; } });
+var types_1 = require("./types");
+Object.defineProperty(exports, "RestoreResult", { enumerable: true, get: function () { return types_1.RestoreResult; } });
+var auth_storage_1 = require("./auth-storage");
+Object.defineProperty(exports, "SecureAuthStorage", { enumerable: true, get: function () { return auth_storage_1.SecureAuthStorage; } });
+var auth_errors_1 = require("./auth-errors");
+Object.defineProperty(exports, "KoolbaseAuthError", { enumerable: true, get: function () { return auth_errors_1.KoolbaseAuthError; } });
+Object.defineProperty(exports, "InvalidCredentialsError", { enumerable: true, get: function () { return auth_errors_1.InvalidCredentialsError; } });
+Object.defineProperty(exports, "EmailAlreadyInUseError", { enumerable: true, get: function () { return auth_errors_1.EmailAlreadyInUseError; } });
+Object.defineProperty(exports, "UserDisabledError", { enumerable: true, get: function () { return auth_errors_1.UserDisabledError; } });
+Object.defineProperty(exports, "WeakPasswordError", { enumerable: true, get: function () { return auth_errors_1.WeakPasswordError; } });
+Object.defineProperty(exports, "SessionExpiredError", { enumerable: true, get: function () { return auth_errors_1.SessionExpiredError; } });
+Object.defineProperty(exports, "TokenRevokedError", { enumerable: true, get: function () { return auth_errors_1.TokenRevokedError; } });
+Object.defineProperty(exports, "AccountLockedError", { enumerable: true, get: function () { return auth_errors_1.AccountLockedError; } });
+Object.defineProperty(exports, "UnlockTokenInvalidError", { enumerable: true, get: function () { return auth_errors_1.UnlockTokenInvalidError; } });
+Object.defineProperty(exports, "RateLimitError", { enumerable: true, get: function () { return auth_errors_1.RateLimitError; } });
+Object.defineProperty(exports, "NetworkError", { enumerable: true, get: function () { return auth_errors_1.NetworkError; } });
+Object.defineProperty(exports, "InvalidPhoneNumberError", { enumerable: true, get: function () { return auth_errors_1.InvalidPhoneNumberError; } });
+Object.defineProperty(exports, "OtpExpiredError", { enumerable: true, get: function () { return auth_errors_1.OtpExpiredError; } });
+Object.defineProperty(exports, "OtpInvalidError", { enumerable: true, get: function () { return auth_errors_1.OtpInvalidError; } });
+Object.defineProperty(exports, "OtpMaxAttemptsError", { enumerable: true, get: function () { return auth_errors_1.OtpMaxAttemptsError; } });
+Object.defineProperty(exports, "OtpRateLimitError", { enumerable: true, get: function () { return auth_errors_1.OtpRateLimitError; } });
+Object.defineProperty(exports, "PhoneAlreadyLinkedError", { enumerable: true, get: function () { return auth_errors_1.PhoneAlreadyLinkedError; } });
+Object.defineProperty(exports, "SmsConfigMissingError", { enumerable: true, get: function () { return auth_errors_1.SmsConfigMissingError; } });

package/dist/types.d.ts

@@ -5,6 +5,24 @@ export interface KoolbaseConfig {
     analyticsEnabled?: boolean;
     appVersion?: string;
     messagingEnabled?: boolean;
+    /**
+     * Optional custom storage adapter for persisting auth state. If omitted,
+     * the SDK uses SecureAuthStorage backed by react-native-keychain (must
+     * be installed). For Expo Go or custom secure backends, provide your
+     * own KoolbaseAuthStorage implementation.
+     */
+    authStorage?: KoolbaseAuthStorage;
+    /**
+     * Per-request timeout in milliseconds for auth endpoints. Default 10000.
+     * On timeout, fetch rejects with an AbortError. restoreSession() treats
+     * this as Offline (preserves optimistic state).
+     */
+    authTimeout?: number;
+    /**
+     * Injectable fetch implementation. Defaults to the global fetch. Useful
+     * for testing (mock fetch), corporate proxies, or instrumented HTTP.
+     */
+    fetch?: FetchLike;
 }
 export interface KoolbaseUser {
     id: string;
@@ -19,8 +37,51 @@ export interface KoolbaseUser {
 export interface KoolbaseSession {
     accessToken: string;
     refreshToken: string;
+    /** ISO 8601 timestamp when accessToken expires; from server response. */
+    expiresAt: string;
     user: KoolbaseUser;
 }
+/**
+ * Abstract storage interface for persisting authentication state.
+ *
+ * The SDK ships with SecureAuthStorage (react-native-keychain) as the
+ * default. Apps with custom requirements — Expo Go (where keychain is
+ * unavailable), compliant encryption layers, or in-memory test mocks —
+ * can implement this interface and inject it via KoolbaseConfig.authStorage.
+ */
+export interface KoolbaseAuthStorage {
+    saveSession(session: KoolbaseSession): Promise<void>;
+    readSession(): Promise<KoolbaseSession | null>;
+    clear(): Promise<void>;
+}
+/**
+ * Result of KoolbaseAuth.restoreSession(). Apps should branch on this:
+ * - NoSession  → show login screen
+ * - Restored   → show authenticated UI
+ * - Expired    → show login screen with "session expired" message
+ * - Offline    → show authenticated UI optimistically; API calls will
+ *                fail until network is reachable
+ */
+export declare enum RestoreResult {
+    NoSession = "no_session",
+    Restored = "restored",
+    Expired = "expired",
+    Offline = "offline"
+}
+/**
+ * Callback invoked when authentication state changes. Receives the
+ * current user, or null when signed out. Listeners fire on login,
+ * register, refresh, session restoration, logout, setSession, and
+ * linkPhone. Errors thrown from a listener are swallowed so one
+ * broken listener cannot break propagation to others.
+ */
+export type AuthStateListener = (user: KoolbaseUser | null) => void;
+/**
+ * Drop-in replacement for the global `fetch` function. Inject via
+ * KoolbaseConfig.fetch for testing (mock fetch), proxying, or
+ * monitoring. Matches the standard fetch signature.
+ */
+export type FetchLike = (input: string, init?: RequestInit) => Promise<Response>;
 export interface RegisterParams {
     email: string;
     password: string;

package/dist/types.js

@@ -1,6 +1,21 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.FunctionRuntime = void 0;
+exports.FunctionRuntime = exports.RestoreResult = void 0;
+/**
+ * Result of KoolbaseAuth.restoreSession(). Apps should branch on this:
+ * - NoSession  → show login screen
+ * - Restored   → show authenticated UI
+ * - Expired    → show login screen with "session expired" message
+ * - Offline    → show authenticated UI optimistically; API calls will
+ *                fail until network is reachable
+ */
+var RestoreResult;
+(function (RestoreResult) {
+    RestoreResult["NoSession"] = "no_session";
+    RestoreResult["Restored"] = "restored";
+    RestoreResult["Expired"] = "expired";
+    RestoreResult["Offline"] = "offline";
+})(RestoreResult || (exports.RestoreResult = RestoreResult = {}));
 // ─── Functions ─────────────────────────────────────────────────────────────
 var FunctionRuntime;
 (function (FunctionRuntime) {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@techfinityedge/koolbase-react-native",
-  "version": "1.7.0",
-  "description": "React Native SDK for Koolbase — auth, database, storage, realtime, feature flags, and functions in one package.",
+  "version": "1.9.0",
+  "description": "React Native SDK for Koolbase \u2014 auth, database, storage, realtime, feature flags, and functions in one package.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "files": [
@@ -27,17 +27,24 @@
   },
   "devDependencies": {
     "@types/jszip": "^3.4.0",
+    "react-native-keychain": "^10.0.0",
     "typescript": "^5.0.0"
   },
   "peerDependencies": {
-    "react-native": ">=0.70.0"
+    "react-native": ">=0.70.0",
+    "react-native-keychain": ">=8.0.0"
   },
   "dependencies": {
     "@react-native-async-storage/async-storage": "^3.0.2",
     "@react-native-community/netinfo": "^12.0.1",
     "jszip": "^3.10.1"
   },
-    "publishConfig": {
+  "publishConfig": {
     "access": "public"
+  },
+  "peerDependenciesMeta": {
+    "react-native-keychain": {
+      "optional": true
+    }
   }
 }