@oxy.so/core 1.18.1 → 3.0.0

package/src/api/linkedAccounts.ts

@@ -0,0 +1,78 @@
+/**
+ * `oxy.linkedAccounts` — external accounts (any Mastodon-API server, Bluesky)
+ * the current user has PROVEN they own by completing an OAuth authorization
+ * there. Oxy uses that authorization only to learn which account granted it and
+ * then discards the token — nothing here ever carries a third-party token.
+ *
+ * The flow is a top-level browser navigation: `start` returns the other
+ * network's `authorizeUrl`; open it (a new tab, or `expo-web-browser`'s auth
+ * session on native); the network sends the browser to Oxy's callback, and Oxy
+ * sends it to `returnTo` with `?link_code=<code>` or `?link_error=<code>`. Pass
+ * the code to `complete` with the same user signed in: that call, not the
+ * callback, creates the link, so an authorization someone else started can
+ * never link to them. `returnTo` must be a redirect URI registered on the
+ * first-party application `clientId` names.
+ *
+ * Wire types live in `@oxy.so/contracts` (`linkedAccounts.ts`).
+ */
+import type {
+  CompleteLinkedAccountResponse,
+  LinkedAccount,
+  LinkedAccountListResponse,
+  LinkedAccountNetwork,
+  StartLinkedAccountRequest,
+  StartLinkedAccountResponse,
+} from '@oxy.so/contracts';
+import type { OxyContext } from '../client/context';
+
+export class LinkedAccountsApi {
+  constructor(protected readonly ctx: OxyContext) {}
+
+  /**
+   * Begin linking an external account for the current user.
+   *
+   * @param network - `'activitypub'` (any Mastodon-API server) or `'atproto'` (Bluesky).
+   * @param options - `instance` for ActivityPub (`mastodon.social`, or
+   *   `@user@mastodon.social`), `handle` for atproto; `clientId` + `returnTo`
+   *   to be sent back to your app afterwards.
+   * @returns The URL to open, and when the attempt expires (ten minutes).
+   */
+  async start(network: LinkedAccountNetwork, options: StartLinkedAccountRequest): Promise<StartLinkedAccountResponse> {
+    return this.ctx.request<StartLinkedAccountResponse>(
+      'POST',
+      `/linked-accounts/${encodeURIComponent(network)}/start`,
+      options,
+      { cache: false },
+    );
+  }
+
+  /**
+   * Finish a link with the `link_code` the callback appended to `returnTo`.
+   * Must be the user who started the flow: for anyone else the API answers 403
+   * and burns the code. 409 when the account is already someone else's link.
+   * Repeating it within the code's five minutes returns the same link.
+   */
+  async complete(code: string): Promise<LinkedAccount> {
+    const res = await this.ctx.request<CompleteLinkedAccountResponse>('POST', '/linked-accounts/complete', { code }, {
+      cache: false,
+    });
+    return res.linkedAccount;
+  }
+
+  /** The current user's live linked accounts, oldest first. */
+  async list(): Promise<LinkedAccount[]> {
+    const res = await this.ctx.request<LinkedAccountListResponse>('GET', '/linked-accounts', undefined, { cache: false });
+    return res.linkedAccounts;
+  }
+
+  /**
+   * Unlink one of the current user's accounts. An ActivityPub link stops being
+   * published as an `alsoKnownAs` alias, and the external account can then be
+   * linked to another Oxy account.
+   */
+  async revoke(linkedAccountId: string): Promise<void> {
+    await this.ctx.request<void>('DELETE', `/linked-accounts/${encodeURIComponent(linkedAccountId)}`, undefined, {
+      cache: false,
+    });
+  }
+}

package/src/api/nodes.ts

