@recursiv/sdk 0.7.50 → 0.7.52

package/dist/resources/boosts.js

@@ -0,0 +1,75 @@
+/**
+ * Boost: pay to promote your own post into the For You feed. CPM campaigns
+ * funded from a prepaid balance with an append-only ledger. Top-ups run on the
+ * app's own Stripe account and need a project-scoped key.
+ */
+export class BoostsResource {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    /**
+     * Create a campaign for one of your own posts. Debits `budget_micros` from your balance
+     * (402 `insufficient_balance` when it cannot). Starts `pending` review.
+     * Not retried automatically, so a slow response cannot fund two campaigns.
+     */
+    create(input) {
+        return this.client.post('/boosts', input, { retry: false });
+    }
+    /** Your campaigns, newest first, with spend and impressions. */
+    mine(params) {
+        return this.client.get('/boosts/mine', params);
+    }
+    /**
+     * Your balance, recent ledger, the CPM floor, the top-up limits, and the boost credit your
+     * plan on this app adds each paid period (`meta.plan_credit`, a `grant` ledger row per period).
+     */
+    balance() {
+        return this.client.get('/boosts/balance');
+    }
+    /** Pause one of your active campaigns. */
+    pause(campaignId) {
+        return this.client.post(`/boosts/${encodeURIComponent(campaignId)}/pause`, {});
+    }
+    /** Resume one of your paused campaigns. */
+    resume(campaignId) {
+        return this.client.post(`/boosts/${encodeURIComponent(campaignId)}/resume`, {});
+    }
+    /** Cancel a campaign and refund its unspent budget to your balance (`meta.refunded_micros`). */
+    cancel(campaignId) {
+        return this.client.post(`/boosts/${encodeURIComponent(campaignId)}/cancel`, {});
+    }
+    /** Report an impression or click on a boosted feed entry. Idempotent per viewer per UTC day. */
+    recordEvent(campaignId, kind) {
+        return this.client.post(`/boosts/${encodeURIComponent(campaignId)}/events`, { kind });
+    }
+    /**
+     * Buy boost credit: opens a one-time Stripe Checkout for `amount_cents` (USD) on the app's
+     * own Stripe account. The balance is credited once the payment succeeds. Limits are in
+     * `balance().meta.topup`. Requires a project-scoped key with `billing:write`.
+     * `return_url` keeps its own query and fragment; `topup=success&session_id=<id>` or
+     * `topup=cancelled` is added to its query (to the fragment's query for a hash route).
+     */
+    topup(input) {
+        return this.client.post('/boosts/topup', input, { retry: false });
+    }
+    /**
+     * Credit a paid top-up when the member returns from Checkout. Safe to call repeatedly
+     * and alongside the webhook: a session credits the balance once.
+     */
+    confirmTopup(sessionId) {
+        return this.client.post('/boosts/topup/confirm', { session_id: sessionId });
+    }
+    /** Campaigns waiting for review, oldest first (admin). */
+    listPendingReview(params) {
+        return this.client.get('/boosts/review', params);
+    }
+    /** Approve or reject a campaign (admin). Rejecting refunds the unspent budget. */
+    review(campaignId, input) {
+        return this.client.post(`/boosts/review/${encodeURIComponent(campaignId)}`, input);
+    }
+    /** Grant balance to a user (admin). */
+    grant(input) {
+        return this.client.post('/boosts/grant', input, { retry: false });
+    }
+}

package/dist/resources/chat.d.ts

@@ -1,5 +1,5 @@
 import type { HttpClient } from '../client.js';
