@oxy.so/core 1.18.0 → 3.0.0

package/dist/esm/api/notifications.js

@@ -0,0 +1,71 @@
+import { buildQueryParams } from '../utils/apiUtils.js';
+/**
+ * `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]+\]$/;
+export class NotificationsApi {
+    constructor(ctx) {
+        this.ctx = ctx;
+    }
+    // ── Inbox ────────────────────────────────────────────────────────────────
+    /** One page of the inbox, newest first, with the unread count across all pages. */
+    async list(params = {}) {
+        return this.ctx.request('GET', '/notifications', buildQueryParams({ page: params.page, limit: params.limit }), {
+            cache: false,
+        });
+    }
+    /** How many notifications are unread. */
+    async unreadCount() {
+        const res = await this.ctx.request('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) {
+        const res = await this.ctx.request('PUT', `/notifications/${encodeURIComponent(notificationId)}/read`, undefined, { cache: false });
+        return res.notification;
+    }
+    /** Mark every notification read. */
+    async markAllRead() {
+        await this.ctx.request('PUT', '/notifications/read-all', undefined, { cache: false });
+    }
+    /** Delete one notification. */
+    async delete(notificationId) {
+        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) {
+        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) {
+        await this.ctx.request('DELETE', '/notifications/push-token', { token: expoPushToken }, { cache: false });
+    }
+}

package/dist/esm/api/privacy.js

