@recursiv/sdk 0.7.71 → 0.7.72

package/README.md

@@ -108,12 +108,12 @@ for await (const chunk of r.agents.chatStream(agent.id, { message: 'Hello!' }))
 ### Platform
 | Resource | Purpose |
 |----------|---------|
-| `r.settings` | User preferences (including app-scoped content choices), sessions (`revokeOtherSessions` keeps this device), password management, email change (`requestConfirmationCode` for accounts with no password), deactivation (`disableAccount({ password })`, 0.7.71; 404 on an API that does not serve it) |
+| `r.settings` | User preferences (including app-scoped content choices; per-kind notification settings in `notifications.channels`, set one kind with `updateNotifications({ channels: { post_reaction: { push: false } } })`, 0.7.72), sessions (`revokeOtherSessions` keeps this device), password management, email change (`requestConfirmationCode` for accounts with no password), deactivation (`disableAccount({ password })`, 0.7.71; 404 on an API that does not serve it) |
 | `r.billing` | Usage tracking, subscriptions, checkout |
 | `r.appSubscriptions` | Consumer app plans: `checkout`, `status`, `createPortalSession`, `previewTierChange`, `changeTier` |
 | `r.boosts` | Promoted posts: `create`, `mine`, `balance`, `pause`, `resume`, `cancel`, `recordEvent`, `topup`, `confirmTopup`; admin `listPendingReview`, `review`, `grant` |
 | `r.wallet` | Wallet, MINDS tokens (`getTokenBalance`, `getTokenLedger`), USD payouts (`getPayouts`, `startPayoutOnboarding`, `payoutLoginLink`) |
-| `r.notifications` | Notification stream (`list`, `unreadCount`, `markAsRead`, `archive`, `markAllAsRead`) and push tokens |
+| `r.notifications` | Notification stream (`list`, `unreadCount`, `markAsRead`, `archive`, `markAllAsRead`; `category: 'mentions'` for mentions and replies only, 0.7.72) and push tokens |
 | `r.github` | GitHub integration |
 | `r.integrations` | External service connections |
 | `r.admin` | User management, stats, content reports (`listReports`, `resolveReport`, `dismissReport`) |
@@ -809,6 +809,13 @@ a legislature, or a party or politician. Hide politics leaves those out whatever
 `feeds.top()` carry `political` too (0.7.67), and those reads and `curator.forYouWorld()` leave political stories out
 under Hide politics.
 
