@oxy.so/core 1.0.0

package/dist/types/shared/utils/colorUtils.d.ts

@@ -0,0 +1,104 @@
+/**
+ * Color Utility Functions
+ *
+ * Consolidated color manipulation utilities used across the OxyServices ecosystem.
+ * These functions work in any JavaScript environment (browser, Node.js, React Native).
+ *
+ * @module shared/utils/colorUtils
+ */
+/**
+ * Darkens a hex color by a specified factor.
+ *
+ * @param color - Hex color string (with or without #)
+ * @param factor - Amount to darken (0-1). Default: 0.6
+ * @returns Darkened hex color string with # prefix
+ *
+ * @example
+ * ```ts
+ * darkenColor('#FF0000', 0.5); // Returns a darker red
+ * darkenColor('FF0000', 0.3);  // Also works without #
+ * ```
+ */
+export declare const darkenColor: (color: string, factor?: number) => string;
+/**
+ * Lightens a hex color by a specified factor.
+ *
+ * @param color - Hex color string (with or without #)
+ * @param factor - Amount to lighten (0-1). Default: 0.3
+ * @returns Lightened hex color string with # prefix
+ *
+ * @example
+ * ```ts
+ * lightenColor('#0000FF', 0.5); // Returns a lighter blue
+ * ```
+ */
+export declare const lightenColor: (color: string, factor?: number) => string;
+/**
+ * Converts a hex color to RGB values.
+ *
+ * @param hex - Hex color string (with or without #)
+ * @returns Object with r, g, b values (0-255)
+ *
+ * @example
+ * ```ts
+ * hexToRgb('#FF5733'); // { r: 255, g: 87, b: 51 }
+ * ```
+ */
+export declare const hexToRgb: (hex: string) => {
+    r: number;
+    g: number;
+    b: number;
+} | null;
+/**
+ * Converts RGB values to a hex color string.
+ *
+ * @param r - Red value (0-255)
+ * @param g - Green value (0-255)
+ * @param b - Blue value (0-255)
+ * @returns Hex color string with # prefix
+ *
+ * @example
+ * ```ts
+ * rgbToHex(255, 87, 51); // '#ff5733'
+ * ```
+ */
+export declare const rgbToHex: (r: number, g: number, b: number) => string;
+/**
+ * Adjusts the opacity of a hex color, returning an rgba string.
+ *
+ * @param hex - Hex color string
+ * @param opacity - Opacity value (0-1)
+ * @returns RGBA color string
+ *
+ * @example
+ * ```ts
+ * withOpacity('#FF0000', 0.5); // 'rgba(255, 0, 0, 0.5)'
+ * ```
+ */
+export declare const withOpacity: (hex: string, opacity: number) => string;
+/**
+ * Checks if a color is considered "light" (for determining text contrast).
+ *
+ * @param hex - Hex color string
+ * @returns true if the color is light, false if dark
+ *
+ * @example
+ * ```ts
+ * isLightColor('#FFFFFF'); // true
+ * isLightColor('#000000'); // false
+ * ```
+ */
+export declare const isLightColor: (hex: string) => boolean;
+/**
+ * Gets a contrasting text color (black or white) for a given background color.
+ *
+ * @param backgroundColor - Hex color string of the background
+ * @returns '#000000' for light backgrounds, '#ffffff' for dark backgrounds
+ *
+ * @example
+ * ```ts
+ * getContrastTextColor('#FFFF00'); // '#000000' (black text on yellow)
+ * getContrastTextColor('#000080'); // '#ffffff' (white text on navy)
+ * ```
+ */
+export declare const getContrastTextColor: (backgroundColor: string) => string;

