@recursiv/sdk 0.7.83 → 0.7.93

package/dist/resources/sealed.d.ts

@@ -25,6 +25,12 @@ export interface SealedTarget {
     /** Exact origin, e.g. `https://router-0.tinfoil.sh`. */
     origin: string;
     kind: SealedTargetKind;
+    /**
+     * Web search works through this target: seal a message that may search only to a target that says true. Set on
+     * `SealedConfig.targets` only, never in a model's own list (look the origin up there). Absent (an older gateway)
+     * means no.
+     */
+    search?: boolean;
 }
 /** A model the app offers in Sealed. */
 export interface SealedModel {
@@ -36,6 +42,8 @@ export interface SealedModel {
      * when one has moved to another target, so read it per model.
      */
     targets: SealedTarget[];
+    /** The app may send pictures to this model. Absent (an older gateway) means no. */
+    vision?: boolean;
 }
 /** What `config()` returns. */
 export interface SealedConfig {
@@ -45,11 +53,73 @@ export interface SealedConfig {
     attestation_path: string;
     /** Every target the gateway forwards to, chat and attestation alike. */
     targets: SealedTarget[];
-    /** The models the app offers in Sealed, each with the targets that serve it. */
+    /** The models the app offers to chat with in Sealed, each with the targets that serve it. */
     models: SealedModel[];
+    /**
+     * The models the app's sealed checks run on (a safeguard model for the message and answer checks, a vision model for
+     * the picture check), each with the targets that serve it. Never offer one of these as a chat model unless `models`
+     * lists it too. Send a check with `send({ purpose: 'check' })`. Absent on an older gateway.
+     */
+    checks?: SealedModel[];
+    /**
+     * Server switch (George plan G7a): web search through the router. Send a message that may search with
+     * `send({ search: true })`, which marks it `X-Sealed-Search: 1`; the gateway refuses a marked message while this is
+     * off (403 `sealed_search_off`), and pauses the member's day when an unmarked one searches. Off unless the gateway
+     * says true: treat it absent, or a config you could not read, as off.
+     */
+    search?: boolean;
+    /** Server switch (G7a): pictures from the phone, off unless true. Post pictures need only the model's `vision`. */
+    phone_pictures?: boolean;
+    /**
+     * Server switch: on-phone memory, off unless true. The memory lives on the phone and the gateway never sees it; this
+     * is the server's switch for the feature, so it can be turned off for everyone at once. Absent (an older gateway), or
+     * a config you could not read, means off.
+     */
+    memory?: boolean;
     /** The attestation policy version the app's verifier must pin; an older pinned policy means the app needs updating. */
     verifier_policy_version: number;
+    /** The member's allowance: its daily numbers are their plan's (`plan`). */
     allowance: SealedAllowance;
+    /** The plan the daily numbers in `allowance` follow. Free when the gateway could not read it. Absent on an older gateway. */
+    plan?: SealedPlan;
+    /** False when the gateway could not read the member's plan and applied Free's numbers: do not tell them they are on Free. */
+    plan_known?: boolean;
+    /** What is left of each daily allowance now; `checks` only while checks count apart. Absent when it could not be read. */
+    remaining_today?: {
+        requests: number;
+        searches: number;
+        checks?: number;
+    };
+    /**
+     * Every plan's daily numbers, so the app can say truthfully whether a plan gives more. It lists plans the gateway
+     * knows, Max among them, whether or not anyone sells them: offer only the plans the app sells.
+     */
+    plan_allowances?: Record<SealedPlan, {
+        requests_per_day: number;
+        searches_per_day: number;
+        checks_per_day?: number;
+    }>;
+    /**
+     * `budget` while the app's monthly Sealed budget is used up (sends get 503 `sealed_paused_budget` until the next UTC
+     * month), `unavailable` while the gateway cannot tell (sends get 503 `sealed_unavailable`), null otherwise.
+     */
+    paused?: 'budget' | 'unavailable' | null;
+}
+/** The plans the gateway knows, lowest first. */
+export type SealedPlan = 'free' | 'plus' | 'pro' | 'max';
+/**
+ * `details` on a refused send whose allowance ran out (RateLimitError.details): which limit, the member's plan, whether
+ * that plan was read (`plan_known`; false: Free's numbers were applied because the read failed), that plan's daily
+ * number (null for `rate`, the per-minute and open-request caps no plan changes), and the plans that give more of it
+ * (empty for `rate` and while the plan is not known). Say "upgrade for more" only when a plan the app sells is in
+ * `higher_plans`.
+ */
+export interface SealedQuotaDetails {
+    limit: 'messages' | 'searches' | 'checks' | 'rate';
+    plan: SealedPlan;
+    plan_known: boolean;
+    per_day: number | null;
+    higher_plans: SealedPlan[];
 }
 export interface SealedAllowance {
     requests_per_day: number;
@@ -57,7 +127,25 @@ export interface SealedAllowance {
     max_concurrent: number;
     /** The cap on one sealed request body, in bytes. */
     max_request_bytes: number;
+    /**
+     * Checks (`send({ purpose: 'check' })`) per UTC day, counted instead of `requests_per_day`. Absent while the gateway
+     * counts checks as messages (its check allowance is off), and on an older gateway: a check then spends a message.
+     */
+    checks_per_day?: number;
+    /** Checks per minute, counted instead of `requests_per_minute`. Absent when `checks_per_day` is. */
+    checks_per_minute?: number;
+    /**
+     * Messages marked as searches per UTC day. A marked search spends a search and no message; a gateway from before plans
+     * counted it against `requests_per_day` as well.
+     */
+    searches_per_day?: number;
 }
+/**
+ * What a sealed request is for, sent as `X-Sealed-Purpose`, which the gateway reads and never forwards. `check`: one of
+ * the app's sealed checks, counted against the check allowance instead of the message allowance while the gateway has
+ * one (`config().allowance.checks_per_day`), and as a message otherwise.
+ */
+export type SealedPurpose = 'check';
 export interface SealedSendInput {
     /** The router the app verified and sealed to: the origin of a `router` target from `config()`, exactly. */
     enclaveOrigin: string;
@@ -67,6 +155,19 @@ export interface SealedSendInput {
     body: Uint8Array | ArrayBuffer | ReadableStream<Uint8Array>;
     /** Ask for a streamed (server-sent events) answer. */
     stream?: boolean;
+    /**
+     * `check` for one of the app's sealed checks (a model from `config().checks`): sent as `X-Sealed-Purpose: check`, so
+     * it counts against the check allowance while the gateway lists one. Omit it for a message.
+     */
+    purpose?: SealedPurpose;
+    /**
+     * True for a message that may search the web: sent as `X-Sealed-Search: 1`, which the gateway reads and never
+     * forwards. It counts against the day's searches instead of its messages, and the gateway refuses it while
+     * `config().search` is off. Only a marked message may carry search options in its sealed body: the gateway pauses the
+     * member's day when an unmarked request searches. Never with `purpose: 'check'` (a check never searches): that is
+     * refused before anything is sent.
+     */
+    search?: boolean;
     /** The targets from a config already read. When omitted, `send()` reads the config first. */
     targets?: readonly SealedTarget[];
     signal?: AbortSignal;
@@ -93,6 +194,10 @@ export type SealedTransportErrorCode =
  | 'bad_encapsulated_key'
 /** The attestation nonce is not 32 bytes of hex: nothing was sent. */
  | 'bad_nonce'
+/** The purpose is not one the gateway takes: nothing was sent. */
+ | 'bad_purpose'
+/** The marks do not go together (`search` on a check), or `search` is not a boolean: nothing was sent. */
+ | 'bad_marks'
 /** A 2xx answer without a valid Ehbp-Response-Nonce: its body was discarded unread. */
  | 'unsealed_answer';
 export declare class SealedTransportError extends Error {
@@ -102,8 +207,10 @@ export declare class SealedTransportError extends Error {
 /** Set on a refusal the gateway wrote itself; a relayed router answer never carries it. */
 export declare const SEALED_REFUSAL_HEADER = "x-sealed-gateway-refusal";
 /**
- * Requests left in the member's allowance today. The gateway sets it on every answer it relayed from the router and on
- * no other, and the router cannot set it, so an error without it is one the API (or an edge in front of it) wrote.
+ * Messages left in the member's allowance today, on a check as on a message. The gateway sets it on every answer it
+ * relayed from the router and on no other, and the router cannot set it, so an error without it is one the API (or an
+ * edge in front of it) wrote. A relayed answer to a check also carries `X-Sealed-Checks-Remaining` while the gateway
+ * has a check allowance, and one to a marked search `X-Sealed-Searches-Remaining`.
  */
 export declare const SEALED_ALLOWANCE_REMAINING_HEADER = "x-sealed-allowance-remaining";
 export declare class SealedResource {
@@ -135,10 +242,23 @@ export declare class SealedResource {
      *   has no nonce, never to be shown as the model's words.
      *
      * Throws a RecursivError for every error the API wrote rather than relayed, whether or not it is marked
-     * X-Sealed-Gateway-Refusal: RateLimitError for an allowance used up (`code` `sealed_allowance_used` or
-     * `sealed_too_many_requests`) or the API's own per-IP limit (`rate_limited`), AuthenticationError for a revoked or
-     * expired key, NotFoundError while Sealed is off or not on for this app. Throws SealedTransportError when the router
-     * is not listed, the key is malformed, or a 2xx answer came back unsealed.
+     * X-Sealed-Gateway-Refusal: RateLimitError for an allowance used up (`code` `sealed_allowance_used`,
+     * `sealed_search_allowance_used` or `sealed_too_many_requests`, with SealedQuotaDetails in `details`) or the API's own
+     * per-IP limit (`rate_limited`), a RecursivError with status 503 and `code` `sealed_paused_budget` while the app's
+     * monthly Sealed budget is used up (until the next UTC month), AuthenticationError for a revoked or expired key,
+     * NotFoundError while Sealed is off or not on for this app, AuthorizationError (`sealed_search_off`) for a marked
+     * search while search is off. Throws SealedTransportError when the router is not listed, the key, purpose or marks
+     * are malformed, or a 2xx answer came back unsealed.
+     *
+     * With `purpose: 'check'` the request counts against the check allowance while the gateway has one (`code`
+     * `sealed_check_allowance_used` when it is used up), and as a message otherwise. With `search: true` it counts
+     * against the day's searches (`sealed_search_allowance_used`) and spends no message. While the gateway's day lock is
+     * on, a member is refused until midnight UTC (`sealed_paused_today`) after a request of theirs that searched the web
+     * unmarked (or marked a check), that the router answered with a model `config()` does not offer for it (a check's must
+     * be in `checks`; any other's in `models`, or in `checks` while the gateway lets checks sent unmarked through), or
+     * that passed the day's count of answers left before their usage line (searches included). The lists can change on
+     * the server: read `config()` again from time to time, not once for the app's whole run, or a member whose app still
+     * sends to a model taken out of them is paused.
      */
     send(input: SealedSendInput): Promise<Response>;
 }

package/dist/resources/sealed.js

@@ -10,8 +10,10 @@ export class SealedTransportError extends Error {
 /** Set on a refusal the gateway wrote itself; a relayed router answer never carries it. */
 export const SEALED_REFUSAL_HEADER = 'x-sealed-gateway-refusal';
 /**
- * Requests left in the member's allowance today. The gateway sets it on every answer it relayed from the router and on
- * no other, and the router cannot set it, so an error without it is one the API (or an edge in front of it) wrote.
+ * Messages left in the member's allowance today, on a check as on a message. The gateway sets it on every answer it
+ * relayed from the router and on no other, and the router cannot set it, so an error without it is one the API (or an
+ * edge in front of it) wrote. A relayed answer to a check also carries `X-Sealed-Checks-Remaining` while the gateway
+ * has a check allowance, and one to a marked search `X-Sealed-Searches-Remaining`.
  */
 export const SEALED_ALLOWANCE_REMAINING_HEADER = 'x-sealed-allowance-remaining';
 const HEX_32_BYTES = /^[0-9a-fA-F]{64}$/;
@@ -95,10 +97,23 @@ export class SealedResource {
      *   has no nonce, never to be shown as the model's words.
      *
      * Throws a RecursivError for every error the API wrote rather than relayed, whether or not it is marked
-     * X-Sealed-Gateway-Refusal: RateLimitError for an allowance used up (`code` `sealed_allowance_used` or
-     * `sealed_too_many_requests`) or the API's own per-IP limit (`rate_limited`), AuthenticationError for a revoked or
-     * expired key, NotFoundError while Sealed is off or not on for this app. Throws SealedTransportError when the router
-     * is not listed, the key is malformed, or a 2xx answer came back unsealed.
+     * X-Sealed-Gateway-Refusal: RateLimitError for an allowance used up (`code` `sealed_allowance_used`,
+     * `sealed_search_allowance_used` or `sealed_too_many_requests`, with SealedQuotaDetails in `details`) or the API's own
+     * per-IP limit (`rate_limited`), a RecursivError with status 503 and `code` `sealed_paused_budget` while the app's
+     * monthly Sealed budget is used up (until the next UTC month), AuthenticationError for a revoked or expired key,
+     * NotFoundError while Sealed is off or not on for this app, AuthorizationError (`sealed_search_off`) for a marked
+     * search while search is off. Throws SealedTransportError when the router is not listed, the key, purpose or marks
+     * are malformed, or a 2xx answer came back unsealed.
+     *
+     * With `purpose: 'check'` the request counts against the check allowance while the gateway has one (`code`
+     * `sealed_check_allowance_used` when it is used up), and as a message otherwise. With `search: true` it counts
+     * against the day's searches (`sealed_search_allowance_used`) and spends no message. While the gateway's day lock is
+     * on, a member is refused until midnight UTC (`sealed_paused_today`) after a request of theirs that searched the web
+     * unmarked (or marked a check), that the router answered with a model `config()` does not offer for it (a check's must
+     * be in `checks`; any other's in `models`, or in `checks` while the gateway lets checks sent unmarked through), or
+     * that passed the day's count of answers left before their usage line (searches included). The lists can change on
+     * the server: read `config()` again from time to time, not once for the app's whole run, or a member whose app still
+     * sends to a model taken out of them is paused.
      */
     async send(input) {
         // Malformed input is refused here, before the config is read, so it never turns into a network error.
@@ -109,6 +124,15 @@ export class SealedResource {
         if (!HEX_32_BYTES.test(input.encapsulatedKey)) {
             throw new SealedTransportError('bad_encapsulated_key', 'The encapsulated key must be 32 bytes of hex. Nothing was sent.');
         }
+        if (input.purpose !== undefined && input.purpose !== 'check') {
+            throw new SealedTransportError('bad_purpose', 'The purpose must be "check" or left out. Nothing was sent.');
+        }
+        if (input.search !== undefined && typeof input.search !== 'boolean') {
+            throw new SealedTransportError('bad_marks', 'search must be true, false or left out. Nothing was sent.');
+        }
+        if (input.search === true && input.purpose === 'check') {
+            throw new SealedTransportError('bad_marks', 'A check never searches: search cannot go with purpose "check". Nothing was sent.');
+        }
         const targets = input.targets ?? (await this.config()).targets;
         if (!targets.some((target) => target.origin === origin && target.kind === 'router')) {
             throw new SealedTransportError('enclave_not_allowed', 'That router is not one the gateway forwards to. Nothing was sent.');
@@ -137,6 +161,9 @@ export class SealedResource {
                     // receives a request marked Sealed is meant to refuse it. No server path reads this header yet, so nothing
                     // enforces that today; the Sealed gateway strips it before the router.
                     'X-Recursiv-Privacy-Tier': 'sealed',
+                    // Read by the gateway to pick the allowance, and never forwarded to the router.
+                    ...(input.purpose === 'check' ? { 'X-Sealed-Purpose': 'check' } : {}),
+                    ...(input.search === true ? { 'X-Sealed-Search': '1' } : {}),
                 },
                 body: input.body,
                 signal: controller.signal,

package/dist/resources/settings.d.ts

@@ -22,7 +22,9 @@ export declare class SettingsResource {
     updateAppearance(input: UpdateAppearanceInput): Promise<SuccessResponse>;
     /**
      * Update per-user content preferences for the app bound to this API key.
-     * Requires a project-bound key with `settings:write`.
+     * Requires a project-bound key with `settings:write`. `sealed_adult: true`
+     * is refused (403 `AuthorizationError`, code `sealed_adult_needs_adult`, and
+     * nothing in the request is saved) unless the member answered 18 or older.
      */
     updateContent(input: UpdateContentPreferencesInput): Promise<SuccessResponse>;
     /** List active sessions */

package/dist/resources/settings.js

@@ -45,7 +45,9 @@ export class SettingsResource {
     }
     /**
      * Update per-user content preferences for the app bound to this API key.
-     * Requires a project-bound key with `settings:write`.
+     * Requires a project-bound key with `settings:write`. `sealed_adult: true`
+     * is refused (403 `AuthorizationError`, code `sealed_adult_needs_adult`, and
+     * nothing in the request is saved) unless the member answered 18 or older.
      */
     updateContent(input) {
         return this.client.put('/settings/preferences/content', input);

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/social-protocol-ids.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Every open network id the API may name a post, an account or a source by (`protocol` on a SocialPost, a SocialProfile,
+ * a SocialSourceRef, a radar member's `kind`, a feed top's `network_post` and lane). The server's twin is
+ * packages/server/src/lib/socialProtocolIds.ts, and its socialProtocolIds test holds the two equal.
+ *
+ * Readers first (0.7.87): `farcaster` is listed one release before any server reader emits it, so an app on this SDK
+ * shows a Farcaster post, radar member or top item the day the API starts serving them, with no app update. Listing an
+ * id serves nothing: which networks an app can read is still `publicNetworks()` / `sharedNetworks(projectId)`, and a
+ * network the catalog does not list never appears. An id a later SDK adds is skipped by this one, never an error.
+ *
+ * Farcaster ids, as the server checks them: an account is its FID in decimal ("3"); a cast is its CastId,
+ * `<fid>:0x<40 lowercase hex>` (its author's FID and its message hash).
+ */
+export declare const SOCIAL_PROTOCOL_IDS: readonly ["bluesky", "activitypub", "nostr", "farcaster"];
+export type SocialProtocolId = (typeof SOCIAL_PROTOCOL_IDS)[number];
+/** Whether `value` is an open network id this SDK knows. */
+export declare function isSocialProtocolId(value: unknown): value is SocialProtocolId;
+/**
+ * The networks a member's native write may act on (0.7.87): the source a reply, follow, like or repost names
+ * (`NativeReplyPrepareInput.parent`, `NativeFollowSourceInput`, `NativeLikeSourceInput`, `NativeRepostSourceInput`), and
+ * the account lists and results those writes answer. Narrower than SOCIAL_PROTOCOL_IDS on purpose: a network is read
+ * before it is written, so a Farcaster post can be shown, muted, hidden or reported (`SocialSourceRef`) while the API
+ * still refuses a Farcaster write (400 `invalid_input`). Check `isNativeWriteProtocol(post.protocol)` before offering one.
+ */
+export declare const NATIVE_WRITE_PROTOCOLS: readonly ["bluesky", "activitypub", "nostr"];
+export type NativeWriteProtocol = (typeof NATIVE_WRITE_PROTOCOLS)[number];
+/** Whether a member's native write may act on a source of network `value` (NATIVE_WRITE_PROTOCOLS). */
+export declare function isNativeWriteProtocol(value: unknown): value is NativeWriteProtocol;

package/dist/social-protocol-ids.js

@@ -0,0 +1,30 @@
+/**
+ * Every open network id the API may name a post, an account or a source by (`protocol` on a SocialPost, a SocialProfile,
+ * a SocialSourceRef, a radar member's `kind`, a feed top's `network_post` and lane). The server's twin is
+ * packages/server/src/lib/socialProtocolIds.ts, and its socialProtocolIds test holds the two equal.
+ *
+ * Readers first (0.7.87): `farcaster` is listed one release before any server reader emits it, so an app on this SDK
+ * shows a Farcaster post, radar member or top item the day the API starts serving them, with no app update. Listing an
+ * id serves nothing: which networks an app can read is still `publicNetworks()` / `sharedNetworks(projectId)`, and a
+ * network the catalog does not list never appears. An id a later SDK adds is skipped by this one, never an error.
+ *
+ * Farcaster ids, as the server checks them: an account is its FID in decimal ("3"); a cast is its CastId,
+ * `<fid>:0x<40 lowercase hex>` (its author's FID and its message hash).
+ */
+export const SOCIAL_PROTOCOL_IDS = Object.freeze(['bluesky', 'activitypub', 'nostr', 'farcaster']);
+/** Whether `value` is an open network id this SDK knows. */
+export function isSocialProtocolId(value) {
+    return typeof value === 'string' && SOCIAL_PROTOCOL_IDS.includes(value);
+}
+/**
+ * The networks a member's native write may act on (0.7.87): the source a reply, follow, like or repost names
+ * (`NativeReplyPrepareInput.parent`, `NativeFollowSourceInput`, `NativeLikeSourceInput`, `NativeRepostSourceInput`), and
+ * the account lists and results those writes answer. Narrower than SOCIAL_PROTOCOL_IDS on purpose: a network is read
+ * before it is written, so a Farcaster post can be shown, muted, hidden or reported (`SocialSourceRef`) while the API
+ * still refuses a Farcaster write (400 `invalid_input`). Check `isNativeWriteProtocol(post.protocol)` before offering one.
+ */
+export const NATIVE_WRITE_PROTOCOLS = Object.freeze(['bluesky', 'activitypub', 'nostr']);
+/** Whether a member's native write may act on a source of network `value` (NATIVE_WRITE_PROTOCOLS). */
+export function isNativeWriteProtocol(value) {
+    return typeof value === 'string' && NATIVE_WRITE_PROTOCOLS.includes(value);
+}