@recursiv/sdk 0.7.104 → 0.7.116

package/README.md

@@ -68,7 +68,9 @@ for await (const chunk of r.agents.chatStream(agent.id, { message: 'Hello!' }))
 | `r.databases` | `ensure`, `create`, `list`, `getCredentials`, `query` |
 | `r.envVars` | `set`, `list`, `delete` (values write-only; secrets masked on read) |
 | `r.projects` | `create`, `deploy`, `executeCode`, `createSandbox`, `stopSandbox`, `deploymentLogs` |
+| `r.deployments` | Operator release coordination: `reserveRelease`, `getRelease`, `advanceRelease`, `startRelease`, `finishRelease`, `recoverRelease`; follow the [shared release guide](../../docs/deploy/shared-releases.md) |
 | `r.storage` | `ensureBucket`, `getUploadUrl`, `getDownloadUrl`, `listItems`, `deleteObject` |
+| `r.telemetry` | `productCounts` — app-bound first-party aggregate counts; reviewed event names and counts only, retained at most 30 days |
 | `r.sandbox` | `execute` (anonymous, no API key needed) |
 
 ### AI Agents
@@ -123,8 +125,9 @@ for await (const chunk of r.agents.chatStream(agent.id, { message: 'Hello!' }))
 | `r.trust` | The signed trust log (0.7.96; 404 until the operator turns on `TRUST_LOG_PUBLIC_READS`): keyless `keys()` (every key that ever signed it), `mine({ before?, limit? })` (`users:read`: the caller's own signed events with the server's check `verified`). `r.moderation.publicLog` then carries `trust_log` on each action (`status`, and where the signed decision and reversal sit: `chain`, `seq`, `key_id`, `occurred_at`, `verified`). No read carries a hash or a signature |
 | `r.dispatcher` | Task queue, claims, signals, outcomes, webhooks |
 | `r.goals` | Org goals with task rollups (group dispatcher tasks) |
-| `r.linkPreview` | `get(url)` — a public link's Open Graph card (`data: null` when it has none). For a chat link pass `{ messageId }` or `{ conversationId }` on a signed-in key with `chat:read`: the link is fetched only when it is in the named message and a person wrote that message, or the caller wrote it in that conversation, else `refused: 'ai_link'`. A source with no id rejects (`ValidationError`). Not in encrypted chats: the server cannot read them, so leave `source` out there and apply the app's own rule |
-| `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?, replies?: 'none' })` (`replies: 'none'`, 0.7.78: the post alone for a card, with `repliesStatus: 'not_requested'`; `getPublicConversation` and `getConnectedSocialConversation` take it too). 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; a story a World Today story seeded carries `volume`, the first page of the posts that story counts across Minds and the open networks, whose `cursor` goes on with `curator.storyPosts` or `curator.memberStoryPosts`), 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` |
+| `r.media` | `sourceApprovals({ projectId, sources })` — cached public host/purpose judgments and exact owned hosts; no caller-triggered provider fetch or inference. Image/icon requests stay relayed; direct players use approved, unexpired decisions once enforcement is active |
+| `r.linkPreview` | `get(url, source?, { projectId })` opts into expiring relayed image/icon capabilities; refresh before `media_expires_at`, and preserve source authorization. `get(url)` — a public link's Open Graph card (`data: null` when it has none). For a chat link pass `{ messageId }` or `{ conversationId }` on a signed-in key with `chat:read`: the link is fetched only when it is in the named message and a person wrote that message, or the caller wrote it in that conversation, else `refused: 'ai_link'`. A source with no id rejects (`ValidationError`). Not in encrypted chats: the server cannot read them, so leave `source` out there and apply the app's own rule |
+| `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?, replies?: 'none' })` (`replies: 'none'`, 0.7.78: the post alone for a card, with `repliesStatus: 'not_requested'`; `getPublicConversation` and `getConnectedSocialConversation` take it too). 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`; a Fediverse community's newest threads, read-only (0.7.109): `getOpenGroupThreads({ group, limit?, cursor?, compass? })`, `group` being the `actor` of a groups read's `open_network` entry; 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; a story a World Today story seeded carries `volume`, the first page of the posts that story counts across Minds and the open networks, whose `cursor` goes on with `curator.storyPosts` or `curator.memberStoryPosts`), 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` |
 
 Full reference: see [llm.md](./llm.md) (ships with this package) or the type definitions in `dist/`.
 
@@ -205,6 +208,8 @@ await r.projects.createSandbox('proj_1')
 await r.projects.stopSandbox('proj_1')
 ```
 
+Shared API/frontend releases use `r.deployments` with a project-bound operator key carrying `projects:read` and `projects:write`. Read an existing reservation with `await r.deployments.getRelease(releaseId, projectId)`. Follow the [shared release guide](../../docs/deploy/shared-releases.md) for phase transitions, health proof and recovery; uncertain operations keep ownership held.
+
 ## AI agents
 
 ```typescript
@@ -316,6 +321,7 @@ const { apiKey, user } = await anonymous.auth.signInAndCreateKey(
     name: 'my-app',
     scopes: ['posts:read'],
     projectId: 'prj_xxx',
+    expiresAt: new Date(Date.now() + 90 * 24 * 60 * 60 * 1000).toISOString(),
     consumeSession: true,
   },
 )
@@ -324,6 +330,7 @@ const { apiKey, user } = await anonymous.auth.signInAndCreateKey(
 `consumeSession: true` atomically retires the temporary login session as the
 API key is minted. Use it when the customer app stores and authenticates only
 with the returned API key; omit it for flows that still need the cookie session.
+`createApiKey(input, sessionToken)` requires a signed-in session. Its optional `expiresAt` must be in the future and at most one year away. The creation receipt includes the stored `projectId`, `networkId` and `expiresAt`; validate these bindings before storing an operator key, and keep the returned key out of logs.
 
 ## Next.js server auth (`@recursiv/sdk/next`)
 
@@ -387,7 +394,9 @@ const { system, user, references } = renderBundleForModel(bundle, 'explain', { b
 
 #### Post pictures as pictures
 
-Pass each media item's `id`, the payload's `checked_at` (when Minds last matched the picture against the child-safety hash lists) and its `held: false` mark into `buildSubjectBundle`, then list the candidates, run your own checks on them, and render with the ones that passed:
+A post picture's `checked_at` is the time this read found it passed Minds' current checks (recursiv#5012): visibility, holds and adult labels. Where the server's media-safety floor is on (CONTENT_MEDIA_SAFETY_ENABLED), one of those labels is a vision model's stored verdict that the picture is not suggestive; no image classifier is run for `checked_at` itself. No hash bank (NCMEC, StopNCII) and no CSAM classifier is among the checks.
+
+Pass each media item's `id`, the payload's `checked_at` and its `held: false` mark into `buildSubjectBundle`, then list the candidates, run your own checks on every one of them, and render with the ones that passed:
 
 ```typescript
 import { type BundlePicture, bundlePictures, renderBundleForModel } from '@recursiv/sdk/assistant'