@@ -0,0 +1,169 @@
+/**
+ * `oxy.nodes` — the signed-in user's personal data NODE: the decentralised store
+ * that holds an authentic copy of their signed-record chain.
+ *
+ *  - `register` registers (or re-registers) a SELF-HOSTED node. It is a signed
+ *    `type:'node'` v2 record (`collection: 'app.oxy.node'`, `rkey: 'self'`,
+ *    last-writer-wins) published through `POST /identity/records`; the server
+ *    verifies it and materializes the node status as a side effect, so the
+ *    registration's authority is the user's own signature. NATIVE-ONLY.
+ *  - `mine` reads the cached node status plus the liveness badge Oxy maintains.
+ *  - `removeMine` revokes the registration.
+ *  - `provisionManagedVault` asks Oxy to operate a MANAGED vault (`managed:true,
+ *    controller:'oxy'`) — the "Create your vault" convenience.
+ *  - `notifyIngest` sends an unauthenticated HINT that a node has new records;
+ *    the server fully re-verifies before ingesting, so it can never inject data.
+ *
+ * The wire shapes are API-internal (not yet a published contract), so
+ * {@link UserNodeStatus} mirrors the server's `serializeNode` projection.
+ */
+import type { OxyContext } from '../client/context';
+import { signOwnChainRecord } from './identity';
+
+/** Short-TTL read cache (the liveness badge is background-maintained). */
+const SHORT_TTL = 60 * 1000;
+
+/** A user has exactly one node: one `self` record in the node collection. */
+const NODE_COLLECTION = 'app.oxy.node';
+const NODE_RKEY = 'self';
+
+/**
+ * A node mutation changes every node read and `/users/me` (the derived DID
+ * document embeds an `#oxy-node` service entry from the node row).
+ */
+const NODE_SWEEP_PREFIXES = ['GET:/nodes/', 'GET:/users/me'] as const;
+
+/** How Oxy and the node move records: the node pulls (default), or Oxy pushes. */
+export type UserNodeMode = 'pull' | 'push';
+
+/** Who operates the node: the user (`self`) or Oxy on their behalf (`oxy`). */
+export type UserNodeController = 'self' | 'oxy';
+
+/**
+ * Liveness badge, maintained ONLY by Oxy's background probes: `active` (the
+ * last probe reached the manifest), `unreachable` (it failed; the cached row is
+ * still served), `revoked` (the user removed the registration).
+ */
+export type UserNodeLivenessStatus = 'active' | 'unreachable' | 'revoked';
+
+/** The caller's registered node, as projected by the server. Dates are ISO strings. */
+export interface UserNodeStatus {
+  /** Optional DID the node advertises for itself (informational). */
+  nodeDid?: string;
+  /** The node's public HTTPS base URL (where its liveness manifest lives). */
+  endpoint: string;
+  /** The node's secp256k1 public key (hex) — records it signs verify against this. */
+  nodePublicKey: string;
+  /** Transport direction. `pull` by default. */
+  mode: UserNodeMode;
+  /** Whether Oxy operates this node on the user's behalf (managed vault). */
+  managed: boolean;
+  /** Operator of the node. */
+  controller: UserNodeController;
+  /** Liveness badge — maintained only by background probes. */
+  status: UserNodeLivenessStatus;
+  /** Last time a probe reached the node successfully. */
+  lastSeenAt?: string;
+  /** Last time a probe ran, success or failure. */
+  lastProbeAt?: string;
+  /** Why the last probe OR ingest failed (cleared on success). */
+  lastError?: string;
+  /** Last synced chain `seq` (advanced only by the ingest worker). */
+  cursor?: number;
+  /** Last time the ingest worker pulled this node. */
+  lastSyncedAt?: string;
+  createdAt: string;
+  updatedAt: string;
+}
+
+/** Input for {@link NodesApi.register}. */
+export interface RegisterNodeInput {
+  /** The node's public HTTPS base URL. */
+  endpoint: string;
+  /** The node's secp256k1 public key (hex). */
+  nodePublicKey: string;
+  /** Transport direction; `'pull'` when omitted. */
+  mode?: UserNodeMode;
+}
+
+/** Result of {@link NodesApi.removeMine}. */
+export interface RemoveNodeResult {
+  /** `true` when an active registration was flipped to `revoked`. */
+  revoked: boolean;
+}
+
+export class NodesApi {
+  constructor(private readonly ctx: OxyContext) {}
+
+  /**
+   * Register (or re-register) the signed-in user's SELF-HOSTED node: sign the
+   * `{ endpoint, nodePublicKey, mode }` record on the caller's own chain and
+   * publish it. NATIVE-ONLY; throws before any network call when signed out.
+   * Returns the freshly materialized status.
+   *
+   * Throws if the record stored but the server skipped materialization (e.g. a
+   * malformed endpoint it rejected) rather than returning a silent `null`.
+   */
+  async register(input: RegisterNodeInput): Promise<UserNodeStatus> {
+    if (!this.ctx.oxy.session.userId) {
+      throw new Error('No authenticated user — sign in before registering a node.');
+    }
+    const envelope = await signOwnChainRecord(
+      this.ctx,
+      'node',
+      { endpoint: input.endpoint, nodePublicKey: input.nodePublicKey, mode: input.mode ?? 'pull' },
+      { collection: NODE_COLLECTION, rkey: NODE_RKEY },
+    );
+    await this.ctx.request('POST', '/identity/records', envelope, { cache: false });
+    this.sweep();
+
+    const node = await this.mine();
+    if (!node) {
+      throw new Error('Node registration stored but the node could not be materialized.');
+    }
+    return node;
+  }
+
+  /** The signed-in user's node status, or `null` when they have none. Short-TTL cached. */
+  async mine(): Promise<UserNodeStatus | null> {
+    const res = await this.ctx.request<{ node: UserNodeStatus | null }>('GET', '/nodes/me', undefined, {
+      cache: true,
+      cacheTTL: SHORT_TTL,
+    });
+    return res.node ?? null;
+  }
+
+  /** Revoke the signed-in user's node registration. */
+  async removeMine(): Promise<RemoveNodeResult> {
+    const res = await this.ctx.request<{ success: boolean }>('DELETE', '/nodes/me', undefined, { cache: false });
+    this.sweep();
+    return { revoked: res.success === true };
+  }
+
+  /**
+   * Provision (or refresh) an Oxy-operated MANAGED vault for the signed-in
+   * user. Idempotent server-side; the owner comes from the session.
+   */
+  async provisionManagedVault(): Promise<UserNodeStatus> {
+    const res = await this.ctx.request<{ node: UserNodeStatus }>('POST', '/nodes/managed', undefined, { cache: false });
+    this.sweep();
+    return res.node;
+  }
+
+  /**
+   * Hint that `userId`'s node has new records. Unauthenticated by design and
+   * fire-and-forget on the server (a 202); resolves once accepted.
+   */
+  async notifyIngest(userId: string): Promise<void> {
+    await this.ctx.request<{ accepted: boolean }>(
+      'POST',
+      `/nodes/ingest/notify/${encodeURIComponent(userId)}`,
+      undefined,
+      { cache: false },
+    );
+  }
+
+  private sweep(): void {
+    this.ctx.http.invalidateCache({ prefixes: NODE_SWEEP_PREFIXES });
+  }
+}

