@recursiv/sdk 0.7.72 → 0.7.74

package/README.md

@@ -117,6 +117,7 @@ for await (const chunk of r.agents.chatStream(agent.id, { message: 'Hello!' }))
 | `r.github` | GitHub integration |
 | `r.integrations` | External service connections |
 | `r.admin` | User management, stats, content reports (`listReports`, `resolveReport`, `dismissReport`) |
+| `r.moderation` | Moderation actions: `publicLog`, `mine`, `appeal`; staff `apply`, `resolveAppeal`, `list({ target_type?, target_id? })` (one target's recorded actions, newest first, at most 100; none named = the network's latest; 0.7.74) and `reverse(actionId)` (sent once: a repeat answers 404 `action_not_found`; 0.7.74); agent grants `listAgentGrants`, `grantAgent`, `revokeAgent` |
 | `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); 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` |
@@ -468,6 +469,17 @@ opaque; topic catalogs have no pagination and the Mastodon post window stops at
 current human project-bound app key. Nostr does not advertise trends. Provider
 failures propagate as SDK errors, and neither method ingests or publishes posts.
 
+A clip player scoped to one network asks for its video window instead (0.7.73):
+`getPublicTrends({ protocol: 'bluesky', limit: 25, media: 'video', cursor })`, or keyless
+`getSharedTrends(projectId, { protocol: 'bluesky', limit: 25, media: 'video', cursor })`.
+The answer is a `kind: 'posts'` page holding only posts that carry a video (Bluesky: What's
+Hot's videos, one provider request a page), paged by its opaque cursor until it is `null`;
+a page may be empty while its cursor goes on. It takes no `category` and judges no layout;
+`compass: 'hide'` (0.7.72) leaves the political clips out of it as it does from trends.
+A signed-out read holds only clips whose video the visitor may see, and counts the rest in
+`mediaFilter.withheld`. A network without a video window answers 404 `unsupported_protocol`;
+an API that predates `media` answers 400 `invalid_input`, so fall back to its trends.
+
 ### Native Nostr signing
 
 Use `protocols.nativeNostrAccount()` to check the app's explicit native-write

package/dist/index.d.ts

@@ -208,7 +208,7 @@ export type { ReportTargetType, ReportStatus, CreateReportInput, ReportRecord, R
 export { JudgmentsResource, isJudgmentSharedWordsError } from './resources/judgments.js';
 export type { JudgmentSubjectKind, JudgmentSource, JudgmentOverrideMethod, PostLabelsStatus, PostLabelsQuery, PostLabelsSubject, PostLabelsCategory, PostLabelsPolitics, PostJudgmentRecord, PostJudgment, PostSafetyAttribution, PostLabelsCategoryView, PostLabelsSummaryView, PostLabelsFullView, PostLabels, DisputeJudgmentInput, JudgmentDispute, ReviewJudgmentInput, JudgmentReviewUpheld, JudgmentReviewAwaitingReviewer, JudgmentReviewOverridden, JudgmentReview, JudgmentSharedWordsDetails, JudgmentSharedWordsError, } from './resources/judgments.js';
 export { ModerationResource } from './resources/moderation.js';
-export type { ModerationTargetType, ModerationActionType, ModerationAppealStatus, ModerationPrinciple, PublicModerationAction, PublicModerationLog, OwnModerationAppeal, OwnModerationAction, OwnModerationLog, ApplyModerationActionInput, AgentModerationMode, AgentModerationGrant, } from './resources/moderation.js';
+export type { ModerationTargetType, ModerationActionType, ModerationAppealStatus, ModerationPrinciple, PublicModerationAction, PublicModerationLog, OwnModerationAppeal, OwnModerationAction, OwnModerationLog, ApplyModerationActionInput, ModerationAction, ListModerationActionsParams, RecordedModerationTargetType, 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';

package/dist/resources/moderation.d.ts

@@ -63,6 +63,30 @@ export interface ApplyModerationActionInput {
     actor_type?: 'human' | 'ai' | 'system';
     source_report_id?: string;
 }
+/** Where an action can be recorded: `source_item` is one open-network post withheld from promotion surfaces. */
+export type RecordedModerationTargetType = ModerationTargetType | 'source_item';
+/** One recorded action as staff read it (GET /moderation/actions): who did what to which target, and why. */
+export interface ModerationAction {
+    id: string;
+    target_type: RecordedModerationTargetType;
+    target_id: string;
+    action: ModerationActionType;
+    label: string | null;
+    reason: string | null;
+    /** The moderator or agent who acted; null for a system or classifier action. */
+    actor_id: string | null;
+    actor_type: 'human' | 'ai' | 'system';
+    source_report_id: string | null;
+    expires_at: string | null;
+    /** Null while the action is in force. */
+    reversed_at: string | null;
+    created_at: string;
+}
+/** Both fields, for one target's history; neither, for the network's latest actions. */
+export interface ListModerationActionsParams {
+    target_type?: RecordedModerationTargetType;
+    target_id?: string;
+}
 /** What a granted agent may do on the report queue: shadow reads it; act also resolves and dismisses. */
 export type AgentModerationMode = 'shadow' | 'act';
 /** A network admin's grant letting one AI agent work the report queue. */
@@ -88,6 +112,23 @@ export declare class ModerationResource {
         success: true;
         id: string;
     }>>;
+    /**
+     * Admin (0.7.74): recorded actions, newest first (at most 100), inside the caller's
+     * network and a bound key's app. Name a target (both fields) for its history,
+     * e.g. to reverse a ban still in force; name none for the latest actions.
+     */
+    list(params?: ListModerationActionsParams): Promise<SingleResponse<ModerationAction[]>>;
+    /**
+     * Admin (0.7.74): reverse an action; the target's state is derived again from what is
+     * still in force (an account is unbanned when its last ban goes) and the
+     * public log shows the reversal. Sent once, never retried: a repeat of a
+     * reversal that landed answers 404 `action_not_found` (`NotFoundError`), as
+     * does an action already reversed. A reviewed label override answers 409
+     * `use_judgment_review`.
+     */
+    reverse(actionId: string): Promise<SingleResponse<{
+        success: true;
+    }>>;
     /**
      * List decisions affecting the caller or content they own. This remains
      * reachable through a valid key while the account is suspended or banned.

package/dist/resources/moderation.js

@@ -15,6 +15,28 @@ export class ModerationResource {
     apply(input) {
         return this.client.post('/moderation/actions', input);
     }
+    /**
+     * Admin (0.7.74): recorded actions, newest first (at most 100), inside the caller's
+     * network and a bound key's app. Name a target (both fields) for its history,
+     * e.g. to reverse a ban still in force; name none for the latest actions.
+     */
+    list(params = {}) {
+        return this.client.get('/moderation/actions', {
+            target_type: params.target_type,
+            target_id: params.target_id,
+        });
+    }
+    /**
+     * Admin (0.7.74): reverse an action; the target's state is derived again from what is
+     * still in force (an account is unbanned when its last ban goes) and the
+     * public log shows the reversal. Sent once, never retried: a repeat of a
+     * reversal that landed answers 404 `action_not_found` (`NotFoundError`), as
+     * does an action already reversed. A reviewed label override answers 409
+     * `use_judgment_review`.
+     */
+    reverse(actionId) {
+        return this.client.post(`/moderation/actions/${encodeURIComponent(actionId)}/reverse`, undefined, { retry: false });
+    }
     /**
      * List decisions affecting the caller or content they own. This remains
      * reachable through a valid key while the account is suspended or banned.

package/dist/resources/protocols.d.ts

@@ -1289,6 +1289,11 @@ export type SocialTrends = SocialTrendProvenance & ({
     safetyFilter?: {
         withheld: number;
     };
+    /** A `media: 'video'` page read signed out: the clips left off because the visitor may not see their video yet (counts only). */
+    mediaFilter?: {
+        media: 'video';
+        withheld: number;
+    };
 }) & {
     /** Present when `getPublicTrends` named a filtering `compass`: what Hide politics did to this page (counts only). */
     meta?: {
@@ -1773,6 +1778,11 @@ export declare class ProtocolsResource {
      * 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.
+     * `media: 'video'` (0.7.73; Bluesky) reads the network's own window of video posts instead of its trends: a `posts`
+     * page paged by `cursor`, with no category and no layout, and `compass: 'hide'` applies to it as to trends. A visitor
+     * is served only the clips whose video they may see; `mediaFilter.withheld` counts the rest. A network without a video
+     * window answers 404 `unsupported_protocol`, and an API that predates the parameter 400 `invalid_input`: read its
+     * trends instead.
      */
     getSharedTrends(projectId: string, params: {
         protocol: string;
@@ -1782,6 +1792,7 @@ export declare class ProtocolsResource {
         category?: string;
         discovery?: boolean;
         compass?: string;
+        media?: 'video';
     }): Promise<SingleResponse<SocialTrends>>;
     /** Open a provider-listed topic through the same public-only app boundary, with the same safety floor. */
     getSharedTrendFeed(projectId: string, params: {
@@ -1850,7 +1861,9 @@ export declare class ProtocolsResource {
      * choice, spelled as `posts.list` takes it): Hide politics (`hide`) leaves out the topics and posts whose cached
      * 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`.
+     * page then says what it did in `meta.compass_filter`. `media: 'video'` (0.7.73; Bluesky) reads the network's own window
+     * of video posts instead of its trends, as `getSharedTrends` does, with every video kept for a member and Hide politics
+     * applied where asked.
      */
     getPublicTrends(params: {
         protocol: string;
@@ -1860,6 +1873,7 @@ export declare class ProtocolsResource {
         category?: string;
         discovery?: boolean;
         compass?: string;
+        media?: 'video';
     }, options?: SocialReadOptions): Promise<SingleResponse<SocialTrends>>;
     /** Open a topic currently listed by the provider. Use its nativeId as topic and preserve the opaque cursor. Screened like `getPublicTrends`. */
     getPublicTrendFeed(params: {

package/dist/resources/protocols.js

@@ -128,10 +128,16 @@ export class ProtocolsResource {
      * 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.
+     * `media: 'video'` (0.7.73; Bluesky) reads the network's own window of video posts instead of its trends: a `posts`
+     * page paged by `cursor`, with no category and no layout, and `compass: 'hide'` applies to it as to trends. A visitor
+     * is served only the clips whose video they may see; `mediaFilter.withheld` counts the rest. A network without a video
+     * window answers 404 `unsupported_protocol`, and an API that predates the parameter 400 `invalid_input`: read its
+     * trends instead.
      */
     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, compass: params.compass });
+            includePreviews: params.includePreviews, category: params.category, discovery: params.discovery, compass: params.compass,
+            ...(params.media !== undefined ? { media: params.media } : {}) });
     }
     /** Open a provider-listed topic through the same public-only app boundary, with the same safety floor. */
     getSharedTrendFeed(projectId, params) {
@@ -213,14 +219,17 @@ export class ProtocolsResource {
      * choice, spelled as `posts.list` takes it): Hide politics (`hide`) leaves out the topics and posts whose cached
      * 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`.
+     * page then says what it did in `meta.compass_filter`. `media: 'video'` (0.7.73; Bluesky) reads the network's own window
+     * of video posts instead of its trends, as `getSharedTrends` does, with every video kept for a member and Hide politics
+     * applied where asked.
      */
     getPublicTrends(params, options) {
         return this.client.get('/protocols/social/trends', { protocol: params.protocol, limit: params.limit, cursor: params.cursor,
             ...(params.includePreviews !== undefined ? { includePreviews: params.includePreviews } : {}),
             ...(params.category !== undefined ? { category: params.category } : {}),
             ...(params.discovery !== undefined ? { discovery: params.discovery } : {}),
-            ...(params.compass !== undefined ? { compass: params.compass } : {}) }, ...readOptions(options));
+            ...(params.compass !== undefined ? { compass: params.compass } : {}),
+            ...(params.media !== undefined ? { media: params.media } : {}) }, ...readOptions(options));
     }
     /** Open a topic currently listed by the provider. Use its nativeId as topic and preserve the opaque cursor. Screened like `getPublicTrends`. */
     getPublicTrendFeed(params, options) {

package/llm.md

@@ -820,6 +820,7 @@ const { data: quote } = await r.appSubscriptions.previewTierChange({ tier: 'pro'
 await r.appSubscriptions.changeTier({ tier: 'pro', proration_date: quote.prorationDate })
 ```
 - `r.admin` — Admin operations (user management, stats, network settings); content reports: `listReports({ status? })`, `resolveReport(id)`, `dismissReport(id)` (project-bound keys see only their app's reports)
+- `r.moderation` — Moderation actions. Staff (admin key), 0.7.74: `const { data: actions } = await r.moderation.list({ target_type: 'user', target_id: userId })` reads one target's recorded actions (`ModerationAction`: `id`, `target_type` incl. `source_item`, `action`, `label`, `reason`, `actor_id`, `actor_type`, `source_report_id`, `expires_at`, `reversed_at`, `created_at`), newest first, at most 100, inside the caller's network and a project-bound key's app; `list()` with no target reads the network's latest. Unban = reverse each ban still in force: `for (const a of actions.filter(a => a.action === 'ban' && !a.reversed_at)) await r.moderation.reverse(a.id)`; the target's state is derived again from what is still in force. `reverse` is sent once, never retried: 404 `action_not_found` (`NotFoundError`) means already reversed or not in the caller's scope; 409 `use_judgment_review` means a reviewed label override (change it with `r.judgments.review`). An older SDK has neither method. Also `apply`, `publicLog`, `mine`, `appeal`, `resolveAppeal`, and agent grants `listAgentGrants`, `grantAgent(agentId, 'shadow' | 'act')`, `revokeAgent`.
 - `r.judgments` (0.7.71) — Jev's labels of one post. `get({ kind: 'post' | 'network_post', id })`: switch on `data.view` — `'full'` for the post's author and staff (`judgments` with answers, `safety` verdict, `viral.withheld`; staff also `reviewer_ids`, `review_note`), `'summary'` for other members (`category`, `politics` band in words with its `judgment_id`; never a probability or cell). `data.status === 'unavailable'` (returned, not thrown): hide label actions. `getPublic(projectId, { kind, id })` on an anonymous client: `view: 'category'` only. `dispute(judgmentId, { question_key: 'placement', proposed: 'cm' | … | 'not_political', note? })` (safety: `question_key: 'safety'`, author only): the author's dispute is an appeal; a repeat answers `existing: true`. Staff: `review(judgmentId, { outcome: 'uphold' } | { outcome: 'override', proposed, note?, apply_to_shared? })`, sent once (never retried): a compass override answers 202 `{ status: 'awaiting_reviewer', agreeing, needed }` until a second reviewer (or an agreeing Jev re-judge) proposes the same; a safety override to `'none'` that would free other posts throws 409 `shared_words` (`isJudgmentSharedWordsError(e)`, `e.details.shared_posts`) until resent with `apply_to_shared: true`. Budgets (60 reads/hour, 25 of one author's posts, 20 disputes/day) throw `RateLimitError` with `scope: 'action'` at once. Example: `const { data } = await r.judgments.get({ kind: 'post', id }); if (data.status === 'ok' && data.view === 'summary' && data.politics) await r.judgments.dispute(data.politics.judgment_id, { question_key: 'placement', proposed: 'not_political' })`
 - `r.inviteCodes` / `r.inviteCodesAdmin` — Invite code management
 - `r.organizationSettings` / `r.organizationSecurity` — Org configuration
@@ -832,7 +833,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`.
   - Progressive Discover feed (0.7.71): `const feed = r.discovery.createProgressiveFeed({ networks, category, recommend, top: { ref: 'builtin:all' }, seen, seenClusters }); const round = await feed.next(part => draw(part))` opens one `createFeed` session per source (Minds with the radar and suggestions, one per network with `public_trends`) and hands each source's page on as a `DiscoveryPart` (`{ source, round, modules, composed?, mixed? }`) the moment it lands, instead of a page that waits for its slowest network (up to 15 s); a round waits `DISCOVERY_STRAGGLER_MS` past its first answer and rejects only when every source failed. The first load is held until Minds and one other network answered (or `FIRST_SCREEN_MS`, 2.5 s, after the first answer; `firstScreenMs: VISITOR_FIRST_SCREEN_MS` for a visitor) and arrives as one `composed: true` part from `composeFirstScreen`: the top's first post when it is a playable video, else a picture lead from the best 8 by engagement (never a story, rail, video strip, column, `isSensitivePost` post or `linksAdultSite` porn link), then every network's posts by engagement (`DiscoveryEngagementMerge`) with row 2 from another network than the lead's when one is left (`FIRST_SCREEN_NETWORK_ROWS`), a story as row 3 and a rail as row 5, nothing dropped. Merge later `mixed` parts with `mergeDiscoveryArrival(rows, arriving, reachedIds)`. `top`/`seen`/`seenClusters`/`bucket` reach every session; the top is read once per open. Also `retryFailed()`, `onStatus(listener)`, `setNetworks(catalog)`; settings `perSource`, `firstScreen`, `onLanded`. For you: `createProgressiveFeed({ createFeed: o => r.discovery.createPersonalFeed(o) }, options, { perSource: false })`. A session's `seen` now also leaves seen network posts out of trend pages, previews and topic pages; in a category a topic page with nothing new ends its topic and after `DISCOVERY_EMPTY_TOPIC_PAGES` (3) in a row the network's other topics are skipped.
   - 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.
+  - Public trends: require `public_trends` from `publicNetworks()`, then `getPublicTrends({ protocol, limit?, cursor?, compass?, media? })` (`compass: 'hide'` leaves out politics, 0.7.62; `media: 'video'`, 0.7.73, Bluesky: the network's own window of video posts, a `kind: posts` page paged by its cursor, no category or layout, 404 `unsupported_protocol` for a network without one, 400 on an API that predates it; keyless `getSharedTrends(projectId, { ..., media: 'video' })` holds only clips a visitor may see and counts the rest in `mediaFilter.withheld`); 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.

package/package.json

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