@oxyhq/core 1.11.11 → 1.11.13

package/dist/types/HttpService.d.ts

@@ -54,17 +54,52 @@ export declare class HttpService {
     private requestMetrics;
     constructor(config: OxyConfig);
     /**
-     * Robust FormData detection that works in browser and Node.js environments
-     * Checks multiple conditions to handle different FormData implementations
+     * 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.
+     *  - We want urlencoded payloads to take the JSON-stringify path so the
+     *    server receives them as `application/x-www-form-urlencoded` instead
+     *    of an empty multipart body.
      */
     private isFormData;
     /**
      * Main request method - handles everything in one place
      */
     request<T = unknown>(config: RequestConfig): Promise<T>;
+    /**
+     * 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;
     /**
      * Generate cache key efficiently
-     * Uses simple hash for large objects to avoid expensive JSON.stringify
+     * 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).
      */
     private generateCacheKey;
     /**
@@ -104,6 +139,15 @@ export declare class HttpService {
     getBaseURL(): string;
     clearCache(): void;
     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;

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

@@ -45,6 +45,13 @@ export declare class OxyServicesBase {
      * 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
      */

package/dist/types/OxyServices.d.ts

@@ -63,8 +63,41 @@ import type { FedCMAuthOptions, FedCMConfig } from './mixins/OxyServices.fedcm';
 import type { PopupAuthOptions } from './mixins/OxyServices.popup';
 import type { RedirectAuthOptions } from './mixins/OxyServices.redirect';
 import { composeOxyServices } from './mixins';
-declare const OxyServices_base: any;
-export declare class OxyServices extends OxyServices_base {
+/**
+ * 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
+ * - **Karma**: Karma system
+ * - **Assets**: File upload and asset management
+ * - **Developer**: Developer API management
+ * - **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'
+ * });
+ * ```
+ */
+declare const OxyServicesComposed: import("./mixins").ComposedOxyServicesConstructor;
+export declare class OxyServices extends OxyServicesComposed {
     constructor(config: OxyConfig);
 }
 export interface OxyServices extends InstanceType<ReturnType<typeof composeOxyServices>> {
@@ -90,7 +123,7 @@ export interface OxyServices extends InstanceType<ReturnType<typeof composeOxySe
 }
 export { OxyAuthenticationError, OxyAuthenticationTimeoutError };
 /**
- * Export the default Oxy Cloud URL (for backward compatibility)
+ * Default Oxy Cloud URL — used when no `cloudURL` is provided to OxyServices.
  */
 export declare const OXY_CLOUD_URL = "https://cloud.oxy.so";
 /**

package/dist/types/crypto/index.d.ts

@@ -5,7 +5,7 @@
  * Handles key generation, secure storage, digital signatures, and recovery phrases.
  */
 import './polyfill';
-export { KeyManager, type KeyPair } from './keyManager';
+export { KeyManager, IdentityAlreadyExistsError, IdentityPersistError, type KeyPair, } from './keyManager';
 export { SignatureService, type SignedMessage, type AuthChallenge } from './signatureService';
 export { RecoveryPhraseService, type RecoveryPhraseResult } from './recoveryPhrase';
 export { KeyManager as default } from './keyManager';

package/dist/types/crypto/keyManager.d.ts

@@ -5,6 +5,31 @@
  * Private keys are stored securely using expo-secure-store and never leave the device.
  */
 import type { ECKeyPair } from 'elliptic';
+/**
+ * Thrown when an identity-mutating operation (createIdentity / importKeyPair)
+ * is invoked while a valid identity already exists on the device.
+ *
+ * The local private key IS the user's identity — overwriting it without
+ * explicit consent permanently loses access to their account (unless
+ * they previously saved their recovery phrase). This error forces callers
+ * to make an explicit, audited decision instead of silently clobbering.
+ */
+export declare class IdentityAlreadyExistsError extends Error {
+    readonly name = "IdentityAlreadyExistsError";
+    readonly existingPublicKey: string;
+    constructor(existingPublicKey: string);
+}
+/**
+ * Thrown when a freshly written identity cannot be read back, parsed, or
+ * round-tripped through sign/verify. Indicates a storage failure or
+ * corruption that would otherwise silently leave the user with an
+ * unusable account.
+ */
+export declare class IdentityPersistError extends Error {
+    readonly cause?: unknown | undefined;
+    readonly name = "IdentityPersistError";
+    constructor(message: string, cause?: unknown | undefined);
+}
 export interface KeyPair {
     publicKey: string;
     privateKey: string;
@@ -24,6 +49,19 @@ export declare class KeyManager {
      * Called internally when shared identity is created/deleted/imported
      */
     private static invalidateSharedCache;
+    /**
+     * Lowercase and pad to canonical 64-hex-char form.
+     *
+     * Tolerates the 1-in-256 leading-zero-strip that elliptic's
+     * `getPrivate('hex')` produces, and the externally-imported uppercase-hex
+     * legacy keys. EVERY `ec.keyFromPrivate(...)` call site in this file must
+     * canonicalize first so that derivation is stable regardless of storage
+     * representation.
+     *
+     * Private (used only inside KeyManager) — public consumers should not need
+     * to think about hex representation.
+     */
+    private static canonicalPrivateKey;
     /**
      * Generate a new ECDSA secp256k1 key pair
      * Returns the keys in hexadecimal format
@@ -120,14 +158,45 @@ export declare class KeyManager {
      */
     static migrateToSharedIdentity(): Promise<boolean>;
     /**
-     * Generate and securely store a new key pair on the device
-     * Returns only the public key (private key is stored securely)
+     * Atomically persist a key pair to secure storage with verification + backup.
+     *
+     * Write order is critical:
+     *   1. Backup (BACKUP_PRIVATE_KEY + BACKUP_PUBLIC_KEY + BACKUP_TIMESTAMP)
+     *   2. Primary public key
+     *   3. Primary private key (last so a partial write leaves us in a known
+     *      "no identity yet" state — easier to retry than a half-written one)
+     *   4. Read back + sign/verify to confirm the storage round-trip works
+     *
+     * If any step throws, the caller sees the error AND any partial state is
+     * cleaned up so the device is left either fully consistent or fully empty.
+     * It never leaves an unusable half-identity that would fool `hasIdentity()`.
+     *
+     * @internal
      */
-    static createIdentity(): Promise<string>;
+    private static _persistIdentityAtomic;
     /**
-     * Import an existing key pair (e.g., from recovery phrase)
+     * Generate and securely store a new key pair on the device.
+     *
+     * Refuses to overwrite an existing identity unless `options.overwrite === true`.
+     * Returns the public key. The private key never leaves secure storage.
+     *
+     * @throws IdentityAlreadyExistsError if an identity already exists and overwrite is not set
+     * @throws IdentityPersistError if the key cannot be durably written
      */
-    static importKeyPair(privateKey: string): Promise<string>;
+    static createIdentity(options?: {
+        overwrite?: boolean;
+    }): Promise<string>;
+    /**
+     * Import an existing key pair (e.g., from recovery phrase).
+     *
+     * Refuses to overwrite an existing identity unless `options.overwrite === true`.
+     *
+     * @throws IdentityAlreadyExistsError if an identity already exists and overwrite is not set
+     * @throws IdentityPersistError if the key cannot be durably written
+     */
+    static importKeyPair(privateKey: string, options?: {
+        overwrite?: boolean;
+    }): Promise<string>;
     /**
      * Get the stored private key
      * WARNING: Only use this for signing operations within the app
@@ -138,7 +207,15 @@ export declare class KeyManager {
      */
     static getPublicKey(): Promise<string | null>;
     /**
-     * Check if an identity (key pair) exists on this device (cached for performance)
+     * Check if a complete, parseable identity exists on this device.
+     *
+     * Returns `true` only when BOTH the private and public keys are present,
+     * both are well-formed, AND the public key derives from the private key.
+     * A partially-written or corrupted identity returns `false` so that
+     * downstream code can resume the create / restore flow correctly.
+     *
+     * Note: this does NOT perform the full sign/verify roundtrip — call
+     * `verifyIdentityIntegrity()` for that.
      */
     static hasIdentity(): Promise<boolean>;
     /**
@@ -156,11 +233,26 @@ export declare class KeyManager {
      */
     static backupIdentity(): Promise<boolean>;
     /**
-     * Verify identity integrity - checks if keys are valid and accessible
+     * Verify identity integrity — checks keys are valid, accessible, derive
+     * consistently, AND can sign + verify a probe message.
+     *
+     * Returns true only when the full sign/verify roundtrip succeeds. Use
+     * this on app start to detect silent corruption before the user finds
+     * out by failing to sign in.
      */
     static verifyIdentityIntegrity(): Promise<boolean>;
     /**
-     * Restore identity from backup if primary storage is corrupted
+     * Restore identity from backup if primary storage is corrupted.
+     *
+     * SAFETY: this method will NEVER overwrite a verifying primary identity.
+     * If the primary passes a sign/verify probe, the backup is left untouched
+     * and `false` is returned — this protects against a transient
+     * `verifyIdentityIntegrity()` blip clobbering valid keys with stale
+     * backup keys (e.g., from a previous account before an import).
+     *
+     * Additionally, if the backup public key does NOT match the (still-
+     * present-but-failing) primary public key, we refuse to overwrite — the
+     * backup may belong to a different identity entirely.
      */
     static restoreIdentityFromBackup(): Promise<boolean>;
     /**
@@ -174,10 +266,19 @@ export declare class KeyManager {
     static derivePublicKey(privateKey: string): string;
     /**
      * Validate that a string is a valid public key
+     *
+     * Returns false on parse errors (invalid input is the expected fail mode here).
+     * Errors are logged at debug level so they're available when troubleshooting
+     * but don't pollute production logs.
      */
     static isValidPublicKey(publicKey: string): boolean;
     /**
-     * Validate that a string is a valid private key
+     * Validate that a string is a valid private key.
+     *
+     * secp256k1 private keys are 256-bit, so 64 hex chars. We require strict
+     * hex-only input because `elliptic`'s underlying `BN(input, 16)` happily
+     * accepts non-hex characters (treating them as zero), which would let
+     * "not-hex" pass through as a valid (but compromised, near-zero) key.
      */
     static isValidPrivateKey(privateKey: string): boolean;
     /**

package/dist/types/crypto/polyfill.d.ts

@@ -5,7 +5,9 @@
  * across all platforms (Node.js, Browser, React Native).
  *
  * - Browser/Node.js: Uses native crypto
- * - React Native: Falls back to expo-crypto if native crypto unavailable
+ * - React Native: Uses expo-crypto (statically imported via the
+ *   per-platform `platformCrypto` module — see that file's doc-comment for
+ *   how platform routing works).
  */
 import { Buffer } from 'buffer';
 export { Buffer };

package/dist/types/crypto/recoveryPhrase.d.ts

@@ -11,20 +11,44 @@ export interface RecoveryPhraseResult {
     words: string[];
     publicKey: string;
 }
+export interface GenerateIdentityOptions {
+    /**
+     * Pass `true` to allow overwriting an existing on-device identity.
+     *
+     * Defaults to `false`. When false, this method throws
+     * `IdentityAlreadyExistsError` if a complete identity already exists,
+     * preventing accidental account loss. UI flows MUST only set this to
+     * `true` after explicitly confirming the user has saved their previous
+     * recovery phrase (or has otherwise been warned).
+     */
+    overwrite?: boolean;
+}
 export declare class RecoveryPhraseService {
     /**
-     * Generate a new identity with a recovery phrase
-     * Returns the mnemonic phrase (should only be shown once to the user)
+     * Generate a new identity with a recovery phrase.
+     * The mnemonic phrase MUST be shown to the user exactly once after this
+     * call resolves — if it is lost, the account becomes unrecoverable.
+     *
+     * Refuses to overwrite an existing identity unless `options.overwrite === true`.
+     *
+     * @throws IdentityAlreadyExistsError if an identity already exists and overwrite is not set
      */
-    static generateIdentityWithRecovery(): Promise<RecoveryPhraseResult>;
+    static generateIdentityWithRecovery(options?: GenerateIdentityOptions): Promise<RecoveryPhraseResult>;
     /**
-     * Generate a 24-word recovery phrase for higher security
+     * Generate a 24-word recovery phrase for higher security.
+     *
+     * Same overwrite-protection semantics as `generateIdentityWithRecovery`.
      */
-    static generateIdentityWithRecovery24(): Promise<RecoveryPhraseResult>;
+    static generateIdentityWithRecovery24(options?: GenerateIdentityOptions): Promise<RecoveryPhraseResult>;
     /**
-     * Restore an identity from a recovery phrase
+     * Restore an identity from a recovery phrase.
+     *
+     * Refuses to overwrite a DIFFERENT existing identity unless
+     * `options.overwrite === true`. Re-importing the same phrase that
+     * matches the current identity is always allowed (it's a no-op refresh
+     * of the backup record).
      */
-    static restoreFromPhrase(phrase: string): Promise<string>;
+    static restoreFromPhrase(phrase: string, options?: GenerateIdentityOptions): Promise<string>;
     /**
      * Validate a recovery phrase without importing it
      */

package/dist/types/crypto/signatureService.d.ts

@@ -37,6 +37,10 @@ export declare class SignatureService {
     static signWithKey(message: string, privateKey: string): Promise<string>;
     /**
      * Verify a signature against a message and public key
+     *
+     * Returns false on any error (invalid signature, malformed input, etc.).
+     * Errors are logged at debug level so they're available when troubleshooting
+     * signature mismatches but don't surface to the caller.
      */
     static verify(message: string, signature: string, publicKey: string): Promise<boolean>;
     /**

package/dist/types/index.d.ts

@@ -26,7 +26,8 @@ export type { RedirectAuthOptions } from './mixins/OxyServices.redirect';
 export type { ServiceTokenResponse } from './mixins/OxyServices.auth';
 export type { ServiceApp } from './mixins/OxyServices.utility';
 export type { CreateManagedAccountInput, ManagedAccountManager, ManagedAccount } from './mixins/OxyServices.managedAccounts';
-export { KeyManager, SignatureService, RecoveryPhraseService } from './crypto';
+export type { ContactDiscoveryMatch, ContactDiscoveryResponse } from './mixins/OxyServices.contacts';
+export { KeyManager, SignatureService, RecoveryPhraseService, IdentityAlreadyExistsError, IdentityPersistError, } from './crypto';
 export type { KeyPair, SignedMessage, AuthChallenge, RecoveryPhraseResult } from './crypto';
 export * from './models/interfaces';
 export * from './models/session';
@@ -57,7 +58,7 @@ export * from './utils/validationUtils';
 export { logger, LogLevel, logAuth, logApi, logSession, logUser, logDevice, logPayment, logPerformance, } from './utils/loggerUtils';
 export type { LogContext } from './utils/loggerUtils';
 export { updateAvatarVisibility } from './utils/avatarUtils';
-export { buildAccountsArray, createQuickAccount } from './utils/accountUtils';
-export type { QuickAccount } from './utils/accountUtils';
+export { buildAccountsArray, createQuickAccount, getAccountDisplayName, getAccountFallbackHandle, formatPublicKeyHandle, } from './utils/accountUtils';
+export type { QuickAccount, DisplayNameUserShape } from './utils/accountUtils';
 import { OxyServices } from './OxyServices';
 export default OxyServices;

package/dist/types/mixins/OxyServices.analytics.d.ts

@@ -36,6 +36,7 @@ export declare function OxyServicesAnalyticsMixin<T extends typeof OxyServicesBa
         };
         clearCache(): void;
         clearCacheEntry(key: string): void;
+        clearCacheByPrefix(prefix: string): number;
         getCacheStats(): {
             size: number;
             hits: number;

package/dist/types/mixins/OxyServices.assets.d.ts

@@ -1,4 +1,4 @@
-import type { AccountStorageUsageResponse, AssetUrlResponse, AssetVariant } from '../models/interfaces';
+import type { AccountStorageUsageResponse, AssetUploadInput, AssetUrlResponse, AssetVariant } from '../models/interfaces';
 import type { OxyServicesBase } from '../OxyServices.base';
 export declare function OxyServicesAssetsMixin<T extends typeof OxyServicesBase>(Base: T): {
     new (...args: any[]): {
@@ -45,7 +45,7 @@ export declare function OxyServicesAssetsMixin<T extends typeof OxyServicesBase>
         /**
          * Upload raw file data
          */
-        uploadRawFile(file: File | Blob, visibility?: "private" | "public" | "unlisted", metadata?: Record<string, any>): Promise<any>;
+        uploadRawFile(file: AssetUploadInput, visibility?: "private" | "public" | "unlisted", metadata?: Record<string, any>): Promise<any>;
         /**
          * Upload file using Central Asset Service.
          *
@@ -53,12 +53,7 @@ export declare function OxyServicesAssetsMixin<T extends typeof OxyServicesBase>
          * ({uri, type, name, size}). RN descriptors are passed directly to
          * FormData.append, which handles them natively.
          */
-        assetUpload(file: File | {
-            uri: string;
-            type?: string;
-            name?: string;
-            size?: number;
-        }, visibility?: "private" | "public" | "unlisted", metadata?: Record<string, any>, onProgress?: (progress: number) => void): Promise<any>;
+        assetUpload(file: AssetUploadInput, visibility?: "private" | "public" | "unlisted", metadata?: Record<string, any>, onProgress?: (progress: number) => void): Promise<any>;
         /**
          * Link asset to an entity
          */
@@ -91,8 +86,8 @@ export declare function OxyServicesAssetsMixin<T extends typeof OxyServicesBase>
          * Update asset visibility
          */
         assetUpdateVisibility(fileId: string, visibility: "private" | "public" | "unlisted"): Promise<any>;
-        uploadAvatar(file: File, userId: string, app?: string): Promise<any>;
-        uploadProfileBanner(file: File, userId: string, app?: string): Promise<any>;
+        uploadAvatar(file: AssetUploadInput, userId: string, app?: string): Promise<any>;
+        uploadProfileBanner(file: AssetUploadInput, userId: string, app?: string): Promise<any>;
         getAssetUrlCacheTTL(expiresIn?: number): number;
         fetchAssetDownloadUrl(fileId: string, variant?: string, cacheTTL?: number, expiresIn?: number): Promise<string | null>;
         fetchAssetContent(url: string, type: "text"): Promise<string>;
@@ -114,6 +109,7 @@ export declare function OxyServicesAssetsMixin<T extends typeof OxyServicesBase>
         };
         clearCache(): void;
         clearCacheEntry(key: string): void;
+        clearCacheByPrefix(prefix: string): number;
         getCacheStats(): {
             size: number;
             hits: number;

package/dist/types/mixins/OxyServices.auth.d.ts

@@ -40,6 +40,12 @@ export declare function OxyServicesAuthMixin<T extends typeof OxyServicesBase>(B
         /** @internal */ _serviceTokenExp: number;
         /** @internal */ _serviceApiKey: string | null;
         /** @internal */ _serviceApiSecret: string | null;
+        /**
+         * In-flight promise for service token fetch. Used to deduplicate concurrent
+         * calls to getServiceToken() — pattern mirrors AuthManager.refreshToken().
+         * @internal
+         */
+        _serviceTokenPromise: Promise<string> | null;
         /**
          * Configure service credentials for internal service-to-service communication.
          * Call this once at startup so that getServiceToken() and makeServiceRequest()
@@ -53,10 +59,19 @@ export declare function OxyServicesAuthMixin<T extends typeof OxyServicesBase>(B
          * Get a service token for internal service-to-service communication.
          * Tokens are short-lived (1h) and automatically cached/refreshed.
          *
+         * Concurrent callers share a single in-flight request to avoid hammering
+         * `/auth/service-token` when the cache is empty or expired.
+         *
          * @param apiKey - DeveloperApp API key (optional if configureServiceAuth was called)
          * @param apiSecret - DeveloperApp API secret (optional if configureServiceAuth was called)
          */
         getServiceToken(apiKey?: string, apiSecret?: string): Promise<string>;
+        /**
+         * Perform the actual /auth/service-token request and cache the result.
+         * Separated so getServiceToken() can deduplicate concurrent calls.
+         * @internal
+         */
+        _doFetchServiceToken(key: string, secret: string): Promise<string>;
         /**
          * Make an authenticated request on behalf of a user using a service token.
          * Automatically obtains/refreshes the service token.
@@ -192,6 +207,7 @@ export declare function OxyServicesAuthMixin<T extends typeof OxyServicesBase>(B
         };
         clearCache(): void;
         clearCacheEntry(key: string): void;
+        clearCacheByPrefix(prefix: string): number;
         getCacheStats(): {
             size: number;
             hits: number;

package/dist/types/mixins/OxyServices.contacts.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Contact Discovery Mixin
+ *
+ * Privacy-preserving discovery of which address-book contacts are on Oxy.
+ *
+ * The client hashes emails and phones locally before calling the API.
+ * The server responds with only Oxy user IDs and the hashes that matched,
+ * so the consumer can map each match back to the local contact that
+ * produced it.
+ *
+ * Hashing rules (must match the server `utils/contactHash.ts` exactly):
+ *   - SHA-256, hex-encoded, lowercase
+ *   - Email: `value.trim().toLowerCase()` then digest
+ *   - Phone: trim → keep a single leading "+" → strip non-digits → prepend "+"
+ *     if missing → digest
+ *
+ * Mobile clients can compute these digests with `expo-crypto`'s
+ * `digestStringAsync(SHA256, value, { encoding: HEX })`. Web clients should
+ * use `SubtleCrypto.digest('SHA-256', ...)`.
+ */
+import type { OxyServicesBase } from '../OxyServices.base';
+/** A single match returned by `POST /contacts/discover`. */
+export interface ContactDiscoveryMatch {
+    /** Oxy user ID (MongoDB ObjectId hex string). */
+    userId: string;
+    /** The hashed identifier from the request that matched this user. */
+    hashedIdentifier: string;
+    /** Whether the match came from the email index or phone index. */
+    matchType: 'email' | 'phone';
+}
+/** Response shape of `POST /contacts/discover`. */
+export interface ContactDiscoveryResponse {
+    matches: ContactDiscoveryMatch[];
+}
+export declare function OxyServicesContactsMixin<T extends typeof OxyServicesBase>(Base: T): {
+    new (...args: any[]): {
+        /**
+         * Discover which of the caller's contacts are on Oxy.
+         *
+         * @param hashedEmails - SHA-256 hex digests of normalized emails.
+         * @param hashedPhones - SHA-256 hex digests of normalized phone numbers.
+         * @returns Matches mapping each hashed identifier to the Oxy user ID it
+         *   resolved to. Empty arrays are valid for either parameter, but at
+         *   least one must be non-empty.
+         *
+         * The server enforces a 200-hash cap per channel per request — callers
+         * should batch larger address books client-side.
+         */
+        discoverContacts(hashedEmails: string[], hashedPhones: string[]): Promise<ContactDiscoveryResponse>;
+        httpService: import("../HttpService").HttpService;
+        cloudURL: string;
+        config: import("../OxyServices.base").OxyConfig;
+        __resetTokensForTests(): void;
+        makeRequest<T_1>(method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE", url: string, data?: any, options?: import("../HttpService").RequestOptions): Promise<T_1>;
+        getBaseURL(): string;
+        getClient(): import("../HttpService").HttpService;
+        getMetrics(): {
+            totalRequests: number;
+            successfulRequests: number;
+            failedRequests: number;
+            cacheHits: number;
+            cacheMisses: number;
+            averageResponseTime: number;
+        };
+        clearCache(): void;
+        clearCacheEntry(key: string): void;
+        clearCacheByPrefix(prefix: string): number;
+        getCacheStats(): {
+            size: number;
+            hits: number;
+            misses: number;
+            hitRate: number;
+        };
+        getCloudURL(): string;
+        setTokens(accessToken: string, refreshToken?: string): void;
+        clearTokens(): void;
+        _cachedUserId: string | null | undefined;
+        _cachedAccessToken: string | null;
+        getCurrentUserId(): string | null;
+        hasValidToken(): boolean;
+        getAccessToken(): string | null;
+        setActingAs(userId: string | null): void;
+        getActingAs(): string | null;
+        waitForAuth(timeoutMs?: number): Promise<boolean>;
+        withAuthRetry<T_1>(operation: () => Promise<T_1>, operationName: string, options?: {
+            maxRetries?: number;
+            retryDelay?: number;
+            authTimeoutMs?: number;
+        }): Promise<T_1>;
+        validate(): Promise<boolean>;
+        handleError(error: unknown): Error;
+        healthCheck(): Promise<{
+            status: string;
+            users?: number;
+            timestamp?: string;
+            [key: string]: any;
+        }>;
+    };
+} & T;

package/dist/types/mixins/OxyServices.developer.d.ts

@@ -69,6 +69,7 @@ export declare function OxyServicesDeveloperMixin<T extends typeof OxyServicesBa
         };
         clearCache(): void;
         clearCacheEntry(key: string): void;
+        clearCacheByPrefix(prefix: string): number;
         getCacheStats(): {
             size: number;
             hits: number;

package/dist/types/mixins/OxyServices.devices.d.ts

@@ -66,6 +66,7 @@ export declare function OxyServicesDevicesMixin<T extends typeof OxyServicesBase
         };
         clearCache(): void;
         clearCacheEntry(key: string): void;
+        clearCacheByPrefix(prefix: string): number;
         getCacheStats(): {
             size: number;
             hits: number;

package/dist/types/mixins/OxyServices.features.d.ts

@@ -177,10 +177,6 @@ export declare function OxyServicesFeaturesMixin<T extends typeof OxyServicesBas
          * Get all available achievements
          */
         getAllAchievements(): Promise<Achievement[]>;
-        /**
-         * Delete user account (requires password confirmation)
-         */
-        deleteAccount(password: string): Promise<void>;
         httpService: import("../HttpService").HttpService;
         cloudURL: string;
         config: import("../OxyServices.base").OxyConfig;
@@ -198,6 +194,7 @@ export declare function OxyServicesFeaturesMixin<T extends typeof OxyServicesBas
         };
         clearCache(): void;
         clearCacheEntry(key: string): void;
+        clearCacheByPrefix(prefix: string): number;
         getCacheStats(): {
             size: number;
             hits: number;
@@ -225,9 +222,7 @@ export declare function OxyServicesFeaturesMixin<T extends typeof OxyServicesBas
         healthCheck(): Promise<{
             status: string;
             users?: number;
-            timestamp? /**
-             * Get FAQs
-             */: string;
+            timestamp?: string;
             [key: string]: any;
         }>;
     };