@oxy.so/core 1.0.0

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

@@ -0,0 +1,157 @@
+/**
+ * OAuth 2.0 Authorization Code + PKCE helpers for "Sign in with Oxy" third-party
+ * sign-in.
+ *
+ * Third-party Relying Parties (SPAs, static sites, and native apps that are NOT
+ * Oxy first-party) authenticate through the standard OAuth flow against
+ * `auth.oxy.so/authorize` — never FedCM, SSO bounces, or Oxy session cookies.
+ * Public clients (no secret) prove possession of the authorization code with
+ * PKCE (RFC 7636, S256): the RP generates a random `code_verifier`, sends its
+ * `code_challenge = BASE64URL(SHA-256(code_verifier))` on the authorize
+ * redirect, and later replays the raw verifier on the token exchange.
+ *
+ * All cross-platform crypto (random bytes, SHA-256) is delegated to the shared
+ * `@oxy.so/protocol` platform loaders — the exact primitives the rest of core's
+ * crypto already uses — so these helpers run identically on web, Node, and
+ * React Native. No `require()`, so the ESM build stays bundler-clean.
+ */
+/** The central Oxy IdP authorization endpoint used by default. */
+export declare const OXY_AUTHORIZE_URL = "https://auth.oxy.so/authorize";
+/** Default OAuth scope requested for a "Sign in with Oxy" third-party flow. */
+export declare const DEFAULT_OAUTH_SCOPE = "openid profile";
+/** A generated PKCE verifier/challenge pair. */
+export interface PkcePair {
+    /** The high-entropy secret replayed on the token exchange (kept client-side). */
+    codeVerifier: string;
+    /** `BASE64URL(SHA-256(codeVerifier))` — sent on the authorize redirect. */
+    codeChallenge: string;
+    /** The PKCE transformation method. Always `S256`. */
+    method: 'S256';
+}
+/** Parameters for {@link buildOAuthAuthorizeUrl}. */
+export interface BuildOAuthAuthorizeUrlParams {
+    /** Authorize endpoint; defaults to {@link OXY_AUTHORIZE_URL}. */
+    authorizeBaseUrl?: string;
+    /** The registered `ApplicationCredential` public key (`oxy_dk_…`). */
+    clientId: string;
+    /** Exact registered redirect URI to return the authorization code to. */
+    redirectUri: string;
+    /** Requested scope; defaults to {@link DEFAULT_OAUTH_SCOPE}. */
+    scope?: string;
+    /** Opaque CSRF token from {@link generateOAuthState}. */
+    state: string;
+    /** The PKCE `codeChallenge` from {@link generatePkcePair}. */
+    codeChallenge: string;
+    /**
+     * OAuth `prompt` parameter — `login` forces a fresh authentication even when
+     * the IdP already has a session, `consent` forces the consent screen even for
+     * an already-granted scope. Both are ordinary OAuth/OIDC and are here for
+     * third-party relying parties building their own authorize link.
+     *
+     * `'none'` is deliberately NOT in this union. It is the silent-SSO value, and
+     * it was the only value this SDK ever sent — from the cold-boot cross-origin
+     * restore deleted in #691 phase 7b. Accepting it again would hand consumers a
+     * one-line rebuild of the automatic, gesture-less full-page bounce to the IdP
+     * that the popup transport exists to eliminate.
+     */
+    prompt?: 'login' | 'consent';
+    /**
+     * How the IdP should deliver the authorization response. Omitted (the
+     * default) means the ordinary top-level redirect back to `redirectUri`.
+     *
+     * `web_message` asks the IdP to `postMessage` the result to its opener
+     * instead, so a popup sign-in never navigates the relying party's tab. It is
+     * a REQUEST, not a guarantee: an IdP with no opener still redirects, which is
+     * why the popup transport must handle both outcomes. Only the authorization
+     * code, the `state`, and a typed OAuth error ever cross that channel — never
+     * a token, device secret, or the PKCE verifier, which the opener keeps.
+     */
+    responseMode?: 'web_message';
+}
+/**
+ * Compute the PKCE S256 `code_challenge` for a given verifier:
+ * `BASE64URL(SHA-256(ASCII(codeVerifier)))` (RFC 7636 §4.2). The verifier is
+ * base64url (ASCII), so its UTF-8 and ASCII byte encodings are identical.
+ *
+ * Reuses `@oxy.so/protocol`'s cross-platform {@link sha256} (which returns
+ * lowercase hex); the digest bytes are recovered and re-encoded as base64url.
+ */
+export declare function computeCodeChallenge(codeVerifier: string): Promise<string>;
+/**
+ * Generate a fresh PKCE verifier/challenge pair for an OAuth authorization-code
+ * flow. The verifier is 64 random bytes as base64url (86 chars, within RFC 7636
+ * §4.1's 43–128 range and drawn only from the unreserved set); the challenge is
+ * its S256 transform.
+ */
+export declare function generatePkcePair(): Promise<PkcePair>;
+/**
+ * Generate an opaque, single-use OAuth `state` token (32 random bytes as
+ * base64url) for CSRF protection across the authorize redirect.
+ */
+export declare function generateOAuthState(): Promise<string>;
+/**
+ * Build the `auth.oxy.so/authorize` redirect URL for an OAuth authorization-code
+ * + PKCE (S256) flow. Built via the WHATWG `URL` API so a custom
+ * `authorizeBaseUrl` that already carries a query string keeps its existing
+ * params (the OAuth params are merged in, not clobbered by a naive `?` concat).
+ * All values are percent-encoded by `URL.searchParams`.
+ */
+export declare function buildOAuthAuthorizeUrl(params: BuildOAuthAuthorizeUrlParams): string;
+/** `sessionStorage` key for the OAuth CSRF `state` across an authorize redirect. */
+export declare const OXY_OAUTH_STATE_STORAGE_KEY = "oxy_oauth_state";
+/** `sessionStorage` key for the PKCE `code_verifier` across an authorize redirect. */
+export declare const OXY_OAUTH_CODE_VERIFIER_STORAGE_KEY = "oxy_oauth_code_verifier";
+/** `sessionStorage` key — the exact `redirect_uri` sent on the authorize request. */
+export declare const OXY_OAUTH_REDIRECT_URI_STORAGE_KEY = "oxy.oauth_redirect_uri";
+/**
+ * `sessionStorage` key for the in-app path to return to after an authorize
+ * round trip. See {@link persistOAuthReturnPath}.
+ */
+export declare const OXY_OAUTH_RETURN_PATH_STORAGE_KEY = "oxy.oauth_return_path";
+/**
+ * Normalize a redirect URI to its origin. Official Oxy apps register apex
+ * origins (`https://inbox.oxy.so`) — never path-qualified URLs.
+ *
+ * This is why the path cannot ride along in `redirect_uri`, and why
+ * {@link persistOAuthReturnPath} exists: the authorize round trip always lands
+ * back on the bare origin, so the page the user was on has to be carried
+ * out-of-band and restored on return.
+ */
+export declare function normalizeOAuthRedirectUri(input: string): string;
+/**
+ * Collapse `https://app.example/` → `https://app.example` for OAuth binding.
+ * Path-qualified redirect URIs are preserved — matches the API token exchange.
+ */
+export declare function canonicalizeOAuthRedirectUri(redirectUri: string): string;
+/**
+ * Remember the page the user was on before a full-page authorize redirect.
+ *
+ * Silent cross-origin restore navigates the whole tab to the IdP and back, and
+ * `redirect_uri` must be a registered apex origin, so the browser returns to
+ * `/` no matter which page the visit started on. Without this, every deep link
+ * — a shared URL, a search result, an ad landing page — silently became the
+ * home page for signed-out visitors on their first navigation in a tab.
+ *
+ * Stored next to the PKCE handshake it belongs to, and cleared by
+ * {@link clearOAuthHandshake} so a stale entry can never be applied to an
+ * unrelated later navigation.
+ */
+export declare function persistOAuthReturnPath(path: string): void;
+/**
+ * Read and remove the persisted return path, or `null` when there is none or
+ * it failed validation.
+ *
+ * Single-use by design: it is consumed on the first return so a leftover value
+ * cannot redirect a later navigation in the same tab.
+ */
+export declare function consumeOAuthReturnPath(): string | null;
+/** Persist the OAuth handshake for a full-page redirect return (web only). */
+export declare function persistOAuthHandshake(state: string, codeVerifier: string, redirectUri?: string): boolean;
+/** Read the persisted OAuth handshake, or `null` when absent. */
+export declare function readOAuthHandshake(): {
+    state: string;
+    codeVerifier: string;
+    redirectUri?: string;
+} | null;
+/** Drop persisted OAuth handshake keys after a successful or aborted return. */
+export declare function clearOAuthHandshake(): void;

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

