@oxy.so/core 1.0.0

package/dist/esm/utils/requestUtils.js

@@ -0,0 +1,203 @@
+/**
+ * Request utilities for HTTP clients
+ *
+ * Provides reusable components for request deduplication, queuing, and logging
+ */
+/**
+ * Request deduplication - prevents duplicate concurrent requests
+ *
+ * When multiple requests with the same key are made simultaneously,
+ * only one request is executed and all callers receive the same result.
+ *
+ * @example
+ * ```typescript
+ * const deduplicator = new RequestDeduplicator();
+ *
+ * // Multiple calls with same key will share the same promise
+ * const promise1 = deduplicator.deduplicate('user-123', () => fetchUser('123'));
+ * const promise2 = deduplicator.deduplicate('user-123', () => fetchUser('123'));
+ * // promise1 === promise2, only one API call is made
+ * ```
+ */
+export class RequestDeduplicator {
+    constructor() {
+        this.pendingRequests = new Map();
+    }
+    /**
+     * Deduplicate a request by key
+     * @param key Unique key for the request
+     * @param requestFn Function that returns a promise
+     * @returns Promise that will be shared if key already exists
+     */
+    async deduplicate(key, requestFn) {
+        const existing = this.pendingRequests.get(key);
+        if (existing) {
+            return existing;
+        }
+        const promise = requestFn()
+            .finally(() => {
+            this.pendingRequests.delete(key);
+        });
+        this.pendingRequests.set(key, promise);
+        return promise;
+    }
+    /**
+     * Clear all pending requests
+     */
+    clear() {
+        this.pendingRequests.clear();
+    }
+    /**
+     * Get number of pending requests
+     */
+    size() {
+        return this.pendingRequests.size;
+    }
+}
+/**
+ * Request queue with concurrency control
+ *
+ * Limits the number of concurrent requests and queues excess requests.
+ * Useful for rate limiting and preventing request flooding.
+ *
+ * @example
+ * ```typescript
+ * const queue = new RequestQueue(5, 100); // Max 5 concurrent, queue up to 100
+ *
+ * // All requests will be queued and processed with max 5 concurrent
+ * await queue.enqueue(() => fetchUser('1'));
+ * await queue.enqueue(() => fetchUser('2'));
+ * // ...
+ * ```
+ */
+export class RequestQueue {
+    /**
+     * Create a new request queue
+     * @param maxConcurrent Maximum number of concurrent requests (default: 10)
+     * @param maxQueueSize Maximum queue size (default: 100)
+     */
+    constructor(maxConcurrent = 10, maxQueueSize = 100) {
+        this.queue = [];
+        this.running = 0;
+        this.maxConcurrent = maxConcurrent;
+        this.maxQueueSize = maxQueueSize;
+    }
+    /**
+     * Enqueue a request
+     * @param requestFn Function that returns a promise
+     * @returns Promise that resolves when request completes
+     */
+    async enqueue(requestFn) {
+        if (this.queue.length >= this.maxQueueSize) {
+            throw new Error('Request queue is full');
+        }
+        return new Promise((resolve, reject) => {
+            this.queue.push(async () => {
+                try {
+                    const result = await requestFn();
+                    resolve(result);
+                }
+                catch (error) {
+                    reject(error);
+                }
+            });
+            this.process();
+        });
+    }
+    /**
+     * Process queued requests
+     */
+    async process() {
+        if (this.running >= this.maxConcurrent || this.queue.length === 0) {
+            return;
+        }
+        this.running++;
+        const requestFn = this.queue.shift();
+        if (requestFn) {
+            try {
+                await requestFn();
+            }
+            finally {
+                this.running--;
+                this.process();
+            }
+        }
+        else {
+            this.running--;
+        }
+    }
+    /**
+     * Clear all queued requests
+     */
+    clear() {
+        this.queue = [];
+    }
+    /**
+     * Get queue size
+     */
+    size() {
+        return this.queue.length;
+    }
+    /**
+     * Get number of currently running requests
+     */
+    runningCount() {
+        return this.running;
+    }
+}
+/**
+ * Simple logger with level support
+ *
+ * Lightweight logger for HTTP clients and utilities.
+ * For structured, namespaced, level-gated logging, use `@oxy.so/core/logger`.
+ *
+ * @example
+ * ```typescript
+ * const logger = new SimpleLogger(true, 'debug');
+ * logger.debug('Debug message');
+ * logger.info('Info message');
+ * logger.error('Error message');
+ * ```
+ */
+export class SimpleLogger {
+    /**
+     * Create a new simple logger
+     * @param enabled Whether logging is enabled
+     * @param level Minimum log level
+     * @param prefix Prefix for log messages (default: '')
+     */
+    constructor(enabled = false, level = 'error', prefix = '') {
+        this.enabled = enabled;
+        this.level = level;
+        this.prefix = prefix;
+    }
+    shouldLog(level) {
+        if (!this.enabled || this.level === 'none')
+            return false;
+        const levels = ['none', 'error', 'warn', 'info', 'debug'];
+        return levels.indexOf(level) <= levels.indexOf(this.level);
+    }
+    formatMessage(...args) {
+        return this.prefix ? [`[${this.prefix}]`, ...args] : args;
+    }
+    error(...args) {
+        if (this.shouldLog('error')) {
+            console.error(...this.formatMessage(...args));
+        }
+    }
+    warn(...args) {
+        if (this.shouldLog('warn')) {
+            console.warn(...this.formatMessage(...args));
+        }
+    }
+    info(...args) {
+        if (this.shouldLog('info')) {
+            console.info(...this.formatMessage(...args));
+        }
+    }
+    debug(...args) {
+        if (this.shouldLog('debug')) {
+            console.log(...this.formatMessage(...args));
+        }
+    }
+}

