@recursiv/sdk 0.7.66 → 0.7.68

package/README.md

@@ -94,7 +94,7 @@ for await (const chunk of r.agents.chatStream(agent.id, { message: 'Hello!' }))
 | Resource | Key methods |
 |----------|------------|
 | `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.bookmarks` | `save`, `unsave`, `posts`, `list`, `keys`, `merge` — the member's saved posts, open-network posts and articles, synced across devices; `collections`: `list`, `create`, `update`, `remove`, `add`, `removeItem`, `items`, `posts` — private named collections of saves (0.7.68, where `network.getConfig()` advertises `capabilities.bookmark_collections`) |
 | `r.feeds` | `top` (what the member is most likely to engage with, rotated by what they saw, with open-network lanes and the lead story), `stories` (the story tail), `publicTop` (a visitor's top, keyless and edge-cacheable) |
 | `r.communities` | `create`, `join`, `search`, `members` |
 | `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) |
@@ -732,7 +732,13 @@ The catalog lists `compass_filter` on every network when the filter is served to
 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`.
+`meta.compass_filter`. These reads answer a side or Mix unfiltered, marked `unavailable`. Every radar story and every
+World Today story (`curator.today()`) carries `political`: true when a quarter of its judged posts are politics, its
+theme or topic is politics, or its headline or summary names an election, a war or troop deployment, a court or justice,
+a legislature, or a party or politician. Hide politics leaves those out whatever their theme, on the radar and on
+`curator.today({ compass: 'hide' })`, where the next story then leads. The stories of `feeds.stories()` and the lead of
+`feeds.top()` carry `political` too (0.7.67), and those reads and `curator.forYouWorld()` leave political stories out
+under Hide politics.
 
 `sdk.discovery.recommendations({ kind, category?, limit?, session?, exclude? })` is
 the app's one recommender for suggestion rails: `kind` is `member`, `group`, `tag`,

package/dist/index.d.ts

@@ -195,7 +195,7 @@ export { VideoResource } from './resources/video.js';
 export type { VideoUploadCreds, CreateVideoUploadResult, VideoStatusInfo, VideoPlaybackToken, VideoEntitlement, } from './resources/video.js';
 export { AppSubscriptionsResource } from './resources/app-subscriptions.js';
 export type { AppSubscriptionBoostCredit, AppSubscriptionCheckoutResult, AppSubscriptionPortalResult, AppSubscriptionStatusResult, AppSubscriptionTierChangePreview, AppSubscriptionTierChangeResult, } from './resources/app-subscriptions.js';
-export type { CuratorSource, CuratorPrompt, CuratorRunInput, CuratorRunResult, CuratorTodayEdition, CuratorTodayExcerpt, CuratorTodayLeadImage, CuratorTodayRadar, CuratorTodayReaction, CuratorTodayResponse, CuratorTodaySource, CuratorTodayStory, ForYouMeta, ForYouParams, ForYouSurface, ForYouWorldBlock, ForYouWorldBlockType, ForYouWorldCategoryShortcut, ForYouWorldItem, ForYouWorldMeta, ForYouWorldParams, ForYouWorldPart, ForYouWorldResponse, ForYouWorldStory, ForYouWorldStoryTarget, ForYouWorldViral, } from './resources/curator.js';
+export type { CuratorSource, CuratorPrompt, CuratorRunInput, CuratorRunResult, CuratorTodayEdition, CuratorTodayExcerpt, CuratorTodayLeadImage, CuratorTodayParams, CuratorTodayRadar, CuratorTodayReaction, CuratorTodayResponse, CuratorTodaySource, CuratorTodayStory, ForYouMeta, ForYouParams, ForYouSurface, ForYouWorldBlock, ForYouWorldBlockType, ForYouWorldCategoryShortcut, ForYouWorldItem, ForYouWorldMeta, ForYouWorldParams, ForYouWorldPart, ForYouWorldResponse, ForYouWorldStory, ForYouWorldStoryTarget, ForYouWorldViral, } from './resources/curator.js';
 export { ReportsResource } from './resources/reports.js';
 export type { ReportTargetType, ReportStatus, CreateReportInput, ReportRecord, ResolveReportInput, } from './resources/reports.js';
 export { ModerationResource } from './resources/moderation.js';
@@ -203,10 +203,10 @@ export type { ModerationTargetType, ModerationActionType, ModerationAppealStatus
 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';
-export { BOOKMARK_MERGE_MAX_ITEMS, BookmarksResource } from './resources/bookmarks.js';
+export { BOOKMARK_MERGE_MAX_ITEMS, BookmarkCollectionsResource, BookmarksResource } from './resources/bookmarks.js';
 export { FEED_TOP_NETWORKS, FeedsResource } from './resources/feeds.js';
 export type { FeedStoriesParams, FeedStoriesResponse, FeedStory, FeedTopExplain, FeedTopItem, FeedTopMeta, FeedTopNetwork, FeedTopNetworkCard, FeedTopNetworkEntry, FeedTopParams, FeedTopResponse, FeedTopTarget, PublicFeedTopMeta, PublicFeedTopParams, PublicFeedTopResponse, } from './resources/feeds.js';
-export type { BookmarkedPost, BookmarkInput, BookmarkItem, BookmarkKey, BookmarkKeyRow, BookmarkKind, BookmarkMergeItem, BookmarkMergeResult, BookmarkProtocol, BookmarkRequestOptions, BookmarksPage, SavedBookmark, UnsavedBookmark, } from './resources/bookmarks.js';
+export type { BookmarkCollection, BookmarkCollectionInput, BookmarkCollectionKind, BookmarkCollectionPatch, BookmarkCollectionsList, BookmarkCollectionTarget, BookmarkCollectionVisibility, BookmarkedPost, BookmarkInput, BookmarkItem, BookmarkKey, BookmarkKeyRow, BookmarkKeysPage, BookmarkKind, BookmarkMergeItem, BookmarkMergeResult, BookmarkProtocol, BookmarkRequestOptions, BookmarksPage, FiledBookmark, RemovedBookmarkCollection, SavedBookmark, UnfiledBookmark, UnsavedBookmark, } from './resources/bookmarks.js';
 export { AccountsResource } from './resources/accounts.js';
 export type { SiblingAccount, SiblingAccountsResponse, SwitchAccountResult, } from './resources/accounts.js';
 export type { LinkPreview, LinkPreviewResponse, } from './resources/link-preview.js';

package/dist/index.js

@@ -257,7 +257,7 @@ export { ReportsResource } from './resources/reports.js';
 export { ModerationResource } from './resources/moderation.js';
 export { LinkPreviewResource } from './resources/link-preview.js';
 export { SEARCH_SECTIONS, SearchResource } from './resources/search.js';
-export { BOOKMARK_MERGE_MAX_ITEMS, BookmarksResource } from './resources/bookmarks.js';
+export { BOOKMARK_MERGE_MAX_ITEMS, BookmarkCollectionsResource, BookmarksResource } from './resources/bookmarks.js';
 export { FEED_TOP_NETWORKS, FeedsResource } from './resources/feeds.js';
 export { AccountsResource } from './resources/accounts.js';
 export { OrganizationSettingsResource } from './resources/organization-settings.js';

package/dist/resources/bookmarks.d.ts

@@ -122,6 +122,83 @@ export interface BookmarksPage<T> extends PaginatedResponse<T> {
         next_cursor: string | null;
     };
 }
+/** A page of saved keys. `collections` (0.7.68) is there only where the server serves collections. */
+export interface BookmarkKeysPage extends BookmarksPage<BookmarkKeyRow> {
+    /**
+     * For this page's keys that are filed somewhere: the ids of the collections each sits in, oldest
+     * collection first. A key filed nowhere is absent. The whole field is absent while collections are
+     * off on the server, so its presence also says collections can be used.
+     */
+    collections?: Record<BookmarkKey, string[]>;
+}
+/** What a collection holds. Before the cutover only `posts` collections are made (any saved thing: posts, open-network posts, articles). */
+export type BookmarkCollectionKind = 'posts' | 'accounts' | 'tags';
+/** Who may see a collection. Before the cutover every collection is `private`. */
+export type BookmarkCollectionVisibility = 'private' | 'unlisted' | 'public';
+/** A member's named collection of saves in this app (0.7.68). Collections are labels on saves. */
+export interface BookmarkCollection {
+    id: string;
+    kind: BookmarkCollectionKind;
+    /** Unique per member and app: lowercase letters and digits joined by hyphens, at most 64 characters. */
+    slug: string;
+    /** At most 120 characters. */
+    title: string;
+    /** At most 500 characters. */
+    description: string | null;
+    visibility: BookmarkCollectionVisibility;
+    item_count: number;
+    created_at: string;
+    updated_at: string;
+}
+export interface BookmarkCollectionsList {
+    /** Oldest first. */
+    data: BookmarkCollection[];
+    /** The most collections one member keeps in this app, and the most things one collection holds. */
+    meta: {
+        max_collections: number;
+        max_items: number;
+    };
+}
+/** A new collection. Without `slug` one is made from the title (made unique with -2, -3, ...). */
+export interface BookmarkCollectionInput {
+    title: string;
+    description?: string | null;
+    slug?: string;
+}
+/** Any of a collection's title, description (null clears it) and slug. */
+export interface BookmarkCollectionPatch {
+    title?: string;
+    description?: string | null;
+    slug?: string;
+}
+export interface RemovedBookmarkCollection {
+    id: string;
+    removed: boolean;
+}
+export interface FiledBookmark {
+    collection_id: string;
+    /** The saved thing's key. A bare repost is filed as its original, as saving one is: use this key and `post_id`. */
+    key: BookmarkKey;
+    filed: true;
+    /** False when it was already in the collection: nothing changed. */
+    created: boolean;
+    /** True when filing it saved it too. */
+    saved_now: boolean;
+    added_at: string;
+    item_count: number;
+    post_id?: string;
+}
+export interface UnfiledBookmark {
+    collection_id: string;
+    key: BookmarkKey;
+    filed: false;
+    /** False when it was not in the collection. It stays saved either way. */
+    removed: boolean;
+}
+/** What to file: a saved key, a Minds post, or an item (saved first if it is not saved yet). */
+export type BookmarkCollectionTarget = BookmarkKey | {
+    postId: string;
+} | BookmarkInput;
 /** Most items one `merge` call takes. */
 export declare const BOOKMARK_MERGE_MAX_ITEMS = 200;
 /**
@@ -131,6 +208,56 @@ export declare const BOOKMARK_MERGE_MAX_ITEMS = 200;
 export interface BookmarkRequestOptions {
     retry?: boolean;
 }
+/**
+ * Bookmark collections (0.7.68): the member's private, named labels on their saves in this app.
+ * Filing something saves it first; one saved thing can sit in several collections; unsaving it takes it
+ * out of every one; deleting a collection leaves everything it held saved.
+ *
+ * Off on a server until it advertises `capabilities.bookmark_collections` (`network.getConfig()`): until
+ * then, and until its tables are applied, every call rejects with a 503 whose code is `lists_unavailable`
+ * (saving still works). A collection that is not the member's is 404 `collection_not_found`. Caps: 409
+ * `collection_limit` (collections per member) and `collection_item_limit` (things per collection).
+ */
+export declare class BookmarkCollectionsResource {
+    private client;
+    constructor(client: HttpClient);
+    /** The member's collections in this app, oldest first, with the caps. */
+    list(options?: BookmarkRequestOptions): Promise<BookmarkCollectionsList>;
+    /**
+     * Make a private collection. 409 `slug_taken` for a slug the member already uses. Retried on a 5xx like any
+     * POST: pass an `idempotencyKey` so a retry cannot make a second collection.
+     */
+    create(input: BookmarkCollectionInput, options?: BookmarkRequestOptions & {
+        idempotencyKey?: string;
+    }): Promise<SingleResponse<BookmarkCollection>>;
+    /** Rename, re-describe or re-slug a collection. */
+    update(collectionId: string, patch: BookmarkCollectionPatch): Promise<SingleResponse<BookmarkCollection>>;
+    /** Delete a collection. Idempotent; what it held stays saved. */
+    remove(collectionId: string, options?: BookmarkRequestOptions): Promise<SingleResponse<RemovedBookmarkCollection>>;
+    /**
+     * File something in a collection; idempotent. A key or `{ postId }` files what is saved, and a Minds post is
+     * saved first when it is not (404 `post_not_found` if the member cannot read it); a key alone that is not saved
+     * is 409 `not_saved`. An item (a Minds post, open-network post or article) goes in one request that saves it if
+     * it is not saved and files it together: when the collection is missing (404), full (409 `collection_item_limit`)
+     * or unavailable (503), or the member's saves are at their cap (409 `bookmark_limit`), nothing is saved.
+     */
+    add(collectionId: string, target: BookmarkCollectionTarget, options?: BookmarkRequestOptions): Promise<SingleResponse<FiledBookmark>>;
+    /** Take something out of a collection. Idempotent; it stays saved, and in any other collection. */
+    removeItem(collectionId: string, target: BookmarkKey | {
+        postId: string;
+    }, options?: BookmarkRequestOptions): Promise<SingleResponse<UnfiledBookmark>>;
+    /** The open-network posts and articles filed in a collection, newest saved first. Page on `meta.next_cursor`. */
+    items(collectionId: string, params?: {
+        kind?: 'social' | 'article';
+        limit?: number;
+        cursor?: string;
+    }, options?: BookmarkRequestOptions): Promise<BookmarksPage<BookmarkItem>>;
+    /** The Minds posts filed in a collection, newest saved first, hydrated like the feed. Page on `meta.next_cursor`. */
+    posts(collectionId: string, params?: {
+        limit?: number;
+        cursor?: string;
+    }, options?: BookmarkRequestOptions): Promise<BookmarksPage<BookmarkedPost>>;
+}
 /**
  * Synced bookmarks: the signed-in member's saved Minds posts, open-network posts and articles in this app,
  * across every device they sign in on. Private to the member; needs the member's own app key.
@@ -140,6 +267,8 @@ export interface BookmarkRequestOptions {
  */
 export declare class BookmarksResource {
     private client;
+    /** Named collections of the member's saves (0.7.68). */
+    readonly collections: BookmarkCollectionsResource;
     constructor(client: HttpClient);
     /** Save one item. Idempotent: saving what is saved changes nothing. 409 `bookmark_limit` past the member's limit. */
     save(item: BookmarkInput, options?: BookmarkRequestOptions): Promise<SingleResponse<SavedBookmark>>;
@@ -147,22 +276,27 @@ export declare class BookmarksResource {
     unsave(target: BookmarkKey | {
         postId: string;
     }, options?: BookmarkRequestOptions): Promise<SingleResponse<UnsavedBookmark>>;
-    /** Saved Minds posts, newest saved first, hydrated like the feed. Page on `meta.next_cursor`. */
+    /** Saved Minds posts, newest saved first, hydrated like the feed; `collection` narrows to one collection (0.7.68). Page on `meta.next_cursor`. */
     posts(params?: {
         limit?: number;
         cursor?: string;
+        collection?: string;
     }, options?: BookmarkRequestOptions): Promise<BookmarksPage<BookmarkedPost>>;
-    /** Saved open-network posts and articles, newest saved first. Page on `meta.next_cursor`. */
+    /** Saved open-network posts and articles, newest saved first; `collection` narrows to one collection (0.7.68). Page on `meta.next_cursor`. */
     list(params?: {
         kind?: 'social' | 'article';
         limit?: number;
         cursor?: string;
+        collection?: string;
     }, options?: BookmarkRequestOptions): Promise<BookmarksPage<BookmarkItem>>;
-    /** Every saved key (hidden posts included), newest saved first, up to 500 a page. For a saved-state cache. */
+    /**
+     * Every saved key (hidden posts included), newest saved first, up to 500 a page. For a saved-state cache.
+     * Where collections are served, `collections` says which collections this page's keys are filed in.
+     */
     keys(params?: {
         limit?: number;
         cursor?: string;
-    }, options?: BookmarkRequestOptions): Promise<BookmarksPage<BookmarkKeyRow>>;
+    }, options?: BookmarkRequestOptions): Promise<BookmarkKeysPage>;
     /**
      * Upload a device's saves, e.g. when its member signs in: at most 200 items a call. Idempotent (a second
      * merge of the same items is a no-op); invalid items and posts the member cannot read are `skipped`, and

package/dist/resources/bookmarks.js

@@ -1,5 +1,68 @@
 /** Most items one `merge` call takes. */
 export const BOOKMARK_MERGE_MAX_ITEMS = 200;
+const itemPath = (collectionId, key) => `/bookmarks/collections/${encodeURIComponent(collectionId)}/items/${encodeURIComponent(key)}`;
+/**
+ * Bookmark collections (0.7.68): the member's private, named labels on their saves in this app.
+ * Filing something saves it first; one saved thing can sit in several collections; unsaving it takes it
+ * out of every one; deleting a collection leaves everything it held saved.
+ *
+ * Off on a server until it advertises `capabilities.bookmark_collections` (`network.getConfig()`): until
+ * then, and until its tables are applied, every call rejects with a 503 whose code is `lists_unavailable`
+ * (saving still works). A collection that is not the member's is 404 `collection_not_found`. Caps: 409
+ * `collection_limit` (collections per member) and `collection_item_limit` (things per collection).
+ */
+export class BookmarkCollectionsResource {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    /** The member's collections in this app, oldest first, with the caps. */
+    list(options) {
+        return this.client.get('/bookmarks/collections', undefined, options);
+    }
+    /**
+     * Make a private collection. 409 `slug_taken` for a slug the member already uses. Retried on a 5xx like any
+     * POST: pass an `idempotencyKey` so a retry cannot make a second collection.
+     */
+    create(input, options) {
+        return this.client.post('/bookmarks/collections', input, options);
+    }
+    /** Rename, re-describe or re-slug a collection. */
+    update(collectionId, patch) {
+        return this.client.patch(`/bookmarks/collections/${encodeURIComponent(collectionId)}`, patch);
+    }
+    /** Delete a collection. Idempotent; what it held stays saved. */
+    remove(collectionId, options) {
+        return this.client.delete(`/bookmarks/collections/${encodeURIComponent(collectionId)}`, options);
+    }
+    /**
+     * File something in a collection; idempotent. A key or `{ postId }` files what is saved, and a Minds post is
+     * saved first when it is not (404 `post_not_found` if the member cannot read it); a key alone that is not saved
+     * is 409 `not_saved`. An item (a Minds post, open-network post or article) goes in one request that saves it if
+     * it is not saved and files it together: when the collection is missing (404), full (409 `collection_item_limit`)
+     * or unavailable (503), or the member's saves are at their cap (409 `bookmark_limit`), nothing is saved.
+     */
+    add(collectionId, target, options) {
+        if (typeof target === 'string')
+            return this.client.put(itemPath(collectionId, target), undefined, options);
+        if ('postId' in target)
+            return this.client.put(itemPath(collectionId, `post:${target.postId}`), undefined, options);
+        return this.client.post(`/bookmarks/collections/${encodeURIComponent(collectionId)}/items`, target, options);
+    }
+    /** Take something out of a collection. Idempotent; it stays saved, and in any other collection. */
+    removeItem(collectionId, target, options) {
+        const key = typeof target === 'string' ? target : `post:${target.postId}`;
+        return this.client.delete(itemPath(collectionId, key), options);
+    }
+    /** The open-network posts and articles filed in a collection, newest saved first. Page on `meta.next_cursor`. */
+    items(collectionId, params, options) {
+        return this.client.get('/bookmarks', { ...params, collection: collectionId }, options);
+    }
+    /** The Minds posts filed in a collection, newest saved first, hydrated like the feed. Page on `meta.next_cursor`. */
+    posts(collectionId, params, options) {
+        return this.client.get('/posts', { bookmarked: true, ...params, collection: collectionId }, options);
+    }
+}
 /**
  * Synced bookmarks: the signed-in member's saved Minds posts, open-network posts and articles in this app,
  * across every device they sign in on. Private to the member; needs the member's own app key.
@@ -9,8 +72,11 @@ export const BOOKMARK_MERGE_MAX_ITEMS = 200;
  */
 export class BookmarksResource {
     client;
+    /** Named collections of the member's saves (0.7.68). */
+    collections;
     constructor(client) {
         this.client = client;
+        this.collections = new BookmarkCollectionsResource(client);
     }
     /** Save one item. Idempotent: saving what is saved changes nothing. 409 `bookmark_limit` past the member's limit. */
     save(item, options) {
@@ -21,15 +87,18 @@ export class BookmarksResource {
         const key = typeof target === 'string' ? target : `post:${target.postId}`;
         return this.client.delete(`/bookmarks/${encodeURIComponent(key)}`, options);
     }
-    /** Saved Minds posts, newest saved first, hydrated like the feed. Page on `meta.next_cursor`. */
+    /** Saved Minds posts, newest saved first, hydrated like the feed; `collection` narrows to one collection (0.7.68). Page on `meta.next_cursor`. */
     posts(params, options) {
         return this.client.get('/posts', { bookmarked: true, ...params }, options);
     }
-    /** Saved open-network posts and articles, newest saved first. Page on `meta.next_cursor`. */
+    /** Saved open-network posts and articles, newest saved first; `collection` narrows to one collection (0.7.68). Page on `meta.next_cursor`. */
     list(params, options) {
         return this.client.get('/bookmarks', params, options);
     }
-    /** Every saved key (hidden posts included), newest saved first, up to 500 a page. For a saved-state cache. */
+    /**
+     * Every saved key (hidden posts included), newest saved first, up to 500 a page. For a saved-state cache.
+     * Where collections are served, `collections` says which collections this page's keys are filed in.
+     */
     keys(params, options) {
         return this.client.get('/bookmarks/keys', params, options);
     }

package/dist/resources/curator.d.ts

@@ -344,6 +344,12 @@ export interface CuratorTodayStory {
     headline: string;
     dek: string | null;
     topic: string | null;
+    /**
+     * Whether the story is political: its headline, dek or topic names an election, a war or troop deployment, a court or
+     * justice, a legislature, or a party or politician, or the radar story it seeded is political. Hide politics
+     * (`today({ compass: 'hide' })`) leaves these out. Absent from a server before it was served.
+     */
+    political?: boolean;
     /** Outlet links for a world story; null for a Minds story. */
     sources: CuratorTodaySource[] | null;
     /** Distinct outlets behind a world story; null for a Minds story. */
@@ -380,10 +386,22 @@ export interface CuratorTodayEdition {
 export interface CuratorTodayResponse {
     /** null when the network has no published edition yet. */
     data: CuratorTodayEdition | null;
+    /**
+     * `compass_filter`: present when the read named a filtering `compass`: what Hide politics did to the stories (counts
+     * only), or status 'unavailable' when it was not applied (not served to this reader yet, or a side or Mix).
+     */
     meta: {
         generating: boolean;
+        compass_filter?: CompassFilterMeta;
     };
 }
+export interface CuratorTodayParams {
+    /**
+     * A Politics choice. Hide politics (`hide`) leaves out the political stories (CuratorTodayStory.political), and the
+     * next story leads. Any other choice is answered unfiltered, marked `unavailable`.
+     */
+    compass?: string;
+}
 export declare class CuratorResource {
     private client;
     constructor(client: HttpClient);
@@ -392,7 +410,7 @@ export declare class CuratorResource {
      * (set by the open web, ranked by outlet count) come first; Minds
      * conversation stories follow. Requires `posts:read`.
      */
-    today(): Promise<CuratorTodayResponse>;
+    today(params?: CuratorTodayParams): Promise<CuratorTodayResponse>;
     /**
      * Fetch the supplied sources in parallel, annotate each top item with
      * the supplied prompt template, and insert audience-scoped posts into

package/dist/resources/curator.js

@@ -8,8 +8,8 @@ export class CuratorResource {
      * (set by the open web, ranked by outlet count) come first; Minds
      * conversation stories follow. Requires `posts:read`.
      */
-    today() {
-        return this.client.get('/curator/today');
+    today(params = {}) {
+        return params.compass ? this.client.get('/curator/today', { compass: params.compass }) : this.client.get('/curator/today');
     }
     /**
      * Fetch the supplied sources in parallel, annotate each top item with

package/dist/resources/feeds.d.ts

@@ -97,6 +97,12 @@ export interface FeedStory {
     kind: 'breaking' | 'viral' | 'story';
     breaking: boolean;
     theme: string | null;
+    /**
+     * Whether the story is political whatever its theme: its headline names an election, a war or troop deployment, a
+     * court or justice, a legislature, or a party or politician, its theme is politics, or a quarter of its judged posts
+     * are politics. Hide politics (`compass: 'hide'`) leaves such a story out. Absent from a server older than 0.7.67.
+     */
+    political?: boolean;
     sources: Partial<Record<'outlet' | 'hackernews' | 'bluesky' | 'activitypub' | 'nostr' | 'minds', number>>;
     media: {
         images: number;

package/dist/resources/network.d.ts

@@ -7,8 +7,14 @@ interface NetworkConfig {
     primary_color: string | null;
     theme: string | null;
     features: Record<string, unknown>;
+    /**
+     * `bookmark_collections` (0.7.68; absent on older servers): this server serves bookmark collections
+     * (`bookmarks.collections`). Show collections only when it is true, and still treat a 503
+     * `lists_unavailable` as off.
+     */
     capabilities: {
         ws_token: boolean;
+        bookmark_collections?: boolean;
     };
     auth_methods: string;
     default_template_name: string | null;

package/dist/resources/protocols.d.ts

@@ -1206,6 +1206,12 @@ export interface SocialRadarCluster {
     };
     /** A browse-category id or `mixed`, from cached judgments only. */
     theme?: string;
+    /**
+     * Whether the story is political, whatever its theme: a quarter or more of its judged posts are politics, its theme is
+     * politics, or its headline or summary names an election, a war or troop deployment, a court or justice, a legislature,
+     * or a party or politician. Hide politics (`compass: 'hide'`) leaves these out. Absent from a server before it was served.
+     */
+    political?: boolean;
     sources: Partial<Record<SocialRadarSourceKind, number>>;
     corroboration: number;
     laneMix: {
@@ -1266,8 +1272,9 @@ export interface SocialRadarParams {
     category?: string;
     limit?: number;
     /**
-     * A Politics choice. Hide politics (`hide`) leaves out the stories whose theme is politics, and the ones not themed yet
-     * or themed `mixed` (a story has no compass placement, so it fails closed); the stories after them fill the list.
+     * A Politics choice. Hide politics (`hide`) leaves out the political stories (SocialRadarCluster.political) whatever
+     * their theme, and the ones not themed yet or themed `mixed` (a story has no compass placement, so it fails closed);
+     * the stories after them fill the list.
      * A side or Mix is answered unfiltered, marked `unavailable`; the keyless `getSharedRadar` takes only `all` or `hide`.
      */
     compass?: string;
@@ -1281,7 +1288,7 @@ export interface SocialRadarPosts {
 /** A story that has left the radar, as the radar's story archive keeps it (up to 30 days after it was last on the radar). */
 export interface SocialRadarStoryArchive {
     /** The story as the radar last published it. Articles keep their headline and link; a post is a member by reference only (no `title`). */
-    cluster: Pick<SocialRadarCluster, 'id' | 'label' | 'kind' | 'seed' | 'theme' | 'sources' | 'laneMix'> & {
+    cluster: Pick<SocialRadarCluster, 'id' | 'label' | 'kind' | 'seed' | 'theme' | 'political' | 'sources' | 'laneMix'> & {
         members: Array<Pick<SocialRadarMember, 'kind' | 'key' | 'url' | 'publishedAt' | 'outlet'> & {
             title?: string;
         }>;

package/dist/types.d.ts

@@ -698,6 +698,20 @@ export interface Conversation {
     /** Whether `chat.leave()` is allowed for the caller. */
     can_leave?: boolean;
     created_at: string;
+    /**
+     * When the conversation last had activity, the time `conversations()` sorts
+     * by (0.7.67): its newest message, or, in an end-to-end encrypted
+     * (`mls_v2`) conversation, the relay's receive time of its newest encrypted
+     * message when that is later; its creation when it has no messages.
+     * In an `mls_v2` conversation, membership and key changes and quiet events
+     * (a reaction, an edit, a delete) do not move it. In any other
+     * conversation it is read from the messages there now, so deleting the
+     * newest message moves it back, to the previous message or to the
+     * creation: do not keep the later of a cached and a served value. A time
+     * only, never content, so a device that cannot read an encrypted chat can
+     * still show when it last moved. Omitted by older APIs.
+     */
+    last_activity_at?: string;
 }
 export interface ConversationRequestResult {
     id: string;
@@ -733,6 +747,12 @@ export interface ConversationDetail {
     /** Whether `chat.leave()` is allowed for the caller. */
     can_leave?: boolean;
     created_at: string;
+    /**
+     * As `Conversation.last_activity_at` (0.7.67). Served by `conversation()`;
+     * omitted by `createGroup()`, to a member who declined the request, and by
+     * older APIs.
+     */
+    last_activity_at?: string;
 }
 export type ChatMemberRole = 'admin' | 'member';
 /**

package/llm.md

@@ -504,6 +504,8 @@ Scroll back with `messages(id, { cursor: page.meta.next_cursor })`, not a growin
 
 Private groups (0.7.59): each member has `role` (`admin` or `member`) and, in a group or a one-on-one chat, `request_status`: `accepted` from the start for the person who wrote, anyone who follows them and agents, else `pending` until that person accepts or replies (a decline reads `pending` to anyone else), so `accepted` alone does not mean they accepted anything. Only the admin (the creator, then the longest-standing person left) may `addMembers(id, { member_ids })`, `removeMember(id, userId)` and `updateGroup(id, { name })` (else 403 `not_admin`). `createGroup({ name, member_ids, encrypted: true, device_id? })` makes an end-to-end encrypted group of people in the pilot, at most 8 counting pending invitees, or throws 409 `conversation_not_eligible` with `details.reason` and creates nothing. `r.realtime.onChatMembers` / `onChatConversation` tell you when people or the name change.
 
+Activity time (0.7.67): conversation rows, `communityConversation()` and `conversation(id)` carry `last_activity_at`, the time `conversations()` sorts by: the newest message, or, in an end-to-end encrypted (`mls_v2`) conversation, the relay's receive time of its newest encrypted message when that is later (membership and key changes and quiet events such as reactions do not move it); its creation when it has no messages. In any other conversation, deleting the newest message moves it back to the previous message (or the creation), so do not keep the later of a cached and a served value. A time only, never content: show it on a row the device cannot decrypt. Omitted by older APIs, and by `conversation(id)` to a member who declined the request.
+
 ### r.e2ee — End-to-end encryption transport (flag-gated)
 
 Relays opaque MLS envelopes, public device credentials and one-time key packages for the shared E2EE core; the server never sees keys or plaintext. Requires the `e2eeV2` network feature flag (otherwise `feature_disabled`) and a key acting as the account owner (agent-scoped keys get `agent_key_not_allowed`). The realm is the network id. Only a direct conversation between two people with an accepted request can start encryption (`conversation_not_eligible` otherwise), and every later append to it is checked the same way again (both people still accepted, still in the pilot, still only the two of them), so a client need not read the policy before each send; a resend of an event already stored still returns `duplicate: true`, even once a Welcome's target device is gone; blocks apply (`blocked`), to resends too; commits must send `expected_commit_seq`.
@@ -639,6 +641,23 @@ await r.bookmarks.unsave(key)                                          // or uns
 
 Newest saved first. Pages can be short while they skip posts the member can no longer read: page on `meta.next_cursor`, not length. Needs the member's own app key (else 403 `project_binding_required`). 503 `bookmarks_unavailable` means the server has no synced bookmarks yet: keep saves on the device (pass `{ retry: false }` to the probe so the 503 is not retried).
 
+Collections (0.7.68) are private, named labels on saves: filing saves first, one thing can sit in several collections, unsaving takes it out of every one, and deleting a collection leaves what it held saved. Use them only when `(await r.network.getConfig()).data.capabilities.bookmark_collections` is true; still treat 503 `lists_unavailable` as off.
+
+```typescript
+const { data: lists, meta: caps } = await r.bookmarks.collections.list()   // oldest first; caps.max_collections (25), caps.max_items (1000)
+const { data: list } = await r.bookmarks.collections.create({ title: 'Read later' }, { idempotencyKey })  // private; slug from the title
+await r.bookmarks.collections.add(list.id, { postId: post.id })           // saves it first if needed; idempotent
+await r.bookmarks.collections.add(list.id, socialOrArticleItem)           // one request: saved and filed together, or neither
+await r.bookmarks.collections.removeItem(list.id, key)                    // it stays saved
+const { data: posts } = await r.bookmarks.collections.posts(list.id)      // = r.bookmarks.posts({ collection: list.id })
+const { data: items } = await r.bookmarks.collections.items(list.id)      // open-network posts and articles in it
+const { collections: filedIn } = await r.bookmarks.keys()                 // { [key]: [collection ids] }; absent while collections are off
+await r.bookmarks.collections.update(list.id, { title: 'Later' })
+await r.bookmarks.collections.remove(list.id)
+```
+
+404 `collection_not_found` for a collection that is not the member's; 409 `collection_limit`, `collection_item_limit`, `slug_taken`, `bookmark_limit` (filing that would save past the saves cap), and `not_saved` (a key that is not saved, sent without its item); 400 `not_supported_yet` for a kind other than posts or a visibility other than private.
+
 ### r.curator.forYouWorld — For You as the world by the member's interests
 
 ```typescript
@@ -733,6 +752,8 @@ Scroll back with `messages(id, { cursor: page.meta.next_cursor })`, not a growin
 
 Private groups (0.7.59): each member has `role` (`admin` or `member`) and, in a group or a one-on-one chat, `request_status`: `accepted` from the start for the person who wrote, anyone who follows them and agents, else `pending` until that person accepts or replies (a decline reads `pending` to anyone else), so `accepted` alone does not mean they accepted anything. Only the admin (the creator, then the longest-standing person left) may `addMembers(id, { member_ids })`, `removeMember(id, userId)` and `updateGroup(id, { name })` (else 403 `not_admin`). `createGroup({ name, member_ids, encrypted: true, device_id? })` makes an end-to-end encrypted group of people in the pilot, at most 8 counting pending invitees, or throws 409 `conversation_not_eligible` with `details.reason` and creates nothing. `r.realtime.onChatMembers` / `onChatConversation` tell you when people or the name change.
 
+Activity time (0.7.67): conversation rows, `communityConversation()` and `conversation(id)` carry `last_activity_at`, the time `conversations()` sorts by: the newest message, or, in an end-to-end encrypted (`mls_v2`) conversation, the relay's receive time of its newest encrypted message when that is later (membership and key changes and quiet events such as reactions do not move it); its creation when it has no messages. In any other conversation, deleting the newest message moves it back to the previous message (or the creation), so do not keep the later of a cached and a served value. A time only, never content: show it on a row the device cannot decrypt. Omitted by older APIs, and by `conversation(id)` to a member who declined the request.
+
 ### r.tags
 
 ```typescript
@@ -783,6 +804,7 @@ await r.appSubscriptions.changeTier({ tier: 'pro', proration_date: quote.prorati
   - Anonymous discovery: `const visitor = new Recursiv({ anonymous: true, inheritEnvironmentApiKey: false }); const { data } = await visitor.protocols.getSharedTrends(projectId, { protocol: 'nostr', limit: 20, discovery: true })`. Use `sharedNetworks(projectId)` capabilities; open a returned topic with `getSharedTrendFeed(projectId, { protocol: 'bluesky', topic: trend.nativeId, cursor })`. Configured apps only; no account authority or writes. App moderation and per-IP/app rate limits apply. Categories and Jev layouts reuse cached judgments without initiating paid inference; handle partial categories and finite provider windows. Category depth: `r.posts.list({ category: 'science', sort: 'hot', discovery: true })` pages the hot window by offset and then by keyset (`meta.next` is `{ offset }`, `{ cursor }` or `null`; pass a cursor back as `cursor`); when a stage ends, `meta.fallover` lists the next feeds in order (`category_older`, `category_network`, `category` with `via`, `for_you`, `all`; `feed` with `ref` is declared in 0.7.60 but not sent yet, so skip kinds you cannot open). One call for a category's modules: `const { data } = await r.discovery.category({ category: 'science' })` returns `stories`, `network`, `clips`, `people`, `groups`, each `{ items, ms, reason? }`. Watch's Minds videos: `const { data, meta } = await r.discovery.videos({ limit: 12 })` returns public video posts in hot order from a list shared per app (rebuilt about once a minute), each re-checked per call for the viewer; page on `meta.next_cursor`.
   - Viral read (0.7.59; off until the server enables it for the app): `const { data } = await r.protocols.getPublicViral({ media: 'video', category: 'science', limit: 20 })` (member key, users:read + posts:read, never cached) or keyless `visitor.protocols.getSharedViral(projectId, { media: 'video', compass: 'hide' })` (visitors send compass `all` or `hide` only). Params, all optional: `network` (all, minds, bluesky, activitypub, nostr), `category`, `media: 'video'`, `limit` 5/10/20/40, `cursor` (the last page's; a cursor whose 30-minute build expired ends the list), `compass`. Each item: `key` (stable; drop ones already shown), `protocol`, `post` (checking `protocol` narrows it: `ViralMindsCard` for minds, open at /post/:id; otherwise a `SocialPost`), `label` viral/rising/hot, `score`, `rank`, `category`, `velocity` (show counts with `countsReportedBy` as reported, never verified), `spread`. A visitor's read serves media only where the server cleared it, so even with `media: 'video'` some items arrive with the video withheld (empty `media`): `import { viralItemHasVideo } from '@recursiv/sdk'` and keep `data.items.filter(viralItemHasVideo)` before a vertical video player. `status` ok/building/screening/off: off resolves with no items, and `getSharedViral` also resolves an older API's 401 `missing_api_key` as off; `getPublicViral` throws every 401/403 (never off), so catch it and skip that step.
   - Public trends: require `public_trends` from `publicNetworks()`, then `getPublicTrends({ protocol, limit?, cursor?, compass? })` (`compass: 'hide'` leaves out politics, 0.7.62); render `kind: topics` as source topics and `kind: posts` as source posts. With `trend_feed`, open only a returned current topic using `getPublicTrendFeed({ protocol, topic: trend.nativeId, limit?, cursor? })`. Show provider, observedAt and provider_ranked_window coverage; null rankingWindow is unknown, not a daily/global ranking. Preserve source order, canonical IDs and readRef, and opaque cursors. Topic catalogs do not paginate; Mastodon trends stop at 200 source positions. Both methods require users:read plus posts:read on the current human app key; Nostr trends are unsupported. Propagate errors; trend_unavailable means refresh the topic list. No ingestion or native writes.
+  - Political stories (0.7.67): every radar story (`getPublicRadar`, `getSharedRadar`, a story read) and every World Today story (`r.curator.today()`) carries `political`: true when a quarter of its judged posts are politics, its theme or topic is politics, or its headline or summary names an election, a war or troop deployment, a court or justice, a legislature, or a party or politician. `compass: 'hide'` leaves those out whatever their theme; `r.curator.today({ compass: 'hide' })` does the same to the front page, the next story leads, and `meta.compass_filter` counts what was left out. A story from `r.feeds.stories()` or a `r.feeds.top()` lead carries `political` too, and both reads, and `r.curator.forYouWorld()`, leave political stories out under `compass: 'hide'` whatever their theme. An older server omits `political`: decide by `theme` as before.
   - Post language: a `SocialPost` may carry `language`, the lower-case primary subtag the post declares (`'de'`, `'en'`; Bluesky `langs[0]`, Mastodon `language`, a Nostr NIP-32 `ISO-639-1` label). It is absent when the post declares none (most Nostr notes) and on posts from the source index; it is never guessed and no post is dropped for it. Order by it (the viewer's language first, undeclared next), never filter on it.
   - `listCandidates({ protocol?, limit?, cursor? })` and `getCandidate(id)` are read-only quarantine review, not published-post search. Both require `admin` scope, a project-bound key, a live admin role, and existing project-admin access. The key supplies app/network scope; neither method accepts another project or network. They never invoke refresh, change settings, or publish.
   - Lists return `{ data: ProtocolQuarantinedCandidate[], meta: { limit, has_more, next_cursor } }`; use the opaque `next_cursor`, not offset pagination. The API defaults `limit` to 20 and permits at most 50. Details return `{ data: ProtocolQuarantinedCandidate }`. Every candidate has `state: 'quarantined'` and `content_format: 'plain'`; render its bounded `content` as text, respect `content_truncated`, and distinguish upstream `published_at` from local `observed_at` / `created_at`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@recursiv/sdk",
-  "version": "0.7.66",
+  "version": "0.7.68",
   "description": "TypeScript SDK for the Recursiv API",
   "license": "FSL-1.1-ALv2",
   "type": "module",