@@ -0,0 +1,13 @@
+/**
+ * Official first-party web origin allowlist — shared by OAuth redirect
+ * validation and the server-side trusted-origin checks.
+ */
+/**
+ * Whether an origin is a loopback / local-dev origin (`localhost`, `127.0.0.1`,
+ * or `[::1]` on any port, http or https).
+ */
+export declare function isLoopbackOrigin(origin: string): boolean;
+/** Whether an origin belongs to the official Oxy web ecosystem. */
+export declare function isOfficialWebOrigin(origin: string): boolean;
+/** @deprecated Use {@link isOfficialWebOrigin}. */
+export declare const isAllowedDeviceJoinOrigin: typeof isOfficialWebOrigin;

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

@@ -0,0 +1,17 @@
+/**
+ * Environment segregation for Oxy service-token JWTs (test/live isolation).
+ * Mirrors `ApplicationCredentialEnvironment` on the API's `ApplicationCredential`
+ * model (`packages/api/src/models/ApplicationCredential.ts`) as an INDEPENDENT
+ * literal union — `@oxy.so/core` has zero dependency on `@oxy.so/api`, so this is
+ * kept in sync by hand, not by import.
+ *
+ * Defined here (not in `server/auth.ts` or `mixins/OxyServices.utility.ts`
+ * directly) because BOTH of those files need it and neither may import from
+ * the other: `server/` types import `express` (Node-only, a peer dependency
+ * `mixins/` deliberately avoids so it stays safe to bundle into RN/browser
+ * consumers — see the "Local request/response/socket typing" comment in
+ * `OxyServices.utility.ts`). This file has zero imports, so both sides can
+ * depend on it without crossing that boundary.
+ */
+export declare const OXY_SERVICE_ENVIRONMENTS: readonly ["development", "staging", "production"];
+export type OxyServiceEnvironment = (typeof OXY_SERVICE_ENVIRONMENTS)[number];

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

