@oxy.so/core 1.18.1 → 3.0.0

package/dist/cjs/api/devices.js

@@ -0,0 +1,351 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DevicesApi = exports.AccountNotOnDeviceError = void 0;
+/**
+ * `oxy.devices` — this user's devices, the sessions on them, their security
+ * activity, and device sign-in.
+ *
+ * Device sign-in is the client half of the zero-cookie device transport:
+ * {@link DevicesApi.mintToken} turns a first-party `deviceId` + `deviceSecret`
+ * into a fresh access token (the cold boot and the re-mint handler call it);
+ * {@link DevicesApi.registerBrowser}, {@link DevicesApi.requestJoinCode} and
+ * {@link DevicesApi.joinBrowser} are the browser bridge (ADR 0029 D2); and
+ * {@link DevicesApi.provisionBackgroundCredential} hands native background code
+ * its own non-rotating credential. The mint carries NO persistence or
+ * token-planting side effects: the cold boot / re-mint handler own those.
+ */
+const contracts_1 = require("@oxy.so/contracts");
+const logger_1 = require("../logger");
+const errorUtils_1 = require("../utils/errorUtils");
+/**
+ * The server's `401 account_not_on_device` for a PINNED mint: the requested
+ * `accountId` is not (or is no longer) a live account of this device session.
+ *
+ * Distinguished from every other mint 401 because the remedy is different: the
+ * device secret is FINE — it is the identity binding that went stale (the
+ * account was signed out on this device, or revoked). An identity-bound caller
+ * must re-establish its session from the local key rather than drop/clear the
+ * device credential.
+ */
+class AccountNotOnDeviceError extends Error {
+    constructor(accountId, cause) {
+        super(`account_not_on_device: ${accountId} is not a live account of this device session`);
+        this.accountId = accountId;
+        this.cause = cause;
+        this.name = 'AccountNotOnDeviceError';
+        /** HTTP status of the originating response; mirrors the ApiError shape. */
+        this.status = 401;
+    }
+}
+exports.AccountNotOnDeviceError = AccountNotOnDeviceError;
+/**
+ * Structural (never `instanceof`) read of a normalized mint error: the thrown
+ * value may be a plain ApiError-shaped object or come from another realm.
+ */
+function isAccountNotOnDevice(error) {
+    if (!error || typeof error !== 'object') {
+        return false;
+    }
+    const { status, message } = error;
+    if (status !== 401) {
+        return false;
+    }
+    return typeof message === 'string' && message.includes('account_not_on_device');
+}
+/**
+ * The bridge calls share their transport rules with the mint: no bearer
+ * (`skipAuth`, so a 401 surfaces directly), one attempt, and never parked
+ * behind the request queue.
+ */
+async function bridgeRequest(ctx, url, body, schema) {
+    const res = await ctx.request('POST', url, body, {
+        cache: false,
+        skipAuth: true,
+        retry: false,
+        bypassQueue: true,
+    });
+    const parsed = (0, contracts_1.safeParseContract)(schema, res);
+    if (!parsed) {
+        throw new Error(`${url.slice(1)} returned an unexpected response shape`);
+    }
+    return parsed;
+}
+class DevicesApi {
+    constructor(ctx) {
+        this.ctx = ctx;
+    }
+    /**
+     * Get all devices for the current user
+     * @returns Array of user devices
+     */
+    async list() {
+        return this.ctx.request('GET', '/devices', undefined, {
+            cache: false, // Don't cache device list - always get fresh data
+        });
+    }
+    /**
+     * Remove a device
+     * @param deviceId - The device ID to remove
+     */
+    async remove(deviceId) {
+        await this.ctx.request('DELETE', `/devices/${deviceId}`, undefined, { cache: false });
+    }
+    /**
+     * Get device sessions for a given session ID
+     * Note: Not cached by default to ensure fresh data
+     * @param sessionId - The session ID
+     * @returns Array of device sessions
+     */
+    async sessions(sessionId) {
+        // Cache disabled by default to ensure fresh session data
+        return this.ctx.request('GET', `/session/device/sessions/${sessionId}`, undefined, {
+            cache: false, // Don't cache sessions - always get fresh data
+            deduplicate: true, // Deduplicate concurrent requests for same sessionId
+        });
+    }
+    /**
+     * Logout all device sessions
+     * @param sessionId - The session ID
+     * @param deviceId - Optional device ID to target
+     * @param excludeCurrent - Whether to exclude the current session
+     * @returns Logout result
+     */
+    async logoutAll(sessionId, deviceId, excludeCurrent) {
+        const urlParams = {};
+        if (deviceId)
+            urlParams.deviceId = deviceId;
+        if (excludeCurrent)
+            urlParams.excludeCurrent = 'true';
+        return this.ctx.request('POST', `/session/device/logout-all/${sessionId}`, urlParams, { cache: false });
+    }
+    /**
+     * Update device name
+     * @param sessionId - The session ID
+     * @param deviceName - New device name
+     * @returns Updated device object
+     */
+    async rename(sessionId, deviceName) {
+        return this.ctx.request('PUT', `/session/device/name/${sessionId}`, { deviceName }, { cache: false });
+    }
+    /**
+     * Get security information
+     * @returns Security information object
+     */
+    async securityInfo() {
+        return this.ctx.request('GET', '/devices/security', undefined, {
+            cache: false,
+        });
+    }
+    /**
+     * 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 securityActivity(limit, offset, eventType) {
+        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.ctx.request('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,
+        };
+    }
+    /**
+     * 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.ctx.request('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_1.logger.warn('[OxyServices] Failed to log private key exported event', { component: 'oxy.devices' }, 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.ctx.request('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_1.logger.warn('[OxyServices] Failed to log backup created event', { component: 'oxy.devices' }, error);
+        }
+    }
+    /**
+     * Zero-cookie mint. Present the first-party `deviceId` + `deviceSecret` to
+     * `POST /session/device/token` — NO bearer, NO cookies: possession of the
+     * secret IS the device-ownership proof. Returns a fresh short access token
+     * for the device's active account plus `nextDeviceSecret` (on mint, the same
+     * proven secret echoed back — rotation happens on sign-in, not mint) and
+     * the projected device-session `state`.
+     *
+     * `skipAuth`: this call carries no bearer, so a 401 must surface DIRECTLY —
+     * never trigger `HttpService`'s 401→refresh→retry dance. The cold boot / re-
+     * mint handler read the 401 body (`invalid_device_secret` vs
+     * `no_active_session`) to decide whether to drop the secret and fall back or
+     * resolve signed-out.
+     *
+     * `retry: false`: the mint is a single logical attempt. The proactive
+     * token-refresh scheduler and the reactive 401 lane already own backoff and
+     * re-arm, so `HttpService`'s inner retry loop here would only multiply the
+     * mint's latency on a slow/black-hole network (3 retries × 5s timeout ≈ 20s
+     * per lane) with no correctness benefit — it is the dominant term in the cold
+     * boot's worst-case time-to-route. A transient failure surfaces once and the
+     * scheduler/401 path retries it later.
+     *
+     * `options.accountId` PINS the mint to one account of the device instead of
+     * whichever account is currently active. It exists for identity-bound
+     * clients (Commons), whose authenticated user is fixed by a local
+     * cryptographic key and must never follow an account switch made by another
+     * app on the same device. The server never mutates `activeAccountId` for a
+     * pinned mint — the returned `state` still reports the device's true active
+     * account — and rejects a non-member/dead account with
+     * `401 account_not_on_device`, surfaced here as {@link AccountNotOnDeviceError}.
+     *
+     * @throws {AccountNotOnDeviceError} when a pinned mint's account is not on the device.
+     * @throws if the response does not match {@link deviceTokenMintResponseSchema}.
+     */
+    async mintToken(deviceId, deviceSecret, options) {
+        const accountId = options?.accountId;
+        try {
+            const res = await this.ctx.request('POST', '/session/device/token', { deviceId, deviceSecret, ...(accountId ? { accountId } : {}) }, 
+            // `bypassQueue`: this mint is the control-plane call the auth lane
+            // depends on — it must run even when every RequestQueue slot is parked
+            // awaiting it, or the whole client deadlocks. See RequestOptions.bypassQueue.
+            { cache: false, skipAuth: true, retry: false, bypassQueue: true });
+            const parsed = (0, contracts_1.safeParseContract)(contracts_1.deviceTokenMintResponseSchema, res);
+            if (!parsed) {
+                throw new Error('session/device/token returned an unexpected response shape');
+            }
+            return parsed;
+        }
+        catch (error) {
+            if (accountId && isAccountNotOnDevice(error)) {
+                throw new AccountNotOnDeviceError(accountId, error);
+            }
+            throw error;
+        }
+    }
+    /**
+     * `POST /session/device/register` — auth.oxy.so only. A new, empty browser
+     * device with a server-chosen id and auth.oxy.so's holder credential. No
+     * bearer: this runs before anyone is signed in.
+     *
+     * @throws if the response does not match {@link deviceRegisterResponseSchema}.
+     */
+    async registerBrowser() {
+        return bridgeRequest(this.ctx, '/session/device/register', {}, contracts_1.deviceRegisterResponseSchema);
+    }
+    /**
+     * `POST /session/device/join-code` — auth.oxy.so only (the bridge page).
+     * Proves the device with its holder secret and returns a one-use, ~60 s
+     * code for an OFFICIAL app, bound to its exact registered redirect URI and
+     * its PKCE S256 challenge. A rejected secret surfaces as a 401 whose message
+     * carries `invalid_device_secret`.
+     */
+    async requestJoinCode(request) {
+        return bridgeRequest(this.ctx, '/session/device/join-code', request, contracts_1.deviceJoinCodeResponseSchema);
+    }
+    /**
+     * `POST /session/device/join` — the app's own origin. Redeems the bridge's
+     * code with the PKCE verifier this app holds, and returns this app's own
+     * holder credential for the browser's device. Persist it, then mint through
+     * {@link DevicesApi.mintToken} like any other holder.
+     */
+    async joinBrowser(request) {
+        return bridgeRequest(this.ctx, '/session/device/join', request, contracts_1.deviceJoinResponseSchema);
+    }
+    /**
+     * Provision a NON-rotating background credential for the caller's account on
+     * this device — the credential native background code (an Android widget
+     * worker, which runs with no JS runtime) presents to mint its own access
+     * tokens without any JS involvement.
+     *
+     * It exists precisely so background code never touches the device secret:
+     * `POST /session/device/token` ROTATES that secret on every mint (the
+     * presented one stays valid only for a short grace), so a worker minting
+     * from it would become a second writer of the value JS depends on and could
+     * silently sign the user out. The background credential is a separate,
+     * non-rotating value minted server-side, so the two lanes never contend.
+     *
+     * Bearer required and NO body: the server derives both the `deviceId` and
+     * the account from the validated bearer. This is the only way a background
+     * credential comes into existence, so background code can EXTEND a session
+     * the user established in-app but can never bootstrap one from nothing.
+     *
+     * Unlike the mint above this is NOT a control-plane call — it runs while a
+     * session is already live — so it takes the normal authenticated path: no
+     * `skipAuth` (a 401 should go through the ordinary re-mint lane) and no
+     * `bypassQueue` (nothing in the auth lane is parked awaiting it).
+     *
+     * There is deliberately no JS counterpart that MINTS from the returned
+     * credential: the native side owns that call, and a symmetric-looking JS
+     * method would be dead code plus a second implementation of the failure
+     * rules. The asymmetry is the design.
+     *
+     * **Call this from NATIVE only.** There is no background worker on web to
+     * consume the credential, and handing a browser origin a long-lived
+     * non-rotating secret to persist is strictly weaker than the rotating device
+     * secret it already holds. The 404 degrade below is also native-shaped: a
+     * browser attaches `Origin`, which a server predating this route answers
+     * `403 BAD_ORIGIN` from its router-wide same-site guard rather than 404, so
+     * the quiet degrade would not fire there. A native client sends no `Origin`
+     * and gets the 404. Gate the caller by platform; do not widen the degrade to
+     * 403, which would also swallow a genuine origin misconfiguration.
+     *
+     * That paragraph is LOAD-BEARING, not belt-and-braces: the route sits above
+     * oxy-api's router-wide origin guard (deliberately, so a native client with
+     * no `Origin` is not rejected). oxy-api additionally refuses callers that
+     * carry browser context signals (`Origin` or `Sec-Fetch-Site`) with
+     * `403 browser_not_allowed` — native HTTP clients send neither. Gate the
+     * caller by platform on the client as well; do not widen the 404 degrade to
+     * 403, which would also swallow a genuine origin misconfiguration.
+     *
+     * @returns the provisioned credential, or `null` when the endpoint is absent
+     * (404). The API deploy leads the SDK release, so a client on a newer SDK
+     * than the server degrades to "no background session" quietly instead of
+     * surfacing an error.
+     * @throws if the response does not match {@link deviceBackgroundCredentialResponseSchema}.
+     */
+    async provisionBackgroundCredential() {
+        try {
+            const res = await this.ctx.request('POST', '/session/device/background-credential', undefined, { cache: false });
+            const parsed = (0, contracts_1.safeParseContract)(contracts_1.deviceBackgroundCredentialResponseSchema, res);
+            if (!parsed) {
+                throw new Error('session/device/background-credential returned an unexpected response shape');
+            }
+            return parsed;
+        }
+        catch (error) {
+            if ((0, errorUtils_1.extractErrorStatus)(error) === 404) {
+                return null;
+            }
+            throw error;
+        }
+    }
+}
+exports.DevicesApi = DevicesApi;