package/src/api/notifications.ts

@@ -0,0 +1,135 @@
+/**
+ * `oxy.notifications` — the signed-in user's in-app inbox, and this
+ * installation's push token.
+ *
+ * ## Push tokens are EXPO push tokens
+ *
+ * `registerPushToken` takes the token `Notifications.getExpoPushTokenAsync()`
+ * returns — the `ExponentPushToken[…]` handle — because the server delivers
+ * through Expo's push service, which only accepts that form. A raw APNs/FCM
+ * token from `getDevicePushTokenAsync()` registers "successfully" and then
+ * every push silently fails at delivery, so it is rejected here, before any
+ * request. Acquiring the token (permission prompt, `expo-notifications`) is the
+ * app's job — `@oxy.so/core` never imports an `expo-*` module.
+ *
+ * Creating a notification is a service-token call: `OxyServer`'s
+ * `notifications.create` (`@oxy.so/core/server`).
+ */
+import type { OxyContext } from '../client/context';
+import type { Notification, NotificationPage } from '../models/interfaces';
+import { buildQueryParams } from '../utils/apiUtils';
+
+/** Platform a push token was minted on; the server rejects any other value. */
+export type PushTokenPlatform = 'ios' | 'android' | 'web';
+
+/**
+ * `ExponentPushToken[…]` (what `getExpoPushTokenAsync()` returns) or the
+ * equivalent `ExpoPushToken[…]`. Plain ASCII: core ships to Hermes, where
+ * Unicode property escapes throw at runtime.
+ */
+const EXPO_PUSH_TOKEN_PATTERN = /^Expo(nent)?PushToken\[[^[\]\s]+\]$/;
+
+/** Input for {@link NotificationsApi.registerPushToken}. */
+export interface RegisterPushTokenInput {
+  /**
+   * The **Expo push token** for this installation (`ExponentPushToken[…]`).
+   * NOT the raw APNs/FCM token from `getDevicePushTokenAsync()`.
+   */
+  expoPushToken: string;
+  platform: PushTokenPlatform;
+  /**
+   * The device-first `deviceId` this installation is registered under, so the
+   * server can retire the token when that device session goes away.
+   */
+  deviceId?: string;
+  /**
+   * The registered OAuth client id (`oxy_dk_…`) of WHICH application this
+   * installation is — what lets a "Sign in with Oxy" request reach a known
+   * Commons installation instead of every token the identity owns.
+   */
+  clientId?: string;
+}
+
+export class NotificationsApi {
+  constructor(protected readonly ctx: OxyContext) {}
+
+  // ── Inbox ────────────────────────────────────────────────────────────────
+
+  /** One page of the inbox, newest first, with the unread count across all pages. */
+  async list(params: { page?: number; limit?: number } = {}): Promise<NotificationPage> {
+    return this.ctx.request<NotificationPage>('GET', '/notifications', buildQueryParams({ page: params.page, limit: params.limit }), {
+      cache: false,
+    });
+  }
+
+  /** How many notifications are unread. */
+  async unreadCount(): Promise<number> {
+    const res = await this.ctx.request<{ unreadCount: number }>('GET', '/notifications/unread-count', undefined, { cache: false });
+    return res.unreadCount;
+  }
+
+  /**
+   * Mark one notification read and return it as stored. Scoped to the recipient
+   * server-side, so it is also the authoritative read by id: a foreign or
+   * unknown id 404s.
+   */
+  async markRead(notificationId: string): Promise<Notification> {
+    const res = await this.ctx.request<{ notification: Notification }>(
+      'PUT',
+      `/notifications/${encodeURIComponent(notificationId)}/read`,
+      undefined,
+      { cache: false },
+    );
+    return res.notification;
+  }
+
+  /** Mark every notification read. */
+  async markAllRead(): Promise<void> {
+    await this.ctx.request('PUT', '/notifications/read-all', undefined, { cache: false });
+  }
+
+  /** Delete one notification. */
+  async delete(notificationId: string): Promise<void> {
+    await this.ctx.request('DELETE', `/notifications/${encodeURIComponent(notificationId)}`, undefined, { cache: false });
+  }
+
+  // ── Push tokens ──────────────────────────────────────────────────────────
+
+  /**
+   * Register this installation's Expo push token for the signed-in identity
+   * (`POST /notifications/push-token`). Idempotent server-side, so it is safe to
+   * call on every cold boot.
+   *
+   * @throws When `expoPushToken` is not an Expo push token.
+   */
+  async registerPushToken(input: RegisterPushTokenInput): Promise<void> {
+    if (!EXPO_PUSH_TOKEN_PATTERN.test(input.expoPushToken)) {
+      throw new Error(
+        'registerPushToken expects an Expo push token ("ExponentPushToken[...]", from getExpoPushTokenAsync). ' +
+          'A raw APNs/FCM device token from getDevicePushTokenAsync cannot be delivered to.',
+      );
+    }
+    await this.ctx.request(
+      'POST',
+      '/notifications/push-token',
+      {
+        token: input.expoPushToken,
+        platform: input.platform,
+        // Omitted when absent: the server reads presence.
+        ...(input.deviceId ? { deviceId: input.deviceId } : {}),
+        ...(input.clientId ? { clientId: input.clientId } : {}),
+      },
+      { cache: false },
+    );
+  }
+
+  /**
+   * Retire a push token (`DELETE /notifications/push-token`). Call it when the
+   * user turns notifications off, when the identity is replaced, and on
+   * sign-out — or the installation keeps receiving requests for an identity it
+   * no longer holds.
+   */
+  async unregisterPushToken(expoPushToken: string): Promise<void> {
+    await this.ctx.request('DELETE', '/notifications/push-token', { token: expoPushToken }, { cache: false });
+  }
+}