package/dist/types/shared/utils/errorUtils.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Error Utility Functions
+ *
+ * Consolidated error handling utilities for the OxyServices ecosystem.
+ * These functions help with common error patterns like checking HTTP status codes.
+ *
+ * @module shared/utils/errorUtils
+ */
+/**
+ * Common HTTP status codes used in error checking.
+ */
+export declare const HttpStatus: {
+    readonly BAD_REQUEST: 400;
+    readonly UNAUTHORIZED: 401;
+    readonly FORBIDDEN: 403;
+    readonly NOT_FOUND: 404;
+    readonly CONFLICT: 409;
+    readonly UNPROCESSABLE_ENTITY: 422;
+    readonly TOO_MANY_REQUESTS: 429;
+    readonly INTERNAL_SERVER_ERROR: 500;
+    readonly BAD_GATEWAY: 502;
+    readonly SERVICE_UNAVAILABLE: 503;
+    readonly GATEWAY_TIMEOUT: 504;
+};
+/**
+ * Extracts the HTTP status code from an error object.
+ *
+ * @param error - Any error object
+ * @returns The status code if found, undefined otherwise
+ */
+export declare const getErrorStatus: (error: unknown) => number | undefined;
+/**
+ * Extracts the error message from an error object.
+ *
+ * @param error - Any error object
+ * @param fallback - Fallback message if none found
+ * @returns The error message
+ */
+export declare const getErrorMessage: (error: unknown, fallback?: string) => string;
+/**
+ * Check if an error indicates the user is already registered (HTTP 409 Conflict).
+ *
+ * The backend should always return HTTP 409 for duplicate registrations.
+ *
+ * @param error - Any error object
+ * @returns true if the error is a 409 Conflict
+ */
+export declare const isAlreadyRegisteredError: (error: unknown) => boolean;
+/**
+ * Check if an error is an authentication error (HTTP 401).
+ *
+ * @param error - Any error object
+ * @returns true if the error is a 401 Unauthorized
+ */
+export declare const isUnauthorizedError: (error: unknown) => boolean;
+/**
+ * Check if an error is a forbidden error (HTTP 403).
+ *
+ * @param error - Any error object
+ * @returns true if the error is a 403 Forbidden
+ */
+export declare const isForbiddenError: (error: unknown) => boolean;
+/**
+ * Check if an error is a not found error (HTTP 404).
+ *
+ * @param error - Any error object
+ * @returns true if the error is a 404 Not Found
+ */
+export declare const isNotFoundError: (error: unknown) => boolean;
+/**
+ * Check if an error is a rate limit error (HTTP 429).
+ *
+ * @param error - Any error object
+ * @returns true if the error is a 429 Too Many Requests
+ */
+export declare const isRateLimitError: (error: unknown) => boolean;
+/**
+ * Check if an error is a server error (HTTP 5xx).
+ *
+ * @param error - Any error object
+ * @returns true if the error is a 5xx server error
+ */
+export declare const isServerError: (error: unknown) => boolean;
+/**
+ * Check if an error is a network error (no response received).
+ *
+ * @param error - Any error object
+ * @returns true if the error appears to be a network error
+ */
+export declare const isNetworkError: (error: unknown) => boolean;
+/**
+ * Check if an error is retryable (network errors or 5xx server errors).
+ *
+ * @param error - Any error object
+ * @returns true if the request should be retried
+ */
+export declare const isRetryableError: (error: unknown) => boolean;

package/dist/types/shared/utils/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Shared Utility Functions
+ *
+ * Re-exports all shared utilities for convenient importing.
+ *
+ * @module shared/utils
+ */
+export { darkenColor, lightenColor, hexToRgb, rgbToHex, withOpacity, isLightColor, getContrastTextColor, } from './colorUtils';
+export { normalizeTheme, normalizeColorScheme, getOppositeTheme, systemPrefersDarkMode, getSystemColorScheme, } from './themeUtils';
+export type { ThemeValue } from './themeUtils';
+export { HttpStatus, getErrorStatus, getErrorMessage, isAlreadyRegisteredError, isUnauthorizedError, isForbiddenError, isNotFoundError, isRateLimitError, isServerError, isNetworkError, isRetryableError, } from './errorUtils';
+export { DEFAULT_CIRCUIT_BREAKER_CONFIG, createCircuitBreakerState, calculateBackoffInterval, recordFailure, recordSuccess, shouldAllowRequest, delay, withRetry, } from './networkUtils';
+export type { CircuitBreakerState, CircuitBreakerConfig, } from './networkUtils';

package/dist/types/shared/utils/networkUtils.d.ts

