@recursiv/sdk 0.7.58 → 0.7.62

package/README.md

@@ -75,7 +75,7 @@ for await (const chunk of r.agents.chatStream(agent.id, { message: 'Hello!' }))
 | Resource | Key methods |
 |----------|------------|
 | `r.agents` | `create`, `update`, `chat`, `chatStream`, `retryChatStream`, `grantProjectAccess`, `conversations` |
-| `r.e2ee` | `status`, `registerDevice`, `devices`, `revokeDevice` (`{ cascade }` to also revoke devices approved through it; 409 `has_dependents` otherwise), `publishKeyPackages`, `keyPackageStatus`, `claimKeyPackage`, `appendEvent`, `events`, `acknowledge`, `conversations`; device linking by scan: `createLink`, `link`, `scannedLink`, `approveLink`, `completeLink`, `linkProgress`, `cancelLink` (flag-gated E2EE v2 transport; its doorbell is `r.realtime.onE2eeEvent`, which carries a small message's stored ciphertext to the owner's own sockets; link and device changes arrive on `r.realtime.onE2eeLink` and `onE2eeDevices`) |
+| `r.e2ee` | `status`, `registerDevice`, `devices`, `revokeDevice` (`{ cascade }` to also revoke devices approved through it; 409 `has_dependents` otherwise), `requestResetCode` and `resetAccount` (reset encrypted chat with an emailed code where `status().accountReset`), `publishKeyPackages`, `keyPackageStatus`, `claimKeyPackage`, `appendEvent`, `events`, `acknowledge`, `conversations`; device linking by scan: `createLink`, `link`, `scannedLink`, `approveLink`, `completeLink`, `linkProgress`, `cancelLink` (flag-gated E2EE v2 transport; its doorbell is `r.realtime.onE2eeEvent`, which carries a small message's stored ciphertext to the owner's own sockets; link and device changes arrive on `r.realtime.onE2eeLink` and `onE2eeDevices`) |
 | `r.brain` | `sendMessage` |
 | `r.commands` | `execute`, `gatePrompt` |
 | `r.projectBrain` | `tasks`, `decisions`, `milestones`, `completeTask`, `usage` |
@@ -96,7 +96,7 @@ for await (const chunk of r.agents.chatStream(agent.id, { message: 'Hello!' }))
 | `r.posts` | `create`, `update`, `list`, `liked`, `bookmarked`, `bookmark`, `unbookmark`, `search`, `replies`, `react` |
 | `r.bookmarks` | `save`, `unsave`, `posts`, `list`, `keys`, `merge` — the member's saved posts, open-network posts and articles, synced across devices |
 | `r.communities` | `create`, `join`, `search`, `members` |
-| `r.chat` | `send`, `dm`, `createGroup`, `messages` (cursor paging), `acceptRequest`, `declineRequest`, `leave`, `deleteConversation` |
+| `r.chat` | `send`, `dm`, `createGroup` (`encrypted: true` for an end-to-end encrypted group, 0.7.59), `messages` (cursor paging), `acceptRequest`, `declineRequest`, `leave`, `deleteConversation`; a private group's admin: `addMembers`, `removeMember`, `updateGroup` (0.7.59) |
 | `r.tags` | `create`, `list` |
 | `r.uploads` | `uploadMedia` — upload post/chat bytes end to end |
 | `r.video` | `entitlement` (may the caller publish video, and how much is left), `createUpload`, `getStatus`, `getPlaybackToken` |
@@ -115,7 +115,7 @@ for await (const chunk of r.agents.chatStream(agent.id, { message: 'Hello!' }))
 | `r.admin` | User management, stats, content reports (`listReports`, `resolveReport`, `dismissReport`) |
 | `r.dispatcher` | Task queue, claims, signals, outcomes, webhooks |
 | `r.goals` | Org goals with task rollups (group dispatcher tasks) |