package/src/api/privacy.ts

@@ -0,0 +1,120 @@
+/**
+ * `oxy.privacy` — privacy settings, blocked and restricted users.
+ */
+import type { BlockedUser, PrivacySettings, RestrictedUser } from '../models/interfaces';
+import type { OxyContext } from '../client/context';
+import { evictOxyIdentityCache } from '../utils/identityCacheSweep';
+
+const LIST_TTL = 60 * 1000;
+const SETTINGS_TTL = 2 * 60 * 1000;
+
+type UserRef = string | { _id: string };
+
+const refId = (ref: UserRef): string => (typeof ref === 'string' ? ref : ref._id);
+
+export class PrivacyApi {
+  constructor(private readonly ctx: OxyContext) {}
+
+  // ── Settings ─────────────────────────────────────────────────────────────
+
+  /** A user's privacy settings (default: the signed-in user's). */
+  async settings(userId?: string): Promise<PrivacySettings> {
+    const id = await this.resolveUserId(userId);
+    return this.ctx.request<PrivacySettings>('GET', `/privacy/${id}/privacy`, undefined, {
+      cache: true,
+      cacheTTL: SETTINGS_TTL,
+    });
+  }
+
+  /** Update privacy settings (default: the signed-in user's). */
+  async updateSettings(settings: Partial<PrivacySettings>, userId?: string): Promise<PrivacySettings> {
+    const id = await this.resolveUserId(userId);
+    const res = await this.ctx.request<PrivacySettings>('PATCH', `/privacy/${id}/privacy`, settings, { cache: false });
+    // Privacy settings ride the user DTO, so every identity read goes stale too.
+    evictOxyIdentityCache(this.ctx.http, id);
+    this.ctx.oxy.cache.delete(`GET:/privacy/${id}/privacy`);
+    return res;
+  }
+
+  // ── Blocked ──────────────────────────────────────────────────────────────
+
+  /** The signed-in user's blocked users. */
+  async blocked(): Promise<BlockedUser[]> {
+    return this.ctx.request<BlockedUser[]>('GET', '/privacy/blocked', undefined, { cache: true, cacheTTL: LIST_TTL });
+  }
+
+  /** Block a user. */
+  async block(userId: string): Promise<{ message: string }> {
+    requireId(userId);
+    const res = await this.ctx.request<{ message: string }>('POST', `/privacy/blocked/${userId}`, undefined, { cache: false });
+    this.invalidate('GET:/privacy/blocked');
+    return res;
+  }
+
+  /** Unblock a user. */
+  async unblock(userId: string): Promise<{ message: string }> {
+    requireId(userId);
+    const res = await this.ctx.request<{ message: string }>('DELETE', `/privacy/blocked/${userId}`, undefined, { cache: false });
+    this.invalidate('GET:/privacy/blocked');
+    return res;
+  }
+
+  /** Whether the signed-in user blocked `userId`. `false` when the list cannot be read. */
+  async isBlocked(userId: string): Promise<boolean> {
+    if (!userId) return false;
+    try {
+      return (await this.blocked()).some((b) => refId(b.blockedId) === userId);
+    } catch {
+      return false;
+    }
+  }
+
+  // ── Restricted ───────────────────────────────────────────────────────────
+
+  /** The signed-in user's restricted users. */
+  async restricted(): Promise<RestrictedUser[]> {
+    return this.ctx.request<RestrictedUser[]>('GET', '/privacy/restricted', undefined, { cache: true, cacheTTL: LIST_TTL });
+  }
+
+  /** Restrict a user: limit their interactions without blocking them. */
+  async restrict(userId: string): Promise<{ message: string }> {
+    requireId(userId);
+    const res = await this.ctx.request<{ message: string }>('POST', `/privacy/restricted/${userId}`, undefined, { cache: false });
+    this.invalidate('GET:/privacy/restricted');
+    return res;
+  }
+
+  /** Lift a restriction. */
+  async unrestrict(userId: string): Promise<{ message: string }> {
+    requireId(userId);
+    const res = await this.ctx.request<{ message: string }>('DELETE', `/privacy/restricted/${userId}`, undefined, { cache: false });
+    this.invalidate('GET:/privacy/restricted');
+    return res;
+  }
+
+  /** Whether the signed-in user restricted `userId`. `false` when the list cannot be read. */
+  async isRestricted(userId: string): Promise<boolean> {
+    if (!userId) return false;
+    try {
+      return (await this.restricted()).some((r) => refId(r.restrictedId) === userId);
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * A block or restriction changes the list AND the viewer's consolidated graph
+   * (`blockedIds` / `restrictedIds` in `GET /users/me/graph`); both go.
+   */
+  private invalidate(listKey: string): void {
+    this.ctx.http.invalidateCache({ keys: [listKey, 'GET:/users/me/graph'] });
+  }
+
+  private async resolveUserId(userId?: string): Promise<string> {
+    return userId || this.ctx.oxy.session.userId || (await this.ctx.oxy.users.me()).id;
+  }
+}
+
+function requireId(userId: string): void {
+  if (!userId) throw new Error('User ID is required');
+}

package/src/api/reputation.ts

@@ -0,0 +1,134 @@
+/**
+ * `oxy.reputation` — Oxy Trust reputation, read-only.
+ *
+ * People only READ reputation here. Points come from the applications that
+ * observed an action (`OxyServer.reputation.award`, service token), under rules
+ * fixed in code. Nobody — staff included — edits a person's standing by hand.
+ *
+ * Every type is owned by `@oxy.so/contracts`; import them from there.
+ */
+import type {
+  ReputationBalance,
+  ReputationBalanceView,
+  ReputationInfluenceContext,
+  ReputationInfluenceResult,
+  ReputationLeaderboardEntry,
+  ReputationRule,
+  ReputationTransaction,
+} from '@oxy.so/contracts';
+import { isFullReputationBalance } from '@oxy.so/contracts';
+import type { OxyContext } from '../client/context';
+import { OxyAuthenticationError } from '../OxyServices.errors';
+
+const SHORT = 60 * 1000;
+const MEDIUM = 2 * 60 * 1000;
+const LONG = 5 * 60 * 1000;
+const EXTRA_LONG = 30 * 60 * 1000;
+
+/** Cache-key prefix of every cached `GET /reputation/...` response. */
+export const REPUTATION_CACHE_PREFIX = 'GET:/reputation/';
+
+export interface ReputationPage {
+  limit?: number;
+  offset?: number;
+}
+
+export class ReputationApi {
+  constructor(protected readonly ctx: OxyContext) {}
+
+  /**
+   * The SIGNED-IN user's balance, in full (`breakdown`, `influence`,
+   * `reliability`). Throws when not signed in, or when the server answered with
+   * the public view (the request was not authenticated as the subject).
+   */
+  balance(): Promise<ReputationBalance>;
+  /**
+   * ANY user's balance, in whichever view the server serves the caller: a third
+   * party gets only `userId`, `total` and `trustTier`. Narrow with
+   * `isFullReputationBalance` before reading the private blocks.
+   * @param userId - The subject's `_id` or publicKey.
+   */
+  balance(userId: string): Promise<ReputationBalanceView>;
+  async balance(userId?: string): Promise<ReputationBalanceView> {
+    const mine = !userId;
+    const id = userId || this.ctx.oxy.session.userId;
+    if (!id) {
+      throw new OxyAuthenticationError('Reading your own reputation balance requires a signed-in user');
+    }
+    const balance = await this.ctx.request<ReputationBalanceView>(
+      'GET',
+      `/reputation/${encodeURIComponent(id)}/balance`,
+      undefined,
+      { cache: true, cacheTTL: MEDIUM },
+    );
+    if (mine && !isFullReputationBalance(balance)) {
+      throw new OxyAuthenticationError(
+        'The reputation balance came back as the public view — the request was not authenticated as its subject',
+      );
+    }
+    return balance;
+  }
+
+  /** The leaderboard, by lifetime total, descending. */
+  async leaderboard(page: ReputationPage = {}): Promise<ReputationLeaderboardEntry[]> {
+    const res = await this.ctx.request<{ data?: ReputationLeaderboardEntry[] }>(
+      'GET',
+      '/reputation/leaderboard',
+      pageParams(page),
+      { cache: true, cacheTTL: LONG },
+    );
+    return res.data ?? [];
+  }
+
+  /** The enabled rules: what earns and what costs reputation. */
+  async rules(): Promise<ReputationRule[]> {
+    const res = await this.ctx.request<{ rules?: ReputationRule[] }>('GET', '/reputation/rules', undefined, {
+      cache: true,
+      cacheTTL: EXTRA_LONG,
+    });
+    return res.rules ?? [];
+  }
+
+  /**
+   * A user's ledger, newest first (default: the signed-in user's). Auth required.
+   * @param userId - The subject's `_id` or publicKey.
+   */
+  async transactions(userId?: string, page: ReputationPage = {}): Promise<ReputationTransaction[]> {
+    const id = this.resolveUserId(userId);
+    const res = await this.ctx.request<{ data?: ReputationTransaction[] }>(
+      'GET',
+      `/reputation/${encodeURIComponent(id)}/transactions`,
+      pageParams(page),
+      { cache: true, cacheTTL: SHORT },
+    );
+    return res.data ?? [];
+  }
+
+  /**
+   * A user's capped influence weight for one context (default: the signed-in
+   * user's). Auth required.
+   * @param context - The weight axis (server default: `default`).
+   */
+  async influence(userId?: string, context?: ReputationInfluenceContext): Promise<ReputationInfluenceResult> {
+    const id = this.resolveUserId(userId);
+    return this.ctx.request<ReputationInfluenceResult>(
+      'GET',
+      `/reputation/${encodeURIComponent(id)}/influence`,
+      context ? { context } : undefined,
+      { cache: true, cacheTTL: MEDIUM },
+    );
+  }
+
+  protected resolveUserId(userId?: string): string {
+    const id = userId || this.ctx.oxy.session.userId;
+    if (!id) throw new OxyAuthenticationError('A user id is required (none given and not signed in)');
+    return id;
+  }
+}
+
+function pageParams(page: ReputationPage): Record<string, number> | undefined {
+  const params: Record<string, number> = {};
+  if (page.limit !== undefined) params.limit = page.limit;
+  if (page.offset !== undefined) params.offset = page.offset;
+  return Object.keys(params).length > 0 ? params : undefined;
+}