@oxyhq/core 1.5.0 → 1.6.1

package/dist/types/mixins/OxyServices.location.d.ts

@@ -20,6 +20,7 @@ export declare function OxyServicesLocationMixin<T extends typeof OxyServicesBas
         httpService: import("../HttpService").HttpService;
         cloudURL: string;
         config: import("../OxyServices.base").OxyConfig;
+        __resetTokensForTests(): void;
         makeRequest<T_1>(method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE", url: string, data?: any, options?: import("../HttpService").RequestOptions): Promise<T_1>;
         getBaseURL(): string;
         getClient(): import("../HttpService").HttpService;
@@ -62,5 +63,4 @@ export declare function OxyServicesLocationMixin<T extends typeof OxyServicesBas
             [key: string]: any;
         }>;
     };
-    __resetTokensForTests(): void;
 } & T;

package/dist/types/mixins/OxyServices.payment.d.ts

@@ -67,6 +67,7 @@ export declare function OxyServicesPaymentMixin<T extends typeof OxyServicesBase
         httpService: import("../HttpService").HttpService;
         cloudURL: string;
         config: import("../OxyServices.base").OxyConfig;
+        __resetTokensForTests(): void;
         makeRequest<T_1>(method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE", url: string, data?: any, options?: import("../HttpService").RequestOptions): Promise<T_1>;
         getBaseURL(): string;
         getClient(): import("../HttpService").HttpService;
@@ -109,5 +110,4 @@ export declare function OxyServicesPaymentMixin<T extends typeof OxyServicesBase
             [key: string]: any;
         }>;
     };
-    __resetTokensForTests(): void;
 } & T;

package/dist/types/mixins/OxyServices.popup.d.ts

@@ -155,6 +155,7 @@ export declare function OxyServicesPopupAuthMixin<T extends typeof OxyServicesBa
         httpService: import("../HttpService").HttpService;
         cloudURL: string;
         config: import("../OxyServices.base").OxyConfig;
+        __resetTokensForTests(): void;
         makeRequest<T_1>(method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE", url: string, data?: any, options?: import("../HttpService").RequestOptions): Promise<T_1>;
         getBaseURL(): string;
         getClient(): import("../HttpService").HttpService;
@@ -202,6 +203,5 @@ export declare function OxyServicesPopupAuthMixin<T extends typeof OxyServicesBa
     readonly POPUP_HEIGHT: 700;
     readonly POPUP_TIMEOUT: 60000;
     readonly SILENT_TIMEOUT: 5000;
-    __resetTokensForTests(): void;
 } & T;
 export { OxyServicesPopupAuthMixin as PopupAuthMixin };

package/dist/types/mixins/OxyServices.privacy.d.ts

@@ -78,6 +78,7 @@ export declare function OxyServicesPrivacyMixin<T extends typeof OxyServicesBase
         httpService: import("../HttpService").HttpService;
         cloudURL: string;
         config: import("../OxyServices.base").OxyConfig;
+        __resetTokensForTests(): void;
         makeRequest<T_1>(method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE", url: string, data?: any, options?: import("../HttpService").RequestOptions): Promise<T_1>;
         getBaseURL(): string;
         getClient(): import("../HttpService").HttpService;
@@ -120,5 +121,4 @@ export declare function OxyServicesPrivacyMixin<T extends typeof OxyServicesBase
             [key: string]: any;
         }>;
     };
-    __resetTokensForTests(): void;
 } & T;

package/dist/types/mixins/OxyServices.redirect.d.ts

@@ -194,6 +194,7 @@ export declare function OxyServicesRedirectAuthMixin<T extends typeof OxyService
         httpService: import("../HttpService").HttpService;
         cloudURL: string;
         config: import("../OxyServices.base").OxyConfig;
