@oxy.so/core 1.0.0

package/src/mixins/OxyServices.privacy.ts

@@ -0,0 +1,219 @@
+/**
+ * Privacy Methods Mixin (Blocked & Restricted Users)
+ */
+import type { BlockedUser, RestrictedUser } from '../models/interfaces';
+import type { OxyServicesBase } from '../OxyServices.base';
+import { logger } from '../logger';
+
+export function OxyServicesPrivacyMixin<T extends typeof OxyServicesBase>(Base: T) {
+  return class extends Base {
+    constructor(...args: any[]) {
+      super(...(args as [any]));
+    }
+    /**
+     * Extract user ID from blocked/restricted user object
+     */
+    public extractUserId(userIdField: string | { _id: string; username?: string; avatar?: string }): string {
+      return typeof userIdField === 'string' ? userIdField : userIdField._id;
+    }
+
+    /**
+     * Check if a user is in a list (blocked or restricted)
+     */
+    public async isUserInList<T extends BlockedUser | RestrictedUser>(
+      userId: string,
+      getUserList: () => Promise<T[]>,
+      getIdField: (item: T) => string | { _id: string; username?: string; avatar?: string }
+    ): Promise<boolean> {
+      try {
+        if (!userId) {
+          return false;
+        }
+        const users = await getUserList();
+        return users.some(item => {
+          const itemId = this.extractUserId(getIdField(item));
+          return itemId === userId;
+        });
+      } catch (error) {
+        // If there's an error, assume not in list to avoid breaking functionality
+        logger.warn('Error checking user list', { component: 'OxyServices.privacy' }, error);
+        return false;
+      }
+    }
+
+    // ============================================================================
+    // BLOCKED USERS METHODS
+    // ============================================================================
+
+    /**
+     * Get list of blocked users
+     * @returns Array of blocked users
+     */
+    async getBlockedUsers(): Promise<BlockedUser[]> {
+      try {
+        return await this.makeRequest<BlockedUser[]>('GET', '/privacy/blocked', undefined, {
+          cache: true,
+          cacheTTL: 1 * 60 * 1000, // 1 minute cache
+        });
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
+    /**
+     * 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
+     */
+    async blockUser(userId: string): Promise<{ message: string }> {
+      try {
+        if (!userId) {
+          throw new Error('User ID is required');
+        }
+        const result = await this.makeRequest<{ message: string }>('POST', `/privacy/blocked/${userId}`, undefined, {
+          cache: false,
+        });
+        this.clearCacheEntry('GET:/privacy/blocked');
+        // The block changed the viewer's graph (`blockedIds`) — bust the cached
+        // consolidated `GET /users/me/graph` so the next read reflects it.
+        this.clearCacheEntry('GET:/users/me/graph');
+        return result;
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
+    /**
+     * 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
+     */
+    async unblockUser(userId: string): Promise<{ message: string }> {
+      try {
+        if (!userId) {
+          throw new Error('User ID is required');
+        }
+        const result = await this.makeRequest<{ message: string }>('DELETE', `/privacy/blocked/${userId}`, undefined, {
+          cache: false,
+        });
+        this.clearCacheEntry('GET:/privacy/blocked');
+        // Symmetric to blockUser: the unblock changed the viewer's `blockedIds`,
+        // so bust the consolidated `GET /users/me/graph` cache.
+        this.clearCacheEntry('GET:/users/me/graph');
+        return result;
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
+    /**
+     * Check if a user is blocked
+     * @param userId - The user ID to check
+     * @returns True if the user is blocked, false otherwise
+     */
+    async isUserBlocked(userId: string): Promise<boolean> {
+      return this.isUserInList(
+        userId,
+        () => this.getBlockedUsers(),
+        (block) => block.blockedId
+      );
+    }
+
+    // ============================================================================
+    // RESTRICTED USERS METHODS
+    // ============================================================================
+
+    /**
+     * Get list of restricted users
+     * @returns Array of restricted users
+     */
+    async getRestrictedUsers(): Promise<RestrictedUser[]> {
+      try {
+        return await this.makeRequest<RestrictedUser[]>('GET', '/privacy/restricted', undefined, {
+          cache: true,
+          cacheTTL: 1 * 60 * 1000, // 1 minute cache
+        });
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
+    /**
+     * 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
+     */
+    async restrictUser(userId: string): Promise<{ message: string }> {
+      try {
+        if (!userId) {
+          throw new Error('User ID is required');
+        }
+        const result = await this.makeRequest<{ message: string }>('POST', `/privacy/restricted/${userId}`, undefined, {
+          cache: false,
+        });
+        this.clearCacheEntry('GET:/privacy/restricted');
+        // The restriction changed the viewer's graph (`restrictedIds`) — bust the
+        // cached consolidated `GET /users/me/graph` so the next read reflects it.
+        this.clearCacheEntry('GET:/users/me/graph');
+        return result;
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
+    /**
+     * 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
+     */
+    async unrestrictUser(userId: string): Promise<{ message: string }> {
+      try {
+        if (!userId) {
+          throw new Error('User ID is required');
+        }
+        const result = await this.makeRequest<{ message: string }>('DELETE', `/privacy/restricted/${userId}`, undefined, {
+          cache: false,
+        });
+        this.clearCacheEntry('GET:/privacy/restricted');
+        // Symmetric to restrictUser: the unrestrict changed the viewer's
+        // `restrictedIds`, so bust the consolidated `GET /users/me/graph` cache.
+        this.clearCacheEntry('GET:/users/me/graph');
+        return result;
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
+    /**
+     * Check if a user is restricted
+     * @param userId - The user ID to check
+     * @returns True if the user is restricted, false otherwise
+     */
+    async isUserRestricted(userId: string): Promise<boolean> {
+      return this.isUserInList(
+        userId,
+        () => this.getRestrictedUsers(),
+        (restrict) => restrict.restrictedId
+      );
+    }
+  };
+}
+

package/src/mixins/OxyServices.reputation.ts

@@ -0,0 +1,436 @@
+/**
+ * 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 { isFullReputationBalance } from '@oxy.so/contracts';
+import type { OxyServicesBase } from '../OxyServices.base';
+import { OxyAuthenticationError } from '../OxyServices.errors';
+import { CACHE_TIMES } from './mixinHelpers';
+
+/** Cache-key prefix for every cached `GET /reputation/...` response. */
+const REPUTATION_CACHE_PREFIX = 'GET:/reputation/';
+
+export function OxyServicesReputationMixin<T extends typeof OxyServicesBase>(Base: T) {
+  return class extends Base {
+    constructor(...args: any[]) {
+      super(...(args as [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.
+     */
+    async getReputationBalance(userId: string): Promise<ReputationBalanceView> {
+      try {
+        return await this.makeRequest<ReputationBalanceView>(
+          'GET',
+          `/reputation/${encodeURIComponent(userId)}/balance`,
+          undefined,
+          { cache: true, cacheTTL: CACHE_TIMES.MEDIUM },
+        );
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
+    /**
+     * 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.
+     */
+    async getMyReputationBalance(): Promise<ReputationBalance> {
+      const userId = this.getCurrentUserId();
+      if (!userId) {
+        throw new OxyAuthenticationError(
+          'Reading your own reputation balance requires a signed-in user',
+        );
+      }
+
+      let balance: ReputationBalanceView;
+      try {
+        balance = await this.makeRequest<ReputationBalanceView>(
+          'GET',
+          `/reputation/${encodeURIComponent(userId)}/balance`,
+          undefined,
+          { cache: true, cacheTTL: CACHE_TIMES.MEDIUM },
+        );
+      } catch (error) {
+        throw this.handleError(error);
+      }
+
+      if (!isFullReputationBalance(balance)) {
+        throw new OxyAuthenticationError(
+          'The reputation balance came back as the public view — the request was not authenticated as its subject',
+        );
+      }
+      return balance;
+    }
+
+    /**
+     * Get the reputation leaderboard, ordered by lifetime total descending.
+     * @param limit - Page size (server-capped).
+     * @param offset - Page offset.
+     */
+    async getReputationLeaderboard(
+      limit?: number,
+      offset?: number,
+    ): Promise<ReputationLeaderboardEntry[]> {
+      try {
+        const params: { limit?: number; offset?: number } = {};
+        if (limit !== undefined) params.limit = limit;
+        if (offset !== undefined) params.offset = offset;
+        const res = await this.makeRequest<{ data?: ReputationLeaderboardEntry[] }>(
+          'GET',
+          '/reputation/leaderboard',
+          Object.keys(params).length > 0 ? params : undefined,
+          { cache: true, cacheTTL: CACHE_TIMES.LONG },
+        );
+        return res.data ?? [];
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
+    /**
+     * List the enabled reputation rules (for client display).
+     */
+    async getReputationRules(): Promise<ReputationRule[]> {
+      try {
+        const res = await this.makeRequest<{ rules?: ReputationRule[] }>(
+          'GET',
+          '/reputation/rules',
+          undefined,
+          { cache: true, cacheTTL: CACHE_TIMES.EXTRA_LONG },
+        );
+        return res.rules ?? [];
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
+    /**
+     * 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.
+     */
+    async getReputationTransactions(
+      userId: string,
+      limit?: number,
+      offset?: number,
+    ): Promise<ReputationTransaction[]> {
+      try {
+        const params: { limit?: number; offset?: number } = {};
+        if (limit !== undefined) params.limit = limit;
+        if (offset !== undefined) params.offset = offset;
+        const res = await this.makeRequest<{ data?: ReputationTransaction[] }>(
+          'GET',
+          `/reputation/${encodeURIComponent(userId)}/transactions`,
+          Object.keys(params).length > 0 ? params : undefined,
+          { cache: true, cacheTTL: CACHE_TIMES.SHORT },
+        );
+        return res.data ?? [];
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
+    /**
+     * 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`).
+     */
+    async getReputationInfluence(
+      userId: string,
+      context?: ReputationInfluenceContext,
+    ): Promise<ReputationInfluenceResult> {
+      try {
+        return await this.makeRequest<ReputationInfluenceResult>(
+          'GET',
+          `/reputation/${encodeURIComponent(userId)}/influence`,
+          context ? { context } : undefined,
+          { cache: true, cacheTTL: CACHE_TIMES.MEDIUM },
+        );
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
+    /**
+     * 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.).
+     */
+    async awardReputation(input: AwardReputationInput): Promise<ReputationTransaction> {
+      try {
+        const res = await this.makeRequest<{ transaction: ReputationTransaction }>(
+          'POST',
+          '/reputation/award',
+          input,
+          { cache: false },
+        );
+        this.clearCacheByPrefix(REPUTATION_CACHE_PREFIX);
+        return res.transaction;
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
+    /**
+     * 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.
+     */
+    async createReputationDispute(
+      input: CreateReputationDisputeInput,
+    ): Promise<ReputationDispute> {
+      try {
+        const res = await this.makeRequest<{ dispute: ReputationDispute }>(
+          'POST',
+          '/reputation/disputes',
+          input,
+          { cache: false },
+        );
+        this.clearCacheByPrefix(REPUTATION_CACHE_PREFIX);
+        return res.dispute;
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
+    /**
+     * 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.
+     */
+    async getUserReputationDisputes(
+      userId: string,
+      limit?: number,
+      offset?: number,
+    ): Promise<ReputationDispute[]> {
+      try {
+        const params: { limit?: number; offset?: number } = {};
+        if (limit !== undefined) params.limit = limit;
+        if (offset !== undefined) params.offset = offset;
+        const res = await this.makeRequest<{ data?: ReputationDispute[] }>(
+          'GET',
+          `/reputation/${encodeURIComponent(userId)}/disputes`,
+          Object.keys(params).length > 0 ? params : undefined,
+          { cache: true, cacheTTL: CACHE_TIMES.SHORT },
+        );
+        return res.data ?? [];
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
+    // =========================================================================
+    // STAFF / ADMIN METHODS (require staff privileges server-side)
+    // =========================================================================
+
+    /**
+     * Create or update a reputation rule, keyed by `actionType` (staff only).
+     * Invalidates the cached rule list.
+     * @param input - The rule definition.
+     */
+    async upsertReputationRule(input: UpsertReputationRuleInput): Promise<ReputationRule> {
+      try {
+        const res = await this.makeRequest<{ rule: ReputationRule }>(
+          'POST',
+          '/reputation/rules',
+          input,
+          { cache: false },
+        );
+        this.clearCacheByPrefix(REPUTATION_CACHE_PREFIX);
+        return res.rule;
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
+    /**
+     * 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.
+     */
+    async reverseReputationTransaction(
+      transactionId: string,
+      input?: ReverseReputationTransactionInput,
+    ): Promise<ReverseReputationTransactionResult> {
+      try {
+        const res = await this.makeRequest<ReverseReputationTransactionResult>(
+          'POST',
+          `/reputation/transactions/${encodeURIComponent(transactionId)}/reverse`,
+          input ?? {},
+          { cache: false },
+        );
+        this.clearCacheByPrefix(REPUTATION_CACHE_PREFIX);
+        return res;
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
+    /**
+     * 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.
+     */
+    async voidReputationTransaction(
+      transactionId: string,
+      input?: ReverseReputationTransactionInput,
+    ): Promise<ReputationTransaction> {
+      try {
+        const res = await this.makeRequest<{ transaction: ReputationTransaction }>(
+          'POST',
+          `/reputation/transactions/${encodeURIComponent(transactionId)}/void`,
+          input ?? {},
+          { cache: false },
+        );
+        this.clearCacheByPrefix(REPUTATION_CACHE_PREFIX);
+        return res.transaction;
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
+    /**
+     * 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.
+     */
+    async recalculateReputation(userId: string): Promise<ReputationBalance> {
+      try {
+        const res = await this.makeRequest<ReputationBalance>(
+          'POST',
+          `/reputation/${encodeURIComponent(userId)}/recalculate`,
+          undefined,
+          { cache: false },
+        );
+        this.clearCacheByPrefix(REPUTATION_CACHE_PREFIX);
+        return res;
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
+    /**
+     * Get the open dispute queue across all users (staff only).
+     * @param limit - Page size (server-capped).
+     * @param offset - Page offset.
+     */
+    async getReputationDisputeQueue(
+      limit?: number,
+      offset?: number,
+    ): Promise<ReputationDispute[]> {
+      try {
+        const params: { limit?: number; offset?: number } = {};
+        if (limit !== undefined) params.limit = limit;
+        if (offset !== undefined) params.offset = offset;
+        const res = await this.makeRequest<{ data?: ReputationDispute[] }>(
+          'GET',
+          '/reputation/disputes',
+          Object.keys(params).length > 0 ? params : undefined,
+          { cache: true, cacheTTL: CACHE_TIMES.SHORT },
+        );
+        return res.data ?? [];
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
+    /**
+     * 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`).
+     */
+    async resolveReputationDispute(
+      disputeId: string,
+      input: ResolveReputationDisputeInput,
+    ): Promise<ReputationDispute> {
+      try {
+        const res = await this.makeRequest<{ dispute: ReputationDispute }>(
+          'POST',
+          `/reputation/disputes/${encodeURIComponent(disputeId)}/resolve`,
+          input,
+          { cache: false },
+        );
+        this.clearCacheByPrefix(REPUTATION_CACHE_PREFIX);
+        return res.dispute;
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+  };
+}