-| `r.protocols` | Private Minds safety: `sourceControls` (current enablement and saved choices; filter with `control`, each item may carry a `display` label), `setSourceControl`, `onSourceControlChange`, `reportSource`. Delegated accounts: `nativeSocialAccounts`, `startNativeSocialConnection`, `finishNativeSocialConnection`, `disconnectNativeSocialAccount`. Native follows: `nativeFollowStates` (every connected account's state for one source, one read), `nativeFollowState`, `prepareNativeFollow`, `submitNativeFollow`, `nativeFollowStatus` (native following or pending approval, distinct from a Minds feed subscription; preserve the complete signed Nostr list). Native reposts and undo: `nativeRepostState`, `prepareNativeRepost`, `submitNativeRepost`, `nativeRepostStatus` (public posts, explicit approval, connected account, no uncertain retries). Native likes and unlikes: `nativeLikeState`, `prepareNativeLike`, `submitNativeLike`, `nativeLikeStatus` (connected authority, app enablement and explicit approval; resume pending actions instead of duplicating them). Reviewed replies and optional linked posts: `prepareNativeReply`, `submitNativeReply`, `nativeReplyStatus`, `nativeReplyHistory`, `prepareNativeReplyRemoval`, `removeNativeReply` (require deployed API support and app enablement). Keyless shared post links: `sharedNetworks(projectId)`, `getSharedConversation(projectId, { protocol, post, readRef? })`. Member public reading: `searchPublicPosts` (selected account required for Bluesky/ActivityPub; public Nostr search), `getConnectedSocialConversation` (preserve result readerAccountId/readRef), `publicNetworks`, `searchPublicProfiles`, `getPublicProfile`, `getPublicAuthorFeed`, `getFollowingFeed`, `getPublicConversation`, `getPublicTrends`, `getPublicTrendFeed`; radar stories: `getPublicRadarStory` (one story by id with its posts; one that left the radar within its minimum lifetime, or within the last half hour, still answers live with `liveUntil` and the story that continues it; one that has left for longer comes with its archived copy and the live story it continues as; the id may be a World Today edition story's, and the answer then names it in `editionStory` under the story's radar id), keyless `getSharedRadarStory(projectId, { cluster })` and `getSharedRadarPosts(projectId, { cluster })` (keyless reads carry images and videos only from outlets and members marked `visitorMedia`; signed-in reads keep all media, so a share card uses only those); private app subscriptions: `listSubscriptions`, `subscribeToProfile`, `unsubscribeFromProfile`, `onSubscriptionChange`. `list` returns bounded adapter `maturity`, `limitations`, and exhaustive `supported`/`planned`/`unsupported` implementation capabilities (not provider health or enablement); settings, candidate refresh/status, search, and read-only quarantined candidate review via `listCandidates` / `getCandidate` |
+| `r.protocols` | Private Minds safety: `sourceControls` (current enablement and saved choices; filter with `control`, each item may carry a `display` label), `setSourceControl`, `onSourceControlChange`, `reportSource`. Delegated accounts: `nativeSocialAccounts`, `startNativeSocialConnection`, `finishNativeSocialConnection`, `disconnectNativeSocialAccount`. Native follows: `nativeFollowStates` (every connected account's state for one source, one read), `nativeFollowState`, `prepareNativeFollow`, `submitNativeFollow`, `nativeFollowStatus` (native following or pending approval, distinct from a Minds feed subscription; preserve the complete signed Nostr list). Native reposts and undo: `nativeRepostState`, `prepareNativeRepost`, `submitNativeRepost`, `nativeRepostStatus` (public posts, explicit approval, connected account, no uncertain retries). Native likes and unlikes: `nativeLikeState`, `prepareNativeLike`, `submitNativeLike`, `nativeLikeStatus` (connected authority, app enablement and explicit approval; resume pending actions instead of duplicating them). Reviewed replies and optional linked posts: `prepareNativeReply`, `submitNativeReply`, `nativeReplyStatus`, `nativeReplyHistory`, `prepareNativeReplyRemoval`, `removeNativeReply` (require deployed API support and app enablement). Keyless shared post links: `sharedNetworks(projectId)`, `getSharedConversation(projectId, { protocol, post, readRef? })`. Member public reading: `searchPublicPosts` (selected account required for Bluesky/ActivityPub; public Nostr search), `getConnectedSocialConversation` (preserve result readerAccountId/readRef), `publicNetworks`, `searchPublicProfiles`, `getPublicProfile`, `getPublicAuthorFeed`, `getFollowingFeed`, `getPublicConversation`, `getPublicTrends`, `getPublicTrendFeed`; radar stories: `getPublicRadarStory` (one story by id with its posts; one that left the radar within its minimum lifetime, or within the last half hour, still answers live with `liveUntil` and the story that continues it; one that has left for longer comes with its archived copy and the live story it continues as; the id may be a World Today edition story's, and the answer then names it in `editionStory` under the story's radar id), keyless `getSharedRadarStory(projectId, { cluster })` and `getSharedRadarPosts(projectId, { cluster })` (keyless reads carry images and videos only from outlets and members marked `visitorMedia`; signed-in reads keep all media, so a share card uses only those); the Viral read (fastest-moving posts across Bluesky, the Fediverse, Nostr and Minds, each against its own network's pace; 0.7.59): `getPublicViral({ network?, category?, media?: 'video', limit?: 5 | 10 | 20 | 40, cursor?, compass? })` under the member's key and keyless `getSharedViral(projectId, params)` (visitors: `compass` `all` or `hide` only; a visitor's `media: 'video'` read can carry items whose video the server withheld, so filter with the exported `viralItemHasVideo` before a video player; `item.post` narrows on `item.protocol`). `status: 'off'` resolves with no items until the app enables the read, and `getSharedViral` also resolves an older API's 401 `missing_api_key` as off; `getPublicViral` throws every 401 and 403, so a session failure is never read as off; private app subscriptions: `listSubscriptions`, `subscribeToProfile`, `unsubscribeFromProfile`, `onSubscriptionChange`. `list` returns bounded adapter `maturity`, `limitations`, and exhaustive `supported`/`planned`/`unsupported` implementation capabilities (not provider health or enablement); settings, candidate refresh/status, search, and read-only quarantined candidate review via `listCandidates` / `getCandidate` |
 
 Full reference: see [llm.md](./llm.md) (ships with this package) or the type definitions in `dist/`.
 