@@ -0,0 +1,49 @@
+/**
+ * Platform Detection Utility
+ *
+ * Provides platform detection WITHOUT importing from 'react-native'.
+ * This allows core modules to be used in web/Node.js environments
+ * without bundlers failing on react-native imports.
+ */
+export type PlatformOS = 'ios' | 'android' | 'web' | 'windows' | 'macos' | 'unknown';
+/**
+ * Get the current platform OS
+ * Safe to call from any environment (web, Node.js, React Native)
+ */
+export declare function getPlatformOS(): PlatformOS;
+/**
+ * Check if running on web platform (browser or Node.js)
+ */
+export declare function isWeb(): boolean;
+/**
+ * Check if running in a native app (iOS or Android)
+ */
+export declare function isNative(): boolean;
+/**
+ * Check if running on iOS
+ */
+export declare function isIOS(): boolean;
+/**
+ * Check if running on Android
+ */
+export declare function isAndroid(): boolean;
+/**
+ * Set the platform OS explicitly
+ * Called by React Native entry point to register the platform
+ * This allows lazy detection in environments where react-native is available
+ */
+export declare function setPlatformOS(os: PlatformOS): void;
+/**
+ * True only in a real web browser (a DOM is present), false on React Native
+ * and Node/SSR.
+ *
+ * Native defines a global `window` but no `document`, so the DOM probe — not a
+ * bare `window` check — is the reliable discriminator. This is the single
+ * source of truth consumed by `@oxy.so/services` (which dropped
+ * their local copies), so every consumer shares the exact same predicate.
+ *
+ * NOTE: this is a live runtime probe (not the cached `getPlatformOS()` verdict)
+ * because it must reflect the actual DOM availability at call time in the
+ * consumer's bundle.
+ */
+export declare function isWebBrowser(): boolean;

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

