@recursiv/sdk 0.7.89 → 0.7.96

package/README.md

@@ -100,7 +100,7 @@ for await (const chunk of r.agents.chatStream(agent.id, { message: 'Hello!' }))
 | `r.communities` | `create`, `join`, `search`, `members` |
 | `r.chat` | `send`, `dm`, `createGroup` (`encrypted: true` for an end-to-end encrypted group, 0.7.59), `messages` (cursor paging), `acceptRequest`, `declineRequest`, `leave`, `deleteConversation`; a private group's admin: `addMembers`, `removeMember`, `updateGroup` (0.7.59); photos and voice notes: `uploadAttachment`, `signAttachments` (private chat storage, 0.7.82) |
 | `r.tags` | `create`, `list` |
-| `r.signals` | `batch` (up to 100 engagement signals, such as views, dwell and hides, for the member's own ranking; `keepalive` for a page-leave flush), `record` (one signal) (0.7.71) |
+| `r.signals` | `batch` (up to 100 engagement signals, such as views, dwell and hides, for the member's own ranking; `keepalive` for a page-leave flush), `record` (one signal) (0.7.71); `clearViewingHistory` ("Clear my viewing history"); typed `SignalMetadata`, an id per event so a retry is stored once, and `duplicates`/`limited`/`rejected` in the answer (0.7.93) |
 | `r.privacy` | `capabilities` (the platform privacy facts the deployed API's build enforces, and its commit); pair with `@recursiv/sdk/privacy` (`PRIVACY_FACTS`, `isFactLive`, `liveFacts`) (unreleased) |
 | `r.curator` | `today` (World Today; a world story can carry `story_key` and `discussion`, its count across networks), `storyPosts` / `memberStoryPosts` (one page of a story's posts, keyless or under the member's key), `storyPostPages` (walk every page), `forYou`, `run`, `refreshIfStale`, `seedDeck` |
 | `r.uploads` | `uploadMedia` — upload post/chat bytes end to end |
@@ -120,6 +120,7 @@ for await (const chunk of r.agents.chatStream(agent.id, { message: 'Hello!' }))
 | `r.integrations` | External service connections |
 | `r.admin` | User management, stats, content reports (`listReports`, `resolveReport`, `dismissReport`) |
 | `r.moderation` | Moderation actions: `publicLog`, `mine`, `appeal`; staff `apply`, `resolveAppeal`, `list({ target_type?, target_id? })` (one target's recorded actions, newest first, at most 100; none named = the network's latest; 0.7.74) and `reverse(actionId)` (sent once: a repeat answers 404 `action_not_found`; 0.7.74); agent grants `listAgentGrants`, `grantAgent`, `revokeAgent` |
+| `r.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 |

package/dist/index.d.ts

@@ -60,6 +60,7 @@ import { JobsResource } from './resources/jobs.js';
 import { CuratorResource } from './resources/curator.js';
 import { ReportsResource } from './resources/reports.js';
 import { ModerationResource } from './resources/moderation.js';
+import { TrustResource } from './resources/trust.js';
 import { JudgmentsResource } from './resources/judgments.js';
 import { LinkPreviewResource } from './resources/link-preview.js';
 import { SearchResource } from './resources/search.js';
@@ -134,6 +135,8 @@ export declare class Recursiv {
     readonly boosts: BoostsResource;
     readonly reports: ReportsResource;
     readonly moderation: ModerationResource;
+    /** The signed trust log: its public keys, and the member's own signed events (0.7.96). */
+    readonly trust: TrustResource;
     /** Jev's labels of a post: read them, dispute or appeal one, and (staff) review a dispute. */
     readonly judgments: JudgmentsResource;
     readonly linkPreview: LinkPreviewResource;
@@ -216,7 +219,9 @@ export type { ReportTargetType, ReportStatus, CreateReportInput, ReportRecord, R
 export { JudgmentsResource, isJudgmentSharedWordsError } from './resources/judgments.js';
 export type { JudgmentSubjectKind, JudgmentSource, JudgmentOverrideMethod, PostLabelsStatus, PostLabelsQuery, PostLabelsSubject, PostLabelsCategory, PostLabelsPolitics, PostJudgmentRecord, PostJudgment, PostSafetyAttribution, PostLabelsCategoryView, PostLabelsSummaryView, PostLabelsFullView, PostLabels, DisputeJudgmentInput, JudgmentDispute, ReviewJudgmentInput, JudgmentReviewUpheld, JudgmentReviewAwaitingReviewer, JudgmentReviewOverridden, JudgmentReview, JudgmentSharedWordsDetails, JudgmentSharedWordsError, } from './resources/judgments.js';
 export { ModerationResource } from './resources/moderation.js';
-export type { ModerationTargetType, ModerationActionType, ModerationAppealStatus, ModerationPrinciple, PublicModerationAction, PublicModerationLog, OwnModerationAppeal, OwnModerationAction, OwnModerationLog, ApplyModerationActionInput, ModerationAction, ListModerationActionsParams, RecordedModerationTargetType, AgentModerationMode, AgentModerationGrant, } from './resources/moderation.js';
+export type { ModerationTargetType, ModerationActionType, ModerationAppealStatus, ModerationPrinciple, PublicModerationAction, PublicModerationLog, OwnModerationAppeal, OwnModerationAction, OwnModerationLog, ApplyModerationActionInput, ModerationAction, ListModerationActionsParams, RecordedModerationTargetType, AgentModerationMode, AgentModerationGrant, ModerationTrustStatus, ModerationTrustLog, ModerationTrustWindow, } from './resources/moderation.js';
+export { TrustResource } from './resources/trust.js';
+export type { TrustEnvelope, OwnTrustEvent, TrustPublicKey, OwnTrustEvents } from './resources/trust.js';
 export { LinkPreviewResource } from './resources/link-preview.js';
 export { SEARCH_SECTIONS, SearchResource } from './resources/search.js';
 export type { PublicSearchPage, PublicSearchTab, SearchAnswer, SearchGroup, SearchLadder, SearchOmitReason, SearchParams, SearchPerson, SearchPost, SearchRelated, SearchResponse, SearchSection, SearchStage, SearchStory, SearchTopic, SearchVia, } from './resources/search.js';
@@ -225,8 +230,8 @@ export { FEED_TOP_NETWORKS, FeedsResource } from './resources/feeds.js';
 export type { FeedStoriesParams, FeedStoriesResponse, FeedStory, FeedTopExplain, FeedTopItem, FeedTopMeta, FeedTopNetwork, FeedTopNetworkCard, FeedTopNetworkEntry, FeedTopNetworkMap, FeedTopParams, FeedTopResponse, FeedTopTarget, PublicFeedTopMeta, PublicFeedTopParams, PublicFeedTopResponse, } from './resources/feeds.js';
 export type { BookmarkCollection, BookmarkCollectionInput, BookmarkCollectionKind, BookmarkCollectionPatch, BookmarkCollectionsList, BookmarkCollectionTarget, BookmarkCollectionVisibility, BookmarkedPost, BookmarkInput, BookmarkItem, BookmarkKey, BookmarkKeyRow, BookmarkKeysPage, BookmarkKind, BookmarkMergeItem, BookmarkMergeResult, BookmarkProtocol, BookmarkRequestOptions, BookmarksPage, FiledBookmark, RemovedBookmarkCollection, SavedBookmark, UnfiledBookmark, UnsavedBookmark, } from './resources/bookmarks.js';
 export { AccountsResource } from './resources/accounts.js';
-export { SIGNAL_BATCH_MAX, SignalsResource } from './resources/signals.js';
-export type { SignalBatchResult, SignalEventInput, SignalEventType, SignalNotRecordedReason, SignalRecordResult, SignalSendOptions, } from './resources/signals.js';
+export { SIGNAL_BATCH_MAX, SignalsResource, newClientEventId } from './resources/signals.js';
+export type { ClearViewingHistoryResult, SignalBatchResult, SignalEventInput, SignalEventType, SignalExit, SignalMetadata, SignalNotRecordedReason, SignalRecordResult, SignalRejection, SignalSendOptions, SignalSurface, } from './resources/signals.js';
 export { SEALED_ALLOWANCE_REMAINING_HEADER, SEALED_REFUSAL_HEADER, SealedResource, SealedTransportError, } from './resources/sealed.js';
 export type { SealedAllowance, SealedAttestationInput, SealedConfig, SealedModel, SealedPlan, SealedPurpose, SealedQuotaDetails, SealedSendInput, SealedTarget, SealedTargetKind, SealedTransportErrorCode, } from './resources/sealed.js';
 export type { SiblingAccount, SiblingAccountsResponse, SwitchAccountResult, } from './resources/accounts.js';

package/dist/index.js

@@ -61,6 +61,7 @@ import { JobsResource } from './resources/jobs.js';
 import { CuratorResource } from './resources/curator.js';
 import { ReportsResource } from './resources/reports.js';
 import { ModerationResource } from './resources/moderation.js';
+import { TrustResource } from './resources/trust.js';
 import { JudgmentsResource } from './resources/judgments.js';
 import { LinkPreviewResource } from './resources/link-preview.js';
 import { SearchResource } from './resources/search.js';
@@ -135,6 +136,8 @@ export class Recursiv {
     boosts;
     reports;
     moderation;
+    /** The signed trust log: its public keys, and the member's own signed events (0.7.96). */
+    trust;
     /** Jev's labels of a post: read them, dispute or appeal one, and (staff) review a dispute. */
     judgments;
     linkPreview;
@@ -211,6 +214,7 @@ export class Recursiv {
         this.boosts = new BoostsResource(client);
         this.reports = new ReportsResource(client);
         this.moderation = new ModerationResource(client);
+        this.trust = new TrustResource(client);
         this.judgments = new JudgmentsResource(client);
         this.linkPreview = new LinkPreviewResource(client);
         this.search = new SearchResource(client);
@@ -274,12 +278,13 @@ export { STORY_POOL_MAX_POSTS, STORY_POST_NETWORKS, STORY_POSTS_PAGE_MAX } from
 export { ReportsResource } from './resources/reports.js';
 export { JudgmentsResource, isJudgmentSharedWordsError } from './resources/judgments.js';
 export { ModerationResource } from './resources/moderation.js';
+export { TrustResource } from './resources/trust.js';
 export { LinkPreviewResource } from './resources/link-preview.js';
 export { SEARCH_SECTIONS, SearchResource } from './resources/search.js';
 export { BOOKMARK_MERGE_MAX_ITEMS, BookmarkCollectionsResource, BookmarksResource } from './resources/bookmarks.js';
 export { FEED_TOP_NETWORKS, FeedsResource } from './resources/feeds.js';
 export { AccountsResource } from './resources/accounts.js';
-export { SIGNAL_BATCH_MAX, SignalsResource } from './resources/signals.js';
+export { SIGNAL_BATCH_MAX, SignalsResource, newClientEventId } from './resources/signals.js';
 export { SEALED_ALLOWANCE_REMAINING_HEADER, SEALED_REFUSAL_HEADER, SealedResource, SealedTransportError, } from './resources/sealed.js';
 export { OrganizationSettingsResource } from './resources/organization-settings.js';
 export { ProjectSettingsResource } from './resources/project-settings.js';

package/dist/resources/moderation.d.ts

@@ -1,5 +1,6 @@
 import type { HttpClient } from '../client.js';
 import type { SingleResponse } from '../types.js';
+import type { TrustEnvelope } from './trust.js';
 export type ModerationTargetType = 'post' | 'user' | 'message' | 'community' | 'agent' | 'source_actor' | 'source_post';
 export type ModerationActionType = 'down_rank' | 'label' | 'remove' | 'suspend' | 'ban';
 export type ModerationAppealStatus = 'none' | 'pending' | 'upheld' | 'overturned';
@@ -8,9 +9,30 @@ export interface ModerationPrinciple {
     title: string;
     summary: string;
 }
+/**
+ * Whether a decision is in the signed trust log, by the server's check (0.7.96): `verified` (signed, and its signature,
+ * hash and link to the event before it hold), `unverified` (signed, and one of those does not), `unsigned` (decided
+ * before the log was written, or not signed yet), `unavailable` (the log could not be read just now).
+ */
+export type ModerationTrustStatus = 'verified' | 'unverified' | 'unsigned' | 'unavailable';
+/** One decision's signed envelopes: where they sit in the chain and what signed them, never the moderator, the subject or a hash. */
+export interface ModerationTrustLog {
+    status: ModerationTrustStatus;
+    decision: TrustEnvelope | null;
+    reversal: TrustEnvelope | null;
+}
+/** The page as a whole: unverified if any action is, verified if any is signed, else unsigned. */
+export interface ModerationTrustWindow {
+    status: ModerationTrustStatus;
+    verified: number;
+    unverified: number;
+    unsigned: number;
+}
 export interface PublicModerationAction {
     id: string;
     target_type: ModerationTargetType;
+    /** One sentence: what kind of thing was acted on and how, never which one. */
+    description?: string;
     action: ModerationActionType;
     policy: string | null;
     actor_type: 'human' | 'ai' | 'system';
@@ -18,6 +40,8 @@ export interface PublicModerationAction {
     reversed_at: string | null;
     created_at: string;
     appeal_status: ModerationAppealStatus;
+    /** Present once the operator turns on the signed log's reads (TRUST_LOG_PUBLIC_READS); absent before. */
+    trust_log?: ModerationTrustLog;
 }
 export interface PublicModerationLog {
     principles: ModerationPrinciple[];
@@ -27,6 +51,8 @@ export interface PublicModerationLog {
         offset: number;
         has_more: boolean;
     };
+    /** Present once the operator turns on the signed log's reads; absent before. */
+    trust_log?: ModerationTrustWindow;
 }
 export interface OwnModerationAppeal {
     id: string;

package/dist/resources/signals.d.ts

@@ -6,24 +6,117 @@ import type { SingleResponse } from '../types.js';
  * one, so send them in a request of their own if the API may be older.
  */
 export type SignalEventType = 'view' | 'click' | 'dwell' | 'react_up' | 'react_down' | 'save' | 'hide' | 'share' | 'mute_source' | 'open_chat' | 'ask_agent' | 'more_like' | 'unhide';
-/** One engagement signal. An open-network post has no Minds id: name it in `metadata` (e.g. `{ ref }`) instead. */
+/**
+ * Where a signal happened: each one a public place. In the Minds app the server lists these (and Discover's older
+ * `discover_featured`, `discover_hot`, `discover_rediscover`) and refuses any other name, `other` included, with a 400
+ * (`private_surface`). Another app's well-formed name the server does not list is stored as `other`, so a new surface
+ * still lands there; add it here (and to the server's SIGNAL_SURFACES) to keep it apart. There is no `group`: a group
+ * can be an encrypted chat, which never sends a signal.
+ */
+export type SignalSurface = 'home_feed' | 'discovery' | 'discovery_story' | 'discovery_module' | 'discover_category' | 'discover_for_you' | 'postcard' | 'story' | 'swipe' | 'watch' | 'clip_strip' | 'discover_videos' | 'story_cluster' | 'headline_gallery' | 'post_clip' | 'search_videos' | 'profile' | 'search' | 'post' | 'other';
+/** How a watch, or a card's time on screen, ended. */
+export type SignalExit = 'swipe' | 'leave' | 'hide' | 'tap';
+/**
+ * A signal's metadata: the only keys the server keeps (0.7.93, the ingest contract). A key not listed here is dropped.
+ * A listed key with a value of the wrong type or past its limit refuses that event (named in `rejections`, never
+ * stored); `null` or `''` reads as absent. Times are milliseconds.
+ */
+export interface SignalMetadata {
+    /**
+     * Where it happened (up to 64 characters). In the Minds app one of SignalSurface's names other than `other`;
+     * elsewhere an unlisted name is stored as `other`.
+     */
+    surface?: SignalSurface | (string & {});
+    /** Which feed of the surface, e.g. `all`, `category`, `for-you:world` (up to 64). */
+    feed?: string;
+    /** The block of the feed, e.g. `top` (up to 32). */
+    block?: string;
+    /** The 0-based row in the feed (0 to 100,000). */
+    position?: number;
+    /** The place within a module that holds several (0 to 10,000). */
+    slot?: number;
+    /** A category feed's category (up to 64). */
+    category?: string;
+    /**
+     * An item with no Minds post id: an open-network post `<protocol>/<native id>` (native id up to 2,048 characters, no
+     * whitespace), a story lead `cluster:<64 hex>` or a World Today story `today:<uuid>`. Stored in an indexed column.
+     */
+    ref?: string;
+    /** How long the clip played (0 to one hour). Held to `duration_ms` x (`loops` + 1) and to the wall clock. */
+    watch_ms?: number;
+    /** The clip's length (0 to six hours). */
+    duration_ms?: number;
+    completed?: boolean;
+    /** Times the clip looped (0 to 1,000). */
+    loops?: number;
+    sound_on?: boolean;
+    /** How it ended. A watch under a second that ended in a `swipe` is stored as a skip. */
+    exit?: SignalExit;
+    /** Cards on screen at once in a grid (1 to 200). Readers divide a grid card's dwell by it; it never divides watch time. */
+    visible_count?: number;
+    autoplay?: boolean;
+    /**
+     * The client's id for this event (a letter or digit, then up to 63 of `A-Za-z0-9_.:-`): an event sent again with the
+     * same id is stored once. `batch` and `record` add one to an event that has none.
+     */
+    client_event_id?: string;
+    /** The event's place in the client's session (0 to 2^31 - 1). */
+    session_seq?: number;
+    /** How the action was taken, e.g. `less_like_this`, `module_hide` (up to 64). */
+    via?: string;
+    /** What the action came from, e.g. `postcard_bookmark` (up to 64). */
+    source?: string;
+    /** How the item was shown, e.g. `video` (up to 32). */
+    presentation?: string;
+}
+/** One engagement signal. An open-network post has no Minds id: name it by `metadata.ref` instead. */
 export interface SignalEventInput {
     event_type: SignalEventType;
     /** The Minds post's id (a UUID). */
     post_id?: string;
-    /** Milliseconds on screen, for `dwell` (0 to one hour). */
+    /** Milliseconds on screen, for `dwell` (0 to one hour; a card's counts up to five minutes). */
     dwell_ms?: number;
-    metadata?: Record<string, unknown>;
+    metadata?: SignalMetadata;
 }
 /**
  * Why nothing was stored, on a 200: `no_project_scope` (the key is not bound to an app, so there is no app database
- * for the signal) or `project_db_unavailable` (the app database did not take it; signals are best-effort).
+ * for the signal), `project_db_unavailable` (the app database did not take it; signals are best-effort),
+ * `viewing_off` (the member turned off "Use what I watch and read to personalize", so a dwell or open is not kept),
+ * `rate_limited` (past the member's events a minute) or `duplicate` (`record` only: an event with this
+ * `client_event_id` is already stored).
  */
-export type SignalNotRecordedReason = 'no_project_scope' | 'project_db_unavailable';
+export type SignalNotRecordedReason = 'no_project_scope' | 'project_db_unavailable' | 'viewing_off' | 'rate_limited' | 'duplicate';
+/** Why the server refused one event of a batch: a metadata value of the wrong type or past its limit. */
+export interface SignalRejection {
+    /** The event's index in the batch. */
+    index: number;
+    reason: 'invalid_metadata' | 'invalid_ref' | 'invalid_client_event_id';
+    /** The metadata key. */
+    key: string;
+}
 export interface SignalBatchResult {
-    /** Events stored. */
+    /** Events stored by this call. */
     recorded: number;
+    /**
+     * Events the server did not keep because the member's viewing personalization is off: dwell and opens. Views and
+     * explicit choices are always kept. Absent when none were left out.
+     */
+    withheld?: number;
     reason?: SignalNotRecordedReason;
+    /** Events already stored (the same `client_event_id`, in this batch or an earlier one): stored once. */
+    duplicates?: number;
+    /** Events past the member's rate (600 a minute by default): not stored. */
+    limited?: number;
+    /** Events refused by the contract: not stored. The rest of the batch is. */
+    rejected?: number;
+    /** The first ten refused events, and why. */
+    rejections?: SignalRejection[];
+}
+/** What "Clear my viewing history" did: the member's views, dwell, Watch time and opens in this app are gone. */
+export interface ClearViewingHistoryResult {
+    cleared: true;
+    /** Rows deleted. */
+    deleted: number;
 }
 export interface SignalRecordResult {
     recorded: boolean;
@@ -44,15 +137,45 @@ export declare const SIGNAL_BATCH_MAX = 100;
  * Engagement signals (views, dwell, hides, "More like this") for the member's own ranking, under the member's
  * app-bound key (`agents:write`). They land in the app's database and feed For You. Best-effort: a signal the server
  * cannot store still answers 200 with `recorded` 0 or false and a `reason`.
+ *
+ * Only from a public place, never a private message: a `metadata` key or placement (`surface`, `feed`, `source`,
+ * `context`, `route`...) that names a chat, DM, inbox, encrypted or Sealed conversation, by any spelling (`chatList`,
+ * `dmThread`, `/messages/1`), is refused with a 400 (`private_surface`), and nothing in that request is stored. An app
+ * names its own public places (`{ source: 'discover' }`). In the Minds app the placements (`surface`, `feed`, `source`,
+ * `via`, `layoutSource`) must be ones the server lists (its feeds, Discover, Watch, stories, the pager and post cards),
+ * and any other key that names a place (`context`) is refused there too.
+ *
+ * That check reads the metadata as sent. The server then keeps only SignalMetadata's keys, each within its limit; a
+ * batch names any event it refused and stores the rest. `record` answers 400 (`invalid_signal`) for an event it refuses.
  */
 export declare class SignalsResource {
     private client;
+    /**
+     * The id each event object was sent with. An event sent again (a retry of the same request, or the app sending the
+     * same object after a failed flush) carries the same id, so the server stores it once. Weak: an event the app has let
+     * go is not held here.
+     */
+    private readonly eventIds;
     constructor(client: HttpClient);
     /**
      * Store up to SIGNAL_BATCH_MAX events in one request (POST /signals/batch). The server reads a post's newest hide or
      * unhide, so send a batch only after the one before it has landed when order matters. An empty array stores nothing.
+     * Each event without a `metadata.client_event_id` is sent with one (the same one each time that object is sent).
      */
     batch(events: SignalEventInput[], options?: SignalSendOptions): Promise<SingleResponse<SignalBatchResult>>;
     /** Store one event (POST /signals/post). Prefer `batch`; this is for an API that predates it (404 there). */
     record(event: SignalEventInput, options?: SignalSendOptions): Promise<SingleResponse<SignalRecordResult>>;
+    /**
+     * "Clear my viewing history" (DELETE /signals/history): the member's views, dwell, Watch time and opens in this app
+     * are deleted, and what was built from them is rebuilt. Their explicit choices (hides, "More like this", saves,
+     * shares, votes) stay. A delete that could not be done is an error (503), never a success.
+     */
+    clearViewingHistory(): Promise<SingleResponse<ClearViewingHistoryResult>>;
+    /** The event as sent: the caller's object is never changed. */
+    private withEventId;
 }
+/**
+ * A fresh event id the server's grammar takes: a random UUID where the platform has one, otherwise the time and about
+ * 104 random bits (React Native's Hermes has no crypto.randomUUID). Unique per member is all it needs to be.
+ */
+export declare function newClientEventId(): string;

package/dist/resources/signals.js

@@ -4,23 +4,79 @@ export const SIGNAL_BATCH_MAX = 100;
  * Engagement signals (views, dwell, hides, "More like this") for the member's own ranking, under the member's
  * app-bound key (`agents:write`). They land in the app's database and feed For You. Best-effort: a signal the server
  * cannot store still answers 200 with `recorded` 0 or false and a `reason`.
+ *
+ * Only from a public place, never a private message: a `metadata` key or placement (`surface`, `feed`, `source`,
+ * `context`, `route`...) that names a chat, DM, inbox, encrypted or Sealed conversation, by any spelling (`chatList`,
+ * `dmThread`, `/messages/1`), is refused with a 400 (`private_surface`), and nothing in that request is stored. An app
+ * names its own public places (`{ source: 'discover' }`). In the Minds app the placements (`surface`, `feed`, `source`,
+ * `via`, `layoutSource`) must be ones the server lists (its feeds, Discover, Watch, stories, the pager and post cards),
+ * and any other key that names a place (`context`) is refused there too.
+ *
+ * That check reads the metadata as sent. The server then keeps only SignalMetadata's keys, each within its limit; a
+ * batch names any event it refused and stores the rest. `record` answers 400 (`invalid_signal`) for an event it refuses.
  */
 export class SignalsResource {
     client;
+    /**
+     * The id each event object was sent with. An event sent again (a retry of the same request, or the app sending the
+     * same object after a failed flush) carries the same id, so the server stores it once. Weak: an event the app has let
+     * go is not held here.
+     */
+    eventIds = new WeakMap();
     constructor(client) {
         this.client = client;
     }
     /**
      * Store up to SIGNAL_BATCH_MAX events in one request (POST /signals/batch). The server reads a post's newest hide or
      * unhide, so send a batch only after the one before it has landed when order matters. An empty array stores nothing.
+     * Each event without a `metadata.client_event_id` is sent with one (the same one each time that object is sent).
      */
     batch(events, options) {
-        return this.client.post('/signals/batch', { events }, sendOptions(options));
+        return this.client.post('/signals/batch', { events: events.map((event) => this.withEventId(event)) }, sendOptions(options));
     }
     /** Store one event (POST /signals/post). Prefer `batch`; this is for an API that predates it (404 there). */
     record(event, options) {
-        return this.client.post('/signals/post', event, sendOptions(options));
+        return this.client.post('/signals/post', this.withEventId(event), sendOptions(options));
+    }
+    /**
+     * "Clear my viewing history" (DELETE /signals/history): the member's views, dwell, Watch time and opens in this app
+     * are deleted, and what was built from them is rebuilt. Their explicit choices (hides, "More like this", saves,
+     * shares, votes) stay. A delete that could not be done is an error (503), never a success.
+     */
+    clearViewingHistory() {
+        return this.client.delete('/signals/history');
+    }
+    /** The event as sent: the caller's object is never changed. */
+    withEventId(event) {
+        if (!event || typeof event !== 'object')
+            return event;
+        const given = event.metadata?.client_event_id;
+        if (typeof given === 'string' && given)
+            return event;
+        let id = this.eventIds.get(event);
+        if (!id) {
+            id = newClientEventId();
+            this.eventIds.set(event, id);
+        }
+        return { ...event, metadata: { ...event.metadata, client_event_id: id } };
+    }
+}
+/**
+ * A fresh event id the server's grammar takes: a random UUID where the platform has one, otherwise the time and about
+ * 104 random bits (React Native's Hermes has no crypto.randomUUID). Unique per member is all it needs to be.
+ */
+export function newClientEventId() {
+    const cryptoApi = globalThis.crypto;
+    if (typeof cryptoApi?.randomUUID === 'function') {
+        try {
+            return cryptoApi.randomUUID();
+        }
+        catch {
+            // A non-secure context can refuse it: fall through.
+        }
     }
+    const random = () => Math.floor(Math.random() * 2 ** 52).toString(36).padStart(11, '0');
+    return `${Date.now().toString(36)}-${random()}${random()}`;
 }
 function sendOptions(options) {
     if (!options)

package/dist/resources/trust.d.ts

@@ -0,0 +1,85 @@
+import type { HttpClient } from '../client.js';
+import type { SingleResponse } from '../types.js';
+/**
+ * Where one event sits in the signed trust log, which key signed it, and whether the server's check of it holds
+ * (0.7.96). The public moderation log carries one per signed decision and reversal (`PublicModerationAction.trust_log`):
+ * never the moderator, the subject or the payload, and never a hash or a signature. The log's v1 encoding signs the
+ * moderator and the subject unsalted, so a published hash or signature would let anyone test guesses of who acted on
+ * what; `verified` is the server's verdict, not something a client re-checks.
+ */
+export interface TrustEnvelope {
+    /** The chain the event is on: the network's id. */
+    chain: string;
+    seq: number;
+    key_id: string;
+    algorithm: 'ed25519';
+    occurred_at: string;
+    /** The server's own check: the signature, the hash, and the link to the event before it. */
+    verified: boolean;
+}
+/** One of the caller's own events: what they did, where it sits in the log, and the server's check of it. */
+export interface OwnTrustEvent extends TrustEnvelope {
+    id: number;
+    network_id: string;
+    project_id: string | null;
+    /** e.g. `follow`, `unfollow`, `block`, `mute`, `hide`, `appeal`, `moderation_action` (a moderator's own decision). */
+    kind: string;
+    actor: {
+        kind: 'user' | 'agent' | 'system';
+        user_id: string | null;
+        principal_id: string | null;
+    };
+    subject: {
+        kind: string;
+        id: string | null;
+        key: string | null;
+        principal_id: string | null;
+    };
+    payload: Record<string, unknown>;
+}
+/** A public key that signed the log. A retired or compromised key still verifies what it signed before that instant. */
+export interface TrustPublicKey {
+    key_id: string;
+    algorithm: 'ed25519';
+    /** base64 SPKI DER. */
+    public_key: string;
+    activated_at: string | null;
+    retired_at: string | null;
+    compromised_at: string | null;
+}
+export interface OwnTrustEvents {
+    events: OwnTrustEvent[];
+    /** The keys that signed this page's events. */
+    keys: TrustPublicKey[];
+    pagination: {
+        limit: number;
+        before: number | null;
+        has_more: boolean;
+        next_before: number | null;
+    };
+}
+/**
+ * The signed trust log (0.7.96). Both reads answer 404 (`NotFoundError`) until the operator turns on
+ * TRUST_LOG_PUBLIC_READS. Signed moderation decisions are on the public moderation log itself
+ * (`r.moderation.publicLog`, `trust_log` on each action).
+ */
+export declare class TrustResource {
+    private client;
+    constructor(client: HttpClient);
+    /**
+     * Keyless: every public key that ever signed the log, retired and compromised ones included. Public material: pin
+     * them to see a rotation, or check a full row an auditor holds.
+     */
+    keys(): Promise<SingleResponse<{
+        keys: TrustPublicKey[];
+    }>>;
+    /**
+     * The caller's own events, newest first: the follows, blocks, mutes, hides and appeals they made (a moderator's own
+     * decisions too), each with where it sits in the log and the server's check. Never a hash or a signature. Page with
+     * `before: pagination.next_before`. Needs `users:read`.
+     */
+    mine(params?: {
+        before?: number;
+        limit?: number;
+    }): Promise<SingleResponse<OwnTrustEvents>>;
+}

package/dist/resources/trust.js

@@ -0,0 +1,26 @@
+/**
+ * The signed trust log (0.7.96). Both reads answer 404 (`NotFoundError`) until the operator turns on
+ * TRUST_LOG_PUBLIC_READS. Signed moderation decisions are on the public moderation log itself
+ * (`r.moderation.publicLog`, `trust_log` on each action).
+ */
+export class TrustResource {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    /**
+     * Keyless: every public key that ever signed the log, retired and compromised ones included. Public material: pin
+     * them to see a rotation, or check a full row an auditor holds.
+     */
+    keys() {
+        return this.client.get('/transparency/trust/keys');
+    }
+    /**
+     * The caller's own events, newest first: the follows, blocks, mutes, hides and appeals they made (a moderator's own
+     * decisions too), each with where it sits in the log and the server's check. Never a hash or a signature. Page with
+     * `before: pagination.next_before`. Needs `users:read`.
+     */
+    mine(params = {}) {
+        return this.client.get('/trust/me', { before: params.before, limit: params.limit });
+    }
+}

package/dist/types.d.ts

@@ -1651,6 +1651,12 @@ export interface ContentPreferences {
      * that predate it: treat absent as off.
      */
     sealed_adult?: boolean;
+    /**
+     * "Use what I watch and read to personalize": on by default. Off, the server stores only views (so a post the member
+     * saw is not served again) and their explicit choices, and no ranking reads what they watched or read. Absent on
+     * servers that predate it: treat absent as on.
+     */
+    personalize_from_viewing?: boolean;
 }
 export interface UpdateNotificationChannelsInput {
     /** Master switch: sets in-app on every kind. */
@@ -1698,6 +1704,8 @@ export interface UpdateContentPreferencesInput {
      * accepted.
      */
     sealed_adult?: boolean;
+    /** "Use what I watch and read to personalize". `false` is the member's opt-out; `true` turns it back on. */
+    personalize_from_viewing?: boolean;
 }
 export interface Session {
     id: string;

package/llm.md

@@ -826,7 +826,7 @@ Methods: `list`, `get`, `create`, `delete`
 ## Platform Resources
 
 - `r.settings` — User preferences, sessions, password changes, account deletion. `revokeOtherSessions({ keep_session_token? })` signs out every other device and keeps this key (and the proven session); `revokeAllSessions()` also revokes this key. Accounts with no password confirm `requestEmailChange({ new_email, email_code })` with a code from `requestConfirmationCode('email_change')`. With a project-bound key, `getPreferences()` includes app-scoped `content`; persist changes with `updateContent({ show_nsfw?, autoplay_video?, ai_enabled?, default_feed?, 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`). `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.
+- `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'`).
 
 ```typescript
 await r.signals.batch([{ event_type: 'view', post_id: post.id }, { event_type: 'dwell', post_id: post.id, dwell_ms: 4200 }])
@@ -866,6 +866,7 @@ await r.appSubscriptions.changeTier({ tier: 'pro', proration_date: quote.prorati
 ```
 - `r.admin` — Admin operations (user management, stats, network settings); content reports: `listReports({ status? })`, `resolveReport(id)`, `dismissReport(id)` (project-bound keys see only their app's reports)
 - `r.moderation` — Moderation actions. Staff (admin key), 0.7.74: `const { data: actions } = await r.moderation.list({ target_type: 'user', target_id: userId })` reads one target's recorded actions (`ModerationAction`: `id`, `target_type` incl. `source_item`, `action`, `label`, `reason`, `actor_id`, `actor_type`, `source_report_id`, `expires_at`, `reversed_at`, `created_at`), newest first, at most 100, inside the caller's network and a project-bound key's app; `list()` with no target reads the network's latest. Unban = reverse each ban still in force: `for (const a of actions.filter(a => a.action === 'ban' && !a.reversed_at)) await r.moderation.reverse(a.id)`; the target's state is derived again from what is still in force. `reverse` is sent once, never retried: 404 `action_not_found` (`NotFoundError`) means already reversed or not in the caller's scope; 409 `use_judgment_review` means a reviewed label override (change it with `r.judgments.review`). An older SDK has neither method. Also `apply`, `publicLog`, `mine`, `appeal`, `resolveAppeal`, and agent grants `listAgentGrants`, `grantAgent(agentId, 'shadow' | 'act')`, `revokeAgent`.
+- `r.trust` — The signed trust log (0.7.96; both reads answer 404, `NotFoundError`, until the operator turns on `TRUST_LOG_PUBLIC_READS`). `r.trust.keys()` (keyless) lists every public key that ever signed it (`key_id`, `algorithm` `ed25519`, `public_key` base64 SPKI DER, `activated_at`, `retired_at`, `compromised_at`). `r.trust.mine({ before?, limit? })` (`users:read`) reads the caller's own signed events, newest first (their follows, blocks, mutes, hides, appeals, and a moderator's own decisions: `kind`, `actor`, `subject`, `payload`, `chain`, `seq`, `key_id`, `occurred_at`, and the server's check `verified`) with the `keys` that signed the page; page with `before: pagination.next_before`. On the public log, `r.moderation.publicLog(networkId)` then carries `trust_log` on each action (`status`: `verified` | `unverified` | `unsigned` | `unavailable`, and the signed `decision` and `reversal`: `chain`, `seq`, `key_id`, `algorithm`, `occurred_at`, `verified`) and on the page (`status` and the count of each). No read carries a hash or a signature (the v1 encoding signs the moderator and the subject unsalted, so one would let anyone test guesses of who acted on what): `verified` is the server's verdict.
 - `r.judgments` (0.7.71) — Jev's labels of one post. `get({ kind: 'post' | 'network_post', id })`: switch on `data.view` — `'full'` for the post's author and staff (`judgments` with answers, `safety` verdict, `viral.withheld`; staff also `reviewer_ids`, `review_note`), `'summary'` for other members (`category`, `politics` band in words with its `judgment_id`; never a probability or cell). `data.status === 'unavailable'` (returned, not thrown): hide label actions. `getPublic(projectId, { kind, id })` on an anonymous client: `view: 'category'` only. `dispute(judgmentId, { question_key: 'placement', proposed: 'cm' | … | 'not_political', note? })` (safety: `question_key: 'safety'`, author only): the author's dispute is an appeal; a repeat answers `existing: true`. Staff: `review(judgmentId, { outcome: 'uphold' } | { outcome: 'override', proposed, note?, apply_to_shared? })`, sent once (never retried): a compass override answers 202 `{ status: 'awaiting_reviewer', agreeing, needed }` until a second reviewer (or an agreeing Jev re-judge) proposes the same; a safety override to `'none'` that would free other posts throws 409 `shared_words` (`isJudgmentSharedWordsError(e)`, `e.details.shared_posts`) until resent with `apply_to_shared: true`. Budgets (60 reads/hour, 25 of one author's posts, 20 disputes/day) throw `RateLimitError` with `scope: 'action'` at once. Example: `const { data } = await r.judgments.get({ kind: 'post', id }); if (data.status === 'ok' && data.view === 'summary' && data.politics) await r.judgments.dispute(data.politics.judgment_id, { question_key: 'placement', proposed: 'not_political' })`
 - `r.inviteCodes` / `r.inviteCodesAdmin` — Invite code management
 - `r.organizationSettings` / `r.organizationSecurity` — Org configuration

package/package.json

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