@oxy.so/core 1.0.0

package/dist/esm/utils/accountUtils.js

@@ -0,0 +1,131 @@
+/**
+ * Shared account types and pure helper functions.
+ * Used by the @oxy.so/services account stores (Expo/RN and RN-Web).
+ */
+import { translate } from '../i18n/index.js';
+import { getNormalizedUserHandle } from './userHandle.js';
+/**
+ * Truncate a long public key for display, e.g. `0x12345678…`.
+ * Falls back to the raw key if it's too short to truncate.
+ */
+export const formatPublicKeyHandle = (publicKey) => {
+    const cleaned = publicKey.startsWith('0x') ? publicKey.slice(2) : publicKey;
+    if (cleaned.length <= 8)
+        return `0x${cleaned}`;
+    return `0x${cleaned.slice(0, 8)}…`;
+};
+/**
+ * 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 const getAccountDisplayName = (user, locale) => {
+    if (!user)
+        return translate(locale, 'common.unnamed');
+    const { name, displayName, username, publicKey } = user;
+    if (name && typeof name === 'object') {
+        if (typeof name.displayName === 'string' && name.displayName.trim()) {
+            return name.displayName.trim();
+        }
+        if (typeof name.full === 'string' && name.full.trim())
+            return name.full.trim();
+        const first = typeof name.first === 'string' ? name.first.trim() : '';
+        const last = typeof name.last === 'string' ? name.last.trim() : '';
+        const composed = [first, last].filter(Boolean).join(' ').trim();
+        if (composed)
+            return composed;
+    }
+    else if (typeof name === 'string' && name.trim()) {
+        return name.trim();
+    }
+    if (typeof displayName === 'string' && displayName.trim())
+        return displayName.trim();
+    if (typeof username === 'string' && username.trim())
+        return username.trim();
+    if (typeof publicKey === 'string' && publicKey.length > 0) {
+        return translate(locale, 'common.accountFallback', {
+            handle: formatPublicKeyHandle(publicKey),
+        });
+    }
+    return translate(locale, 'common.unnamed');
+};
+/**
+ * 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 const getAccountFallbackHandle = (user) => {
+    if (!user)
+        return undefined;
+    if (typeof user.username === 'string' && user.username.trim())
+        return user.username.trim();
+    if (typeof user.publicKey === 'string' && user.publicKey.length > 0) {
+        return formatPublicKeyHandle(user.publicKey);
+    }
+    return undefined;
+};
+/**
+ * Build an ordered array of QuickAccounts from a map and order list.
+ */
+export const buildAccountsArray = (accounts, order) => {
+    const result = [];
+    for (const id of order) {
+        const account = accounts[id];
+        if (account)
+            result.push(account);
+    }
+    return result;
+};
+/**
+ * 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 const createQuickAccount = (sessionId, userData, existingAccount, getFileDownloadUrl) => {
+    const nameObj = userData.name && typeof userData.name === 'object' ? userData.name : undefined;
+    const apiDisplayName = typeof nameObj?.displayName === 'string' ? nameObj.displayName.trim() : '';
+    const displayName = apiDisplayName ||
+        getNormalizedUserHandle(userData) ||
+        getAccountDisplayName(null);
+    const userId = userData.id || (typeof userData._id === 'string' ? userData._id : userData._id?.toString());
+    // Preserve existing avatarUrl if avatar hasn't changed (prevents image reload)
+    let avatarUrl;
+    const avatar = userData.avatar ?? undefined;
+    if (existingAccount && existingAccount.avatar === avatar && existingAccount.avatarUrl) {
+        avatarUrl = existingAccount.avatarUrl;
+    }
+    else if (avatar && getFileDownloadUrl) {
+        avatarUrl = getFileDownloadUrl(avatar, 'thumb');
+    }
+    return {
+        sessionId,
+        userId,
+        username: userData.username || '',
+        displayName,
+        avatar,
+        avatarUrl,
+    };
+};
+/**
+ * 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 const getAccountColor = (account) => {
+    return account.color ?? null;
+};

package/dist/esm/utils/activityId.js

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

package/dist/esm/utils/apiUtils.js

@@ -0,0 +1,84 @@
+/**
+ * Utility functions for common API patterns
+ */
+/**
+ * Build a plain query-parameter record from an object, stringifying values and
+ * dropping `undefined`/`null` entries.
+ *
+ * This is the shape `OxyServices.makeRequest` expects for a GET's `params`:
+ * `HttpService` inspects it with `Object.keys(...)` (both to decide whether to
+ * append a query string and to build the request's cache key), and
+ * `Object.keys(new URLSearchParams({ limit: '20' }))` is `[]` — a
+ * `URLSearchParams` exposes its entries through iterator methods, never as own
+ * enumerable properties. Passing one to `makeRequest` therefore silently drops
+ * the whole query string. Always hand `makeRequest` a plain record.
+ *
+ * Generic over the input object rather than taking `Record<string, unknown>`,
+ * because a TypeScript `interface` (`PaginationParams`, `FollowGraphParams`, …)
+ * has no implicit index signature and so is not assignable to that type.
+ */
+export function buildQueryParams(params) {
+    const query = {};
+    // Widening the value to `unknown` is always sound; the default overload of
+    // `Object.entries` would otherwise infer `any` here.
+    for (const [key, value] of Object.entries(params)) {
+        if (value !== undefined && value !== null) {
+            query[key] = String(value);
+        }
+    }
+    return query;
+}
+/**
+ * Build URL search parameters from an object.
+ *
+ * For building a URL string only — see {@link buildQueryParams} for the shape
+ * `makeRequest` needs.
+ *
+ * @param params Object with parameter key-value pairs
+ * @returns URLSearchParams instance
+ */
+export function buildSearchParams(params) {
+    return new URLSearchParams(buildQueryParams(params));
+}
+/**
+ * Build URL with search parameters
+ * @param baseUrl Base URL
+ * @param params Object with parameter key-value pairs
+ * @returns Complete URL with search parameters
+ */
+export function buildUrl(baseUrl, params) {
+    if (!params)
+        return baseUrl;
+    const searchParams = buildSearchParams(params);
+    const queryString = searchParams.toString();
+    return queryString ? `${baseUrl}?${queryString}` : baseUrl;
+}
+/**
+ * Build pagination query parameters.
+ *
+ * Returns a plain record — NOT a `URLSearchParams` — because that is the only
+ * shape `makeRequest`/`HttpService` can read. See {@link buildQueryParams}.
+ *
+ * @param params Pagination parameters
+ * @returns Query record with pagination
+ */
+export function buildPaginationParams(params) {
+    return buildQueryParams(params);
+}
+/**
+ * Safe JSON parsing with error handling
+ * @param data Data to parse
+ * @param fallback Fallback value if parsing fails
+ * @returns Parsed data or fallback
+ */
+export function safeJsonParse(data, fallback) {
+    if (typeof data === 'string') {
+        try {
+            return JSON.parse(data);
+        }
+        catch {
+            return fallback;
+        }
+    }
+    return data;
+}

