@recursiv/sdk 0.7.122 → 0.7.123

package/dist/index.d.ts

@@ -227,8 +227,8 @@ export type { ModerationTargetType, ModerationActionType, ModerationAppealStatus
 export { TrustResource } from './resources/trust.js';
 export type { TrustEnvelope, OwnTrustEvent, TrustPublicKey, OwnTrustEvents } from './resources/trust.js';
 export { LinkPreviewResource } from './resources/link-preview.js';
-export { SEARCH_SECTIONS, SearchResource } from './resources/search.js';
-export type { PublicSearchPage, PublicSearchTab, SearchAnswer, SearchGroup, SearchLadder, SearchOmitReason, SearchParams, SearchPerson, SearchPost, SearchRelated, SearchResponse, SearchSection, SearchStage, SearchStory, SearchTopic, SearchVia, } from './resources/search.js';
+export { SEARCH_MEDIA_KINDS, SEARCH_SECTIONS, SearchResource } from './resources/search.js';
+export type { PublicSearchPage, PublicSearchTab, SearchAnswer, SearchGroup, SearchLadder, SearchOmitReason, SearchParams, SearchPerson, SearchPost, SearchRelated, SearchResponse, SearchSection, SearchStage, SearchStory, SearchTopic, SearchVia, SearchMedia, SearchMediaEmbed, SearchMediaItem, SearchMediaKind, SearchMediaProvider, SearchMediaProviderStatus, SearchMediaSource, } from './resources/search.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, FeedTopNetworkMap, FeedTopParams, FeedTopResponse, FeedTopTarget, PublicFeedTopMeta, PublicFeedTopParams, PublicFeedTopResponse, } from './resources/feeds.js';

package/dist/index.js

@@ -284,7 +284,7 @@ export { JudgmentsResource, isJudgmentSharedWordsError } from './resources/judgm
 export { ModerationResource } from './resources/moderation.js';
 export { TrustResource } from './resources/trust.js';
 export { LinkPreviewResource } from './resources/link-preview.js';
-export { SEARCH_SECTIONS, SearchResource } from './resources/search.js';
+export { SEARCH_MEDIA_KINDS, SEARCH_SECTIONS, SearchResource } from './resources/search.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';

package/dist/resources/search.d.ts

@@ -2,7 +2,7 @@ import type { HttpClient } from '../client.js';
 import type { Post, StoryOutlets, ViewerModeration } from '../types.js';
 import type { SocialPost } from './protocols.js';
 /** The sections a blended search can answer, in no particular order (see `SearchAnswer.order`). */
-export declare const SEARCH_SECTIONS: readonly ["top_posts", "latest_posts", "open_network", "people", "groups", "topics", "stories", "related", "trending"];
+export declare const SEARCH_SECTIONS: readonly ["top_posts", "latest_posts", "open_network", "people", "groups", "topics", "stories", "related", "trending", "media"];
 export type SearchSection = (typeof SEARCH_SECTIONS)[number];
 /** Why a section is absent: out of time, the server was busy, not available for this app, not allowed for this key, or it failed. */
 export type SearchOmitReason = 'timeout' | 'saturated' | 'unavailable' | 'scope' | 'error';
@@ -39,8 +39,11 @@ export interface SearchLadder {
 export type SearchPost = Post & {
     via?: SearchVia;
 };
-/** A visitor's search tabs (tRPC `publicDiscovery.search`, read keyless through the app's public client). */
-export type PublicSearchTab = 'top' | 'latest' | 'people' | 'groups' | 'videos' | 'news' | 'tag';
+/**
+ * A visitor's search tabs (tRPC `publicDiscovery.search`, read keyless through the app's public client). `media` (server
+ * 0.7.123): no items, the page's `media` section instead.
+ */
+export type PublicSearchTab = 'top' | 'latest' | 'people' | 'groups' | 'videos' | 'news' | 'tag' | 'media';
 /** `fast` answers within about a second; `deep` waits for the reads `fast` left running. */
 export type SearchStage = 'fast' | 'deep';
 /** One page of a visitor's search: every item labelled `via`, never empty while the app has anything popular. */
@@ -57,15 +60,75 @@ export interface PublicSearchPage<T = Record<string, unknown>> {
         next_cursor: string | null;
         has_more: boolean;
     };
+    /** The `media` tab only: what the web has for the words. Absent where the app does not get it (`ladder.unavailable` names `media`). */
+    media?: SearchMedia;
+}
+/** The kinds of a search's media items, in the order the server lists them. */
+export declare const SEARCH_MEDIA_KINDS: readonly ["about", "video", "article", "image", "audio"];
+export type SearchMediaKind = (typeof SEARCH_MEDIA_KINDS)[number];
+/** Where a media item was found. */
+export type SearchMediaSource = 'brave' | 'wikipedia' | 'peertube' | 'openverse';
+/**
+ * How a video may play in place: YouTube's own player for `id` (use youtube-nocookie.com and follow its player rules:
+ * at least 200x200, nothing drawn over it, YouTube shown as the source), or a PeerTube instance's own embed page.
+ */
+export type SearchMediaEmbed = {
+    provider: 'youtube';
+    id: string;
+} | {
+    provider: 'peertube';
+    url: string;
+};
+/** One item of the media section: a video, a picture, a news article, a sound or the about card. */
+export interface SearchMediaItem {
+    kind: SearchMediaKind;
+    source: SearchMediaSource;
+    title: string;
+    /** The page it lives on: open it when the item is tapped. */
+    url: string;
+    /** The picture to draw, always on the API's signed media proxy; null when there is none. A picture item always has one. */
+    thumbnail: string | null;
+    width: number | null;
+    height: number | null;
+    duration_s: number | null;
+    /** The channel, outlet or creator. */
+    publisher: string | null;
+    /** ISO 8601. */
+    published_at: string | null;
+    /** A news description, or the about card's extract. */
+    description: string | null;
+    embed: SearchMediaEmbed | null;
+    /** The credit a licensed work requires: show it with the work. */
+    attribution: string | null;
+    license: string | null;
+    /**
+     * Its picture was judged suggestive: present only for a member who turned Show NSFW on, who is shown it blurred.
+     * Visitors and members on safe defaults are never served such an item.
+     */
+    sensitive?: true;
+}
+export type SearchMediaProvider = 'brave_web' | 'brave_images' | 'wikipedia' | 'peertube' | 'openverse_images' | 'openverse_audio';
+/**
+ * What each provider did for this answer; `timeout`: it is still reading, ask again shortly for more; `budget`: a
+ * spending limit held it back (the day's Brave calls, or this caller's own calls a day or fresh answers an hour, past
+ * which only what is already cached is served).
+ */
+export type SearchMediaProviderStatus = 'ok' | 'cached' | 'empty' | 'skipped' | 'budget' | 'unconfigured' | 'timeout' | 'error';
+/** The media section: what the web has for the words (server 0.7.123). */
+export interface SearchMedia {
+    items: SearchMediaItem[];
+    providers: Partial<Record<SearchMediaProvider, SearchMediaProviderStatus>>;
 }
 export interface SearchParams {
     q: string;
     /** Items per section, 1-20 (default 6). */
     limit?: number;
-    /** Only these sections (default: all). */
+    /** Only these sections (default: all but `media`, which answers only when named: each may spend a paid web search). */
     sections?: readonly SearchSection[];
     /** For organization-bound keys, as on `posts.search`. */
     organization_id?: string;
+    /** How many pictures the app already shows for the query: the media section asks the web for pictures only when fewer than six. */
+    own_images?: number;
 }
 export interface SearchPerson {
     id: string;
@@ -205,6 +268,11 @@ export interface SearchAnswer {
             } | null;
             items: SearchPost[];
         };
+        /**
+         * What the web has for the words (server 0.7.123): videos, news, pictures, sound and an about card, only on the
+         * networks the server offers it to (others list it in `omitted` as `unavailable`).
+         */
+        media?: SearchMedia;
     };
     /** Answered, non-empty sections in the order to render them. */
     order: SearchSection[];