@@ -364,7 +364,7 @@ try {
 }
 ```
 
-Auto-retry is built in. 429 and 5xx responses retry with exponential backoff (configurable via `maxRetries`, default 2). A 429 with `X-RateLimit-Scope: action` refuses one member action past its budget and is never retried: its `RateLimitError` has `scope: 'action'` and `resetAt` (a `Date`, when that action's budget reopens).
+Auto-retry is built in. 429 and 5xx responses retry with exponential backoff (configurable via `maxRetries`, default 2). A 429 with `X-RateLimit-Scope: action` refuses one member action past its budget and is never retried: its `RateLimitError` has `scope: 'action'` and `resetAt` (a `Date`, when that action's budget reopens). A read that holds its own deadline can ask once with `retry: false` in its params: `r.posts.list({ ...params, retry: false })` and `r.curator.forYou({ ...params, retry: false })` throw the first 5xx or 429 with no retry and no `Retry-After` sleep, and never send `retry` to the server.
 
 ## Pagination
 
@@ -653,8 +653,13 @@ sources; create a new session to refresh exhausted source windows. A topics netw
 (Bluesky) is read one topic page at a time; in a category the catalog's previews are not
 judged to be in it, so a read walks into the topics at once, and walks past a topic the
 provider no longer lists (`trend_unavailable`) or one with nothing in the category, up
-to five topic pages a read, so a page reaches a topic that carries posts. Any other
-failure marks the source failed until `retryFailed()`.
+to five topic pages a read, so a page reaches a topic that carries posts. A network read
+that fails for a passing reason (past the 15 s page deadline, a dropped connection, a 429
+or a 5xx) leaves the network out of that page and the next, named in `retryingSources`
+until a later page asks it again (from the page after, when its turn comes), up to two
+times in a row. Any other failure, or one past that, marks the source failed
+(`failedSources`) until `retryFailed()`. The Minds read is asked once and is never
+retried this way: any failure of it is in `failedSources` on that page.
 
 `sdk.discovery.createPersonalFeed({ networks, category?, learning?, recommend? })`
 builds the same kind of session for a member's For you tab: its Minds slot reads
@@ -664,6 +669,18 @@ and says whether the member is personalized yet (`meta.personalized`). With a
 `category` (the member's first), the session also reads open-network posts from it;
 without, it is Minds only. It never carries the radar.
 
+Both take a Politics choice, `compass` (`all`, `mix`, `hide`, or cells in the order
+`lo,co,ro,lm,cm,rm,ll,cl,rl`, optionally `np`), and send it with every Minds read
+(`posts.list` and `curator.forYou` take it too). Each such page says what it did in
+`meta.compass_filter` (`status` `applied` or `unavailable`, and counts only), and each session
+page carries its Minds read's answer as `page.compass` (`unavailable`: the page is unfiltered). Only Minds
+posts are filtered, so a view that leaves posts out reads best with `source: 'minds'`.
+The catalog lists `compass_filter` on every network when the filter is served to the viewer.
+Hide politics (`compass: 'hide'`) also applies on its own, with or without compass judgments on the server, to
+`sdk.discovery.videos`, `protocols.getPublicTrends` and the radar (`getPublicRadar`, keyless `getSharedRadar`; 0.7.62):
+it leaves out what is categorised politics (a story not themed yet, or `mixed`, too) and says what it did in
+`meta.compass_filter`. These reads answer a side or Mix unfiltered, marked `unavailable`.
+
 `sdk.discovery.recommendations({ kind, category?, limit?, session?, exclude? })` is
 the app's one recommender for suggestion rails: `kind` is `member`, `group`, `tag`,
 `network_account` or `story`, and `category` is `all` or a browse category id. It
@@ -682,14 +699,20 @@ history: every page's `meta.next` is `{ offset }`, `{ cursor }` or `null`, and w
 stage ends `meta.fallover` lists where to go, in order: `category_older` (the keyset
 cursor `next` also carries), `category_network` (the same category on the open
 networks), the member's next categories (`via` names the order they came from), `for_you`
-and `all`. A `DiscoveryFeedSession` follows the cursor itself and reports the Minds
-feed's `fallover` on its pages. `sdk.discovery.category({ category, session? })` answers a
+and `all`. A `feed` step (`ref`, the next feed's ref; 0.7.60) is declared but not sent yet:
+skip a kind your app cannot open. A `DiscoveryFeedSession` follows the cursor itself and
+reports the Minds feed's `fallover` on its pages, leaving out any step this SDK does not
+know or a malformed one. `sdk.discovery.category({ category, session? })` answers a
 category's surface in one call: `stories`, `network` and `clips` (each shared per app and
 category, refreshed after 30 s, kept up to 300 s and warmed as the warmer reaches the category, then filtered for the viewer on every call: the cached safety verdicts of story members, network posts and clips again, the term list, the viewer's blocks and mutes over clips, and the member's own hidden sources over network posts and story members) and the
 viewer's `people` and `groups`; a section that timed out, failed or is off is empty with a
 `reason` for that request only (a failure is never cached, so asking again retries it), and one this
 key may not read is empty with `refused` (`stories` and `network` need the member's own app
-key with `users:read`; `people` and `groups` need `users:read`). A plain category page
+key with `users:read`; `people` and `groups` need `users:read`). `sdk.discovery.videos({ category?, limit?, cursor?, offset?, compass? })`
+is Watch's Minds read: the app's public video posts in hot order, from one list the server shares among every viewer of
+the app and rebuilds about once a minute, each post checked again on every call under the public floors and the viewer's
+blocks and mutes, in the `Post` shape with the viewer's own `user_reaction` and `reposted_by_viewer_id` (page on
+`meta.next_cursor`; a feed session's Minds slot can read it as its `list`). A plain category page
 (`posts.list({ category })` with no other filter) reads on past a slice the safety floors
 thinned, up to six reads, until it holds `limit` posts or its candidates end: `meta.scanned`
 is how many it examined (the next offset is `offset + scanned`), and the stage ends on the

package/dist/errors.d.ts

@@ -84,3 +84,16 @@ export declare class RateLimitError extends RecursivError {
 export declare class ConflictError extends RecursivError {
     constructor(body: ApiErrorBody['error']);
 }
+/**
+ * `email.send` answered 200 but sent to nobody: every recipient was held
+ * (no marketing consent, suppressed, preference off). Thrown so a caller that
+ * only checks for success cannot report mail as sent. `details` carries the
+ * per-recipient `messages` with each `reason`.
+ */
+export declare class EmailNotSentError extends RecursivError {
+    constructor(body: {
+        message: string;
+        hint?: string;
+        details?: unknown;
+    });
+}

package/dist/errors.js

@@ -189,3 +189,15 @@ export class ConflictError extends RecursivError {
         this.name = 'ConflictError';
     }
 }
+/**
+ * `email.send` answered 200 but sent to nobody: every recipient was held
+ * (no marketing consent, suppressed, preference off). Thrown so a caller that
+ * only checks for success cannot report mail as sent. `details` carries the
+ * per-recipient `messages` with each `reason`.
+ */
+export class EmailNotSentError extends RecursivError {
+    constructor(body) {
+        super(200, { type: 'email_not_sent', code: 'email_held', message: body.message, hint: body.hint, details: body.details });
+        this.name = 'EmailNotSentError';
+    }
+}

package/dist/feed-definition.d.ts

@@ -0,0 +1,129 @@
+/**
+ * FeedDefinition v1, as apps read and write it: the one recipe behind every feed (a list of sources read as one union,
+ * a ranking mode, optional filters and exclusions). Types and constants only; the server
+ * (packages/server/src/features/feeds/FeedDefinition.ts) validates, canonicalises and digests a definition, and its
+ * FeedDefinitionSdkContract test holds these constants equal to its own.
+ *
+ * Nothing serves a definition yet: no route reads one before the cutover. Discover's built-in categories, All and
+ * For you are definitions held in code on the server (refs `builtin:category:<id>`, `builtin:all`, `builtin:for_you`).
+ *
+ * A definition never holds the viewer's safe/open setting, blocks or mutes, or a compass Mix or Choose-sides choice:
+ * `filters.politics: 'hide'` is the only Politics value a feed stores.
+ */
+export declare const FEED_DEFINITION_VERSION: 1;
+/** Sources a definition may name, read as one union. Only `builtin:all` and `builtin:for_you` have none. */
+export declare const FEED_SOURCES_MAX = 50;
+/** The largest canonical definition the server keeps, in bytes. */
+export declare const FEED_DEFINITION_MAX_BYTES: number;
+export declare const FEED_SOURCE_KINDS: readonly ["category", "tag", "account", "community", "collection", "list", "story", "bsky_feed", "bsky_list", "bsky_starterpack", "nostr_set"];
+export type FeedSourceKind = typeof FEED_SOURCE_KINDS[number];
+export declare const FEED_RANKING_MODES: readonly ["hot", "new", "top", "for_you", "viral"];
+export type FeedRankingMode = typeof FEED_RANKING_MODES[number];
+export declare const FEED_RANKING_RANGES: readonly ["24h", "7d", "30d", "1y"];
+export type FeedRankingRange = typeof FEED_RANKING_RANGES[number];
+export declare const FEED_MEDIA: readonly ["any", "images", "video", "longread"];
+export type FeedMedia = typeof FEED_MEDIA[number];
+export declare const FEED_NETWORKS: readonly ["minds", "bluesky", "activitypub", "nostr"];
+export type FeedNetwork = typeof FEED_NETWORKS[number];
+/** Source kinds a topical feed may hold (with a hot, new or top ranking); any other feed is 'wide'. */
+export declare const FEED_TOPICAL_SOURCE_KINDS: readonly ["category", "tag", "account", "community", "list", "collection", "story"];
+export declare const FEED_TOPICAL_MODES: readonly ["hot", "new", "top"];
+/** The one field that names what each source kind reads. */
+export declare const FEED_SOURCE_KEY: {
+    readonly category: "id";
+    readonly tag: "slug";
+    readonly account: "ref";
+    readonly community: "id";
+    readonly collection: "id";
+    readonly list: "id";
+    readonly story: "clusterId";
+    readonly bsky_feed: "uri";
+    readonly bsky_list: "uri";
+    readonly bsky_starterpack: "uri";
+    readonly nostr_set: "naddr";
+};
+/** An account by its native id: a Minds user, an atproto DID, a Nostr hex pubkey or a WebFinger account. */
+export type FeedAccountRef = `user:${string}` | `did:${string}` | `nostr:${string}` | `acct:${string}`;
+export type FeedSource = 
+/** A Discover category id, as `posts.categories()` lists them. */
+{
+    kind: 'category';
+    id: string;
+}
+/** A hashtag, without the `#`. */
+ | {
+    kind: 'tag';
+    slug: string;
+} | {
+    kind: 'account';
+    ref: FeedAccountRef;
+} | {
+    kind: 'community';
+    id: string;
+}
+/** A member's collection of saved posts, or a list (after the cutover). */
+ | {
+    kind: 'collection';
+    id: string;
+} | {
+    kind: 'list';
+    id: string;
+}
+/** A World Today story, by its radar cluster id. */
+ | {
+    kind: 'story';
+    clusterId: string;
+}
+/** Bluesky feeds, lists and starter packs by their at:// record URI (after the cutover). */
+ | {
+    kind: 'bsky_feed';
+    uri: string;
+} | {
+    kind: 'bsky_list';
+    uri: string;
+} | {
+    kind: 'bsky_starterpack';
+    uri: string;
+}
+/** A Nostr people, interest, bookmark or curation set by its NIP-19 naddr (after the cutover). */
+ | {
+    kind: 'nostr_set';
+    naddr: string;
+};
+export interface FeedRanking {
+    mode: FeedRankingMode;
+    range?: FeedRankingRange;
+}
+export interface FeedFilters {
+    /** Absent means any media. */
+    media?: FeedMedia;
+    /** Absent means every network. */
+    networks?: FeedNetwork[];
+    /** The only Politics value a feed stores. Mix and Choose sides stay the viewer's own. */
+    politics?: 'hide';
+    /** BCP 47 language tags such as `en` or `pt-br`; at most 10. */
+    languages?: string[];
+}
+export interface FeedExclude {
+    /** At most 50 tags. */
+    tags?: string[];
+    /** At most 50 accounts. */
+    accounts?: FeedAccountRef[];
+}
+export interface FeedDefinition {
+    v: typeof FEED_DEFINITION_VERSION;
+    /** 1 to 50, read as one union; empty only for `builtin:all` and `builtin:for_you`. */
+    sources: FeedSource[];
+    ranking: FeedRanking;
+    filters?: FeedFilters;
+    exclude?: FeedExclude;
+}
+export type BuiltinFeedRef = `builtin:category:${string}` | 'builtin:all' | 'builtin:for_you';
+/** A feed's address: a built-in, a member feed's current version (`feed:<uuid>`), or one version of it. */
+export type FeedRef = BuiltinFeedRef | `feed:${string}` | `feed:${string}@${number}`;
+/** Computed by the server, never stored: 'anon' feeds are ranked once and may be shared; 'viewer' feeds are ranked per viewer. */
+export type FeedAudience = 'anon' | 'viewer';
+/** Computed by the server: 'wide' feeds leave out Bluesky authors who asked not to be recommended. */
+export type FeedConsentClass = 'topical' | 'wide';
+/** The built-in feed for a Discover category. */
+export declare function builtinCategoryFeedRef(category: string): BuiltinFeedRef;

