@recursiv/sdk 0.7.93 → 0.7.96

package/README.md

@@ -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';

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,6 +278,7 @@ 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';

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/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/llm.md

@@ -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.93",
+  "version": "0.7.96",
   "description": "TypeScript SDK for the Recursiv API",
   "license": "FSL-1.1-ALv2",
   "type": "module",