@@ -0,0 +1,44 @@
+/**
+ * Normalized profile link shape for display.
+ *
+ * `id` is a stable key for list rendering (the source entry's id when present,
+ * otherwise the source index as a string). `url` is always a non-empty string.
+ * `title`, `description`, and `image` are carried through from `linksMetadata`
+ * only when present; the legacy `links: string[]` path produces just
+ * `{ id, url }`.
+ */
+export interface ProfileLink {
+    id: string;
+    title?: string;
+    url: string;
+    description?: string;
+    image?: string;
+}
+/** Source shape of a single `User.linksMetadata` entry. */
+export interface ProfileLinkMetadata {
+    url: string;
+    title?: string;
+    description?: string;
+    image?: string;
+    id?: string;
+}
+/**
+ * Normalizes a user's profile links into a clean display shape.
+ *
+ * Pure, no side effects, no I/O.
+ *
+ * - Prefers `linksMetadata` when it is a non-empty array: maps each entry to
+ *   `{ id, title, url, description, image }`, using `entry.id` when present and
+ *   falling back to the entry index. `title`, `description`, and `image` are
+ *   carried through only when they are present strings. Entries without a
+ *   non-empty string `url` are dropped.
+ * - Otherwise falls back to the legacy `links` string array: maps each string to
+ *   `{ id: <index>, url }` (no title/description/image). Empty/non-string values
+ *   are dropped.
+ * - Returns `[]` when both are absent or empty (including when `linksMetadata`
+ *   is present but every entry is dropped — it does NOT fall back to `links`).
+ *
+ * URLs are trimmed and blanks are filtered out. This does NOT add a scheme such
+ * as `https://`; prefixing is a display concern left to the caller.
+ */
+export declare function normalizeProfileLinks(linksMetadata?: ProfileLinkMetadata[], links?: string[]): ProfileLink[];

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

@@ -0,0 +1,17 @@
+/**
+ * URL redaction for logging.
+ *
+ * Asset URLs the API hands back for private assets carry a scoped, short-lived
+ * media token (`mt=…`) in their query string. That token is a bearer credential
+ * for the underlying object, so it must never land in a log line, breadcrumb,
+ * or metric — a captured log would otherwise grant read access until the token
+ * expires. Query strings on API URLs can also carry other sensitive params, so
+ * we redact the whole query rather than allow-listing one key.
+ *
+ * `redactUrlQuery` returns the URL's path portion with a `?<redacted>` marker
+ * when a query string is present, and the input unchanged otherwise. It is
+ * defensive: any input that does not parse as a URL is passed through as-is,
+ * except that a bare `?query` tail is still stripped so a relative path with a
+ * query never leaks.
+ */
+export declare function redactUrlQuery(url: string): string;

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

@@ -0,0 +1,27 @@
+/**
+ * Registrable-apex (eTLD+1) host kernel.
+ *
+ * The client FAPI auto-detection helper was removed in the device-first cutover
+ * (which is why this file is now named for what it actually is, not the old
+ * `fapiAutoDetect`). What survives is the pure registrable-domain kernel, still
+ * used by the `@oxy.so/core/server` CORS layer (the `*.oxy.so` same-apex trust
+ * check) and its re-export surface.
+ */
+/**
+ * Compute the bare registrable apex (eTLD+1) of a hostname using the Public
+ * Suffix List, including private hosted suffixes.
+ *
+ * Performs NO protocol handling and builds NO URL — it only answers "what is
+ * the registrable domain of this host, or is that undefinable?".
+ *
+ * Returns `null` (apex undefinable) for:
+ *   - empty input;
+ *   - IPv4 literals (`192.168.1.10`);
+ *   - IPv6 literals or any host carrying a port (`[::1]`, anything with `:`);
+ *   - single-label hosts (`intranet`, `localhost`);
+ *   - public suffixes without a registrable label (e.g. `co.uk`, `github.io`).
+ *
+ * @param hostname - A bare hostname (no scheme), e.g. `www.mention.earth`.
+ * @returns The eTLD+1 (`mention.earth`), or `null` when undefinable.
+ */
+export declare function registrableApex(hostname: string): string | null;

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

