@oxy.so/core 1.0.0

package/dist/esm/OxyServices.base.js

@@ -0,0 +1,386 @@
+/**
+ * OxyServices Base Class
+ *
+ * Contains core infrastructure, HTTP client, request management, and error handling
+ */
+import { jwtDecode } from 'jwt-decode';
+import { handleHttpError } from './utils/errorUtils.js';
+import { HttpService } from './HttpService.js';
+import { OxyAuthenticationError, OxyAuthenticationTimeoutError } from './OxyServices.errors.js';
+/**
+ * Base class for OxyServices with core infrastructure
+ */
+export class OxyServicesBase {
+    constructor(...args) {
+        /** @internal */ this._cachedUserId = undefined;
+        /** @internal */ this._cachedAccessToken = null;
+        const config = args[0];
+        if (!config || typeof config !== 'object') {
+            throw new Error('OxyConfig is required');
+        }
+        // `authWebUrl` is a plain optional config value now (used only for building
+        // third-party "Sign in with Oxy" OAuth links). The SDK no longer derives or
+        // defaults an IdP host — the device-first cold boot restores sessions from
+        // the persisted refresh store, not an `auth.<apex>` bounce.
+        this.config = config;
+        this.cloudURL = config.cloudURL || 'https://cloud.oxy.so';
+        // Initialize unified HTTP service (handles auth, caching, deduplication, queuing, retry)
+        this.httpService = new HttpService(config);
+    }
+    // Test-only utility to reset tokens on this instance between jest tests
+    // Note: tokens are now per-instance, so create new instances in tests for isolation
+    __resetTokensForTests() {
+        this.httpService.__resetTokensForTests();
+    }
+    /**
+     * Make a request with all performance optimizations
+     * This is the main method for all API calls - ensures authentication and performance features
+     */
+    async makeRequest(method, url, data, options = {}) {
+        return this.httpService.request({
+            method,
+            url,
+            data: method !== 'GET' ? data : undefined,
+            params: method === 'GET' ? data : undefined,
+            ...options,
+        });
+    }
+    // ============================================================================
+    // CORE METHODS (HTTP Client, Token Management, Error Handling)
+    // ============================================================================
+    /**
+     * Get the configured Oxy API base URL
+     */
+    getBaseURL() {
+        return this.httpService.getBaseURL();
+    }
+    /**
+     * Get the HTTP service instance
+     * Useful for advanced use cases where direct access to the HTTP service is needed
+     */
+    getClient() {
+        return this.httpService;
+    }
+    /**
+     * Create an app/backend HTTP client linked to this Oxy session.
+     *
+     * Use this when an app has its own API origin (for example
+     * `https://api.syra.fm`) but authentication is owned by the canonical
+     * OxyServices instance mounted in OxyProvider. The returned client has its own
+     * base URL, cache and request queue, but its bearer token is kept in lockstep
+     * with this session and its 401 refresh path delegates back to this session.
+     *
+     * **GET response caching is OFF by default for linked clients.** The SDK's
+     * per-instance GET cache is only safe where the SDK OWNS invalidation: on the
+     * canonical OxyServices client, every mutation (`updateProfile`, `followUser`,
+     * `blockUser`, …) busts the matching cached GET. A linked client targets the
+     * consuming app's OWN backend (`api.mention.earth`, `api.syra.fm`, …), whose
+     * resources and write endpoints the SDK has no knowledge of — so it cannot
+     * invalidate them, and a cached GET there would silently serve stale data
+     * after the app mutates its own data. Caching is therefore unsafe-by-construction
+     * here and is left to the consumer's own layer (React Query / stores), which
+     * owns its invalidation. Pass `createLinkedClient({ baseURL, enableCache: true })`
+     * to explicitly opt back in when the consumer accepts that responsibility.
+     */
+    createLinkedClient(config) {
+        // Default the GET cache OFF unless the caller explicitly opts in (see the
+        // method doc): the SDK cannot invalidate the consumer backend's resources.
+        const client = new HttpService({ ...config, enableCache: config.enableCache ?? false });
+        const syncToken = (accessToken) => {
+            const currentAccessToken = client.getAccessToken();
+            if (accessToken) {
+                if (currentAccessToken !== accessToken) {
+                    client.setTokens(accessToken);
+                }
+                return;
+            }
+            if (currentAccessToken) {
+                client.clearTokens();
+            }
+        };
+        syncToken(this.getAccessToken());
+        const unsubscribe = this.onTokensChanged(syncToken);
+        client.setAccessTokenProvider(() => this.getAccessToken());
+        client.setAuthRefreshHandler(async (reason) => {
+            const refreshed = await this.httpService.refreshAccessToken(reason);
+            if (!refreshed) {
+                return null;
+            }
+            syncToken(refreshed);
+            return refreshed;
+        });
+        return {
+            client,
+            dispose: () => {
+                unsubscribe();
+                client.setAuthRefreshHandler(null);
+                client.setAccessTokenProvider(null);
+                client.clearTokens();
+            },
+        };
+    }
+    /**
+     * Get performance metrics
+     */
+    getMetrics() {
+        return this.httpService.getMetrics();
+    }
+    /**
+     * Clear request cache
+     */
+    clearCache() {
+        this.httpService.clearCache();
+    }
+    /**
+     * Clear specific cache entry
+     */
+    clearCacheEntry(key) {
+        this.httpService.clearCacheEntry(key);
+    }
+    /**
+     * Clear every cache entry whose key starts with `prefix`.
+     * Useful for mutations that invalidate a family of GET responses
+     * without enumerating each one (e.g. all session-user lookups after
+     * a profile update).
+     */
+    clearCacheByPrefix(prefix) {
+        return this.httpService.clearCacheByPrefix(prefix);
+    }
+    /**
+     * Get cache statistics
+     */
+    getCacheStats() {
+        return this.httpService.getCacheStats();
+    }
+    /**
+     * Get the configured Oxy Cloud (file storage/CDN) URL
+     */
+    getCloudURL() {
+        return this.cloudURL;
+    }
+    /**
+     * Set authentication tokens
+     */
+    setTokens(accessToken) {
+        this.httpService.setTokens(accessToken);
+    }
+    /**
+     * Clear stored authentication tokens
+     */
+    clearTokens() {
+        this.httpService.clearTokens();
+        this._cachedUserId = undefined;
+        this._cachedAccessToken = null;
+    }
+    /**
+     * Subscribe to access-token changes on this client.
+     *
+     * The listener fires on every access-token mutation — explicit
+     * `setTokens`/`clearTokens`, a successful silent refresh, and the internal
+     * 401-driven clear — receiving the resulting token, or `null` when cleared.
+     * Returns an unsubscribe function.
+     *
+     * Primary use: keeping an external token sink (e.g. the shared `oxyClient`
+     * singleton) in lockstep with whichever `OxyServices` instance actually owns
+     * the session, so imperative consumers reading the singleton always observe
+     * the live token regardless of the code path that changed it.
+     */
+    onTokensChanged(listener) {
+        return this.httpService.addTokenChangeListener(listener);
+    }
+    /**
+     * Get the current user ID from the access token.
+     * Caches the decoded value and invalidates when the token changes.
+     */
+    getCurrentUserId() {
+        const accessToken = this.httpService.getAccessToken();
+        // Return cached value if token hasn't changed
+        if (accessToken === this._cachedAccessToken && this._cachedUserId !== undefined) {
+            return this._cachedUserId;
+        }
+        this._cachedAccessToken = accessToken;
+        if (!accessToken) {
+            this._cachedUserId = null;
+            return null;
+        }
+        try {
+            const decoded = jwtDecode(accessToken);
+            const userId = decoded.userId || decoded.id || null;
+            this._cachedUserId = userId;
+            return userId;
+        }
+        catch {
+            this._cachedUserId = null;
+            return null;
+        }
+    }
+    /**
+     * Check if the client has a valid access token (public method)
+     */
+    hasValidToken() {
+        return this.httpService.hasAccessToken();
+    }
+    /**
+     * Get the raw access token (for constructing anchor URLs when needed)
+     */
+    getAccessToken() {
+        return this.httpService.getAccessToken();
+    }
+    /**
+     * Decode the current access token and return its `exp` claim in SECONDS since
+     * the Unix epoch (the raw JWT `exp` unit), or `null` when there is no token,
+     * the token is opaque/undecodable, or it carries no numeric `exp`.
+     *
+     * Exposed so `@oxy.so/services` can schedule a PROACTIVE in-session refresh a
+     * fixed lead before expiry without re-importing a JWT decoder (and without
+     * duplicating the `jwt-decode` dependency in the RN bundle). HttpService keeps
+     * the per-request preflight refresh; this powers the idle/background timer.
+     */
+    getAccessTokenExpiry() {
+        const token = this.httpService.getAccessToken();
+        if (!token) {
+            return null;
+        }
+        try {
+            const decoded = jwtDecode(token);
+            return typeof decoded.exp === 'number' ? decoded.exp : null;
+        }
+        catch {
+            // A malformed / non-JWT token has no usable expiry — fall back to the
+            // reactive 401 refresh path instead of a scheduled one.
+            return null;
+        }
+    }
+    /**
+     * Wait for authentication to be ready
+     *
+     * Optimized for high-scale usage with immediate synchronous check and adaptive polling.
+     * Returns immediately if token is already available (0ms delay), otherwise uses
+     * adaptive polling that starts fast (50ms) and gradually increases to reduce CPU usage.
+     *
+     * @param timeoutMs Maximum time to wait in milliseconds (default: 5000ms)
+     * @returns Promise that resolves to true if authentication is ready, false if timeout
+     *
+     * @example
+     * ```typescript
+     * const isReady = await oxyServices.waitForAuth(3000);
+     * if (isReady) {
+     *   // Proceed with authenticated operations
+     * }
+     * ```
+     */
+    async waitForAuth(timeoutMs = 5000) {
+        // Immediate synchronous check - no delay if token is ready
+        if (this.httpService.hasAccessToken()) {
+            return true;
+        }
+        const startTime = performance.now();
+        const maxTime = startTime + timeoutMs;
+        // Adaptive polling: start fast, then slow down to reduce CPU usage
+        let pollInterval = 50; // Start with 50ms
+        while (performance.now() < maxTime) {
+            await new Promise(resolve => setTimeout(resolve, pollInterval));
+            if (this.httpService.hasAccessToken()) {
+                return true;
+            }
+            // Increase interval after first few checks (adaptive polling)
+            // This reduces CPU usage for long waits while maintaining responsiveness
+            if (pollInterval < 200) {
+                pollInterval = Math.min(pollInterval * 1.5, 200);
+            }
+        }
+        return false;
+    }
+    /**
+     * Execute a function with automatic authentication retry logic
+     * This handles the common case where API calls are made before authentication completes
+     */
+    async withAuthRetry(operation, operationName, options = {}) {
+        const { maxRetries = 2, retryDelay = 1000, authTimeoutMs = 5000 } = options;
+        for (let attempt = 0; attempt <= maxRetries; attempt++) {
+            try {
+                // First attempt: check if we have a token
+                if (!this.httpService.hasAccessToken()) {
+                    if (attempt === 0) {
+                        // On first attempt, wait briefly for authentication to complete
+                        const authReady = await this.waitForAuth(authTimeoutMs);
+                        if (!authReady) {
+                            throw new OxyAuthenticationTimeoutError(operationName, authTimeoutMs);
+                        }
+                    }
+                    else {
+                        // On retry attempts, fail immediately if no token
+                        throw new OxyAuthenticationError(`Authentication required: ${operationName} requires a valid access token.`, 'AUTH_REQUIRED');
+                    }
+                }
+                // Execute the operation
+                return await operation();
+            }
+            catch (error) {
+                const isLastAttempt = attempt === maxRetries;
+                const errorObj = error && typeof error === 'object' ? error : null;
+                const isAuthError = errorObj?.response?.status === 401 ||
+                    errorObj?.code === 'MISSING_TOKEN' ||
+                    errorObj?.message?.includes('Authentication') ||
+                    error instanceof OxyAuthenticationError;
+                if (isAuthError && !isLastAttempt && !(error instanceof OxyAuthenticationTimeoutError)) {
+                    await new Promise(resolve => setTimeout(resolve, retryDelay));
+                    continue;
+                }
+                // If it's not an auth error, or it's the last attempt, throw the error
+                if (error instanceof OxyAuthenticationError) {
+                    throw error;
+                }
+                throw this.handleError(error);
+            }
+        }
+        // This should never be reached, but TypeScript requires it
+        throw new OxyAuthenticationError(`${operationName} failed after ${maxRetries + 1} attempts`);
+    }
+    /**
+     * Validate the current access token with the server
+     */
+    async validate() {
+        if (!this.hasValidToken()) {
+            return false;
+        }
+        try {
+            const res = await this.makeRequest('GET', '/auth/validate', undefined, {
+                cache: false,
+                retry: false,
+            });
+            return res.valid === true;
+        }
+        catch (error) {
+            return false;
+        }
+    }
+    /**
+     * Centralized error handling
+     */
+    handleError(error) {
+        const api = handleHttpError(error);
+        // Ensure we always have a non-empty message
+        const message = api.message?.trim() || 'An unexpected error occurred';
+        const err = new Error(message);
+        err.code = api.code;
+        err.status = api.status;
+        err.details = api.details;
+        return err;
+    }
+    /**
+     * Health check endpoint
+     */
+    async healthCheck() {
+        try {
+            return await this.makeRequest('GET', '/health', undefined, {
+                cache: false,
+                retry: false,
+                timeout: 5000
+            });
+        }
+        catch (error) {
+            throw this.handleError(error);
+        }
+    }
+}

