@oxy.so/core 1.0.0

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

@@ -0,0 +1,95 @@
+/**
+ * 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 declare function buildQueryParams<T extends object>(params: T): Record<string, string>;
+/**
+ * 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 declare function buildSearchParams<T extends object>(params: T): URLSearchParams;
+/**
+ * Build URL with search parameters
+ * @param baseUrl Base URL
+ * @param params Object with parameter key-value pairs
+ * @returns Complete URL with search parameters
+ */
+export declare function buildUrl<T extends object>(baseUrl: string, params?: T): string;
+/**
+ * Common pagination parameters
+ */
+export interface PaginationParams {
+    limit?: number;
+    offset?: number;
+}
+/**
+ * Ordering for the follow-graph list endpoints (`/users/:id/followers`,
+ * `/users/:id/following`, `/users/:id/mutuals`).
+ *
+ * - `recent` — newest follow edge first (the server default).
+ * - `oldest` — oldest follow edge first.
+ */
+export type FollowGraphSort = 'recent' | 'oldest';
+/**
+ * Pagination plus the follow-graph ordering.
+ *
+ * Kept separate from {@link PaginationParams}, which is shared by endpoints
+ * that have no `sort` at all.
+ */
+export interface FollowGraphParams extends PaginationParams {
+    sort?: FollowGraphSort;
+}
+/**
+ * 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 declare function buildPaginationParams(params: PaginationParams): Record<string, string>;
+/**
+ * Common API response wrapper
+ */
+export interface ApiResponse<T = any> {
+    data: T;
+    message?: string;
+    success?: boolean;
+}
+/**
+ * Common error response wrapper
+ */
+export interface ErrorResponse {
+    message: string;
+    code: string;
+    status: number;
+    details?: any;
+}
+/**
+ * Safe JSON parsing with error handling
+ * @param data Data to parse
+ * @param fallback Fallback value if parsing fails
+ * @returns Parsed data or fallback
+ */
+export declare function safeJsonParse<T>(data: any, fallback: T): T;

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

@@ -0,0 +1,62 @@
+/**
+ * Async utilities for common asynchronous patterns and error handling
+ */
+/**
+ * Wrapper for async operations with automatic error handling
+ * Returns null on error instead of throwing
+ */
+export declare function withErrorHandling<T>(operation: () => Promise<T>, errorHandler?: (error: any) => void, context?: string): Promise<T | null>;
+/**
+ * Execute multiple async operations in parallel with error handling
+ */
+export declare function parallelWithErrorHandling<T>(operations: (() => Promise<T>)[], errorHandler?: (error: any, index: number) => void): Promise<(T | null)[]>;
+/**
+ * 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 declare function retryAsync<T>(operation: () => Promise<T>, maxRetries?: number, baseDelay?: number, shouldRetry?: (error: any) => boolean): Promise<T>;
+/**
+ * Debounce async function calls
+ */
+export declare function debounceAsync<T extends (...args: any[]) => Promise<any>>(func: T, delay: number): (...args: Parameters<T>) => Promise<ReturnType<T>>;
+/**
+ * Throttle async function calls
+ */
+export declare function throttleAsync<T extends (...args: any[]) => Promise<any>>(func: T, limit: number, interval: number): (...args: Parameters<T>) => Promise<ReturnType<T>>;
+/**
+ * Execute async operations sequentially with progress tracking
+ */
+export declare function sequentialWithProgress<T>(operations: (() => Promise<T>)[], onProgress?: (completed: number, total: number) => void): Promise<T[]>;
+/**
+ * Batch async operations
+ */
+export declare function batchAsync<T>(items: T[], batchSize: number, processor: (batch: T[]) => Promise<void>): Promise<void>;
+/**
+ * Create a cancellable async operation
+ */
+export declare function createCancellableAsync<T>(operation: (signal: AbortSignal) => Promise<T>): {
+    execute: () => Promise<T>;
+    cancel: () => void;
+};
+/**
+ * Timeout wrapper for async operations
+ */
+export declare function withTimeout<T>(operation: Promise<T>, timeoutMs: number, timeoutMessage?: string): Promise<T>;
+/**
+ * Execute async operation with loading state
+ */
+export declare function withLoadingState<T>(operation: () => Promise<T>, setLoading: (loading: boolean) => void): Promise<T>;
+/**
+ * Create a promise that resolves after a delay
+ */
+export declare const delay: (ms: number) => Promise<void>;
+/**
+ * Execute async operation with retry on specific errors
+ */
+export declare function retryOnError<T>(operation: () => Promise<T>, retryableErrors: (string | number)[], maxRetries?: number): Promise<T>;

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