package/dist/feed-definition.js

@@ -0,0 +1,46 @@
+/**
+ * FeedDefinition v1, as apps read and write it: the one recipe behind every feed (a list of sources read as one union,
+ * a ranking mode, optional filters and exclusions). Types and constants only; the server
+ * (packages/server/src/features/feeds/FeedDefinition.ts) validates, canonicalises and digests a definition, and its
+ * FeedDefinitionSdkContract test holds these constants equal to its own.
+ *
+ * Nothing serves a definition yet: no route reads one before the cutover. Discover's built-in categories, All and
+ * For you are definitions held in code on the server (refs `builtin:category:<id>`, `builtin:all`, `builtin:for_you`).
+ *
+ * A definition never holds the viewer's safe/open setting, blocks or mutes, or a compass Mix or Choose-sides choice:
+ * `filters.politics: 'hide'` is the only Politics value a feed stores.
+ */
+export const FEED_DEFINITION_VERSION = 1;
+/** Sources a definition may name, read as one union. Only `builtin:all` and `builtin:for_you` have none. */
+export const FEED_SOURCES_MAX = 50;
+/** The largest canonical definition the server keeps, in bytes. */
+export const FEED_DEFINITION_MAX_BYTES = 16 * 1024;
+export const FEED_SOURCE_KINDS = [
+    'category', 'tag', 'account', 'community', 'collection', 'list', 'story',
+    'bsky_feed', 'bsky_list', 'bsky_starterpack', 'nostr_set',
+];
+export const FEED_RANKING_MODES = ['hot', 'new', 'top', 'for_you', 'viral'];
+export const FEED_RANKING_RANGES = ['24h', '7d', '30d', '1y'];
+export const FEED_MEDIA = ['any', 'images', 'video', 'longread'];
+export const FEED_NETWORKS = ['minds', 'bluesky', 'activitypub', 'nostr'];
+/** Source kinds a topical feed may hold (with a hot, new or top ranking); any other feed is 'wide'. */
+export const FEED_TOPICAL_SOURCE_KINDS = ['category', 'tag', 'account', 'community', 'list', 'collection', 'story'];
+export const FEED_TOPICAL_MODES = ['hot', 'new', 'top'];
+/** The one field that names what each source kind reads. */
+export const FEED_SOURCE_KEY = {
+    category: 'id',
+    tag: 'slug',
+    account: 'ref',
+    community: 'id',
+    collection: 'id',
+    list: 'id',
+    story: 'clusterId',
+    bsky_feed: 'uri',
+    bsky_list: 'uri',
+    bsky_starterpack: 'uri',
+    nostr_set: 'naddr',
+};
+/** The built-in feed for a Discover category. */
+export function builtinCategoryFeedRef(category) {
+    return `builtin:category:${category}`;
+}

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 export * from './resources/discovery-learning.js';
 import { DiscoveryResource } from './resources/discovery.js';
 export * from './resources/discovery.js';