+        __resetTokensForTests(): void;
         makeRequest<T_1>(method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE", url: string, data?: any, options?: import("../HttpService").RequestOptions): Promise<T_1>;
         getBaseURL(): string;
         getClient(): import("../HttpService").HttpService;
@@ -242,6 +243,5 @@ export declare function OxyServicesRedirectAuthMixin<T extends typeof OxyService
     readonly STATE_STORAGE_KEY: "oxy_auth_state";
     readonly PRE_AUTH_URL_KEY: "oxy_pre_auth_url";
     readonly NONCE_STORAGE_KEY: "oxy_auth_nonce";
-    __resetTokensForTests(): void;
 } & T;
 export { OxyServicesRedirectAuthMixin as RedirectAuthMixin };

package/dist/types/mixins/OxyServices.security.d.ts

@@ -34,6 +34,7 @@ export declare function OxyServicesSecurityMixin<T extends typeof OxyServicesBas
         httpService: import("../HttpService").HttpService;
         cloudURL: string;
         config: import("../OxyServices.base").OxyConfig;
+        __resetTokensForTests(): void;
         makeRequest<T_1>(method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE", url: string, data?: any, options?: import("../HttpService").RequestOptions): Promise<T_1>;
         getBaseURL(): string;
         getClient(): import("../HttpService").HttpService;
@@ -76,5 +77,4 @@ export declare function OxyServicesSecurityMixin<T extends typeof OxyServicesBas
             [key: string]: any;
         }>;
     };
-    __resetTokensForTests(): void;
 } & T;

package/dist/types/mixins/OxyServices.user.d.ts

@@ -138,6 +138,7 @@ export declare function OxyServicesUserMixin<T extends typeof OxyServicesBase>(B
         httpService: import("../HttpService").HttpService;
         cloudURL: string;
         config: import("../OxyServices.base").OxyConfig;
+        __resetTokensForTests(): void;
         makeRequest<T_1>(method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE", url: string, data?: any, options?: import("../HttpService").RequestOptions): Promise<T_1>;
         getBaseURL(): string;
         getClient(): import("../HttpService").HttpService;
@@ -180,5 +181,4 @@ export declare function OxyServicesUserMixin<T extends typeof OxyServicesBase>(B
             [key: string]: any;
         }>;
     };
-    __resetTokensForTests(): void;
 } & T;

package/dist/types/mixins/OxyServices.utility.d.ts

@@ -43,25 +43,36 @@ export declare function OxyServicesUtilityMixin<T extends typeof OxyServicesBase
          * Validates JWT tokens against the Oxy API and attaches user data to requests.
          * Uses server-side session validation for security (not just JWT decode).
          *
+         * **Design note — jwtDecode vs jwt.verify:**
+         * This middleware intentionally uses `jwtDecode()` (decode-only, no signature
+         * verification) for user tokens. This is by design, NOT a security gap:
+         * - Third-party apps using `oxy.auth()` don't have the Oxy JWT secret
+         * - Security comes from API-based session validation (`validateSession()`)
+         *   which checks the session server-side on every request
+         * - Service tokens (type: 'service') DO use cryptographic HMAC verification
+         *   via the `jwtSecret` option, since they are stateless
+         * - The backend's own `authMiddleware` uses `jwt.verify()` because it has
+         *   direct access to `ACCESS_TOKEN_SECRET`
+         *
          * @example
          * ```typescript
          * import { OxyServices } from '@oxyhq/core';
          *
          * const oxy = new OxyServices({ baseURL: 'https://api.oxy.so' });
          *
-         * // Protect all routes under /api/protected
-         * app.use('/api/protected', oxy.auth());
+         * // Protect all routes under /protected
+         * app.use('/protected', oxy.auth());
          *
          * // Access user in route handler
-         * app.get('/api/protected/me', (req, res) => {
+         * app.get('/protected/me', (req, res) => {
          *   res.json({ userId: req.userId, user: req.user });
          * });
          *
          * // Load full user profile from API
-         * app.use('/api/admin', oxy.auth({ loadUser: true }));
+         * app.use('/admin', oxy.auth({ loadUser: true }));
          *
          * // Optional auth - attach user if present, don't block if absent
-         * app.use('/api/public', oxy.auth({ optional: true }));
+         * app.use('/public', oxy.auth({ optional: true }));
          * ```
          *
          * @param options Optional configuration
