@techfinityedge/koolbase-react-native 1.8.0 → 1.10.0

package/dist/auth.js

@@ -1,62 +1,379 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.KoolbaseAuth = void 0;
+const types_1 = require("./types");
 const auth_errors_1 = require("./auth-errors");
+const auth_storage_1 = require("./auth-storage");
+const device_metadata_1 = require("./device-metadata");
 class KoolbaseAuth {
     constructor(config) {
         this.session = null;
+        this.ongoingRefresh = null;
+        this.listeners = new Set();
         this.config = config;
+        this.metadata = new device_metadata_1.DeviceMetadata(config.appVersion);
+        this.fetchFn = config.fetch ?? ((url, init) => fetch(url, init));
+        this.timeoutMs = config.authTimeout ?? 10000;
+        if (config.authStorage) {
+            this.storage = config.authStorage;
+        }
+        else if ((0, auth_storage_1.isKeychainAvailable)()) {
+            this.storage = new auth_storage_1.SecureAuthStorage();
+        }
+        else {
+            this.storage = null;
+            // eslint-disable-next-line no-console
+            console.warn('[Koolbase] No persistent auth storage available. Sessions will not ' +
+                'survive app restarts. Install react-native-keychain for the ' +
+                'default secure backend, or provide KoolbaseConfig.authStorage ' +
+                'with your own implementation.');
+        }
+    }
+    // ─── Auth state listener ────────────────────────────────────────────────
+    /**
+     * Subscribe to authentication state changes. The listener fires:
+     * - Immediately on subscribe, with the current user (or null).
+     * - On every successful login, register, refresh, session restoration.
+     * - On logout / explicit setSession(null).
+     * - On linkPhone success (user object updated with phone fields).
+     *
+     * Returns an unsubscribe function. Call it when the consumer no longer
+     * needs updates (e.g. in a React useEffect cleanup).
+     *
+     * Listener errors are swallowed so a buggy listener can't break auth
+     * state propagation to other listeners.
+     *
+     * @example
+     * const unsubscribe = auth.onAuthStateChange((user) => {
+     *   setCurrentUser(user);
+     * });
+     * // later:
+     * unsubscribe();
+     */
+    onAuthStateChange(listener) {
+        this.listeners.add(listener);
+        // Fire immediately with current state — matches RN ecosystem
+        // convention (Firebase Auth, Supabase Auth) so consumers don't
+        // need to separately read currentUser on mount.
+        try {
+            listener(this.session?.user ?? null);
+        }
+        catch {
+            // swallow
+        }
+        return () => {
+            this.listeners.delete(listener);
+        };
     }
-    get headers() {
-        return { 'Content-Type': 'application/json' };
+    fireAuthStateChange() {
+        const user = this.session?.user ?? null;
+        for (const listener of this.listeners) {
+            try {
+                listener(user);
+            }
+            catch {
+                // swallow — one broken listener doesn't break others
+            }
+        }
     }
-    get authHeaders() {
+    // ─── Headers ────────────────────────────────────────────────────────────
+    /**
+     * Compose the full header set for an outbound request: base headers,
+     * device metadata, and optionally the Authorization bearer token.
+     * Async because device metadata's first build may read from keychain.
+     */
+    async prepareHeaders(includeAuth) {
+        const deviceHeaders = await this.metadata.build();
         return {
             'Content-Type': 'application/json',
-            ...(this.session
+            'x-api-key': this.config.publicKey,
+            ...deviceHeaders,
+            ...(includeAuth && 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}`);
+    // ─── Request plumbing ───────────────────────────────────────────────────
+    /**
+     * Low-level request helper used by every endpoint. Wires together:
+     * - The injected fetch implementation (config.fetch or global fetch)
+     * - Device metadata + x-api-key + auth header in one place
+     * - AbortController-based timeout (config.authTimeout, default 10s)
+     *
+     * On timeout, fetch rejects with an AbortError; callers see this as a
+     * non-KoolbaseAuthError exception, which restoreSession() treats as
+     * Offline (preserving optimistic state).
+     */
+    async authRequest(path, options = {}) {
+        const headers = await this.prepareHeaders(options.includeAuth ?? false);
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+        try {
+            return await this.fetchFn(`${this.config.baseUrl}${path}`, {
+                method: options.method ?? 'GET',
+                headers,
+                body: options.body !== undefined ? JSON.stringify(options.body) : undefined,
+                signal: controller.signal,
+            });
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    /**
+     * Authenticated request wrapper. Refreshes the access token if it's
+     * stale (within 1-min buffer of expiry) before issuing the call, then
+     * delegates to {@link authRequest} with includeAuth=true.
+     */
+    async authedRequest(path, options = {}) {
+        await this._ensureValidToken();
+        return this.authRequest(path, { ...options, includeAuth: true });
+    }
+    // ─── Internal session lifecycle ─────────────────────────────────────────
+    async setSessionInternal(session) {
+        this.session = session;
+        if (this.storage) {
+            try {
+                await this.storage.saveSession(session);
+            }
+            catch (err) {
+                // eslint-disable-next-line no-console
+                console.warn('[Koolbase] Failed to persist session; staying signed in for this ' +
+                    'session only:', err);
+            }
+        }
+        this.fireAuthStateChange();
+    }
+    async clearSessionInternal() {
+        this.session = null;
+        if (this.storage) {
+            try {
+                await this.storage.clear();
+            }
+            catch {
+                // best effort
+            }
+        }
+        this.fireAuthStateChange();
+    }
+    // ─── Session restoration ────────────────────────────────────────────────
+    async restoreSession() {
+        if (!this.storage)
+            return types_1.RestoreResult.NoSession;
+        const persisted = await this.storage.readSession();
+        if (!persisted)
+            return types_1.RestoreResult.NoSession;
+        // Optimistic restore — populate state and fire listener before any
+        // network call. App can render authenticated UI immediately.
+        this.session = persisted;
+        this.fireAuthStateChange();
+        const expiresAt = persisted.expiresAt
+            ? new Date(persisted.expiresAt).getTime()
+            : 0;
+        const oneMinuteMs = 60 * 1000;
+        if (expiresAt > Date.now() + oneMinuteMs) {
+            return types_1.RestoreResult.Restored;
+        }
+        try {
+            await this.refresh(persisted.refreshToken);
+            return types_1.RestoreResult.Restored;
+        }
+        catch (e) {
+            if (e instanceof auth_errors_1.SessionExpiredError ||
+                e instanceof auth_errors_1.TokenRevokedError ||
+                e instanceof auth_errors_1.InvalidCredentialsError) {
+                await this.clearSessionInternal();
+                return types_1.RestoreResult.Expired;
+            }
+            return types_1.RestoreResult.Offline;
         }
-        return data;
     }
+    // ─── Public auth API ────────────────────────────────────────────────────
     async register(params) {
-        const data = await this.request('POST', '/v1/sdk/auth/register', params);
-        return data.user;
+        if (params.password.length < 8)
+            throw new auth_errors_1.WeakPasswordError();
+        const res = await this.authRequest('/v1/sdk/auth/register', {
+            method: 'POST',
+            body: params,
+        });
+        const session = await this.parseSessionResponse(res, false);
+        await this.setSessionInternal(session);
+        return session.user;
     }
     async login(params) {
-        const data = await this.request('POST', '/v1/sdk/auth/login', params);
-        this.session = data;
-        return data;
+        const res = await this.authRequest('/v1/sdk/auth/login', {
+            method: 'POST',
+            body: params,
+        });
+        const session = await this.parseSessionResponse(res, false);
+        await this.setSessionInternal(session);
+        return session;
+    }
+    /**
+   * Sign in with Apple using a credential obtained from a native Apple
+   * Sign-In SDK.
+   *
+   * The SDK is library-agnostic — use any native Apple Sign-In package
+   * (`@invertase/react-native-apple-authentication`, etc.) and pass the
+   * resulting `identityToken`, optional `nonce`, and optional `fullName`.
+   *
+   * `fullName` is meaningful only on first sign-in — Apple omits name
+   * data on subsequent sign-ins. The server persists at link time and
+   * ignores on subsequent sign-ins.
+   *
+   * On success the session is persisted via the configured storage and
+   * `onAuthStateChange` fires with the resolved user.
+   *
+   * @throws AppleSignInNotConfiguredError when Apple is not enabled in
+   *   the dashboard OAuth config for this environment (400).
+   * @throws InvalidAppleTokenError when the token signature, audience,
+   *   expiry, replay, or nonce check failed server-side (401).
+   * @throws UserDisabledError when the account flag is set to disabled (403).
+   * @throws AppleEmailRequiredError when Apple did not return email for
+   *   a new-account sign-in (400).
+   * @throws OAuthEmailConflictError when email matches existing user
+   *   but auto-link rule blocked (409).
+   */
+    async signInWithApple(params) {
+        const body = {
+            identity_token: params.identityToken,
+        };
+        if (params.nonce && params.nonce.length > 0) {
+            body.nonce = params.nonce;
+        }
+        if (params.fullName) {
+            const nameJson = {};
+            if (params.fullName.givenName)
+                nameJson.given_name = params.fullName.givenName;
+            if (params.fullName.familyName)
+                nameJson.family_name = params.fullName.familyName;
+            if (Object.keys(nameJson).length > 0) {
+                body.full_name = nameJson;
+            }
+        }
+        const res = await this.authRequest('/v1/sdk/auth/oauth/apple', {
+            method: 'POST',
+            body,
+        });
+        const session = await this.parseAppleSessionResponse(res);
+        await this.setSessionInternal(session);
+        return session;
+    }
+    /**
+     * Parses a /v1/sdk/auth/oauth/apple response. Distinct from
+     * parseSessionResponse because OAuth error semantics differ from
+     * credential auth — status codes map to a separate error set.
+     */
+    async parseAppleSessionResponse(res) {
+        if (res.status === 200) {
+            const data = await res.json();
+            return {
+                accessToken: data.access_token,
+                refreshToken: data.refresh_token,
+                expiresAt: data.expires_at,
+                user: this.mapUser(data.user),
+            };
+        }
+        let errorMessage = '';
+        try {
+            const data = await res.json();
+            errorMessage = data?.error ?? '';
+        }
+        catch {
+            // best-effort error message extraction
+        }
+        if (res.status === 400) {
+            if (errorMessage.includes('not configured')) {
+                throw new auth_errors_1.AppleSignInNotConfiguredError();
+            }
+            if (errorMessage.includes('did not return email')) {
+                throw new auth_errors_1.AppleEmailRequiredError();
+            }
+            throw new auth_errors_1.KoolbaseAuthError(`apple sign-in failed: ${errorMessage}`, 'apple_signin_failed');
+        }
+        if (res.status === 401)
+            throw new auth_errors_1.InvalidAppleTokenError();
+        if (res.status === 403)
+            throw new auth_errors_1.UserDisabledError();
+        if (res.status === 409)
+            throw new auth_errors_1.OAuthEmailConflictError();
+        if (res.status === 429)
+            throw new auth_errors_1.RateLimitError(errorMessage);
+        throw new auth_errors_1.KoolbaseAuthError(`apple sign-in failed: ${res.status} ${errorMessage}`, `apple_signin_http_${res.status}`);
+    }
+    async refresh(refreshToken) {
+        if (this.ongoingRefresh) {
+            return this.ongoingRefresh;
+        }
+        const promise = this._doRefresh(refreshToken);
+        this.ongoingRefresh = promise;
+        promise
+            .catch(() => {
+            // swallow; original promise still rejects to awaiters
+        })
+            .finally(() => {
+            if (this.ongoingRefresh === promise) {
+                this.ongoingRefresh = null;
+            }
+        });
+        return promise;
+    }
+    async _doRefresh(refreshToken) {
+        const token = refreshToken ?? this.session?.refreshToken;
+        if (!token) {
+            throw new auth_errors_1.SessionExpiredError();
+        }
+        const res = await this.authRequest('/v1/sdk/auth/refresh', {
+            method: 'POST',
+            body: { refresh_token: token },
+        });
+        const session = await this.parseSessionResponse(res, true);
+        await this.setSessionInternal(session);
+        return session;
     }
     async logout() {
-        if (!this.session)
-            return;
+        let serverSucceeded = true;
         try {
-            await this.request('POST', '/v1/sdk/auth/logout', {}, true);
+            if (this.session) {
+                // Best-effort: don't auto-refresh during logout. If the token's
+                // already expired, we still want to clear local state — server
+                // will reap expired sessions itself.
+                const res = await this.authRequest('/v1/sdk/auth/logout', {
+                    method: 'POST',
+                    includeAuth: true,
+                });
+                if (!res.ok)
+                    serverSucceeded = false;
+            }
+        }
+        catch {
+            serverSucceeded = false;
         }
         finally {
-            this.session = null;
+            await this.clearSessionInternal();
         }
+        return serverSucceeded;
     }
     async forgotPassword(email) {
-        await this.request('POST', '/v1/sdk/auth/forgot-password', { email });
+        const res = await this.authRequest('/v1/sdk/auth/password-reset', {
+            method: 'POST',
+            body: { email },
+        });
+        await this.checkResponse(res);
     }
     async resetPassword(token, password) {
-        await this.request('POST', '/v1/sdk/auth/reset-password', {
-            token,
-            password,
+        const res = await this.authRequest('/v1/sdk/auth/password-reset/confirm', {
+            method: 'POST',
+            body: { token, password },
+        });
+        await this.checkResponse(res);
+    }
+    async unlock(token) {
+        const res = await this.authRequest('/v1/sdk/auth/unlock', {
+            method: 'POST',
+            body: { token },
         });
+        await this.checkResponse(res);
     }
     get currentUser() {
         return this.session?.user ?? null;
@@ -64,61 +381,58 @@ class KoolbaseAuth {
     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;
+    async setSession(session) {
+        if (session) {
+            await this.setSessionInternal(session);
         }
-        catch {
-            return null;
+        else {
+            await this.clearSessionInternal();
         }
     }
+    // ─── OAuth (DEPRECATED — see v1.10.0) ───────────────────────────────────
+    /**
+     * @deprecated v1.9.0: Server endpoint /v1/sdk/auth/oauth not yet
+     * shipped. This method previously routed to /v1/auth/oauth (dashboard
+     * developer OAuth) which never created project-scoped end-user
+     * sessions. Properly implemented in v1.10.0 with provider-specific
+     * server endpoints under /v1/sdk/auth/oauth/{apple,google,github}.
+     * Use email/password sign-in for now.
+     *
+     * @throws Always throws KoolbaseAuthError('not_implemented').
+     */
+    async oauthLogin(_params) {
+        throw new auth_errors_1.KoolbaseAuthError('OAuth sign-in is not yet implemented for the Koolbase SDK. ' +
+            'Planned for v1.10.0 (server-side endpoints under ' +
+            '/v1/sdk/auth/oauth/{provider}). Use email/password authentication ' +
+            'in the meantime.', 'not_implemented');
+    }
+    // ─── Phone OTP ──────────────────────────────────────────────────────────
     async sendOtp(params) {
         this.validatePhone(params.phoneNumber);
-        const res = await fetch(`${this.config.baseUrl}/v1/sdk/auth/phone/send-otp`, {
+        const res = await this.authRequest('/v1/sdk/auth/phone/send-otp', {
             method: 'POST',
-            headers: this.headers,
-            body: JSON.stringify({ phone_number: params.phoneNumber }),
+            body: { phone_number: params.phoneNumber },
         });
         const data = await this.parsePhoneResponse(res);
         return { expiresAt: data.expires_at };
     }
     async verifyOtp(params) {
         this.validatePhone(params.phoneNumber);
-        const res = await fetch(`${this.config.baseUrl}/v1/sdk/auth/phone/verify-otp`, {
+        const res = await this.authRequest('/v1/sdk/auth/phone/verify-otp', {
             method: 'POST',
-            headers: this.headers,
-            body: JSON.stringify({
+            body: {
                 phone_number: params.phoneNumber,
                 code: params.code,
-            }),
+            },
         });
         const data = await this.parsePhoneResponse(res);
-        const user = {
-            id: data.user.id,
-            email: data.user.email ?? '',
-            phoneNumber: data.user.phone_number,
-            phoneVerified: data.user.phone_verified ?? false,
-            fullName: data.user.full_name,
-            avatarUrl: data.user.avatar_url,
-            verified: data.user.verified ?? false,
-            createdAt: data.user.created_at,
-        };
         const session = {
             accessToken: data.access_token,
             refreshToken: data.refresh_token,
-            user,
+            expiresAt: data.expires_at,
+            user: this.mapUser(data.user),
         };
-        this.session = session;
+        await this.setSessionInternal(session);
         return { session, isNewUser: data.is_new_user ?? false };
     }
     async linkPhone(params) {
@@ -126,27 +440,135 @@ class KoolbaseAuth {
             throw new auth_errors_1.KoolbaseAuthError('Must be signed in to link a phone number', 'unauthenticated');
         }
         this.validatePhone(params.phoneNumber);
-        const res = await fetch(`${this.config.baseUrl}/v1/sdk/auth/phone/link`, {
+        const res = await this.authedRequest('/v1/sdk/auth/phone/link', {
             method: 'POST',
-            headers: this.authHeaders,
-            body: JSON.stringify({
+            body: {
                 phone_number: params.phoneNumber,
                 code: params.code,
-            }),
+            },
         });
-        await this.parsePhoneResponse(res);
+        const body = await this.parsePhoneResponse(res);
+        // Update local session: prefer the canonical user from the server
+        // response if present; otherwise merge the linked phone into the
+        // existing in-memory user. Either way, setSessionInternal fires the
+        // auth state listener so consumers can react to the phone link.
+        if (this.session) {
+            const updatedUser = body.user
+                ? this.mapUser(body.user)
+                : {
+                    ...this.session.user,
+                    phoneNumber: params.phoneNumber,
+                    phoneVerified: true,
+                };
+            await this.setSessionInternal({
+                ...this.session,
+                user: updatedUser,
+            });
+        }
+    }
+    // ─── Cleanup ────────────────────────────────────────────────────────────
+    /**
+     * Release resources held by this auth client. Clears the in-memory
+     * listener set. Does not invalidate sessions or clear storage — call
+     * {@link logout} for that.
+     */
+    dispose() {
+        this.listeners.clear();
     }
+    // ─── Helpers ────────────────────────────────────────────────────────────
     validatePhone(phoneNumber) {
         if (!/^\+[1-9]\d{6,14}$/.test(phoneNumber)) {
             throw new auth_errors_1.InvalidPhoneNumberError();
         }
     }
+    async _ensureValidToken() {
+        if (this.session && this.session.expiresAt) {
+            const expiresAt = new Date(this.session.expiresAt).getTime();
+            if (Date.now() < expiresAt - 60 * 1000) {
+                return this.session.accessToken;
+            }
+        }
+        if (!this.session) {
+            throw new auth_errors_1.SessionExpiredError();
+        }
+        try {
+            const session = await this.refresh();
+            return session.accessToken;
+        }
+        catch (e) {
+            if (e instanceof auth_errors_1.KoolbaseAuthError)
+                throw e;
+            throw new auth_errors_1.SessionExpiredError();
+        }
+    }
+    mapUser(raw) {
+        return {
+            id: raw.id,
+            email: raw.email ?? '',
+            phoneNumber: raw.phone_number,
+            phoneVerified: raw.phone_verified ?? false,
+            fullName: raw.full_name,
+            avatarUrl: raw.avatar_url,
+            verified: raw.verified ?? false,
+            createdAt: raw.created_at,
+        };
+    }
+    async parseSessionResponse(res, isRefresh) {
+        if (res.status === 409)
+            throw new auth_errors_1.EmailAlreadyInUseError();
+        if (res.status === 401) {
+            throw isRefresh ? new auth_errors_1.SessionExpiredError() : new auth_errors_1.InvalidCredentialsError();
+        }
+        if (res.status === 403)
+            throw new auth_errors_1.UserDisabledError();
+        if (!res.ok)
+            await this.throwTypedError(res);
+        const data = await res.json();
+        return {
+            accessToken: data.access_token,
+            refreshToken: data.refresh_token,
+            expiresAt: data.expires_at,
+            user: this.mapUser(data.user),
+        };
+    }
+    async checkResponse(res) {
+        if (res.ok)
+            return;
+        await this.throwTypedError(res);
+    }
+    async throwTypedError(res) {
+        let body = {};
+        try {
+            body = await res.json();
+        }
+        catch {
+            // ignore
+        }
+        const msg = body.error ?? '';
+        if (res.status === 429) {
+            if (msg.includes('account temporarily locked')) {
+                throw new auth_errors_1.AccountLockedError();
+            }
+            throw new auth_errors_1.RateLimitError(msg || undefined);
+        }
+        if (msg.includes('invalid or expired unlock token')) {
+            throw new auth_errors_1.UnlockTokenInvalidError();
+        }
+        if (msg.includes('session revoked') ||
+            msg.includes('token revoked') ||
+            msg.includes('session has been revoked')) {
+            throw new auth_errors_1.TokenRevokedError();
+        }
+        throw new auth_errors_1.KoolbaseAuthError(msg || `Request failed: ${res.status}`, `http_${res.status}`);
+    }
     async parsePhoneResponse(res) {
         let body = {};
         try {
             body = await res.json();
         }
-        catch { }
+        catch {
+            // ignore
+        }
         if (res.ok)
             return body;
         const msg = body.error ?? '';

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.10.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;
+}