+From 0.7.72 Hide politics on those reads that need no compass judgment (the radar, `curator.today()`,
+`getPublicTrends` and keyless `getSharedTrends({ ..., compass: 'hide' })`, the viral read, `sdk.discovery.videos` and a
+visitor's Discover posts) applies for every caller, whether or not the operator serves them the full filter: where it
+does not, Hide is the floor (the server's own `political` flags and browse categories, no judgment read) and
+`meta.compass_filter` says `status: 'applied'` with `basis: 'flags'`. Choose sides, Mix sides and the catalog's
+`compass_filter` capability still follow the operator's audience.
+
 Every story names one outlet count (0.7.71): radar stories, World Today stories, category strip stories, feed-top and search stories carry `outlets: { total, mainstream, independent, other }`, the distinct outlets of the articles the story lists (buckets sum to `total`). Show `outlets.total`; `sources.outlet` counts articles, not outlets.
 
 A World Today story's discussion across networks (0.7.69; servers with World Story Volume on): `sdk.curator.today()`

package/dist/resources/curator.d.ts

@@ -409,7 +409,8 @@ export interface CuratorTodayResponse {
     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).
+     * only; from 0.7.72 for every reader, `basis: 'flags'` where the full filter is not served to them), or status
+     * 'unavailable' when it was not applied (a side or Mix).
      */
     meta: {
         generating: boolean;

package/dist/resources/notifications.d.ts

@@ -91,7 +91,11 @@ export interface Notification {
     actor?: NotificationActor | null;
     post_preview?: NotificationPostPreview | null;
 }
-export type NotificationCategory = 'all' | 'social' | 'system';
+/**
+ * `mentions` (SDK 0.7.72) is a Mentions tab: mentions and replies only, a
+ * subset of `social`. An older server answers it 400.
+ */
+export type NotificationCategory = 'all' | 'social' | 'system' | 'mentions';
 export type NotificationScopeParams = {
     /** Which kind of notification to count. Defaults to `all`. Same meaning as in `list`. */
     category?: NotificationCategory;
@@ -114,7 +118,8 @@ export interface ListNotificationsParams extends PaginationParams {
      * reposts, mentions, community invites, joins and join requests, moderation
      * decisions). `system` is everything operational (agent, task, deploy,
      * billing, security). Direct messages are in neither: they live in the chat
-     * inbox. `all` (the default) lists every row that has not been archived.
+     * inbox. `mentions` is the posts that name you or answer you (mentions and
+     * replies). `all` (the default) lists every row that has not been archived.
      *
      * Ask for it here rather than filtering the page you get back: the server
      * applies the limit AFTER the category, so a client that filters afterwards

package/dist/resources/protocols.d.ts

@@ -1768,7 +1768,11 @@ export declare class ProtocolsResource {
     }): Promise<SingleResponse<SocialAuthorFeed>>;
     /**
      * Public, app-moderated discovery without account authority. Enrichment uses cached judgments only.
-     * Every page, previews included, gets the safety floor; `discovery` only asks for a layout.
+     * Every page, previews included, gets the safety floor; `discovery` only asks for a layout. `compass` (0.7.72): a
+     * visitor's Politics choice, `all` or `hide` only (a side or Mix is refused, 400 `invalid_input`). Hide politics leaves
+     * out the topics and posts whose cached browse category is politics, for every visitor, and the page says what it did
+     * in `meta.compass_filter` (`basis: 'flags'` until the operator serves visitors the full filter). An API older than
+     * 0.7.72 refuses `compass` here with a 400.
      */
     getSharedTrends(projectId: string, params: {
         protocol: string;
@@ -1777,6 +1781,7 @@ export declare class ProtocolsResource {
         includePreviews?: boolean;
         category?: string;
         discovery?: boolean;
+        compass?: string;
     }): Promise<SingleResponse<SocialTrends>>;
     /** Open a provider-listed topic through the same public-only app boundary, with the same safety floor. */
     getSharedTrendFeed(projectId: string, params: {
@@ -1843,7 +1848,8 @@ export declare class ProtocolsResource {
      * Current provider-ranked topics or posts, with explicit source and coverage. Does not ingest content.
      * Every page, previews included, gets the safety floor; `discovery` only asks for a layout. `compass` (a Politics
      * choice, spelled as `posts.list` takes it): Hide politics (`hide`) leaves out the topics and posts whose cached
-     * browse category is politics, where the filter is served to the member; a side or Mix is answered unfiltered. The
+     * browse category is politics, for every member (from 0.7.72; before, only where the filter was served to them), with
+     * `meta.compass_filter.basis` 'flags' where the full filter is not served; a side or Mix is answered unfiltered. The
      * page then says what it did in `meta.compass_filter`.
      */
     getPublicTrends(params: {

package/dist/resources/protocols.js

@@ -123,11 +123,15 @@ export class ProtocolsResource {
     }
     /**
      * Public, app-moderated discovery without account authority. Enrichment uses cached judgments only.
-     * Every page, previews included, gets the safety floor; `discovery` only asks for a layout.
+     * Every page, previews included, gets the safety floor; `discovery` only asks for a layout. `compass` (0.7.72): a
+     * visitor's Politics choice, `all` or `hide` only (a side or Mix is refused, 400 `invalid_input`). Hide politics leaves
+     * out the topics and posts whose cached browse category is politics, for every visitor, and the page says what it did
+     * in `meta.compass_filter` (`basis: 'flags'` until the operator serves visitors the full filter). An API older than
+     * 0.7.72 refuses `compass` here with a 400.
      */
     getSharedTrends(projectId, params) {
         return this.client.get(`/protocols/public/${encodeURIComponent(projectId)}/trends`, { protocol: params.protocol, limit: params.limit, cursor: params.cursor,
-            includePreviews: params.includePreviews, category: params.category, discovery: params.discovery });
+            includePreviews: params.includePreviews, category: params.category, discovery: params.discovery, compass: params.compass });
     }
     /** Open a provider-listed topic through the same public-only app boundary, with the same safety floor. */
     getSharedTrendFeed(projectId, params) {
@@ -207,7 +211,8 @@ export class ProtocolsResource {
      * Current provider-ranked topics or posts, with explicit source and coverage. Does not ingest content.
      * Every page, previews included, gets the safety floor; `discovery` only asks for a layout. `compass` (a Politics
      * choice, spelled as `posts.list` takes it): Hide politics (`hide`) leaves out the topics and posts whose cached
-     * browse category is politics, where the filter is served to the member; a side or Mix is answered unfiltered. The
+     * browse category is politics, for every member (from 0.7.72; before, only where the filter was served to them), with
+     * `meta.compass_filter.basis` 'flags' where the full filter is not served; a side or Mix is answered unfiltered. The
      * page then says what it did in `meta.compass_filter`.
      */
     getPublicTrends(params, options) {

package/dist/types.d.ts

@@ -104,6 +104,13 @@ export interface CompassFilterMeta {
             o: number;
         };
     };
+    /**
+     * `flags` (0.7.72): Hide politics was applied by the floor every caller gets, with no compass judgment: a story's
+     * `political` flag and theme (the radar, World Today), a network post's cached browse category (trends, the viral
+     * read), a Minds post's browse category (Watch's videos, a visitor's Discover posts). Sent where the operator does not
+     * serve this caller the full filter yet. Absent: the full filter as served. Choose sides and Mix sides never take it.
+     */
+    basis?: 'flags';
 }
 export interface PaginationMeta {
     discovery?: DiscoveryLayout;
@@ -1453,11 +1460,32 @@ export interface RegisterTokenInput {
      */
     device_key?: string;
 }
+/** The three ways one kind of notification can reach someone. */
+export interface NotificationChannelToggles {
+    inApp: boolean;
+    push: boolean;
+    email: boolean;
+}
+/**
+ * The kinds of notification a person can set one by one. Social: mentions,
+ * replies, reposts, reactions, follows and messages. Operator: agent work,
+ * deploys, billing, invites and the daily email. A server may send more keys
+ * than these.
+ */
+export type NotificationChannelKind = 'post_mention' | 'post_reply' | 'post_repost' | 'post_reaction' | 'follow' | 'message' | 'agent_activity' | 'billing' | 'community_invite' | 'project_invite' | 'deployment' | 'daily_digest';
+/** Every kind with all three channels spelled out, as the delivery gates read them. */
+export type NotificationChannelSettings = Partial<Record<NotificationChannelKind, NotificationChannelToggles>> & Record<string, NotificationChannelToggles>;
 export interface UserPreferences {
     notifications: {
+        /** Master switches: on when any kind has the channel on. */
         in_app: boolean;
         push: boolean;
         email: boolean;
+        /**
+         * Each kind on its own (`post_reaction: { inApp: true, push: false, email: false }`).
+         * Absent on servers older than SDK 0.7.72.
+         */
+        channels?: NotificationChannelSettings;
     };
     privacy: {
         profile_visibility: 'public' | 'network' | 'private';
@@ -1479,9 +1507,18 @@ export interface ContentPreferences {
     default_feed: 'foryou' | 'following';
 }
 export interface UpdateNotificationChannelsInput {
+    /** Master switch: sets in-app on every kind. */
     in_app?: boolean;
+    /** Master switch: sets push on every kind. */
     push?: boolean;
+    /** Master switch: sets email on every kind. */
     email?: boolean;
+    /**
+     * Set single kinds and leave every other kind as it is:
+     * `{ post_reaction: { push: false } }` stops reaction pushes and nothing else.
+     * Applied after the master switches when both are sent.
+     */
+    channels?: Partial<Record<NotificationChannelKind, Partial<NotificationChannelToggles>>> & Record<string, Partial<NotificationChannelToggles>>;
 }
 export interface UpdatePrivacyInput {
     profile_visibility?: 'public' | 'network' | 'private';

package/llm.md

@@ -788,7 +788,7 @@ Methods: `list`, `get`, `create`, `delete`
 
 ## Platform Resources
 
-- `r.settings` — User preferences, sessions, password changes, account deletion. `revokeOtherSessions({ keep_session_token? })` signs out every other device and keeps this key (and the proven session); `revokeAllSessions()` also revokes this key. Accounts with no password confirm `requestEmailChange({ new_email, email_code })` with a code from `requestConfirmationCode('email_change')`. With a project-bound key, `getPreferences()` includes app-scoped `content`; persist changes with `updateContent({ show_nsfw?, autoplay_video?, ai_enabled?, default_feed? })`. `disableAccount({ password })` (0.7.71) deactivates the account (hidden, nothing deleted; signing back in restores it), asked once; an API that does not serve deactivation answers 404 `NotFoundError`, so keep the control hidden until yours does.
+- `r.settings` — User preferences, sessions, password changes, account deletion. `revokeOtherSessions({ keep_session_token? })` signs out every other device and keeps this key (and the proven session); `revokeAllSessions()` also revokes this key. Accounts with no password confirm `requestEmailChange({ new_email, email_code })` with a code from `requestConfirmationCode('email_change')`. With a project-bound key, `getPreferences()` includes app-scoped `content`; persist changes with `updateContent({ show_nsfw?, autoplay_video?, ai_enabled?, default_feed? })`. Notifications (0.7.72): `getPreferences()` returns `notifications.channels`, each kind (`post_mention`, `post_reply`, `post_repost`, `post_reaction`, `follow`, `message`, and the operator kinds) with `{ inApp, push, email }`; `updateNotifications({ channels: { post_reaction: { push: false } } })` changes that kind only, while `in_app`/`push`/`email` stay master switches over every kind. `disableAccount({ password })` (0.7.71) deactivates the account (hidden, nothing deleted; signing back in restores it), asked once; an API that does not serve deactivation answers 404 `NotFoundError`, so keep the control hidden until yours does.
 - `r.signals` (0.7.71) — The member's engagement signals for their own ranking (For You), under their app-bound key (`agents:write`): `batch(events, { keepalive?, retry? })` sends up to `SIGNAL_BATCH_MAX` (100) `{ event_type, post_id?, dwell_ms?, metadata? }` to POST /signals/batch; `record(event)` sends one to POST /signals/post (for an API before the batch route, which answers that one 404). `event_type`: `view`, `click`, `dwell`, `react_up`, `react_down`, `save`, `hide`, `share`, `mute_source`, `open_chat`, `ask_agent`, `more_like`, `unhide`. Best-effort: a signal the server cannot store answers 200 with `recorded` 0 (or false) and a `reason` (`no_project_scope`, `project_db_unavailable`). `keepalive: true` is for a flush as the page is hidden or unloads: the request is on the wire before the call returns and is asked once.
 
 ```typescript
@@ -798,7 +798,7 @@ addEventListener('pagehide', () => { void r.signals.batch(pending.splice(0, SIGN
 - `r.billing` — Usage tracking, checkout sessions, portal sessions, metered billing
 - `r.appSubscriptions` — Project-scoped consumer plans: `checkout` (409 `subscription_exists` when the member already pays), `status`, `createPortalSession({ return_url, flow?: 'cancel' })` (`flow: 'cancel'` opens Stripe's cancel confirmation; 409 `no_subscription` when there is no plan to cancel), `previewTierChange({ tier })`, `changeTier({ tier, proration_date? })` (in-place, prorated, never a second subscription)
 - `r.boosts` — Promoted posts (micro-USD): `create`, `mine`, `balance`, `pause`, `resume`, `cancel`, `recordEvent`; buy credit with `topup({ amount_cents, return_url })` then `confirmTopup(sessionId)` (credits once); admin `listPendingReview`, `review`, `grant`
-- `r.notifications` — The notification stream: `list({ category: 'social' })` (rows carry `actor`, `reaction_type` and a `post_preview` with the viewer's `user_reaction`/`reposted_by_viewer_id` and counts; an `agent_needs_input` row carries `answered`, true once you have written in the agent's thread since it asked, when its title reads "You answered <agent>"), `unreadCount({ category })` for badges (`const { data } = await r.notifications.unreadCount({ category: 'social' })`), `markAsRead(id)`, `archive(id)` to dismiss, `markAllAsRead(category)` or `markAllAsRead({ category, organization_id })`, plus push token `registerToken`/`unregisterToken`. A push's `data.notificationId` is the row to mark read on tap. DMs are not in the stream.
+- `r.notifications` — The notification stream: `list({ category: 'social' })` (rows carry `actor`, `reaction_type` and a `post_preview` with the viewer's `user_reaction`/`reposted_by_viewer_id` and counts; an `agent_needs_input` row carries `answered`, true once you have written in the agent's thread since it asked, when its title reads "You answered <agent>"), `category: 'mentions'` (0.7.72) for a Mentions tab (mentions and replies only; `unreadCount` and `markAllAsRead` take it too), `unreadCount({ category })` for badges (`const { data } = await r.notifications.unreadCount({ category: 'social' })`), `markAsRead(id)`, `archive(id)` to dismiss, `markAllAsRead(category)` or `markAllAsRead({ category, organization_id })`, plus push token `registerToken`/`unregisterToken`. A push's `data.notificationId` is the row to mark read on tap. DMs are not in the stream.
 - `r.uploads` — Legacy media upload URLs (prefer `r.storage` for new projects)
 - `r.github` — GitHub integration (getRepository, getTree, getFileContent, getCommits, createFromTemplate)
 - `r.deployments` — Deployment management (prefer `r.projects.deploy()` for new projects)
@@ -835,6 +835,7 @@ await r.appSubscriptions.changeTier({ tier: 'pro', proration_date: quote.prorati
   - 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.
   - One outlet count per story (0.7.71): a radar story (list, story read, archive), a World Today story (`outlets`, with `outlet_count` its total and `lane_mix` its lanes), a category strip story, a `feeds.top`/`feeds.stories` story and a search story carry `outlets: { total, mainstream, independent, other }`, the distinct outlets of the articles the story lists (an allow-listed outlet once, an unlisted host in `other`; the buckets sum to `total`). Show `outlets.total`; `sources.outlet` counts articles. `DiscoveryCluster.outletCount` reads it. An older server omits it.
   - 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.
+  - Hide politics as a floor (0.7.72): the radar, `r.curator.today()`, `getPublicTrends`, keyless `visitor.protocols.getSharedTrends(projectId, { protocol, compass: 'hide' })` (visitors send `all` or `hide` only; an older API answers 400 to `compass` there), the viral read, `r.discovery.videos` and a visitor's Discover posts apply `compass: 'hide'` for every caller. Where the operator does not serve the caller the full filter, the answer's `meta.compass_filter` is `{ status: 'applied', basis: 'flags', ... }`: left out by the server's own `political` flags and browse categories, no judgment read. Treat `applied` with or without `basis` as filtered. Choose sides and Mix sides still answer `unavailable` until the operator serves them, and the catalog's `compass_filter` capability still says when to offer Politics in Filters.
   - 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.71",
+  "version": "0.7.72",
   "description": "TypeScript SDK for the Recursiv API",
   "license": "FSL-1.1-ALv2",
   "type": "module",