@recursiv/sdk 0.7.83 → 0.7.89

package/dist/resources/feeds.d.ts

@@ -1,4 +1,5 @@
 import type { HttpClient } from '../client.js';
+import { type SocialProtocolId } from '../social-protocol-ids.js';
 import type { CompassFilterMeta, StoryOutlets } from '../types.js';
 /**
  * The top of a feed: what the member (or a visitor) is most likely to engage with, rotated by what they have seen.
@@ -8,9 +9,17 @@ import type { CompassFilterMeta, StoryOutlets } from '../types.js';
  * Every tap target is in the app: a Minds post by id, an open-network post by `/social/post/<protocol>/<id>`, a story
  * by id. Nothing here is a URL on another network.
  */
-/** The open networks whose lanes a top carries. */
-export type FeedTopNetwork = 'bluesky' | 'activitypub' | 'nostr';
+/**
+ * The open networks whose lanes a top may carry: every SOCIAL_PROTOCOL_IDS network (0.7.87: Farcaster before any top
+ * carries a Farcaster lane or item).
+ */
+export type FeedTopNetwork = SocialProtocolId;
 export declare const FEED_TOP_NETWORKS: readonly FeedTopNetwork[];
+/**
+ * A top's lanes, or their states, by network: Bluesky, ActivityPub and Nostr are always named; a network listed later
+ * (Farcaster) only once the API carries its lane, so read `networks.farcaster ?? []`.
+ */
+export type FeedTopNetworkMap<T> = Record<'bluesky' | 'activitypub' | 'nostr', T> & Partial<Record<FeedTopNetwork, T>>;
 /** Where a tap on an item goes, always in the app. `path` is the app's own page of a network post, never its URL there. */
 export type FeedTopTarget = {
     kind: 'post';
@@ -103,7 +112,7 @@ export interface FeedStory {
      * are politics. Hide politics (`compass: 'hide'`) leaves such a story out. Absent from a server older than 0.7.67.
      */
     political?: boolean;
-    sources: Partial<Record<'outlet' | 'hackernews' | 'bluesky' | 'activitypub' | 'nostr' | 'minds', number>>;
+    sources: Partial<Record<'outlet' | 'hackernews' | SocialProtocolId | '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;
     media: {
@@ -141,13 +150,13 @@ export interface FeedTopMeta {
     /** 'safe' for a member on safe defaults, 'open' for one who turned them off. */
     safety: 'safe' | 'open';
     mindsSource: 'member' | 'anonymous' | 'none' | 'following';
-    networks: Record<FeedTopNetwork, 'ok' | 'unavailable'> | null;
+    networks: FeedTopNetworkMap<'ok' | 'unavailable'> | null;
     compass_filter?: CompassFilterMeta;
 }
 /** GET /feeds/top. `networks` is null on a feed with no lanes (Following, a story); `lead` is null when the feed has no story. */
 export interface FeedTopResponse {
     items: FeedTopItem[];
-    networks: Record<FeedTopNetwork, FeedTopNetworkEntry[]> | null;
+    networks: FeedTopNetworkMap<FeedTopNetworkEntry[]> | null;
     lead: FeedStory | null;
     meta: FeedTopMeta;
 }
@@ -179,7 +188,7 @@ export interface PublicFeedTopMeta {
 /** A visitor's top (`feeds.publicTop`): safe items only, the same for every visitor in one 15-minute bucket. */
 export interface PublicFeedTopResponse {
     items: FeedTopItem[];
-    networks: Record<FeedTopNetwork, FeedTopNetworkEntry[]> | null;
+    networks: FeedTopNetworkMap<FeedTopNetworkEntry[]> | null;
     lead: FeedStory | null;
     meta: PublicFeedTopMeta;
 }

package/dist/resources/feeds.js

@@ -1,5 +1,6 @@
 import { NotFoundError, RecursivError } from '../errors.js';
-export const FEED_TOP_NETWORKS = ['bluesky', 'activitypub', 'nostr'];
+import { SOCIAL_PROTOCOL_IDS } from '../social-protocol-ids.js';
+export const FEED_TOP_NETWORKS = SOCIAL_PROTOCOL_IDS;
 export class FeedsResource {
     http;
     constructor(http) {

package/dist/resources/integrations.d.ts

@@ -90,6 +90,9 @@ export interface UpdateAgentIntegrationInput {
     allowed_tools?: string[];
 }
 export interface PendingToolExecution {
+    /** First-party builder identity is supplied by the server, never inferred from tool name. */
+    builder_approval?: true;
+    details_withheld?: boolean;
     id: string;
     conversation_id: string;
     agent: {

package/dist/resources/privacy.d.ts

@@ -0,0 +1,13 @@
+import type { HttpClient } from '../client.js';
+import type { PrivacyCapabilities } from '../privacy/index.js';
+import type { SingleResponse } from '../types.js';
+/**
+ * What the deployed API enforces. Pair it with `@recursiv/sdk/privacy`, which says what each fact means and whether
+ * the installed SDK marks it enforced: render a privacy sentence only when both do (`isFactLive`).
+ */
+export declare class PrivacyResource {
+    private client;
+    constructor(client: HttpClient);
+    /** GET /privacy/capabilities: the platform facts this deployment's build enforces, and its commit. Any API key. */
+    capabilities(): Promise<SingleResponse<PrivacyCapabilities>>;
+}

package/dist/resources/privacy.js

@@ -0,0 +1,14 @@
+/**
+ * What the deployed API enforces. Pair it with `@recursiv/sdk/privacy`, which says what each fact means and whether
+ * the installed SDK marks it enforced: render a privacy sentence only when both do (`isFactLive`).
+ */
+export class PrivacyResource {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    /** GET /privacy/capabilities: the platform facts this deployment's build enforces, and its commit. Any API key. */
+    capabilities() {
+        return this.client.get('/privacy/capabilities');
+    }
+}

package/dist/resources/protocols.d.ts

@@ -1,6 +1,7 @@
 import type { HttpClient } from '../client.js';
 import type { CompassFilterMeta, DiscoveryLayout, PaginatedResponse, PaginationParams, SingleResponse, StoryOutlets } from '../types.js';
 import type { CuratorStoryPostsPage } from './curator.js';
+import type { NativeWriteProtocol, SocialProtocolId } from '../social-protocol-ids.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"];
@@ -426,8 +427,55 @@ export interface FederationIdentityView {
     origin: string | null;
     identity: FederationIdentity | null;
 }
+/** A native network every eligible member is on by rule (Farcaster joins later). */
+export type NativeNetwork = 'activitypub' | 'atproto' | 'nostr';
+/**
+ * A member's state on one native network. `ready`: on by rule, set up on their first public post, first interaction
+ * there, or `activateNetwork` ("Will be set up when you first post or interact"). `pending`: being set up, or waiting
+ * for the setup budget (`retryAt`). `off`: the member turned it off (`reason: 'opted_out'`), it is not available to them
+ * yet (`not_rolled_out`), or their profile is private (`private_profile`, AT Protocol and Nostr only; `setNetwork`
+ * with `enabled: true` turns it on). `needs_action`: the member must act first (`age_band_required`,
+ * `needs_verified_email`). `locked`: held off by a rule the member cannot change.
+ */
+export type NativeNetworkState = 'ready' | 'on' | 'pending' | 'off' | 'error' | 'locked' | 'needs_action';
+export interface NativeNetworkPresence {
+    network: NativeNetwork;
+    state: NativeNetworkState;
+    /** Why, as a code: `opted_out`, `not_rolled_out`, `private_profile`, `age_band_required`, `needs_verified_email`, `activation_failed`... */
+    reason: string | null;
+    /** `hosted` (a Minds-run ActivityPub actor or AT Protocol account), `managed` (a Minds-held Nostr key) or `attached`. */
+    mode: 'hosted' | 'managed' | 'attached';
+    /** The member's address on the network, set up or not, when the server can say it. */
+    handle: string | null;
+    /** Which identity a one-tap like, repost, reply or follow uses when the member also linked an outside account. */
+    engageDefault: 'native' | 'linked';
+    activatedAt: string | null;
+    optedOutAt: string | null;
+    removePast: boolean;
+}
+export interface NativeNetworkActivation {
+    outcome: 'activated' | 'already_on' | 'pending' | 'in_flight' | 'needs_action' | 'error' | 'not_eligible' | 'refused' | 'unavailable';
+    presence: NativeNetworkPresence;
+    /** When the setup budget frees, for `pending`. */
+    retryAt: string | null;
+}
+export interface NativeNetworkOff {
+    outcome: 'off';
+    presence: NativeNetworkPresence;
+    /** `failed`: the member is off, but removing what was shared did not start; call `setNetwork` again to retry it. */
+    retraction: 'queued' | 'failed' | 'none';
+}
+export interface SetNativeNetworkInput {
+    enabled: boolean;
+    /** Turning off: also remove what was already shared there (the Settings sheet checks this by default). */
+    removePast?: boolean;
+}
 export interface SocialSourceRef {
-    protocol: 'bluesky' | 'activitypub' | 'nostr';
+    /**
+     * 0.7.87: any SOCIAL_PROTOCOL_IDS network, Farcaster (an FID, or a `<fid>:0x<hash>` CastId) before its reader serves a
+     * post. A source to show, mute, hide or report; a native write takes only a NativeWriteProtocol network.
+     */
+    protocol: SocialProtocolId;
     kind: 'actor' | 'post';
     nativeId: string;
 }
@@ -474,7 +522,7 @@ export interface NativeReplyPrepareInput {
     clientMutationId: string;
     text: string;
     parent: {
-        protocol: SocialSourceRef['protocol'];
+        protocol: NativeWriteProtocol;
         nativeId: string;
         readRef?: string;
     };
@@ -491,7 +539,7 @@ export interface NativeReplyPrepareInput {
 }
 export interface NativeFollowSourceInput {
     accountId: string;
-    protocol: SocialSourceRef['protocol'];
+    protocol: NativeWriteProtocol;
     nativeId: string;
 }
 export interface NativeFollowPrepareInput extends NativeFollowSourceInput {
@@ -536,7 +584,7 @@ export interface NativeFollowState extends NativeFollowReceipt {
 /** One connected account on the source's network, as the account lists describe it. */
 export interface NativeFollowAccount {
     id: string;
-    protocol: SocialSourceRef['protocol'];
+    protocol: NativeWriteProtocol;
     nativeId: string;
     handle: string;
     serverUrl: string;
@@ -545,7 +593,7 @@ export interface NativeFollowAccount {
 }
 /** Every connected account's relationship with one source, from one read. */
 export interface NativeFollowStates {
-    protocol: SocialSourceRef['protocol'];
+    protocol: NativeWriteProtocol;
     nativeId: string;
     /** False when native follows are off for this app; accounts are still listed, and no state is read. */
     enabled: boolean;
@@ -578,7 +626,7 @@ export interface NativeFollowReview {
 }
 export interface NativeLikeSourceInput {
     accountId: string;
-    protocol: SocialSourceRef['protocol'];
+    protocol: NativeWriteProtocol;
     nativeId: string;
 }
 export interface NativeLikePrepareInput extends NativeLikeSourceInput {
@@ -644,7 +692,7 @@ export interface NativeLikeReview {
 }
 export interface NativeRepostSourceInput {
     accountId: string;
-    protocol: SocialSourceRef['protocol'];
+    protocol: NativeWriteProtocol;
     nativeId: string;
 }
 export interface NativeRepostPrepareInput extends NativeRepostSourceInput {
@@ -773,7 +821,7 @@ export interface NativeReplyBatch {
             serverUrl: string;
         } | null;
         parent: {
-            protocol: SocialSourceRef['protocol'];
+            protocol: NativeWriteProtocol;
             nativeId: string;
             sourceUrl: string;
             authorId: string;
@@ -910,7 +958,7 @@ export interface NativeNostrReplyResult {
     text: string;
     /** `readRef`: a linked ActivityPub source's public reader id, for the conversation read (replies saved before it existed have none). */
     source: {
-        protocol: SocialSourceRef['protocol'];
+        protocol: NativeWriteProtocol;
         nativeId: string;
         sourceUrl: string;
         readRef?: string;
@@ -1321,7 +1369,8 @@ export interface SocialTrendFeed extends SocialTrendProvenance {
     };
 }
 /** A member of a radar cluster: a headline or excerpt and a link only, never a body. */
-export type SocialRadarSourceKind = 'outlet' | 'hackernews' | 'bluesky' | 'activitypub' | 'nostr' | 'minds';
+/** 0.7.87: an open-network member's kind is any SOCIAL_PROTOCOL_IDS network, Farcaster before the radar holds any. */
+export type SocialRadarSourceKind = 'outlet' | 'hackernews' | SocialProtocolId | 'minds';
 export interface SocialRadarMember {
     kind: SocialRadarSourceKind;
     /** outlet: the article url; hackernews: the `hn:<id>` candidate id; social: JSON `[protocol, nativeId]`; minds: the post id. */
@@ -1748,12 +1797,27 @@ export interface SocialConversation {
     hiddenByViewer?: true;
     viewerControls?: Array<Pick<SocialSourceControl, 'source' | 'control'>>;
 }
+/**
+ * A followed account's status on a Following page, in the server's order (SocialFollowingFeed.ts
+ * FOLLOWING_SOURCE_STATUSES). `late` (added after 0.7.82): the account's read had not answered at the page's deadline;
+ * it is read again on a later page and is never a failure. APIs before it name such an account `unavailable` with
+ * `late: true`.
+ */
+export declare const SOCIAL_FOLLOWING_SOURCE_STATUSES: readonly ["ok", "late", "unavailable", "rate_limited", "unsupported_protocol"];
+export type SocialFollowingSourceStatus = typeof SOCIAL_FOLLOWING_SOURCE_STATUSES[number];
 export interface SocialFollowingSource {
     subscriptionId: string;
     protocol: string;
     nativeId: string;
-    status: 'ok' | 'unavailable' | 'rate_limited' | 'unsupported_protocol';
+    /**
+     * `late`: the account's read has not answered yet; it is read again on a later page. `ok` with `late: true`: the
+     * account's last-held first page, served while its fresh read goes on. `unavailable` is a read that failed, or one
+     * still late after its reads again.
+     */
+    status: SocialFollowingSourceStatus;
     moreAvailable: boolean | null;
+    /** The account is read again on a later page: never show it as a failure; read the next page for its posts. */
+    late?: true;
 }
 /** A bounded batch of recent author windows. Continue the cursor to read more followed accounts. */
 export interface SocialFollowingFeed {
@@ -1764,6 +1828,10 @@ export interface SocialFollowingFeed {
     totalAccounts: number;
     postsPerAccount: number;
     coverage: 'recent_original_posts';
+    /** The networks with an account named late on this page (absent from older APIs). */
+    lateNetworks?: string[];
+    /** How long this page waited for an account's first read on each network, in ms (absent from older APIs). */
+    deadlineMs?: number;
 }
 export declare class ProtocolsResource {
     private client;
@@ -2134,6 +2202,26 @@ export declare class ProtocolsResource {
         disconnected: true;
         providerRevocation: 'acknowledged' | 'unconfirmed';
     }>>;
+    /**
+     * The signed-in member's native networks in the key's app (ActivityPub, AT Protocol, Nostr): each one's state, reason
+     * and address. Read-only: it never sets anything up. Needs `users:read`.
+     */
+    networks(): Promise<SingleResponse<{
+        networks: NativeNetworkPresence[];
+    }>>;
+    /**
+     * "Set up now": sets up a network that is `ready` (or `pending`, or failed) at once, instead of on the member's first
+     * post. Never undoes their off switch (409 `network_off`) or a private profile's rule (409 `private_profile`): use
+     * `setNetwork` for those. Over the setup budget it answers `pending` with `retryAt`. Needs `users:write`.
+     */
+    activateNetwork(network: NativeNetwork): Promise<SingleResponse<NativeNetworkActivation>>;
+    /**
+     * The member's switch for one network. `{ enabled: false, removePast: true }` turns it off and removes what was
+     * shared there (reversible: turning it back on serves the same identity; remote followers may need to follow again).
+     * `{ enabled: true }` turns it back on or sets it up. Refusals: 403 `network_locked`, 409 `not_rolled_out` or
+     * `age_band_required`. Needs `users:write`.
+     */
+    setNetwork(network: NativeNetwork, input: SetNativeNetworkInput): Promise<SingleResponse<NativeNetworkActivation | NativeNetworkOff>>;
     /** Current Minds-hosted ActivityPub state for this app user; never provisions. */
     federationIdentity(): Promise<SingleResponse<FederationIdentityView>>;
     /** Explicit opt-in; the platform provisions once and never rotates keys or re-enables a disabled identity on retry. */

package/dist/resources/protocols.js

@@ -28,6 +28,13 @@ export const PROTOCOL_ADAPTER_MATURITIES = Object.freeze([
     'beta',
     'stable',
 ]);
+const NATIVE_NETWORKS = ['activitypub', 'atproto', 'nostr'];
+function nativeNetworkPath(network) {
+    if (!NATIVE_NETWORKS.includes(network)) {
+        throw new ValidationError({ type: 'validation_error', code: 'invalid_network', message: 'network must be activitypub, atproto or nostr' });
+    }
+    return `/protocols/networks/${network}`;
+}
 function hostedIdentityPath(id) {
     if (!/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(id)) {
         throw new ValidationError({ type: 'validation_error', code: 'invalid_identity_id', message: 'A valid hosted identity connection ID is required' });
@@ -42,6 +49,19 @@ function hostedIdentityPath(id) {
 export function viralItemHasVideo(item) {
     return item.post.media.some(media => media.type === 'video');
 }
+/**
+ * A followed account's status on a Following page, in the server's order (SocialFollowingFeed.ts
+ * FOLLOWING_SOURCE_STATUSES). `late` (added after 0.7.82): the account's read had not answered at the page's deadline;
+ * it is read again on a later page and is never a failure. APIs before it name such an account `unavailable` with
+ * `late: true`.
+ */
+export const SOCIAL_FOLLOWING_SOURCE_STATUSES = Object.freeze([
+    'ok',
+    'late',
+    'unavailable',
+    'rate_limited',
+    'unsupported_protocol',
+]);
 /** Only the radar's own fields travel; caller scope or destination extras never reach the query string. */
 /** Forwarded only when given, so a default read makes exactly the call it always made. */
 const readOptions = (options) => options ? [options] : [];
@@ -488,6 +508,31 @@ export class ProtocolsResource {
         hostedIdentityPath(id);
         return this.client.delete(`/protocols/social/accounts/${encodeURIComponent(id)}`);
     }
+    /**
+     * The signed-in member's native networks in the key's app (ActivityPub, AT Protocol, Nostr): each one's state, reason
+     * and address. Read-only: it never sets anything up. Needs `users:read`.
+     */
+    networks() {
+        return this.client.get('/protocols/networks');
+    }
+    /**
+     * "Set up now": sets up a network that is `ready` (or `pending`, or failed) at once, instead of on the member's first
+     * post. Never undoes their off switch (409 `network_off`) or a private profile's rule (409 `private_profile`): use
+     * `setNetwork` for those. Over the setup budget it answers `pending` with `retryAt`. Needs `users:write`.
+     */
+    activateNetwork(network) {
+        return this.client.post(`${nativeNetworkPath(network)}/activate`, {});
+    }
+    /**
+     * The member's switch for one network. `{ enabled: false, removePast: true }` turns it off and removes what was
+     * shared there (reversible: turning it back on serves the same identity; remote followers may need to follow again).
+     * `{ enabled: true }` turns it back on or sets it up. Refusals: 403 `network_locked`, 409 `not_rolled_out` or
+     * `age_band_required`. Needs `users:write`.
+     */
+    setNetwork(network, input) {
+        const body = input.enabled ? { enabled: true } : { enabled: false, ...(input.removePast !== undefined ? { remove_past: input.removePast } : {}) };
+        return this.client.put(nativeNetworkPath(network), body);
+    }
     /** Current Minds-hosted ActivityPub state for this app user; never provisions. */
     federationIdentity() {
         return this.client.get('/protocols/social/federation/identity');

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,