@oxy.so/core 1.0.0

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

@@ -0,0 +1,146 @@
+/**
+ * Privacy Methods Mixin (Blocked & Restricted Users)
+ */
+import type { BlockedUser, RestrictedUser } from '../models/interfaces';
+import type { OxyServicesBase } from '../OxyServices.base';
+export declare function OxyServicesPrivacyMixin<T extends typeof OxyServicesBase>(Base: T): {
+    new (...args: any[]): {
+        /**
+         * Extract user ID from blocked/restricted user object
+         */
+        extractUserId(userIdField: string | {
+            _id: string;
+            username?: string;
+            avatar?: string;
+        }): string;
+        /**
+         * Check if a user is in a list (blocked or restricted)
+         */
+        isUserInList<T_1 extends BlockedUser | RestrictedUser>(userId: string, getUserList: () => Promise<T_1[]>, getIdField: (item: T_1) => string | {
+            _id: string;
+            username?: string;
+            avatar?: string;
+        }): Promise<boolean>;
+        /**
+         * Get list of blocked users
+         * @returns Array of blocked users
+         */
+        getBlockedUsers(): Promise<BlockedUser[]>;
+        /**
+         * Block a user.
+         *
+         * Invalidates the cached `GET /privacy/blocked` response after the write.
+         * `getBlockedUsers` caches for ~1 minute (identity-scoped); without busting
+         * that entry, a consumer that re-reads the blocked list within the TTL
+         * window would not see the user it just blocked. `clearCacheEntry` deletes
+         * every identity-scoped variant of the key.
+         * @param userId - The user ID to block
+         * @returns Success message
+         */
+        blockUser(userId: string): Promise<{
+            message: string;
+        }>;
+        /**
+         * Unblock a user.
+         *
+         * Busts the cached `GET /privacy/blocked` response so a remount reads the
+         * fresh list without the just-unblocked user (see `blockUser`).
+         * @param userId - The user ID to unblock
+         * @returns Success message
+         */
+        unblockUser(userId: string): Promise<{
+            message: string;
+        }>;
+        /**
+         * Check if a user is blocked
+         * @param userId - The user ID to check
+         * @returns True if the user is blocked, false otherwise
+         */
+        isUserBlocked(userId: string): Promise<boolean>;
+        /**
+         * Get list of restricted users
+         * @returns Array of restricted users
+         */
+        getRestrictedUsers(): Promise<RestrictedUser[]>;
+        /**
+         * Restrict a user (limit their interactions without fully blocking).
+         *
+         * Invalidates the cached `GET /privacy/restricted` response after the write.
+         * `getRestrictedUsers` caches for ~1 minute (identity-scoped); without
+         * busting that entry, a consumer that re-reads the restricted list within
+         * the TTL window would not see the user it just restricted.
+         * `clearCacheEntry` deletes every identity-scoped variant of the key.
+         * @param userId - The user ID to restrict
+         * @returns Success message
+         */
+        restrictUser(userId: string): Promise<{
+            message: string;
+        }>;
+        /**
+         * Unrestrict a user.
+         *
+         * Busts the cached `GET /privacy/restricted` response so a remount reads the
+         * fresh list without the just-unrestricted user (see `restrictUser`).
+         * @param userId - The user ID to unrestrict
+         * @returns Success message
+         */
+        unrestrictUser(userId: string): Promise<{
+            message: string;
+        }>;
+        /**
+         * Check if a user is restricted
+         * @param userId - The user ID to check
+         * @returns True if the user is restricted, false otherwise
+         */
+        isUserRestricted(userId: string): Promise<boolean>;
+        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.reputation.d.ts

@@ -0,0 +1,202 @@
+/**
+ * Reputation Methods Mixin (Oxy Trust)
+ *
+ * Provides typed access to the reputation ledger (#217) and the derived
+ * trust-tier / capped-influence model (#219) via the `/reputation` API.
+ *
+ * The reputation ledger is append-only: transactions are NEVER deleted.
+ * A correction is expressed either as a compensating REVERSAL (the original is
+ * marked `reversed` and a new `active` transaction with negated points is
+ * appended) or a VOID (the original is marked `voided` and excluded from the
+ * balance). A user's `ReputationBalance` is a recomputable cache of the sum of
+ * their `active` transactions, augmented with a trust tier, capped influence
+ * weights, and reliability signals.
+ *
+ * A balance is served in TWO views (see `ReputationBalanceView`): the subject
+ * and platform staff get the whole thing, a third party gets the public trust
+ * signal only. The two are distinct types so a caller cannot read a field the
+ * server did not send them.
+ *
+ * EVERY type on this surface is owned by `@oxy.so/contracts`, which the API's
+ * serializers are annotated and validated against. This mixin declares none of
+ * them and re-exports none of them: consumers import the types straight from
+ * `@oxy.so/contracts`, so the wire shape has exactly one definition and a
+ * server-side change to a serializer cannot compile while the type still
+ * promises the old shape.
+ *
+ * Reference users by their Mongo `_id` (or publicKey, which the API resolves),
+ * transactions by their `id`, and disputes by their `id`.
+ */
+import type { AwardReputationInput, CreateReputationDisputeInput, ReputationBalance, ReputationBalanceView, ReputationDispute, ReputationInfluenceContext, ReputationInfluenceResult, ReputationLeaderboardEntry, ReputationRule, ReputationTransaction, ResolveReputationDisputeInput, ReverseReputationTransactionInput, ReverseReputationTransactionResult, UpsertReputationRuleInput } from '@oxy.so/contracts';
+import type { OxyServicesBase } from '../OxyServices.base';
+export declare function OxyServicesReputationMixin<T extends typeof OxyServicesBase>(Base: T): {
+    new (...args: any[]): {
+        /**
+         * Get ANY user's reputation balance, in whichever view the server serves the
+         * caller.
+         *
+         * A third party gets `userId`, `total` and `trustTier` and nothing else, so
+         * the return type is a {@link ReputationBalanceView} union: narrow it with
+         * {@link isFullReputationBalance} before touching `breakdown`, `influence`
+         * or `reliability`. To read your OWN balance, call
+         * {@link getMyReputationBalance} instead — it returns the full shape with no
+         * narrowing.
+         *
+         * @param userId - The subject user's `_id` or publicKey.
+         */
+        getReputationBalance(userId: string): Promise<ReputationBalanceView>;
+        /**
+         * Get the SIGNED-IN user's own reputation balance, in full.
+         *
+         * The subject view is the only one carrying `breakdown`, `influence` and
+         * `reliability`, and the subject is the common caller, so this is the
+         * ergonomic path: no id to pass, no narrowing to do.
+         *
+         * Throws rather than returning a half-populated object when the request was
+         * not authenticated as the subject — with no signed-in user, and when the
+         * server answered `200` with the public view anyway (which it does for an
+         * absent or lapsed token, since the endpoint's auth is optional). Both mean
+         * the private blocks are simply absent, and a thrown error is the only
+         * honest report of that.
+         */
+        getMyReputationBalance(): Promise<ReputationBalance>;
+        /**
+         * Get the reputation leaderboard, ordered by lifetime total descending.
+         * @param limit - Page size (server-capped).
+         * @param offset - Page offset.
+         */
+        getReputationLeaderboard(limit?: number, offset?: number): Promise<ReputationLeaderboardEntry[]>;
+        /**
+         * List the enabled reputation rules (for client display).
+         */
+        getReputationRules(): Promise<ReputationRule[]>;
+        /**
+         * Get a user's paginated reputation ledger, newest first (auth required).
+         * @param userId - The subject user's `_id` or publicKey.
+         * @param limit - Page size (server-capped).
+         * @param offset - Page offset.
+         */
+        getReputationTransactions(userId: string, limit?: number, offset?: number): Promise<ReputationTransaction[]>;
+        /**
+         * Get a user's capped influence weight for a given context (auth required).
+         * @param userId - The subject user's `_id` or publicKey.
+         * @param context - The weight axis to read (defaults server-side to `default`).
+         */
+        getReputationInfluence(userId: string, context?: ReputationInfluenceContext): Promise<ReputationInfluenceResult>;
+        /**
+         * Award (or penalise) reputation to a user by `actionType`. Restricted to
+         * service tokens and platform staff. Invalidates cached reputation reads.
+         * @param input - The award payload (subject, action, source, target, etc.).
+         */
+        awardReputation(input: AwardReputationInput): Promise<ReputationTransaction>;
+        /**
+         * Open a dispute against a transaction (auth required; the disputer is the
+         * authenticated user and must own the transaction).
+         * @param input - The transaction id, reason, and optional evidence.
+         */
+        createReputationDispute(input: CreateReputationDisputeInput): Promise<ReputationDispute>;
+        /**
+         * List a user's own reputation disputes (auth required; the caller must be
+         * the subject or platform staff).
+         * @param userId - The subject user's `_id` or publicKey.
+         * @param limit - Page size (server-capped).
+         * @param offset - Page offset.
+         */
+        getUserReputationDisputes(userId: string, limit?: number, offset?: number): Promise<ReputationDispute[]>;
+        /**
+         * Create or update a reputation rule, keyed by `actionType` (staff only).
+         * Invalidates the cached rule list.
+         * @param input - The rule definition.
+         */
+        upsertReputationRule(input: UpsertReputationRuleInput): Promise<ReputationRule>;
+        /**
+         * Reverse a transaction (staff only): mark the original `reversed` and append
+         * a compensating `active` reversal with negated points. Invalidates cached
+         * reputation reads.
+         * @param transactionId - The transaction's id.
+         * @param input - Optional reason for the reversal.
+         */
+        reverseReputationTransaction(transactionId: string, input?: ReverseReputationTransactionInput): Promise<ReverseReputationTransactionResult>;
+        /**
+         * Void a transaction (staff only): mark it `voided` so it is excluded from
+         * the balance, with NO compensating entry. Invalidates cached reputation
+         * reads.
+         * @param transactionId - The transaction's id.
+         * @param input - Optional reason for the void.
+         */
+        voidReputationTransaction(transactionId: string, input?: ReverseReputationTransactionInput): Promise<ReputationTransaction>;
+        /**
+         * Force a recompute of a user's balance snapshot from their active ledger
+         * (staff only). Invalidates cached reputation reads.
+         *
+         * Staff-gated, so the response is always the full subject view — no
+         * narrowing needed.
+         *
+         * @param userId - The subject user's `_id` or publicKey.
+         */
+        recalculateReputation(userId: string): Promise<ReputationBalance>;
+        /**
+         * Get the open dispute queue across all users (staff only).
+         * @param limit - Page size (server-capped).
+         * @param offset - Page offset.
+         */
+        getReputationDisputeQueue(limit?: number, offset?: number): Promise<ReputationDispute[]>;
+        /**
+         * Resolve a dispute (staff only). Accepting reverses the disputed
+         * transaction; rejecting restores it to `active`. Invalidates cached
+         * reputation reads.
+         * @param disputeId - The dispute's id.
+         * @param input - The resolution (`accepted` or `rejected`).
+         */
+        resolveReputationDispute(disputeId: string, input: ResolveReputationDisputeInput): Promise<ReputationDispute>;
+        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.security.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Security Methods Mixin
+ */
+import type { OxyServicesBase } from '../OxyServices.base';
+import type { SecurityActivity, SecurityActivityResponse, SecurityEventType } from '../models/interfaces';
+export declare function OxyServicesSecurityMixin<T extends typeof OxyServicesBase>(Base: T): {
+    new (...args: any[]): {
+        /**
+         * Get user's security activity with pagination
+         * @param limit - Number of results (default: 50, max: 100)
+         * @param offset - Pagination offset (default: 0)
+         * @param eventType - Optional filter by event type
+         * @returns Security activity response with pagination
+         */
+        getSecurityActivity(limit?: number, offset?: number, eventType?: SecurityEventType): Promise<SecurityActivityResponse>;
+        /**
+         * Get recent security activity (convenience method)
+         * @param limit - Number of recent events to fetch (default: 10)
+         * @returns Array of recent security activities
+         */
+        getRecentSecurityActivity(limit?: number): Promise<SecurityActivity[]>;
+        /**
+         * Log private key exported event
+         * @param deviceId - Optional device ID for tracking
+         * @returns Promise that resolves when event is logged
+         */
+        logPrivateKeyExported(deviceId?: string): Promise<void>;
+        /**
+         * Log backup created event
+         * @param deviceId - Optional device ID for tracking
+         * @returns Promise that resolves when event is logged
+         */
+        logBackupCreated(deviceId?: string): Promise<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;