@@ -0,0 +1,58 @@
+/**
+ * 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, 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 declare function ensureValidToken(oxyServices: OxyServices, _activeSessionId: string | null | undefined, syncSession?: () => Promise<unknown>): 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/authWebUrl.d.ts

@@ -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 declare const CENTRAL_IDP_APEX = "oxy.so";

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

@@ -0,0 +1,16 @@
+/**
+ * Minimal interface for services that can update asset visibility.
+ * Kept loose to avoid mixin type-inference issues with the OxyServices class.
+ */
+export interface AssetVisibilityService {
+    assetUpdateVisibility(fileId: string, visibility: 'private' | 'public' | 'unlisted'): Promise<unknown>;
+}
+/**
+ * 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 declare function updateAvatarVisibility(fileId: string | undefined, oxyServices: AssetVisibilityService, contextName?: string): Promise<void>;

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

@@ -0,0 +1,130 @@
+/**
+ * Centralized cache utility with TTL support
+ *
+ * This is a production-ready cache implementation used across the codebase
+ * for consistent caching behavior and performance optimization.
+ */
+/**
+ * Cache statistics
+ */
+export interface CacheStats {
+    size: number;
+    hits: number;
+    misses: number;
+    hitRate: number;
+}
+/**
+ * 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();
+ * ```
+ */
+export declare class TTLCache<T> {
+    private cache;
+    private defaultTTL;
+    private hits;
+    private misses;
+    /**
+     * Create a new TTL cache
+     * @param defaultTTL Default TTL in milliseconds (default: 5 minutes)
+     */
+    constructor(defaultTTL?: number);
+    /**
+     * Get a value from cache
+     * @param key Cache key
+     * @returns Cached value or null if not found or expired
+     */
+    get(key: string): T | null;
+    /**
+     * Set a value in cache
+     * @param key Cache key
+     * @param data Data to cache
+     * @param ttl Optional TTL override (uses default if not provided). An
+     *   explicit `0` or negative value is honored as "already expired" — the
+     *   entry is stored with `expiresAt <= now`, so the next `get`/`has` treats
+     *   it as a miss — rather than silently falling back to the default TTL.
+     */
+    set(key: string, data: T, ttl?: number): void;
+    /**
+     * Delete a specific cache entry
+     * @param key Cache key
+     * @returns true if entry was deleted, false if not found
+     */
+    delete(key: string): boolean;
+    /**
+     * Clear all cache entries
+     */
+    clear(): void;
+    /**
+     * Check if a key exists and is not expired
+     * @param key Cache key
+     * @returns true if key exists and is valid
+     */
+    has(key: string): boolean;
+    /**
+     * Get all valid cache keys
+     * @returns Array of valid cache keys
+     */
+    keys(): string[];
+    /**
+     * Clean up expired entries
+     * @returns Number of entries removed
+     */
+    cleanup(): number;
+    /**
+     * Get cache size (number of entries)
+     */
+    size(): number;
+    /**
+     * Get cache statistics
+     */
+    getStats(): CacheStats;
+    /**
+     * Reset statistics (keeps cache entries)
+     */
+    resetStats(): void;
+}
+/**
+ * Create a TTL cache instance (convenience function)
+ *
+ * @example
+ * ```typescript
+ * const cache = createCache<string>(5 * 60 * 1000);
+ * ```
+ */
+export declare function createCache<T>(ttl?: number): TTLCache<T>;
+/**
+ * Register a cache for automatic cleanup
+ * @param cache Cache instance to register
+ */
+export declare function registerCacheForCleanup(cache: TTLCache<any>): void;
+/**
+ * Unregister a cache from automatic cleanup
+ * @param cache Cache instance to unregister
+ */
+export declare function unregisterCacheFromCleanup(cache: TTLCache<any>): void;
+/**
+ * Stop all cleanup intervals (useful for testing)
+ * This will clear the interval and unregister all caches
+ */
+export declare function stopAllCleanupIntervals(): void;

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

