@recursiv/sdk 0.7.67 → 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) |

package/dist/index.d.ts

@@ -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/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/llm.md

@@ -641,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

package/package.json

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