+export * from './feed-definition.js';
 import { AuthResource } from './resources/auth.js';
 import { PostsResource } from './resources/posts.js';
 import { UsersResource } from './resources/users.js';
@@ -154,12 +155,12 @@ export { UsersResource } from './resources/users.js';
 export { CommunitiesResource } from './resources/communities.js';
 export { ChatResource } from './resources/chat.js';
 export { E2eeResource } from './resources/e2ee.js';
-export type { E2eeDevice, E2eeDevicesRealtimeEvent, E2eeEnvelope, E2eeEvent, E2eeHasDependentsDetails, E2eeKeyPackageStatus, E2eeLink, E2eeLinkCancelledBy, E2eeLinkProgress, E2eeLinkRealtimeEvent, E2eeLinkState, E2eeObjectDownload, E2eeObjectUpload, E2eeRealtimeEvent, E2eeRevokeResponse, E2eeStatus, E2eeStatusReason, } from './resources/e2ee.js';
+export type { E2eeAccountReset, E2eeDevice, E2eeDevicesRealtimeEvent, E2eeEnvelope, E2eeEvent, E2eeHasDependentsDetails, E2eeKeyPackageStatus, E2eeLink, E2eeLinkCancelledBy, E2eeLinkProgress, E2eeLinkRealtimeEvent, E2eeLinkState, E2eeObjectDownload, E2eeObjectUpload, E2eeRealtimeEvent, E2eeResetCodeSent, E2eeResetErrorCode, E2eeRevokeResponse, E2eeStatus, E2eeStatusReason, } from './resources/e2ee.js';
 export { ProjectsResource } from './resources/projects.js';
 export { AgentsResource, SUPPORTED_MODELS } from './resources/agents.js';
 export { EvidenceResource } from './resources/evidence.js';
 export type { EvidenceTarget, EvalType, CreateEvalInput, SimulateInput, SimulateResult, EvalRunRow, EvalResultRow, EvalRunDetail, EvidenceSummary, EvidenceEvent, EvidenceRecordDetail } from './resources/evidence.js';
-export type { AgentMessage, AgentMessageInput, AgentInboxParams, SupportedModel, SalesLead, SalesLeadListParams, SalesLeadStatus } from './resources/agents.js';
+export type { AgentMessage, AgentMessageInput, AgentInboxParams, AgentAskInput, AgentAskResult, SupportedModel, SalesLead, SalesLeadListParams, SalesLeadStatus } from './resources/agents.js';
 export { TagsResource } from './resources/tags.js';
 export { SandboxResource } from './resources/sandbox.js';
 export { ProfilesResource } from './resources/profiles.js';
@@ -173,6 +174,7 @@ export { InviteCodesResource } from './resources/invite-codes.js';
 export { InviteCodesAdminResource } from './resources/invite-codes-admin.js';
 export { AdminResource } from './resources/admin.js';
 export { EmailResource } from './resources/email.js';
+export type { SendEmailInput, SendEmailResult, SendEmailMessage } from './resources/email.js';
 export { StorageResource } from './resources/storage.js';
 export { DatabasesResource } from './resources/databases.js';
 export { EnvVarsResource } from './resources/env-vars.js';
