@oxy.so/core 1.0.0

package/dist/esm/mixins/OxyServices.privacy.js

@@ -0,0 +1,196 @@
+import { logger } from '../logger/index.js';
+export function OxyServicesPrivacyMixin(Base) {
+    return class extends Base {
+        constructor(...args) {
+            super(...args);
+        }
+        /**
+         * Extract user ID from blocked/restricted user object
+         */
+        extractUserId(userIdField) {
+            return typeof userIdField === 'string' ? userIdField : userIdField._id;
+        }
+        /**
+         * Check if a user is in a list (blocked or restricted)
+         */
+        async isUserInList(userId, getUserList, getIdField) {
+            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() {
+            try {
+                return await this.makeRequest('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) {
+            try {
+                if (!userId) {
+                    throw new Error('User ID is required');
+                }
+                const result = await this.makeRequest('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) {
+            try {
+                if (!userId) {
+                    throw new Error('User ID is required');
+                }
+                const result = await this.makeRequest('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) {
+            return this.isUserInList(userId, () => this.getBlockedUsers(), (block) => block.blockedId);
+        }
+        // ============================================================================
+        // RESTRICTED USERS METHODS
+        // ============================================================================
+        /**
+         * Get list of restricted users
+         * @returns Array of restricted users
+         */
+        async getRestrictedUsers() {
+            try {
+                return await this.makeRequest('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) {
+            try {
+                if (!userId) {
+                    throw new Error('User ID is required');
+                }
+                const result = await this.makeRequest('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) {
+            try {
+                if (!userId) {
+                    throw new Error('User ID is required');
+                }
+                const result = await this.makeRequest('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) {
+            return this.isUserInList(userId, () => this.getRestrictedUsers(), (restrict) => restrict.restrictedId);
+        }
+    };
+}

package/dist/esm/mixins/OxyServices.reputation.js

@@ -0,0 +1,286 @@
+import { isFullReputationBalance } from '@oxy.so/contracts';
+import { OxyAuthenticationError } from '../OxyServices.errors.js';
+import { CACHE_TIMES } from './mixinHelpers.js';
+/** Cache-key prefix for every cached `GET /reputation/...` response. */
+const REPUTATION_CACHE_PREFIX = 'GET:/reputation/';
+export function OxyServicesReputationMixin(Base) {
+    return class extends Base {
+        constructor(...args) {
+            super(...args);
+        }
+        /**
+         * 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) {
+            try {
+                return await this.makeRequest('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() {
+            const userId = this.getCurrentUserId();
+            if (!userId) {
+                throw new OxyAuthenticationError('Reading your own reputation balance requires a signed-in user');
+            }
+            let balance;
+            try {
+                balance = await this.makeRequest('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, offset) {
+            try {
+                const params = {};
+                if (limit !== undefined)
+                    params.limit = limit;
+                if (offset !== undefined)
+                    params.offset = offset;
+                const res = await this.makeRequest('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() {
+            try {
+                const res = await this.makeRequest('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, limit, offset) {
+            try {
+                const params = {};
+                if (limit !== undefined)
+                    params.limit = limit;
+                if (offset !== undefined)
+                    params.offset = offset;
+                const res = await this.makeRequest('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, context) {
+            try {
+                return await this.makeRequest('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) {
+            try {
+                const res = await this.makeRequest('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) {
+            try {
+                const res = await this.makeRequest('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, limit, offset) {
+            try {
+                const params = {};
+                if (limit !== undefined)
+                    params.limit = limit;
+                if (offset !== undefined)
+                    params.offset = offset;
+                const res = await this.makeRequest('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) {
+            try {
+                const res = await this.makeRequest('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, input) {
+            try {
+                const res = await this.makeRequest('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, input) {
+            try {
+                const res = await this.makeRequest('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) {
+            try {
+                const res = await this.makeRequest('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, offset) {
+            try {
+                const params = {};
+                if (limit !== undefined)
+                    params.limit = limit;
+                if (offset !== undefined)
+                    params.offset = offset;
+                const res = await this.makeRequest('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, input) {
+            try {
+                const res = await this.makeRequest('POST', `/reputation/disputes/${encodeURIComponent(disputeId)}/resolve`, input, { cache: false });
+                this.clearCacheByPrefix(REPUTATION_CACHE_PREFIX);
+                return res.dispute;
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+    };
+}

package/dist/esm/mixins/OxyServices.security.js

@@ -0,0 +1,86 @@
+import { logger } from '../logger/index.js';
+export function OxyServicesSecurityMixin(Base) {
+    return class extends Base {
+        constructor(...args) {
+            super(...args);
+        }
+        /**
+         * 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
+         */
+        async getSecurityActivity(limit, offset, eventType) {
+            try {
+                const params = {};
+                if (limit !== undefined)
+                    params.limit = limit;
+                if (offset !== undefined)
+                    params.offset = offset;
+                if (eventType)
+                    params.eventType = eventType;
+                // The API responds with the standard paginated envelope:
+                //   { data: SecurityActivity[], pagination: { total, limit, offset, hasMore } }
+                // SecurityActivityResponse is the flattened shape consumers expect.
+                const raw = await this.makeRequest('GET', '/security/activity', params, { cache: false });
+                const requestedLimit = typeof params.limit === 'number' ? params.limit : 0;
+                const requestedOffset = typeof params.offset === 'number' ? params.offset : 0;
+                return {
+                    data: raw.data ?? [],
+                    total: raw.pagination?.total ?? raw.data?.length ?? 0,
+                    limit: raw.pagination?.limit ?? requestedLimit,
+                    offset: raw.pagination?.offset ?? requestedOffset,
+                    hasMore: raw.pagination?.hasMore ?? false,
+                };
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+        /**
+         * Get recent security activity (convenience method)
+         * @param limit - Number of recent events to fetch (default: 10)
+         * @returns Array of recent security activities
+         */
+        async getRecentSecurityActivity(limit = 10) {
+            try {
+                const response = await this.getSecurityActivity(limit, 0);
+                return response.data || [];
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+        /**
+         * Log private key exported event
+         * @param deviceId - Optional device ID for tracking
+         * @returns Promise that resolves when event is logged
+         */
+        async logPrivateKeyExported(deviceId) {
+            try {
+                await this.makeRequest('POST', '/security/activity/private-key-exported', { deviceId }, { cache: false });
+            }
+            catch (error) {
+                // Don't throw - logging failures shouldn't break user flow, but surface
+                // for monitoring via the shared logger sink.
+                logger.warn('[OxyServices] Failed to log private key exported event', { component: 'OxyServices.security' }, error);
+            }
+        }
+        /**
+         * Log backup created event
+         * @param deviceId - Optional device ID for tracking
+         * @returns Promise that resolves when event is logged
+         */
+        async logBackupCreated(deviceId) {
+            try {
+                await this.makeRequest('POST', '/security/activity/backup-created', { deviceId }, { cache: false });
+            }
+            catch (error) {
+                // Don't throw - logging failures shouldn't break user flow, but surface
+                // for monitoring via the shared logger sink.
+                logger.warn('[OxyServices] Failed to log backup created event', { component: 'OxyServices.security' }, error);
+            }
+        }
+    };
+}