@@ -0,0 +1,139 @@
+/**
+ * Network Utility Functions
+ *
+ * Consolidated network utilities including circuit breaker pattern
+ * and exponential backoff for resilient API calls.
+ *
+ * @module shared/utils/networkUtils
+ */
+/**
+ * State for circuit breaker pattern.
+ */
+export interface CircuitBreakerState {
+    /** Number of consecutive failures */
+    consecutiveFailures: number;
+    /** Current interval between retries (ms) */
+    currentInterval: number;
+    /** Base interval for retries (ms) */
+    baseInterval: number;
+    /** Maximum interval cap (ms) */
+    maxInterval: number;
+    /** Number of failures before circuit opens */
+    maxFailures: number;
+    /** Whether the circuit is currently open (blocking requests) */
+    isOpen?: boolean;
+    /** Timestamp when circuit was opened */
+    openedAt?: number;
+}
+/**
+ * Configuration for circuit breaker.
+ */
+export interface CircuitBreakerConfig {
+    /** Base interval between retries in milliseconds. Default: 10000 (10s) */
+    baseInterval?: number;
+    /** Maximum interval cap in milliseconds. Default: 60000 (60s) */
+    maxInterval?: number;
+    /** Number of consecutive failures before opening circuit. Default: 5 */
+    maxFailures?: number;
+    /** Time to wait before attempting recovery in milliseconds. Default: 30000 (30s) */
+    recoveryTimeout?: number;
+}
+/**
+ * Default circuit breaker configuration.
+ */
+export declare const DEFAULT_CIRCUIT_BREAKER_CONFIG: Required<CircuitBreakerConfig>;
+/**
+ * Creates initial circuit breaker state.
+ *
+ * @param config - Optional custom configuration
+ * @returns Initial circuit breaker state
+ *
+ * @example
+ * ```ts
+ * const state = createCircuitBreakerState({ maxFailures: 3 });
+ * ```
+ */
+export declare const createCircuitBreakerState: (config?: CircuitBreakerConfig) => CircuitBreakerState;
+/**
+ * Calculates next interval using exponential backoff.
+ *
+ * @param state - Current circuit breaker state
+ * @returns Next interval in milliseconds
+ *
+ * @example
+ * ```ts
+ * const nextInterval = calculateBackoffInterval(state);
+ * await delay(nextInterval);
+ * ```
+ */
+export declare const calculateBackoffInterval: (state: CircuitBreakerState) => number;
+/**
+ * Records a failure and updates circuit breaker state.
+ *
+ * @param state - Current circuit breaker state
+ * @returns Updated state after recording failure
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await apiCall();
+ *   state = recordSuccess(state);
+ * } catch (error) {
+ *   state = recordFailure(state);
+ * }
+ * ```
+ */
+export declare const recordFailure: (state: CircuitBreakerState) => CircuitBreakerState;
+/**
+ * Records a success and resets circuit breaker state.
+ *
+ * @param state - Current circuit breaker state
+ * @returns Reset state after successful request
+ */
+export declare const recordSuccess: (state: CircuitBreakerState) => CircuitBreakerState;
+/**
+ * Checks if the circuit breaker should allow a request.
+ *
+ * When the circuit is open, it will only allow requests after
+ * the recovery timeout has passed (half-open state).
+ *
+ * @param state - Current circuit breaker state
+ * @param recoveryTimeout - Time to wait before allowing recovery attempts
+ * @returns true if request should be allowed
+ */
+export declare const shouldAllowRequest: (state: CircuitBreakerState, recoveryTimeout?: number) => boolean;
+/**
+ * Delays execution for a specified duration.
+ *
+ * @param ms - Milliseconds to delay
+ * @returns Promise that resolves after the delay
+ *
+ * @example
+ * ```ts
+ * await delay(1000); // Wait 1 second
+ * ```
+ */
+export declare const delay: (ms: number) => Promise<void>;
+/**
+ * Executes a function with exponential backoff retry.
+ *
+ * @param fn - Async function to execute
+ * @param options - Retry options
+ * @returns Result of the function
+ * @throws Last error if all retries fail
+ *
+ * @example
+ * ```ts
+ * const result = await withRetry(
+ *   () => fetchData(),
+ *   { maxRetries: 3, baseDelay: 1000 }
+ * );
+ * ```
+ */
+export declare const withRetry: <T>(fn: () => Promise<T>, options?: {
+    maxRetries?: number;
+    baseDelay?: number;
+    maxDelay?: number;
+    shouldRetry?: (error: unknown) => boolean;
+    onRetry?: (error: unknown, attempt: number) => void;
+}) => Promise<T>;