@@ -194,7 +196,7 @@ export type { CuratorSource, CuratorPrompt, CuratorRunInput, CuratorRunResult, C
 export { ReportsResource } from './resources/reports.js';
 export type { ReportTargetType, ReportStatus, CreateReportInput, ReportRecord, ResolveReportInput, } from './resources/reports.js';
 export { ModerationResource } from './resources/moderation.js';
-export type { ModerationTargetType, ModerationActionType, ModerationAppealStatus, ModerationPrinciple, PublicModerationAction, PublicModerationLog, OwnModerationAppeal, OwnModerationAction, OwnModerationLog, ApplyModerationActionInput, } from './resources/moderation.js';
+export type { ModerationTargetType, ModerationActionType, ModerationAppealStatus, ModerationPrinciple, PublicModerationAction, PublicModerationLog, OwnModerationAppeal, OwnModerationAction, OwnModerationLog, ApplyModerationActionInput, AgentModerationMode, AgentModerationGrant, } from './resources/moderation.js';
 export { LinkPreviewResource } from './resources/link-preview.js';
 export { SEARCH_SECTIONS, SearchResource } from './resources/search.js';
 export type { SearchAnswer, SearchGroup, SearchOmitReason, SearchParams, SearchPerson, SearchRelated, SearchResponse, SearchSection, SearchStory, SearchTopic } from './resources/search.js';
@@ -214,8 +216,8 @@ export type { LinkedTokenWallet, PayoutState, TokenBalance, TokenLedgerEntry } f
 export { BoostsResource } from './resources/boosts.js';
 export type { BoostBalance, BoostBalanceResponse, BoostCampaign, BoostCampaignResponse, BoostEventResult, BoostLedgerEntry, BoostLedgerKind, BoostPlanCredit, BoostRejectionReason, BoostReviewStatus, BoostStatus, BoostTopupCheckout, BoostTopupConfirmation, BoostTopupLimits, } from './resources/boosts.js';
 export { ProtocolsResource } from './resources/protocols.js';
-export { PROTOCOL_ADAPTER_MATURITIES, PROTOCOL_CAPABILITY_OPERATIONS, PROTOCOL_CAPABILITY_STATUSES, } from './resources/protocols.js';
-export type { SocialProfile, SocialSubscription, SocialSubscriptionChange, SocialProfilePage, SocialRadar, SocialRadarCluster, SocialRadarMember, SocialRadarParams, SocialRadarPosts, SocialRadarStory, SocialRadarStoryArchive, SocialNetwork, SocialPost, SocialConversation, SocialTrend, SocialTrendProvenance, SocialTrends, SocialTrendSourceIndex, SocialTrendFeed, SocialPopularProfiles, SocialAuthorFeed, SocialFollowingFeed, SocialFollowingSource, SearchPublicProfilesParams, SearchPublicPostsParams, SocialPostSearch, HostedProtocolConnections, HostedProtocol, HostedProtocolIdentity, HostedNostrChallenge, HostedNostrIdentityProof, NativeNostrPrepareInput, NativeNostrPrepared, NativeNostrAccount, NativeNostrPostState, NativeNostrReceipt, NativeSocialProtocol, FederationIdentity, FederationIdentityView, NativeSocialAccount, NativeSocialCallbackInput, NativeReplyPrepareInput, NativePostPrepareInput, NativeMediaInput, NativeMediaItem, NativePostBatch, NativePostHistory, NativeDelegatedPostHistoryItem, NativeNostrPostHistoryItem, NativeFollowSourceInput, NativeFollowPrepareInput, NativeFollowTarget, NativeFollowReceipt, NativeFollowState, NativeFollowAccount, NativeFollowStates, NativeFollowReview, NativeLikeSourceInput, NativeRepostSourceInput, NativeLikePrepareInput, NativeRepostPrepareInput, NativeLikeTarget, NativeRepostTarget, NativeLikeReceipt, NativeRepostReceipt, NativeLikeState, NativeRepostState, NativeLikeReview, NativeRepostReview, NativeReplyReceipt, NativeReplyBatch, NativeReplyHistory, NativeDelegatedReplyHistoryItem, NativeNostrReplyResult, NativeNostrReplyHistoryItem, NativeReplyRemovalReceipt, NativeReplyRemovalPreview, SocialSourceRef, SocialSourceControl, SocialSourceControlDisplay, SocialSourceControlChange, HostedPostPreview, ConnectHostedIdentityInput, CreateHostedIdentityInput, CreatedHostedProtocolIdentity, PreviewHostedPostInput, PublishHostedPostInput, ListProtocolCandidatesParams, ProtocolAdapterMaturity, ProtocolAdapterMetadata, ProtocolCandidateListResponse, ProtocolCandidatePageMeta, ProtocolCapabilityOperation, ProtocolCapabilityStatus, ProtocolCollectionStatus, ProtocolIngestionReplayResult, ProtocolIngestionStatus, ProtocolQuarantinedCandidate, ProtocolRefreshResult, ProtocolSettings, ProtocolSettingsUpdateResult, ReplayProtocolIngestionJobInput, UpdateSettingsInput as UpdateProtocolSettingsInput, } from './resources/protocols.js';
+export { PROTOCOL_ADAPTER_MATURITIES, PROTOCOL_CAPABILITY_OPERATIONS, PROTOCOL_CAPABILITY_STATUSES, viralItemHasVideo, } from './resources/protocols.js';
+export type { SocialProfile, SocialBridge, SocialSubscription, SocialSubscriptionChange, SocialProfilePage, SocialRadar, SocialRadarCluster, SocialRadarMember, SocialRadarParams, SocialRadarPosts, SocialRadarStory, SocialRadarStoryArchive, ViralBaseline, ViralItem, ViralItemFields, ViralItemSpread, ViralItemVelocity, ViralLabel, ViralMindsCard, ViralMindsItem, ViralNetwork, ViralOpenProtocol, ViralProtocol, ViralProvider, ViralReadMeta, ViralReadParams, ViralReadResponse, ViralReadStatus, ViralRef, ViralSocialItem, SocialNetwork, SocialPost, SocialConversation, SocialTrend, SocialTrendProvenance, SocialTrends, SocialTrendSourceIndex, SocialTrendFeed, SocialPopularProfiles, SocialAuthorFeed, SocialFollowingFeed, SocialFollowingSource, SearchPublicProfilesParams, SearchPublicPostsParams, SocialPostSearch, HostedProtocolConnections, HostedProtocol, HostedProtocolIdentity, HostedNostrChallenge, HostedNostrIdentityProof, NativeNostrPrepareInput, NativeNostrPrepared, NativeNostrAccount, NativeNostrPostState, NativeNostrReceipt, NativeSocialProtocol, FederationIdentity, FederationIdentityView, NativeSocialAccount, NativeSocialCallbackInput, NativeReplyPrepareInput, NativePostPrepareInput, NativeMediaInput, NativeMediaItem, NativePostBatch, NativePostHistory, NativeDelegatedPostHistoryItem, NativeNostrPostHistoryItem, NativeFollowSourceInput, NativeFollowPrepareInput, NativeFollowTarget, NativeFollowReceipt, NativeFollowState, NativeFollowAccount, NativeFollowStates, NativeFollowReview, NativeLikeSourceInput, NativeRepostSourceInput, NativeLikePrepareInput, NativeRepostPrepareInput, NativeLikeTarget, NativeRepostTarget, NativeLikeReceipt, NativeRepostReceipt, NativeLikeState, NativeRepostState, NativeLikeReview, NativeRepostReview, NativeReplyReceipt, NativeReplyBatch, NativeReplyHistory, NativeDelegatedReplyHistoryItem, NativeNostrReplyResult, NativeNostrReplyHistoryItem, NativeReplyRemovalReceipt, NativeReplyRemovalPreview, SocialSourceRef, SocialSourceControl, SocialSourceControlDisplay, SocialSourceControlChange, HostedPostPreview, ConnectHostedIdentityInput, CreateHostedIdentityInput, CreatedHostedProtocolIdentity, PreviewHostedPostInput, PublishHostedPostInput, ListProtocolCandidatesParams, ProtocolAdapterMaturity, ProtocolAdapterMetadata, ProtocolCandidateListResponse, ProtocolCandidatePageMeta, ProtocolCapabilityOperation, ProtocolCapabilityStatus, ProtocolCollectionStatus, ProtocolIngestionReplayResult, ProtocolIngestionStatus, ProtocolQuarantinedCandidate, ProtocolRefreshResult, ProtocolSettings, ProtocolSettingsUpdateResult, ReplayProtocolIngestionJobInput, UpdateSettingsInput as UpdateProtocolSettingsInput, } from './resources/protocols.js';
 export { InboxResource } from './resources/inbox.js';
 export { NetworkResource } from './resources/network.js';
 export { SimulatorResource } from './resources/simulator.js';
@@ -240,7 +242,7 @@ export { TemplatesResource } from './resources/templates.js';
 export type { Template, CreateTemplateInput, UpdateTemplateInput, ListTemplatesParams } from './resources/templates.js';
 export { MediaResource } from './resources/media.js';
 export type { GenerateImageInput, GeneratedImage, ImageProvider } from './resources/media.js';
-export { RecursivError, AuthenticationError, AuthorizationError, LegacyHandoffError, NotFoundError, ValidationError, InsufficientCreditsError, RateLimitError, ConflictError, isActionRateLimitScope, } from './errors.js';
+export { RecursivError, AuthenticationError, AuthorizationError, LegacyHandoffError, NotFoundError, ValidationError, InsufficientCreditsError, RateLimitError, ConflictError, isActionRateLimitScope, EmailNotSentError, } from './errors.js';
 export type { RateLimitDetails } from './errors.js';
 export { parseSSE } from './lib/sse.js';
 export * from './lib/webhooks.js';

package/dist/index.js

@@ -1,6 +1,7 @@
 export * from './resources/discovery-learning.js';
 import { DiscoveryResource } from './resources/discovery.js';
 export * from './resources/discovery.js';
+export * from './feed-definition.js';
 import { HttpClient } from './client.js';
 import { AuthResource } from './resources/auth.js';
 import { PostsResource } from './resources/posts.js';
@@ -261,7 +262,7 @@ export { UploadsResource } from './resources/uploads.js';
 export { WalletResource } from './resources/wallet.js';
 export { BoostsResource } from './resources/boosts.js';
 export { ProtocolsResource } from './resources/protocols.js';
-export { PROTOCOL_ADAPTER_MATURITIES, PROTOCOL_CAPABILITY_OPERATIONS, PROTOCOL_CAPABILITY_STATUSES, } from './resources/protocols.js';
+export { PROTOCOL_ADAPTER_MATURITIES, PROTOCOL_CAPABILITY_OPERATIONS, PROTOCOL_CAPABILITY_STATUSES, viralItemHasVideo, } from './resources/protocols.js';
 export { InboxResource } from './resources/inbox.js';
 export { NetworkResource } from './resources/network.js';
 export { SimulatorResource } from './resources/simulator.js';
@@ -277,6 +278,6 @@ export { HumanInputResource } from './resources/human-input.js';
 export { SwarmsResource } from './resources/swarms.js';
 export { TemplatesResource } from './resources/templates.js';
 export { MediaResource } from './resources/media.js';
-export { RecursivError, AuthenticationError, AuthorizationError, LegacyHandoffError, NotFoundError, ValidationError, InsufficientCreditsError, RateLimitError, ConflictError, isActionRateLimitScope, } from './errors.js';
+export { RecursivError, AuthenticationError, AuthorizationError, LegacyHandoffError, NotFoundError, ValidationError, InsufficientCreditsError, RateLimitError, ConflictError, isActionRateLimitScope, EmailNotSentError, } from './errors.js';
 export { parseSSE } from './lib/sse.js';
 export * from './lib/webhooks.js';

package/dist/realtime.d.ts

@@ -1,6 +1,7 @@
 import type { Socket } from 'socket.io-client';
 import { HttpClient } from './client.js';
 import type { E2eeDevicesRealtimeEvent, E2eeLinkRealtimeEvent, E2eeRealtimeEvent } from './resources/e2ee.js';
+import type { ChatConversationEvent, ChatMembersEvent } from './types.js';
 export interface ChatMessageEvent {
     id: string;
     conversationId: string;
@@ -147,7 +148,8 @@ export declare class RealtimeClient {
      *
      * Server events include `notification`, `feed_update`,
      * `conversation_created`, `chat_message`, `chat_typing`, `agent_thinking`,
-     * `e2ee:event`, `e2ee:link` and `e2ee:devices`.
+     * `chat:members`, `chat:conversation`, `e2ee:event`, `e2ee:link` and
+     * `e2ee:devices`.
      */
     on<T = unknown>(event: string, listener: (payload: T) => void): () => void;
     /** Join a conversation room now, and again after every reconnect, until you leave it. */
@@ -159,6 +161,14 @@ export declare class RealtimeClient {
     onMessageDelete(callback: (msg: ChatMessageDeleteEvent) => void): (() => void) | undefined;
     onTyping(callback: (event: TypingEvent) => void): (() => void) | undefined;
     onAgentThinking(callback: (event: AgentThinkingEvent) => void): (() => void) | undefined;
+    /**
+     * A private group's people changed (0.7.59): `{ conversationId, change, userIds, actorId }`,
+     * change `added`, `removed`, `left` or `invites_cancelled`. Sent to everyone in the group
+     * and to the people it is about. Read the conversation again; in an encrypted group, check its keys.
+     */
+    onChatMembers(callback: (event: ChatMembersEvent) => void): () => void;
+    /** A private group was renamed (0.7.59): `{ conversationId, change: 'renamed', name, actorId }`. */
+    onChatConversation(callback: (event: ChatConversationEvent) => void): () => void;
     /**
      * The E2EE doorbell after each append to an encrypted conversation this
      * account belongs to: `{ conversationId, seq }`, plus the stored `event`

package/dist/realtime.js

@@ -369,7 +369,8 @@ export class RealtimeClient {
      *
      * Server events include `notification`, `feed_update`,
      * `conversation_created`, `chat_message`, `chat_typing`, `agent_thinking`,
-     * `e2ee:event`, `e2ee:link` and `e2ee:devices`.
+     * `chat:members`, `chat:conversation`, `e2ee:event`, `e2ee:link` and
+     * `e2ee:devices`.
      */
     on(event, listener) {
         // Every call is its own subscription, even for a function that is already
@@ -426,6 +427,18 @@ export class RealtimeClient {
     onAgentThinking(callback) {
         return this.on('agent_thinking', callback);
     }
+    /**
+     * A private group's people changed (0.7.59): `{ conversationId, change, userIds, actorId }`,
+     * change `added`, `removed`, `left` or `invites_cancelled`. Sent to everyone in the group
+     * and to the people it is about. Read the conversation again; in an encrypted group, check its keys.
+     */
+    onChatMembers(callback) {
+        return this.on('chat:members', callback);
+    }
+    /** A private group was renamed (0.7.59): `{ conversationId, change: 'renamed', name, actorId }`. */
+    onChatConversation(callback) {
+        return this.on('chat:conversation', callback);
+    }
     /**
      * The E2EE doorbell after each append to an encrypted conversation this
      * account belongs to: `{ conversationId, seq }`, plus the stored `event`

package/dist/resources/agents.d.ts

@@ -26,6 +26,68 @@ export interface AgentInboxParams {
     limit?: number;
     offset?: number;
 }
+export interface AgentAskInput {
+    organization_id: string;
+    /** The person whose agent you are asking: name, first name, @username, email or user id. */
+    owner: string;
+    question: string;
+    /** How far back to read their record (1-90, default 7). */
+    since_days?: number;
+    /** false = read the record only, leave nothing in their agent's inbox. */
+    deliver?: boolean;
+}
+export interface AgentAskResult {
+    owner: {
+        id: string;
+        name: string | null;
+        username: string | null;
+    };
+    agents: Array<{
+        id: string;
+        name: string;
+        client: string | null;
+    }>;
+    window: {
+        since: string;
+        days: number;
+    };
+    record: {
+        claims: Array<{
+            task_id: string;
+            task_title: string;
+            task_status: string;
+            agent: string;
+            claim_status: string;
+            claimed_at: string;
+            completed_at: string | null;
+            released_at: string | null;
+            release_reason: string | null;
+            notes: string | null;
+            context_handoff: string | null;
+            pr_urls: string[] | null;
+            commits: string[] | null;
+        }>;
+        decisions: Array<{
+            id: string;
+            decision: string;
+            context: string | null;
+            tags: string[] | null;
+            project_id: string | null;
+            created_at: string;
+        }>;
+    };
+    question: {
+        delivered: true;
+        message_id: string;
+        to_agent_id: string;
+        to_agent_name: string;
+        from_agent_id: string;
+    } | {
+        delivered: false;
+        reason: string;
+    };
+    how_to_answer: string;
+}
 export interface AgentLeaderboardParams extends PaginationParams {
     organization_id?: string;
 }
@@ -264,6 +326,14 @@ export declare class AgentsResource {
     }>>;
     /** Send a direct message to an agent */
     sendMessage(toAgentId: string, input: AgentMessageInput): Promise<SingleResponse<AgentMessage>>;
+    /**
+     * Ask a teammate's agent by naming its owner ("bill", "@ottman", an email).
+     * Returns that person's agents' work in the organization over the window
+     * (task claims with notes, handoffs, PRs and commits; decisions) and leaves
+     * the question in their agent's inbox; its reply arrives in yours as a
+     * `result` message with `metadata.in_reply_to`.
+     */
+    ask(input: AgentAskInput): Promise<SingleResponse<AgentAskResult>>;
     /** Get an agent's inbox (messages sent to them) */
     inbox(agentId: string, params?: AgentInboxParams): Promise<SingleResponse<AgentMessage[]>>;
     /** Get unread message count for an agent */

package/dist/resources/agents.js

@@ -172,6 +172,16 @@ export class AgentsResource {
     sendMessage(toAgentId, input) {
         return this.client.post(`/agents/${toAgentId}/messages`, input);
     }
+    /**
+     * Ask a teammate's agent by naming its owner ("bill", "@ottman", an email).
+     * Returns that person's agents' work in the organization over the window
+     * (task claims with notes, handoffs, PRs and commits; decisions) and leaves
+     * the question in their agent's inbox; its reply arrives in yours as a
+     * `result` message with `metadata.in_reply_to`.
+     */
+    ask(input) {
+        return this.client.post('/agents/ask', input);
+    }
     /** Get an agent's inbox (messages sent to them) */
     inbox(agentId, params) {
         return this.client.get(`/agents/${agentId}/inbox`, params);