package/dist/esm/utils/asyncUtils.js

@@ -0,0 +1,207 @@
+/**
+ * Async utilities for common asynchronous patterns and error handling
+ */
+import { logger } from '../logger/index.js';
+/**
+ * Wrapper for async operations with automatic error handling
+ * Returns null on error instead of throwing
+ */
+export async function withErrorHandling(operation, errorHandler, context) {
+    try {
+        return await operation();
+    }
+    catch (error) {
+        if (errorHandler) {
+            errorHandler(error);
+        }
+        else {
+            logger.error(`Error in ${context || 'operation'}`, error instanceof Error ? error : new Error(String(error)), {
+                component: 'asyncUtils',
+                method: 'withErrorHandling',
+            });
+        }
+        return null;
+    }
+}
+/**
+ * Execute multiple async operations in parallel with error handling
+ */
+export async function parallelWithErrorHandling(operations, errorHandler) {
+    const results = await Promise.allSettled(operations.map((op, index) => withErrorHandling(op, error => errorHandler?.(error, index))));
+    return results.map(result => result.status === 'fulfilled' ? result.value : null);
+}
+/**
+ * Extract an HTTP status code from an error value, tolerating both the
+ * axios-style nested shape (`error.response.status`) and the flat shape
+ * produced by {@link handleHttpError} / fetch-based clients (`error.status`).
+ *
+ * Centralising this lookup prevents retry predicates from silently falling
+ * through when one of the two shapes is missing, which previously caused
+ * @oxy.so/core to retry 4xx responses and turn sub-10ms failures into
+ * multi-second stalls for every missing-resource lookup.
+ */
+function extractHttpStatus(error) {
+    if (!error || typeof error !== 'object')
+        return undefined;
+    const candidate = error;
+    const flat = candidate.status;
+    if (typeof flat === 'number' && Number.isFinite(flat))
+        return flat;
+    const nested = candidate.response?.status;
+    if (typeof nested === 'number' && Number.isFinite(nested))
+        return nested;
+    return undefined;
+}
+/**
+ * Retry an async operation with exponential backoff
+ *
+ * By default, does not retry on 4xx errors (client errors). The default
+ * predicate accepts both the axios-style `error.response.status` and the
+ * flat `error.status` shape produced by {@link handleHttpError}, so callers
+ * never accidentally retry a deterministic client failure.
+ *
+ * Use the `shouldRetry` callback to customize retry behavior.
+ */
+export async function retryAsync(operation, maxRetries = 3, baseDelay = 1000, shouldRetry) {
+    let lastError;
+    // Default shouldRetry: don't retry on 4xx errors (client errors).
+    // Checks BOTH `error.status` (flat shape from handleHttpError / fetch
+    // clients) AND `error.response.status` (axios-style shape) so neither
+    // representation can leak a client error into the retry loop.
+    const defaultShouldRetry = (error) => {
+        const status = extractHttpStatus(error);
+        if (status !== undefined && status >= 400 && status < 500) {
+            return false;
+        }
+        return true;
+    };
+    const retryCheck = shouldRetry || defaultShouldRetry;
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+        try {
+            return await operation();
+        }
+        catch (error) {
+            lastError = error;
+            if (attempt === maxRetries) {
+                break;
+            }
+            if (!retryCheck(error)) {
+                break;
+            }
+            // Calculate delay with exponential backoff and jitter
+            const delay = baseDelay * Math.pow(2, attempt) + Math.random() * 1000;
+            await new Promise(resolve => setTimeout(resolve, delay));
+        }
+    }
+    throw lastError;
+}
+/**
+ * Debounce async function calls
+ */
+export function debounceAsync(func, delay) {
+    let timeoutId;
+    return (...args) => {
+        return new Promise((resolve, reject) => {
+            clearTimeout(timeoutId);
+            timeoutId = setTimeout(async () => {
+                try {
+                    const result = await func(...args);
+                    resolve(result);
+                }
+                catch (error) {
+                    reject(error);
+                }
+            }, delay);
+        });
+    };
+}
+/**
+ * Throttle async function calls
+ */
+export function throttleAsync(func, limit, interval) {
+    let inThrottle = false;
+    let lastPromise = null;
+    return (...args) => {
+        if (inThrottle) {
+            return lastPromise;
+        }
+        inThrottle = true;
+        lastPromise = func(...args);
+        setTimeout(() => {
+            inThrottle = false;
+        }, interval);
+        return lastPromise;
+    };
+}
+/**
+ * Execute async operations sequentially with progress tracking
+ */
+export async function sequentialWithProgress(operations, onProgress) {
+    const results = [];
+    for (let i = 0; i < operations.length; i++) {
+        const result = await operations[i]();
+        results.push(result);
+        onProgress?.(i + 1, operations.length);
+    }
+    return results;
+}
+/**
+ * Batch async operations
+ */
+export async function batchAsync(items, batchSize, processor) {
+    for (let i = 0; i < items.length; i += batchSize) {
+        const batch = items.slice(i, i + batchSize);
+        await processor(batch);
+    }
+}
+/**
+ * Create a cancellable async operation
+ */
+export function createCancellableAsync(operation) {
+    let abortController = null;
+    return {
+        execute: async () => {
+            abortController = new AbortController();
+            return await operation(abortController.signal);
+        },
+        cancel: () => {
+            abortController?.abort();
+        }
+    };
+}
+/**
+ * Timeout wrapper for async operations
+ */
+export async function withTimeout(operation, timeoutMs, timeoutMessage) {
+    const timeoutPromise = new Promise((_, reject) => {
+        setTimeout(() => {
+            reject(new Error(timeoutMessage || `Operation timed out after ${timeoutMs}ms`));
+        }, timeoutMs);
+    });
+    return Promise.race([operation, timeoutPromise]);
+}
+/**
+ * Execute async operation with loading state
+ */
+export async function withLoadingState(operation, setLoading) {
+    setLoading(true);
+    try {
+        return await operation();
+    }
+    finally {
+        setLoading(false);
+    }
+}
+/**
+ * Create a promise that resolves after a delay
+ */
+export const delay = (ms) => new Promise(resolve => setTimeout(resolve, ms));
+/**
+ * Execute async operation with retry on specific errors
+ */
+export async function retryOnError(operation, retryableErrors, maxRetries = 3) {
+    return retryAsync(operation, maxRetries, 1000, (error) => {
+        const errorCode = error?.code || error?.status || error?.message;
+        return retryableErrors.includes(errorCode);
+    });
+}

