@oxy.so/core 1.0.0

package/dist/types/HttpService.d.ts

@@ -0,0 +1,413 @@
+/**
+ * Unified HTTP Service
+ *
+ * Consolidates HttpClient + RequestManager into a single efficient class.
+ * Uses native fetch instead of axios for smaller bundle size.
+ *
+ * Handles:
+ * - Authentication (token management, auto-refresh)
+ * - Caching (TTL-based)
+ * - Deduplication (concurrent requests)
+ * - Retry logic
+ * - Error handling
+ * - Request queuing
+ */
+import type { OxyConfig } from './models/interfaces';
+import type { DeviceSecretMintOutcome } from './session/refresh';
+export type AuthRefreshReason = 'preflight' | 'response-401';
+export type AuthRefreshHandler = (reason: AuthRefreshReason) => Promise<string | null>;
+export type AccessTokenProvider = () => string | null;
+/**
+ * A low-level authenticated request whose response body remains unread.
+ *
+ * This is intended for streaming protocols such as SSE. The body must already
+ * be serialised so it can be replayed once after an access-token refresh.
+ */
+export interface AuthenticatedResponseRequest {
+    method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+    url: string;
+    body?: string;
+    headers?: Record<string, string>;
+    signal?: AbortSignal;
+}
+export interface RequestOptions {
+    cache?: boolean;
+    cacheTTL?: number;
+    deduplicate?: boolean;
+    retry?: boolean;
+    maxRetries?: number;
+    timeout?: number;
+    signal?: AbortSignal;
+    headers?: Record<string, string>;
+    responseType?: 'blob';
+    /**
+     * Skip BOTH the bearer auth header (and its near-expiry preflight refresh)
+     * AND the 401-driven auto-refresh/retry for this request.
+     *
+     * Required for the body-authenticated device-secret mint (`POST
+     * /session/device/token`): it does not need a bearer, and — critically — it is
+     * itself invoked from inside the registered `AuthRefreshHandler`. If it went
+     * through the normal preflight, `getAuthHeader` would call
+     * `refreshAccessToken` while the handler-owning `tokenRefreshPromise` is
+     * still in flight and await ITSELF (deadlock). Skipping auth makes the
+     * mint call fully independent of the current (near-expired) bearer.
+     */
+    skipAuth?: boolean;
+    /**
+     * Execute this request WITHOUT taking a `RequestQueue` slot — run it directly.
+     *
+     * A queue slot represents network occupancy for ordinary DATA requests. The
+     * CONTROL-PLANE calls the auth lane depends on (the device-secret mint, `POST
+     * /session/device/token`, reached from `getAuthHeader` → `refreshAccessToken`)
+     * must never compete for a slot: when `maxConcurrentRequests` requests are all
+     * parked awaiting that very mint, a queued mint could never acquire a slot to
+     * run — a systemic deadlock. `bypassQueue` lets the mint run even when the
+     * queue is saturated. (The auth preflight is also resolved OUTSIDE the slot in
+     * `request()`, so ordinary requests never hold a slot while awaiting the mint;
+     * this flag is the explicit guarantee for the mint itself.)
+     */
+    bypassQueue?: boolean;
+}
+interface RequestConfig extends RequestOptions {
+    method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+    url: string;
+    data?: unknown;
+    params?: Record<string, unknown>;
+    /** @internal Used to prevent infinite auth retry loops */
+    _isAuthRetry?: boolean;
+    /** @internal Used to prevent infinite CSRF retry loops */
+    _isCsrfRetry?: boolean;
+}
+/**
+ * Unified HTTP Service
+ *
+ * Consolidates HttpClient + RequestManager into a single efficient class.
+ * Uses native fetch instead of axios for smaller bundle size.
+ */
+export declare class HttpService {
+    private baseURL;
+    private tokenStore;
+    private cache;
+    /**
+     * When true, the per-instance GET response cache is OFF: GET responses are
+     * never read from nor written to {@link cache}, so every request hits the
+     * network. Set from `config.enableCache === false` OR `config.cacheTTL <= 0`.
+     * A disabled instance does not register its cache for the global cleanup
+     * interval (nothing ever lands in it). Request deduplication is unaffected —
+     * concurrent identical in-flight requests still collapse into one.
+     */
+    private readonly cacheDisabled;
+    private deduplicator;
+    private requestQueue;
+    private logger;
+    private config;
+    private tokenRefreshPromise;
+    /**
+     * Epoch ms of the last FAILED refresh (0 = none since the last success). The
+     * post-failure cooldown is measured from here; its length depends on whether
+     * the current token is still valid ({@link TOKEN_REFRESH_COOLDOWN_MS}) or
+     * already expired ({@link EXPIRED_TOKEN_REFRESH_COOLDOWN_MS}), so an expired
+     * token recovers promptly the instant it crosses `exp` — without storing a
+     * fixed deadline that could not shrink once the token expired mid-cooldown.
+     */
+    private lastRefreshFailureAt;
+    private authRefreshHandler;
+    private accessTokenProvider;
+    private deviceSecretMintInFlight;
+    /**
+     * Epoch (ms) before which a cache-size telemetry warning must not be
+     * re-emitted. Throttles the {@link CACHE_SOFT_MAX_ENTRIES} warning to at most
+     * one per {@link CACHE_SIZE_WARNING_THROTTLE_MS} window.
+     */
+    private cacheSizeWarningSilentUntil;
+    /**
+     * Fan-out listeners notified on EVERY access-token change on this instance:
+     * explicit `setTokens`, `clearTokens`, a refresh-handler rotation, and the
+     * internal 401-driven clear. This is a Set so multiple independent observers
+     * can mirror token state without clobbering each other.
+     *
+     * Each listener receives the resulting access token, or `null` when cleared.
+     */
+    private _tokenChangeListeners;
+    private requestMetrics;
+    constructor(config: OxyConfig);
+    private syncAccessTokenFromProvider;
+    /**
+     * Robust FormData detection that works in browser, React Native, and
+     * Node.js polyfill environments.
+     *
+     * Why we don't use `instanceof FormData` alone:
+     *  - React Native's FormData is a separate class, not the browser one —
+     *    `instanceof FormData` is true only inside the JS runtime that
+     *    instantiated the value (browser-side polyfills also have their own).
+     *  - The Node.js `form-data` polyfill ships its own constructor.
+     *
+     * Why we explicitly reject `URLSearchParams`:
+     *  - `URLSearchParams` ALSO exposes `append` / `get` / `has`, so the
+     *    duck-type fallback below would have misidentified it as FormData and
+     *    sent an empty multipart body.
+     *  - It has its own encoding path instead — see {@link isUrlSearchParams}.
+     */
+    private isFormData;
+    /**
+     * True for an `application/x-www-form-urlencoded` payload.
+     *
+     * Needed because a handful of endpoints are defined by a standard that fixes
+     * their request encoding rather than by our own JSON conventions — today
+     * `POST /auth/oauth/token`, whose encoding RFC 6749 §4.1.3 mandates. Passing
+     * a `URLSearchParams` as `data` selects that encoding; everything else is
+     * still JSON.
+     */
+    private isUrlSearchParams;
+    /**
+     * Main request method - handles everything in one place
+     */
+    request<T = unknown>(config: RequestConfig): Promise<T>;
+    /**
+     * Soft cache-size guard. Emits a single throttled telemetry warning when the
+     * identity-scoped response cache grows past {@link CACHE_SOFT_MAX_ENTRIES}.
+     *
+     * This intentionally does NOT evict: the {@link TTLCache} already bounds
+     * memory by TTL (and the global cleanup interval sweeps expired entries), so
+     * an LRU here would only risk thrashing a legitimately warm cache. The point
+     * is observability — if entry count climbs and stays high, an identity tag or
+     * cache key is folding in volatile data (a per-request nonce, an undecodable
+     * rotating token) and the cache is no longer doing its job. Surfacing that via
+     * the logger lets a consumer with `enableLogging` catch the regression in the
+     * field instead of debugging silent memory growth.
+     */
+    private warnIfCacheOversized;
+    /**
+     * Upload via XMLHttpRequest (React Native FormData workaround).
+     *
+     * Expo SDK 56's "winter fetch" cannot serialize RN file descriptors
+     * (`{uri, type, name}`) — `convertFormDataAsync` rejects them as
+     * `Unsupported FormDataPart implementation`. RN's native XHR streams
+     * the file from disk correctly, so multipart uploads go through XHR
+     * on RN only.
+     *
+     * Returns a standard `Response` so downstream parsing in `request()`
+     * (status checks, 401/403 retries, JSON/blob/text parsing) is identical
+     * to the fetch path.
+     */
+    private uploadViaXHR;
+    /**
+     * Parse raw header string from `XMLHttpRequest.getAllResponseHeaders()`
+     * into a `Headers`-compatible object.
+     */
+    private static parseXHRHeaders;
+    /**
+     * Delimiter that separates the logical `method:url[:data]` portion of a
+     * cache key from its identity suffix. Always APPENDED, never used to parse
+     * a key apart, so the `method:url` prefix stays intact for
+     * `clearCacheByPrefix` sweeps and `clearCacheEntry` base-key matching.
+     * The `clearCacheEntry` callsites all pass fixed, dataless logical keys
+     * (`GET:/users/<id>`, `GET:/session/user/<sessionId>`,
+     * `GET:/auth/grants`), so this readable suffix can never be
+     * ambiguous with a serialized request body.
+     */
+    private static readonly CACHE_IDENTITY_DELIM;
+    /**
+     * The keys whose presence beside `data` makes a body a PAGE rather than a
+     * payload — see {@link unwrapResponse} for why this list is narrow.
+     *
+     *  - `pagination` — the offset-paginated house envelope (`sendPaginated`).
+     *  - `nextCursor` — the keyset-paginated one (the account audit trails).
+     *
+     * Membership is decided by key PRESENCE, never by value: the last page sends
+     * `nextCursor: null`, and an envelope that collapsed into a bare payload
+     * exactly when the stream ended would be a worse bug than the one this fixes.
+     */
+    private static readonly PAGE_ENVELOPE_KEYS;
+    /**
+     * Derive a stable, non-sensitive identity discriminator for cache scoping.
+     *
+     * Thin instance wrapper over the pure {@link computeIdentityTag} helper —
+     * binds it to this instance's live access token. See that function's docs for
+     * the full resolution contract (anon fallback, decoded `userId || id`,
+     * token-hash fallback for undecodable tokens).
+     */
+    private computeIdentityTag;
+    /**
+     * Generate cache key efficiently
+     * Uses a content-addressed hash for large payloads so two requests with
+     * the same shape but different values never collide on the same key
+     * (which would silently serve stale data — e.g. paginated search results,
+     * large object updates).
+     *
+     * The key is identity-scoped: the logical `method:url[:data]` portion is
+     * suffixed with ` id=<identityTag>` so two callers with different
+     * identities (anon vs authed, or two different users) never share an entry.
+     * The identity tag is placed at the END so the key still STARTS with
+     * `method:url`, preserving the prefix-based invalidation in
+     * `clearCacheByPrefix` (e.g. `GET:/session/user/`) and the base-key matching
+     * in `clearCacheEntry`.
+     */
+    private generateCacheKey;
+    /**
+     * Build the identity-agnostic portion of a cache key (`method:url[:data]`).
+     * Kept separate so identity scoping is applied in exactly one place
+     * (`generateCacheKey`) and cannot drift between the cache and dedupe paths.
+     */
+    private generateBaseCacheKey;
+    /**
+     * Build full URL with query params
+     */
+    private buildURL;
+    private getCredentialsMode;
+    private shouldSendCredentials;
+    /**
+     * Fetch CSRF token from server (with deduplication)
+     * Required for state-changing requests (POST, PUT, PATCH, DELETE)
+     */
+    private fetchCsrfToken;
+    /**
+     * Get auth header with automatic token refresh
+     */
+    private getAuthHeader;
+    refreshAccessToken(reason: AuthRefreshReason): Promise<string | null>;
+    /**
+     * Whether the CURRENT stored access token is already past its `exp`. Drives
+     * the shorter post-failure refresh cooldown ({@link EXPIRED_TOKEN_REFRESH_COOLDOWN_MS}):
+     * a still-valid (near-expiry) token can wait out the full cooldown, but an
+     * expired one must re-mint promptly. Returns `false` for an absent or
+     * opaque/no-`exp` token — no proof it is expired, so keep the conservative
+     * (longer) cooldown and avoid an unnecessary retry loop.
+     */
+    private isAccessTokenExpired;
+    /**
+     * PROCESS-WIDE single-flight for the rotating device-secret mint
+     * (`POST /session/device/token`).
+     *
+     * The server rotates the presented `deviceSecret` on every successful mint, so
+     * two concurrent mints would double-rotate and the durable store could end up
+     * holding a superseded secret → a later cold-boot mint 401s → the user is
+     * signed out. Every mint lane (the re-mint handler behind `refreshAccessToken`,
+     * the device-first cold boot, the socket token transport, the tab-focus
+     * reconcile) funnels its `refreshDeviceSecretArm` call through here, so
+     * concurrent callers await the SAME in-flight mint and all receive its result —
+     * exactly one server rotation.
+     *
+     * Distinct from {@link tokenRefreshPromise} (which dedups the FULL re-mint
+     * handler incl. the native shared-key arm + the failure cooldown): this inner
+     * guard serializes the rotation itself across BOTH the handler and the
+     * handler-independent cold boot, which never runs through `refreshAccessToken`.
+     */
+    runSingleFlightDeviceSecretMint(mint: () => Promise<DeviceSecretMintOutcome>): Promise<DeviceSecretMintOutcome>;
+    /**
+     * Unwrap the standardized API response envelope — EXCEPT when the envelope is
+     * a page, in which case it travels whole.
+     *
+     * `{ data: <payload> }` is the house success envelope (`sendSuccess`), and
+     * reducing it to `<payload>` is what every call site in the SDK expects. But
+     * the reduction DISCARDS every sibling key, silently, and a page's siblings
+     * are the only thing that says where the next page starts. That is how
+     * `GET /accounts/:id/audit` lost its `nextCursor`: the caller received a bare
+     * array, `getNextPageParam` read `undefined`, and pagination was dead past the
+     * first page with nothing to show that it was.
+     *
+     * ## Why the rule is narrow, and not "any sibling key survives"
+     *
+     * "An object carrying `data` plus anything else is not an envelope" is the
+     * tempting general rule, and it is wrong here: this API already answers
+     * `{ data, count }` on ~15 routes, plus `{ data, source }`, `{ data, reason }`
+     * and `{ data, credentialRevoked }`, and a dozen measured Console call sites
+     * type those as the bare payload (`Array<ProviderConnection>`,
+     * `AccountBillingState | null`, …). Preserving those envelopes would hand every
+     * one of them an object where it expects its payload — at runtime only, since
+     * the response type is a call-site assertion. So the rule names PAGINATION
+     * specifically: `data` beside {@link PAGE_ENVELOPE_KEYS} is a page.
+     *
+     * A route whose sibling key genuinely matters to its caller belongs in that
+     * list, or should not be a sibling of `data` at all — the cursor-paginated
+     * surfaces already in the SDK (`{ follows, nextCursor }`,
+     * `{ records, nextCursor }`) sidestep this by never using `data`.
+     */
+    private unwrapResponse;
+    /**
+     * Update request metrics
+     */
+    private updateMetrics;
+    /**
+     * Send an authenticated request without consuming its response body.
+     *
+     * Regular {@link request} calls parse the body before returning. Streaming
+     * consumers instead need the original `Response`, while retaining the same
+     * token ownership and one-time 401 refresh behaviour as every SDK request.
+     * No SDK timeout is installed after the connection opens: the caller-owned
+     * abort signal defines the lifetime of a healthy stream.
+     */
+    requestAuthenticatedResponse(config: AuthenticatedResponseRequest): Promise<Response>;
+    private requestAuthenticatedResponseAttempt;
+    get<T = unknown>(url: string, config?: Omit<RequestConfig, 'method' | 'url'>): Promise<T>;
+    post<T = unknown>(url: string, data?: unknown, config?: Omit<RequestConfig, 'method' | 'url' | 'data'>): Promise<T>;
+    put<T = unknown>(url: string, data?: unknown, config?: Omit<RequestConfig, 'method' | 'url' | 'data'>): Promise<T>;
+    patch<T = unknown>(url: string, data?: unknown, config?: Omit<RequestConfig, 'method' | 'url' | 'data'>): Promise<T>;
+    delete<T = unknown>(url: string, config?: Omit<RequestConfig, 'method' | 'url'>): Promise<T>;
+    setTokens(accessToken: string): void;
+    setAuthRefreshHandler(handler: AuthRefreshHandler | null): void;
+    setAccessTokenProvider(provider: AccessTokenProvider | null): void;
+    clearTokens(): void;
+    /**
+     * Subscribe to access-token changes on this instance.
+     *
+     * Fires on every mutation of the access token — `setTokens`, `clearTokens`,
+     * a successful silent refresh, and the internal 401-driven clear — passing
+     * the resulting token (or `null` when cleared). Returns an unsubscribe
+     * function; call it on teardown to avoid leaks.
+     *
+     * This is the single hook downstream code (e.g. @oxy.so/services' OxyProvider)
+     * uses to keep an external token sink — such as the shared `oxyClient`
+     * singleton — in lockstep with the active session, regardless of which code
+     * path mutated the token.
+     */
+    addTokenChangeListener(listener: (accessToken: string | null) => void): () => void;
+    /**
+     * Notify all token-change listeners with the current access token.
+     * Listener exceptions are isolated so one bad subscriber cannot break token
+     * propagation to the others or to the calling auth flow.
+     * @internal
+     */
+    private notifyTokenChange;
+    getAccessToken(): string | null;
+    hasAccessToken(): boolean;
+    getBaseURL(): string;
+    clearCache(): void;
+    /**
+     * Delete a cache entry by its LOGICAL key (`method:url[:data]`).
+     *
+     * Because the response cache is identity-scoped — stored keys carry an
+     * ` id=<identityTag>` suffix — a caller passing the logical key
+     * `GET:/users/<id>` must invalidate that resource for EVERY identity that
+     * cached it (e.g. `updateProfile` busting a user representation that may be
+     * cached under both the owner's id and a viewer's id). We therefore delete
+     * the exact key (for any pre-existing un-suffixed entries) AND every
+     * identity-scoped variant `<key> id=*`.
+     */
+    clearCacheEntry(key: string): void;
+    /**
+     * Delete every cache entry whose key starts with `prefix`.
+     *
+     * Used by mutations that don't know the exact downstream cache keys —
+     * e.g. `updateProfile` invalidating all `GET:/session/user/*` entries
+     * without having to track every active session ID. Returns the number of
+     * deleted entries (for observability in tests).
+     */
+    clearCacheByPrefix(prefix: string): number;
+    getCacheStats(): {
+        size: number;
+        hits: number;
+        misses: number;
+        hitRate: number;
+    };
+    getMetrics(): {
+        totalRequests: number;
+        successfulRequests: number;
+        failedRequests: number;
+        cacheHits: number;
+        cacheMisses: number;
+        averageResponseTime: number;
+    };
+    __resetTokensForTests(): void;
+}
+export {};

