@oxy.so/core 4.5.0-oxy-one.0 → 4.5.0

package/src/utils/asyncUtils.ts

@@ -88,7 +88,7 @@ export async function retryAsync<T>(
   operation: () => Promise<T>,
   maxRetriesOrOptions: number | RetryOptions = 3,
   baseDelayArg = 1000,
-  shouldRetryArg?: (error: unknown) => boolean
+  shouldRetryArg?: (error: unknown) => boolean,
 ): Promise<T> {
   // An options-object overload rather than a fifth positional parameter:
   // `retryOnError` below and other in-tree callers pass positionally, and a
@@ -163,7 +163,7 @@ export async function retryAsync<T>(
         break;
       }
 
-      await new Promise(resolve => setTimeout(resolve, delay));
+      await new Promise((resolve) => setTimeout(resolve, delay));
     }
   }
 

package/src/utils/authHelpers.ts

@@ -36,7 +36,7 @@ export class AuthenticationFailedError extends Error {
 export async function ensureValidToken(
   oxyServices: OxyServices,
   _activeSessionId: string | null | undefined,
-  syncSession?: () => Promise<unknown>
+  syncSession?: () => Promise<unknown>,
 ): Promise<void> {
   if (oxyServices.session.isAuthenticated) {
     return;
@@ -51,7 +51,10 @@ export async function ensureValidToken(
     } catch (syncError) {
       const errorMessage = syncError instanceof Error ? syncError.message : String(syncError);
 
-      if (errorMessage.includes('AUTH_REQUIRED_OFFLINE_SESSION') || errorMessage.includes('offline')) {
+      if (
+        errorMessage.includes('AUTH_REQUIRED_OFFLINE_SESSION') ||
+        errorMessage.includes('offline')
+      ) {
         throw new SessionSyncRequiredError();
       }
 
@@ -59,7 +62,9 @@ export async function ensureValidToken(
     }
   }
 
-  throw new SessionSyncRequiredError('No active access token is available. Sync the session before calling authenticated APIs.');
+  throw new SessionSyncRequiredError(
+    'No active access token is available. Sync the session before calling authenticated APIs.',
+  );
 }
 
 /**
@@ -98,7 +103,7 @@ export function isAuthenticationError(error: unknown): boolean {
  */
 export async function withAuthErrorHandling<T>(
   apiCall: () => Promise<T>,
-  options?: HandleApiErrorOptions
+  options?: HandleApiErrorOptions,
 ): Promise<T> {
   try {
     return await apiCall();
@@ -136,7 +141,7 @@ export async function authenticatedApiCall<T>(
   oxyServices: OxyServices,
   activeSessionId: string | null | undefined,
   apiCall: () => Promise<T>,
-  syncSession?: () => Promise<unknown>
+  syncSession?: () => Promise<unknown>,
 ): Promise<T> {
   await ensureValidToken(oxyServices, activeSessionId, syncSession);
 

package/src/utils/avatarUtils.ts

@@ -2,7 +2,9 @@ import { logger } from '../logger';
 
 /** What `updateAvatarVisibility` needs of a client: `oxy.assets.setVisibility`. */
 export interface AssetVisibilityService {
-  assets: { setVisibility(fileId: string, visibility: 'private' | 'public' | 'unlisted'): Promise<unknown> };
+  assets: {
+    setVisibility(fileId: string, visibility: 'private' | 'public' | 'unlisted'): Promise<unknown>;
+  };
 }
 
 /**
@@ -16,7 +18,7 @@ export interface AssetVisibilityService {
 export async function updateAvatarVisibility(
   fileId: string | undefined,
   oxyServices: AssetVisibilityService,
-  contextName = 'AvatarUtils'
+  contextName = 'AvatarUtils',
 ): Promise<void> {
   if (!fileId || fileId.startsWith('temp-')) {
     return;
@@ -26,11 +28,14 @@ export async function updateAvatarVisibility(
     await oxyServices.assets.setVisibility(fileId, 'public');
   } catch (visError: unknown) {
     // 404 is expected when asset doesn't exist yet — skip logging
-    const status = (visError instanceof Error && 'status' in visError)
-      ? (visError as Error & { status: number }).status
-      : undefined;
+    const status =
+      visError instanceof Error && 'status' in visError
+        ? (visError as Error & { status: number }).status
+        : undefined;
     if (status !== 404) {
-      logger.error(`[${contextName}] Failed to update avatar visibility for ${fileId}`, visError, { component: contextName });
+      logger.error(`[${contextName}] Failed to update avatar visibility for ${fileId}`, visError, {
+        component: contextName,
+      });
     }
   }
 }

package/src/utils/cache.ts

@@ -1,6 +1,6 @@
 /**
  * Centralized cache utility with TTL support
- * 
+ *
  * This is a production-ready cache implementation used across the codebase
  * for consistent caching behavior and performance optimization.
  */
@@ -26,26 +26,26 @@ export interface CacheStats {
 
 /**
  * TTL-based cache implementation
- * 
+ *
  * Features:
  * - Automatic expiration based on TTL
  * - Manual cleanup of expired entries
  * - Statistics tracking (hits, misses, hit rate)
  * - Type-safe generic interface
- * 
+ *
  * @example
  * ```typescript
  * const cache = new TTLCache<string>(5 * 60 * 1000); // 5 minutes
- * 
+ *
  * // Set with default TTL
  * cache.set('key', 'value');
- * 
+ *
  * // Set with custom TTL
  * cache.set('key', 'value', 10 * 60 * 1000); // 10 minutes
- * 
+ *
  * // Get value
  * const value = cache.get('key');
- * 
+ *
  * // Get statistics
  * const stats = cache.getStats();
  * ```
@@ -244,7 +244,7 @@ export class TTLCache<T> {
 
 /**
  * Create a TTL cache instance (convenience function)
- * 
+ *
  * @example
  * ```typescript
  * const cache = createCache<string>(5 * 60 * 1000);
@@ -272,7 +272,7 @@ export function registerCacheForCleanup(cache: TTLCache<unknown>): void {
 
 /** Empty registered caches need no timer; importing a client must stay inert. */
 function updateCleanupInterval(): void {
-  const hasEntries = [...activeCaches].some(cache => cache.size() > 0);
+  const hasEntries = [...activeCaches].some((cache) => cache.size() > 0);
   if (!hasEntries) {
     if (cleanupInterval) clearInterval(cleanupInterval);
     cleanupInterval = null;
@@ -303,4 +303,3 @@ export function stopAllCleanupIntervals(): void {
   }
   activeCaches.clear();
 }
-

package/src/utils/cacheKey.ts

@@ -85,5 +85,9 @@ export function computeIdentityTag(accessToken: string | null): string {
   const decoded = decodeTokenClaims(accessToken);
   // An undecodable token is still partitioned away from anon and from other
   // tokens via a hash — never silently ANON_IDENTITY.
-  return (decoded?.userId as string | undefined) || (decoded?.id as string | undefined) || `t${fnv1a32(accessToken)}`;
+  return (
+    (decoded?.userId as string | undefined) ||
+    (decoded?.id as string | undefined) ||
+    `t${fnv1a32(accessToken)}`
+  );
 }

package/src/utils/coldBoot.ts

@@ -141,9 +141,7 @@ export interface RunColdBootOptions<S> {
  *      - `{ kind: 'skip' }` → continue.
  *   4. After the loop with no winner → `{ kind: 'unauthenticated' }`.
  */
-export async function runColdBoot<S>(
-  options: RunColdBootOptions<S>
-): Promise<ColdBootOutcome<S>> {
+export async function runColdBoot<S>(options: RunColdBootOptions<S>): Promise<ColdBootOutcome<S>> {
   const { steps, onStepError, overallDeadlineMs, onStepDeadline } = options;
 
   // Arm the optional overall deadline. The budget is SHARED across the whole

package/src/utils/commonsDelivery.ts

@@ -108,10 +108,7 @@ export function selectCommonsDelivery(facts: CommonsDeliveryFacts): CommonsDeliv
  * `delivered: false` with `targets > 0`, which must NOT park the user on
  * "check your phone".
  */
-export function pushTargetsFromDelivery(result: {
-  delivered: boolean;
-  targets: number;
-}): number {
+export function pushTargetsFromDelivery(result: { delivered: boolean; targets: number }): number {
   return result.delivered ? result.targets : 0;
 }
 

package/src/utils/deviceManager.ts

@@ -30,14 +30,14 @@ export interface StoredDeviceInfo {
 // biome-ignore lint/complexity/noStaticOnlyClass: a public, static-only API surface (`X.method()`) that consumers and tests call and spy on by name.
 export class DeviceManager {
   private static DEVICE_KEY = 'oxy_device_info';
-  
+
   /**
    * Check if we're in React Native environment
    */
   private static isReactNative(): boolean {
     return typeof navigator !== 'undefined' && navigator.product === 'ReactNative';
   }
-  
+
   /**
    * Get appropriate storage for the platform
    */
@@ -67,11 +67,11 @@ export class DeviceManager {
       return {
         getItem: async (key: string) => localStorage.getItem(key),
         setItem: async (key: string, value: string) => localStorage.setItem(key, value),
-        removeItem: async (key: string) => localStorage.removeItem(key)
+        removeItem: async (key: string) => localStorage.removeItem(key),
       };
     }
   }
-  
+
   /**
    * Get or create device fingerprint for current device
    */
@@ -80,7 +80,8 @@ export class DeviceManager {
       userAgent: typeof navigator !== 'undefined' ? navigator.userAgent : 'unknown',
       platform: typeof navigator !== 'undefined' ? navigator.platform : 'unknown',
       language: typeof navigator !== 'undefined' ? navigator.language : undefined,
-      timezone: typeof Intl !== 'undefined' ? Intl.DateTimeFormat().resolvedOptions().timeZone : undefined,
+      timezone:
+        typeof Intl !== 'undefined' ? Intl.DateTimeFormat().resolvedOptions().timeZone : undefined,
     };
 
     // Add screen info if available
@@ -88,7 +89,7 @@ export class DeviceManager {
       fingerprint.screen = {
         width: screen.width,
         height: screen.height,
-        colorDepth: screen.colorDepth
+        colorDepth: screen.colorDepth,
       };
     }
 
@@ -102,17 +103,17 @@ export class DeviceManager {
     try {
       const storage = await DeviceManager.getStorage();
       const stored = await storage.getItem(DeviceManager.DEVICE_KEY);
-      
+
       if (stored) {
         const deviceInfo: StoredDeviceInfo = JSON.parse(stored);
-        
+
         // Update last used timestamp
         deviceInfo.lastUsed = new Date().toISOString();
         await DeviceManager.saveDeviceInfo(deviceInfo);
-        
+
         return deviceInfo;
       }
-      
+
       // Create new device info
       return await DeviceManager.createNewDeviceInfo();
     } catch (error) {
@@ -129,7 +130,7 @@ export class DeviceManager {
       deviceId: DeviceManager.generateDeviceId(),
       fingerprint: JSON.stringify(DeviceManager.getDeviceFingerprint()),
       createdAt: new Date().toISOString(),
-      lastUsed: new Date().toISOString()
+      lastUsed: new Date().toISOString(),
     };
 
     await DeviceManager.saveDeviceInfo(deviceInfo);
@@ -180,7 +181,7 @@ export class DeviceManager {
     if (typeof crypto !== 'undefined' && crypto.getRandomValues) {
       const array = new Uint8Array(32);
       crypto.getRandomValues(array);
-      return Array.from(array, byte => byte.toString(16).padStart(2, '0')).join('');
+      return Array.from(array, (byte) => byte.toString(16).padStart(2, '0')).join('');
     }
     throw new Error('No secure random source available for device ID generation');
   }
@@ -191,14 +192,14 @@ export class DeviceManager {
   static getDefaultDeviceName(): string {
     const fingerprint = DeviceManager.getDeviceFingerprint();
     const platform = (fingerprint.platform || '').toLowerCase();
-    
+
     if (platform.includes('win')) return 'Windows Computer';
     if (platform.includes('mac')) return 'Mac Computer';
     if (platform.includes('linux')) return 'Linux Computer';
     if (platform.includes('iphone')) return 'iPhone';
     if (platform.includes('ipad')) return 'iPad';
     if (platform.includes('android')) return 'Android Device';
-    
+
     return 'Unknown Device';
   }
 }

package/src/utils/errorUtils.ts

@@ -14,23 +14,23 @@ export const ErrorCodes = {
   FORBIDDEN: 'FORBIDDEN',
   INVALID_TOKEN: 'INVALID_TOKEN',
   MISSING_TOKEN: 'MISSING_TOKEN',
-  
+
   // Validation errors
   VALIDATION_ERROR: 'VALIDATION_ERROR',
   BAD_REQUEST: 'BAD_REQUEST',
   MISSING_PARAMETER: 'MISSING_PARAMETER',
   INVALID_FORMAT: 'INVALID_FORMAT',
-  
+
   // Resource errors
   NOT_FOUND: 'NOT_FOUND',
   ALREADY_EXISTS: 'ALREADY_EXISTS',
   CONFLICT: 'CONFLICT',
-  
+
   // Server errors
   INTERNAL_ERROR: 'INTERNAL_ERROR',
   SERVICE_UNAVAILABLE: 'SERVICE_UNAVAILABLE',
   TIMEOUT: 'TIMEOUT',
-  
+
   // Network errors
   NETWORK_ERROR: 'NETWORK_ERROR',
   CONNECTION_FAILED: 'CONNECTION_FAILED',
@@ -47,7 +47,7 @@ export const ErrorCodes = {
    * nothing may retry it. See `retryAsync`'s default predicate, which refuses
    * this code specifically.
    */
-  CANCELLED: 'CANCELLED'
+  CANCELLED: 'CANCELLED',
 } as const;
 
 /**
@@ -61,22 +61,22 @@ export const ErrorCodes = {
  * Narrow a caught value with {@link isHttpRequestError} instead of asserting.
  */
 export interface HttpRequestError extends Error {
-    /** HTTP status of the failed response. */
+  /** HTTP status of the failed response. */
+  status: number;
+  /** Machine-readable code the server sent, when it sent one. */
+  code?: string;
+  /** Structured error detail the server sent, when it sent an object. */
+  details?: Record<string, unknown>;
+  /**
+   * Present on errors thrown directly by `HttpService`. `data` is the parsed
+   * JSON error body verbatim — the escape hatch for any server field the SDK
+   * does not lift onto `code`/`details`.
+   */
+  response?: {
     status: number;
-    /** Machine-readable code the server sent, when it sent one. */
-    code?: string;
-    /** Structured error detail the server sent, when it sent an object. */
-    details?: Record<string, unknown>;
-    /**
-     * Present on errors thrown directly by `HttpService`. `data` is the parsed
-     * JSON error body verbatim — the escape hatch for any server field the SDK
-     * does not lift onto `code`/`details`.
-     */
-    response?: {
-        status: number;
-        statusText: string;
-        data?: unknown;
-    };
+    statusText: string;
+    data?: unknown;
+  };
 }
 
 /**
@@ -87,26 +87,26 @@ export interface HttpRequestError extends Error {
  * first if you need one normalized.
  */
 export function isHttpRequestError(value: unknown): value is HttpRequestError {
-    if (!(value instanceof Error)) {
-        return false;
-    }
-    return typeof (value as Partial<HttpRequestError>).status === 'number';
+  if (!(value instanceof Error)) {
+    return false;
+  }
+  return typeof (value as Partial<HttpRequestError>).status === 'number';
 }
 
 /**
  * The fields {@link parseHttpErrorBody} lifts off a parsed error response body.
  */
 export interface ParsedHttpErrorBody {
-    message?: string;
-    code?: string;
-    details?: Record<string, unknown>;
+  message?: string;
+  code?: string;
+  details?: Record<string, unknown>;
 }
 
 const isPlainRecord = (value: unknown): value is Record<string, unknown> =>
-    typeof value === 'object' && value !== null && !Array.isArray(value);
+  typeof value === 'object' && value !== null && !Array.isArray(value);
 
 const nonEmptyString = (value: unknown): string | undefined =>
-    typeof value === 'string' && value.trim().length > 0 ? value : undefined;
+  typeof value === 'string' && value.trim().length > 0 ? value : undefined;
 
 /**
  * Extract `message` / `code` / `details` from a parsed HTTP error response body.
@@ -131,27 +131,27 @@ const nonEmptyString = (value: unknown): string | undefined =>
  * its status-based fallback message. Total function: never throws.
  */
 export function parseHttpErrorBody(body: unknown): ParsedHttpErrorBody {
-    if (!isPlainRecord(body)) {
-        return {};
-    }
+  if (!isPlainRecord(body)) {
+    return {};
+  }
 
-    const nested = isPlainRecord(body.error) ? body.error : undefined;
-    const errorString = nonEmptyString(body.error);
-    // A sibling that proves the top-level `error` is a CODE rather than prose.
-    const siblingMessage = nonEmptyString(body.message) ?? nonEmptyString(body.error_description);
-
-    return {
-        message: siblingMessage ?? (nested ? nonEmptyString(nested.message) : errorString),
-        code:
-            (nested ? nonEmptyString(nested.code) : undefined) ??
-            nonEmptyString(body.code) ??
-            (siblingMessage ? errorString : undefined),
-        details: isPlainRecord(body.details)
-            ? body.details
-            : nested && isPlainRecord(nested.details)
-                ? nested.details
-                : undefined,
-    };
+  const nested = isPlainRecord(body.error) ? body.error : undefined;
+  const errorString = nonEmptyString(body.error);
+  // A sibling that proves the top-level `error` is a CODE rather than prose.
+  const siblingMessage = nonEmptyString(body.message) ?? nonEmptyString(body.error_description);
+
+  return {
+    message: siblingMessage ?? (nested ? nonEmptyString(nested.message) : errorString),
+    code:
+      (nested ? nonEmptyString(nested.code) : undefined) ??
+      nonEmptyString(body.code) ??
+      (siblingMessage ? errorString : undefined),
+    details: isPlainRecord(body.details)
+      ? body.details
+      : nested && isPlainRecord(nested.details)
+        ? nested.details
+        : undefined,
+  };
 }
 
 /**
@@ -161,13 +161,13 @@ export function createApiError(
   message: string,
   code: string = ErrorCodes.INTERNAL_ERROR,
   status = 500,
-  details?: Record<string, unknown>
+  details?: Record<string, unknown>,
 ): ApiError {
   return {
     message,
     code,
     status,
-    details
+    details,
   };
 }
 
@@ -251,28 +251,24 @@ export function handleHttpError(error: unknown): ApiError {
   // anywhere else, and it stays TIMEOUT: a caller that never passed a signal
   // cannot have cancelled anything.
   if (isAbortLike(error)) {
-    return createApiError(
-      'Request timeout or cancelled',
-      ErrorCodes.TIMEOUT,
-      0
-    );
+    return createApiError('Request timeout or cancelled', ErrorCodes.TIMEOUT, 0);
   }
 
   // Handle TypeError (network failures, CORS, etc.)
   if (error instanceof TypeError) {
     // Check if it's a network-related TypeError
-    if (error.message.includes('fetch') || error.message.includes('network') || error.message.includes('Failed to fetch')) {
+    if (
+      error.message.includes('fetch') ||
+      error.message.includes('network') ||
+      error.message.includes('Failed to fetch')
+    ) {
       return createApiError(
         'Network error - failed to connect to server',
         ErrorCodes.NETWORK_ERROR,
-        0
+        0,
       );
     }
-    return createApiError(
-      error.message || 'Network error occurred',
-      ErrorCodes.NETWORK_ERROR,
-      0
-    );
+    return createApiError(error.message || 'Network error occurred', ErrorCodes.NETWORK_ERROR, 0);
   }
 
   // Handle fetch Response errors - check if it has response property with status
@@ -298,7 +294,7 @@ export function handleHttpError(error: unknown): ApiError {
         fetchError.message || `HTTP ${status} error`,
         getErrorCodeFromStatus(status),
         status,
-        isPlainRecord(fetchError.details) ? fetchError.details : undefined
+        isPlainRecord(fetchError.details) ? fetchError.details : undefined,
       );
     }
   }
@@ -307,36 +303,24 @@ export function handleHttpError(error: unknown): ApiError {
   if (error instanceof Error) {
     // Check for common error patterns
     if (error.message.includes('timeout') || error.message.includes('aborted')) {
-      return createApiError(
-        'Request timeout',
-        ErrorCodes.TIMEOUT,
-        0
-      );
+      return createApiError('Request timeout', ErrorCodes.TIMEOUT, 0);
     }
-    
+
     if (error.message.includes('network') || error.message.includes('fetch')) {
-      return createApiError(
-        error.message || 'Network error occurred',
-        ErrorCodes.NETWORK_ERROR,
-        0
-      );
+      return createApiError(error.message || 'Network error occurred', ErrorCodes.NETWORK_ERROR, 0);
     }
 
     return createApiError(
       error.message || 'Unknown error occurred',
       ErrorCodes.INTERNAL_ERROR,
-      500
+      500,
     );
   }
 
   // Handle other errors - ensure we always return a non-empty message
   const errorString = error ? String(error) : '';
   const message = errorString.trim() || 'Unknown error occurred';
-  return createApiError(
-    message,
-    ErrorCodes.INTERNAL_ERROR,
-    500
-  );
+  return createApiError(message, ErrorCodes.INTERNAL_ERROR, 500);
 }
 
 /**
@@ -395,13 +379,13 @@ export function extractErrorStatus(error: unknown): number | undefined {
  * Validate required fields and throw error if missing
  */
 export function validateRequiredFields(data: Record<string, unknown>, fields: string[]): void {
-  const missing = fields.filter(field => !data[field]);
-  
+  const missing = fields.filter((field) => !data[field]);
+
   if (missing.length > 0) {
     throw createApiError(
       `Missing required fields: ${missing.join(', ')}`,
       ErrorCodes.MISSING_PARAMETER,
-      400
+      400,
     );
   }
 }
@@ -423,5 +407,3 @@ export function logError(error: unknown, context?: string): void {
     });
   }
 }
-
-