package/dist/esm/utils/authHelpers.js

@@ -0,0 +1,111 @@
+/**
+ * Authentication helper utilities for common token validation
+ * and authentication error handling patterns.
+ */
+/**
+ * Error thrown when session sync is required
+ */
+export class SessionSyncRequiredError extends Error {
+    constructor(message = 'Session needs to be synced. Please try again.') {
+        super(message);
+        this.name = 'SessionSyncRequiredError';
+    }
+}
+/**
+ * Error thrown when authentication fails
+ */
+export class AuthenticationFailedError extends Error {
+    constructor(message = 'Authentication failed. Please sign in again.') {
+        super(message);
+        this.name = 'AuthenticationFailedError';
+    }
+}
+/**
+ * Ensures a valid token exists before making authenticated API calls.
+ * If no valid token exists, callers may provide a session synchronizer that
+ * uses the platform-appropriate new flow (cookie restore, device claim, or
+ * native secure restore). This helper never exchanges a session id for a token.
+ *
+ * @throws {SessionSyncRequiredError} If the session needs to be synced (offline session)
+ */
+export async function ensureValidToken(oxyServices, _activeSessionId, syncSession) {
+    if (oxyServices.hasValidToken()) {
+        return;
+    }
+    if (syncSession) {
+        try {
+            await syncSession();
+            if (oxyServices.hasValidToken()) {
+                return;
+            }
+        }
+        catch (syncError) {
+            const errorMessage = syncError instanceof Error ? syncError.message : String(syncError);
+            if (errorMessage.includes('AUTH_REQUIRED_OFFLINE_SESSION') || errorMessage.includes('offline')) {
+                throw new SessionSyncRequiredError();
+            }
+            throw syncError;
+        }
+    }
+    throw new SessionSyncRequiredError('No active access token is available. Sync the session before calling authenticated APIs.');
+}
+/**
+ * Checks if an error is an authentication error (401 or auth-related message)
+ */
+export function isAuthenticationError(error) {
+    if (!error || typeof error !== 'object') {
+        return false;
+    }
+    const errorObj = error;
+    const errorMessage = errorObj.message || '';
+    const status = errorObj.status || errorObj.response?.status;
+    return (status === 401 ||
+        errorMessage.includes('Authentication required') ||
+        errorMessage.includes('Invalid or missing authorization header'));
+}
+/**
+ * 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 async function withAuthErrorHandling(apiCall, options) {
+    try {
+        return await apiCall();
+    }
+    catch (error) {
+        if (!isAuthenticationError(error)) {
+            throw error;
+        }
+        if (options?.syncSession && options?.oxyServices) {
+            try {
+                await options.syncSession();
+                return await apiCall();
+            }
+            catch {
+                throw new AuthenticationFailedError();
+            }
+        }
+        throw new AuthenticationFailedError();
+    }
+}
+/**
+ * Combines token validation and auth error handling for a complete authenticated API call.
+ *
+ * @example
+ * ```ts
+ * return await authenticatedApiCall(
+ *   oxyServices,
+ *   activeSessionId,
+ *   () => oxyServices.updateProfile(updates)
+ * );
+ * ```
+ */
+export async function authenticatedApiCall(oxyServices, activeSessionId, apiCall, syncSession) {
+    await ensureValidToken(oxyServices, activeSessionId, syncSession);
+    return withAuthErrorHandling(apiCall, {
+        syncSession,
+        activeSessionId,
+        oxyServices,
+    });
+}

