@recursiv/sdk 0.7.70 → 0.7.72

package/dist/resources/judgments.d.ts

@@ -0,0 +1,252 @@
+import type { HttpClient } from '../client.js';
+import { ConflictError } from '../errors.js';
+import type { SingleResponse } from '../types.js';
+/** A Minds post (`post`, its uuid) or an open-network post (`network_post`, its subject id). */
+export type JudgmentSubjectKind = 'post' | 'network_post';
+/** Who wrote the label: Jev (`model`), or staff who overrode it (`review`). */
+export type JudgmentSource = 'model' | 'review';
+/** Whether the server's judgment store answered. `'unavailable'`: only the category index's label is known; hide label actions. */
+export type PostLabelsStatus = 'ok' | 'unavailable';
+/** How an override met its quorum: one reviewer (a safety appeal), two agreeing reviewers, or one beside an agreeing Jev re-judge. */
+export type JudgmentOverrideMethod = 'reviewer' | 'two_reviewers' | 'reviewer_and_rejudge';
+export interface PostLabelsQuery {
+    kind: JudgmentSubjectKind;
+    /** A Minds post id, or an open-network post's subject id. */
+    id: string;
+}
+export interface PostLabelsSubject {
+    kind: JudgmentSubjectKind;
+    id: string;
+}
+export interface PostLabelsCategory {
+    id: string;
+    name: string;
+}
+/** The compass band in words. Never a probability or a cell code. */
+export interface PostLabelsPolitics {
+    /** The judgment a member disputes with `dispute(judgment_id, { question_key: 'placement', proposed })`. */
+    judgment_id: string;
+    politics: 'Takes a side' | 'Maybe' | 'No';
+    /** Each placed axis in words, e.g. `{ axis: 'Liberty ↔ Order', band: 'Order' }`. Empty unless the post takes a side. */
+    axes: Array<{
+        axis: string;
+        band: string;
+    }>;
+    model: string;
+    rubric: string;
+    source: JudgmentSource;
+    judged_at: string | null;
+}
+/** One stored judgment, as the post's author and staff see it. */
+export interface PostJudgmentRecord {
+    id: string;
+    rubric: string;
+    model: string;
+    source: JudgmentSource;
+    judged_at: string | null;
+    /** The typed answers, every probability included. */
+    answers: Record<string, unknown>;
+    political: number | null;
+    cell: string | null;
+    reason: 'hate' | 'spam' | null;
+}
+/** A rubric's current judgment in the full view. */
+export interface PostJudgment extends PostJudgmentRecord {
+    /** How many staff reviewers wrote it (0 for Jev's own). */
+    reviewers: number;
+    /** Staff only. */
+    reviewer_ids?: string[];
+    /** Staff only. */
+    review_note?: string | null;
+    /** Whether `dispute()` takes it: political-compass and safety labels (safety: the author only). */
+    disputable: boolean;
+    /** Jev's judgment a staff review replaced, for the same words. */
+    superseded: PostJudgmentRecord | null;
+}
+/** The safety verdict the Discover floor applies to the post now, with who judged it (full view, Minds posts). */
+export type PostSafetyAttribution = {
+    status: 'judged';
+    reason: 'hate' | 'spam' | null;
+    unsafe: boolean;
+    hate: number;
+    spam: number;
+    rubric: string;
+    /** The judging model, `'review'` for a staff review; null when only the cache holds the verdict. */
+    model: string | null;
+    source: JudgmentSource | 'cache';
+    judgedAt: string | null;
+    /** A staff review the floor does not apply yet (the cache still holds another verdict). */
+    unappliedReview?: {
+        reason: 'hate' | 'spam' | null;
+        unsafe: boolean;
+        hate: number;
+        spam: number;
+        judgedAt: string;
+    };
+} | {
+    status: 'pending';
+} | {
+    status: 'not_judgeable';
+};
+/** A visitor's view (`getPublic`): the category only. */
+export interface PostLabelsCategoryView {
+    subject: PostLabelsSubject;
+    view: 'category';
+    category: PostLabelsCategory | null;
+    status: PostLabelsStatus;
+}
+/** Any other member's view: the category and the compass band in words, with the id to dispute it. */
+export interface PostLabelsSummaryView {
+    subject: PostLabelsSubject;
+    view: 'summary';
+    category: PostLabelsCategory | null;
+    politics: PostLabelsPolitics | null;
+    status: PostLabelsStatus;
+}
+/** The post's author's and staff's view: every rubric's current judgment, the safety verdict and Viral. */
+export interface PostLabelsFullView {
+    subject: PostLabelsSubject;
+    view: 'full';
+    category: PostLabelsCategory | null;
+    politics: PostLabelsPolitics | null;
+    judgments: PostJudgment[];
+    /** null for an open-network post. */
+    safety: PostSafetyAttribution | null;
+    /** Why the post is withheld from Viral ("Withheld from Viral: <reason>"), or null. */
+    viral: {
+        withheld: string | null;
+    };
+    status: PostLabelsStatus;
+}
+/** One post's labels, in the view the caller may see: switch on `view`. */
+export type PostLabels = PostLabelsFullView | PostLabelsSummaryView | PostLabelsCategoryView;
+export interface DisputeJudgmentInput {
+    /** The label's question: `'placement'` for a political-compass label, `'safety'` for a safety label (its author only). */
+    question_key: string;
+    /** The answer it should be: a compass cell (`'lo'`, `'cm'`, …) or `'not_political'`; for safety `'none'`, `'hate'` or `'spam'`. */
+    proposed: string;
+    /** At most 500 characters. */
+    note?: string;
+}
+/** A filed dispute. The author's is an appeal and goes to the moderation queue; anyone else's feeds the evaluation. */
+export interface JudgmentDispute {
+    id: string;
+    judgment_id: string;
+    /** True when the caller wrote the post: an appeal. */
+    appeal: boolean;
+    /** Whether it waits in the moderation queue now. */
+    queued: boolean;
+    /** Present on a repeat: the member's first dispute of this judgment, unchanged. */
+    existing?: true;
+}
+export type ReviewJudgmentInput = {
+    outcome: 'uphold';
+    note?: string;
+} | {
+    outcome: 'override';
+    /** The answer the label becomes. */
+    proposed: string;
+    /** At most 2,000 characters. */
+    note?: string;
+    /** A safety override to `'none'` that frees other posts with exactly these words: send true after a 409 `shared_words`. */
+    apply_to_shared?: boolean;
+};
+/** 200: the label stands, and its queue items are closed. */
+export interface JudgmentReviewUpheld {
+    status: 'upheld';
+    resolved: number;
+}
+/** 202: this reviewer's vote is recorded; a compass label needs another reviewer (or an agreeing Jev re-judge). */
+export interface JudgmentReviewAwaitingReviewer {
+    status: 'awaiting_reviewer';
+    vote_id: string;
+    agreeing: number;
+    needed: number;
+}
+/** 200: the override is written and in the public moderation log. */
+export interface JudgmentReviewOverridden {
+    status: 'overridden';
+    review_id: string;
+    moderation_action_id: string;
+    method: JudgmentOverrideMethod;
+    reviewers: number;
+    resolved: number;
+    trust_log: 'appended' | 'disabled' | 'duplicate';
+    /** A safety review: whether the Discover floor applies it now; null for a compass label. */
+    applied_to_discover: boolean | null;
+    /** A safety review of words the post no longer has: recorded, never applied. */
+    words_changed: boolean | null;
+    shared_posts: number | null;
+}
+export type JudgmentReview = JudgmentReviewUpheld | JudgmentReviewAwaitingReviewer | JudgmentReviewOverridden;
+/** The `details` of a 409 `shared_words` from `review()`. */
+export interface JudgmentSharedWordsDetails {
+    shared_posts: number;
+}
+/** The 409 `review()` throws before a safety override frees other posts with exactly these words. */
+export type JudgmentSharedWordsError = ConflictError & {
+    code: 'shared_words';
+    details: JudgmentSharedWordsDetails;
+};
+/**
+ * Whether `error` is the 409 `shared_words` of `review()`: nothing was recorded, and
+ * `error.details.shared_posts` other posts have exactly these words. Resend with
+ * `apply_to_shared: true` once the reviewer agrees to change them all.
+ */
+export declare function isJudgmentSharedWordsError(error: unknown): error is JudgmentSharedWordsError;
+/**
+ * Jev's labels of one post: read them, dispute or appeal one, and (staff)
+ * decide a dispute.
+ *
+ * Budgets: 60 label reads per member an hour (25 of one author's posts) and
+ * 20 disputes a day. Past one, the server answers 429 with
+ * `X-RateLimit-Scope: action`: the SDK throws `RateLimitError` at once
+ * (`scope === 'action'`, `resetAt`, a member-facing `message`) and never
+ * retries it. Disputes and reviews answer 503 until the server's judgment
+ * store is applied; reads answer `status: 'unavailable'` instead.
+ */
+export declare class JudgmentsResource {
+    private client;
+    constructor(client: HttpClient);
+    /**
+     * One post's labels as the caller may see them. The post's author and staff
+     * get `view: 'full'` (every judgment with its answers, the safety verdict,
+     * Viral); any other member who can see the post gets `view: 'summary'` (the
+     * category and the compass band in words). `status: 'unavailable'` is
+     * returned, not thrown. A post the caller cannot see throws `NotFoundError`.
+     * Open-network posts need a key bound to an app (400 `app_required`).
+     *
+     * @example
+     * const { data } = await r.judgments.get({ kind: 'post', id: postId });
+     * if (data.status === 'ok' && data.view !== 'category' && data.politics) showBand(data.politics);
+     */
+    get(query: PostLabelsQuery): Promise<SingleResponse<PostLabels>>;
+    /**
+     * A signed-out visitor's view of one post's labels: the category only.
+     * Keyless: use an anonymous client (`new Recursiv({ anonymous: true })`).
+     */
+    getPublic(projectId: string, query: PostLabelsQuery): Promise<SingleResponse<PostLabelsCategoryView>>;
+    /**
+     * Disagree with a label. The post's author's dispute is an appeal and goes
+     * to the moderation queue; anyone else's feeds the evaluation and changes
+     * nothing on its own. One per member and judgment: a repeat returns the
+     * first with `existing: true`. Sent once, never retried automatically.
+     *
+     * @example
+     * await r.judgments.dispute(labels.politics.judgment_id, { question_key: 'placement', proposed: 'not_political' });
+     */
+    dispute(judgmentId: string, input: DisputeJudgmentInput): Promise<SingleResponse<JudgmentDispute>>;
+    /**
+     * Staff: uphold a disputed label, or vote to override it. A compass label
+     * changes when two reviewers propose the same answer (or one, beside an
+     * agreeing Jev re-judge): the first gets `status: 'awaiting_reviewer'`
+     * (HTTP 202). Every override is in the public moderation log.
+     *
+     * Sent once, never retried: an override that met its quorum but lost its
+     * response would otherwise be recorded again as a fresh vote. A safety
+     * override to `'none'` that would free other posts with exactly these words
+     * throws a 409 (`isJudgmentSharedWordsError`, `details.shared_posts`) until
+     * resent with `apply_to_shared: true`.
+     */
+    review(judgmentId: string, input: ReviewJudgmentInput): Promise<SingleResponse<JudgmentReview>>;
+}