@@ -938,7 +947,9 @@ Both take a Politics choice, `compass` (`all`, `mix`, `hide`, or cells in the or
 `meta.compass_filter` (`status` `applied` or `unavailable`, and counts only), and each session
 page carries its Minds read's answer as `page.compass` (`unavailable`: the page is unfiltered). Only Minds
 posts are filtered, so a view that leaves posts out reads best with `source: 'minds'`.
-The catalog lists `compass_filter` on every network when the filter is served to the viewer.
+The catalog lists `compass_filter` on every network when the filter is served to the viewer, and `compass_sides`
+with it (0.7.116) when the viewer may choose sides and Mix too: a visitor's catalog lists it where the operator serves
+visitors the whole filter; without it, offer a visitor Hide politics only.
 Hide politics (`compass: 'hide'`) also applies on its own, with or without compass judgments on the server, to
 `sdk.discovery.videos`, `protocols.getPublicTrends` and the radar (`getPublicRadar`, keyless `getSharedRadar`; 0.7.62):
 it leaves out what is categorised politics (a story not themed yet, or `mixed`, too) and says what it did in
@@ -955,7 +966,7 @@ From 0.7.72 Hide politics on those reads that need no compass judgment (the rada
 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.
+`compass_filter` and `compass_sides` capabilities 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.
 

package/dist/assistant/render.d.ts

@@ -3,9 +3,9 @@ import type { AssistIntent, BundlePicture, BundlePictureOptions, RenderBundleOpt
 export declare const MEMBER_LINE_PREFIX = "| ";
 /**
  * When a post picture may go to a model as a picture (sealed-full-scope-v1 2.1, 2.2): at most `max_pictures` in one
- * message, pictures from the phone included (the caller passes the room left as `max`); only while Minds' last
- * child-safety check of it is younger than `fresh_ms`; a check time up to `clock_skew_ms` ahead of the caller's clock
- * still counts (clocks drift), and one further ahead is not a time Minds wrote, so it does not.
+ * message, pictures from the phone included (the caller passes the room left as `max`); only while the time it last
+ * passed Minds' current checks (`checked_at`) is younger than `fresh_ms`; a check time up to `clock_skew_ms` ahead of
+ * the caller's clock still counts (clocks drift), and one further ahead is not a time Minds wrote, so it does not.
  */
 export declare const BUNDLE_PICTURE_LIMITS: Readonly<{
     max_pictures: 3;

package/dist/assistant/render.js

@@ -12,11 +12,12 @@
  *
  * Pictures (sealed-full-scope-v1 2.1, 2.2): with `pictures` given, a picture on the asked-about post, its parent or
  * its quote (never a reply's) also goes as a picture, an image part inside the content block after the content's text,
- * when Minds' last child-safety check of it (`checked_at`) is under 24 hours old by the caller's clock, the caller
- * approved it (`allowed`, from bundlePictures) and the caller's image cache holds its prepared JPEG; at most 3 per
- * message, fewer when the message carries pictures from the phone, never for 'translate'. Every other picture goes as
- * its alt text and stored caption only, as before. The renderer never reads a clock or fetches: the clock and the
- * cached bytes are the caller's.
+ * when the time it last passed Minds' current checks (`checked_at`; SubjectMediaInput says what those checks are and
+ * are not) is under 24 hours old by the caller's clock, the caller approved it (`allowed`, from bundlePictures, after
+ * the caller's own checks) and the caller's image cache holds its prepared JPEG; at most 3 per message, fewer when the
+ * message carries pictures from the phone, never for 'translate'. Every other picture goes as its alt text and stored
+ * caption only, as before. The renderer never reads a clock or fetches: the clock and the cached bytes are the
+ * caller's.
  */
 import { count, isoTime, plainHandle, plainId, referencesOf, webAddress } from './subjectBundle.js';
 import { ASSIST_INTENTS } from './types.js';
@@ -27,9 +28,9 @@ const LANGUAGE_PATTERN = /^[A-Za-z]{2,3}(?:-[A-Za-z0-9]{2,8}){0,3}$/;
 export const MEMBER_LINE_PREFIX = '| ';
 /**
  * When a post picture may go to a model as a picture (sealed-full-scope-v1 2.1, 2.2): at most `max_pictures` in one
- * message, pictures from the phone included (the caller passes the room left as `max`); only while Minds' last
- * child-safety check of it is younger than `fresh_ms`; a check time up to `clock_skew_ms` ahead of the caller's clock
- * still counts (clocks drift), and one further ahead is not a time Minds wrote, so it does not.
+ * message, pictures from the phone included (the caller passes the room left as `max`); only while the time it last
+ * passed Minds' current checks (`checked_at`) is younger than `fresh_ms`; a check time up to `clock_skew_ms` ahead of
+ * the caller's clock still counts (clocks drift), and one further ahead is not a time Minds wrote, so it does not.
  */
 export const BUNDLE_PICTURE_LIMITS = Object.freeze({
     max_pictures: 3,

package/dist/assistant/types.d.ts

@@ -55,10 +55,14 @@ export interface SubjectMediaInput {
     id?: string | null;
     /**
      * When the picture last passed Minds' current checks (the post payload's `media[].checked_at`, sent with `held:
-     * false`, sealed-full-scope-v1 2.1): an ISO time with its zone, written only by the server. Under Bill's 2026-10-11
-     * departure from gate P1 no hash-bank check is among them (recursiv#5012). Kept only when `held` is exactly `false`. A picture can go to a model as a picture only while this is under 24 hours old by the
-     * renderer's clock; absent, not an ISO time with its zone, or without `held: false`, means alt text and the stored
-     * caption only, as for every other picture.
+     * false`, sealed-full-scope-v1 2.1): an ISO time with its zone, written only by the server. The checks are
+     * visibility, holds and adult labels (recursiv#5012). Where the server's media-safety floor is on
+     * (CONTENT_MEDIA_SAFETY_ENABLED), one of those labels is a vision model's stored verdict that the picture is not
+     * suggestive; no image classifier is run for this field. No hash bank (NCMEC, StopNCII) and no CSAM classifier is
+     * among the checks, so run your own checks on the picture too. Kept only when `held` is exactly `false`. A picture
+     * can go to a model as a picture only while this is under 24 hours old by the renderer's clock; absent, not an ISO
+     * time with its zone, or without `held: false`, means alt text and the stored caption only, as for every other
+     * picture.
      */
     checked_at?: string | null;
 }
@@ -171,8 +175,8 @@ export interface BundleMedia {
     /** Pictures only: the media's id, when the input had a plain one. Never written into model input. */
     id?: string;
     /**
-     * Pictures only: Minds' last child-safety check of it (ISO time, UTC), when the input had a valid one and marked the
-     * picture not held (`held: false`).
+     * Pictures only: when it last passed Minds' current checks (ISO time, UTC; `SubjectMediaInput.checked_at` says what
+     * those checks are and are not), when the input had a valid one and marked the picture not held (`held: false`).
      */
     checked_at?: string;
 }
@@ -300,7 +304,10 @@ export interface BundlePicture {
     media_id: string;
     /** Which picture of its item it is, from 1, as the content numbers them ("picture 2 alt text"). */
     number: number;
-    /** Minds' last child-safety check of it (ISO time, UTC), from the bundle, for your own freshness check. */
+    /**
+     * When it last passed Minds' current checks (ISO time, UTC; `SubjectMediaInput.checked_at` says what those checks
+     * are and are not), from the bundle, for your own freshness check. It is not a reason to skip your own checks.
+     */
     checked_at: string;
 }
 export interface BundlePictureOptions {

package/dist/index.d.ts

@@ -3,6 +3,8 @@ import { DiscoveryResource } from './resources/discovery.js';
 export * from './resources/discovery.js';
 export * from './feed-definition.js';
 export * from './social-protocol-ids.js';
+import { TelemetryResource } from './resources/telemetry.js';
+export * from './resources/telemetry.js';
 import { AuthResource } from './resources/auth.js';
 import { PostsResource } from './resources/posts.js';
 import { UsersResource } from './resources/users.js';
@@ -124,6 +126,7 @@ export declare class Recursiv {
     readonly swarms: SwarmsResource;
     readonly templates: TemplatesResource;
     readonly media: MediaResource;
+    readonly telemetry: TelemetryResource;
     readonly webhooks: WebhooksResource;
     readonly jobs: JobsResource;
     readonly curator: CuratorResource;
@@ -201,6 +204,7 @@ export { EnvVarsResource } from './resources/env-vars.js';
 export type { QueryDatabaseInput, QueryResult } from './resources/databases.js';
 export { GitHubResource } from './resources/github.js';
 export { DeploymentsResource } from './resources/deployments.js';
+export type { DeploymentReleaseInput, DeploymentRelease, DeploymentReleaseOperation, DeploymentReleaseRecoveryInput } from './resources/deployments.js';
 export type { PrepareProtocolServersInput, PreparedProtocolServers, ProtocolServerPreparation, ProtocolServerUpgradePreview, ProtocolServerUpgradeInput, ProtocolServerUpgradeStatus } from './resources/deployments.js';
 export { IntegrationsResource } from './resources/integrations.js';
 export type { ExecuteToolInput, ExecuteToolResult } from './resources/integrations.js';
@@ -248,7 +252,7 @@ export { BoostsResource } from './resources/boosts.js';
 export type { BoostBalance, BoostBalanceResponse, BoostCampaign, BoostCampaignResponse, BoostEventResult, BoostLedgerEntry, BoostLedgerKind, BoostPlanCredit, BoostRejectionReason, BoostReviewStatus, BoostStatus, BoostTopupCheckout, BoostTopupConfirmation, BoostTopupLimits, } from './resources/boosts.js';
 export { ProtocolsResource } from './resources/protocols.js';
 export { PROTOCOL_ADAPTER_MATURITIES, PROTOCOL_CAPABILITY_OPERATIONS, PROTOCOL_CAPABILITY_STATUSES, SOCIAL_FOLLOWING_SOURCE_STATUSES, viralItemHasVideo, } from './resources/protocols.js';
-export type { SocialProfile, SocialBridge, SocialSubscription, SocialSubscriptionChange, SocialProfilePage, SocialRadar, SocialRadarCluster, SocialRadarMember, SocialRadarParams, SocialRadarSourceKind, SocialRadarPosts, SocialRadarStory, SocialRadarStoryArchive, ViralBaseline, ViralItem, ViralItemFields, ViralItemSpread, ViralItemVelocity, ViralLabel, ViralMindsCard, ViralMindsItem, ViralNetwork, ViralOpenProtocol, ViralProtocol, ViralProvider, ViralReadMeta, ViralReadParams, ViralReadResponse, ViralReadStatus, ViralRef, ViralSocialItem, SocialNetwork, SocialPost, SocialConversation, SocialTrend, SocialTrendProvenance, SocialTrends, SocialTrendSourceIndex, SocialTrendFeed, SocialPopularProfiles, SocialAuthorFeed, SocialFollowingFeed, SocialFollowingSource, SocialFollowingSourceStatus, SearchPublicProfilesParams, SearchPublicPostsParams, SocialPostSearch, HostedProtocolConnections, HostedProtocol, HostedProtocolIdentity, HostedNostrChallenge, HostedNostrIdentityProof, NativeNostrPrepareInput, NativeNostrPrepared, NativeNostrAccount, NativeNostrPostState, NativeNostrReceipt, NativeSocialProtocol, FederationIdentity, FederationIdentityView, NativeSocialAccount, NativeNetwork, NativeNetworkState, NativeNetworkPresence, NativeNetworkActivation, NativeNetworkOff, SetNativeNetworkInput, NativeSocialCallbackInput, NativeReplyPrepareInput, NativePostPrepareInput, NativeMediaInput, NativeMediaItem, NativePostBatch, NativePostQuote, NativePostHistory, NativeDelegatedPostHistoryItem, NativeNostrPostHistoryItem, NativeFollowSourceInput, NativeFollowPrepareInput, NativeFollowTarget, NativeFollowReceipt, NativeFollowState, NativeFollowAccount, NativeFollowStates, NativeFollowReview, NativeLikeSourceInput, NativeRepostSourceInput, NativeLikePrepareInput, NativeRepostPrepareInput, NativeLikeTarget, NativeRepostTarget, NativeLikeReceipt, NativeRepostReceipt, NativeLikeState, NativeRepostState, NativeLikeReview, NativeRepostReview, NativeReplyReceipt, NativeReplyBatch, NativeReplyHistory, NativeDelegatedReplyHistoryItem, NativeNostrReplyResult, NativeNostrReplyHistoryItem, NativeReplyRemovalReceipt, NativeReplyRemovalPreview, SocialSourceRef, SocialSourceControl, SocialSourceControlDisplay, SocialSourceControlChange, HostedPostPreview, ConnectHostedIdentityInput, CreateHostedIdentityInput, CreatedHostedProtocolIdentity, PreviewHostedPostInput, PublishHostedPostInput, ListProtocolCandidatesParams, ProtocolAdapterMaturity, ProtocolAdapterMetadata, ProtocolCandidateListResponse, ProtocolCandidatePageMeta, ProtocolCapabilityOperation, ProtocolCapabilityStatus, ProtocolCollectionStatus, ProtocolIngestionActivityReason, ProtocolIngestionCircuitHealth, ProtocolIngestionDeadLetterGroup, ProtocolIngestionHealthPosition, ProtocolIngestionHealthReport, ProtocolIngestionHealthRuntime, ProtocolIngestionHealthSection, ProtocolIngestionLaneActivity, ProtocolIngestionLaneCurrentJob, ProtocolIngestionLaneDeadLetters, ProtocolIngestionLaneHealth, ProtocolIngestionLaneJobs, ProtocolIngestionReplayResult, ProtocolIngestionStatus, ProtocolQuarantinedCandidate, ProtocolRefreshResult, ProtocolSettings, ProtocolSettingsUpdateResult, ReplayProtocolIngestionJobInput, UpdateSettingsInput as UpdateProtocolSettingsInput, } from './resources/protocols.js';
+export type { SocialProfile, SocialBridge, SocialSubscription, SocialSubscriptionChange, SocialProfilePage, SocialRadar, SocialRadarCluster, SocialRadarMember, SocialRadarParams, SocialRadarSourceKind, SocialRadarPosts, SocialRadarStory, SocialRadarStoryArchive, ViralBaseline, ViralItem, ViralItemFields, ViralItemSpread, ViralItemVelocity, ViralLabel, ViralMindsCard, ViralMindsItem, ViralNetwork, ViralOpenProtocol, ViralProtocol, ViralProvider, ViralReadMeta, ViralReadParams, ViralReadResponse, ViralReadStatus, ViralRef, ViralSocialItem, SocialNetwork, SocialPost, SocialConversation, SocialTrend, SocialTrendProvenance, SocialTrends, SocialTrendSourceIndex, SocialTrendFeed, SocialPopularProfiles, SocialAuthorFeed, OpenGroupThreads, OpenGroupThreadsGroup, OpenGroupThreadsParams, SocialFollowingFeed, SocialFollowingSource, SocialFollowingSourceStatus, SearchPublicProfilesParams, SearchPublicPostsParams, SocialPostSearch, HostedProtocolConnections, HostedProtocol, HostedProtocolIdentity, HostedNostrChallenge, HostedNostrIdentityProof, NativeNostrPrepareInput, NativeNostrPrepared, NativeNostrAccount, NativeNostrPostState, NativeNostrReceipt, NativeSocialProtocol, FederationIdentity, FederationIdentityView, NativeSocialAccount, NativeNetwork, NativeNetworkState, NativeNetworkPresence, NativeNetworkActivation, NativeNetworkOff, SetNativeNetworkInput, NativeSocialCallbackInput, NativeReplyPrepareInput, NativePostPrepareInput, NativeMediaInput, NativeMediaItem, NativePostBatch, NativePostQuote, NativePostHistory, NativeDelegatedPostHistoryItem, NativeNostrPostHistoryItem, NativeFollowSourceInput, NativeFollowPrepareInput, NativeFollowTarget, NativeFollowReceipt, NativeFollowState, NativeFollowAccount, NativeFollowStates, NativeFollowReview, NativeLikeSourceInput, NativeRepostSourceInput, NativeLikePrepareInput, NativeRepostPrepareInput, NativeLikeTarget, NativeRepostTarget, NativeLikeReceipt, NativeRepostReceipt, NativeLikeState, NativeRepostState, NativeLikeReview, NativeRepostReview, NativeReplyReceipt, NativeReplyBatch, NativeReplyHistory, NativeDelegatedReplyHistoryItem, NativeNostrReplyResult, NativeNostrReplyHistoryItem, NativeReplyRemovalReceipt, NativeReplyRemovalPreview, SocialSourceRef, SocialSourceControl, SocialSourceControlDisplay, SocialSourceControlChange, HostedPostPreview, ConnectHostedIdentityInput, CreateHostedIdentityInput, CreatedHostedProtocolIdentity, PreviewHostedPostInput, PublishHostedPostInput, ListProtocolCandidatesParams, ProtocolAdapterMaturity, ProtocolAdapterMetadata, ProtocolCandidateListResponse, ProtocolCandidatePageMeta, ProtocolCapabilityOperation, ProtocolCapabilityStatus, ProtocolCollectionStatus, ProtocolIngestionActivityReason, ProtocolIngestionCircuitHealth, ProtocolIngestionDeadLetterGroup, ProtocolIngestionHealthPosition, ProtocolIngestionHealthReport, ProtocolIngestionHealthRuntime, ProtocolIngestionHealthSection, ProtocolIngestionLaneActivity, ProtocolIngestionLaneCurrentJob, ProtocolIngestionLaneDeadLetters, ProtocolIngestionLaneHealth, ProtocolIngestionLaneJobs, ProtocolIngestionReplayResult, ProtocolIngestionStatus, ProtocolQuarantinedCandidate, ProtocolRefreshResult, ProtocolSettings, ProtocolSettingsUpdateResult, ReplayProtocolIngestionJobInput, 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';
@@ -272,7 +276,7 @@ export type { Swarm, SwarmMember, CreateSwarmInput, ListSwarmsParams, ScheduledT
 export { TemplatesResource } from './resources/templates.js';
 export type { Template, CreateTemplateInput, UpdateTemplateInput, ListTemplatesParams } from './resources/templates.js';
 export { MediaResource } from './resources/media.js';
-export type { GenerateImageInput, GeneratedImage, ImageProvider } from './resources/media.js';
+export type { GenerateImageInput, GeneratedImage, ImageProvider, MediaSourceApprovalInput, MediaSourceApprovalResponse } from './resources/media.js';
 export { RecursivError, AuthenticationError, AuthorizationError, LegacyHandoffError, NotFoundError, ValidationError, InsufficientCreditsError, RateLimitError, ConflictError, isActionRateLimitScope, EmailNotSentError, } from './errors.js';
 export type { RateLimitDetails } from './errors.js';
 export { parseSSE } from './lib/sse.js';

package/dist/index.js

@@ -3,6 +3,8 @@ import { DiscoveryResource } from './resources/discovery.js';
 export * from './resources/discovery.js';
 export * from './feed-definition.js';
 export * from './social-protocol-ids.js';
+import { TelemetryResource } from './resources/telemetry.js';
+export * from './resources/telemetry.js';
 import { HttpClient } from './client.js';
 import { AuthResource } from './resources/auth.js';
 import { PostsResource } from './resources/posts.js';
@@ -125,6 +127,7 @@ export class Recursiv {
     swarms;
     templates;
     media;
+    telemetry;
     webhooks;
     jobs;
     curator;
@@ -204,6 +207,7 @@ export class Recursiv {
         this.swarms = new SwarmsResource(client);
         this.templates = new TemplatesResource(client);
         this.media = new MediaResource(client);
+        this.telemetry = new TelemetryResource(client);
         this.webhooks = new WebhooksResource(client);
         this.jobs = new JobsResource(client);
         this.curator = new CuratorResource(client);

package/dist/resources/auth.d.ts

@@ -130,6 +130,8 @@ export interface VerifyOtpInput {
 export interface CreateApiKeyInput {
     name: string;
     scopes: string[];
+    /** ISO timestamp in the future, at most one year from creation. */
+    expiresAt?: string;
     /**
      * Optional human-readable note describing what the key is for. Stored on the
      * key record and surfaced in the dashboard / key listings.
@@ -197,6 +199,9 @@ export interface ApiKeyResult {
     scopes: string[];
     organizationId?: string | null;
     projectId?: string | null;
+    networkId?: string | null;
+    /** The server's stored expiry; null denotes a key without an expiry. */
+    expiresAt?: string | null;
     /** ISO timestamp of when the key was created. */
     createdAt?: string | null;
 }

package/dist/resources/deployments.d.ts

@@ -31,6 +31,42 @@ export interface CreateDeploymentInput {
     commit_hash?: string;
     commit_message?: string;
 }
+export interface DeploymentReleaseInput {
+    project_id: string;
+    /** Caller-generated random 32-byte secret, encoded as 64 lowercase hex characters. Never log or store in source. */
+    capability: string;
+    api_revision: string;
+    frontend_revision: string;
+    expected_frontend_revision: string;
+    frontend_deploy: boolean;
+    coordinator_repository: string;
+    run_id: number;
+    attempt: number;
+}
+export interface DeploymentRelease {
+    deployment_id: string;
+    status: string;
+    phase: 'reserved' | 'api_started' | 'api_verified' | 'started' | 'complete' | 'aborted';
+    api_revision: string;
+    frontend_revision: string;
+    expected_frontend_revision: string;
+    frontend_deploy: boolean;
+    coordinator_repository: string;
+    run_id: number;
+    attempt: number;
+    provider_deployment_id: string | null;
+    /** Non-secret recovery link; replay still requires both original and replacement capabilities. */
+    replacement_deployment_id: string | null;
+}
+export interface DeploymentReleaseOperation {
+    project_id: string;
+    capability: string;
+}
+export interface DeploymentReleaseRecoveryInput extends DeploymentReleaseOperation {
+    replacement: DeploymentReleaseInput;
+    /** Short-lived GitHub OIDC token from the main protected Promote workflow. Never log it. */
+    coordinator_identity_token: string;
+}
 export interface GetLogsParams {
     coolify_app_uuid: string;
     lines?: number;
@@ -146,6 +182,22 @@ export interface HostedServiceObservation extends HostedServiceReservation {
 export declare class DeploymentsResource {
     private client;
     constructor(client: HttpClient);
+    /** Atomically block competing production deployments before promoting the API. Retry explicitly with the SAME capability. */
+    reserveRelease(input: DeploymentReleaseInput): Promise<SingleResponse<DeploymentRelease>>;
+    getRelease(deploymentId: string, projectId: string): Promise<SingleResponse<DeploymentRelease>>;
+    /** Mark immediately before API mutation, then only after the existing API health gates pass. */
+    advanceRelease(deploymentId: string, input: DeploymentReleaseOperation & {
+        phase: 'api_started' | 'api_verified';
+        api_revision: string;
+    }): Promise<SingleResponse<DeploymentRelease>>;
+    /** Consume the authenticated reservation after API verification; an unknown earlier trigger is never replayed. */
+    startRelease(deploymentId: string, input: DeploymentReleaseOperation): Promise<SingleResponse<DeploymentRelease>>;
+    /** Abort before API mutation, or finish an API-only release after proving the frontend unchanged. */
+    finishRelease(deploymentId: string, input: DeploymentReleaseOperation & {
+        operation: 'abort_before_api' | 'complete_api_only' | 'complete_paired';
+    }): Promise<SingleResponse<DeploymentRelease>>;
+    /** Atomically hand a settled interrupted release to a new protected runner; retry explicitly with identical ownership. */
+    recoverRelease(deploymentId: string, input: DeploymentReleaseRecoveryInput): Promise<SingleResponse<DeploymentRelease>>;
     /** Prepare a stopped staging service from a maintained recipe. Requires an unbound owner key. */
     prepareHostedService(input: PrepareHostedServiceInput): Promise<SingleResponse<HostedServiceReservation>>;
     getHostedService(scope: HostedServiceScope): Promise<SingleResponse<HostedServiceObservation | null>>;

package/dist/resources/deployments.js

@@ -3,6 +3,29 @@ export class DeploymentsResource {
     constructor(client) {
         this.client = client;
     }
+    /** Atomically block competing production deployments before promoting the API. Retry explicitly with the SAME capability. */
+    reserveRelease(input) {
+        return this.client.post('/deployments/releases/reserve', input, { retry: false });
+    }
+    getRelease(deploymentId, projectId) {
+        return this.client.get(`/deployments/releases/${deploymentId}`, { project_id: projectId });
+    }
+    /** Mark immediately before API mutation, then only after the existing API health gates pass. */
+    advanceRelease(deploymentId, input) {
+        return this.client.post(`/deployments/releases/${deploymentId}/advance`, input, { retry: false });
+    }
+    /** Consume the authenticated reservation after API verification; an unknown earlier trigger is never replayed. */
+    startRelease(deploymentId, input) {
+        return this.client.post(`/deployments/releases/${deploymentId}/start`, input, { retry: false });
+    }
+    /** Abort before API mutation, or finish an API-only release after proving the frontend unchanged. */
+    finishRelease(deploymentId, input) {
+        return this.client.post(`/deployments/releases/${deploymentId}/finish`, input, { retry: false });
+    }
+    /** Atomically hand a settled interrupted release to a new protected runner; retry explicitly with identical ownership. */
+    recoverRelease(deploymentId, input) {
+        return this.client.post(`/deployments/releases/${deploymentId}/recover`, input, { retry: false });
+    }
     /** Prepare a stopped staging service from a maintained recipe. Requires an unbound owner key. */
     prepareHostedService(input) {
         return this.client.post('/deployments/hosted-services/prepare', input);

package/dist/resources/link-preview.d.ts

@@ -9,6 +9,8 @@ export interface LinkPreview {
     siteName: string | null;
 }
 export interface LinkPreviewResponse {
+    /** Relayed preview images expire; refetch their metadata before this time. */
+    media_expires_at?: string;
     /**
      * The preview, or null when the link cannot be previewed: the page refused a
      * server (a private repository, a paywall or bot wall), is not HTML, or could
@@ -69,5 +71,7 @@ export declare class LinkPreviewResource {
      * @example
      * const { data, refused } = await r.linkPreview.get(url, { messageId: message.id });
      */
-    get(url: string, source?: LinkPreviewSource | null): Promise<LinkPreviewResponse>;
+    get(url: string, source?: LinkPreviewSource | null, options?: {
+        projectId: string;
+    }): Promise<LinkPreviewResponse>;
 }

package/dist/resources/link-preview.js

@@ -28,8 +28,12 @@ export class LinkPreviewResource {
      * @example
      * const { data, refused } = await r.linkPreview.get(url, { messageId: message.id });
      */
-    async get(url, source) {
+    async get(url, source, options) {
         const params = { url };
+        if (options) {
+            params.project_id = options.projectId;
+            params.relay_media = '1';
+        }
         if (source != null) {
             // A source with no id must not turn into a bare request: the server would
             // then fetch the link with no check at all.

package/dist/resources/media.d.ts

@@ -12,9 +12,31 @@ export interface GeneratedImage {
     provider: ImageProvider;
     prompt: string;
 }
+export interface MediaSourceApprovalInput {
+    projectId: string;
+    sources: Array<{
+        host: string;
+        purpose: 'video' | 'audio' | 'player' | 'icon';
+    }>;
+}
+export interface MediaSourceApprovalResponse {
+    enabled: boolean;
+    enforce: boolean;
+    policy: string;
+    owned_hosts: string[];
+    sources: Array<{
+        host: string;
+        purpose: 'video' | 'audio' | 'player' | 'icon';
+        decision: 'approved' | 'relay' | 'pending';
+        expires_at: string | null;
+        proxy_url?: string | null;
+    }>;
+}
 export declare class MediaResource {
     private client;
     constructor(client: HttpClient);
+    /** Read cached automatic provider reviews. Sends host/purpose only; never initiates a policy or media fetch. */
+    sourceApprovals(input: MediaSourceApprovalInput): Promise<SingleResponse<MediaSourceApprovalResponse>>;
     /** Generate an AI image and return a URL for use in posts */
     generateImage(input: GenerateImageInput): Promise<SingleResponse<GeneratedImage>>;
 }

package/dist/resources/media.js

@@ -3,6 +3,10 @@ export class MediaResource {
     constructor(client) {
         this.client = client;
     }
+    /** Read cached automatic provider reviews. Sends host/purpose only; never initiates a policy or media fetch. */
+    sourceApprovals(input) {
+        return this.client.get('/media/source-approvals', { project_id: input.projectId, sources: JSON.stringify(input.sources) });
+    }
     /** Generate an AI image and return a URL for use in posts */
     generateImage(input) {
         return this.client.post('/media/generate', input);

package/dist/resources/protocols.d.ts

@@ -1118,8 +1118,12 @@ export interface SocialNetwork {
         url: string;
     };
     coverage: string;
-    /** `compass_filter`: the Politics filter is served to this viewer (an app offers it only then); listed on every network. */
-    capabilities: Array<'profile_search' | 'profile_read' | 'original_author_posts' | 'minds_subscription' | 'following_feed' | 'conversation_read' | 'public_trends' | 'trend_feed' | 'popular_accounts' | 'post_search' | 'compass_filter'>;
+    /**
+     * `compass_filter`: the Politics filter is served to this viewer (an app offers it only then); listed on every network.
+     * `compass_sides` (0.7.116): this viewer may also choose sides and Mix sides, not Hide politics alone; a visitor's
+     * catalog lists it where the operator serves visitors the whole filter. Without it, offer a visitor Hide politics only.
+     */
+    capabilities: Array<'profile_search' | 'profile_read' | 'original_author_posts' | 'minds_subscription' | 'following_feed' | 'conversation_read' | 'public_trends' | 'trend_feed' | 'popular_accounts' | 'post_search' | 'compass_filter' | 'compass_sides'>;
     profileSearchPagination: boolean;
     postSearchAccountRequired?: boolean;
     /** Categories available from the current app configuration. */
@@ -1288,6 +1292,48 @@ export interface SocialAuthorFeed {
     cursor: string | null;
     coverage: 'original_posts';
 }
+/** A Fediverse community (a Lemmy or PieFed community) as its threads page names it (0.7.109). */
+export interface OpenGroupThreadsGroup {
+    /** Stable (`ap-…`) and never a Minds group id: never send it to a Minds groups route. */
+    id: string;
+    network: 'activitypub';
+    /** The network as members read it ("ActivityPub"). */
+    network_label: string;
+    /** The community's Group actor id on its own server: the `group` its page is read by. */
+    nativeId: string;
+    /** `name@server`, as the network writes the community's address. */
+    handle: string;
+    name: string;
+    /** Plain text. */
+    description: string;
+    /** The host of the server it lives on. */
+    server: string;
+    /** A community is read here, not joined (phase 1). */
+    read_only: true;
+    joinable: false;
+}
+/** A page of a Fediverse community's newest threads (`getOpenGroupThreads`, 0.7.109). */
+export interface OpenGroupThreads {
+    group: OpenGroupThreadsGroup;
+    /** Each thread's opening post, newest first, after every floor the server applies for this member. */
+    items: SocialPost[];
+    /** The next page's opaque cursor, or null at the end of what the community's server listed. */
+    cursor: string | null;
+    /** The community's newest threads as its own server's outbox lists them; older threads are not read. */
+    coverage: 'community_outbox';
+    /** Present when `compass` asked for a filter: what Hide politics left out. */
+    compass_filter?: CompassFilterMeta;
+}
+export interface OpenGroupThreadsParams {
+    /** The community's Group actor id (an https address): the `actor` of a groups read's `open_network` entry. */
+    group: string;
+    /** 1 to 25; the server's default is 20. */
+    limit?: number;
+    /** The `cursor` of the page before, as it was given. */
+    cursor?: string;
+    /** A Politics choice as `getPublicTrends` takes it: `hide` leaves out the threads in politics. */
+    compass?: string;
+}
 export interface SocialTrendProvenance {
     discovery?: DiscoveryLayout;
     provider: {
@@ -1944,6 +1990,17 @@ export declare class ProtocolsResource {
         limit?: number;
         cursor?: string;
     }): Promise<SingleResponse<SocialAuthorFeed>>;
+    /**
+     * A Fediverse community's newest threads, read-only (0.7.109; GET /protocols/social/groups/threads): a Lemmy or PieFed
+     * community that a groups read (`communities.list`, the group recommender) lists under `open_network`, read by its
+     * `actor` as `group`. Every floor the server applies for this member is applied: the group words and tier-1 rules, the
+     * app's moderation and the member's own blocks and mutes of the community, authors who opted out of indexing, the term
+     * list and the safety verdict, and #nsfw threads unless the member turned Show NSFW on. Requires `users:read` and
+     * `posts:read` on the member's app key. A 404 means the app does not offer groups from other networks
+     * (OPEN_GROUPS_AP_ENABLED off) or does not list that community; a 400 an address it does not read; a 503 that the
+     * community's server could not be read.
+     */
+    getOpenGroupThreads(params: OpenGroupThreadsParams, options?: SocialReadOptions): Promise<SingleResponse<OpenGroupThreads>>;
     listSubscriptions(): Promise<SingleResponse<SocialSubscription[]>>;
     /** Recent originals from the current app user's followed accounts, with explicit source failures. */
     getFollowingFeed(params?: {

package/dist/resources/protocols.js

@@ -231,6 +231,23 @@ export class ProtocolsResource {
             protocol: params.protocol, actor: params.actor, limit: params.limit, cursor: params.cursor,
         });
     }
+    /**
+     * A Fediverse community's newest threads, read-only (0.7.109; GET /protocols/social/groups/threads): a Lemmy or PieFed
+     * community that a groups read (`communities.list`, the group recommender) lists under `open_network`, read by its
+     * `actor` as `group`. Every floor the server applies for this member is applied: the group words and tier-1 rules, the
+     * app's moderation and the member's own blocks and mutes of the community, authors who opted out of indexing, the term
+     * list and the safety verdict, and #nsfw threads unless the member turned Show NSFW on. Requires `users:read` and
+     * `posts:read` on the member's app key. A 404 means the app does not offer groups from other networks
+     * (OPEN_GROUPS_AP_ENABLED off) or does not list that community; a 400 an address it does not read; a 503 that the
+     * community's server could not be read.
+     */
+    getOpenGroupThreads(params, options) {
+        // Only the four keys the server's strict query schema takes, each only when given.
+        return this.client.get('/protocols/social/groups/threads', { group: params.group,
+            ...(params.limit !== undefined ? { limit: params.limit } : {}),
+            ...(params.cursor !== undefined ? { cursor: params.cursor } : {}),
+            ...(params.compass !== undefined ? { compass: params.compass } : {}) }, ...readOptions(options));
+    }
     listSubscriptions() {
         return this.client.get('/protocols/social/subscriptions');
     }

package/dist/resources/telemetry.d.ts

@@ -0,0 +1,17 @@
+import type { HttpClient } from '../client.js';
+import type { SingleResponse } from '../types.js';
+export type ProductEvent = 'auth.otp_verified' | 'community.join' | 'person.follow' | 'network.connect_started' | 'network.connect_finished' | 'social.follow_submitted' | 'social.like_submitted' | 'social.repost_submitted' | 'social.post_submitted' | 'social.reply_submitted' | 'signal' | 'screen.view';
+export interface ProductCountsInput {
+    counts: Array<{
+        event: ProductEvent;
+        count: number;
+    }>;
+}
+export declare class TelemetryResource {
+    private readonly client;
+    constructor(client: HttpClient);
+    /** Count reviewed events within the member's app. No paths, member IDs or properties; requires an app-bound key. */
+    productCounts(input: ProductCountsInput): Promise<SingleResponse<{
+        accepted: boolean;
+    }>>;
+}

package/dist/resources/telemetry.js

@@ -0,0 +1,10 @@
+export class TelemetryResource {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    /** Count reviewed events within the member's app. No paths, member IDs or properties; requires an app-bound key. */
+    productCounts(input) {
+        return this.client.post('/telemetry/product-counts', input, { retry: false });
+    }
+}

package/dist/types.d.ts

@@ -244,9 +244,11 @@ export interface MediaItem {
     unplayable?: boolean;
     /**
      * On an image only, in the member's own app with Sealed on: the time (ISO 8601) this read found the picture passed
-     * Minds' current checks (visibility, holds, adult labels). No hash-bank or image-classifier check runs. Absent for any
-     * other item, and whenever a check could not be read. Sealed sends a post picture only while this is under 24 hours
-     * old.
+     * Minds' current checks: visibility, holds and adult labels. Where the server's media-safety floor is on
+     * (CONTENT_MEDIA_SAFETY_ENABLED), one of those labels is a vision model's stored verdict that the picture is not
+     * suggestive; no image classifier is run for this field. No hash bank (NCMEC, StopNCII) and no CSAM classifier is
+     * among the checks, so run your own. Absent for any other item, and whenever a check could not be read. Sealed sends
+     * a post picture only while this is under 24 hours old.
      */
     checked_at?: string;
     /**
@@ -394,6 +396,7 @@ export interface PostRepliesPage {
         next_cursor: string | null;
     };
 }
+export type PostDestination = 'minds' | 'activitypub' | 'atproto' | 'nostr';
 export interface CreatePostInput {
     content: string;
     content_format?: 'plain' | 'markdown';
@@ -405,6 +408,8 @@ export interface CreatePostInput {
     /** Tag names to resolve or create atomically when the post is published. */
     tag_names?: string[];
     media_urls?: string[];
+    /** Exact publishing selection. Include minds; omitted only by legacy clients. */
+    destinations?: PostDestination[];
 }
 export interface CreatedPost {
     id: string;

package/llm.md

@@ -28,6 +28,7 @@ const r = new Recursiv() // reads RECURSIV_API_KEY from env
 | Receive external webhooks (Stripe, etc.) | `r.webhooks.register()` | Custom webhook server |
 | Server-side cron / scheduled tasks | `r.jobs.create()` | External cron services |
 | A member's engagement signals (views, dwell, hides) | `r.signals.batch()` | Raw fetch to `/signals/*`, or a resource's `client` |
+| Coarse first-party product counts | `r.telemetry.productCounts()` | Member IDs, paths, URLs or arbitrary event properties |
 
 **IMPORTANT:** Do NOT store structured app data (records, inventory, tasks, settings) as JSON inside `r.posts.content`. Posts are for social content. Use `r.databases` for application data.
 
@@ -99,6 +100,8 @@ const { data: logs } = await r.projects.deploymentLogs(project.id, deployment.id
 
 Methods: `list`, `get`, `create`, `delete`, `deploy`, `executeCode`, `sandbox`, `createSandbox`, `stopSandbox`, `deployment`, `deploymentLogs`, `deployments`
 
+Operator API/frontend coordination: `r.deployments.reserveRelease(input)`, `getRelease(releaseId, projectId)`, `advanceRelease(releaseId, input)`, `startRelease(releaseId, input)`, `finishRelease(releaseId, input)`, `recoverRelease(originalReleaseId, input)`. Example read: `const { data: release } = await r.deployments.getRelease(releaseId, projectId)`. Use a project-bound `projects:read`/`projects:write` operator key; follow [shared release phases, live proof and recovery](../../docs/deploy/shared-releases.md). Keep capabilities out of logs; uncertain operations retain ownership.
+
 ### r.storage — Bucket-based file storage
 
 ```typescript
@@ -389,10 +392,10 @@ const session = await r.auth.signUp({ name: 'Jane', email: 'jane@example.com', p
 const session = await r.auth.signIn({ email: 'jane@example.com', password: 'secure12345!' })
 
 const key = await r.auth.createApiKey(
-  { name: 'my-key', scopes: ['posts:read', 'agents:write'], description: 'CI bot' },
+  { name: 'my-key', scopes: ['posts:read', 'agents:write'], description: 'CI bot', expiresAt: new Date(Date.now() + 90 * 24 * 60 * 60 * 1000).toISOString() },
   session.token,
 )
-// key: { key, id, name, prefix, lastFourChars, scopes, createdAt }
+// key: { key, id, name, prefix, lastFourChars, scopes, projectId, networkId, expiresAt, createdAt }
 
 await r.auth.signOut(session.token)
 ```
@@ -401,6 +404,7 @@ await r.auth.signOut(session.token)
 Bearer auth, with a Cookie fallback for native/server runtimes. `getSession`
 also answers `session: { id, expiresAt }`; an API-key client lists sessions with
 `is_current: false`, so it matches `session.id` to mark its own device.
+`createApiKey` requires a signed-in session; optional `expiresAt` is a future ISO timestamp at most one year away. Validate the receipt's stored `projectId`, `networkId` and `expiresAt` before storing an operator key, and never log its key value.
 
 Methods: `signUp`, `signIn`, `getSession`, `signOut`, `createApiKey`, `signInAndCreateKey`, `signUpAndCreateKey`, `verifyOtpAndCreateKey`
 
@@ -825,6 +829,18 @@ Methods: `list`, `get`, `create`, `delete`
 
 ## Platform Resources
 
+### r.telemetry — First-party aggregate product counts
+
+`productCounts({ counts: [{ event, count }] })` sends reviewed event totals under a human member's project-bound key with `users:write`. It is unbillable, including for a free project with zero credits; authentication, scopes and rate limits still apply. No anonymous or agent keys. Only counts are stored in a network/project/UTC-day bucket, retained at most 30 days; member IDs, session IDs, paths, URLs and extra properties are refused. Use `r.signals` separately for personal feed ranking.
+
+`event` is `auth.otp_verified`, `community.join`, `person.follow`, `network.connect_started`, `network.connect_finished`, `social.follow_submitted`, `social.like_submitted`, `social.repost_submitted`, `social.post_submitted`, `social.reply_submitted`, `signal` or `screen.view`. Each `count` is an integer from 1 to 1000; send 1-12 entries. Do not replay an accepted batch: counts increment, and the SDK deliberately does not retry this optional write. `{ data: { accepted: false } }` means storage was unavailable, not that the member's action failed. Catch request failures without blocking the app.
+
+```typescript
+// r holds the signed-in member's app-bound key; send no route or member properties.
+const result = await r.telemetry.productCounts({ counts: [{ event: 'screen.view', count: 1 }] }).catch(() => null)
+const counted = result?.data.accepted === true
+```
+
 - `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?, sealed_adult? })`; `content.default_feed_chosen` is true once the member set `default_feed` themselves (absent on older APIs). `privacy.age_is_adult` is true only when the member answered the age question 18 or older (false for 13-17 and for no answer; only their own preferences carry it). `content.sealed_adult` is the Sealed adult-content setting: it reads true only while it is on and the member is a known adult, and `updateContent({ sealed_adult: true })` from anyone else throws `AuthorizationError` with code `sealed_adult_needs_adult` and saves nothing in that request; `sealed_adult: false` is always accepted. Both are absent on older APIs (treat as false). 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`, `viewing_off`, `rate_limited`, or for `record` `duplicate`). `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. Only from a public place, never a private message: a `metadata` key or placement (`surface`, `feed`, `source`, `context`, `route`...) naming a chat, DM, inbox, encrypted or Sealed conversation by any spelling (`chatList`, `dmThread`, `/messages/1`) answers 400 (`private_surface`) and nothing in that request is stored; this is read on the metadata as sent, before any key is dropped. An app names its own public places (`{ source: 'discover' }`). In the Minds app a `surface` must be one of `SignalSurface`'s names other than `other` (each a public place the server lists), a `feed`, `source`, `via` or `layoutSource` one the server lists (its feeds, Discover, Watch, stories, the pager and post cards), and any other key naming a place (`context`) is refused there too. With the member's "Use what I watch and read to personalize" off (`settings.updateContent({ personalize_from_viewing: false })`, on by default), only views and explicit choices are stored and `withheld` counts the dwell and opens left out. `clearViewingHistory()` (DELETE /signals/history) is "Clear my viewing history": the member's views, dwell, Watch time and opens in this app are deleted; their hides, "More like this", saves, shares and votes stay. Ingest contract (0.7.93): `metadata` is `SignalMetadata`; the server keeps only its keys (`surface`, `feed`, `block`, `position`, `slot`, `category`, `ref`, `watch_ms`, `duration_ms`, `completed`, `loops`, `sound_on`, `exit` (`swipe`/`leave`/`hide`/`tap`), `visible_count`, `autoplay`, `client_event_id`, `session_seq`, `via`, `source`, `presentation`) and drops the rest; a listed key of the wrong type or past its limit refuses that event (batch: `rejected` + the first ten `rejections` `{ index, reason, key }`, the rest stored; record: 400 `invalid_signal`). `batch`/`record` add a `client_event_id` to each event without one (the same id each time that object is sent), so a retry is stored once (`duplicates`). An open-network item is named by `metadata.ref` (`<protocol>/<native id>`, `cluster:<id>`, `today:<uuid>`). Watch time is held to `duration_ms` x (`loops` + 1) and to the wall clock, a card's dwell to 5 min; a watch under 1 s ending in `exit: 'swipe'` is stored as a skip. Past 600 events a minute per member the rest are `limited` (record: `reason: 'rate_limited'`).
 
@@ -846,7 +862,7 @@ const showCheckedLine = isFactLive('sealed.attest_before_send', capabilities, {
 - `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)
+- `r.deployments` — App deployment management plus protected API/frontend reservations (`reserveRelease`, `getRelease`, `advanceRelease`, `startRelease`, `finishRelease`, `recoverRelease`); see the [shared release guide](../../docs/deploy/shared-releases.md). Use `r.projects.deploy()` for ordinary app deploys.
 - `r.integrations` — External service integrations and agent tool connections. Connections: `listConnections(orgId)`, `connect()`, `confirmConnection()`. Deterministic tool execution (no agent/LLM in the loop): `executeTool({ connection_id, tool, arguments })` — run a tool yourself with explicit args + pagination and get the raw result back (e.g. `{ tool: 'GMAIL_FETCH_EMAILS', arguments: { query, max_results } }`); use for reliable batch coverage, vs `agents.chat` for autonomous behavior. Tool approvals: `listPendingExecutions(conversationId)`, `approveExecution(id)`, `rejectExecution(id)` — handles both integration tools and brain/platform tools (provision_sandbox etc.); use these to unblock a permission-mode agent waiting on tool approval
 - `r.email` — Email campaigns, batch sending, and transactional email. **Pass `category: 'transactional'`** for receipts, invites, confirmations and alerts: `r.email.send({ to, subject, html, category: 'transactional' })`. Without it the send is treated as marketing and held for anyone who has not given marketing consent. A send where every recipient was held throws `EmailNotSentError` (its message carries the reason). A `status: 'partial'` result lists each recipient's `status` and `reason` in `messages`.
 - `r.webhooks` — Register inbound webhook endpoints: `register()`, `list()`, `delete()`. Webhook events execute handler code in project sandbox.
@@ -873,17 +889,17 @@ await r.appSubscriptions.changeTier({ tier: 'pro', proration_date: quote.prorati
 - Native follows: `nativeFollowState({ accountId, protocol, nativeId })`, `prepareNativeFollow({ clientMutationId, accountId, protocol, nativeId, action: "follow" | "unfollow" })`, `submitNativeFollow(id, { approve: true, event? })`, `nativeFollowStatus(id)`. Show the acting identity and native following/requested/unfollowed state separately from the Minds feed subscription. Nostr must sign the complete review event without dropping other contacts; stale lists require a fresh review. Keep mutation IDs and reconcile ambiguous outcomes without replay. Requires current follow scopes and API `NATIVE_SOCIAL_FOLLOW_PROJECTS` plus source controls.
 - Native reposts: `nativeRepostState({ accountId, protocol, nativeId })`, `prepareNativeRepost({ clientMutationId, accountId, protocol, nativeId, action: "repost" | "unrepost" })`, `submitNativeRepost(id, { approve: true, event? })`, `nativeRepostStatus(id)`. Requires `NATIVE_SOCIAL_REPOST_PROJECTS`, account capability and explicit approval; Nostr signs the exact review (kind 6 or own kind 5). Unknown attempts only reconcile. Bluesky connections need the new repost scope; ActivityPub uses write:statuses. Native likes: `nativeLikeState({ accountId, protocol, nativeId })`, `prepareNativeLike({ clientMutationId, accountId, protocol, nativeId, action: "like" | "unlike" })`, `submitNativeLike(id, { approve: true, event? })`, and `nativeLikeStatus(id)`. Display the selected account, source and action before approval. Only Nostr supplies `event`: sign the exact public `signing.event` in the review; never transmit a private key. Preserve mutation IDs on ambiguous responses and refresh unknown results instead of resending. Read capabilities before offering actions; old reply-only connections need reconnecting for likes. Nostr results describe the connected relay, not every public relay. The app-specific `NATIVE_SOCIAL_LIKE_PROJECTS` switch and source controls must be enabled on the API.
 - Delegated social accounts: `r.protocols.nativeSocialAccounts()`, `startNativeSocialConnection({ protocol, identifier })`, `finishNativeSocialConnection({ protocol, state, code?, iss?, error? })`, `disconnectNativeSocialAccount(id)`. Example: `const { data } = await r.protocols.startNativeSocialConnection({ protocol: "bluesky", identifier: "alice.bsky.social" })`; open `data.authorizationUrl`, then complete with the same signed-in app user. Never log callback codes, send passwords, or auto-retry OAuth callbacks. Shared replies (off until schema/API deployment and live verification): `prepareNativeReply({ clientMutationId, text, parent: { protocol, nativeId, readRef? }, accountIds, media?, linkedPostAccountIds?, recoverFrom?: { batchId, deliveryIds } })`, `submitNativeReply(id, { approve: true, deliveryIds })`, `nativeReplyStatus(id)`, `nativeReplyHistory({ limit?, cursor? })`, `prepareNativeReplyRemoval(id, { deliveryIds })`, `removeNativeReply(id, { approve: true, removals })`. Review account, destination, `kind`, source, exact `wireText` and every reviewed `media` item with its alt text; connection is not publication approval. `media` takes the same `NativeMediaInput[]` as `prepareNativePost` and needs the account's `publish_media` capability. `linkedPostAccountIds` explicitly selects different-network standalone posts with a source link, never matching threaded replies or a same-network denial fallback. Preserve mutation IDs, show per-destination results and reconcile uncertain attempts without reposting. To review selected unsent or definitively rejected deliveries again, use recoverFrom with a new mutation ID, the same source/accounts and freshly reviewed text; preserve that ID on uncertain preparation. Only saved recoverable destinations qualify, current gates still apply, and replacedBy disables old sends atomically. Never restart unknown, accepted or published deliveries. The new preview still needs explicit approval. Saved delegated drafts/results: `const { data: history } = await r.protocols.nativeReplyHistory({ limit: 20 })`; use its opaque cursor for the next page and `nativeReplyStatus(item.id)` for details. This is a private read, not a write or provider refresh, and includes Nostr results marked type=nostr. Use nativeNostrReplyResult(item.id) to check that recorded event on its relay without signing or resending. Discard page state on owner/app changes. See README for examples and the callback, revocation and removal contracts.
-- `r.protocols` — Private app safety: `sourceControls` returns current `enabled` plus paged saved choices; `setSourceControl`, `onSourceControlChange` and `reportSource` share app scope. Example: `const choices = new Map(); const stop = r.protocols.onSourceControlChange(change => choices.set(JSON.stringify([change.source, change.control]), change.enabled));` then `await r.protocols.setSourceControl({ source: { protocol: "bluesky", kind: "actor", nativeId: "did:plc:aaaaaaaaaaaaaaaaaaaaaaaa" }, control: "mute", enabled: true, scope: "minds" });` and call `stop(); choices.clear()` on account change/unmount. Notifications follow an exact server confirmation, never an uncertain response. These preferences and reports apply in Minds, not on the remote network. Open network ids (0.7.87, readers first): `import { SOCIAL_PROTOCOL_IDS, isSocialProtocolId } from '@recursiv/sdk'` lists every network a post, account or `SocialSourceRef` may name: bluesky, activitypub, nostr and farcaster (a Farcaster account by its FID, "3"; a cast by `<fid>:0x<40 lowercase hex>`). Listing an id serves nothing: read only what `publicNetworks()` lists, and skip an id this SDK does not know. Writes stay narrower: a native reply, follow, like or repost takes only `NATIVE_WRITE_PROTOCOLS` (bluesky, activitypub, nostr; `isNativeWriteProtocol(post.protocol)` before offering one), and a feed top's `networks` always names those three while a Farcaster lane may be absent (`networks.farcaster ?? []`). Keyless post links: `const visitor = new Recursiv({ anonymous: true, inheritEnvironmentApiKey: false }); const { data: thread } = await visitor.protocols.getSharedConversation(projectId, { protocol: 'nostr', post: publicEventId })`; `sharedNetworks(projectId)` lists public conversation capabilities. Only configured apps; app moderation and rate limits apply, no member state or write authority. Member public reading: `publicNetworks`, `searchPublicProfiles`, `getPublicProfile`, `getPublicAuthorFeed`, `getFollowingFeed`, `getPublicConversation`, `getPublicTrends`, `getPublicTrendFeed`; private app subscriptions: `listSubscriptions`, `subscribeToProfile`, `unsubscribeFromProfile`, `onSubscriptionChange`. `getFollowingFeed` sources: a slow account is `late` (status `late`, or `ok` with `late: true` while its held first page is shown; older APIs say `unavailable` with `late: true`), never a failure: read the next page for its posts (`lateNetworks` names its network). 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. The author's own thread (0.7.81): `thread` holds the focus author's continuation below the post, oldest first (a "1/" post's 2/, 3/, 4/ ..., at most 20 parts, each held to the same moderation and member controls as a reply); its first part is not repeated in `replies`, so render `focus`, `thread`, then `replies` (`thread ?? []`: older APIs omit it, and a `replies: 'none'` read answers none). A card (a post shared into a chat, a link preview) asks for the post alone, 0.7.78: `getPublicConversation({ protocol, post, replies: 'none' })` (also `getSharedConversation` and `getConnectedSocialConversation`) answers `focus` with no `ancestors` or `replies` and `repliesStatus: 'not_requested'`; a Nostr note answers from one relay read instead of a whole thread's. An older API answers 400 `invalid_input`: read without it. 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`.
+- `r.protocols` — Private app safety: `sourceControls` returns current `enabled` plus paged saved choices; `setSourceControl`, `onSourceControlChange` and `reportSource` share app scope. Example: `const choices = new Map(); const stop = r.protocols.onSourceControlChange(change => choices.set(JSON.stringify([change.source, change.control]), change.enabled));` then `await r.protocols.setSourceControl({ source: { protocol: "bluesky", kind: "actor", nativeId: "did:plc:aaaaaaaaaaaaaaaaaaaaaaaa" }, control: "mute", enabled: true, scope: "minds" });` and call `stop(); choices.clear()` on account change/unmount. Notifications follow an exact server confirmation, never an uncertain response. These preferences and reports apply in Minds, not on the remote network. Open network ids (0.7.87, readers first): `import { SOCIAL_PROTOCOL_IDS, isSocialProtocolId } from '@recursiv/sdk'` lists every network a post, account or `SocialSourceRef` may name: bluesky, activitypub, nostr and farcaster (a Farcaster account by its FID, "3"; a cast by `<fid>:0x<40 lowercase hex>`). Listing an id serves nothing: read only what `publicNetworks()` lists, and skip an id this SDK does not know. Writes stay narrower: a native reply, follow, like or repost takes only `NATIVE_WRITE_PROTOCOLS` (bluesky, activitypub, nostr; `isNativeWriteProtocol(post.protocol)` before offering one), and a feed top's `networks` always names those three while a Farcaster lane may be absent (`networks.farcaster ?? []`). Keyless post links: `const visitor = new Recursiv({ anonymous: true, inheritEnvironmentApiKey: false }); const { data: thread } = await visitor.protocols.getSharedConversation(projectId, { protocol: 'nostr', post: publicEventId })`; `sharedNetworks(projectId)` lists public conversation capabilities. Only configured apps; app moderation and rate limits apply, no member state or write authority. Member public reading: `publicNetworks`, `searchPublicProfiles`, `getPublicProfile`, `getPublicAuthorFeed`, `getFollowingFeed`, `getPublicConversation`, `getPublicTrends`, `getPublicTrendFeed`; a Fediverse community a groups read lists under `open_network` (0.7.109): `const { data: page } = await r.protocols.getOpenGroupThreads({ group: entry.actor, limit: 20 })` reads its newest threads read-only (`page.group`, `page.items`); `limit` is 1 to 25, `compass: 'hide'` leaves out the threads in politics, and the next page passes `cursor: page.cursor` while it is set (404 while the app does not offer groups from other networks); private app subscriptions: `listSubscriptions`, `subscribeToProfile`, `unsubscribeFromProfile`, `onSubscriptionChange`. `getFollowingFeed` sources: a slow account is `late` (status `late`, or `ok` with `late: true` while its held first page is shown; older APIs say `unavailable` with `late: true`), never a failure: read the next page for its posts (`lateNetworks` names its network). 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. The author's own thread (0.7.81): `thread` holds the focus author's continuation below the post, oldest first (a "1/" post's 2/, 3/, 4/ ..., at most 20 parts, each held to the same moderation and member controls as a reply); its first part is not repeated in `replies`, so render `focus`, `thread`, then `replies` (`thread ?? []`: older APIs omit it, and a `replies: 'none'` read answers none). A card (a post shared into a chat, a link preview) asks for the post alone, 0.7.78: `getPublicConversation({ protocol, post, replies: 'none' })` (also `getSharedConversation` and `getConnectedSocialConversation`) answers `focus` with no `ancestors` or `replies` and `repliesStatus: 'not_requested'`; a Nostr note answers from one relay read instead of a whole thread's. An older API answers 400 `invalid_input`: read without it. 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`.
   - Native Nostr: `const { data: preview } = await r.protocols.prepareNativeNostr(identityId, { action: "publish", content: draft })`; review and sign the exact public event, then `submitNativeNostr(identityId, { intent: preview.intent, event, approve: true })`. Preparation/submission never auto-retry. After uncertainty, use `getNativeNostrPost(identityId, preview.postId ?? preview.eventId)` before a user-selected retry of the identical intent/event: deletion checks the original note's `postId`, publication checks `eventId`. Check `nativeNostrAccount()` enablement first; keys stay with the signer. For replies, after `nativeNostrAccount()` advertises `reply_text_note`, use `prepareNativeNostr(identityId, { action: "reply", content: draft, parentId: post.nativeId })`. Review returned parent/root/participants/relay and exact event, sign with the connected client signer, then `submitNativeNostr(identityId, { intent, event, approve: true })`. Requires users:read, posts:read and posts:write. Kind1 public notes only; reply enablement and shared UI/live proof remain pending. Do not inherit arbitrary notification tags or relay hints. Signing mutations never auto-retry; check `getNativeNostrPost(identityId, eventId)` after uncertainty before a user-selected identical-event retry.
   - Native networks (0.7.89): every eligible member is on ActivityPub, AT Protocol and Nostr by rule. `const { data } = await r.protocols.networks()` lists `{ network, state, reason, mode, handle, engageDefault }` (read-only; `ready` = set up on their first post or interaction, show "Will be set up when you first post or interact"). `activateNetwork(network)` = "Set up now" (`pending` + `retryAt` over budget; 409 `network_off` after the member's off switch). `setNetwork(network, { enabled: false, removePast: true })` turns it off and removes what was shared; `{ enabled: true }` turns it back on (403 `network_locked`, 409 `not_rolled_out`/`age_band_required`). Needs users:read (+ users:write to change). A linked outside account is a Settings choice, never a step in a main flow.
   - Hosted Bluesky account on the app's own PDS: `const { data } = await r.protocols.createHostedIdentity({ protocol: 'atproto', handle: 'alice', email })`. Only the label is sent; `data.handle` carries the domain and `data.password` is returned this once, never stored. Never auto-retried. Either the account is finished or it is removed again. 409 `handle_unavailable` = choose another label; 503 `handle_dns_unavailable`/`handle_unresolvable`/`handle_unverified` = operator setup, retry later unchanged.
   - 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`. With no category about one row in four is an open-network clip (0.7.78): `isWatchNetworkClip(row)` tells `{ kind: 'social', id, post: SocialPost }` from a `Post`; open and react to it as the network's post (its `id` is never a Minds id).
   - 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; 0.7.80: never a post with no picture or clip and no engagement while the screen holds one with either, which then leads: media and engagement, else media, else engagement, as `mergeDiscoveryArrival` leads a feed's top and the feed after a line), 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. 0.7.84: a featured module carries `theme` only when its lead window was themed so and most of its own posts were judged into that category (a category feed's posts, by the read's category filter); a feed with no category titles every module by its kind alone ("Videos", not "Videos in Technology" over an unjudged Nostr clip). A post is shown once by every identity (`discoveryItemIdentities(item)`: its key, an open-network post's network id, and each media file by address and by content hash, so a second note carrying the same clip is the same post) across a session's pages, a progressive feed's sources (`withoutSeenItems` takes identities or keys), `mergeDiscoveryArrival` and gallery pooling; `withoutRepeatedDiscoveryItems(rows, shown)` does the same for an app's own rows.
-  - 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.
+  - 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`, and a side or `mix` only where the catalog lists `compass_sides`). 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?, 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.
+  - 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`, and a side or `mix` only where the catalog lists `compass_sides`, 0.7.116; 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; `compass_sides` (0.7.116) says the viewer may choose sides and Mix too (a visitor only where the operator serves visitors the whole filter).
   - 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`.
@@ -1083,3 +1099,9 @@ Bluesky quote: accounts must advertise `quote`; call `prepareNativePost({clientM
 Public post search (API/SDK 0.7.35): `const { data: page } = await r.protocols.searchPublicPosts({ protocol: 'nostr', query: 'open social', limit: 10 })`. Bluesky/ActivityPub require a selected `accountId` from `nativeSocialAccounts()` with `post_search`; older Bluesky grants must reconnect with consent. Open their results with `getConnectedSocialConversation({ protocol, accountId: page.readerAccountId, post: item.nativeId, readRef: item.readRef })` and pass the same accountId to `reportSource` for post reports. Nostr uses `getPublicConversation`. Pages report provider/observedAt and bounded coverage; no invented exhaustive or global search. Keep cursors paired with the exact owner, query, account, limit and connection revision. No writes, credentials or new ingestion are part of search.
 
 Topic browsing can request `getPublicTrends({ protocol: "bluesky", includePreviews: true })`. Optional `SocialTrend.preview` is a real image-bearing post from that topic, never a generated illustration. The server samples at most eight posts for each of ten topics, with three concurrent reads and a shared 2.5-second deadline; missing images leave usable text topics. App moderation and user source controls filter previews on every request. Bluesky CDN image attachments, quote-with-media images, and unlabeled link-preview thumbnails are supported; omitted content retains the source link.
+
+## Public media privacy
+
+`await r.media.sourceApprovals({ projectId, sources: [{ host: 'www.youtube-nocookie.com', purpose: 'player' }] })` reads only cached judgments for a registered app. Respect `enabled`, `enforce`, exact `owned_hosts` and expiry; unknown/stale provider results remain pending. Static images/icons stay relayed. A judgment permits only its exact host and purpose, and does not establish downstream player hosts or tenant ownership.
+
+`await r.linkPreview.get(url, { messageId }, { projectId })` opts a signed-in chat preview into expiring opaque image/icon URLs. Keep previews in a source/member-bound memory cache, refresh before `media_expires_at`, clear on sign-out, and never fall back to a bare private chat URL. Existing two-argument calls preserve their wire behavior.

package/package.json

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