package/dist/esm/utils/sessionUtils.js

@@ -0,0 +1,171 @@
+/**
+ * Session management utilities
+ *
+ * Provides consistent session normalization, deduplication, and sorting
+ * to ensure sessions are always displayed in a predictable order.
+ */
+/**
+ * Normalize a session to ensure all required fields are present
+ */
+export function normalizeSession(session) {
+    const now = new Date().toISOString();
+    return {
+        sessionId: session.sessionId,
+        deviceId: session.deviceId || '',
+        expiresAt: session.expiresAt || now,
+        lastActive: session.lastActive || now,
+        userId: session.userId || '',
+    };
+}
+/**
+ * Compare two sessions for equality
+ */
+export function sessionsEqual(a, b) {
+    return a.sessionId === b.sessionId;
+}
+/**
+ * Sort sessions by lastActive (most recent first), then by sessionId for stability
+ */
+export function sortSessions(sessions) {
+    return [...sessions].sort((a, b) => {
+        // Sort by lastActive descending (most recent first)
+        const timeA = new Date(a.lastActive).getTime();
+        const timeB = new Date(b.lastActive).getTime();
+        if (timeA !== timeB) {
+            return timeB - timeA; // Descending order
+        }
+        // If lastActive is the same, sort by sessionId for stability
+        return a.sessionId.localeCompare(b.sessionId);
+    });
+}
+/**
+ * Deduplicate sessions by sessionId, keeping the most recent version
+ */
+export function deduplicateSessions(sessions) {
+    const sessionMap = new Map();
+    for (const session of sessions) {
+        const existing = sessionMap.get(session.sessionId);
+        if (!existing) {
+            sessionMap.set(session.sessionId, session);
+        }
+        else {
+            // Keep the one with more recent lastActive
+            const existingTime = new Date(existing.lastActive).getTime();
+            const currentTime = new Date(session.lastActive).getTime();
+            if (currentTime > existingTime) {
+                sessionMap.set(session.sessionId, session);
+            }
+        }
+    }
+    return Array.from(sessionMap.values());
+}
+/**
+ * Deduplicate sessions by userId, keeping only one session per user
+ * Priority: 1) Active session (if provided), 2) Most recent session
+ * This prevents showing duplicate accounts for the same user
+ */
+export function deduplicateSessionsByUserId(sessions, activeSessionId) {
+    if (!sessions.length)
+        return [];
+    const userSessionMap = new Map();
+    for (const session of sessions) {
+        if (!session.userId)
+            continue; // Skip sessions without userId
+        const existing = userSessionMap.get(session.userId);
+        if (!existing) {
+            userSessionMap.set(session.userId, session);
+        }
+        else {
+            // Prioritize active session
+            const isCurrentActive = activeSessionId && session.sessionId === activeSessionId;
+            const isExistingActive = activeSessionId && existing.sessionId === activeSessionId;
+            if (isCurrentActive && !isExistingActive) {
+                userSessionMap.set(session.userId, session);
+            }
+            else if (!isCurrentActive && isExistingActive) {
+                // Keep existing (active) session
+                continue;
+            }
+            else {
+                // Neither is active, keep the one with more recent lastActive
+                const existingTime = new Date(existing.lastActive).getTime();
+                const currentTime = new Date(session.lastActive).getTime();
+                if (currentTime > existingTime) {
+                    userSessionMap.set(session.userId, session);
+                }
+            }
+        }
+    }
+    return Array.from(userSessionMap.values());
+}
+/**
+ * Normalize, deduplicate, and sort sessions
+ * This ensures consistent session ordering across the application
+ *
+ * @param sessions - Array of sessions to normalize
+ * @param activeSessionId - Optional active session ID to prioritize
+ * @param deduplicateByUserId - If true, deduplicate by userId (one account per user). Default: true
+ */
+export function normalizeAndSortSessions(sessions, activeSessionId, deduplicateByUserId = true) {
+    if (!sessions.length)
+        return [];
+    // Normalize all sessions
+    const normalized = sessions.map(normalizeSession);
+    // First deduplicate by sessionId (exact duplicates)
+    const deduplicatedBySessionId = deduplicateSessions(normalized);
+    // Then deduplicate by userId if requested (one account per user)
+    const finalSessions = deduplicateByUserId
+        ? deduplicateSessionsByUserId(deduplicatedBySessionId, activeSessionId)
+        : deduplicatedBySessionId;
+    // Sort consistently
+    return sortSessions(finalSessions);
+}
+/**
+ * Merge two session arrays, prioritizing newer data
+ * Returns normalized, deduplicated, and sorted sessions
+ *
+ * @param existing - Existing sessions array
+ * @param incoming - New sessions to merge in
+ * @param activeSessionId - Optional active session ID to prioritize
+ * @param deduplicateByUserId - If true, deduplicate by userId (one account per user). Default: true
+ */
+export function mergeSessions(existing, incoming, activeSessionId, deduplicateByUserId = true) {
+    if (!existing.length && !incoming.length)
+        return [];
+    if (!existing.length)
+        return normalizeAndSortSessions(incoming, activeSessionId, deduplicateByUserId);
+    if (!incoming.length)
+        return normalizeAndSortSessions(existing, activeSessionId, deduplicateByUserId);
+    // Normalize both arrays
+    const normalizedExisting = existing.map(normalizeSession);
+    const normalizedIncoming = incoming.map(normalizeSession);
+    // Create a map with existing sessions (by sessionId)
+    const sessionMap = new Map();
+    // Add existing sessions first
+    for (const session of normalizedExisting) {
+        sessionMap.set(session.sessionId, session);
+    }
+    // Merge incoming sessions - backend data always replaces existing
+    for (const session of normalizedIncoming) {
+        sessionMap.set(session.sessionId, session);
+    }
+    // Convert to array
+    const merged = Array.from(sessionMap.values());
+    // Apply userId deduplication if requested
+    const finalSessions = deduplicateByUserId
+        ? deduplicateSessionsByUserId(merged, activeSessionId)
+        : merged;
+    // Sort consistently
+    return sortSessions(finalSessions);
+}
+/**
+ * Check if two session arrays are equal (same sessionIds in same order)
+ */
+export function sessionsArraysEqual(a, b) {
+    if (a.length !== b.length) {
+        return false;
+    }
+    const sortedA = sortSessions(a);
+    const sortedB = sortSessions(b);
+    return sortedA.every((session, index) => sessionsEqual(session, sortedB[index]));
+}