package/dist/resources/judgments.js

@@ -0,0 +1,79 @@
+import { ConflictError } from '../errors.js';
+/**
+ * Whether `error` is the 409 `shared_words` of `review()`: nothing was recorded, and
+ * `error.details.shared_posts` other posts have exactly these words. Resend with
+ * `apply_to_shared: true` once the reviewer agrees to change them all.
+ */
+export function isJudgmentSharedWordsError(error) {
+    if (!(error instanceof ConflictError) || error.code !== 'shared_words')
+        return false;
+    const count = error.details?.shared_posts;
+    return typeof count === 'number' && Number.isFinite(count);
+}
+const path = (judgmentId, action) => `/content-judgments/${encodeURIComponent(judgmentId)}/${action}`;
+/**
+ * Jev's labels of one post: read them, dispute or appeal one, and (staff)
+ * decide a dispute.
+ *
+ * Budgets: 60 label reads per member an hour (25 of one author's posts) and
+ * 20 disputes a day. Past one, the server answers 429 with
+ * `X-RateLimit-Scope: action`: the SDK throws `RateLimitError` at once
+ * (`scope === 'action'`, `resetAt`, a member-facing `message`) and never
+ * retries it. Disputes and reviews answer 503 until the server's judgment
+ * store is applied; reads answer `status: 'unavailable'` instead.
+ */
+export class JudgmentsResource {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    /**
+     * One post's labels as the caller may see them. The post's author and staff
+     * get `view: 'full'` (every judgment with its answers, the safety verdict,
+     * Viral); any other member who can see the post gets `view: 'summary'` (the
+     * category and the compass band in words). `status: 'unavailable'` is
+     * returned, not thrown. A post the caller cannot see throws `NotFoundError`.
+     * Open-network posts need a key bound to an app (400 `app_required`).
+     *
+     * @example
+     * const { data } = await r.judgments.get({ kind: 'post', id: postId });
+     * if (data.status === 'ok' && data.view !== 'category' && data.politics) showBand(data.politics);
+     */
+    get(query) {
+        return this.client.get('/content-judgments', { kind: query.kind, id: query.id });
+    }
+    /**
+     * A signed-out visitor's view of one post's labels: the category only.
+     * Keyless: use an anonymous client (`new Recursiv({ anonymous: true })`).
+     */
+    getPublic(projectId, query) {
+        return this.client.get(`/protocols/public/${encodeURIComponent(projectId)}/content-judgments`, { kind: query.kind, id: query.id });
+    }
+    /**
+     * Disagree with a label. The post's author's dispute is an appeal and goes
+     * to the moderation queue; anyone else's feeds the evaluation and changes
+     * nothing on its own. One per member and judgment: a repeat returns the
+     * first with `existing: true`. Sent once, never retried automatically.
+     *
+     * @example
+     * await r.judgments.dispute(labels.politics.judgment_id, { question_key: 'placement', proposed: 'not_political' });
+     */
+    dispute(judgmentId, input) {
+        return this.client.post(path(judgmentId, 'disputes'), input, { retry: false });
+    }
+    /**
+     * Staff: uphold a disputed label, or vote to override it. A compass label
+     * changes when two reviewers propose the same answer (or one, beside an
+     * agreeing Jev re-judge): the first gets `status: 'awaiting_reviewer'`
+     * (HTTP 202). Every override is in the public moderation log.
+     *
+     * Sent once, never retried: an override that met its quorum but lost its
+     * response would otherwise be recorded again as a fresh vote. A safety
+     * override to `'none'` that would free other posts with exactly these words
+     * throws a 409 (`isJudgmentSharedWordsError`, `details.shared_posts`) until
+     * resent with `apply_to_shared: true`.
+     */
+    review(judgmentId, input) {
+        return this.client.post(path(judgmentId, 'reviews'), input, { retry: false });
+    }
+}

package/dist/resources/notifications.d.ts

@@ -91,7 +91,11 @@ export interface Notification {
     actor?: NotificationActor | null;
     post_preview?: NotificationPostPreview | null;
 }
-export type NotificationCategory = 'all' | 'social' | 'system';
+/**
+ * `mentions` (SDK 0.7.72) is a Mentions tab: mentions and replies only, a
+ * subset of `social`. An older server answers it 400.
+ */
+export type NotificationCategory = 'all' | 'social' | 'system' | 'mentions';
 export type NotificationScopeParams = {
     /** Which kind of notification to count. Defaults to `all`. Same meaning as in `list`. */
     category?: NotificationCategory;
@@ -114,7 +118,8 @@ export interface ListNotificationsParams extends PaginationParams {
      * reposts, mentions, community invites, joins and join requests, moderation
      * decisions). `system` is everything operational (agent, task, deploy,
      * billing, security). Direct messages are in neither: they live in the chat
-     * inbox. `all` (the default) lists every row that has not been archived.
+     * inbox. `mentions` is the posts that name you or answer you (mentions and
+     * replies). `all` (the default) lists every row that has not been archived.
      *
      * Ask for it here rather than filtering the page you get back: the server
      * applies the limit AFTER the category, so a client that filters afterwards