@fias/arche-sdk 2.27.0 → 2.29.0

package/dist/types.d.ts

@@ -887,6 +887,16 @@ export interface FiasNavigationApi {
 export type ArcheHandoffPayloadInput = {
     kind: 'open_document';
     documentId: string;
+}
+/**
+ * Open a chat channel in the Chat arche (`openArche('arche_chat', …)`).
+ * `channelId` is `cch_` + 32 lowercase hex. A pointer, never access: Chat
+ * re-reads the channel under the user's own membership, and a non-member
+ * lands on the Chat home with a notice — make the user a member first.
+ */
+ | {
+    kind: 'open_channel';
+    channelId: string;
 } | {
     kind: 'sign_document';
     /** Idempotency key for this signing request. One uuid per user intent. */
@@ -1045,7 +1055,9 @@ export interface VaultUserDocumentSaveContentResult extends VaultDocumentSaveCon
 export interface VaultDocumentSearchOptions {
     /** Number of results to return. 1..50, default 10. */
     topK?: number;
-    /** Minimum cosine similarity (0..1). Default 0.5. */
+    /** Minimum cosine similarity (0..1). Default: the floor of the platform's
+     * current embedding model, which the platform keeps calibrated as the model
+     * changes — pass a value only when you have measured one for your corpus. */
     minSimilarity?: number;
     /** When false, results omit the chunk content. Default true. */
     includeContent?: boolean;
@@ -1183,12 +1195,26 @@ export interface VaultDocumentUploadInitResult {
     requiredHeaders: Record<string, string>;
     /** ISO 8601 timestamp when the upload URL expires. */
     uploadUrlExpiresAt: string;
+    /**
+     * Where the file was kept: `'workspace'` when the user is working in a team
+     * workspace that approved your arche to keep its files there (every member
+     * using your arche can open it), `'personal'` otherwise (only this person
+     * can). Absent on servers older than this field.
+     */
+    space?: 'workspace' | 'personal';
 }
 export interface VaultDocumentUploadResult {
     documentId: string;
     /** Status after finalize — `'uploaded'`, then `'available'` once the
      *  extraction worker indexes the document for search. */
     status: string;
+    /**
+     * Where the file was kept: `'workspace'` when the user is working in a team
+     * workspace that approved your arche to keep its files there (every member
+     * using your arche can open it), `'personal'` otherwise (only this person
+     * can). Absent on servers older than this field.
+     */
+    space?: 'workspace' | 'personal';
     /**
      * Only on a save into the user's Documents (`destination: 'documents'`,
      * `saveCopy`): the name the user kept — it may differ from the one you
@@ -1229,6 +1255,15 @@ export interface VaultDocumentReferenceResult {
  *   - `vault:documents:read` — list, read, getDownloadUrl
  *   - `vault:documents:write` — write, update, delete
  *
+ * Where the files live: in the person's own Vault — or, while they work in a
+ * team workspace whose owner or admin approved your arche, in that
+ * workspace's Vault, counted against the workspace's storage. There the
+ * files are the team's: every member using your arche lists and opens them,
+ * members and above change them, viewers only open them
+ * (`WORKSPACE_VIEWER_READ_ONLY`). A document id saved before the approval
+ * still opens for the person who saved it. `write`/`upload` report which
+ * one they used (`space`).
+ *
  * Note: images returned from useImageGeneration() are auto-saved into
  * the arche's folder and the result includes a `documentId`. Pass that
  * documentId here to refresh the presigned URL after the original ~1h
@@ -1320,6 +1355,7 @@ export interface VaultDocumentsApi {
      *  the bridge request body). For binaries or larger documents use `upload`. */
     write: (params: VaultDocumentWriteParams) => Promise<{
         documentId: string;
+        space?: 'workspace' | 'personal';
     }>;
     /** Rename or retag a document. */
     update: (documentId: string, params: VaultDocumentUpdateParams) => Promise<void>;
@@ -1383,9 +1419,13 @@ export interface VaultDocumentsApi {
         checksumSha256: string;
     }) => Promise<VaultDocumentUploadResult>;
 }
+/** Media kind of a library asset — what `list` / `index` filter by. */
+export type ArcheAssetKind = 'image' | 'audio';
 /**
- * One entry from the arche's published asset manifest. Surfaced to
- * plugins via `useArcheAssets().list()`.
+ * One IMAGE from the arche's published asset manifest — what
+ * `useArcheAssets().list()` returns when you name no `kinds`. A listing that
+ * names `kinds` returns {@link ArcheLibraryAsset}, which may also hold
+ * {@link ArcheSoundAsset} entries.
  *
  * `signedUrl` is a short-lived (~5 min default) URL that loads through
  * api.fias.ai's signed proxy. Plugins should use `getUrl(assetId)` to
@@ -1414,6 +1454,23 @@ export interface ArcheAsset {
      */
     workspaceId?: string | null;
 }
+/**
+ * A short sound effect from the asset library (≤ 1 MB, ≤ 30 s). Returned only
+ * by a listing whose `kinds` include `'audio'`. Play it through Web Audio:
+ * read its bytes with `useArcheAssetBytes()` and decode them once.
+ */
+export interface ArcheSoundAsset extends Omit<ArcheAsset, 'contentType' | 'width' | 'height'> {
+    /** MP3 or WAV — both decode with `decodeAudioData` in every browser. */
+    contentType: 'audio/mpeg' | 'audio/wav';
+    /** Sounds have no pixel grid. */
+    width: null;
+    height: null;
+}
+/**
+ * Any library asset: an image or a sound. Narrow on `contentType` (or on
+ * `width !== null`) before using an image's dimensions.
+ */
+export type ArcheLibraryAsset = ArcheAsset | ArcheSoundAsset;
 export interface ArcheAssetsListOptions {
     cursor?: string;
     /** 1..1000. Default 50. */
@@ -1424,9 +1481,16 @@ export interface ArcheAssetsListOptions {
      * `['category:background']` — instead of pulling the whole manifest.
      */
     tags?: string[];
+    /**
+     * Which media kinds to return. Default `['image']`, so a plugin written
+     * before the library held sounds never receives one. Pass `['audio']` for
+     * sound effects, or `['image', 'audio']` for both.
+     */
+    kinds?: ArcheAssetKind[];
 }
-export interface ArcheAssetsListResult {
-    entries: ArcheAsset[];
+/** A page of the listing. `T` is {@link ArcheLibraryAsset} when you listed with `kinds`. */
+export interface ArcheAssetsListResult<T extends ArcheLibraryAsset = ArcheAsset> {
+    entries: T[];
     nextCursor: string | null;
 }
 export interface ArcheAssetsIndexOptions {
@@ -1434,6 +1498,8 @@ export interface ArcheAssetsIndexOptions {
     tags?: string[];
     /** Tag prefix that defines a folder. Defaults to `subject:`. */
     groupBy?: string;
+    /** Which media kinds to index. Default `['image']` (see ArcheAssetsListOptions.kinds). */
+    kinds?: ArcheAssetKind[];
 }
 /** A folder in the faceted library index: one signed cover + member count. */
 export interface ArcheAssetGroup {
@@ -1446,6 +1512,11 @@ export interface ArcheAssetGroup {
         signedUrl: string;
         /** Unix-seconds expiry of `signedUrl`. */
         expiresAt: number;
+        /**
+         * The cover's content type. An image whenever the folder has one; a
+         * sound only for an audio-only folder (indexed with `kinds: ['audio']`).
+         */
+        contentType: ArcheLibraryAsset['contentType'];
         /** Representative member tags — category/subject/subcat/theme/tier. */
         tags: string[];
     };
@@ -1454,24 +1525,95 @@ export interface ArcheAssetsIndexResult {
     groups: ArcheAssetGroup[];
 }
 /**
- * Asset library API. Permission: `assets:read`.
+ * The part of a listed asset that `getBytes` / `getMany` reuse: its id and
+ * signed URL. Any entry from `list()`, `getUrl()` or an index cover fits.
+ */
+export type ArcheAssetRef = Pick<ArcheLibraryAsset, 'assetId' | 'signedUrl' | 'expiresAt'>;
+/** The bytes of one library asset, from {@link ArcheAssetBytesApi}. */
+export interface ArcheAssetBytes {
+    contentType: ArcheLibraryAsset['contentType'];
+    /** The asset's bytes — e.g. for `AudioContext.decodeAudioData` or a canvas. */
+    bytes: ArrayBuffer;
+    sizeBytes: number;
+}
+/**
+ * Why `useArcheAssetBytes().getBytes` failed. `PERMISSION_DENIED` names the
+ * missing permission: it needs `entities:client_invoke` as well as `assets:read`.
+ */
+export type ArcheAssetErrorCode = 'PERMISSION_DENIED' | 'RATE_LIMIT' | 'ASSETS_UNAVAILABLE_IN_PREVIEW' | 'ASSET_URL_FORBIDDEN' | 'ASSET_URL_EXPIRED' | 'ASSET_TOO_LARGE' | 'ASSET_UNAVAILABLE' | 'INVALID_INPUT';
+/**
+ * Asset library API. Permission: `assets:read`. To read an asset's bytes
+ * (Web Audio, canvas) use {@link ArcheAssetBytesApi} via `useArcheAssetBytes()`.
  *
- * The library is a contributor-curated set of images pinned to this
+ * The library is a contributor-curated set of images and short sound
+ * effects pinned to this
  * arche's published version — once the contributor publishes, the set
  * is immutable for that version's runtime. New uploads on the
  * contributor's side affect future published versions only.
  */
 export interface ArcheAssetsApi {
-    /** Page through the published asset manifest. */
-    list: (options?: ArcheAssetsListOptions) => Promise<ArcheAssetsListResult>;
+    /**
+     * Page through the published asset manifest. Images only unless you pass
+     * `kinds`; with `kinds` the entries are typed {@link ArcheLibraryAsset}, so
+     * narrow on `contentType` before using an image's dimensions.
+     */
+    list: {
+        (options: ArcheAssetsListOptions & {
+            kinds: ArcheAssetKind[];
+        }): Promise<ArcheAssetsListResult<ArcheLibraryAsset>>;
+        (options?: ArcheAssetsListOptions & {
+            kinds?: undefined;
+        }): Promise<ArcheAssetsListResult<ArcheAsset>>;
+        (options?: ArcheAssetsListOptions): Promise<ArcheAssetsListResult<ArcheLibraryAsset>>;
+    };
     /**
      * Faceted folder index: one signed cover + count per group (default
      * `subject:`). Renders a large library's folder grid in a single call; load
      * a folder's contents lazily with `list({ tags: ['subject:<id>'] })`.
      */
     index: (options?: ArcheAssetsIndexOptions) => Promise<ArcheAssetsIndexResult>;
-    /** Refresh the signed URL for a single asset. */
-    getUrl: (assetId: string) => Promise<ArcheAsset>;
+    /**
+     * Refresh the signed URL for a single asset. Typed as an image, which is
+     * all an images-only listing hands you; for an id that may be a sound
+     * (you listed with `kinds`), call `getUrl<ArcheLibraryAsset>(id)`.
+     */
+    getUrl: <T extends ArcheLibraryAsset = ArcheAsset>(assetId: string) => Promise<T>;
+}
+/**
+ * Asset-library byte reads (`useArcheAssetBytes()`). Permissions:
+ * `entities:client_invoke` AND `assets:read`.
+ */
+export interface ArcheAssetBytesApi {
+    /**
+     * Read one asset's bytes — for Web Audio (`decodeAudioData`), canvas, or
+     * anything else a URL cannot do (the plugin sandbox cannot fetch). Read
+     * each sound once per session and keep the decoded buffer. Rejects with
+     * an `ArcheAssetError`. Unavailable in the builder preview.
+     *
+     * Pass an entry straight from `list()` / `getUrl()` to reuse its signed
+     * URL — one round trip instead of two. An `assetId`, or an entry whose URL
+     * is about to expire, is first given a fresh URL. Calls made together (in
+     * the same tick, e.g. `Promise.all(entries.map(getBytes))`) are sent as one
+     * batch; to load many sounds, prefer {@link ArcheAssetBytesApi.getMany}.
+     */
+    getBytes: (asset: string | ArcheAssetRef) => Promise<ArcheAssetBytes>;
+    /**
+     * Read many assets in as few calls as possible — the way to load a game's
+     * sound effects at startup. Pass entries straight from `list()` (their URLs
+     * last about five minutes): up to 100 go in each call, so any number of
+     * sounds takes one or two calls instead of one per sound — the bridge
+     * blocks more than 50 calls in 5 seconds.
+     *
+     * Resolves to a map from `assetId` to that asset's bytes, or to the
+     * `ArcheAssetError` that kept it from loading — one failed sound does not
+     * fail the rest. Rejects with an `ArcheAssetError` only when the read as a
+     * whole is refused (a missing permission, the builder preview, the rate
+     * limit). An entry whose URL has lapsed is given a fresh one, up to 10 per
+     * call; past that it comes back `ASSET_URL_EXPIRED` — list again.
+     */
+    getMany: (assets: ArcheAssetRef[]) => Promise<Record<string, ArcheAssetBytes | (Error & {
+        code: ArcheAssetErrorCode;
+    })>>;
 }
 /**
  * Why a content read failed. The first seven come from the host's content
@@ -1518,6 +1660,80 @@ export interface FiasContentApi {
      */
     getUrl(path: string): Promise<FiasContentUrl>;
 }
+/**
+ * Why a local-store call failed. The first four come from the host's store;
+ * `LOCAL_STORE_WRONG_KIND` from the typed getters (`getBytes` on a text
+ * entry); `PERMISSION_DENIED` (the manifest lacks `storage:local`) and
+ * `RATE_LIMIT` from the bridge.
+ */
+export type FiasLocalStoreErrorCode = 'LOCAL_STORE_UNAVAILABLE' | 'LOCAL_STORE_KEY_INVALID' | 'LOCAL_STORE_VALUE_TOO_LARGE' | 'LOCAL_STORE_QUOTA_EXCEEDED' | 'LOCAL_STORE_WRONG_KIND' | 'INVALID_INPUT' | 'PERMISSION_DENIED' | 'RATE_LIMIT';
+/** What `put` accepts: text, bytes, or any JSON-serializable value. */
+export type FiasLocalStoreValue = string | ArrayBuffer | Uint8Array | FiasLocalStoreJson;
+export type FiasLocalStoreJson = null | boolean | number | string | FiasLocalStoreJson[] | {
+    [key: string]: FiasLocalStoreJson;
+};
+/** One entry's metadata, as `list` returns it. */
+export interface FiasLocalStoreEntryMeta {
+    key: string;
+    sizeBytes: number;
+    /** ISO-8601, the last `put`. */
+    updatedAt: string;
+}
+/** One entry with its value — a string, an `ArrayBuffer` for bytes, or JSON, as it was put. */
+export interface FiasLocalStoreEntry extends FiasLocalStoreEntryMeta {
+    value: string | ArrayBuffer | FiasLocalStoreJson;
+}
+/** How much of this plugin's budget (for this user, in this workspace) is in use. */
+export interface FiasLocalStoreEstimate {
+    usedBytes: number;
+    budgetBytes: number;
+}
+export interface FiasLocalStoreApi {
+    /** The entry, or null. The value comes back as the kind it was put. */
+    get(key: string): Promise<FiasLocalStoreEntry | null>;
+    /**
+     * Up to 100 entries in one call, in the order asked, null for a missing
+     * key — restore a journal without a call per key. Throws
+     * `LOCAL_STORE_VALUE_TOO_LARGE` when the entries hold more than 64 MB
+     * together (read fewer at a time) and `INVALID_INPUT` for an empty or
+     * over-long key list.
+     */
+    getMany(keys: string[]): Promise<Array<FiasLocalStoreEntry | null>>;
+    /** A text entry, or null. Throws `LOCAL_STORE_WRONG_KIND` if the entry holds bytes or JSON. */
+    getText(key: string): Promise<string | null>;
+    /** A bytes entry, or null. Throws `LOCAL_STORE_WRONG_KIND` if the entry holds text or JSON. */
+    getBytes(key: string): Promise<ArrayBuffer | null>;
+    /**
+     * A JSON entry, or null. A text entry is parsed as JSON (so `put(key,
+     * JSON.stringify(x))` and `put(key, x)` read back the same); throws
+     * `LOCAL_STORE_WRONG_KIND` for bytes. A stored JSON `null` reads as null,
+     * indistinguishable from an absent key — use `get` if that matters.
+     */
+    getJson<T = unknown>(key: string): Promise<T | null>;
+    /**
+     * Store or overwrite. A string, bytes (`ArrayBuffer` / `Uint8Array`), or
+     * plain JSON (no `Date`, `Map`, `Blob` or other typed arrays — those are
+     * refused rather than stored as something else). One value ≤ 64 MB; the
+     * plugin's whole store for this user ≤ 256 MB (or a quarter of the browser's
+     * quota if smaller) and ≤ 10,000 entries; each entry is also charged its key
+     * and a small fixed overhead. Over a limit the call throws instead of
+     * evicting anything. Put a large snapshot as bytes: JSON is validated and
+     * serialized on the host page on every write.
+     */
+    put(key: string, value: FiasLocalStoreValue): Promise<{
+        sizeBytes: number;
+    }>;
+    /** Remove one entry. Idempotent. */
+    delete(key: string): Promise<void>;
+    /** Entries' metadata, optionally under a key prefix, sorted by key. */
+    list(prefix?: string): Promise<FiasLocalStoreEntryMeta[]>;
+    /** Remove every entry of this plugin's store for the signed-in user in the current workspace. */
+    clear(): Promise<{
+        deleted: number;
+    }>;
+    /** Bytes in use and the budget, so you can decide what to keep before a `put` is refused. */
+    estimate(): Promise<FiasLocalStoreEstimate>;
+}
 /** Where an asset sits in the moderation lifecycle, from the author's view. */
 export type CommunityAssetStatus = 
 /** Awaiting a verdict. Nobody else can see it yet. */
@@ -1719,6 +1935,223 @@ export interface CompanyEmailSendResult {
     /** Recipients counted as sent (`accepted` + `unknown`). */
     sent: number;
 }
+/** An outside account the acting workspace lets this app use (ADR-029 §2). */
+export interface FiasConnection {
+    connectionId: string;
+    /** Provider id, e.g. `'x'`, `'linkedin'`. */
+    provider: string;
+    providerDisplayName: string;
+    accountDisplayName: string | null;
+    /** The account's handle, without `@`. */
+    accountHandle: string | null;
+    accountAvatarUrl: string | null;
+    /** `needs_reconnect`: a person has to connect it again before it can be used. */
+    status: 'active' | 'needs_reconnect';
+}
+export type FiasConnectResult = {
+    connectionId: string;
+    provider: string;
+} | {
+    canceled: true;
+};
+export interface FiasConnectionsApi {
+    /** The accounts the workspace the app is open in lets it use. */
+    list: () => Promise<FiasConnection[]>;
+    /**
+     * Ask the person to connect an account at `provider`, or let this app use one
+     * the workspace already connected. The HOST draws the screen and makes every
+     * grant; resolves `{ canceled: true }` when they decline.
+     */
+    connect: (provider: string) => Promise<FiasConnectResult>;
+    /** Give up this app's access to one connection. */
+    release: (connectionId: string) => Promise<void>;
+}
+/** One X post. Images are Vault document ids: this app's own files, or ones shared with it. */
+export interface FiasXPostInput {
+    text: string;
+    /** Images (PNG, JPEG, WebP or GIF, 5 MB each) — at most 4 across the whole publish. */
+    mediaDocumentIds?: string[];
+}
+export interface FiasXPublishParams {
+    connectionId: string;
+    /** One post, or a thread of up to 10. */
+    posts: FiasXPostInput[];
+    /** Reply to this post id. */
+    replyToPostId?: string;
+    /** A poll on a single post with no images. */
+    poll?: {
+        options: string[];
+        durationMinutes: number;
+    };
+}
+export interface FiasXPublishResult {
+    posts: Array<{
+        postId: string;
+        url: string;
+    }>;
+    /** False when X stopped part-way through a thread: `posts` is what went out. */
+    complete: boolean;
+    /** Where a thread stopped (1-based) and X's reason; present only when `complete` is false. */
+    stopped?: {
+        atPost: number;
+        reason: string;
+    };
+}
+export interface FiasXUser {
+    id: string;
+    name: string;
+    username: string;
+    profileImageUrl?: string;
+    description?: string;
+    verified: boolean;
+    verifiedType: 'blue' | 'government' | 'business' | 'none';
+    followersCount: number;
+}
+export interface FiasXPost {
+    postId: string;
+    text: string;
+    createdAt: string | null;
+    mediaUrl: string | null;
+    likes: number | null;
+    replies: number | null;
+    reposts: number | null;
+    views: number | null;
+}
+export interface FiasXPostMetrics {
+    postId: string;
+    likes: number;
+    replies: number;
+    reposts: number;
+    views: number;
+}
+export interface FiasXAccountStats {
+    followers: number;
+    following: number;
+    posts: number;
+    listed: number;
+}
+/**
+ * X, as an account the workspace let this app use. Every call names the
+ * connection (from `useFiasConnections`) and is charged to the user per X
+ * request. `publishPost` shows the person a confirm sheet first — the text,
+ * every image and the cost — and resolves only once they approve; a decline
+ * rejects with `USER_DECLINED`, and a host already showing another sheet with
+ * `SHEET_BUSY`. The approval covers the images' exact bytes: an image file
+ * changed after asking rejects with `MEDIA_CHANGED` and nothing is posted.
+ */
+export interface FiasXApi {
+    publishPost: (params: FiasXPublishParams) => Promise<FiasXPublishResult>;
+    searchUsers: (connectionId: string, query: string, options?: {
+        maxResults?: number;
+    }) => Promise<FiasXUser[]>;
+    /**
+     * Recent posts by `userId`, or by the connected account when omitted.
+     * `sinceId`: only posts newer than that one — re-reading an account pays
+     * only for its new posts, since each post returned is billed.
+     */
+    getUserPosts: (connectionId: string, options?: {
+        userId?: string;
+        maxResults?: number;
+        sinceId?: string;
+    }) => Promise<FiasXPost[]>;
+    getPostMetrics: (connectionId: string, postIds: string[]) => Promise<FiasXPostMetrics[]>;
+    getAccountStats: (connectionId: string) => Promise<FiasXAccountStats>;
+}
+export interface FiasLinkedInPublishParams {
+    connectionId: string;
+    /** Up to 3,000 characters. */
+    text: string;
+    /** Up to 9 images (PNG, JPEG or GIF, 8 MB each): this app's files or ones shared with it. */
+    mediaDocumentIds?: string[];
+    /** A link LinkedIn previews (when there are no images). */
+    link?: string;
+    /** Organizations to mention; each `name` must appear in `text`. */
+    mentions?: Array<{
+        name: string;
+        urn: string;
+    }>;
+    visibility?: 'PUBLIC' | 'CONNECTIONS' | 'LOGGED_IN';
+}
+export interface FiasLinkedInOrganization {
+    id: string;
+    name: string;
+    /** `urn:li:organization:<id>` — what a mention names. */
+    urn: string;
+}
+/**
+ * LinkedIn, as a member account the workspace let this app use. Every call
+ * names the connection and is charged to the user. `publishPost` shows the
+ * person a confirm sheet first; a decline rejects with `USER_DECLINED`.
+ */
+export interface FiasLinkedInApi {
+    publishPost: (params: FiasLinkedInPublishParams) => Promise<{
+        postUrn: string;
+        url: string | null;
+    }>;
+    searchOrganizations: (connectionId: string, vanityName: string) => Promise<FiasLinkedInOrganization[]>;
+}
+/** One call to schedule for later (ADR-029 §5). */
+export interface FiasScheduleParams {
+    /** The entity, e.g. `X_ENTITY_ID`. */
+    entityId: string;
+    /** A verb that can be scheduled, e.g. `'publish_post'`. */
+    verb: string;
+    /** Exactly what the verb takes now (without `op`) — e.g. `{ connectionId, posts }`. */
+    payload: Record<string, unknown>;
+    /** When to send it: 5 minutes to 60 days from now. */
+    fireAt: Date | string;
+}
+export interface FiasSchedule {
+    scheduleId: string;
+    entityId: string;
+    verb: string;
+    /** What it does, in the platform's words ("Post to X"). */
+    summary: string;
+    fireAt: string | null;
+    /**
+     * `refused`: something changed before it was due (the account was
+     * disconnected, the app lost access, the approved time passed while it was
+     * paused, …) and nothing was sent — see `refusal`. `partial`: a thread the
+     * provider stopped part-way; some of it went out. `paused`: the person paused
+     * it in Fias.
+     */
+    status: 'scheduled' | 'paused' | 'sent' | 'partial' | 'refused' | 'failed' | 'cancelled';
+    refusal?: {
+        code: string;
+        message: string;
+    };
+    /**
+     * Once `sent` or `partial`: what the call returned — the same output an
+     * immediate call gives (for X `publish_post`, `{ posts: [{ postId, url }], complete }`),
+     * so the app can record where it went. Absent before then, or if too large to relay.
+     */
+    output?: Record<string, unknown>;
+}
+export interface FiasScheduleListOptions {
+    /** How many to return, 1–100. Default 20, or the number of `scheduleIds`. */
+    limit?: number;
+    /** Only these schedules (1–100 ids from `schedule()`); ids that are not this app's are left out. */
+    scheduleIds?: string[];
+}
+/**
+ * Schedule ONE call for later. For an action outside Fias the person approves
+ * exactly what will be sent, and when, in a confirm sheet first; a decline
+ * rejects with `USER_DECLINED`. There is no edit: cancel, and schedule again.
+ */
+export interface FiasSchedulesApi {
+    schedule: (params: FiasScheduleParams) => Promise<{
+        scheduleId: string;
+        fireAt: string;
+    }>;
+    /**
+     * This app's schedules in the workspace it is open in, newest first: the
+     * newest 20 unless `limit` says otherwise (at most 100). Pass `scheduleIds`
+     * to follow just the schedules you are waiting on.
+     */
+    list: (options?: FiasScheduleListOptions) => Promise<FiasSchedule[]>;
+    /** Cancel one before it is sent. */
+    cancel: (scheduleId: string) => Promise<void>;
+}
 export interface CompanyEmailApi {
     /**
      * Send one email AS the Company this app is being used in, from its verified
@@ -1899,6 +2332,23 @@ export interface FiasTextModel {
         outputCreditsPerMillionTokens: number;
     } | null;
 }
+/**
+ * The Fias workspace the plugin was opened in — the user's own (`personal`) or
+ * an organization's (`org`) — and the user's role there. Fixed for as long as
+ * the plugin is open: when the user switches workspace, the host offers to
+ * reopen the plugin there, and the reopened plugin receives the new value.
+ *
+ * It carries no id and no name, and grants nothing; the platform applies the
+ * workspace to every call on its own. An org workspace that has approved the
+ * app gives it a shared space (`useFiasWorkspaces().openForWorkspace()`), named
+ * after the workspace — that space's id is the plugin's key for per-workspace
+ * data.
+ */
+export interface FiasHolder {
+    type: 'personal' | 'org';
+    /** The user's role in it. Always `owner` for a personal workspace. */
+    role: 'owner' | 'admin' | 'member' | 'viewer';
+}
 export interface BridgeInitMessage {
     type: 'init';
     messageId: string;
@@ -1921,6 +2371,12 @@ export interface BridgeInitMessage {
          * backwards compat with older hosts.
          */
         textModels?: FiasTextModel[] | null;
+        /**
+         * The workspace the plugin was opened in — present only when the plugin
+         * declared `user:profile:read` or `data:workspace`. `null`/absent when the
+         * host could not resolve it, and from older hosts.
+         */
+        holder?: FiasHolder | null;
         /**
          * Bridge protocol version the HOST speaks. Optional for backwards
          * compat with hosts pre-dating the versioning work — absence is
@@ -2034,6 +2490,14 @@ export interface DataStoreFieldBound {
  *   - `nonNegative` — named numeric fields must be ≥ 0 when present.
  *   - `fieldBounds` — numeric bounds, e.g. `issued lte authorized`.
  *   - `immutableFields` — set-once fields an overwrite must carry unchanged.
+ *   - `references` — a field holds the key of a document that must exist in
+ *     another collection of the same scope (e.g. a security's `stakeholderId`
+ *     → `stakeholders`). Checked at the end of the write (a batch may create
+ *     both together); deleting a referenced document is refused.
+ *   - `ledgerSums` — a counter field may only change by exactly the sum of the
+ *     matching rows appended to an append-only ledger collection in the same
+ *     write (e.g. a security's `quantityOutstanding` by its transactions'
+ *     `quantityDelta`), and ledger rows naming a counter must be matched by it.
  *
  * Violations reject the write with code `CONSTRAINT_VIOLATION`.
  */
@@ -2042,6 +2506,47 @@ export interface DataStoreCollectionConstraints {
     nonNegative?: string[];
     fieldBounds?: DataStoreFieldBound[];
     immutableFields?: string[];
+    references?: DataStoreReference[];
+    ledgerSums?: DataStoreLedgerSum[];
+}
+/**
+ * Counter-follows-ledger: `field` on this collection's documents may only
+ * change by the sum of the matching rows appended to `ledger` (an append-only
+ * collection of the same scope) in the same write. Checked at the end of the
+ * write, so a batch may write the ledger rows and the counter in any order.
+ */
+export interface DataStoreLedgerSum {
+    /** Numeric counter field (absent/null counts as 0). */
+    field: string;
+    /** The append-only ledger collection. */
+    ledger: string;
+    /** Which ledger rows count, and with what sign (1–4 terms). */
+    terms: DataStoreLedgerSumTerm[];
+}
+/** A ledger row counts toward the counter whose key its `key` field holds. */
+export interface DataStoreLedgerSumTerm {
+    /** Ledger-row field naming the counter document's key. */
+    key: string;
+    /** Numeric ledger-row field to add. */
+    amount: string;
+    /** Subtract instead (e.g. the receiving side of a transfer row). */
+    negate?: boolean;
+    /** Only rows whose `field` holds one of these strings count. */
+    when?: {
+        field: string;
+        in: string[];
+    };
+}
+/**
+ * One declared reference: `field` holds the key of a document in
+ * `collection` (same arche, same scope). Skipped when the field is absent or
+ * null; the writer must be able to read the target collection.
+ */
+export interface DataStoreReference {
+    /** Dot-notation path into the document data holding the target key. */
+    field: string;
+    /** Target collection name. */
+    collection: string;
 }
 /**
  * One precondition on an atomic {@link FiasDataStoreApi.batch}: evaluated by
@@ -2345,6 +2850,13 @@ export interface DataStoreWorkspace {
     createdAt: string;
     /** Soft-archive timestamp; null while active. */
     archivedAt: string | null;
+    /**
+     * True for the shared space of a Fias workspace (see
+     * `FiasWorkspacesApi.openForWorkspace`): its members are the Fias
+     * workspace's members, so the member methods refuse with
+     * `HOLDER_BACKED_WORKSPACE`. Absent from older hosts.
+     */
+    holderBacked?: boolean;
 }
 /** A member of a workspace. Members are addressed by username — the platform
  *  userId is internal and never exposed to plugins or users. */
@@ -2374,11 +2886,27 @@ export interface DataStoreWorkspaceMember {
 export interface FiasWorkspacesApi {
     /** Create a workspace; the caller becomes its owner. */
     create: (displayName: string) => Promise<DataStoreWorkspace>;
+    /**
+     * Open the shared space of the Fias org workspace the plugin was opened in
+     * (see `useFiasHolder`), creating it on first use. It exists only once a
+     * workspace owner or admin has approved the app. Its `displayName` is the
+     * workspace's name, and its members are that workspace's members, with their
+     * workspace roles — nobody manages a member list, and someone who leaves the
+     * workspace loses access at once. Every member gets the same space, and it
+     * answers only while the plugin is open in that workspace. Rejects with
+     * `HOLDER_NOT_ELIGIBLE` in a personal workspace, before the workspace has
+     * approved the app, and for a viewer when the space does not exist yet.
+     */
+    openForWorkspace: () => Promise<DataStoreWorkspace>;
     /** List the workspaces the caller is an active member of. */
     list: () => Promise<DataStoreWorkspace[]>;
     /** Get a single workspace (caller must be a member). */
     get: (workspaceId: string) => Promise<DataStoreWorkspace>;
-    /** Archive a workspace (owner only). */
+    /**
+     * Archive a workspace (owner only). Final: an archived workspace cannot be
+     * reopened, and it is deleted with its documents 30 days later — tell your
+     * user before they archive.
+     */
     archive: (workspaceId: string) => Promise<void>;
     /** List a workspace's members (any member). */
     listMembers: (workspaceId: string) => Promise<DataStoreWorkspaceMember[]>;