@@ -0,0 +1,66 @@
+/**
+ * Cache-key primitives for the identity-scoped HTTP GET response cache.
+ *
+ * Extracted from {@link HttpService} so the identity-tag derivation is a pure,
+ * independently testable function with no dependency on instance/token state.
+ * The HTTP service injects the live access token; everything here is
+ * referentially transparent given that input.
+ */
+/**
+ * Minimal JWT payload shape we read for cache scoping. The identity discriminator
+ * comes from `userId` (preferred) or `id`; nothing else is consulted here.
+ */
+export interface CacheIdentityJwtPayload {
+    userId?: string;
+    id?: string;
+    [key: string]: unknown;
+}
+/**
+ * Discriminator used when there is no access token at all. Anonymous responses
+ * must never collide with any authenticated identity.
+ */
+export declare const ANON_IDENTITY = "anon";
+/**
+ * FNV-1a 32-bit non-cryptographic hash.
+ *
+ * Used by the cache-key generator for large payloads where full JSON inclusion
+ * would balloon the cache map keys, and as the fallback discriminator for an
+ * undecodable access token. Content-addressed: every byte of the input
+ * contributes to the digest, so two inputs with the same top-level shape but
+ * different field values produce different keys (the previous `keys + length`
+ * heuristic collided on these).
+ *
+ * Trade-offs:
+ *  - 32 bits is ample for an in-process cache (collision risk negligible at our
+ *    key counts; we also prefix with method + url which further partitions the
+ *    keyspace).
+ *  - Not cryptographically secure — never use for security decisions.
+ *  - Zero dependencies, branch-free hot loop, ~1 GiB/s on V8.
+ */
+export declare function fnv1a32(str: string): string;
+/**
+ * Derive a stable, non-sensitive identity discriminator for cache scoping.
+ *
+ * The GET-response cache MUST be partitioned by caller identity: endpoints with
+ * optional auth (e.g. `GET /profiles/recommendations`) return different content
+ * for an anonymous vs an authenticated caller, and per-user content for
+ * different authenticated users. Keying solely on `method:url:data` let an
+ * anonymous response be served to an authenticated caller — surfacing as
+ * "Who to follow" recommending accounts the user already follows after a
+ * cold-boot session restore.
+ *
+ * Resolution order:
+ *  - no token            → {@link ANON_IDENTITY} (`'anon'`).
+ *  - decodable token     → the token's `userId || id`.
+ *  - undecodable token   → a short FNV-1a hash of the token, prefixed `t` so it
+ *                          can never collide with `'anon'` or a real user id.
+ *
+ * We use the decoded user id rather than the raw JWT so the token never lands
+ * in a cache key (no token leakage through any cache-key logging, no key bloat).
+ * Switching into a managed account mints a REAL new session whose access token
+ * carries the target account's id, so the identity tag changes naturally on a
+ * switch — there is no separate acting-as discriminator to fold in.
+ *
+ * @param accessToken The current bearer access token, or `null` when anonymous.
+ */
+export declare function computeIdentityTag(accessToken: string | null): string;

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