@@ -0,0 +1,101 @@
+import { evictOxyIdentityCache } from '../utils/identityCacheSweep.js';
+const LIST_TTL = 60 * 1000;
+const SETTINGS_TTL = 2 * 60 * 1000;
+const refId = (ref) => (typeof ref === 'string' ? ref : ref._id);
+export class PrivacyApi {
+    constructor(ctx) {
+        this.ctx = ctx;
+    }
+    // ── Settings ─────────────────────────────────────────────────────────────
+    /** A user's privacy settings (default: the signed-in user's). */
+    async settings(userId) {
+        const id = await this.resolveUserId(userId);
+        return this.ctx.request('GET', `/privacy/${id}/privacy`, undefined, {
+            cache: true,
+            cacheTTL: SETTINGS_TTL,
+        });
+    }
+    /** Update privacy settings (default: the signed-in user's). */
+    async updateSettings(settings, userId) {
+        const id = await this.resolveUserId(userId);
+        const res = await this.ctx.request('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() {
+        return this.ctx.request('GET', '/privacy/blocked', undefined, { cache: true, cacheTTL: LIST_TTL });
+    }
+    /** Block a user. */
+    async block(userId) {
+        requireId(userId);
+        const res = await this.ctx.request('POST', `/privacy/blocked/${userId}`, undefined, { cache: false });
+        this.invalidate('GET:/privacy/blocked');
+        return res;
+    }
+    /** Unblock a user. */
+    async unblock(userId) {
+        requireId(userId);
+        const res = await this.ctx.request('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) {
+        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() {
+        return this.ctx.request('GET', '/privacy/restricted', undefined, { cache: true, cacheTTL: LIST_TTL });
+    }
+    /** Restrict a user: limit their interactions without blocking them. */
+    async restrict(userId) {
+        requireId(userId);
+        const res = await this.ctx.request('POST', `/privacy/restricted/${userId}`, undefined, { cache: false });
+        this.invalidate('GET:/privacy/restricted');
+        return res;
+    }
+    /** Lift a restriction. */
+    async unrestrict(userId) {
+        requireId(userId);
+        const res = await this.ctx.request('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) {
+        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.
+     */
+    invalidate(listKey) {
+        this.ctx.http.invalidateCache({ keys: [listKey, 'GET:/users/me/graph'] });
+    }
+    async resolveUserId(userId) {
+        return userId || this.ctx.oxy.session.userId || (await this.ctx.oxy.users.me()).id;
+    }
+}
+function requireId(userId) {
+    if (!userId)
+        throw new Error('User ID is required');
+}

package/dist/esm/api/reputation.js

@@ -0,0 +1,70 @@
+import { isFullReputationBalance } from '@oxy.so/contracts';
+import { OxyAuthenticationError } from '../OxyServices.errors.js';
+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 class ReputationApi {
+    constructor(ctx) {
+        this.ctx = ctx;
+    }
+    async balance(userId) {
+        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('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 = {}) {
+        const res = await this.ctx.request('GET', '/reputation/leaderboard', pageParams(page), { cache: true, cacheTTL: LONG });
+        return res.data ?? [];
+    }
+    /** The enabled rules: what earns and what costs reputation. */
+    async rules() {
+        const res = await this.ctx.request('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, page = {}) {
+        const id = this.resolveUserId(userId);
+        const res = await this.ctx.request('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, context) {
+        const id = this.resolveUserId(userId);
+        return this.ctx.request('GET', `/reputation/${encodeURIComponent(id)}/influence`, context ? { context } : undefined, { cache: true, cacheTTL: MEDIUM });
+    }
+    resolveUserId(userId) {
+        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) {
+    const params = {};
+    if (page.limit !== undefined)
+        params.limit = page.limit;
+    if (page.offset !== undefined)
+        params.offset = page.offset;
+    return Object.keys(params).length > 0 ? params : undefined;
+}

package/dist/esm/api/session.js

@@ -0,0 +1,173 @@
+/**
+ * `oxy.session` — this client's auth state and its server session.
+ *
+ * The local half is synchronous state: the access token, the user id it
+ * carries, change notifications. The remote half is the server session that
+ * token belongs to: validating it, listing the sessions beside it, signing out.
+ */
+import { jwtDecode } from 'jwt-decode';
+import { normalizeUserIdentity } from '../utils/userIdentity.js';
+export class SessionApi {
+    constructor(ctx) {
+        this.ctx = ctx;
+        this.deviceCredentialProvider = null;
+        this.decodedFor = null;
+        this.decoded = null;
+    }
+    // ── Local state ──────────────────────────────────────────────────────────
+    /** The current access token, or `null` when signed out. */
+    get accessToken() {
+        return this.ctx.http.getAccessToken();
+    }
+    /** Whether an access token is held. Does not ask the server; see `validateToken`. */
+    get isAuthenticated() {
+        return this.ctx.http.hasAccessToken();
+    }
+    /** The signed-in user's id, from the access token; `null` when signed out. */
+    get userId() {
+        const claims = this.claims();
+        return claims?.userId || claims?.id || null;
+    }
+    /**
+     * The access token's `exp` in SECONDS since the epoch (the raw JWT unit), or
+     * `null` when there is no token or it carries no numeric `exp`. Powers the
+     * proactive refresh timer in `@oxy.so/services`.
+     */
+    get accessTokenExpiry() {
+        const exp = this.claims()?.exp;
+        return typeof exp === 'number' ? exp : null;
+    }
+    /** Plant an access token (e.g. one a sign-in returned). */
+    setAccessToken(accessToken) {
+        this.ctx.http.setTokens(accessToken);
+    }
+    /**
+     * Forget the token and end the local session: a re-mint already in flight
+     * plants nothing, and none runs until a token is set again.
+     */
+    clear() {
+        this.ctx.http.endSession();
+    }
+    /**
+     * Subscribe to access-token changes — `setAccessToken`, `clear`, a silent
+     * refresh, the 401-driven clear. The listener gets the new token, or `null`.
+     * Returns the unsubscribe.
+     */
+    onChange(listener) {
+        return this.ctx.http.addTokenChangeListener(listener);
+    }
+    /**
+     * Resolve `true` as soon as a token is held, or `false` after `timeoutMs`.
+     * Event-driven: no polling.
+     */
+    waitForAuth(timeoutMs = 5000) {
+        if (this.isAuthenticated)
+            return Promise.resolve(true);
+        return new Promise((resolve) => {
+            const timer = setTimeout(() => {
+                unsubscribe();
+                resolve(false);
+            }, timeoutMs);
+            const unsubscribe = this.onChange((token) => {
+                if (!token)
+                    return;
+                clearTimeout(timer);
+                unsubscribe();
+                resolve(true);
+            });
+        });
+    }
+    /**
+     * Tell this client how to read the device credential it holds, so a sign-in
+     * can PROVE the device (ADR 0029 D2): every sign-in in `oxy.auth` then sends
+     * it as `device`, and the server puts the new session on that device — the
+     * browser's shared one, which every Oxy app holding it sees at once.
+     *
+     * `OxyProvider` wires this from its auth store; nothing else needs to.
+     * Returns a disposer that clears it (only if still installed).
+     */
+    setDeviceCredentialProvider(provider) {
+        this.deviceCredentialProvider = provider;
+        return () => {
+            if (this.deviceCredentialProvider === provider) {
+                this.deviceCredentialProvider = null;
+            }
+        };
+    }
+    /**
+     * The device proof a sign-in should carry, or `null`. Never throws: a store
+     * that cannot be read only means the sign-in gets its own device.
+     */
+    async readDeviceProof() {
+        const provider = this.deviceCredentialProvider;
+        if (!provider)
+            return null;
+        try {
+            const proof = await provider();
+            if (proof && typeof proof.deviceId === 'string' && proof.deviceId && typeof proof.deviceSecret === 'string' && proof.deviceSecret) {
+                return { deviceId: proof.deviceId, deviceSecret: proof.deviceSecret };
+            }
+            return null;
+        }
+        catch {
+            return null;
+        }
+    }
+    // ── The server session ───────────────────────────────────────────────────
+    /** Ask the server whether the current access token is valid. */
+    async validateToken() {
+        if (!this.isAuthenticated)
+            return false;
+        try {
+            const res = await this.ctx.request('GET', '/auth/validate', undefined, { cache: false, retry: false });
+            return res.valid === true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /** Validate a session by id and return it with its user. */
+    async validate(sessionId, options = {}) {
+        const params = {};
+        if (options.deviceFingerprint)
+            params.deviceFingerprint = options.deviceFingerprint;
+        if (options.useHeaderValidation)
+            params.useHeaderValidation = 'true';
+        try {
+            const validation = await this.ctx.request('GET', `/session/validate/${sessionId}`, params, { cache: false });
+            return { ...validation, user: normalizeUserIdentity(validation.user) };
+        }
+        catch (error) {
+            // The session is gone: drop any user cached for it (#196).
+            this.ctx.oxy.cache.delete(`GET:/session/user/${sessionId}`);
+            throw error;
+        }
+    }
+    /** The sessions that belong with `sessionId` (same account set). */
+    async list(sessionId) {
+        return this.ctx.request('GET', `/session/sessions/${sessionId}`, undefined, { cache: false });
+    }
+    /** Sign out `sessionId`, or — with `targetSessionId` — one of the sessions beside it. */
+    async logout(sessionId, targetSessionId) {
+        const url = targetSessionId ? `/session/logout/${sessionId}/${targetSessionId}` : `/session/logout/${sessionId}`;
+        await this.ctx.request('POST', url, undefined, { cache: false });
+    }
+    /** Sign out every session beside `sessionId`, and it. */
+    async logoutAll(sessionId) {
+        await this.ctx.request('POST', `/session/logout-all/${sessionId}`, undefined, { cache: false });
+    }
+    /** Decoded claims of the current token, memoised per token string. */
+    claims() {
+        const token = this.ctx.http.getAccessToken();
+        if (token !== this.decodedFor) {
+            this.decodedFor = token;
+            try {
+                this.decoded = token ? jwtDecode(token) : null;
+            }
+            catch {
+                this.decoded = null;
+            }
+        }
+        return this.decoded;
+    }
+}

package/dist/esm/api/store.js

@@ -0,0 +1,192 @@
+const SHORT_TTL = 60 * 1000;
+const MEDIUM_TTL = 2 * 60 * 1000;
+const enc = encodeURIComponent;
+/** Read one page out of that envelope. */
+function pageOf(res) {
+    return {
+        items: res.data ?? [],
+        total: res.pagination?.total ?? 0,
+        hasMore: res.pagination?.hasMore ?? false,
+    };
+}
+/**
+ * Build a query string from the options that were actually supplied.
+ *
+ * Generic over the options object rather than taking a `Record`: an interface
+ * has no implicit index signature in TypeScript, so `StoreReviewsOptions` would
+ * not be assignable to one and every call site would need a cast.
+ */
+function queryOf(params) {
+    const search = new URLSearchParams();
+    for (const [key, value] of Object.entries(params)) {
+        if (value !== undefined)
+            search.set(key, String(value));
+    }
+    const rendered = search.toString();
+    return rendered ? `?${rendered}` : '';
+}
+/** `oxy.store.reviews` — what people say about an app, and the caller's own review. */
+export class StoreReviewsApi {
+    constructor(ctx) {
+        this.ctx = ctx;
+    }
+    /** Visible reviews for a published app, each with the publisher's reply. */
+    async list(slug, options = {}) {
+        const res = await this.ctx.request('GET', `/store/apps/${enc(slug)}/reviews${queryOf(options)}`, undefined, { cache: true, cacheTTL: SHORT_TTL });
+        return pageOf(res);
+    }
+    /** The caller's own review of an app, or `null` if they have not written one. */
+    async mine(slug) {
+        const res = await this.ctx.request('GET', reviewPath(slug), undefined, {
+            cache: false,
+        });
+        return res.data ?? null;
+    }
+    /**
+     * Write the caller's review, or replace what they said before.
+     *
+     * A person has one review per app, so this sets it rather than adding one.
+     * Rewriting does not clear a moderator's decision: a hidden review stays
+     * hidden when its author edits it.
+     */
+    async write(slug, input) {
+        const res = await this.ctx.request('PUT', reviewPath(slug), input, { cache: false });
+        return res.data;
+    }
+    /** Withdraw the caller's own review. A real delete — the words were theirs. */
+    async deleteMine(slug) {
+        await this.ctx.request('DELETE', reviewPath(slug), undefined, { cache: false });
+    }
+}
+/** `oxy.store.listing.screenshots` — the pictures on a listing. */
+export class ListingScreenshotsApi {
+    constructor(ctx) {
+        this.ctx = ctx;
+    }
+    /** Every picture on the listing, in the author's order. */
+    async list(applicationId) {
+        return this.ctx.request('GET', screenshotsPath(applicationId), undefined, { cache: false });
+    }
+    /**
+     * Attach an already-uploaded image, appended to the end.
+     *
+     * Upload through `oxy.assets` first; the store keeps a reference rather than
+     * a second copy of the asset pipeline. The file must be live, an image, and
+     * one the caller is entitled to.
+     */
+    async add(applicationId, input) {
+        return this.ctx.request('POST', screenshotsPath(applicationId), input, { cache: false });
+    }
+    /** Edit a picture's caption or the frame it was taken in. Order is `reorder`. */
+    async update(applicationId, screenshotId, input) {
+        return this.ctx.request('PATCH', `${screenshotsPath(applicationId)}/${enc(screenshotId)}`, input, { cache: false });
+    }
+    /** Remove a picture. The uploaded file stays — it may be in use elsewhere. */
+    async delete(applicationId, screenshotId) {
+        await this.ctx.request('DELETE', `${screenshotsPath(applicationId)}/${enc(screenshotId)}`, undefined, {
+            cache: false,
+        });
+    }
+    /**
+     * Set the order of every picture at once.
+     *
+     * Send EVERY id on the listing, exactly once, in the order they should
+     * appear. A partial list is rejected rather than applied: it would leave the
+     * pictures it omits at their old positions, interleaved with the new ones.
+     */
+    async reorder(applicationId, screenshotIds) {
+        return this.ctx.request('PUT', `${screenshotsPath(applicationId)}/order`, { screenshotIds }, {
+            cache: false,
+        });
+    }
+}
+/** `oxy.store.listing` — the page a publisher edits for an application they own. */
+export class StoreListingApi {
+    constructor(ctx) {
+        this.ctx = ctx;
+        this.screenshots = new ListingScreenshotsApi(ctx);
+    }
+    /** The application's store page in whatever state, or `null` if it has none. */
+    async get(applicationId) {
+        return this.ctx.request('GET', listingPath(applicationId), undefined, { cache: false });
+    }
+    /**
+     * Create the page or replace its content. Never its status.
+     *
+     * Editing does not move a page: correcting a typo on a live listing leaves
+     * it live, and fixing a rejected one does not re-submit it.
+     */
+    async write(applicationId, input) {
+        return this.ctx.request('PUT', listingPath(applicationId), input, { cache: false });
+    }
+    /** Hand the page to the store for review. From a draft, or a rejected page once fixed. */
+    async submit(applicationId) {
+        return this.ctx.request('POST', `${listingPath(applicationId)}/submit`, undefined, {
+            cache: false,
+        });
+    }
+    /**
+     * Take the page down, or withdraw it from the queue.
+     *
+     * Back to a draft, never deleted: the slug, the words and the screenshots are
+     * the publisher's work, and the reviews were never the listing's to take with
+     * them.
+     */
+    async unpublish(applicationId) {
+        return this.ctx.request('POST', `${listingPath(applicationId)}/unpublish`, undefined, {
+            cache: false,
+        });
+    }
+}
+export class StoreApi {
+    constructor(ctx) {
+        this.ctx = ctx;
+        this.reviews = new StoreReviewsApi(ctx);
+        this.listing = new StoreListingApi(ctx);
+    }
+    // The storefront is public: everything served here needs no session.
+    /** The shelves, in the order the store curates them. */
+    async categories() {
+        const res = await this.ctx.request('GET', '/store/categories', undefined, {
+            cache: true,
+            cacheTTL: MEDIUM_TTL,
+        });
+        return res.data ?? [];
+    }
+    /**
+     * Published listings, newest first, optionally one shelf.
+     *
+     * An unknown category slug is an EMPTY shelf, not every app on the store —
+     * so a typo shows nothing rather than showing everything.
+     *
+     * @param options - `category` is a category slug; `limit` defaults to 24.
+     */
+    async apps(options = {}) {
+        const res = await this.ctx.request('GET', `/store/apps${queryOf(options)}`, undefined, { cache: true, cacheTTL: SHORT_TTL });
+        return pageOf(res);
+    }
+    /**
+     * One store page.
+     *
+     * A draft answers 404 exactly as an unknown slug does: whether an unpublished
+     * page exists under a name is not something a visitor learns.
+     *
+     * @param slug - The listing's public slug, not an application id.
+     */
+    async app(slug) {
+        const res = await this.ctx.request('GET', `/store/apps/${enc(slug)}`, undefined, {
+            cache: true,
+            cacheTTL: SHORT_TTL,
+        });
+        return res.data;
+    }
+}
+function reviewPath(slug) {
+    return `/store/apps/${enc(slug)}/review`;
+}
+function listingPath(applicationId) {
+    return `/applications/${enc(applicationId)}/listing`;
+}
+function screenshotsPath(applicationId) {
+    return `${listingPath(applicationId)}/screenshots`;
+}

package/dist/esm/api/topics.js

@@ -0,0 +1,62 @@
+const SHORT = 60 * 1000;
+const LONG = 5 * 60 * 1000;
+const EXTRA_LONG = 30 * 60 * 1000;
+export class TopicsApi {
+    constructor(ctx) {
+        this.ctx = ctx;
+    }
+    /** Topics, filtered and paginated; returns the page with `total`/`limit`/`offset`. */
+    async list(options = {}) {
+        const params = {};
+        if (options.type)
+            params.type = options.type;
+        if (options.q)
+            params.q = options.q;
+        if (options.limit)
+            params.limit = options.limit;
+        if (options.offset)
+            params.offset = options.offset;
+        if (options.locale)
+            params.locale = options.locale;
+        const res = await this.ctx.request('GET', '/topics', params, {
+            cache: true,
+            cacheTTL: SHORT,
+        });
+        return {
+            topics: res.topics ?? [],
+            total: res.total ?? res.topics?.length ?? 0,
+            limit: res.limit ?? options.limit ?? 0,
+            offset: res.offset ?? options.offset ?? 0,
+        };
+    }
+    /** Topics matching `query`. Never cached. */
+    async search(query, limit) {
+        const params = { q: query };
+        if (limit)
+            params.limit = limit;
+        const res = await this.ctx.request('GET', '/topics/search', params, { cache: false });
+        return res.topics ?? [];
+    }
+    /** One topic by slug. */
+    async get(slug) {
+        return this.ctx.request('GET', `/topics/${slug}`, undefined, { cache: true, cacheTTL: LONG });
+    }
+    /** The top-level categories, optionally translated. */
+    async categories(locale) {
+        const res = await this.ctx.request('GET', '/topics/categories', locale ? { locale } : {}, { cache: true, cacheTTL: EXTRA_LONG });
+        return res.categories ?? [];
+    }
+    /** Resolve names to topics, creating the missing ones. Staff or service only. */
+    async resolveNames(names) {
+        const res = await this.ctx.request('POST', '/topics/resolve', { names }, {
+            cache: false,
+        });
+        return Object.values(res.topics ?? {});
+    }
+    /** Update a topic's description and translations. Staff or service only. */
+    async update(slug, data) {
+        const topic = await this.ctx.request('PATCH', `/topics/${slug}`, data, { cache: false });
+        this.ctx.oxy.cache.delete(`GET:/topics/${slug}`);
+        return topic;
+    }
+}