package/dist/esm/utils/textNormalization.js

@@ -0,0 +1,154 @@
+/**
+ * Canonical text normalization for the Oxy ecosystem.
+ *
+ * WHY THIS EXISTS
+ * ---------------
+ * Third-party text (federated actor display names, spoiler/CW text, image alt
+ * text, bios, `<title>` / `og:site_name` of scraped remote pages, …) arrives
+ * with the whitespace the remote author's markup happened to contain. A real
+ * bug: a remote page served
+ *
+ *     <title>
+ *       Mi título
+ *     </title>
+ *
+ * and the extracted string — newlines and indentation included — was stored
+ * verbatim. Clients render text with React Native Web `Text`, which maps to
+ * CSS `white-space: pre-wrap`: unlike HTML, newlines and repeated spaces are
+ * NOT collapsed at render time, so the user saw a blank line and a six-space
+ * indent inside the link preview.
+ *
+ * Storage-time normalization is therefore the ONLY place this can be fixed:
+ * every renderer downstream is faithful by design.
+ *
+ * WHICH HELPER DO I USE?
+ * ----------------------
+ *  - {@link normalizeInlineText} — the value is conceptually ONE LINE, and a
+ *    line break in it is always an accident of the source markup: page titles,
+ *    `siteName`, display names, image `alt`, handles, profile field labels.
+ *    Every line break becomes a space.
+ *
+ *  - {@link normalizeMultilineText} — the value is a BODY whose line breaks are
+ *    the author's own paragraphs and must survive: post text, bios/summaries.
+ *    Line breaks are preserved (capped at one blank line); only the surrounding
+ *    whitespace noise is cleaned.
+ *
+ * Using the multiline helper on a title would keep the newlines and reproduce
+ * the original bug; using the inline helper on a post body would flatten the
+ * author's paragraphs into a single run-on line. Pick deliberately.
+ *
+ * Neither helper truncates, strips markup, or enforces a character policy —
+ * those are separate, product-specific concerns (see `isValidDisplayName` for
+ * the display-name character policy). These functions do exactly one thing:
+ * normalize whitespace and Unicode form.
+ */
+/** Any run of whitespace, including tabs, line breaks and Unicode spaces. */
+const ANY_WHITESPACE_RUN = /\s+/g;
+/**
+ * Every line-break form, unified to `\n` before the multiline passes run:
+ * CRLF (Windows), a lone CR (classic Mac / stray `\r`), and the Unicode LINE
+ * SEPARATOR (U+2028) / PARAGRAPH SEPARATOR (U+2029), which are mandatory breaks
+ * in Unicode and a well-known hazard in JSON/JS payloads. CRLF must be matched
+ * before the lone `\r` alternative or it would yield two breaks. The separators
+ * are matched by their code-point ESCAPES (`\u2028` = LINE SEPARATOR, `\u2029` =
+ * PARAGRAPH SEPARATOR) rather than by their Unicode Line_Separator /
+ * Paragraph_Separator property escapes: React Native's Hermes engine ships with
+ * Unicode property escapes compiled OUT and rejects those subcategory property
+ * names with "Invalid RegExp: Invalid property name", whereas the `\uXXXX`
+ * escapes are exactly equivalent (each property covers exactly its one code
+ * point), engine-portable, and drop the now-unneeded `u` flag. (A literal
+ * U+2028/U+2029 is itself a LineTerminator and cannot appear in a regex literal.)
+ */
+const LINE_BREAK_FORMS = /\r\n|\r|\u2028|\u2029/g;
+/**
+ * A run of HORIZONTAL whitespace: any whitespace that is not a line break.
+ * `[^\S\n]` is "whitespace, minus `\n`" — it covers the tab, the vertical tab,
+ * the form feed and every Unicode space separator (NBSP U+00A0, the U+2000
+ * block, the ideographic space U+3000, the zero-width no-break space U+FEFF).
+ * Applied AFTER {@link LINE_BREAK_FORMS}, so no line break can hide in it.
+ */
+const HORIZONTAL_WHITESPACE_RUN = /[^\S\n]+/g;
+/**
+ * Horizontal whitespace at the END of a line — the blank-line spoiler: it is
+ * what makes an "empty" line non-empty and hides it from {@link EXCESS_BLANK_LINES}.
+ */
+const TRAILING_HORIZONTAL_WHITESPACE = / +\n/g;
+/**
+ * Horizontal whitespace at the START of a line: source-markup indentation. HTML
+ * collapses it by spec, so it is invisible where the text came from and carries
+ * no meaning — it only becomes visible once a client renders the value with
+ * `white-space: pre-wrap`.
+ */
+const LEADING_HORIZONTAL_WHITESPACE = /\n +/g;
+/** Three or more line breaks: more than one blank line between paragraphs. */
+const EXCESS_BLANK_LINES = /\n{3,}/g;
+/**
+ * Normalize a SINGLE-LINE text value: page/link-preview titles, `siteName`,
+ * display names, image alt text, handles, profile field labels.
+ *
+ * A line break in such a value is never meaningful — it is an artifact of the
+ * markup the value was extracted from (`<title>\n  Título\n</title>`) — and it
+ * survives into the UI because RN Web renders `Text` with `white-space:
+ * pre-wrap`. So ALL whitespace, line breaks included, collapses to one space.
+ *
+ *   1. NFC-normalize, so visually identical strings store and compare
+ *      identically (a decomposed `e`+◌́ recomposes into `é`).
+ *   2. Collapse every run of whitespace — spaces, tabs, `\n`, `\r`, and Unicode
+ *      spaces such as NBSP — to a single plain space.
+ *   3. Trim both ends.
+ *
+ * Length is NOT capped: a maximum length is a product rule of the specific
+ * field (see `MAX_DISPLAY_NAME_LENGTH`), not a property of text normalization.
+ * Markup is NOT stripped: run the caller's sanitizer first if the source can
+ * contain HTML.
+ *
+ * A value that is empty or whitespace-only returns `''`. Callers decide whether
+ * that means "omit the field" (`|| undefined`) or "store an empty string".
+ *
+ * Idempotent: `f(f(x)) === f(x)`.
+ */
+export function normalizeInlineText(value) {
+    return value.normalize('NFC').replace(ANY_WHITESPACE_RUN, ' ').trim();
+}
+/**
+ * Normalize a MULTILINE text BODY: post text, bios, summaries — anywhere the
+ * line breaks are the author's paragraphs and must be preserved.
+ *
+ * Cleans the whitespace noise around those paragraphs without destroying them:
+ *
+ *   1. NFC-normalize (same rationale as {@link normalizeInlineText}).
+ *   2. Unify every line-break form (CRLF, lone CR, U+2028, U+2029) to `\n`.
+ *   3. Collapse runs of HORIZONTAL whitespace (spaces, tabs, NBSP and friends)
+ *      to a single space. Line breaks are untouched.
+ *   4. Strip the horizontal whitespace at BOTH ends of every line.
+ *   5. Collapse three or more line breaks to exactly one blank line (`\n\n`).
+ *   6. Trim both ends of the value.
+ *
+ * STEP 4 MUST PRECEDE STEP 5 — this is the whole point of the function. A
+ * "blank" line that actually contains spaces (`"a\n   \n   \nb"`) breaks the
+ * run of `\n` characters, so a bare `\n{3,}` collapse (step 5 alone) never sees
+ * it and the extra blank lines survive into the UI. That is exactly the bug in
+ * federated post bodies. Trimming each line first turns those lines into real,
+ * empty lines, which step 5 then collapses.
+ *
+ * Every line is trimmed on BOTH sides, so a leading indent is removed outright
+ * rather than reduced to one space. Step 3 has already destroyed whatever indent
+ * the author wrote (`"      Mundo"` → `" Mundo"`), so a surviving space would not
+ * be the author's intent — it would be an arbitrary remnant of exactly the
+ * source-markup indentation this function exists to erase, and `pre-wrap` renders
+ * it. Indentation is invisible in HTML by spec; it must be invisible here too.
+ *
+ * A value that is empty or whitespace-only returns `''`.
+ *
+ * Idempotent: `f(f(x)) === f(x)`.
+ */
+export function normalizeMultilineText(value) {
+    return value
+        .normalize('NFC')
+        .replace(LINE_BREAK_FORMS, '\n')
+        .replace(HORIZONTAL_WHITESPACE_RUN, ' ')
+        .replace(TRAILING_HORIZONTAL_WHITESPACE, '\n')
+        .replace(LEADING_HORIZONTAL_WHITESPACE, '\n')
+        .replace(EXCESS_BLANK_LINES, '\n\n')
+        .trim();
+}