@@ -74,6 +85,8 @@ export declare function OxyServicesUtilityMixin<T extends typeof OxyServicesBase
          * Returns a middleware function for Socket.IO that validates JWT tokens
          * from the handshake auth object and attaches user data to the socket.
          *
+         * Uses `jwtDecode()` + API session validation (same rationale as `auth()`).
+         *
          * @example
          * ```typescript
          * import { OxyServices } from '@oxyhq/core';
@@ -111,10 +124,12 @@ export declare function OxyServicesUtilityMixin<T extends typeof OxyServicesBase
          */
         serviceAuth(options?: {
             debug?: boolean;
+            jwtSecret?: string;
         }): (req: any, res: any, next: any) => Promise<void>;
         httpService: import("../HttpService").HttpService;
         cloudURL: string;
         config: import("../OxyServices.base").OxyConfig;
+        __resetTokensForTests(): void;
         makeRequest<T_1>(method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE", url: string, data?: any, options?: import("../HttpService").RequestOptions): Promise<T_1>;
         getBaseURL(): string;
         getClient(): import("../HttpService").HttpService;
@@ -157,6 +172,5 @@ export declare function OxyServicesUtilityMixin<T extends typeof OxyServicesBase
             [key: string]: any;
         }>;
     };
-    __resetTokensForTests(): void;
 } & T;
 export {};

package/dist/types/utils/authHelpers.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Authentication helper utilities for common token validation
+ * and authentication error handling patterns.
+ */
+import type { OxyServices } from '../OxyServices';
+/**
+ * Error thrown when session sync is required
+ */
+export declare class SessionSyncRequiredError extends Error {
+    constructor(message?: string);
+}
+/**
+ * Error thrown when authentication fails
+ */
+export declare class AuthenticationFailedError extends Error {
+    constructor(message?: string);
+}
+/**
+ * Ensures a valid token exists before making authenticated API calls.
+ * If no valid token exists and an active session ID is available,
+ * attempts to refresh the token using the session.
+ *
+ * @throws {SessionSyncRequiredError} If the session needs to be synced (offline session)
+ */
+export declare function ensureValidToken(oxyServices: OxyServices, activeSessionId: string | null | undefined): Promise<void>;
+/**
+ * Options for handling API authentication errors
+ */
+export interface HandleApiErrorOptions {
+    syncSession?: () => Promise<unknown>;
+    activeSessionId?: string | null;
+    oxyServices?: OxyServices;
+}
+/**
+ * Checks if an error is an authentication error (401 or auth-related message)
+ */
+export declare function isAuthenticationError(error: unknown): boolean;
+/**
+ * Wraps an API call with authentication error handling.
+ * On auth failure, optionally attempts to sync the session and retry.
+ *
+ * @throws {AuthenticationFailedError} If authentication fails and cannot be recovered
+ */
+export declare function withAuthErrorHandling<T>(apiCall: () => Promise<T>, options?: HandleApiErrorOptions): Promise<T>;
+/**
+ * Combines token validation and auth error handling for a complete authenticated API call.
+ *
+ * @example
+ * ```ts
+ * return await authenticatedApiCall(
+ *   oxyServices,
+ *   activeSessionId,
+ *   () => oxyServices.updateProfile(updates)
+ * );
+ * ```
+ */
+export declare function authenticatedApiCall<T>(oxyServices: OxyServices, activeSessionId: string | null | undefined, apiCall: () => Promise<T>, syncSession?: () => Promise<unknown>): Promise<T>;

package/dist/types/utils/platform.d.ts

@@ -27,6 +27,14 @@ export declare function isIOS(): boolean;
  * Check if running on Android
  */
 export declare function isAndroid(): boolean;
+/**
+ * Check if running in React Native
+ */
+export declare function isReactNative(): boolean;
+/**
+ * Check if running in Node.js
+ */
+export declare function isNodeJS(): boolean;
 /**
  * Set the platform OS explicitly
  * Called by React Native entry point to register the platform

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxyhq/core",
-  "version": "1.5.0",
+  "version": "1.6.1",
   "description": "OxyHQ SDK Foundation — API client, authentication, cryptographic identity, and shared utilities",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",

package/src/AuthManager.ts

@@ -308,7 +308,7 @@ export class AuthManager {
           // Use session-based token endpoint which handles auto-refresh server-side
           const response = await httpService.request<{ accessToken: string; expiresAt: string }>({
             method: 'GET',
-            url: `/api/session/token/${sessionId}`,
+            url: `/session/token/${sessionId}`,
             cache: false,
             retry: false,
           });
@@ -366,6 +366,19 @@ export class AuthManager {
       this.refreshTimer = null;
     }
 
+    // Invalidate current session on the server (best-effort)
+    try {
+      const sessionJson = await this.storage.getItem(STORAGE_KEYS.SESSION);
+      if (sessionJson) {
+        const session = JSON.parse(sessionJson);
+        if (session.sessionId && typeof (this.oxyServices as any).logoutSession === 'function') {
+          await (this.oxyServices as any).logoutSession(session.sessionId);
+        }
+      }
+    } catch {
+      // Best-effort: don't block local signout on network failure
+    }
+
     // Revoke FedCM credential if supported
     try {
       const services = this.oxyServices as OxyServicesWithFedCM;

package/src/HttpService.ts

@@ -54,27 +54,21 @@ interface RequestConfig extends RequestOptions {
   params?: Record<string, unknown>;
   /** @internal Used to prevent infinite auth retry loops */
   _isAuthRetry?: boolean;
+  /** @internal Used to prevent infinite CSRF retry loops */
+  _isCsrfRetry?: boolean;
 }
 
 /**
- * Token store for authentication (singleton)
+ * Token store for authentication (instance-based)
+ * Each HttpService gets its own TokenStore to prevent conflicts
+ * when multiple OxyServices instances coexist server-side.
  */
 class TokenStore {
-  private static instance: TokenStore;
   private accessToken: string | null = null;
   private refreshToken: string | null = null;
   private csrfToken: string | null = null;
   private csrfTokenFetchPromise: Promise<string | null> | null = null;
 
-  private constructor() {}
-
-  static getInstance(): TokenStore {
-    if (!TokenStore.instance) {
-      TokenStore.instance = new TokenStore();
-    }
-    return TokenStore.instance;
-  }
-
   setTokens(accessToken: string, refreshToken = ''): void {
     this.accessToken = accessToken;
     this.refreshToken = refreshToken;
@@ -134,6 +128,7 @@ export class HttpService {
   private logger: SimpleLogger;
   private config: OxyConfig;
   private tokenRefreshPromise: Promise<string | null> | null = null;
+  private tokenRefreshCooldownUntil: number = 0;
   private _onTokenRefreshed: ((accessToken: string) => void) | null = null;
 
   // Performance monitoring
@@ -149,7 +144,7 @@ export class HttpService {
   constructor(config: OxyConfig) {
     this.config = config;
     this.baseURL = config.baseURL;
-    this.tokenStore = TokenStore.getInstance();
+    this.tokenStore = new TokenStore();
     
     this.logger = new SimpleLogger(
       config.enableLogging || false,
@@ -346,6 +341,20 @@ export class HttpService {
             this.tokenStore.clearTokens();
           }
 
+          // On 403 with CSRF error, clear cached token and retry once
+          if (response.status === 403 && !config._isCsrfRetry) {
+            try {
+              const clonedResponse = response.clone();
+              const errBody = await clonedResponse.json() as { code?: string } | null;
+              if (errBody?.code === 'CSRF_TOKEN_INVALID' || errBody?.code === 'CSRF_TOKEN_MISSING') {
+                this.tokenStore.clearCsrfToken();
+                return this.request<T>({ ...config, _isCsrfRetry: true, retry: false });
+              }
+            } catch {
+              // Failed to parse error body — not a CSRF error
+            }
+          }
+
           // Try to parse error response (handle empty/malformed JSON)
           let errorMessage = `HTTP ${response.status}: ${response.statusText}`;
           const contentType = response.headers.get('content-type');
@@ -518,52 +527,58 @@ export class HttpService {
     }
 
     const fetchPromise = (async () => {
-      try {
-        if (isDev()) console.log('[HttpService] Fetching CSRF token from:', `${this.baseURL}/api/csrf-token`);
+      const maxAttempts = 2;
+      for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+        try {
+          if (isDev()) console.log('[HttpService] Fetching CSRF token from:', `${this.baseURL}/csrf-token`, `(attempt ${attempt})`);
 
-        // Use AbortController for timeout (more compatible than AbortSignal.timeout)
-        const controller = new AbortController();
-        const timeoutId = setTimeout(() => controller.abort(), 5000);
+          // Use AbortController for timeout (more compatible than AbortSignal.timeout)
+          const controller = new AbortController();
+          const timeoutId = setTimeout(() => controller.abort(), 5000);
 
-        const response = await fetch(`${this.baseURL}/api/csrf-token`, {
-          method: 'GET',
-          headers: { 'Accept': 'application/json' },
-          credentials: 'include', // Required to receive and send cookies
-          signal: controller.signal,
-        });
+          const response = await fetch(`${this.baseURL}/csrf-token`, {
+            method: 'GET',
+            headers: { 'Accept': 'application/json' },
+            credentials: 'include', // Required to receive and send cookies
+            signal: controller.signal,
+          });
 
-        clearTimeout(timeoutId);
+          clearTimeout(timeoutId);
 
-        if (isDev()) console.log('[HttpService] CSRF fetch response:', response.status, response.ok);
+          if (isDev()) console.log('[HttpService] CSRF fetch response:', response.status, response.ok);
 
-        if (response.ok) {
-          const data = await response.json() as { csrfToken?: string };
-          if (isDev()) console.log('[HttpService] CSRF response data:', data);
-          const token = data.csrfToken || null;
-          this.tokenStore.setCsrfToken(token);
-          this.logger.debug('CSRF token fetched');
-          return token;
-        }
+          if (response.ok) {
+            const data = await response.json() as { csrfToken?: string };
+            if (isDev()) console.log('[HttpService] CSRF response data:', data);
+            const token = data.csrfToken || null;
+            this.tokenStore.setCsrfToken(token);
+            this.logger.debug('CSRF token fetched');
+            return token;
+          }
 
-        // Also check response header for CSRF token
-        const headerToken = response.headers.get('X-CSRF-Token');
-        if (headerToken) {
-          this.tokenStore.setCsrfToken(headerToken);
-          this.logger.debug('CSRF token from header');
-          return headerToken;
-        }
+          // Also check response header for CSRF token
+          const headerToken = response.headers.get('X-CSRF-Token');
+          if (headerToken) {
+            this.tokenStore.setCsrfToken(headerToken);
+            this.logger.debug('CSRF token from header');
+            return headerToken;
+          }
 
-        if (isDev()) console.log('[HttpService] CSRF fetch failed with status:', response.status);
-        this.logger.warn('Failed to fetch CSRF token:', response.status);
-        return null;
-      } catch (error) {
-        if (isDev()) console.log('[HttpService] CSRF fetch error:', error);
-        this.logger.warn('CSRF token fetch error:', error);
-        return null;
-      } finally {
-        this.tokenStore.setCsrfTokenFetchPromise(null);
+          if (isDev()) console.log('[HttpService] CSRF fetch failed with status:', response.status);
+          this.logger.warn('Failed to fetch CSRF token:', response.status);
+        } catch (error) {
+          if (isDev()) console.log('[HttpService] CSRF fetch error:', error);
+          this.logger.warn('CSRF token fetch error:', error);
+        }
+        // Wait before retry (500ms)
+        if (attempt < maxAttempts) {
+          await new Promise(resolve => setTimeout(resolve, 500));
+        }
       }
-    })();
+      return null;
+    })().finally(() => {
+      this.tokenStore.setCsrfTokenFetchPromise(null);
+    });
 
     this.tokenStore.setCsrfTokenFetchPromise(fetchPromise);
     return fetchPromise;
@@ -584,16 +599,23 @@ export class HttpService {
 
       // If token expires in less than 60 seconds, refresh it
       if (decoded.exp && decoded.exp - currentTime < 60 && decoded.sessionId) {
-        // Deduplicate concurrent refresh attempts
-        if (!this.tokenRefreshPromise) {
-          this.tokenRefreshPromise = this._refreshTokenFromSession(decoded.sessionId);
+        // Skip if we recently failed a refresh (5s cooldown to prevent storms)
+        if (Date.now() < this.tokenRefreshCooldownUntil) {
+          return `Bearer ${accessToken}`;
         }
-        try {
-          const result = await this.tokenRefreshPromise;
-          if (result) return result;
-        } finally {
-          this.tokenRefreshPromise = null;
+        // Deduplicate concurrent refresh attempts. The promise is shared
+        // across all concurrent callers and cleared only after it settles,
+        // so every awaiter receives the same result.
+        if (!this.tokenRefreshPromise) {
+          this.tokenRefreshPromise = this._refreshTokenFromSession(decoded.sessionId)
+            .then((result) => {
+              if (!result) this.tokenRefreshCooldownUntil = Date.now() + 5000;
+              return result;
+            })
+            .finally(() => { this.tokenRefreshPromise = null; });
         }
+        const result = await this.tokenRefreshPromise;
+        if (result) return result;
       }
 
       return `Bearer ${accessToken}`;
@@ -605,7 +627,7 @@ export class HttpService {
 
   private async _refreshTokenFromSession(sessionId: string): Promise<string | null> {
     try {
-      const refreshUrl = `${this.baseURL}/api/session/token/${sessionId}`;
+      const refreshUrl = `${this.baseURL}/session/token/${sessionId}`;
       const response = await fetch(refreshUrl, {
         method: 'GET',
         headers: { 'Accept': 'application/json' },
@@ -778,14 +800,10 @@ export class HttpService {
     return { ...this.requestMetrics };
   }
 
-  // Test-only utility
-  static __resetTokensForTests(): void {
-    try {
-      TokenStore.getInstance().clearTokens();
-    } catch (error) {
-      // Silently fail in test cleanup - this is expected behavior
-      // TokenStore might not be initialized in some test scenarios
-    }
+  // Test-only utility — clears tokens on this instance
+  __resetTokensForTests(): void {
+    this.tokenStore.clearTokens();
+    this.tokenStore.clearCsrfToken();
   }
 }
 

package/src/OxyServices.base.ts

@@ -41,9 +41,10 @@ export class OxyServicesBase {
     this.httpService = new HttpService(config);
   }
 
-  // Test-only utility to reset global tokens between jest tests
-  static __resetTokensForTests(): void {
-    HttpService.__resetTokensForTests();
+  // Test-only utility to reset tokens on this instance between jest tests
+  // Note: tokens are now per-instance, so create new instances in tests for isolation
+  __resetTokensForTests(): void {
+    this.httpService.__resetTokensForTests();
   }
 
   /**
@@ -304,7 +305,7 @@ export class OxyServicesBase {
     }
 
     try {
-      const res = await this.makeRequest<{ valid: boolean }>('GET', '/api/auth/validate', undefined, {
+      const res = await this.makeRequest<{ valid: boolean }>('GET', '/auth/validate', undefined, {
         cache: false,
         retry: false,
       });

package/src/crypto/keyManager.ts

@@ -7,7 +7,7 @@
 
 import { ec as EC } from 'elliptic';
 import type { ECKeyPair } from 'elliptic';
-import { isWeb, isIOS, isAndroid } from '../utils/platform';
+import { isWeb, isIOS, isAndroid, isReactNative, isNodeJS } from '../utils/platform';
 import { logger } from '../utils/loggerUtils';
 import { isDev } from '../shared/utils/debugUtils';
 
@@ -64,20 +64,6 @@ async function initSecureStore(): Promise<typeof import('expo-secure-store')> {
   return SecureStore;
 }
 
-/**
- * Check if we're in a React Native environment
- */
-function isReactNative(): boolean {
-  return typeof navigator !== 'undefined' && navigator.product === 'ReactNative';
-}
-
-/**
- * Check if we're in a Node.js environment
- */
-function isNodeJS(): boolean {
-  return typeof process !== 'undefined' && process.versions != null && process.versions.node != null;
-}
-
 /**
  * Check if we're on web platform
  * Identity storage is only available on native platforms (iOS/Android)

package/src/crypto/signatureService.ts

@@ -7,26 +7,13 @@
 
 import { ec as EC } from 'elliptic';
 import { KeyManager } from './keyManager';
+import { isReactNative, isNodeJS } from '../utils/platform';
 
 // Lazy import for expo-crypto
 let ExpoCrypto: typeof import('expo-crypto') | null = null;
 
 const ec = new EC('secp256k1');
 
-/**
- * Check if we're in a React Native environment
- */
-function isReactNative(): boolean {
-  return typeof navigator !== 'undefined' && navigator.product === 'ReactNative';
-}
-
-/**
- * Check if we're in a Node.js environment
- */
-function isNodeJS(): boolean {
-  return typeof process !== 'undefined' && process.versions != null && process.versions.node != null;
-}
-
 /**
  * Initialize expo-crypto module
  */
@@ -55,9 +42,7 @@ async function sha256(message: string): Promise<string> {
   // In Node.js, use Node's crypto module
   if (isNodeJS()) {
     try {
-      // eslint-disable-next-line @typescript-eslint/no-implied-eval
-      const getCrypto = new Function('return require("crypto")');
-      const nodeCrypto = getCrypto();
+      const nodeCrypto = await import('crypto');
       return nodeCrypto.createHash('sha256').update(message).digest('hex');
     } catch {
       // Fall through to Web Crypto API

package/src/index.ts

@@ -123,6 +123,17 @@ export {
 // --- i18n ---
 export { translate } from './i18n';
 
+// --- Auth Helpers ---
+export {
+  SessionSyncRequiredError,
+  AuthenticationFailedError,
+  ensureValidToken,
+  isAuthenticationError,
+  withAuthErrorHandling,
+  authenticatedApiCall,
+} from './utils/authHelpers';
+export type { HandleApiErrorOptions } from './utils/authHelpers';
+
 // --- Session Utilities ---
 export { mergeSessions, normalizeAndSortSessions, sessionsArraysEqual } from './utils/sessionUtils';
 

package/src/mixins/OxyServices.analytics.ts

@@ -19,7 +19,7 @@ export function OxyServicesAnalyticsMixin<T extends typeof OxyServicesBase>(Base
      */
     async trackEvent(eventName: string, properties?: Record<string, any>): Promise<void> {
       try {
-        await this.makeRequest('POST', '/api/analytics/events', {
+        await this.makeRequest('POST', '/analytics/events', {
           event: eventName,
           properties
         }, { cache: false, retry: false }); // Don't retry analytics events
@@ -40,7 +40,7 @@ export function OxyServicesAnalyticsMixin<T extends typeof OxyServicesBase>(Base
         if (startDate) params.startDate = startDate;
         if (endDate) params.endDate = endDate;
         
-        return await this.makeRequest('GET', '/api/analytics', params, {
+        return await this.makeRequest('GET', '/analytics', params, {
           cache: true,
           cacheTTL: CACHE_TIMES.LONG,
         });