package/dist/types/shared/utils/themeUtils.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Theme Utility Functions
+ *
+ * Consolidated theme utilities for normalizing and handling color schemes
+ * across the OxyServices ecosystem.
+ *
+ * @module shared/utils/themeUtils
+ */
+/**
+ * Valid theme values in the Oxy ecosystem.
+ */
+export type ThemeValue = 'light' | 'dark';
+/**
+ * Normalizes a theme value to ensure it's always 'light' or 'dark'.
+ *
+ * @param theme - Theme value (may be 'light' | 'dark' | string | undefined)
+ * @returns Normalized 'light' | 'dark' theme (defaults to 'light')
+ *
+ * @example
+ * ```ts
+ * normalizeTheme('dark');     // 'dark'
+ * normalizeTheme('light');    // 'light'
+ * normalizeTheme('unknown');  // 'light'
+ * normalizeTheme(undefined);  // 'light'
+ * normalizeTheme(null);       // 'light'
+ * ```
+ */
+export declare const normalizeTheme: (theme?: string | null) => ThemeValue;
+/**
+ * Normalizes a color scheme value with optional fallback chain.
+ *
+ * Handles null/undefined cases from React Native's useColorScheme() hook
+ * with a proper fallback chain.
+ *
+ * @param colorScheme - The color scheme from useColorScheme() hook (may be null/undefined)
+ * @param theme - Optional theme prop as fallback
+ * @returns Normalized 'light' | 'dark' color scheme
+ *
+ * @example
+ * ```ts
+ * // In a React Native component:
+ * const systemScheme = useColorScheme(); // might be null
+ * const colorScheme = normalizeColorScheme(systemScheme, props.theme);
+ *
+ * normalizeColorScheme('dark', 'light');      // 'dark'
+ * normalizeColorScheme(null, 'dark');         // 'dark'
+ * normalizeColorScheme(undefined, undefined); // 'light'
+ * ```
+ */
+export declare const normalizeColorScheme: (colorScheme?: string | null, theme?: string) => ThemeValue;
+/**
+ * Gets the opposite theme value.
+ *
+ * @param theme - Current theme value
+ * @returns The opposite theme ('light' → 'dark', 'dark' → 'light')
+ *
+ * @example
+ * ```ts
+ * getOppositeTheme('light'); // 'dark'
+ * getOppositeTheme('dark');  // 'light'
+ * ```
+ */
+export declare const getOppositeTheme: (theme: ThemeValue) => ThemeValue;
+/**
+ * Checks if the system prefers dark mode.
+ *
+ * This function only works in browser environments.
+ * Returns false in non-browser environments (Node.js, React Native).
+ *
+ * @returns true if system prefers dark mode, false otherwise
+ *
+ * @example
+ * ```ts
+ * if (systemPrefersDarkMode()) {
+ *   setTheme('dark');
+ * }
+ * ```
+ */
+export declare const systemPrefersDarkMode: () => boolean;
+/**
+ * Gets the system's preferred color scheme.
+ *
+ * @returns 'dark' if system prefers dark mode, 'light' otherwise
+ *
+ * @example
+ * ```ts
+ * const theme = getSystemColorScheme();
+ * ```
+ */
+export declare const getSystemColorScheme: () => ThemeValue;

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

