@oxy.so/core 1.0.0

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

@@ -0,0 +1,351 @@
+/**
+ * Identity Methods Mixin (self-sovereign identity layer)
+ *
+ * Provides typed access to Oxy's AtProto/Bluesky-flavoured identity &
+ * portability layer:
+ *  - DID resolution (`did:web:oxy.so:u:<userId>`, derived on demand by the API).
+ *  - The auth-method ↔ DID verification-method mapping and its reversibility
+ *    (link/unlink an identity key, link a password) via the existing
+ *    `/auth/link` surface.
+ *  - Signed records: clients sign an envelope with their own cryptographic key
+ *    (`SignatureService.signRecord` + the shared `canonicalize`) and publish it;
+ *    anyone can fetch and verify it.
+ *  - The signed data-export ("credible exit") bundle.
+ *  - Verified-domain badges (prove ownership of `nate.com`).
+ *
+ * Wire shapes come from `@oxy.so/contracts` (`DidDocument`,
+ * `SignedRecordEnvelope`, `AuthMethodsResponse`, `VerifiedDomain`,
+ * `DomainVerificationInstructions`, `ExportBundle`) — the single source of truth
+ * the API validates its output against, so producer and consumer cannot drift.
+ *
+ * Identity signing is NATIVE-ONLY: the private key lives in native secure
+ * storage, so `linkIdentityKey`, `signRecord`, and `publishRecord` require an
+ * on-device identity and throw on web (where `KeyManager.getPublicKey()` is
+ * always `null`).
+ */
+import type { AuthMethodsResponse, DidDocument, DomainVerificationInstructions, ExportBundle, OxySignedRecordType, SignedRecordEnvelope, VerifiedDomain } from '@oxy.so/contracts';
+import type { OxyServicesBase } from '../OxyServices.base';
+import { type PendingIdentityResult } from '../crypto/recoveryPhrase';
+/**
+ * Record categories a client may sign and publish to the Oxy store. The base
+ * envelope `type` is now an open string (any app may define its own records on
+ * the shared grammar); the Oxy identity store re-narrows it to the closed Oxy
+ * record set.
+ */
+export type IdentityRecordType = OxySignedRecordType;
+/** Auth-method types that can be unlinked via {@link OxyServicesIdentityMixin}. */
+export type UnlinkableAuthMethodType = 'identity' | 'webauthn';
+/**
+ * Result of a link/unlink auth-method mutation (`POST /auth/link`,
+ * `DELETE /auth/link/:type`).
+ */
+export interface LinkAuthMethodResult {
+    success: boolean;
+    message: string;
+}
+/**
+ * Result of publishing a signed record (`POST /identity/records`). Echoes the
+ * stored envelope plus the server's verification verdict.
+ */
+export interface PublishRecordResult {
+    envelope: SignedRecordEnvelope;
+    verified: boolean;
+}
+/**
+ * Result of verifying a stored record (`GET /identity/records/:userId/:type/verify`).
+ * `verified` is the server's verdict; `reason` is present when it is `false`.
+ */
+export interface VerifyRecordResult {
+    verified: boolean;
+    reason?: string;
+}
+/** Result of a successful domain verification (`POST /identity/domains/:domain/verify`). */
+export interface VerifyDomainResult {
+    verified: boolean;
+    domain: VerifiedDomain;
+}
+/** Result of removing a verified domain (`DELETE /identity/domains/:domain`). */
+export interface RemoveDomainResult {
+    success: boolean;
+}
+/** How the caller proves control of the CURRENT key during a key rotation. */
+export type RotateKeyProof = 'device' | 'phrase';
+/** Options for {@link OxyServicesIdentityMixin.rotateKey}. */
+export interface RotateKeyOptions {
+    /**
+     * How to prove control of the CURRENT key:
+     *  - `'device'`: sign with the on-device SecureStore key (native-only).
+     *  - `'phrase'`: re-derive the current key from the entered recovery `phrase`
+     *    and sign with it. This works even when the device holds NO SecureStore
+     *    copy of the key — it is how the LAST remaining credential is replaced.
+     */
+    proof: RotateKeyProof;
+    /** The CURRENT identity's recovery phrase. Required when `proof: 'phrase'`. */
+    phrase?: string;
+    /**
+     * When true, all OTHER active sessions are revoked after a successful
+     * rotation (the rotating device stays signed in). Use it when the old key is
+     * presumed compromised.
+     */
+    signOutEverywhere?: boolean;
+    /**
+     * A pre-derived NEW identity to rotate to (from
+     * {@link RecoveryPhraseService.derivePendingIdentity}). Pass it when the UI
+     * derived + SHOWED the new phrase to the user BEFORE committing, so the SAME
+     * identity is the one rotated in. When omitted, a fresh identity is derived
+     * internally and its phrase is returned in the result.
+     */
+    pendingIdentity?: PendingIdentityResult;
+}
+/** Result of a successful key rotation. */
+export interface RotateKeyResult {
+    /** The account's new (rotated) public key. */
+    newPublicKey: string;
+    /**
+     * The NEW identity's recovery phrase. It MUST be surfaced to the user so they
+     * can back up the rotated key — if lost, the new identity is unrecoverable.
+     */
+    newPhrase: string;
+    /** The recovery phrase split into its individual words. */
+    words: string[];
+    /**
+     * Present (and `true`) only when the server rotated successfully but the new
+     * key could NOT be persisted on-device. The account key IS the new one
+     * server-side, so the user must re-import it from `newPhrase`; the caller
+     * should surface a recovery prompt. Omitted on full success.
+     */
+    localPersistFailed?: true;
+}
+/**
+ * Derive a user's Oxy DID from their stable account id.
+ * `did:web:oxy.so:u:<userId>`.
+ */
+export declare function buildUserDid(userId: string): string;
+export declare function OxyServicesIdentityMixin<T extends typeof OxyServicesBase>(Base: T): {
+    new (...args: any[]): {
+        /**
+         * Resolve the W3C DID document for any user. The API derives it on demand
+         * from the account's `authMethods` + `publicKey` — there is no stored
+         * document. Public (no auth required); short-TTL cached.
+         *
+         * @param userId - The account's Mongo `_id`. URL-encoded into the path.
+         */
+        resolveDid(userId: string): Promise<DidDocument>;
+        /**
+         * The current user's DID (`did:web:oxy.so:u:<userId>`), derived locally from
+         * the access token's user id. Throws if no user is authenticated.
+         */
+        getMyDid(): string;
+        /** Resolve the current user's DID document. Requires an authenticated session. */
+        getMyDidDocument(): Promise<DidDocument>;
+        /**
+         * List the current user's linked authentication methods plus their DID.
+         * Each `identity` method carries a `verificationMethodId` linking it to its
+         * DID verification-method fragment.
+         */
+        listAuthMethods(): Promise<AuthMethodsResponse>;
+        /**
+         * Link the on-device cryptographic identity to the current account,
+         * upgrading it from custodial to self-sovereign. Signs a proof of private
+         * key ownership and posts it to `POST /auth/link`.
+         *
+         * NATIVE-ONLY: requires a stored identity (throws if `KeyManager` has no key
+         * or no user is authenticated). The signed payload is
+         * `JSON.stringify({ action: 'link_identity', userId, timestamp })` — the
+         * exact bytes the server reconstructs and verifies.
+         */
+        linkIdentityKey(): Promise<LinkAuthMethodResult>;
+        /**
+         * Unlink an authentication method from the current account. The server
+         * refuses to remove the last remaining method (the account would become
+         * inaccessible). Unlinking `identity` downgrades the account to custodial.
+         *
+         * @param type - The auth-method type to remove.
+         */
+        unlinkAuthMethod(type: UnlinkableAuthMethodType): Promise<LinkAuthMethodResult>;
+        /**
+         * Remove ONE passkey (WebAuthn credential) from the current account.
+         *
+         * Passkeys are per-credential, so unlike {@link unlinkAuthMethod} (which
+         * removes an auth method by type) this targets a specific credential id.
+         * The server refuses to remove the last remaining auth method (the account
+         * would become inaccessible) and deletes the stored `WebauthnCredential`.
+         *
+         * @param credentialId - The passkey's public credential id
+         *   (`AuthMethodEntry.credentialId`).
+         */
+        removePasskey(credentialId: string): Promise<LinkAuthMethodResult>;
+        /**
+         * Rotate the account's identity key: derive a brand-new keypair, prove
+         * control of the CURRENT key, and have the server ATOMICALLY replace the old
+         * key with the new one.
+         *
+         * The rotation is an atomic REPLACE on the server (never remove-then-add), so
+         * it never passes through a zero-auth-method state and is independent of the
+         * unlink guards. Because control of the current key is PROVEN (from
+         * SecureStore in `'device'` mode, or a recovery-phrase re-derivation in
+         * `'phrase'` mode), even the LAST remaining credential can be replaced.
+         *
+         * Ordering (safety-critical): the new key is persisted on-device ONLY AFTER
+         * the server confirms the swap. Persisting earlier would clobber the local
+         * key while the server still trusts the old one, locking the device out.
+         *
+         * Ambiguous-network-failure guard: if the `complete` response is lost
+         * (request sent, no reply), the swap may already have applied server-side.
+         * Before surfacing the error we reconcile against the derived DID document —
+         * if it already advertises the new key, the rotation is treated as done.
+         *
+         * NOTE: the UI is responsible for showing `newPhrase` to the user. For a
+         * "show-phrase-first" flow, derive the identity up front via
+         * {@link RecoveryPhraseService.derivePendingIdentity}, display it, then pass
+         * it back as `options.pendingIdentity` so the SAME identity is committed.
+         *
+         * @throws when no user is authenticated, when `proof: 'phrase'` is given
+         *   without a `phrase`, when `proof: 'device'` runs with no on-device key,
+         *   or when the rotation does not complete.
+         */
+        rotateKey(options: RotateKeyOptions): Promise<RotateKeyResult>;
+        /**
+         * Reconciliation probe for the rotation ambiguous-failure guard: fetch the
+         * account's derived DID document (uncached) and report whether it already
+         * advertises `newPublicKey` as a verification method — i.e. whether the swap
+         * already landed server-side. A failed probe returns `false` (unconfirmed),
+         * so the caller surfaces the original network error.
+         *
+         * Uses the DID document rather than `GET /auth/methods` because the latter
+         * intentionally does NOT expose raw public keys, whereas the DID's
+         * `verificationMethod[].publicKeyHex` is derived live from the account's
+         * current key — so it reflects a completed rotation immediately.
+         *
+         * Internal helper (leading underscore); public rather than `private` for the
+         * same TS4094 reason as {@link _invalidateIdentityCaches}.
+         */
+        _rotationAlreadyApplied(userId: string, newPublicKey: string): Promise<boolean>;
+        /**
+         * Sign a record with the on-device identity key, WITHOUT publishing it.
+         * The subject is the current user's DID. NATIVE-ONLY (requires a stored
+         * key). Use {@link publishRecord} to sign and store in one step.
+         *
+         * @param type - The record category.
+         * @param record - The arbitrary record payload to attest to.
+         */
+        signRecord(type: IdentityRecordType, record: Record<string, unknown>): Promise<SignedRecordEnvelope>;
+        /**
+         * Sign a record and publish it to the append-only record store
+         * (`POST /identity/records`). NATIVE-ONLY (requires a stored key).
+         *
+         * @param type - The record category.
+         * @param record - The arbitrary record payload to attest to.
+         */
+        publishRecord(type: IdentityRecordType, record: Record<string, unknown>): Promise<PublishRecordResult>;
+        /**
+         * Fetch a user's most recent signed record of a given type. Public (no auth
+         * required); short-TTL cached.
+         *
+         * @param userId - The subject account's Mongo `_id`.
+         * @param type - The record category to fetch.
+         */
+        getRecord(userId: string, type: IdentityRecordType): Promise<SignedRecordEnvelope>;
+        /**
+         * Ask the server to verify a user's stored record: it recomputes the
+         * canonical signing input, checks the signature, and asserts the signing key
+         * is a current verification method on the subject's DID.
+         *
+         * @param userId - The subject account's Mongo `_id`.
+         * @param type - The record category to verify.
+         */
+        verifyRecord(userId: string, type: IdentityRecordType): Promise<VerifyRecordResult>;
+        /**
+         * Download the current user's signed, open-format data-export bundle
+         * (`GET /users/me/export`) — the "credible exit" snapshot. Always carries an
+         * Oxy provenance `attestation`; carries an optional client `proof` when the
+         * account holds its own key.
+         */
+        exportMyData(): Promise<ExportBundle>;
+        /**
+         * Start verifying ownership of a domain. Returns the instructions: publish
+         * EITHER the DNS-TXT record OR the `/.well-known/oxy-domain` file, then call
+         * {@link verifyDomain}.
+         *
+         * @param domain - The domain to claim (e.g. `nate.com`).
+         */
+        requestDomainVerification(domain: string): Promise<DomainVerificationInstructions>;
+        /**
+         * Complete domain verification: the server checks the DNS-TXT record or
+         * well-known file and, on success, attaches the domain to the account
+         * (surfaced in the DID's `alsoKnownAs` and the user's `verifiedDomains`).
+         *
+         * @param domain - The domain previously requested via
+         *   {@link requestDomainVerification}.
+         */
+        verifyDomain(domain: string): Promise<VerifyDomainResult>;
+        /** List the current user's verified domains. */
+        listDomains(): Promise<VerifiedDomain[]>;
+        /**
+         * Remove a verified domain from the current account.
+         * @param domain - The verified domain to remove.
+         */
+        removeDomain(domain: string): Promise<RemoveDomainResult>;
+        /**
+         * Bust the cached reads that an identity mutation invalidates: the current
+         * user (`/users/me*`), the linked auth-methods list, the verified-domains
+         * list, and the user's derived DID document (which embeds auth methods +
+         * verified domains, so it goes stale on link/unlink/domain changes).
+         *
+         * Internal helper (leading underscore); not part of the supported public
+         * surface. Public rather than `private` because mixins compose into an
+         * exported anonymous class, where TypeScript cannot represent a private
+         * member in the emitted declaration file (TS4094).
+         */
+        _invalidateIdentityCaches(userId: string | null): void;
+        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;
+        createLinkedClient(config: import("../OxyServices.base").OxyConfig): import("..").LinkedHttpClient;
+        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): void;
+        clearTokens(): void;
+        onTokensChanged(listener: (accessToken: string | null) => void): () => void;
+        _cachedUserId: string | null | undefined;
+        _cachedAccessToken: string | null;
+        getCurrentUserId(): string | null;
+        hasValidToken(): boolean;
+        getAccessToken(): string | null;
+        getAccessTokenExpiry(): number | 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.identityBackup.d.ts

@@ -0,0 +1,129 @@
+/**
+ * Encrypted off-device identity backup mixin (b3 Feature 1).
+ *
+ * Lets a self-custody identity store an ENCRYPTED copy of its key off-device so
+ * a lost/wiped device can be recovered from the recovery phrase alone — while the
+ * platform never sees the phrase, the derived key, or the plaintext private key.
+ *
+ * Key schedule (from the recovery phrase; see
+ * {@link RecoveryPhraseService.deriveBackupMaterial}):
+ *   seed      = mnemonicToSeed(phrase)                          // 64 bytes, UNCHANGED
+ *   backupKey = HKDF(seed, 'oxy-identity-backup-v1', 'oxy-backup-encryption-key')
+ *   lookupId  = HKDF(seed, 'oxy-identity-backup-v1', 'oxy-backup-lookup-id')   // hex
+ *
+ * The two derivations require the FULL seed, so a device compromise that leaks
+ * only the raw 32-byte private key can neither locate nor decrypt the backup.
+ *
+ * Wire shapes come from `@oxy.so/contracts` (`EncryptedBackupEnvelope`,
+ * `BackupUploadRequest`, `BackupStatusResponse`) — the API validates its
+ * request/response against the same schemas, so producer and consumer cannot
+ * drift.
+ *
+ * Encryption/derivation are cross-platform (pure `@noble/*`), but persisting a
+ * restored key is NATIVE-ONLY: `restoreFromEncryptedBackup` ends in
+ * `KeyManager.importKeyPair`, which throws on web (SecureStore does not exist
+ * there) — decryption still succeeds, only the local write is native-only.
+ */
+import type { BackupStatusResponse } from '@oxy.so/contracts';
+import type { OxyServicesBase } from '../OxyServices.base';
+export declare function OxyServicesIdentityBackupMixin<T extends typeof OxyServicesBase>(Base: T): {
+    new (...args: any[]): {
+        /**
+         * Derive the backup key material from the recovery phrase, encrypt the
+         * identity's `{privateKey, publicKey, createdAt}` with it, and upload the
+         * ciphertext + raw `lookupId` (`POST /identity/backup`, bearer). The server
+         * stores only `sha256(lookupId)` + the ciphertext. Idempotent per user: a
+         * re-upload REPLACES the prior backup (upsert by user id).
+         *
+         * The identity is derived from the PHRASE (not read from SecureStore), so
+         * this works cross-platform and does not require an on-device key.
+         *
+         * @param phrase - The identity's BIP-39 recovery phrase.
+         * @returns The post-write backup status (`{ exists: true, publicKeyHint, createdAt }`).
+         */
+        createEncryptedBackup(phrase: string): Promise<BackupStatusResponse>;
+        /**
+         * Whether the authenticated user has a stored encrypted backup, plus the
+         * non-sensitive hint + timestamp when one exists (`GET /identity/backup/status`,
+         * bearer). Returns no ciphertext and no locator.
+         */
+        getBackupStatus(): Promise<BackupStatusResponse>;
+        /**
+         * Delete the authenticated user's stored backup (`DELETE /identity/backup`,
+         * bearer). Idempotent — deleting a non-existent backup still succeeds.
+         */
+        deleteBackup(): Promise<{
+            success: boolean;
+        }>;
+        /**
+         * Restore an identity from its encrypted off-device backup using ONLY the
+         * recovery phrase: re-derive `{backupKey, lookupId}`, fetch the envelope by
+         * `lookupId` (`GET /identity/backup/:lookupId`, PUBLIC — the 256-bit locator
+         * is the protection), decrypt + authenticate locally, then persist the key.
+         *
+         * NATIVE-ONLY persistence: `KeyManager.importKeyPair` throws on web. It also
+         * refuses to clobber a DIFFERENT existing on-device identity unless
+         * `overwrite: true` — the {@link import('../crypto/keyManager').IdentityAlreadyExistsError}
+         * propagates to the caller (never swallowed) so the UI can confirm before
+         * overwriting.
+         *
+         * @param phrase - The identity's BIP-39 recovery phrase.
+         * @param options.overwrite - Replace a different existing on-device identity.
+         * @returns The restored identity's public key.
+         * @throws if the phrase is invalid, no backup exists (404), the ciphertext
+         *   fails authentication (tamper), or an existing identity blocks the import.
+         */
+        restoreFromEncryptedBackup(phrase: string, options?: {
+            overwrite?: boolean;
+        }): Promise<string>;
+        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;
+        createLinkedClient(config: import("../OxyServices.base").OxyConfig): import("..").LinkedHttpClient;
+        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): void;
+        clearTokens(): void;
+        onTokensChanged(listener: (accessToken: string | null) => void): () => void;
+        _cachedUserId: string | null | undefined;
+        _cachedAccessToken: string | null;
+        getCurrentUserId(): string | null;
+        hasValidToken(): boolean;
+        getAccessToken(): string | null;
+        getAccessTokenExpiry(): number | 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.inference.d.ts

@@ -0,0 +1,95 @@
+/**
+ * The inference API, reached with whatever bearer this session already holds
+ * (issue #972, workstream 15).
+ *
+ * ```typescript
+ * const models = await oxyServices.inference().listModels();
+ * ```
+ *
+ * One method, and it is a FACTORY rather than a set of inference methods on
+ * `OxyServices`. The calls themselves live once, in
+ * {@link OxyInferenceClient} — which an external developer holding only an
+ * `oxy_sk_…` machine key constructs directly, with no Oxy session anywhere in
+ * the picture. Declaring the same calls a second time here would give the
+ * ecosystem two spellings of one request, and only one of them would stay
+ * correct.
+ *
+ * This is the reasoning `createLinkedClient` is already built on: the plumbing
+ * that binds an Oxy bearer to a client belongs in core, once, rather than in
+ * each app.
+ *
+ * The credential is a FUNCTION, not the current token: a session bearer rotates
+ * on refresh and on account switch, and a client that captured one at
+ * construction would start answering 401 an hour into the process's life.
+ */
+import { OxyInferenceClient } from '../inference/OxyInferenceClient';
+import type { OxyServicesBase } from '../OxyServices.base';
+export declare function OxyServicesInferenceMixin<T extends typeof OxyServicesBase>(Base: T): {
+    new (...args: any[]): {
+        /** @internal Memoized so repeated calls return one object identity. */
+        _inferenceClient: OxyInferenceClient | null;
+        /**
+         * The inference client for this session.
+         *
+         * Bound to this instance's base URL and to `getAccessToken()`, so it
+         * follows every refresh, sign-in and account switch without being
+         * rebuilt.
+         *
+         * A service-authenticated process wants a different credential and
+         * builds {@link OxyInferenceClient} directly:
+         * `new OxyInferenceClient({ credential: () => oxy.getServiceToken() })`.
+         * The mint is asynchronous and cached, which is exactly what a
+         * credential function is for.
+         */
+        inference(): OxyInferenceClient;
+        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;
+        createLinkedClient(config: import("../OxyServices.base").OxyConfig): import("..").LinkedHttpClient;
+        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): void;
+        clearTokens(): void;
+        onTokensChanged(listener: (accessToken: string | null) => void): () => void;
+        _cachedUserId: string | null | undefined;
+        _cachedAccessToken: string | null;
+        getCurrentUserId(): string | null;
+        hasValidToken(): boolean;
+        getAccessToken(): string | null;
+        getAccessTokenExpiry(): number | 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.language.d.ts

@@ -0,0 +1,87 @@
+import type { SupportedLanguage } from '../utils/languageUtils';
+import type { OxyServicesBase } from '../OxyServices.base';
+export declare function OxyServicesLanguageMixin<T extends typeof OxyServicesBase>(Base: T): {
+    new (...args: any[]): {
+        /**
+         * Get appropriate storage for the platform (similar to DeviceManager)
+         */
+        getStorage(): Promise<{
+            getItem: (key: string) => Promise<string | null>;
+            setItem: (key: string, value: string) => Promise<void>;
+            removeItem: (key: string) => Promise<void>;
+        }>;
+        /**
+         * Get the current locale from the user profile or local storage.
+         * @param storageKeyPrefix - Optional prefix for storage key (default: 'oxy_session')
+         * @returns The current BCP-47 locale (e.g., 'en-US') or null if not set
+         */
+        getCurrentLanguage(storageKeyPrefix?: string): Promise<string | null>;
+        /**
+         * Get the current language with metadata (name, nativeName, etc.)
+         * @param storageKeyPrefix - Optional prefix for storage key (default: 'oxy_session')
+         * @returns Language metadata object or null if not set
+         */
+        getCurrentLanguageMetadata(storageKeyPrefix?: string): Promise<SupportedLanguage | null>;
+        /**
+         * Get the current language name (e.g., 'English')
+         * @param storageKeyPrefix - Optional prefix for storage key (default: 'oxy_session')
+         * @returns Language name or null if not set
+         */
+        getCurrentLanguageName(storageKeyPrefix?: string): Promise<string | null>;
+        /**
+         * Get the current native language name (e.g., 'Español')
+         * @param storageKeyPrefix - Optional prefix for storage key (default: 'oxy_session')
+         * @returns Native language name or null if not set
+         */
+        getCurrentNativeLanguageName(storageKeyPrefix?: string): Promise<string | null>;
+        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;
+        createLinkedClient(config: import("../OxyServices.base").OxyConfig): import("..").LinkedHttpClient;
+        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): void;
+        clearTokens(): void;
+        onTokensChanged(listener: (accessToken: string | null) => void): () => void;
+        _cachedUserId: string | null | undefined;
+        _cachedAccessToken: string | null;
+        getCurrentUserId(): string | null;
+        hasValidToken(): boolean;
+        getAccessToken(): string | null;
+        getAccessTokenExpiry(): number | 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;