package/dist/esm/OxyServices.errors.js

@@ -0,0 +1,88 @@
+/**
+ * Custom error types for better error handling
+ */
+export class OxyAuthenticationError extends Error {
+    constructor(message, code = 'AUTH_ERROR', status = 401) {
+        super(message);
+        this.name = 'OxyAuthenticationError';
+        this.code = code;
+        this.status = status;
+    }
+}
+/**
+ * Thrown when an asset's authorized download URL cannot be resolved.
+ *
+ * `getFileDownloadUrlAsync` asks the API for a URL that is valid for the
+ * CALLER and the asset's actual visibility. When that resolution fails there is
+ * no honest fallback: the public CDN origin only serves `public` assets, so
+ * handing back `https://cloud.oxy.so/<id>` for an unresolved asset produces a
+ * hard 404 at render time and hides the real failure from the caller. This
+ * error surfaces the failure instead.
+ *
+ * The message and fields deliberately carry only the asset id, the requested
+ * variant and the HTTP status — never the resolved URL, which embeds a scoped
+ * media token.
+ *
+ * ## `status` lets a caller decide whether a CDN fallback is safe
+ *
+ * Core itself never falls back to the public CDN builder, because it has no
+ * knowledge of the asset's visibility and that URL is a guaranteed 404 for a
+ * private asset. A CALLER that knows an asset is public MAY choose to fall back
+ * to `getFileDownloadUrl(id, variant)` — but only for a TRANSIENT failure, not
+ * a definitive denial:
+ *   - `status` 401/403/404 → definitive: the asset is private/denied/missing.
+ *     Never CDN-fall-back — it will 404.
+ *   - `status` undefined (network error) or 5xx → transient: resolution itself
+ *     failed. If the caller independently knows the asset is public, a CDN
+ *     fallback is defensible best-effort.
+ */
+export class AssetUrlResolutionError extends Error {
+    constructor(fileId, variant, status, cause) {
+        const variantSuffix = variant ? ` (variant "${variant}")` : '';
+        const statusSuffix = typeof status === 'number' ? ` — status ${status}` : '';
+        super(`Could not resolve a download URL for asset "${fileId}"${variantSuffix}${statusSuffix}`);
+        this.code = 'ASSET_URL_UNRESOLVED';
+        this.name = 'AssetUrlResolutionError';
+        this.fileId = fileId;
+        this.variant = variant;
+        this.status = status;
+        this.cause = cause;
+    }
+}
+/**
+ * Thrown when one or more chunks of `getServiceAssetMetadataByIds` could not be
+ * resolved.
+ *
+ * Exists because for this endpoint a FAILED request and an ABSENT asset produce
+ * the same observable result. The server legitimately omits unknown/deleted ids,
+ * so callers are documented to map the response by `id` and treat a missing
+ * entry as "no such asset" — which means a chunk that 429s, times out or 5xxs
+ * reads as authoritative absence unless it is raised.
+ *
+ * That was not hypothetical: a metadata backfill counted every throttled asset
+ * as needing no update and exited 0, and the MTN signed-record builder embedded
+ * media with no content hash into records that are immutable once signed. Both
+ * paths reported success and wrote nothing.
+ *
+ * `unresolvedIds` carries every id in a failed chunk — not the subset the server
+ * would have omitted anyway, which is unknowable when the request never landed.
+ * A caller that wants best-effort passes `{ partial: true }` and never sees this.
+ */
+export class ServiceAssetMetadataError extends Error {
+    constructor(unresolvedIds, statuses, cause) {
+        const uniqueStatuses = Array.from(new Set(statuses)).sort((a, b) => a - b);
+        const statusSuffix = uniqueStatuses.length > 0 ? ` — status ${uniqueStatuses.join(', ')}` : '';
+        super(`Could not resolve asset metadata for ${unresolvedIds.length} id(s)${statusSuffix}. Treat this as unknown, not as absent; pass { partial: true } for best-effort.`);
+        this.code = 'SERVICE_ASSET_METADATA_UNRESOLVED';
+        this.name = 'ServiceAssetMetadataError';
+        this.unresolvedIds = unresolvedIds;
+        this.statuses = uniqueStatuses;
+        this.cause = cause;
+    }
+}
+export class OxyAuthenticationTimeoutError extends OxyAuthenticationError {
+    constructor(operationName, timeoutMs) {
+        super(`Authentication timeout (${timeoutMs}ms): ${operationName} requires user authentication. Please ensure the user is logged in before calling this method.`, 'AUTH_TIMEOUT', 408);
+        this.name = 'OxyAuthenticationTimeoutError';
+    }
+}