@@ -0,0 +1,75 @@
+/**
+ * THE enumeration of `OxyServices` GET-cache keys that serve the ACCOUNT FOREST
+ * — the caller's accessible accounts, as lists and as individual detail rows —
+ * and the one sweep that clears them.
+ *
+ * WHY THIS IS NOT A METHOD ON THE ACCOUNTS MIXIN
+ * ---------------------------------------------
+ * `AccountNode.account` is a whole `User`, so a forest read embeds the very
+ * profile the identity reads serve. That makes an IDENTITY write a writer of
+ * these keys too: `updateProfile` edits the caller's own personal account,
+ * which is a row in `GET /accounts` and is its own `GET /accounts/<id>`. Leave
+ * those cached and the account switcher keeps drawing the pre-edit name and
+ * picture for the full TTL, against a perfectly healthy server.
+ *
+ * The mixins compose into one class at runtime but are typed one at a time, so
+ * the user mixin cannot call a method the accounts mixin owns. The key list
+ * therefore lives here, once, and every writer calls {@link
+ * evictOxyAccountForestCache} — exactly like the identity key list in
+ * `identityCacheSweep`, which the accounts mixin already calls for the
+ * mirror-image case (an account write staling the identity reads). The
+ * alternative — a second hand-written copy of these keys in the other mixin —
+ * is the drift that shipped the two stale-profile bugs `identityCacheSweep`
+ * documents.
+ *
+ * WHY THE LIST NEEDS A PREFIX AND THE DETAIL DOES NOT
+ * --------------------------------------------------
+ * `listAccounts({tree?})` keys the flat list as `GET:/accounts` and every
+ * option variant as `GET:/accounts?<query>` (the query string is part of the
+ * URL, hence of the key), and a writer cannot enumerate which variants a caller
+ * has read. The detail key, by contrast, is derivable from the account id the
+ * writer already holds.
+ *
+ * The `GET:/accounts?` prefix matches ONLY the query-string list variants —
+ * never `GET:/accounts/<id>` or its `…/members`, `…/credentials`, `…/children`
+ * sub-resources, which are the accounts mixin's own business and stay there.
+ */
+import type { OxyIdentityCacheEvictor } from './identityCacheSweep';
+/**
+ * The cache-eviction surface of an `OxyServices` instance. Reused from
+ * `identityCacheSweep` rather than re-declared: it is the SDK's one published
+ * name for these two methods, and a second identical interface would be one
+ * more shape to keep in step.
+ */
+export type OxyAccountCacheEvictor = OxyIdentityCacheEvictor;
+/** The cache key `listAccounts()` reads under with no options. */
+export declare const OXY_ACCOUNT_LIST_CACHE_KEY = "GET:/accounts";
+/**
+ * The prefix covering every option-carrying `listAccounts(opts)` variant
+ * (`?tree=true`, …), none of which a writer can enumerate.
+ */
+export declare const OXY_ACCOUNT_LIST_CACHE_QUERY_PREFIX = "GET:/accounts?";
+/**
+ * Prefix covering every per-account sub-resource cache key
+ * (`GET:/accounts/<id>`, `…/members`, `…/credentials`, `…/children`). A
+ * membership mutation on an ancestor must sweep ALL of these, not only the
+ * account named in the path: descendant member rosters embed inherited rows
+ * resolved from that ancestor, and the writer cannot enumerate which descendant
+ * ids a caller has already read. The trailing slash deliberately excludes the
+ * forest list keys (`GET:/accounts`, `GET:/accounts?…`) documented above.
+ */
+export declare const OXY_ACCOUNT_PER_ACCOUNT_CACHE_PREFIX = "GET:/accounts/";
+/**
+ * Build the exact cache key `getAccount(accountId)` reads under.
+ */
+export declare function oxyAccountDetailCacheKey(accountId: string): string;
+/**
+ * Sweep an `OxyServices` GET response cache of the account forest.
+ *
+ * @param oxy       - Anything exposing the SDK's two eviction methods.
+ * @param accountId - The account whose detail row to drop as well. Optional: a
+ *                    writer that changed the SHAPE of the forest rather than one
+ *                    account in it (create, archive, ownership transfer) has no
+ *                    detail row to name, and clears only the lists.
+ */
+export declare function evictOxyAccountForestCache(oxy: OxyAccountCacheEvictor, accountId?: string): void;

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

