@recursiv/sdk 0.7.22 → 0.7.25

package/README.md

@@ -110,7 +110,7 @@ for await (const chunk of r.agents.chatStream(agent.id, { message: 'Hello!' }))
 | `r.admin` | User management, stats, content reports (`listReports`, `resolveReport`, `dismissReport`) |
 | `r.dispatcher` | Task queue, claims, signals, outcomes, webhooks |
 | `r.goals` | Org goals with task rollups (group dispatcher tasks) |
-| `r.protocols` | `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` |
+| `r.protocols` | Public reading: `publicNetworks`, `searchPublicProfiles`, `getPublicProfile`, `getPublicAuthorFeed`, `getFollowingFeed`, `getPublicConversation`, `getPublicTrends`, `getPublicTrendFeed`; 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` |
 
 Full reference: see [llm.md](./llm.md) (ships with this package) or the type definitions in `dist/`.
 
@@ -423,3 +423,34 @@ import type {
 ## License
 
 FSL-1.1-ALv2 — source-available, converts to Apache 2.0 after 2 years.
+
+### Public source trends
+
+Check `publicNetworks()` for `public_trends` before calling
+`getPublicTrends({ protocol, limit: 10, cursor })`. The response is a discriminated
+union: `kind: 'topics'` contains Bluesky topics; `kind: 'posts'` contains public
+ActivityPub posts ranked by mastodon.social. Preserve provider order and display
+`provider`, `observedAt`, and `coverage: 'provider_ranked_window'`. A null
+`rankingWindow` means the provider has not supplied an exact ranking interval.
+
+For a network with `trend_feed`, open a returned topic with
+`getPublicTrendFeed({ protocol, topic: topic.nativeId, limit: 10, cursor })`.
+The service rechecks current topic availability before each page; a disappeared
+topic returns `trend_unavailable` rather than an empty feed. Keep canonical post
+IDs and provider `readRef` when opening `getPublicConversation`. Cursors are
+opaque; topic catalogs have no pagination and the Mastodon post window stops at
+200 source positions. Both reads require `users:read` and `posts:read` on the
+current human project-bound app key. Nostr does not advertise trends. Provider
+failures propagate as SDK errors, and neither method ingests or publishes posts.
+
+### Native Nostr signing
+
+Use `protocols.nativeNostrAccount()` to check the app's explicit native-write
+capability. For an enabled connected key, prepare a text post with
+`prepareNativeNostr(identityId, { action: 'publish', content })`, show its
+identity, relay and text, and ask the client signer to sign the returned event.
+Submit only the public event with `submitNativeNostr(identityId, { intent, event,
+approve: true })`. Preserve that exact event on uncertain retries. Check
+`getNativeNostrPost(identityId, eventId)` for relay visibility. An owned note can
+prepare `{ action: 'delete', postId }`; deletion is a signed request, not a
+promise of erasure across all relays. Keys are never sent to this SDK service.

package/dist/index.d.ts

@@ -189,7 +189,7 @@ export type { UploadMediaInput, UploadUrlInput, UploadUrlResult } from './resour
 export { WalletResource } from './resources/wallet.js';
 export { ProtocolsResource } from './resources/protocols.js';
 export { PROTOCOL_ADAPTER_MATURITIES, PROTOCOL_CAPABILITY_OPERATIONS, PROTOCOL_CAPABILITY_STATUSES, } from './resources/protocols.js';
-export type { SocialProfile, SocialSubscription, SocialSubscriptionChange, SocialProfilePage, SocialNetwork, SocialPost, SocialAuthorFeed, SocialFollowingFeed, SocialFollowingSource, SearchPublicProfilesParams, HostedProtocolConnections, HostedProtocol, HostedProtocolIdentity, HostedNostrChallenge, HostedNostrIdentityProof, HostedPostPreview, ConnectHostedIdentityInput, PreviewHostedPostInput, PublishHostedPostInput, ListProtocolCandidatesParams, ProtocolAdapterMaturity, ProtocolAdapterMetadata, ProtocolCandidateListResponse, ProtocolCandidatePageMeta, ProtocolCapabilityOperation, ProtocolCapabilityStatus, ProtocolCollectionStatus, ProtocolQuarantinedCandidate, ProtocolRefreshResult, ProtocolSettings, ProtocolSettingsUpdateResult, UpdateSettingsInput as UpdateProtocolSettingsInput, } from './resources/protocols.js';
+export type { SocialProfile, SocialSubscription, SocialSubscriptionChange, SocialProfilePage, SocialNetwork, SocialPost, SocialConversation, SocialTrend, SocialTrendProvenance, SocialTrends, SocialTrendFeed, SocialAuthorFeed, SocialFollowingFeed, SocialFollowingSource, SearchPublicProfilesParams, HostedProtocolConnections, HostedProtocol, HostedProtocolIdentity, HostedNostrChallenge, HostedNostrIdentityProof, NativeNostrPrepareInput, NativeNostrPrepared, NativeNostrAccount, NativeNostrPostState, NativeNostrReceipt, HostedPostPreview, ConnectHostedIdentityInput, PreviewHostedPostInput, PublishHostedPostInput, ListProtocolCandidatesParams, ProtocolAdapterMaturity, ProtocolAdapterMetadata, ProtocolCandidateListResponse, ProtocolCandidatePageMeta, ProtocolCapabilityOperation, ProtocolCapabilityStatus, ProtocolCollectionStatus, ProtocolQuarantinedCandidate, ProtocolRefreshResult, ProtocolSettings, ProtocolSettingsUpdateResult, UpdateSettingsInput as UpdateProtocolSettingsInput, } from './resources/protocols.js';
 export { InboxResource } from './resources/inbox.js';
 export { NetworkResource } from './resources/network.js';
 export { SimulatorResource } from './resources/simulator.js';

package/dist/resources/protocols.d.ts

@@ -159,6 +159,55 @@ export interface HostedNostrIdentityProof {
     created_at: number;
     tags: string[][];
 }
+export type NativeNostrPrepareInput = {
+    action: 'publish';
+    content: string;
+} | {
+    action: 'delete';
+    postId: string;
+};
+export interface NativeNostrPrepared {
+    intent: string;
+    event: {
+        kind: number;
+        created_at: number;
+        content: string;
+        tags: string[][];
+    };
+    eventId: string;
+    action: 'publish' | 'delete';
+    identityId: string;
+    pubkey: string;
+    relay: string;
+    expiresAt: string;
+    postId?: string;
+}
+export interface NativeNostrAccount {
+    enabled: boolean;
+    identity: HostedProtocolIdentity | null;
+    capabilities: Array<'publish_original_text' | 'request_own_post_deletion'>;
+    signing?: 'client';
+}
+export interface NativeNostrPostState {
+    postId: string;
+    relay: string;
+    pubkey: string;
+    state: 'published' | 'deletion_requested' | 'not_found';
+    post: {
+        content: string;
+        createdAt: string;
+    } | null;
+}
+export interface NativeNostrReceipt {
+    eventId: string;
+    postId: string;
+    relay: string;
+    action: 'publish' | 'delete';
+    state: 'published' | 'deletion_requested' | 'unknown' | 'rejected';
+    acknowledged: boolean;
+    readBack: 'found' | 'absent' | 'unavailable';
+    reason?: 'blocked' | 'rate_limited' | 'restricted' | 'invalid' | 'relay_error';
+}
 export type ConnectHostedIdentityInput = {
     protocol: 'atproto';
     identifier: string; /** Prefer a native app password. Used once, never stored. */
@@ -201,8 +250,9 @@ export interface SocialNetwork {
         url: string;
     };
     coverage: string;
-    capabilities: Array<'profile_search' | 'profile_read' | 'original_author_posts' | 'minds_subscription' | 'following_feed'>;
+    capabilities: Array<'profile_search' | 'profile_read' | 'original_author_posts' | 'minds_subscription' | 'following_feed' | 'conversation_read' | 'public_trends' | 'trend_feed'>;
     profileSearchPagination: boolean;
+    conversationCoverage?: string;
 }
 /** Public source identity, independent of any local Minds user or handle. */
 export interface SocialProfile {
@@ -248,6 +298,8 @@ export interface SocialPost {
     protocol: string;
     nativeId: string;
     sourceUrl: string;
+    /** Opaque provider-local reference returned by public reads. */
+    readRef?: string;
     author: Omit<SocialProfile, 'subscription'>;
     text: string;
     createdAt: string;
@@ -266,6 +318,48 @@ export interface SocialAuthorFeed {
     cursor: string | null;
     coverage: 'original_posts';
 }
+export interface SocialTrendProvenance {
+    provider: {
+        name: string;
+        url: string;
+    };
+    observedAt: string;
+    coverage: 'provider_ranked_window';
+    /** Exact ranking interval is not supplied by these providers. */
+    rankingWindow: null;
+}
+export interface SocialTrend {
+    protocol: string;
+    nativeId: string;
+    title: string;
+    description: string;
+    sourceUrl: string;
+    startedAt: string | null;
+    postCount: number | null;
+}
+export type SocialTrends = SocialTrendProvenance & ({
+    kind: 'topics';
+    items: SocialTrend[];
+    cursor: null;
+} | {
+    kind: 'posts';
+    items: SocialPost[];
+    cursor: string | null;
+});
+export interface SocialTrendFeed extends SocialTrendProvenance {
+    trend: SocialTrend;
+    items: SocialPost[];
+    cursor: string | null;
+}
+export interface SocialConversation {
+    focus: SocialPost;
+    /** Oldest available ancestor first, ending with the immediate parent. */
+    ancestors: SocialPost[];
+    /** Available direct replies to focus, not all descendants. */
+    replies: SocialPost[];
+    coverage: 'public_provider_window';
+    limited: boolean;
+}
 export interface SocialFollowingSource {
     subscriptionId: string;
     protocol: string;
@@ -306,6 +400,35 @@ export declare class ProtocolsResource {
         protocol?: string;
         cursor?: string;
     }): Promise<SingleResponse<SocialFollowingFeed>>;
+    /** Read the selected source post and its bounded public conversation; never publishes or imports it. */
+    getPublicConversation(params: {
+        protocol: string;
+        post: string;
+        readRef?: string;
+    }): Promise<SingleResponse<SocialConversation>>;
+    /** Current provider-ranked topics or posts, with explicit source and coverage. Does not ingest content. */
+    getPublicTrends(params: {
+        protocol: string;
+        limit?: number;
+        cursor?: string;
+    }): Promise<SingleResponse<SocialTrends>>;
+    /** Open a topic currently listed by the provider. Use its nativeId as topic and preserve the opaque cursor. */
+    getPublicTrendFeed(params: {
+        protocol: string;
+        topic: string;
+        limit?: number;
+        cursor?: string;
+    }): Promise<SingleResponse<SocialTrendFeed>>;
+    /** Native writes are off unless enabled for this exact app; public readers are independent. */
+    nativeNostrAccount(): Promise<SingleResponse<NativeNostrAccount>>;
+    prepareNativeNostr(id: string, input: NativeNostrPrepareInput): Promise<SingleResponse<NativeNostrPrepared>>;
+    /** Pass only the public signed event. Retry with this same intent/event, never sign a replacement after a timeout. */
+    submitNativeNostr(id: string, input: {
+        intent: string;
+        event: HostedNostrIdentityProof;
+        approve: true;
+    }): Promise<SingleResponse<NativeNostrReceipt>>;
+    getNativeNostrPost(id: string, postId: string): Promise<SingleResponse<NativeNostrPostState>>;
     /** Save a private reading subscription after resolving the immutable native ID. */
     subscribeToProfile(input: {
         protocol: string;

package/dist/resources/protocols.js

@@ -78,6 +78,41 @@ export class ProtocolsResource {
     getFollowingFeed(params = {}) {
         return this.client.get('/protocols/social/following-feed', { protocol: params.protocol, cursor: params.cursor });
     }
+    /** Read the selected source post and its bounded public conversation; never publishes or imports it. */
+    getPublicConversation(params) {
+        return this.client.get('/protocols/social/conversation', { protocol: params.protocol, post: params.post, readRef: params.readRef });
+    }
+    /** Current provider-ranked topics or posts, with explicit source and coverage. Does not ingest content. */
+    getPublicTrends(params) {
+        return this.client.get('/protocols/social/trends', { protocol: params.protocol, limit: params.limit, cursor: params.cursor });
+    }
+    /** Open a topic currently listed by the provider. Use its nativeId as topic and preserve the opaque cursor. */
+    getPublicTrendFeed(params) {
+        return this.client.get('/protocols/social/trend-feed', { protocol: params.protocol, topic: params.topic, limit: params.limit, cursor: params.cursor });
+    }
+    /** Native writes are off unless enabled for this exact app; public readers are independent. */
+    nativeNostrAccount() {
+        return this.client.get('/protocols/social/nostr/account');
+    }
+    prepareNativeNostr(id, input) {
+        hostedIdentityPath(id);
+        const body = input.action === 'publish' ? { action: input.action, content: input.content } : { action: input.action, postId: input.postId };
+        return this.client.post(`/protocols/social/nostr/${encodeURIComponent(id)}/prepare`, body);
+    }
+    /** Pass only the public signed event. Retry with this same intent/event, never sign a replacement after a timeout. */
+    submitNativeNostr(id, input) {
+        hostedIdentityPath(id);
+        const { id: eventId, pubkey, sig, kind, content, created_at, tags } = input.event;
+        return this.client.post(`/protocols/social/nostr/${encodeURIComponent(id)}/submit`, {
+            intent: input.intent, event: { id: eventId, pubkey, sig, kind, content, created_at, tags }, approve: input.approve,
+        });
+    }
+    getNativeNostrPost(id, postId) {
+        hostedIdentityPath(id);
+        if (!/^[0-9a-f]{64}$/.test(postId))
+            throw new ValidationError({ type: 'validation_error', code: 'invalid_post_id', message: 'A Nostr event ID is required' });
+        return this.client.get(`/protocols/social/nostr/${encodeURIComponent(id)}/posts/${postId}`);
+    }
     /** Save a private reading subscription after resolving the immutable native ID. */
     subscribeToProfile(input) {
         return this.client.post('/protocols/social/subscriptions', input).then(result => {

package/llm.md

@@ -619,7 +619,8 @@ if (subscription.active) {
 - `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.inviteCodes` / `r.inviteCodesAdmin` — Invite code management
 - `r.organizationSettings` / `r.organizationSecurity` — Org configuration
-- `r.protocols` — Protocol discovery/settings: `const { data: adapters } = await r.protocols.list()` returns bounded `{ id, name, icon, color, maturity, capabilities, limitations }` metadata; `supported` means implemented, not configured, healthy, authorized, or enabled. Methods: `list`, `status`, `listCandidates`, `getCandidate`, `search`, `getSettings`, `refresh`, `updateSettings`.
+- `r.protocols` — Public reading: `publicNetworks`, `searchPublicProfiles`, `getPublicProfile`, `getPublicAuthorFeed`, `getFollowingFeed`, `getPublicConversation`, `getPublicTrends`, `getPublicTrendFeed`; private app subscriptions: `listSubscriptions`, `subscribeToProfile`, `unsubscribeFromProfile`, `onSubscriptionChange`. Example after selecting a returned source post: `const { data: thread } = await r.protocols.getPublicConversation({ protocol: post.protocol, post: post.nativeId, readRef: post.readRef })`. Render `focus`, oldest-first `ancestors` and direct `replies`; `public_provider_window` never promises every reply, and `limited` marks known omissions. Requires both `users:read` and `posts:read` on the current human app key. Protocol discovery/settings: `const { data: adapters } = await r.protocols.list()` returns bounded `{ id, name, icon, color, maturity, capabilities, limitations }` metadata; `supported` means implemented, not configured, healthy, authorized, or enabled. Methods: `list`, `status`, `listCandidates`, `getCandidate`, `search`, `getSettings`, `refresh`, `updateSettings`.
+  - Public trends: require `public_trends` from `publicNetworks()`, then `getPublicTrends({ protocol, limit?, cursor? })`; 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.
   - `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`.
   - Safe source IDs are preserved byte-exact. `external_id: null` means unsafe or malformed provenance was withheld, not an invented ID; `author.native_id` may likewise be absent or withheld. Preserve nulls in both list and detail views, and use the candidate's own `id` for `getCandidate`.

package/package.json

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