package/dist/esm/OxyServices.js

@@ -0,0 +1,66 @@
+import { AssetUrlResolutionError, OxyAuthenticationError, OxyAuthenticationTimeoutError, ServiceAssetMetadataError } from './OxyServices.errors.js';
+// Import mixin composition helper
+import { composeOxyServices } from './mixins/index.js';
+/**
+ * OxyServices - Unified client library for interacting with the Oxy API
+ *
+ * This class provides all API functionality in one simple, easy-to-use interface.
+ *
+ * ## Architecture
+ * - **HttpService**: Unified HTTP service handling authentication, caching, deduplication, queuing, and retry
+ * - **OxyServices**: Provides high-level API methods
+ *
+ * ## Mixin Composition
+ * The class is composed using TypeScript mixins for better code organization:
+ * - **Base**: Core infrastructure (HTTP client, request management, error handling)
+ * - **Auth**: Authentication and session management
+ * - **User**: User profiles, follow, notifications
+ * - **Privacy**: Blocked and restricted users
+ * - **Language**: Language detection and metadata
+ * - **Payment**: Payment processing
+ * - **Reputation**: Reputation system (Oxy Trust)
+ * - **Assets**: File upload and asset management
+ * - **Accounts**: Unified account graph (tree, members, roles, bot credentials)
+ *   and the applications owned within it (Application = OAuth client)
+ * - **Connected apps**: OAuth-consent surface (public app identity, grants)
+ * - **Location**: Location-based features
+ * - **Analytics**: Analytics tracking
+ * - **Devices**: Device management
+ * - **Utility**: Utility methods and Express middleware
+ *
+ * @example
+ * ```typescript
+ * const oxy = new OxyServices({
+ *   baseURL: 'https://api.oxy.so',
+ *   cloudURL: 'https://cloud.oxy.so'
+ * });
+ * ```
+ */
+// Compose all mixins into the final OxyServices class. The composed runtime
+// class augments OxyServicesBase with every mixin's methods (see mixins/index.ts).
+// Statically, TypeScript sees this as a constructor producing OxyServicesBase;
+// the additional methods are exposed via interface merging on `OxyServices` below.
+const OxyServicesComposed = composeOxyServices();
+// Export as a named class to avoid TypeScript issues with anonymous class types.
+// We extend the composed constructor directly — its public surface is broadened
+// to the full mixin set via the interface declaration that follows.
+export class OxyServices extends OxyServicesComposed {
+    constructor(config) {
+        super(config);
+    }
+}
+// Re-export error classes for convenience
+export { AssetUrlResolutionError, OxyAuthenticationError, OxyAuthenticationTimeoutError, ServiceAssetMetadataError };
+/**
+ * Default Oxy Cloud URL — used when no `cloudURL` is provided to OxyServices.
+ */
+export const OXY_CLOUD_URL = 'https://cloud.oxy.so';
+/**
+ * Export the default Oxy API URL (for documentation)
+ */
+export const OXY_API_URL = (typeof process !== 'undefined' && process.env && process.env.OXY_API_URL) || 'https://api.oxy.so';
+/**
+ * Pre-configured client instance for easy import
+ * Uses OXY_API_URL as baseURL and OXY_CLOUD_URL as cloudURL
+ */
+export const oxyClient = new OxyServices({ baseURL: OXY_API_URL, cloudURL: OXY_CLOUD_URL });