@@ -0,0 +1,100 @@
+/**
+ * Shared account types and pure helper functions.
+ * Used by the @oxy.so/services account stores (Expo/RN and RN-Web).
+ */
+export interface QuickAccount {
+    sessionId: string;
+    userId?: string;
+    username: string;
+    displayName: string;
+    avatar?: string;
+    avatarUrl?: string;
+    /**
+     * Device-local account slot index, 0..N-1 (Google-style multi-account).
+     * Optional so that pre-multi-account QuickAccounts (sessionId-only) remain
+     * valid; the device session set populates it where available.
+     */
+    authuser?: number;
+    /**
+     * Account's preferred Bloom color preset (e.g. `"blue"`, `"oxy"`). Drives
+     * per-account theming in the account chooser. `null` / `undefined` means
+     * the account has no preference and the base theme should be used.
+     */
+    color?: string | null;
+}
+/** Minimal user shape accepted by display-name helpers. Avoids importing the full User type. */
+export interface DisplayNameUserShape {
+    name?: string | {
+        displayName?: string;
+        first?: string;
+        last?: string;
+        full?: string;
+        [key: string]: unknown;
+    };
+    /** Pre-normalized account-row display name, not the API User DTO field. */
+    displayName?: string;
+    username?: string;
+    publicKey?: string;
+}
+/**
+ * Truncate a long public key for display, e.g. `0x12345678…`.
+ * Falls back to the raw key if it's too short to truncate.
+ */
+export declare const formatPublicKeyHandle: (publicKey: string) => string;
+/**
+ * Resolve a friendly display name for a user.
+ *
+ * Order of preference:
+ *  1. `name.displayName` from the API user contract.
+ *  2. `name.full`, or composed `name.first name.last` for local unsaved shapes.
+ *  3. `name` when passed as a plain string by local non-DTO call sites.
+ *  4. pre-normalized account-row `displayName`.
+ *  5. `username`
+ *  6. `Account 0x12345678…` (derived from publicKey, when present)
+ *  7. Translated fallback (e.g. "Unnamed")
+ *
+ * The translation key `common.unnamed` is used for the final fallback. If the
+ * caller does not pass a locale, the default English translation is used.
+ */
+export declare const getAccountDisplayName: (user: DisplayNameUserShape | null | undefined, locale?: string) => string;
+/**
+ * Resolve a `@handle` style identifier for a user.
+ *
+ * Returns the bare username when present (without the `@`), otherwise a
+ * truncated public-key handle (`0x12345678…`), or `undefined` when neither is
+ * available — callers can decide whether to hide the line entirely.
+ */
+export declare const getAccountFallbackHandle: (user: DisplayNameUserShape | null | undefined) => string | undefined;
+/**
+ * Build an ordered array of QuickAccounts from a map and order list.
+ */
+export declare const buildAccountsArray: (accounts: Record<string, QuickAccount>, order: string[]) => QuickAccount[];
+/**
+ * Create a QuickAccount from user data returned by the API.
+ *
+ * @param sessionId - Session identifier
+ * @param userData - Raw user object from the API
+ * @param existingAccount - Previously cached account (to preserve avatarUrl if unchanged)
+ * @param getFileDownloadUrl - Function to generate avatar download URL from file ID
+ */
+export declare const createQuickAccount: (sessionId: string, userData: {
+    name?: string | {
+        displayName?: string;
+        full?: string;
+        first?: string;
+        last?: string;
+    };
+    username?: string;
+    publicKey?: string;
+    id?: string;
+    _id?: {
+        toString(): string;
+    } | string;
+    avatar?: string | null;
+}, existingAccount?: QuickAccount, getFileDownloadUrl?: (fileId: string, variant: string) => string) => QuickAccount;
+/**
+ * Return the account's preferred Bloom color preset, or `null` if it has no
+ * preference. Centralises the `color ?? null` normalisation so consumers can
+ * drive per-account theming without duplicating the nullish-handling.
+ */
+export declare const getAccountColor: (account: QuickAccount) => string | null;

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

@@ -0,0 +1,2 @@
+/** @deprecated Import from `@oxy.so/telemetry/browser` in new code. */
+export { getBrowserActivityIdHeader } from '@oxy.so/telemetry/browser';