@@ -0,0 +1,131 @@
+/**
+ * coldBoot — a pure, ordered, short-circuit runner for "cold boot"
+ * authentication resolution.
+ *
+ * On a fresh page load / app launch the SDK may have several ways to recover an
+ * existing session (a persisted refresh-token family, a shared-keychain
+ * identity, a cross-domain boot-fragment return, ...). They must be attempted
+ * in a deterministic order, and the FIRST one that yields a session wins —
+ * every later step is skipped. This module encodes exactly that contract and
+ * nothing else.
+ *
+ * Design constraints (all enforced):
+ *   - PURE: no DOM, no `navigator`, no `window`, no React, no platform globals.
+ *   - NO module-level mutable state. Every call to {@link runColdBoot} is fully
+ *     self-contained, so it is safe under bundler re-evaluation (e.g. the Metro
+ *     web bundle — the reason any run-once guard for a step must live in the
+ *     calling consumer, never in a core module-level singleton).
+ *   - Architecture-agnostic: it knows nothing about HOW a step resolves a
+ *     session; `runSessionColdBoot` (`boot/sessionColdBoot.ts`) is the current
+ *     device-first consumer.
+ *
+ * A step is skipped (without running) when its `enabled` predicate returns
+ * false. Any thrown error — from either `enabled` or `run` — is reported via
+ * `onStepError` and treated as a non-fatal skip, so one broken recovery path
+ * can never prevent a later, healthy one from succeeding.
+ */
+/**
+ * A successful step result carrying the recovered session.
+ */
+export interface ColdBootSession<S> {
+    readonly kind: 'session';
+    readonly session: S;
+}
+/**
+ * A step result indicating this step has nothing to contribute; the runner
+ * should fall through to the next step.
+ */
+export interface ColdBootSkip {
+    readonly kind: 'skip';
+}
+/**
+ * The result of running a single cold-boot step.
+ */
+export type ColdBootStepResult<S> = ColdBootSession<S> | ColdBootSkip;
+/**
+ * A single ordered cold-boot recovery step.
+ */
+export interface ColdBootStep<S> {
+    /** Stable identifier; surfaced as {@link ColdBootOutcome.via} on success. */
+    readonly id: string;
+    /**
+     * Optional gate. When provided and it returns `false`, `run` is NOT called
+     * and the runner moves to the next step. A throw is treated as disabled
+     * (and reported via `onStepError`).
+     */
+    readonly enabled?: () => boolean;
+    /**
+     * Attempts to recover a session. Resolve with `{ kind: 'session' }` to win
+     * the cold boot, or `{ kind: 'skip' }` to defer to the next step. A throw is
+     * treated as a skip (and reported via `onStepError`).
+     */
+    readonly run: () => Promise<ColdBootStepResult<S>>;
+}
+/**
+ * The terminal outcome of a cold boot: either the winning step's session
+ * (with the step `id` it came from), or `unauthenticated` if every step
+ * skipped, was disabled, or errored.
+ */
+export type ColdBootOutcome<S> = {
+    readonly kind: 'session';
+    readonly via: string;
+    readonly session: S;
+} | {
+    readonly kind: 'unauthenticated';
+};
+/**
+ * Options for {@link runColdBoot}.
+ */
+export interface RunColdBootOptions<S> {
+    /** Ordered steps; evaluated front to back, first session wins. */
+    readonly steps: ReadonlyArray<ColdBootStep<S>>;
+    /**
+     * Optional observer invoked whenever a step's `enabled` or `run` throws.
+     * Receives the offending step `id` and the thrown value. Must not throw;
+     * the runner does not guard against an observer that itself throws.
+     */
+    readonly onStepError?: (id: string, error: unknown) => void;
+    /**
+     * Optional HARD overall deadline (ms) for the entire ordered step loop —
+     * defense-in-depth so a single non-settling step can NEVER hang the whole
+     * cold boot forever.
+     *
+     * Each step's `run()` is raced against the SHARED remaining time. If a step
+     * fails to settle before the deadline, the runner abandons the await for that
+     * step (reporting it via `onStepDeadline`) and CONTINUES to the next step,
+     * each now racing against an already-expired deadline. This is deliberate:
+     * the runner keeps iterating so the TERMINAL step (e.g. `sessionColdBoot`'s
+     * `bootstrap-hop`, whose `run()` performs its navigation side effect
+     * synchronously before its first `await`) still gets to fire. A step that
+     * has nothing to contribute after the deadline simply doesn't settle and is
+     * skipped in turn.
+     *
+     * Per-step timeouts inside `run()` remain the first line of defense and
+     * should keep every step well under this budget on a healthy load; this only
+     * trips when one of them regresses (a step hanging past its own timeout).
+     * When omitted there is no overall deadline.
+     */
+    readonly overallDeadlineMs?: number;
+    /**
+     * Optional observer invoked once per step that was abandoned because the
+     * overall deadline expired before it settled. Receives the step `id`. Must
+     * not throw.
+     */
+    readonly onStepDeadline?: (id: string) => void;
+}
+/**
+ * Run the ordered cold-boot steps and resolve to the first recovered session,
+ * or `unauthenticated` if none recovers one.
+ *
+ * Semantics:
+ *   1. Iterate `steps` in order.
+ *   2. If a step has an `enabled` predicate, call it inside try/catch:
+ *      - throw → report via `onStepError(id, err)` → treat as disabled → continue.
+ *      - returns false → continue (skip, `run` not called).
+ *   3. Otherwise await `step.run()` inside try/catch:
+ *      - throw → report via `onStepError(id, err)` → continue.
+ *      - `{ kind: 'session' }` → return `{ kind: 'session', via: step.id, session }`.
+ *      - `{ kind: 'skip' }` → continue.
+ *   4. After the loop with no winner → `{ kind: 'unauthenticated' }`.
+ */
+export declare function runColdBoot<S>(options: RunColdBootOptions<S>): Promise<ColdBootOutcome<S>>;

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

@@ -0,0 +1,13 @@
+import type { PublicApplication } from '../mixins/OxyServices.connectedApps';
+export interface CommonsApprovalValidationInput {
+    application: PublicApplication | null;
+    status: string;
+    expiresAt: number | string;
+}
+/**
+ * Returns a user-facing blocking reason when an approval payload must not be
+ * shown as actionable, or `null` when the request is still pending and valid.
+ */
+export declare function getCommonsApprovalBlockingReason(info: CommonsApprovalValidationInput): string | null;
+/** Normalize API `expiresAt` (number or ISO string) to epoch ms. */
+export declare function parseCommonsApprovalExpiresAt(expiresAt: CommonsApprovalValidationInput['expiresAt']): number | null;