@recursiv/sdk 0.7.70 → 0.7.72

package/dist/resources/protocols.d.ts

@@ -1,5 +1,5 @@
 import type { HttpClient } from '../client.js';
-import type { CompassFilterMeta, DiscoveryLayout, PaginatedResponse, PaginationParams, SingleResponse } from '../types.js';
+import type { CompassFilterMeta, DiscoveryLayout, PaginatedResponse, PaginationParams, SingleResponse, StoryOutlets } from '../types.js';
 /** Canonical protocol operation names returned by the adapter registry. */
 export declare const PROTOCOL_CAPABILITY_OPERATIONS: readonly ["discover", "stream", "backfill", "search", "resolveIdentity", "fetchProfile", "fetchThread", "publish", "reply", "react", "repost", "follow", "delete", "health", "checkpoint"];
 export declare const PROTOCOL_CAPABILITY_STATUSES: readonly ["supported", "planned", "unsupported"];
@@ -181,6 +181,134 @@ export interface ProtocolIngestionReplayResult {
     job_id: string;
     status: 'replayed';
 }
+/** A section of the ingestion health report that can fail to answer within its budget. */
+export type ProtocolIngestionHealthSection = 'activity' | 'circuits' | 'dead_letters' | 'jobs' | 'kill_switch' | 'lanes';
+/**
+ * Where a job is in its lane, read from its checkpoint: RSS reads one feed per page (feed_index); Hacker News and
+ * Event Registry walk term_index and page. Null when the checkpoint holds no such index.
+ */
+export interface ProtocolIngestionHealthPosition {
+    feed_index: number | null;
+    term_index: number | null;
+    page: number | null;
+}
+export interface ProtocolIngestionHealthRuntime {
+    mode: 'collector' | 'runtime';
+    enabled: boolean;
+    simulation: boolean;
+    global_kill_switch: boolean;
+    controls_valid: boolean;
+    project_allowed: boolean;
+    /** This app's operator kill switch; null when that read did not answer. */
+    kill_switch: boolean | null;
+}
+export interface ProtocolIngestionLaneJobs {
+    queued: number;
+    leased: number;
+    done: number;
+    dead: number;
+}
+/** The lane's open job (the worker keeps one open per lane). */
+export interface ProtocolIngestionLaneCurrentJob {
+    status: 'queued' | 'leased';
+    position: ProtocolIngestionHealthPosition;
+    pages_committed: number;
+    consecutive_failures: number;
+    last_error: string | null;
+    retry_at: string | null;
+    /** A leased job's lease end; null while queued. */
+    lease_until: string | null;
+    /** Leased, but the lease ran out and no worker reclaimed it (the worker died mid-page). */
+    lease_expired: boolean;
+    /** Eligible to run since then; null while a live lease holds it or it waits out a retry. */
+    waiting_since: string | null;
+    /** waiting_since once the wait passes the worker's starvation threshold (30 minutes); otherwise null. */
+    starved_since: string | null;
+}
+export interface ProtocolIngestionActivityReason {
+    status: 'retry' | 'dead' | 'invalid_job' | 'deferred' | 'abandoned';
+    reason: string | null;
+    count: number;
+}
+/** Attempts over the last window_hours; last success, last failure and failing_since look back lookback_days. */
+export interface ProtocolIngestionLaneActivity {
+    window_hours: number;
+    pages_committed: number;
+    /** Attempts that ended in a retry, a dead letter or an invalid job. */
+    failed: number;
+    deferred: number;
+    abandoned: number;
+    reasons: ProtocolIngestionActivityReason[];
+    lookback_days: number;
+    last_success_at: string | null;
+    last_failure_at: string | null;
+    /** The first failure after the last success; null when the newest finished attempt succeeded or none failed. */
+    failing_since: string | null;
+}
+export interface ProtocolIngestionDeadLetterGroup {
+    reason: string | null;
+    position: ProtocolIngestionHealthPosition;
+    count: number;
+    last_at: string | null;
+}
+/** Every dead job of the lane counted in total; the newest 20 (reason, position) groups listed. */
+export interface ProtocolIngestionLaneDeadLetters {
+    total: number;
+    last_dead_at: string | null;
+    groups: ProtocolIngestionDeadLetterGroup[];
+}
+/** One ingestion lane. A section that did not answer reads as null here and is named in the report's `unavailable`. */
+export interface ProtocolIngestionLaneHealth {
+    provider_id: string;
+    source_subscription_key: string;
+    active: boolean;
+    /** RSS only: the feeds this process reads, one page each, so a pass ends after feed_count pages. Null for other providers. */
+    feed_count: number | null;
+    jobs: ProtocolIngestionLaneJobs | null;
+    /** When a job of this lane last reached done (read every page of its pass). */
+    last_done_at: string | null;
+    /** Null when the lane has no open job or the jobs section is unavailable. */
+    current: ProtocolIngestionLaneCurrentJob | null;
+    activity: ProtocolIngestionLaneActivity | null;
+    dead_letters: ProtocolIngestionLaneDeadLetters | null;
+}
+/** A circuit row that is open, counting failures or killed: the provider's own, or (per-RSS-host circuit on) a fetch host's. */
+export interface ProtocolIngestionCircuitHealth {
+    provider_id: string;
+    kind: 'provider' | 'host';
+    /**
+     * A host circuit's fetch host: read from a readable key, or for a hashed key the configured feed host (with any
+     * explicit port) it belongs to. Null for the provider's own circuit and for a hashed key no configured feed names.
+     */
+    host: string | null;
+    /** The quota row key: `rss`, `rss--h-feeds_bbci_co_uk`, `rss--x-<hash>`. */
+    domain: string;
+    open: boolean;
+    open_until: string | null;
+    /**
+     * When the circuit last opened, or re-opened on a failed probe (open_until minus the open window). Null when it has
+     * not opened since it last closed.
+     */
+    opened_at: string | null;
+    /** Failures in a row since the circuit last closed (a host circuit's: feeds whose host never accepted the connection). */
+    failures: number;
+    killed: boolean;
+}
+/**
+ * Counts-only ingestion health for the key's app (audit row 8a): per lane, job counts, the open job's position,
+ * the last done, success and failure, 24-hour attempts by reason and dead letters by reason and position; plus the
+ * open or counting circuits. Never a checkpoint, payload, candidate or feed body.
+ */
+export interface ProtocolIngestionHealthReport {
+    generated_at: string;
+    runtime: ProtocolIngestionHealthRuntime;
+    /** Null when the lanes section is unavailable. */
+    lanes: ProtocolIngestionLaneHealth[] | null;
+    /** Open first. Null when the circuits section is unavailable. */
+    circuits: ProtocolIngestionCircuitHealth[] | null;
+    /** Sections that did not answer within their statement budget; their fields read as null. */
+    unavailable: ProtocolIngestionHealthSection[];
+}
 /** App/network scope comes only from the authenticated project-bound key. */
 export interface ListProtocolCandidatesParams {
     protocol?: string;
@@ -250,6 +378,14 @@ export type NativeNostrPrepareInput = {
     content: string;
     /** Your own post in this app (sdk.posts) that this note copies, so deleting it can offer this copy. */
     crossPostOf?: string;
+    /**
+     * A NIP-18 quote of one public note (0.7.71; accounts advertising `quote`). The server reads the note and adds its
+     * `q` and `p` tags and a `nostr:nevent` line after your text; review `quote` and the exact event before signing.
+     */
+    quote?: {
+        protocol: 'nostr';
+        nativeId: string;
+    };
 } | {
     action: 'reply';
     content: string;
@@ -662,13 +798,22 @@ export interface NativeReplyBatch {
 /** Public text and Minds-hosted images; accounts are selected explicitly in the shared editor. */
 export interface NativePostPrepareInput {
     clientMutationId: string;
+    /**
+     * The exact public text. Pass '' for a photo-only post (no words), which needs at least one `media`
+     * item: Bluesky gets an empty text with the images and Mastodon a status with only the photos, each
+     * photo's `alt` as its description. '' without media, or only spaces, is refused. Replies always need text.
+     */
     text: string;
     accountIds: string[];
     /** Minds-hosted images attached to every selected destination. Omit for a text-only post. */
     media?: NativeMediaInput[];
-    /** Native quote on Bluesky only. The server reads the source and permissions using each selected account. */
+    /**
+     * A native quote: a Bluesky record (`at://` URI), or a Mastodon status by its public URI (0.7.71) on a server that
+     * creates quote posts (Mastodon API version 7). The server reads the source and permissions using each selected account;
+     * a server without quote posts answers `quote_not_supported`, never a plain link. Nostr quotes use `prepareNativeNostr`.
+     */
     quote?: {
-        protocol: 'bluesky';
+        protocol: 'bluesky' | 'activitypub';
         nativeId: string;
     };
     /**
@@ -685,17 +830,24 @@ export interface NativePostBatch {
     deliveries: Array<Omit<NativeReplyBatch['deliveries'][number], 'kind' | 'parent' | 'recoverable' | 'replacedBy'> & {
         audience: 'public';
         maxCharacters: number;
-        quote?: {
-            protocol: 'bluesky';
-            nativeId: string;
-            cid: string;
-            authorId: string;
-            authorHandle: string;
-            sourceUrl: string;
-            text: string;
-        };
+        quote?: NativePostQuote;
     }>;
 }
+/** The reviewed quote of a delivery: Bluesky binds the record's CID, Mastodon the status's id on the member's server and its revision. */
+export type NativePostQuote = {
+    nativeId: string;
+    authorId: string;
+    authorHandle: string;
+    sourceUrl: string;
+    text: string;
+} & ({
+    protocol: 'bluesky';
+    cid: string;
+} | {
+    protocol: 'activitypub';
+    localId: string;
+    revision: string;
+});
 export interface NativeDelegatedPostHistoryItem {
     id: string;
     createdAt: string;
@@ -822,11 +974,22 @@ export interface NativeNostrPrepared {
         text: string;
         textTruncated?: boolean;
     };
+    /** The quoted note (a publish with `quote`), and the relay hint its `q` tag and `nostr:nevent` carry. */
+    quote?: {
+        protocol: 'nostr';
+        nativeId: string;
+        authorId: string;
+        authorHandle: string;
+        sourceUrl: string;
+        text: string;
+        textTruncated: boolean;
+        relay: string;
+    };
 }
 export interface NativeNostrAccount {
     enabled: boolean;
     identity: HostedProtocolIdentity | null;
-    capabilities: Array<'publish_original_text' | 'request_own_post_deletion' | 'reply_text_note' | 'publish_linked_text' | 'like' | 'unlike' | 'repost' | 'unrepost' | 'follow' | 'unfollow'>;
+    capabilities: Array<'publish_original_text' | 'request_own_post_deletion' | 'reply_text_note' | 'publish_linked_text' | 'quote' | 'like' | 'unlike' | 'repost' | 'unrepost' | 'follow' | 'unfollow'>;
     signing?: 'client';
 }
 export interface NativeNostrPostState {
@@ -1212,12 +1375,19 @@ export interface SocialRadarCluster {
      * or a party or politician. Hide politics (`compass: 'hide'`) leaves these out. Absent from a server before it was served.
      */
     political?: boolean;
+    /** Members per source kind, counted before the member cap: `outlet` counts articles, not outlets (use `outlets`). */
     sources: Partial<Record<SocialRadarSourceKind, number>>;
     corroboration: number;
+    /** Distinct outlets per lane; from 0.7.71's servers, `outlets`' two lanes. */
     laneMix: {
         mainstream: number;
         independent: number;
     };
+    /**
+     * How many outlets the story's coverage holds (StoryOutlets), from the members this read serves: the number its card,
+     * page, the News section and World Today all name. Absent from a server older than 0.7.71.
+     */
+    outlets?: StoryOutlets;
     velocity: {
         perHour: number;
         normalized: number;
@@ -1288,7 +1458,7 @@ export interface SocialRadarPosts {
 /** A story that has left the radar, as the radar's story archive keeps it (up to 30 days after it was last on the radar). */
 export interface SocialRadarStoryArchive {
     /** The story as the radar last published it. Articles keep their headline and link; a post is a member by reference only (no `title`). */
-    cluster: Pick<SocialRadarCluster, 'id' | 'label' | 'kind' | 'seed' | 'theme' | 'political' | 'sources' | 'laneMix'> & {
+    cluster: Pick<SocialRadarCluster, 'id' | 'label' | 'kind' | 'seed' | 'theme' | 'political' | 'sources' | 'laneMix' | 'outlets'> & {
         members: Array<Pick<SocialRadarMember, 'kind' | 'key' | 'url' | 'publishedAt' | 'outlet'> & {
             title?: string;
         }>;
@@ -1598,7 +1768,11 @@ export declare class ProtocolsResource {
     }): Promise<SingleResponse<SocialAuthorFeed>>;
     /**
      * Public, app-moderated discovery without account authority. Enrichment uses cached judgments only.
-     * Every page, previews included, gets the safety floor; `discovery` only asks for a layout.
+     * Every page, previews included, gets the safety floor; `discovery` only asks for a layout. `compass` (0.7.72): a
+     * visitor's Politics choice, `all` or `hide` only (a side or Mix is refused, 400 `invalid_input`). Hide politics leaves
+     * out the topics and posts whose cached browse category is politics, for every visitor, and the page says what it did
+     * in `meta.compass_filter` (`basis: 'flags'` until the operator serves visitors the full filter). An API older than
+     * 0.7.72 refuses `compass` here with a 400.
      */
     getSharedTrends(projectId: string, params: {
         protocol: string;
@@ -1607,6 +1781,7 @@ export declare class ProtocolsResource {
         includePreviews?: boolean;
         category?: string;
         discovery?: boolean;
+        compass?: string;
     }): Promise<SingleResponse<SocialTrends>>;
     /** Open a provider-listed topic through the same public-only app boundary, with the same safety floor. */
     getSharedTrendFeed(projectId: string, params: {
@@ -1673,7 +1848,8 @@ export declare class ProtocolsResource {
      * Current provider-ranked topics or posts, with explicit source and coverage. Does not ingest content.
      * Every page, previews included, gets the safety floor; `discovery` only asks for a layout. `compass` (a Politics
      * choice, spelled as `posts.list` takes it): Hide politics (`hide`) leaves out the topics and posts whose cached
-     * browse category is politics, where the filter is served to the member; a side or Mix is answered unfiltered. The
+     * browse category is politics, for every member (from 0.7.72; before, only where the filter was served to them), with
+     * `meta.compass_filter.basis` 'flags' where the full filter is not served; a side or Mix is answered unfiltered. The
      * page then says what it did in `meta.compass_filter`.
      */
     getPublicTrends(params: {
@@ -1761,7 +1937,7 @@ export declare class ProtocolsResource {
     }): Promise<SingleResponse<NativeRepostReview>>;
     /** Reconcile the saved action without sending another native write. */
     nativeRepostStatus(id: string): Promise<SingleResponse<NativeRepostReview>>;
-    /** Prepare exact public text and reviewed images for selected connected Bluesky/ActivityPub accounts. */
+    /** Prepare exact public text, reviewed images and an optional native quote for selected connected Bluesky/ActivityPub accounts. */
     prepareNativePost(input: NativePostPrepareInput): Promise<SingleResponse<NativePostBatch>>;
     /** Explicitly approve selected deliveries; never auto-retry an uncertain write. */
     submitNativePost(id: string, input: {
@@ -2005,6 +2181,17 @@ export declare class ProtocolsResource {
      * project-admin authorization as listCandidates.
      */
     ingestionStatus(): Promise<SingleResponse<ProtocolIngestionStatus>>;
+    /**
+     * Read counts-only ingestion health for the key's app: per lane, whether it
+     * reaches done or dies part way (the open job's position, failures in a row,
+     * starvation, last success and failure, attempts by reason, dead letters by
+     * reason and position), plus open or counting circuits. Read-only. Needs a
+     * project-bound admin key and current project-admin authority, but not the
+     * content_intelligence_admin binding. Scope comes only from the key, so no
+     * query is sent (the API rejects one). A section that does not answer in its
+     * budget reads as null and is listed in `unavailable`.
+     */
+    ingestionHealth(): Promise<SingleResponse<ProtocolIngestionHealthReport>>;
     /** Turn the app's ingestion kill switch on: no reservation, screening or approval proceeds. */
     killIngestion(): Promise<SingleResponse<{
         kill_switch: true;

package/dist/resources/protocols.js

@@ -123,11 +123,15 @@ export class ProtocolsResource {
     }
     /**
      * Public, app-moderated discovery without account authority. Enrichment uses cached judgments only.
-     * Every page, previews included, gets the safety floor; `discovery` only asks for a layout.
+     * Every page, previews included, gets the safety floor; `discovery` only asks for a layout. `compass` (0.7.72): a
+     * visitor's Politics choice, `all` or `hide` only (a side or Mix is refused, 400 `invalid_input`). Hide politics leaves
+     * out the topics and posts whose cached browse category is politics, for every visitor, and the page says what it did
+     * in `meta.compass_filter` (`basis: 'flags'` until the operator serves visitors the full filter). An API older than
+     * 0.7.72 refuses `compass` here with a 400.
      */
     getSharedTrends(projectId, params) {
         return this.client.get(`/protocols/public/${encodeURIComponent(projectId)}/trends`, { protocol: params.protocol, limit: params.limit, cursor: params.cursor,
-            includePreviews: params.includePreviews, category: params.category, discovery: params.discovery });
+            includePreviews: params.includePreviews, category: params.category, discovery: params.discovery, compass: params.compass });
     }
     /** Open a provider-listed topic through the same public-only app boundary, with the same safety floor. */
     getSharedTrendFeed(projectId, params) {
@@ -207,7 +211,8 @@ export class ProtocolsResource {
      * Current provider-ranked topics or posts, with explicit source and coverage. Does not ingest content.
      * Every page, previews included, gets the safety floor; `discovery` only asks for a layout. `compass` (a Politics
      * choice, spelled as `posts.list` takes it): Hide politics (`hide`) leaves out the topics and posts whose cached
-     * browse category is politics, where the filter is served to the member; a side or Mix is answered unfiltered. The
+     * browse category is politics, for every member (from 0.7.72; before, only where the filter was served to them), with
+     * `meta.compass_filter.basis` 'flags' where the full filter is not served; a side or Mix is answered unfiltered. The
      * page then says what it did in `meta.compass_filter`.
      */
     getPublicTrends(params, options) {
@@ -327,7 +332,7 @@ export class ProtocolsResource {
         hostedIdentityPath(id);
         return this.client.get(`/protocols/social/reposts/${encodeURIComponent(id)}`);
     }
-    /** Prepare exact public text and reviewed images for selected connected Bluesky/ActivityPub accounts. */
+    /** Prepare exact public text, reviewed images and an optional native quote for selected connected Bluesky/ActivityPub accounts. */
     prepareNativePost(input) {
         return this.client.post('/protocols/social/posts/prepare', { clientMutationId: input.clientMutationId,
             text: input.text, accountIds: input.accountIds,
@@ -479,7 +484,8 @@ export class ProtocolsResource {
     prepareNativeNostr(id, input) {
         hostedIdentityPath(id);
         const body = input.action === 'publish' ? { action: input.action, content: input.content,
-            ...(input.crossPostOf !== undefined ? { crossPostOf: input.crossPostOf } : {}) }
+            ...(input.crossPostOf !== undefined ? { crossPostOf: input.crossPostOf } : {}),
+            ...(input.quote ? { quote: { protocol: input.quote.protocol, nativeId: input.quote.nativeId } } : {}) }
             : input.action === 'reply' ? { action: input.action, content: input.content, parentId: input.parentId }
                 : input.action === 'linked_post' ? { action: input.action, content: input.content,
                     source: { protocol: input.source.protocol, nativeId: input.source.nativeId,
@@ -619,6 +625,19 @@ export class ProtocolsResource {
     ingestionStatus() {
         return this.client.get('/protocols/ingestion/status');
     }
+    /**
+     * Read counts-only ingestion health for the key's app: per lane, whether it
+     * reaches done or dies part way (the open job's position, failures in a row,
+     * starvation, last success and failure, attempts by reason, dead letters by
+     * reason and position), plus open or counting circuits. Read-only. Needs a
+     * project-bound admin key and current project-admin authority, but not the
+     * content_intelligence_admin binding. Scope comes only from the key, so no
+     * query is sent (the API rejects one). A section that does not answer in its
+     * budget reads as null and is listed in `unavailable`.
+     */
+    ingestionHealth() {
+        return this.client.get('/protocols/ingestion/health');
+    }
     /** Turn the app's ingestion kill switch on: no reservation, screening or approval proceeds. */
     killIngestion() {
         return this.client.post('/protocols/ingestion/kill', {});

package/dist/resources/search.d.ts

@@ -1,5 +1,5 @@
 import type { HttpClient } from '../client.js';
-import type { Post, ViewerModeration } from '../types.js';
+import type { Post, StoryOutlets, ViewerModeration } from '../types.js';
 import type { SocialPost } from './protocols.js';
 /** The sections a blended search can answer, in no particular order (see `SearchAnswer.order`). */
 export declare const SEARCH_SECTIONS: readonly ["top_posts", "latest_posts", "open_network", "people", "groups", "topics", "stories", "related", "trending"];
@@ -52,6 +52,12 @@ export interface SearchGroup {
     member_count: number;
     post_count: number;
     is_member: boolean;
+    /** The group's description as one line (legacy entities decoded, cut at a word with an ellipsis), null when it has none. Absent from an older API. */
+    description?: string | null;
+    /** When the group was last posted in (ISO 8601), null when nobody has or the API had no time to read it. Absent from an older API. */
+    last_active_at?: string | null;
+    /** The group's own words label it adult: cover its avatar. Absent from an older API. */
+    is_nsfw?: boolean;
 }
 export type SearchTopic = {
     kind: 'tag';
@@ -71,6 +77,8 @@ export interface SearchStory {
     theme: string | null;
     newest_at: string;
     sources: Partial<Record<'outlet' | 'hackernews' | 'bluesky' | 'activitypub' | 'nostr' | 'minds', number>>;
+    /** How many outlets reported it (StoryOutlets): the number every surface names for the story. Absent from a server older than 0.7.71. */
+    outlets?: StoryOutlets;
     lead: {
         type: 'image' | 'video';
         url: string;

package/dist/resources/settings.d.ts

@@ -1,5 +1,5 @@
 import type { HttpClient } from '../client.js';
-import type { ChangePasswordInput, ConfirmationCodePurpose, ConfirmationCodeSent, DeletionStatus, LoginHistoryEntry, PaginatedResponse, RequestEmailChangeInput, RevokeOtherSessionsInput, RevokeOtherSessionsResult, Session, SingleResponse, SuccessResponse, UpdateAppearanceInput, UpdateContentPreferencesInput, UpdateNotificationChannelsInput, UpdatePrivacyInput, UserPreferences } from '../types.js';
+import type { ChangePasswordInput, ConfirmationCodePurpose, ConfirmationCodeSent, DeletionStatus, DisableAccountInput, LoginHistoryEntry, PaginatedResponse, RequestEmailChangeInput, RevokeOtherSessionsInput, RevokeOtherSessionsResult, Session, SingleResponse, SuccessResponse, UpdateAppearanceInput, UpdateContentPreferencesInput, UpdateNotificationChannelsInput, UpdatePrivacyInput, UserPreferences } from '../types.js';
 export declare class SettingsResource {
     private client;
     constructor(client: HttpClient);
@@ -66,6 +66,13 @@ export declare class SettingsResource {
         success: true;
         new_email: string;
     }>>;
+    /**
+     * Deactivate the account (POST /settings/account/disable): it is hidden and nothing is deleted; signing back in
+     * restores it. Confirmed with the password and asked once (`retry: false`), so a retried 5xx never lands after the
+     * first attempt already went through. An API that does not serve deactivation answers 404 (`NotFoundError`): keep
+     * the control hidden until the app's API serves it.
+     */
+    disableAccount(input: DisableAccountInput): Promise<SuccessResponse>;
     /** Request account deletion */
     requestDeletion(input?: {
         password?: string;

package/dist/resources/settings.js

@@ -102,6 +102,15 @@ export class SettingsResource {
     verifyEmailChange(token) {
         return this.client.post('/settings/email-change/verify', { token });
     }
+    /**
+     * Deactivate the account (POST /settings/account/disable): it is hidden and nothing is deleted; signing back in
+     * restores it. Confirmed with the password and asked once (`retry: false`), so a retried 5xx never lands after the
+     * first attempt already went through. An API that does not serve deactivation answers 404 (`NotFoundError`): keep
+     * the control hidden until the app's API serves it.
+     */
+    disableAccount(input) {
+        return this.client.post('/settings/account/disable', input, { retry: false });
+    }
     /** Request account deletion */
     requestDeletion(input) {
         return this.client.post('/settings/delete-account', input);

package/dist/resources/signals.d.ts

@@ -0,0 +1,58 @@
+import type { HttpClient } from '../client.js';
+import type { SingleResponse } from '../types.js';
+/**
+ * What a member did with a post. `more_like` ("More like this") and `unhide` ("Show the post again" after "Less like
+ * this") are stored as marked clicks; an API before they were accepted answers 400 for the whole batch that carries
+ * 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. */
+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). */
+    dwell_ms?: number;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * 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).
+ */
+export type SignalNotRecordedReason = 'no_project_scope' | 'project_db_unavailable';
+export interface SignalBatchResult {
+    /** Events stored. */
+    recorded: number;
+    reason?: SignalNotRecordedReason;
+}
+export interface SignalRecordResult {
+    recorded: boolean;
+    reason?: SignalNotRecordedReason;
+}
+export interface SignalSendOptions {
+    /**
+     * The request outlives the page (`fetch` keepalive), for a flush as the page is hidden or unloads: it is on the wire
+     * before the call returns and is asked once. Browsers cap keepalive bodies (about 64 KB in flight).
+     */
+    keepalive?: boolean;
+    /** `false` asks once: a 429 or 5xx is the call's failure at once, not retried after Retry-After. */
+    retry?: boolean;
+}
+/** The most events one `signals.batch` call may carry; the server answers 400 for a larger array. */
+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`.
+ */
+export declare class SignalsResource {
+    private client;
+    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.
+     */
+    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>>;
+}

package/dist/resources/signals.js

@@ -0,0 +1,32 @@
+/** The most events one `signals.batch` call may carry; the server answers 400 for a larger array. */
+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`.
+ */
+export class SignalsResource {
+    client;
+    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.
+     */
+    batch(events, options) {
+        return this.client.post('/signals/batch', { events }, 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));
+    }
+}
+function sendOptions(options) {
+    if (!options)
+        return undefined;
+    return {
+        ...(options.retry === false ? { retry: false } : {}),
+        ...(options.keepalive ? { keepalive: true } : {}),
+    };
+}