package/dist/cjs/api/follows.js

@@ -0,0 +1,240 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FollowsApi = void 0;
+const apiUtils_1 = require("../utils/apiUtils");
+const GRAPH_TTL = 2 * 60 * 1000;
+const STATUS_TTL = 60 * 1000;
+/**
+ * Maximum number of ids sent per `POST /users/follow-status/bulk` request.
+ * Matches the server-side `MAX_BULK_FOLLOW` cap.
+ */
+const FOLLOW_STATUS_CHUNK_SIZE = 200;
+class FollowsApi {
+    constructor(ctx) {
+        this.ctx = ctx;
+    }
+    // ── People ───────────────────────────────────────────────────────────────
+    /** Follow a user. */
+    async follow(userId) {
+        const result = await this.ctx.request('POST', `/users/${userId}/follow`, undefined, { cache: false });
+        this.invalidate([userId]);
+        return result;
+    }
+    /** Follow many users in one request (the server caps it at 200). */
+    async followMany(userIds) {
+        if (userIds.length === 0)
+            return { results: [], followedCount: 0 };
+        const result = await this.ctx.request('POST', '/users/follow/bulk', { userIds }, { cache: false });
+        this.invalidate(userIds);
+        return result;
+    }
+    /** Unfollow a user. */
+    async unfollow(userId) {
+        const result = await this.ctx.request('DELETE', `/users/${userId}/follow`, undefined, { cache: false });
+        this.invalidate([userId]);
+        return result;
+    }
+    /** Unfollow many users in one request (the server caps it at 200). */
+    async unfollowMany(userIds) {
+        if (userIds.length === 0)
+            return { results: [], unfollowedCount: 0 };
+        const result = await this.ctx.request('POST', '/users/unfollow/bulk', { userIds }, { cache: false });
+        this.invalidate(userIds);
+        return result;
+    }
+    /** Whether the signed-in user follows `userId`. Cached 1 minute, busted by every write. */
+    async status(userId) {
+        return this.ctx.request('GET', `/users/${userId}/follow-status`, undefined, { cache: true, cacheTTL: STATUS_TTL });
+    }
+    /**
+     * Follow status for MANY users, one round-trip per chunk of 200 — for list
+     * UIs that would otherwise fire one `status` per button. Every requested id
+     * is in the result (`false` when not followed). Not cached: the UI store
+     * owns follow-status freshness.
+     */
+    async statuses(userIds) {
+        const uniqueIds = Array.from(new Set(userIds.filter((id) => typeof id === 'string' && id.trim().length > 0)));
+        if (uniqueIds.length === 0)
+            return {};
+        const chunks = [];
+        for (let i = 0; i < uniqueIds.length; i += FOLLOW_STATUS_CHUNK_SIZE) {
+            chunks.push(uniqueIds.slice(i, i + FOLLOW_STATUS_CHUNK_SIZE));
+        }
+        const responses = await Promise.all(chunks.map((chunk) => this.ctx.request('POST', '/users/follow-status/bulk', { userIds: chunk }, { cache: false })));
+        const merged = {};
+        for (const response of responses)
+            Object.assign(merged, response?.statuses ?? {});
+        return merged;
+    }
+    /**
+     * A user's followers. `sort` is `recent` (default) or `oldest`; each
+     * `limit`/`offset`/`sort` combination is its own cache entry (2 minutes).
+     */
+    async followers(userId, params) {
+        const { data, total, hasMore } = await this.userPage(`/users/${userId}/followers`, params);
+        return { followers: data, total, hasMore };
+    }
+    /** Who a user follows. `sort` as in `followers`. */
+    async following(userId, params) {
+        const { data, total, hasMore } = await this.userPage(`/users/${userId}/following`, params);
+        return { following: data, total, hasMore };
+    }
+    /**
+     * "Followers you know": users the signed-in viewer follows who also follow
+     * `userId`.
+     */
+    async mutuals(userId, params) {
+        const { data, total, hasMore } = await this.userPage(`/users/${userId}/mutuals`, params);
+        return { mutuals: data, total, hasMore };
+    }
+    /**
+     * The signed-in viewer's OWN mutuals, as ids — to seed a "Mutuals" feed.
+     * Signed out: `[]`. Cached 2 minutes.
+     */
+    async mutualIds(params) {
+        const response = await this.ctx.request('GET', '/users/mutual-ids', (0, apiUtils_1.buildPaginationParams)(params ?? {}), {
+            cache: true,
+            cacheTTL: GRAPH_TTL,
+        });
+        return response.data || [];
+    }
+    /**
+     * The signed-in viewer's follows-of-follows (two hops, minus their own
+     * follows and themselves), as ids ordered by frequency then recency — to seed
+     * a friends-of-friends feed. Signed out: `[]`. Cached 2 minutes.
+     */
+    async followsOfFollowsIds(params) {
+        const response = await this.ctx.request('GET', '/users/follows-of-follows-ids', (0, apiUtils_1.buildPaginationParams)(params ?? {}), { cache: true, cacheTTL: GRAPH_TTL });
+        return response.data || [];
+    }
+    /**
+     * The signed-in viewer's graph in one request (see {@link ViewerGraph}).
+     * Cached 2 minutes; follow, block and restrict writes bust it.
+     */
+    async viewerGraph() {
+        const response = await this.ctx.request('GET', '/users/me/graph', undefined, {
+            cache: true,
+            cacheTTL: GRAPH_TTL,
+        });
+        const graph = response.data;
+        return {
+            followingIds: graph?.followingIds || [],
+            mutualIds: graph?.mutualIds || [],
+            blockedIds: graph?.blockedIds || [],
+            restrictedIds: graph?.restrictedIds || [],
+        };
+    }
+    // ── Targets (`/v2/follows`) ──────────────────────────────────────────────
+    /**
+     * Follow a registered target (by id, not URI — see `ensureTarget`).
+     * Idempotent: an existing follow returns `created: false`. The follower and
+     * the acting application are both derived server-side; `expiresIn` (seconds)
+     * lets a follow lapse on its own.
+     */
+    async followTarget(targetId, options) {
+        return this.ctx.request('PUT', `/v2/follows/${encodeURIComponent(targetId)}`, options?.expiresIn !== undefined ? { expiresIn: options.expiresIn } : {}, { cache: false });
+    }
+    /**
+     * Unfollow everywhere. ("Unfollow here" is `setApplicationMode(…,
+     * 'disabled')`.) Idempotent: `removed: false` when already gone.
+     */
+    async unfollowTarget(relationshipId) {
+        return this.ctx.request('DELETE', `/v2/follows/${encodeURIComponent(relationshipId)}`, undefined, {
+            cache: false,
+        });
+    }
+    /**
+     * The three-part status — globally, in this application, in effect. Render
+     * `effectiveState`; keep the other two for the explanation.
+     */
+    async targetStatus(targetId) {
+        return this.ctx.request('GET', `/v2/follows/${encodeURIComponent(targetId)}/status`, undefined, {
+            cache: false,
+        });
+    }
+    /**
+     * Turn a relationship off, or back on, in ONE application — the calling one
+     * unless `applicationId` names another (which needs `follows:manage`).
+     */
+    async setApplicationMode(relationshipId, mode, applicationId) {
+        return this.ctx.request('PUT', `/v2/follows/${encodeURIComponent(relationshipId)}/context`, { mode, ...(applicationId ? { applicationId } : {}) }, { cache: false });
+    }
+    /**
+     * Drop the override so the application follows the global relationship
+     * again (a later global change then takes effect here; an explicit
+     * `enabled` would not).
+     */
+    async restoreInheritance(relationshipId, applicationId) {
+        const path = (0, apiUtils_1.buildUrl)(`/v2/follows/${encodeURIComponent(relationshipId)}/context`, applicationId ? { applicationId } : {});
+        return this.ctx.request('DELETE', path, undefined, { cache: false });
+    }
+    /**
+     * Resolve a target by canonical URI, registering it the first time. Idempotent
+     * on the URI, so two applications describing the same thing reach ONE row.
+     * `metadata` is a display snapshot refreshed only by the providing app.
+     */
+    async ensureTarget(input) {
+        return this.ctx.request('POST', '/v2/follow-targets', input, { cache: false });
+    }
+    /** Claim a namespace for the calling application (first come; idempotent for the holder). */
+    async claimNamespace(namespace) {
+        return this.ctx.request('POST', '/v2/follow-targets/namespaces', { namespace }, { cache: false });
+    }
+    /**
+     * Release a namespace the calling application holds, while nothing is
+     * registered in it. Idempotent (`released: false` when already unowned).
+     */
+    async releaseNamespace(namespace) {
+        return this.ctx.request('DELETE', `/v2/follow-targets/namespaces/${encodeURIComponent(namespace)}`, undefined, {
+            cache: false,
+        });
+    }
+    /**
+     * Declare what following a kind of thing MEANS — the verb, whether reverse
+     * lookups are public, whether it federates. Once, by the owning application.
+     */
+    async registerKind(input) {
+        return this.ctx.request('POST', '/v2/follow-targets/kinds', input, { cache: false });
+    }
+    /**
+     * Everything the signed-in user follows, newest first. Paginate with
+     * `nextCursor`, never an offset: the list changes while it is read.
+     */
+    async list(params) {
+        const path = (0, apiUtils_1.buildUrl)('/v2/me/follows', {
+            ...(params?.kind ? { kind: params.kind } : {}),
+            ...(params?.cursor ? { cursor: params.cursor } : {}),
+            ...(params?.limit ? { limit: params.limit } : {}),
+        });
+        return this.ctx.request('GET', path, undefined, { cache: false });
+    }
+    // ── Internals ────────────────────────────────────────────────────────────
+    async userPage(path, params) {
+        const response = await this.ctx.request('GET', path, (0, apiUtils_1.buildQueryParams)(params ?? {}), { cache: true, cacheTTL: GRAPH_TTL });
+        return { data: response.data || [], total: response.pagination.total, hasMore: response.pagination.hasMore };
+    }
+    /**
+     * Every cached read a follow write makes stale, in ONE pass over the cache.
+     *
+     * Lists go by PREFIX: they are paginated and sorted, so one logical list is
+     * spread over many content-addressed keys, and an exact-key clear would bust
+     * only the page read last.
+     */
+    invalidate(targetUserIds) {
+        const keys = ['GET:/users/me/graph'];
+        const prefixes = ['GET:/profiles/username/', 'GET:/profiles/resolve'];
+        for (const id of targetUserIds) {
+            keys.push(`GET:/users/${id}/follow-status`);
+            // Profiles embed the viewer-relative `relationship`.
+            keys.push(`GET:/users/${id}`);
+            // The target gained or lost a follower, and "followers you know" with it.
+            prefixes.push(`GET:/users/${id}/followers`, `GET:/users/${id}/mutuals`);
+        }
+        // The viewer's own following list changed.
+        const viewerId = this.ctx.oxy.session.userId;
+        if (viewerId)
+            prefixes.push(`GET:/users/${viewerId}/following`);
+        this.ctx.http.invalidateCache({ keys, prefixes });
+    }
+}
+exports.FollowsApi = FollowsApi;