package/dist/esm/utils/authWebUrl.js

@@ -0,0 +1,16 @@
+/**
+ * Central IdP apex constant.
+ *
+ * The client SSO/FedCM resolvers (`resolveCentralAuthUrl`, `CENTRAL_AUTH_URL`)
+ * were removed in the device-first / legacy-final cutovers. The lone survivor is
+ * `CENTRAL_IDP_APEX`, kept because it has a LIVE consumer —
+ * `@oxy.so/core/server`'s CORS helper (`server/cors.ts`'s `createOxyCors`)
+ * auto-allows `*.oxy.so` from it. That CORS use is permanent, so this stays
+ * past the SSO/FedCM teardown.
+ */
+/**
+ * The registrable apex (eTLD+1) of the Oxy ecosystem's central Identity
+ * Provider, reachable at `auth.${CENTRAL_IDP_APEX}`. Single source of truth so
+ * the CORS helper (and anything else that needs the central apex) never drifts.
+ */
+export const CENTRAL_IDP_APEX = 'oxy.so';

package/dist/esm/utils/avatarUtils.js

@@ -0,0 +1,26 @@
+import { logger } from '../logger/index.js';
+/**
+ * Updates file visibility to public for avatar use.
+ * Logs non-404 errors to help debug upload issues.
+ *
+ * @param fileId - The file ID to update visibility for
+ * @param oxyServices - OxyServices instance (or any object with assetUpdateVisibility)
+ * @param contextName - Context name for error logging
+ */
+export async function updateAvatarVisibility(fileId, oxyServices, contextName = 'AvatarUtils') {
+    if (!fileId || fileId.startsWith('temp-')) {
+        return;
+    }
+    try {
+        await oxyServices.assetUpdateVisibility(fileId, 'public');
+    }
+    catch (visError) {
+        // 404 is expected when asset doesn't exist yet — skip logging
+        const status = (visError instanceof Error && 'status' in visError)
+            ? visError.status
+            : undefined;
+        if (status !== 404) {
+            logger.error(`[${contextName}] Failed to update avatar visibility for ${fileId}`, visError, { component: contextName });
+        }
+    }
+}