-import type { PaginatedResponse, SingleResponse, SuccessResponse, Conversation, ConversationDetail, Message, SendMessageInput, SentMessage, DmInput, DmResult, PaginationParams } from '../types.js';
+import type { PaginatedResponse, SingleResponse, SuccessResponse, Conversation, ConversationDetail, Message, SendMessageInput, SentMessage, DmInput, DmResult, PaginationParams, ConversationRequestResult, LeaveConversationResult } from '../types.js';
 export declare class ChatResource {
     private client;
     constructor(client: HttpClient);
@@ -11,7 +11,14 @@ export declare class ChatResource {
     communityConversation(communityId: string): Promise<SingleResponse<Conversation>>;
     /** Get a conversation by ID */
     conversation(id: string): Promise<SingleResponse<ConversationDetail>>;
-    /** List messages in a conversation (newest first) */
+    /**
+     * List messages in a conversation (newest first).
+     *
+     * For scrolling back, pass the previous page's `meta.next_cursor` as
+     * `cursor` rather than growing `offset`: an offset counts from the newest
+     * message and shifts every time one arrives, a cursor does not. The cursor
+     * is bound to this conversation.
+     */
     messages(conversationId: string, params?: PaginationParams): Promise<PaginatedResponse<Message>>;
     /** Send a message to a conversation */
     send(input: SendMessageInput): Promise<SingleResponse<SentMessage>>;
@@ -35,8 +42,31 @@ export declare class ChatResource {
         name: string;
         member_ids: string[];
     }): Promise<SingleResponse<ConversationDetail>>;
-    /** Delete a conversation (only the creator can delete) */
+    /**
+     * Delete a conversation for every member. Allowed when the conversation's
+     * `can_delete` is true: the caller started it, or every other member is an
+     * agent. Otherwise the API answers 403 `not_creator`; use `leave()` where
+     * `can_leave` is true.
+     */
     deleteConversation(id: string): Promise<SuccessResponse>;
+    /**
+     * Remove the caller from a conversation (a group, or a room whose other
+     * members are all agents). The last person to leave removes the room. A
+     * one-on-one with another person cannot be left (409 `dm_leave_unsupported`);
+     * check `can_leave` on the conversation first.
+     *
+     * This changes membership. It is not `realtime.leaveConversation()`, which
+     * only stops listening for live events.
+     */
+    leave(conversationId: string): Promise<SingleResponse<LeaveConversationResult>>;
+    /** Accept a message request (`request_status: 'pending'`). Idempotent; also reverses a decline. */
+    acceptRequest(conversationId: string): Promise<SingleResponse<ConversationRequestResult>>;
+    /**
+     * Decline a message request. The conversation leaves the caller's lists and
+     * stops notifying them; the sender is not told. Only a pending request can
+     * be declined (409 `not_a_request` otherwise). Idempotent.
+     */
+    declineRequest(conversationId: string): Promise<SingleResponse<ConversationRequestResult>>;
     /** React to a message (toggles: adds if not present, removes if already reacted) */
     reactToMessage(messageId: string, input: {
         type: string;

package/dist/resources/chat.js

@@ -15,7 +15,14 @@ export class ChatResource {
     conversation(id) {
         return this.client.get(`/chat/conversations/${id}`);
     }
-    /** List messages in a conversation (newest first) */
+    /**
+     * List messages in a conversation (newest first).
+     *
+     * For scrolling back, pass the previous page's `meta.next_cursor` as
+     * `cursor` rather than growing `offset`: an offset counts from the newest
+     * message and shifts every time one arrives, a cursor does not. The cursor
+     * is bound to this conversation.
+     */
     messages(conversationId, params) {
         return this.client.get(`/chat/conversations/${conversationId}/messages`, params);
     }
@@ -41,10 +48,39 @@ export class ChatResource {
     createGroup(input) {
         return this.client.post('/chat/conversations/group', input);
     }
-    /** Delete a conversation (only the creator can delete) */
+    /**
+     * Delete a conversation for every member. Allowed when the conversation's
+     * `can_delete` is true: the caller started it, or every other member is an
+     * agent. Otherwise the API answers 403 `not_creator`; use `leave()` where
+     * `can_leave` is true.
+     */
     deleteConversation(id) {
         return this.client.delete(`/chat/conversations/${id}`);
     }
+    /**
+     * Remove the caller from a conversation (a group, or a room whose other
+     * members are all agents). The last person to leave removes the room. A
+     * one-on-one with another person cannot be left (409 `dm_leave_unsupported`);
+     * check `can_leave` on the conversation first.
+     *
+     * This changes membership. It is not `realtime.leaveConversation()`, which
+     * only stops listening for live events.
+     */
+    leave(conversationId) {
+        return this.client.post(`/chat/conversations/${conversationId}/leave`);
+    }
+    /** Accept a message request (`request_status: 'pending'`). Idempotent; also reverses a decline. */
+    acceptRequest(conversationId) {
+        return this.client.post(`/chat/conversations/${conversationId}/accept`);
+    }
+    /**
+     * Decline a message request. The conversation leaves the caller's lists and
+     * stops notifying them; the sender is not told. Only a pending request can
+     * be declined (409 `not_a_request` otherwise). Idempotent.
+     */
+    declineRequest(conversationId) {
+        return this.client.post(`/chat/conversations/${conversationId}/decline`);
+    }
     /** React to a message (toggles: adds if not present, removes if already reacted) */
     reactToMessage(messageId, input) {
         return this.client.post(`/chat/messages/${messageId}/react`, input);

package/dist/resources/communities.d.ts

@@ -1,19 +1,31 @@
 import type { HttpClient } from '../client.js';
-import type { Community, CommunityBannedMember, CommunityDetail, CommunityMember, CreateCommunityInput, CreatedCommunity, JoinResult, LeaveResult, ListCommunitiesParams, PaginatedResponse, PaginationParams, SingleResponse } from '../types.js';
+import type { Community, CommunityBannedMember, CommunityCard, CommunityDetail, CommunityMember, CommunityPeopleParams, CreateCommunityInput, CreatedCommunity, JoinResult, LeaveResult, ListCommunitiesParams, PaginatedResponse, PaginationParams, RelatedCommunity, SingleResponse } from '../types.js';
 export declare class CommunitiesResource {
     private client;
     constructor(client: HttpClient);
-    /** List public communities, or only the authenticated caller's memberships. */
+    /**
+     * List public communities, or only the authenticated caller's memberships
+     * (`member: true`). `q` filters either list by name or description.
+     */
     list(params?: ListCommunitiesParams): Promise<PaginatedResponse<Community>>;
-    /** Get a community by ID */
-    get(id: string): Promise<SingleResponse<CommunityDetail>>;
-    /** List members of a community */
-    /** Groups related to this one, ranked by shared members; the caller's own groups are left out. */
+    /**
+     * Search communities by name or description, server-side. Name matches rank
+     * first. Pass `{ member: true }` to search only the caller's own groups.
+     */
+    search(query: string, params?: ListCommunitiesParams): Promise<PaginatedResponse<Community>>;
+    /**
+     * Get a community by ID or slug. A private group the caller is not in comes
+     * back as a `CommunityCard` (`limited: true`) instead of a 404; a hidden one
+     * still 404s.
+     */
+    get(id: string): Promise<SingleResponse<CommunityDetail | CommunityCard>>;
+    /** Public groups related to this one, ranked by shared members; each row carries the caller's `is_member`. */
     related(id: string, params?: {
         limit?: number;
-    }): Promise<PaginatedResponse<Community>>;
-    members(id: string, params?: PaginationParams): Promise<PaginatedResponse<CommunityMember>>;
-    /** Create a new community */
+    }): Promise<PaginatedResponse<RelatedCommunity>>;
+    /** List members of a community. `q` searches by name or username. */
+    members(id: string, params?: CommunityPeopleParams): Promise<PaginatedResponse<CommunityMember>>;
+    /** Create a new community. Omit slug for a server-generated collision-resistant slug. */
     create(input: CreateCommunityInput): Promise<SingleResponse<CreatedCommunity>>;
     /** Join a community */
     join(id: string): Promise<SingleResponse<JoinResult>>;
@@ -28,8 +40,8 @@ export declare class CommunitiesResource {
     delete(id: string): Promise<SingleResponse<{
         deleted: boolean;
     }>>;
-    /** People waiting to join a private group. Moderator or higher. */
-    requests(id: string, params?: PaginationParams): Promise<PaginatedResponse<CommunityMember>>;
+    /** People waiting to join a private group. Moderator or higher. `q` searches by name or username. */
+    requests(id: string, params?: CommunityPeopleParams): Promise<PaginatedResponse<CommunityMember>>;
     /** Active bans an admin can review and lift. Admin or higher. */
     bans(id: string, params?: PaginationParams): Promise<PaginatedResponse<CommunityBannedMember>>;
     /** Let a pending member in. Admin or higher. */

package/dist/resources/communities.js

@@ -3,23 +3,37 @@ export class CommunitiesResource {
     constructor(client) {
         this.client = client;
     }
-    /** List public communities, or only the authenticated caller's memberships. */
+    /**
+     * List public communities, or only the authenticated caller's memberships
+     * (`member: true`). `q` filters either list by name or description.
+     */
     list(params) {
         return this.client.get('/communities', params);
     }
-    /** Get a community by ID */
+    /**
+     * Search communities by name or description, server-side. Name matches rank
+     * first. Pass `{ member: true }` to search only the caller's own groups.
+     */
+    search(query, params) {
+        return this.client.get('/communities', { ...params, q: query });
+    }
+    /**
+     * Get a community by ID or slug. A private group the caller is not in comes
+     * back as a `CommunityCard` (`limited: true`) instead of a 404; a hidden one
+     * still 404s.
+     */
     get(id) {
         return this.client.get(`/communities/${id}`);
     }
-    /** List members of a community */
-    /** Groups related to this one, ranked by shared members; the caller's own groups are left out. */
+    /** Public groups related to this one, ranked by shared members; each row carries the caller's `is_member`. */
     related(id, params) {
         return this.client.get(`/communities/${encodeURIComponent(id)}/related`, params);
     }
+    /** List members of a community. `q` searches by name or username. */
     members(id, params) {
         return this.client.get(`/communities/${id}/members`, params);
     }
-    /** Create a new community */
+    /** Create a new community. Omit slug for a server-generated collision-resistant slug. */
     create(input) {
         return this.client.post('/communities', input);
     }
@@ -40,7 +54,7 @@ export class CommunitiesResource {
         return this.client.delete(`/communities/${id}`);
     }
     // ── Running the group: the tools an owner, admin or moderator has ────────
-    /** People waiting to join a private group. Moderator or higher. */
+    /** People waiting to join a private group. Moderator or higher. `q` searches by name or username. */
     requests(id, params) {
         return this.client.get(`/communities/${id}/requests`, params);
     }

package/dist/resources/curator.d.ts

@@ -1,5 +1,23 @@
 import type { HttpClient } from '../client.js';
-import type { PaginatedResponse, Post, SingleResponse } from '../types.js';
+import type { DiscoveryLayout, PaginatedResponse, PaginationMeta, Post, SingleResponse } from '../types.js';
+/** Which surface is asking: Home's For You (default) or Discover's For you. */
+export type ForYouSurface = 'home' | 'discover';
+export type ForYouParams = {
+    limit?: number;
+    offset?: number;
+    /** The previous page's `meta.next_cursor`: pages a stored ranking, so posts read meanwhile never shift the next page. */
+    cursor?: string;
+    /** Adds `meta.discovery` (layouts) and the public safety floor; limit <= 25. */
+    discovery?: boolean;
+    /** `discover` ranks for Discover: fresher, beyond the member's follows, with their category order. */
+    surface?: ForYouSurface;
+};
+export interface ForYouMeta extends PaginationMeta {
+    discovery?: DiscoveryLayout;
+    next_cursor?: string;
+    /** Whether the ranker can personalize for this member yet (3 follows or 3 upvoted authors). */
+    personalized?: boolean;
+}
 /** RSS / Atom source. Default — `type` may be omitted for back-compat. */
 export interface CuratorRssSource {
     type?: 'rss';
@@ -250,10 +268,10 @@ export declare class CuratorResource {
      * existing posts for the signed-in user (engagement + recency + social +
      * affinity, no model calls). Returns posts in the same shape as
      * `sdk.posts.list()`, so any feed UI renders it unchanged. Requires a
-     * project-scoped key (the feed is per-app).
+     * project-scoped key (the feed is per-app). Servers that predate `cursor`,
+     * `discovery` and `surface` ignore them.
      */
-    forYou(params?: {
-        limit?: number;
-        offset?: number;
-    }): Promise<PaginatedResponse<Post>>;
+    forYou(params?: ForYouParams): Promise<PaginatedResponse<Post> & {
+        meta: ForYouMeta;
+    }>;
 }

package/dist/resources/curator.js

@@ -47,7 +47,8 @@ export class CuratorResource {
      * existing posts for the signed-in user (engagement + recency + social +
      * affinity, no model calls). Returns posts in the same shape as
      * `sdk.posts.list()`, so any feed UI renders it unchanged. Requires a
-     * project-scoped key (the feed is per-app).
+     * project-scoped key (the feed is per-app). Servers that predate `cursor`,
+     * `discovery` and `surface` ignore them.
      */
     forYou(params = {}) {
         return this.client.get('/curator/foryou', params);

package/dist/resources/deployments.d.ts

@@ -47,15 +47,20 @@ export interface PrepareProtocolServersInput {
      * hostnames must be allow-listed. Default `staging`.
      */
     target?: 'staging' | 'production';
+    /**
+     * `activitypub` is the staging GoToSocial and is required for staging. A
+     * production stack is the Bluesky PDS and the Nostr relay only (ActivityPub is
+     * Fedify inside the API), and a production request that names it is refused.
+     */
     hosts: {
         pds: string;
-        activitypub: string;
+        activitypub?: string;
         nostr: string;
     };
-    /** Immutable upstream image references including @sha256 digest. */
+    /** Immutable upstream image references including @sha256 digest; `activitypub` as for `hosts`. */
     images: {
         pds: string;
-        activitypub: string;
+        activitypub?: string;
         nostr: string;
     };
     /** A staging PLC, or https://plc.directory for a production PDS whose operator set HOSTED_PDS_PRODUCTION_PLC=true. */

package/dist/resources/discovery.d.ts

@@ -1,4 +1,5 @@
 import type { DiscoveryLayout, Post } from '../types.js';
+import type { CuratorResource } from './curator.js';
 import type { DiscoveryLearning } from './discovery-learning.js';
 import type { PostsResource } from './posts.js';
 import type { ProtocolsResource, SocialNetwork, SocialPost, SocialRadar, SocialRadarPosts } from './protocols.js';
@@ -201,7 +202,20 @@ export declare class DiscoveryFeedSession {
 export declare class DiscoveryResource {
     private posts;
     private protocols;
-    constructor(posts: PostsResource, protocols: ProtocolsResource);
+    private curator?;
+    constructor(posts: PostsResource, protocols: ProtocolsResource, curator?: Pick<CuratorResource, "forYou"> | undefined);
+    /**
+     * A For you Discover feed: the member's For You ranking (asked for Discover's surface, with layouts and a
+     * snapshot cursor) in a session's Minds slot. With a category, the session also reads open-network posts
+     * from that category (the member's top one); without, it is Minds only. Never the radar. The page-0
+     * arrangement and when to use which are the app's choice.
+     */
+    createPersonalFeed(options: {
+        networks: SocialNetwork[];
+        learning?: DiscoveryLearning;
+        recommend?: DiscoveryRecommendationSources;
+        category?: string;
+    }): DiscoveryFeedSession;
     createFeed(options: {
         networks: SocialNetwork[];
         category?: string;

package/dist/resources/discovery.js

@@ -160,6 +160,9 @@ export class DiscoveryFeedSession {
         return this.pending;
     }
     async read(stream) {
+        // `discovery` asks only for the layout judgment (and, for Minds posts, the public-only floor). The
+        // server's safety floor does not depend on it, so a reader that drops it to skip layout work (a clip
+        // pool) is screened exactly like this session.
         const params = { limit: 25, ...(this.category ? { category: this.category } : {}), discovery: true };
         if (stream.protocol === 'minds') {
             // Discover leads with what is moving now: the REST hot order (engagement
@@ -462,9 +465,34 @@ export class DiscoveryFeedSession {
 export class DiscoveryResource {
     posts;
     protocols;
-    constructor(posts, protocols) {
+    curator;
+    constructor(posts, protocols, curator) {
         this.posts = posts;
         this.protocols = protocols;
+        this.curator = curator;
+    }
+    /**
+     * A For you Discover feed: the member's For You ranking (asked for Discover's surface, with layouts and a
+     * snapshot cursor) in a session's Minds slot. With a category, the session also reads open-network posts
+     * from that category (the member's top one); without, it is Minds only. Never the radar. The page-0
+     * arrangement and when to use which are the app's choice.
+     */
+    createPersonalFeed(options) {
+        const curator = this.curator;
+        if (!curator)
+            throw new Error('createPersonalFeed needs the curator resource');
+        const list = {
+            // The session's `sort` and `category` are Discover's hot-order knobs; the ranker ignores them.
+            list: async (params) => {
+                const response = await curator.forYou({ limit: params?.limit, offset: params?.offset, cursor: params?.cursor, discovery: true, surface: 'discover' });
+                // A server that predates the cursor says has_more: false on a partial ranked page although its
+                // continuation serves the next offset. A cursor-aware server always says `personalized`, and its
+                // has_more is the end of the feed.
+                const legacy = typeof response.meta.personalized !== 'boolean';
+                return { ...response, meta: { ...response.meta, has_more: response.meta.has_more || (legacy && response.data.length > 0) } };
+            },
+        };
+        return new DiscoveryFeedSession(list, this.protocols, options.category ? options.networks : [], options.category, options.category ? 'all' : 'minds', options.learning, options.recommend);
     }
     createFeed(options) {
         // The radar rides along by default; an older server answers 404 and the session simply shows no story module.

package/dist/resources/invite-codes-admin.d.ts

@@ -18,12 +18,25 @@ export interface InviteCodeStats {
         used: number;
         expired: number;
         revoked: number;
+        /** @deprecated Use `total`. */
+        total_codes: number;
+        /** @deprecated Use `active`. */
+        active_codes: number;
+        /** @deprecated Use `used`. */
+        used_codes: number;
+        /** @deprecated Use `expired`. */
+        expired_codes: number;
+        /** @deprecated Use `revoked`. */
+        revoked_codes: number;
     };
     waitlist: Record<string, number>;
     current_wave: {
         id: string;
         wave: number;
         name: string;
+        max_codes: number;
+        invites_per_user: number;
+        reward_tokens: number;
         is_active: boolean;
     } | null;
 }

package/dist/resources/invite-codes.d.ts

@@ -90,10 +90,20 @@ export interface BulkGenerateResult {
 }
 export interface InviteStats {
     codes: {
+        total: number;
+        active: number;
+        used: number;
+        expired: number;
+        revoked: number;
+        /** @deprecated Use `total`. Retained for legacy admin clients. */
         total_codes: number;
+        /** @deprecated Use `active`. Retained for legacy admin clients. */
         active_codes: number;
+        /** @deprecated Use `used`. Retained for legacy admin clients. */
         used_codes: number;
+        /** @deprecated Use `expired`. Retained for legacy admin clients. */
         expired_codes: number;
+        /** @deprecated Use `revoked`. Retained for legacy admin clients. */
         revoked_codes: number;
     };
     waitlist: Record<string, number>;

package/dist/resources/invite-codes.js

@@ -43,26 +43,26 @@ export class InviteCodesResource {
     // ── Admin Methods ──
     /** Admin: Initialize wave configs for the network */
     initializeWaves() {
-        return this.client.post('/invite-codes/admin/initialize-waves');
+        return this.client.post('/invite-codes-admin/waves/initialize');
     }
     /** Admin: Get all wave configs */
     getWaves() {
-        return this.client.get('/invite-codes/admin/waves');
+        return this.client.get('/invite-codes-admin/waves');
     }
     /** Admin: Activate a specific wave */
     activateWave(wave) {
-        return this.client.post('/invite-codes/admin/activate-wave', { wave });
+        return this.client.post('/invite-codes-admin/waves/activate', { wave });
     }
     /** Admin: Bulk generate invite codes */
     bulkGenerate(input) {
-        return this.client.post('/invite-codes/admin/bulk-generate', input);
+        return this.client.post('/invite-codes-admin/bulk-generate', input);
     }
     /** Admin: Get invite system stats */
     getStats() {
-        return this.client.get('/invite-codes/admin/stats');
+        return this.client.get('/invite-codes-admin/stats');
     }
     /** Admin: Get waitlist entries */
     getWaitlist(params) {
-        return this.client.get('/invite-codes/admin/waitlist', params);
+        return this.client.get('/invite-codes-admin/waitlist', params);
     }
 }

package/dist/resources/notifications.d.ts

@@ -1,5 +1,35 @@
 import type { HttpClient } from '../client.js';
-import type { RegisterTokenInput, SuccessResponse, PaginationParams } from '../types.js';
+import type { RegisterTokenInput, SuccessResponse, SingleResponse, PaginationParams } from '../types.js';
+/** Who did the thing a notification is about. */
+export interface NotificationActor {
+    id: string;
+    name: string | null;
+    username: string | null;
+    image: string | null;
+    is_ai: boolean | null;
+}
+/**
+ * The post a notification references, as it reads NOW, with the viewer's own
+ * state so inline Upvote and Repost can start in the right position. `null`
+ * when the post is gone or no longer visible to the viewer.
+ */
+export interface NotificationPostPreview {
+    id: string;
+    excerpt: string | null;
+    media_url: string | null;
+    media_type: string | null;
+    reactions_count?: number;
+    score?: number;
+    upvote_count?: number;
+    downvote_count?: number;
+    /** The viewer's own reaction on this post ('upvote', 'downvote', ...), if any. */
+    user_reaction?: string | null;
+    reply_count?: number;
+    unique_commenters?: number;
+    reposts_count?: number;
+    /** Id of the viewer's own repost of this post; delete it to undo the repost. */
+    reposted_by_viewer_id?: string | null;
+}
 export interface Notification {
     id: string;
     target_type: string;
@@ -11,8 +41,22 @@ export interface Notification {
     status: 'unread' | 'read' | 'archived';
     created_at: string;
     read_at: string | null;
+    /** For `post_reaction` rows: which reaction ('upvote', 'downvote', ...). Null otherwise or on older rows. */
+    reaction_type?: string | null;
+    actor?: NotificationActor | null;
+    post_preview?: NotificationPostPreview | null;
 }
 export type NotificationCategory = 'all' | 'social' | 'system';
+export type NotificationScopeParams = {
+    /** Which kind of notification to count. Defaults to `all`. Same meaning as in `list`. */
+    category?: NotificationCategory;
+    /** Scope to a specific organization, as `list` does. */
+    organization_id?: string;
+};
+export interface NotificationUnreadCount {
+    count: number;
+    category: NotificationCategory;
+}
 export interface ListNotificationsParams extends PaginationParams {
     status?: 'unread' | 'read' | 'all';
     cursor?: string;
@@ -22,8 +66,10 @@ export interface ListNotificationsParams extends PaginationParams {
      * Which kind of notification to return. Defaults to `all`.
      *
      * `social` is what a person did to you (follows, replies, reactions,
-     * reposts, mentions, chat, community invites/joins). `system` is everything
-     * operational (agent, task, deploy, billing, security).
+     * reposts, mentions, community invites, joins and join requests, moderation
+     * decisions). `system` is everything operational (agent, task, deploy,
+     * billing, security). Direct messages are in neither: they live in the chat
+     * inbox. `all` (the default) lists every row that has not been archived.
      *
      * Ask for it here rather than filtering the page you get back: the server
      * applies the limit AFTER the category, so a client that filters afterwards
@@ -43,10 +89,33 @@ export declare class NotificationsResource {
     constructor(client: HttpClient);
     /** List notifications for the authenticated user */
     list(params?: ListNotificationsParams): Promise<NotificationListResponse>;
+    /**
+     * Count unread notifications in a category, straight from the database.
+     * Use this for badges: `list` returns at most 50 rows, so a badge built from
+     * a page can only ever say "50+".
+     *
+     * @example
+     * const { data } = await r.notifications.unreadCount({ category: 'social' });
+     * setBadge(data.count);
+     */
+    unreadCount(params?: NotificationScopeParams): Promise<SingleResponse<NotificationUnreadCount>>;
     /** Mark a single notification as read */
     markAsRead(notificationId: string): Promise<SuccessResponse>;
-    /** Mark all notifications as read */
-    markAllAsRead(category?: NotificationCategory): Promise<SuccessResponse>;
+    /**
+     * Dismiss a notification (swipe to remove). It stops appearing in `list`
+     * and stops counting as unread; the row is kept, not deleted. Dismissing an
+     * id that is already dismissed, or not yours, succeeds and changes nothing.
+     */
+    archive(notificationId: string): Promise<SuccessResponse>;
+    /**
+     * Mark every unread notification in a scope as read. Pass the same scope the
+     * list was read with, so a client only clears what it could show.
+     *
+     * @example
+     * await r.notifications.markAllAsRead('social');
+     * await r.notifications.markAllAsRead({ category: 'social', organization_id: orgId });
+     */
+    markAllAsRead(scope?: NotificationCategory | NotificationScopeParams): Promise<SuccessResponse>;
     /** Register a push notification token for the current user */
     registerToken(input: RegisterTokenInput): Promise<SuccessResponse>;
     /** Unregister a push notification token (e.g., on logout) */