package/dist/types/OxyServices.base.d.ts

@@ -0,0 +1,187 @@
+import type { OxyConfig as OxyConfigBase } from './models/interfaces';
+import { HttpService, type RequestOptions } from './HttpService';
+export interface OxyConfig extends OxyConfigBase {
+    cloudURL?: string;
+}
+export interface LinkedHttpClient {
+    client: HttpService;
+    dispose(): void;
+}
+/**
+ * Base class for OxyServices with core infrastructure
+ */
+export declare class OxyServicesBase {
+    httpService: HttpService;
+    cloudURL: string;
+    config: OxyConfig;
+    constructor(...args: any[]);
+    __resetTokensForTests(): void;
+    /**
+     * Make a request with all performance optimizations
+     * This is the main method for all API calls - ensures authentication and performance features
+     */
+    makeRequest<T>(method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE', url: string, data?: any, options?: RequestOptions): Promise<T>;
+    /**
+     * Get the configured Oxy API base URL
+     */
+    getBaseURL(): string;
+    /**
+     * Get the HTTP service instance
+     * Useful for advanced use cases where direct access to the HTTP service is needed
+     */
+    getClient(): 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: OxyConfig): LinkedHttpClient;
+    /**
+     * Get performance metrics
+     */
+    getMetrics(): {
+        totalRequests: number;
+        successfulRequests: number;
+        failedRequests: number;
+        cacheHits: number;
+        cacheMisses: number;
+        averageResponseTime: number;
+    };
+    /**
+     * Clear request cache
+     */
+    clearCache(): void;
+    /**
+     * Clear specific cache entry
+     */
+    clearCacheEntry(key: string): void;
+    /**
+     * 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: string): number;
+    /**
+     * Get cache statistics
+     */
+    getCacheStats(): {
+        size: number;
+        hits: number;
+        misses: number;
+        hitRate: number;
+    };
+    /**
+     * Get the configured Oxy Cloud (file storage/CDN) URL
+     */
+    getCloudURL(): string;
+    /**
+     * Set authentication tokens
+     */
+    setTokens(accessToken: string): void;
+    /**
+     * Clear stored authentication tokens
+     */
+    clearTokens(): void;
+    /**
+     * 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: (accessToken: string | null) => void): () => void;
+    /** @internal */ _cachedUserId: string | null | undefined;
+    /** @internal */ _cachedAccessToken: string | null;
+    /**
+     * Get the current user ID from the access token.
+     * Caches the decoded value and invalidates when the token changes.
+     */
+    getCurrentUserId(): string | null;
+    /**
+     * Check if the client has a valid access token (public method)
+     */
+    hasValidToken(): boolean;
+    /**
+     * Get the raw access token (for constructing anchor URLs when needed)
+     */
+    getAccessToken(): string | null;
+    /**
+     * 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(): number | 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
+     * }
+     * ```
+     */
+    waitForAuth(timeoutMs?: number): Promise<boolean>;
+    /**
+     * Execute a function with automatic authentication retry logic
+     * This handles the common case where API calls are made before authentication completes
+     */
+    withAuthRetry<T>(operation: () => Promise<T>, operationName: string, options?: {
+        maxRetries?: number;
+        retryDelay?: number;
+        authTimeoutMs?: number;
+    }): Promise<T>;
+    /**
+     * Validate the current access token with the server
+     */
+    validate(): Promise<boolean>;
+    /**
+     * Centralized error handling
+     */
+    handleError(error: unknown): Error;
+    /**
+     * Health check endpoint
+     */
+    healthCheck(): Promise<{
+        status: string;
+        users?: number;
+        timestamp?: string;
+        [key: string]: any;
+    }>;
+}