@@ -0,0 +1,123 @@
+/**
+ * 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 declare class RequestDeduplicator {
+    private pendingRequests;
+    /**
+     * 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
+     */
+    deduplicate<T>(key: string, requestFn: () => Promise<T>): Promise<T>;
+    /**
+     * Clear all pending requests
+     */
+    clear(): void;
+    /**
+     * Get number of pending requests
+     */
+    size(): number;
+}
+/**
+ * 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 declare class RequestQueue {
+    private queue;
+    private running;
+    private maxConcurrent;
+    private maxQueueSize;
+    /**
+     * Create a new request queue
+     * @param maxConcurrent Maximum number of concurrent requests (default: 10)
+     * @param maxQueueSize Maximum queue size (default: 100)
+     */
+    constructor(maxConcurrent?: number, maxQueueSize?: number);
+    /**
+     * Enqueue a request
+     * @param requestFn Function that returns a promise
+     * @returns Promise that resolves when request completes
+     */
+    enqueue<T>(requestFn: () => Promise<T>): Promise<T>;
+    /**
+     * Process queued requests
+     */
+    private process;
+    /**
+     * Clear all queued requests
+     */
+    clear(): void;
+    /**
+     * Get queue size
+     */
+    size(): number;
+    /**
+     * Get number of currently running requests
+     */
+    runningCount(): number;
+}
+/** Log level type for SimpleLogger */
+export type LogLevel = 'none' | 'error' | 'warn' | 'info' | 'debug';
+/**
+ * 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 declare class SimpleLogger {
+    private enabled;
+    private level;
+    private prefix;
+    /**
+     * 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?: boolean, level?: LogLevel, prefix?: string);
+    private shouldLog;
+    private formatMessage;
+    error(...args: any[]): void;
+    warn(...args: any[]): void;
+    info(...args: any[]): void;
+    debug(...args: any[]): void;
+}

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

@@ -0,0 +1,54 @@
+/**
+ * Session management utilities
+ *
+ * Provides consistent session normalization, deduplication, and sorting
+ * to ensure sessions are always displayed in a predictable order.
+ */
+import type { ClientSession } from '../models/session';
+/**
+ * Normalize a session to ensure all required fields are present
+ */
+export declare function normalizeSession(session: Partial<ClientSession> & {
+    sessionId: string;
+}): ClientSession;
+/**
+ * Compare two sessions for equality
+ */
+export declare function sessionsEqual(a: ClientSession, b: ClientSession): boolean;
+/**
+ * Sort sessions by lastActive (most recent first), then by sessionId for stability
+ */
+export declare function sortSessions(sessions: ClientSession[]): ClientSession[];
+/**
+ * Deduplicate sessions by sessionId, keeping the most recent version
+ */
+export declare function deduplicateSessions(sessions: ClientSession[]): ClientSession[];
+/**
+ * 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 declare function deduplicateSessionsByUserId(sessions: ClientSession[], activeSessionId?: string | null): ClientSession[];
+/**
+ * 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 declare function normalizeAndSortSessions(sessions: ClientSession[], activeSessionId?: string | null, deduplicateByUserId?: boolean): ClientSession[];
+/**
+ * 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 declare function mergeSessions(existing: ClientSession[], incoming: ClientSession[], activeSessionId?: string | null, deduplicateByUserId?: boolean): ClientSession[];
+/**
+ * Check if two session arrays are equal (same sessionIds in same order)
+ */
+export declare function sessionsArraysEqual(a: ClientSession[], b: ClientSession[]): boolean;

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

@@ -0,0 +1,103 @@
+/**
+ * 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.
+ */
+/**
+ * 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 declare function normalizeInlineText(value: string): string;
+/**
+ * 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 declare function normalizeMultilineText(value: string): string;

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

@@ -0,0 +1,26 @@
+export interface UserHandleInput {
+    username?: string | null;
+    handle?: string | null;
+    instance?: string | null;
+    isFederated?: boolean | null;
+    type?: string | null;
+    federation?: {
+        domain?: string | null;
+    } | null;
+}
+export type CanonicalUserHandleInput = UserHandleInput;
+/**
+ * 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 declare function getNormalizedUserHandle(user: UserHandleInput | null | undefined): string | null;
+/**
+ * Compatibility alias for the first public name shipped with this helper.
+ * Prefer {@link getNormalizedUserHandle} in new code.
+ */
+export declare function getCanonicalUserHandle(user: CanonicalUserHandleInput | null | undefined): string | null;

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

@@ -0,0 +1,21 @@
+interface UserIdentityInput {
+    id?: unknown;
+    _id?: unknown;
+}
+/**
+ * Returns the stable SDK user id from API payloads that may use either `id` or
+ * Mongo-style `_id`.
+ */
+export declare function getNormalizedUserId(user: UserIdentityInput | null | undefined): string | null;
+/**
+ * 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 declare function normalizeUserIdentity<T extends UserIdentityInput>(user: T): T & {
+    id: string;
+};
+export declare function normalizeUserIdentityOrNull<T extends UserIdentityInput>(user: T | null | undefined): (T & {
+    id: string;
+}) | null;
+export {};