package/dist/esm/utils/userHandle.js

@@ -0,0 +1,33 @@
+function normalizeHandlePart(value) {
+    const trimmed = value?.trim().replace(/^@+/, '');
+    if (!trimmed || /[/?#]/.test(trimmed))
+        return null;
+    return trimmed;
+}
+/**
+ * Returns the normalized profile handle used by Oxy consumers for display and
+ * profile routing.
+ *
+ * Local users resolve to `username`. Federated users resolve to
+ * `username@instance` when the username does not already include an instance.
+ * Route-like values are rejected so callers do not accidentally turn paths or
+ * query strings into profile destinations.
+ */
+export function getNormalizedUserHandle(user) {
+    const username = normalizeHandlePart(user?.username ?? user?.handle);
+    if (!username)
+        return null;
+    const isFederated = user?.isFederated === true || user?.type === 'federated';
+    const instance = normalizeHandlePart(user?.instance ?? user?.federation?.domain);
+    if (isFederated && instance && !username.includes('@')) {
+        return `${username}@${instance}`;
+    }
+    return username;
+}
+/**
+ * Compatibility alias for the first public name shipped with this helper.
+ * Prefer {@link getNormalizedUserHandle} in new code.
+ */
+export function getCanonicalUserHandle(user) {
+    return getNormalizedUserHandle(user);
+}

package/dist/esm/utils/userIdentity.js

@@ -0,0 +1,45 @@
+function stringifyIdentity(value) {
+    if (typeof value === 'string') {
+        const trimmed = value.trim();
+        return trimmed.length > 0 ? trimmed : null;
+    }
+    if (typeof value === 'number' && Number.isFinite(value)) {
+        return String(value);
+    }
+    if (value && typeof value === 'object' && 'toString' in value) {
+        const toStringFn = value.toString;
+        if (typeof toStringFn === 'function' && toStringFn !== Object.prototype.toString) {
+            const rendered = toStringFn.call(value);
+            if (typeof rendered === 'string') {
+                const trimmed = rendered.trim();
+                return trimmed.length > 0 && trimmed !== '[object Object]' ? trimmed : null;
+            }
+        }
+    }
+    return null;
+}
+/**
+ * Returns the stable SDK user id from API payloads that may use either `id` or
+ * Mongo-style `_id`.
+ */
+export function getNormalizedUserId(user) {
+    if (!user) {
+        return null;
+    }
+    return stringifyIdentity(user.id) ?? stringifyIdentity(user._id);
+}
+/**
+ * Normalizes a user payload to always expose `id`. Throws when the payload does
+ * not contain a usable id, because SDK callers should never receive anonymous
+ * user objects from authenticated identity endpoints.
+ */
+export function normalizeUserIdentity(user) {
+    const id = getNormalizedUserId(user);
+    if (!id) {
+        throw new Error('User response missing id');
+    }
+    return { ...user, id };
+}
+export function normalizeUserIdentityOrNull(user) {
+    return user ? normalizeUserIdentity(user) : null;
+}