package/dist/resources/search.js

@@ -1,5 +1,7 @@
 /** The sections a blended search can answer, in no particular order (see `SearchAnswer.order`). */
-export const SEARCH_SECTIONS = ['top_posts', 'latest_posts', 'open_network', 'people', 'groups', 'topics', 'stories', 'related', 'trending'];
+export const SEARCH_SECTIONS = ['top_posts', 'latest_posts', 'open_network', 'people', 'groups', 'topics', 'stories', 'related', 'trending', 'media'];
+/** The kinds of a search's media items, in the order the server lists them. */
+export const SEARCH_MEDIA_KINDS = ['about', 'video', 'article', 'image', 'audio'];
 export class SearchResource {
     client;
     constructor(client) {

package/llm.md

@@ -739,9 +739,13 @@ Each answers 404 while the app's operator has it off; `feeds.top` is private to
 // One query, answered as sections. Each has its own time budget; a slow one is listed in `omitted`.
 const { data: answer } = await r.search.query({ q: 'apple', limit: 6 })
 for (const section of answer.order) render(section, answer.sections[section])
-// top_posts, latest_posts, open_network, people, groups, topics, stories, related, trending
+// top_posts, latest_posts, open_network, people, groups, topics, stories, related, trending, media
+// What the web has for the words, alone, so it paints beside the rest (0.7.123):
+const { data: web } = await r.search.query({ q: 'hockey', sections: ['media'], own_images: shownPictures })
 ```
 
+`media` (0.7.123): videos (YouTube ids as `embed`, PeerTube embed pages), news articles, pictures, sound and one `about` card (Wikipedia), from Brave Search, Wikipedia, PeerTube and Openverse with strict safe search. It answers only when `sections` names it (the default sections leave it out: each answer may spend a paid web search). Every picture passes the same vision check a post's picture does: a visitor sees only pictures judged safe, and a member who turned Show NSFW on gets a suggestive one marked `sensitive` (blur it). Every `thumbnail` is on the API's signed media proxy; play a YouTube embed through youtube-nocookie.com by its player's rules and show each `attribution`. `own_images` (how many pictures the page already shows) lets the server ask for the web's pictures only when fewer than six. Only the networks the server offers it to get it (others: `omitted` `unavailable`); `providers` says what each source did (`timeout`: ask again shortly). Visitors read it as `publicDiscovery.search` `tab: 'media'` (`PublicSearchPage.media`).
+
 `trending` joins when the answer is thin or old, so a search never dead-ends. A thin answer steps down the search ladder (0.7.79): the word a typo meant, the known words with the rest dropped ("wiggly memes" searches "memes"), what is popular in the category the words are about, then on the app. Every item says how in `via` (`SearchVia`) and `answer.ladder` (`SearchLadder`) says what happened: label it honestly ("No exact matches for X", "Did you mean Y?", "Popular in Comedy right now"); `ladder.unavailable` names sections the key cannot read. Visitors read the same ladder keyless through tRPC `publicDiscovery.search` (`PublicSearchPage`). `top_posts` is floored as `r.posts.search`'s relevance page is; `people` rows carry `followers_count`, `posts_count`, `empty` and `verified` (see `r.profiles.search`); `groups` rows carry `description` (one line) and `last_active_at`, to tell groups of one name apart. Page further with `r.posts.search`. Needs `posts:read`; `people` needs `users:read`, `groups` `communities:read`; `open_network` and `stories` need `users:read` plus the caller's own app key on its network, `trending` that app key. What the key cannot have is in `omitted` (`scope` / `unavailable`).
 
 ### r.curator — World Today and its story pages

package/package.json

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