@fias/arche-sdk 2.28.0 → 2.30.0

package/dist/types.d.ts

@@ -595,6 +595,32 @@ export interface ImageGenerationParams {
      * `referenceImage` is provided.
      */
     referenceStrength?: number;
+    /**
+     * Generate in a style from the user's Creative Library (ADR-035) — a style
+     * made in FiasWorks Studio, say. Needs `vault:creative:read`. The platform
+     * adds the style's reference pictures after your own references (up to
+     * three, while the model has room) and its words to the prompt; with no
+     * room left it carries the style in words, which needs a description
+     * (STYLE_NEEDS_DESCRIPTION otherwise). `version` pins one version of the
+     * style; leave it out for the current one. `pictures` chooses which of the
+     * style's pictures go, in order (1–3 of its `referenceDocumentIds`; an indoor
+     * picture for an indoor scene) — leave it out for its first. Get ids from
+     * `useCreativeLibrary`.
+     *
+     * Or `{ shipped: key }`: a style this arche ships for its players — listed
+     * in the manifest's `styles` with its pictures in the asset library tagged
+     * `style:<key>` (ADR-035 D7). No permission beyond this one. It is read
+     * from the arche's PUBLISHED version — publish once with the style before
+     * relying on it; the dev harness has none (SHIPPED_STYLE_UNAVAILABLE). The
+     * player pays, as for any generation.
+     */
+    creativeStyle?: {
+        styleId: string;
+        version?: number;
+        pictures?: string[];
+    } | {
+        shipped: string;
+    };
 }
 /**
  * A reference image for `useImageGeneration`: an asset from this arche's
@@ -799,6 +825,91 @@ export interface AudioGenerationApi {
     result: AudioGenerationResult | null;
     error: Error | null;
 }
+/**
+ * The host chrome around a plugin's arche, as the host reports it (`init`
+ * and every `chrome_update`). See `useFiasChrome`.
+ *
+ * "Focus mode" is the platform's expand: the platform header, the arche's
+ * own header and the suggested-arches sidebar are hidden so the arche fills
+ * the viewport, and the host draws a thin bar with the way back — Fias home,
+ * Worktop, Fias AI, Collapse — unless the plugin suppresses it and draws its
+ * own.
+ */
+export interface FiasChromeState {
+    /** The arche is expanded (platform header + sidebar hidden). */
+    focusMode: boolean;
+    /**
+     * Whether focus mode exists on this surface at all — only the normal
+     * signed-in layout has chrome to hide. False on public, full-screen and
+     * embedded views, where `setFocusMode` is ignored.
+     */
+    focusModeAvailable: boolean;
+    /**
+     * Whether the layout draws the suggested-arches sidebar for this arche —
+     * false where the manifest declined it (`showSidebar: false`) and on
+     * surfaces that never had one. Hide your sidebar toggle when false.
+     */
+    sidebarAvailable: boolean;
+    /** The sidebar is collapsed (only meaningful when `sidebarAvailable`). */
+    sidebarCollapsed: boolean;
+    /**
+     * In focus mode, the host draws its thin bar (Fias home · Worktop · Fias
+     * AI · Collapse). False when the plugin suppressed it to draw its own.
+     */
+    hostExpandedBar: boolean;
+    /**
+     * The host draws its default expand button over the plugin. False once a
+     * plugin takes the chrome over (mounting `useFiasChrome` does that) or
+     * when the manifest declined it (`showExpandButton: false`). The takeover
+     * also removes the host's re-open control for a collapsed sidebar — a
+     * plugin that owns its chrome draws its own (`setSidebarCollapsed(false)`).
+     */
+    hostExpandButton: boolean;
+}
+/** What `chrome_set` may carry — every present key a boolean. */
+export interface FiasChromeSetPayload {
+    focusMode?: boolean;
+    sidebarCollapsed?: boolean;
+    hostExpandedBar?: boolean;
+    hostExpandButton?: boolean;
+}
+/** The host destinations a plugin may leave for — a closed enum, never a URL. */
+export type FiasChromeNavigateTarget = 'home' | 'worktop';
+/**
+ * Host-chrome API available via useFiasChrome() — the state above plus the
+ * controls the platform's own focus-mode bar carries, so a plugin can place
+ * them where its design wants them.
+ */
+export interface FiasChromeApi extends FiasChromeState {
+    /**
+     * The host delivered chrome state. False before `init` lands and on a host
+     * older than this API — the state fields then hold inert defaults and the
+     * setters are no-ops, so a plugin can render unconditionally.
+     */
+    supported: boolean;
+    /** Expand (`true`) or collapse (`false`) — the platform's own expand/contract. */
+    setFocusMode: (on: boolean) => void;
+    /** Collapse or reopen the suggested-arches sidebar (when `sidebarAvailable`). */
+    setSidebarCollapsed: (collapsed: boolean) => void;
+    /**
+     * Keep (`true`, the default) or suppress (`false`) the host's focus-mode
+     * bar. Suppress it ONLY if you draw your own way back — once the chrome is
+     * hidden that bar is the only one. Focus mode you set persists across
+     * reloads only while the bar is kept; with it suppressed a reload restores
+     * the chrome, so a broken collapse control of yours is never a trap.
+     */
+    setHostExpandedBar: (shown: boolean) => void;
+    /** Leave the arche for Fias home (`/`). */
+    goToFiasHome: () => void;
+    /** Leave the arche for the user's Worktop. */
+    goToWorktop: () => void;
+    /**
+     * Ask the host to open the Fias AI panel. No permission needed; no text can
+     * be passed (the assistant's input belongs to the user); the host debounces
+     * and honours the user's last dismissal — never call it on mount or in a loop.
+     */
+    openAssistant: () => void;
+}
 /**
  * Navigation API available via useFiasNavigation() hook.
  */
@@ -1195,12 +1306,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
@@ -1241,6 +1366,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
@@ -1332,6 +1466,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>;
@@ -1911,6 +2046,310 @@ 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>;
+}
+export type FiasCreativeItemKind = 'style' | 'character';
+/** A style or character, as the Creative Library returns it. */
+export interface FiasCreativeItem {
+    itemId: string;
+    kind: FiasCreativeItemKind;
+    name: string;
+    /** The version shown — the current one unless you asked for another. */
+    version: number;
+    currentVersion: number;
+    /** A style's description, or a character's appearance. */
+    words: string;
+    /** Vault document ids of the reference pictures, best first. */
+    referenceDocumentIds: string[];
+    /** A character's style: a library style id or a built-in style key. Null for a style. */
+    styleRef: string | null;
+    /** YOUR arche's own fields on this item; other arches' are never shown. */
+    extension: Record<string, unknown> | null;
+    /** The arche that created it, when one did. */
+    sourceArcheId: string | null;
+    createdAt: string;
+    updatedAt: string;
+    deletedAt: string | null;
+    /** `get` only: short-lived (5 minute) inline preview URLs of the reference pictures. */
+    previews?: Array<{
+        documentId: string;
+        url: string;
+        expiresAt: string;
+    }>;
+}
+export interface FiasCreativeItemFields {
+    name?: string;
+    words?: string;
+    /** Images THIS arche created (e.g. with `useVaultDocuments().upload`), in the same library. */
+    referenceDocumentIds?: string[];
+    styleRef?: string | null;
+    /** Your arche's own fields; `null` removes them on update. At most 16 KB. */
+    extension?: Record<string, unknown> | null;
+}
+export interface FiasCreativeLibraryApi {
+    /**
+     * Styles and characters, most recently changed first — the whole library
+     * (it holds at most 500); with `includeDeleted`, the 500 most recently changed.
+     */
+    list: (options?: {
+        kind?: FiasCreativeItemKind;
+        includeDeleted?: boolean;
+    }) => Promise<FiasCreativeItem[]>;
+    /** One item, with preview URLs; pass `version` for an earlier version. */
+    get: (itemId: string, version?: number) => Promise<FiasCreativeItem>;
+    /** Needs `vault:creative:write`. A style has 1–12 pictures; a character exactly one. */
+    create: (fields: FiasCreativeItemFields & {
+        kind: FiasCreativeItemKind;
+        name: string;
+    }) => Promise<FiasCreativeItem>;
+    /**
+     * Writes the next version; fields left out carry forward. Pass
+     * `expectedVersion` to fail with CREATIVE_VERSION_CONFLICT if someone else
+     * changed it first.
+     */
+    update: (itemId: string, fields: FiasCreativeItemFields & {
+        expectedVersion?: number;
+    }) => Promise<FiasCreativeItem>;
+    /** To the trash (versions kept); `restore` brings it back. */
+    remove: (itemId: string) => Promise<FiasCreativeItem>;
+    restore: (itemId: string) => Promise<FiasCreativeItem>;
+    /**
+     * Let the person pick one style or character in a sheet Fias draws, with
+     * its pictures — what `list` would return, nothing more. Resolves with the
+     * item picked, or `{ canceled: true }` when they close the sheet. Rejects
+     * with `PICKER_UNAVAILABLE` where there is no picker (the dev harness, the
+     * builder preview) and `SHEET_BUSY` while another Fias sheet is open.
+     */
+    pick: (options?: {
+        kind?: FiasCreativeItemKind;
+    }) => Promise<FiasCreativePickResult>;
+}
+/** What `useCreativeLibrary().pick()` resolves with. */
+export type FiasCreativePickResult = {
+    item: {
+        itemId: string;
+        kind: FiasCreativeItemKind;
+        name: string;
+        version: number;
+    };
+} | {
+    canceled: true;
+};
+/** 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
@@ -1923,7 +2362,7 @@ export interface CompanyEmailApi {
 /**
  * Message types sent from the plugin iframe to the parent frame.
  */
-export type PluginToHostMessageType = 'ready' | 'resize' | 'toast' | 'get_user' | 'get_theme' | 'storage_read' | 'storage_write' | 'storage_list' | 'storage_delete' | 'entity_invoke' | 'client_entity_invoke' | 'image_generate' | 'entities_list_image' | 'audio_generate' | 'surface_invoke' | 'navigate' | 'open_arche' | 'data_create_collection' | 'data_list_collections' | 'data_delete_collection' | 'data_put' | 'data_get' | 'data_query' | 'data_delete' | 'data_batch' | 'data_search' | 'workspace_create' | 'workspace_list' | 'workspace_get' | 'workspace_archive' | 'workspace_list_members' | 'workspace_add_member' | 'workspace_update_member' | 'workspace_remove_member' | 'store_get_products' | 'store_purchase' | 'store_get_entitlements' | 'store_get_purchase_history' | 'store_restore' | 'store_cancel_subscription' | 'vault_documents_list' | 'vault_documents_read' | 'vault_documents_read_many' | 'vault_documents_download_url' | 'vault_documents_get_urls' | 'vault_documents_search' | 'vault_documents_write' | 'vault_documents_update' | 'vault_documents_delete' | 'vault_documents_attach' | 'vault_documents_detach' | 'vault_documents_upload_init' | 'vault_documents_upload_finalize' | 'vault_documents_upload' | 'vault_documents_pick' | 'arche_assets_list' | 'arche_assets_index' | 'arche_assets_get_url' | 'preview_state' | 'subscription_unsubscribe' | 'ai_actions_declare' | 'ai_state' | 'ai_action_result' | 'ai_open';
+export type PluginToHostMessageType = 'ready' | 'resize' | 'toast' | 'get_user' | 'get_theme' | 'storage_read' | 'storage_write' | 'storage_list' | 'storage_delete' | 'entity_invoke' | 'client_entity_invoke' | 'image_generate' | 'entities_list_image' | 'audio_generate' | 'surface_invoke' | 'navigate' | 'open_arche' | 'data_create_collection' | 'data_list_collections' | 'data_delete_collection' | 'data_put' | 'data_get' | 'data_query' | 'data_delete' | 'data_batch' | 'data_search' | 'workspace_create' | 'workspace_list' | 'workspace_get' | 'workspace_archive' | 'workspace_list_members' | 'workspace_add_member' | 'workspace_update_member' | 'workspace_remove_member' | 'store_get_products' | 'store_purchase' | 'store_get_entitlements' | 'store_get_purchase_history' | 'store_restore' | 'store_cancel_subscription' | 'vault_documents_list' | 'vault_documents_read' | 'vault_documents_read_many' | 'vault_documents_download_url' | 'vault_documents_get_urls' | 'vault_documents_search' | 'vault_documents_write' | 'vault_documents_update' | 'vault_documents_delete' | 'vault_documents_attach' | 'vault_documents_detach' | 'vault_documents_upload_init' | 'vault_documents_upload_finalize' | 'vault_documents_upload' | 'vault_documents_pick' | 'arche_assets_list' | 'arche_assets_index' | 'arche_assets_get_url' | 'preview_state' | 'subscription_unsubscribe' | 'ai_actions_declare' | 'ai_state' | 'ai_action_result' | 'ai_open' | 'chrome_set' | 'chrome_navigate';
 /**
  * One Fias AI action a plugin declares — what the platform assistant may do
  * in this plugin's UI while it is open. Mirrors the platform's
@@ -1963,18 +2402,33 @@ export interface FiasAIActionsDeclaration {
 /**
  * Why a realtime subscription ended (ADR-012 Phase M4). Closed union so
  * hooks can distinguish terminal endings (`authorization_revoked`,
- * `collection_deleted`) from ones worth resubscribing after conditions
- * change (`limit`, `transport_error`, `lease_expired`).
+ * `collection_deleted` — the observed resource is gone, whatever its kind)
+ * from ones worth resubscribing after conditions change (`limit`,
+ * `transport_error`, `lease_expired`).
  */
 export type SubscriptionEndedReason = 'authorization_revoked' | 'lease_expired' | 'collection_deleted' | 'limit' | 'transport_error' | 'unsubscribed';
 /**
- * State reported by useDataSubscription().
+ * A realtime invalidation delivered to a subscriber (ADR-012 Phase M4).
+ * Notify-then-refetch: it says only that the observed resource changed.
+ * `resource` is the resource's public identifier as you subscribed to it —
+ * a datastore collection's name, a chat channel's id.
  */
-export interface DataSubscriptionState {
+export interface SubscriptionEvent {
+    resource: string;
+    changed: true;
+    /** @deprecated Alias of `resource`, kept for bundles built before the `resource` rename; removed in the next major. */
+    collection?: string;
+}
+/**
+ * State reported by useEntitySubscription() and useDataSubscription().
+ */
+export interface EntitySubscriptionState {
     status: 'subscribing' | 'active' | 'ended';
     /** Set once status === 'ended'. */
     endedReason?: SubscriptionEndedReason;
 }
+/** State reported by useDataSubscription() — the same shape as every entity subscription. */
+export type DataSubscriptionState = EntitySubscriptionState;
 /**
  * Step navigation API available via useStepNavigation() hook.
  */
@@ -2000,7 +2454,7 @@ export interface StepNavigationOptions {
 /**
  * Message types sent from the parent frame to the plugin iframe.
  */
-export type HostToPluginMessageType = 'init' | 'response' | 'theme_update' | 'navigate_update' | 'step_navigate' | 'stream_token' | 'text_models_update' | 'preview_state_capture' | 'preview_state_restore' | 'subscription_event' | 'subscription_ended' | 'ai_action_dispatch' | 'arche_handoff';
+export type HostToPluginMessageType = 'init' | 'response' | 'theme_update' | 'access_update' | 'navigate_update' | 'chrome_update' | 'step_navigate' | 'stream_token' | 'text_models_update' | 'preview_state_capture' | 'preview_state_restore' | 'subscription_event' | 'subscription_ended' | 'ai_action_dispatch' | 'arche_handoff';
 /**
  * Base message structure for all bridge communication.
  */
@@ -2091,6 +2545,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;
@@ -2100,6 +2571,12 @@ export interface BridgeInitMessage {
         theme: FiasTheme;
         /** Plugin-relative path — see `FiasNavigationApi.currentPath`. */
         currentPath: string;
+        /**
+         * The host-chrome state for this arche — see `FiasChromeState`. Absent
+         * from hosts older than `useFiasChrome` (the hook then reports
+         * `supported: false`), and null on a surface with no chrome of its own.
+         */
+        chrome?: FiasChromeState | null;
         /**
          * Self-hosted vendored-library asset URLs (keyed by import specifier) —
          * present only when the plugin declared `sandbox:vendored-libraries` and the
@@ -2113,6 +2590,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
@@ -2168,6 +2651,20 @@ export interface DataStoreCollection {
      * plugin can VERIFY its declared constraints took effect.
      */
     constraints?: DataStoreCollectionConstraints | null;
+    /**
+     * The app-role permissions that protect this collection (workspace scope,
+     * apps that declare `access` in fias-plugin.json); null = none. Set once,
+     * from the manifest only. Returned so a plugin can VERIFY its declaration
+     * took effect — absent from older platforms.
+     */
+    readPermission?: string | null;
+    writePermission?: string | null;
+    /**
+     * The audiences (manifest `access.audiences`) this collection's documents
+     * may be placed in (ADR-034); null = none. Set with the permissions, then
+     * only grows. Absent from older platforms.
+     */
+    audiences?: string[] | null;
     /**
      * Which plugin project created this collection, as the dev harness reported
      * it. Display metadata only — never a scope or an authorization input.
@@ -2337,9 +2834,15 @@ export interface DataStoreBatchOptions {
  * read-back. Absent on platforms without conditional-write support.
  */
 export interface DataStoreBatchResult {
+    /**
+     * Each put's key — the server-generated one for a put without a key, in a
+     * collection with audiences — its version, and the audience it sits in
+     * (where it has one).
+     */
     written?: {
         key: string;
         version?: number;
+        audience?: string;
     }[];
 }
 /**
@@ -2350,6 +2853,14 @@ export interface DataStoreBatchResult {
  */
 export interface DataStorePutResult {
     version?: number;
+    /**
+     * The document's key — the one the server generated for a create in a
+     * collection with audiences (see {@link FiasDataStoreApi.create}). Absent
+     * from hosts that predate audiences.
+     */
+    key?: string;
+    /** The audience the document sits in, in a collection with audiences. */
+    audience?: string;
 }
 /**
  * A document returned from the data store.
@@ -2375,6 +2886,12 @@ export interface DataStoreDocument<T = Record<string, unknown>> {
      * absent otherwise.
      */
     authoredByCollaborator?: boolean;
+    /**
+     * The audience the document is placed in, in a collection with audiences
+     * (ADR-034): who may read it is decided by the platform from the
+     * audience's readers, never by your code. Absent elsewhere.
+     */
+    audience?: string;
 }
 /**
  * Filter condition for querying documents.
@@ -2463,6 +2980,8 @@ export interface DataStoreSearchMatch<T = Record<string, unknown>> {
     version?: number;
     /** Present on shared-scope matches: see {@link DataStoreDocument.authoredByCollaborator}. */
     authoredByCollaborator?: boolean;
+    /** The match's audience, in a collection with audiences — see {@link DataStoreDocument.audience}. */
+    audience?: string;
 }
 /**
  * Data Store API available via useFiasDataStore() hook.
@@ -2497,7 +3016,14 @@ export interface FiasDataStoreApi {
     }) => Promise<DataStoreCollection>;
     /** List all collections for this arche. */
     listCollections: () => Promise<DataStoreCollection[]>;
-    /** Delete a collection and all its documents. */
+    /**
+     * Delete a collection and all its documents. Only an arche collaborator
+     * (owner or publisher) may; anyone else gets `FORBIDDEN`. On a published app
+     * it works only while the collection is EMPTY: one that still holds
+     * documents (every user's, workspace's and tenant's) is refused with
+     * `COLLECTION_NOT_EMPTY`. Sandbox tenants (fias-dev, builder preview, test
+     * channel) can delete any.
+     */
     deleteCollection: (name: string) => Promise<void>;
     /**
      * Write (upsert) a document by key. For a `workspace`-scoped collection pass
@@ -2507,7 +3033,30 @@ export interface FiasDataStoreApi {
      * Resolves with the document's post-write `version` (ADR-014) so a follow-up
      * conditional batch can assert it without a read-back.
      */
-    put: <T extends Record<string, unknown> = Record<string, unknown>>(collection: string, key: string, data: T, options?: DataStoreScopeOptions) => Promise<DataStorePutResult>;
+    put: <T extends Record<string, unknown> = Record<string, unknown>>(collection: string, 
+    /**
+     * The document to write. In a collection with audiences keys are made by
+     * the server: pass `null` to create one (or use {@link create}); a key
+     * names an existing document you may change, and anything else —
+     * missing, or in an audience you cannot read — is refused alike
+     * (`DOCUMENT_NOT_FOUND`). Passing `{ audience }` with a key MOVES the
+     * document to that audience.
+     */
+    key: string | null, data: T, options?: DataStoreScopeOptions) => Promise<DataStorePutResult>;
+    /**
+     * Create a document in a collection with audiences (ADR-034): the server
+     * makes its key and places it in `options.audience`, which you must name.
+     * Placing needs the audience's `disclosedBy` permission — not its read
+     * permission, so a person can file something they will not see afterwards.
+     * Resolves with the new key. Only in collections with audiences — in one
+     * without, a create is `INVALID_DOCUMENT_KEY` (keys there are yours). A
+     * platform that predates audiences rejects the call as invalid parameters
+     * (`INVALID_PARAMS`); `AUDIENCES_UNAVAILABLE` is only a backstop for a host
+     * that accepted it yet returned no key.
+     */
+    create: <T extends Record<string, unknown> = Record<string, unknown>>(collection: string, data: T, options: DataStoreScopeOptions & {
+        audience: string;
+    }) => Promise<Required<Pick<DataStorePutResult, 'key'>> & DataStorePutResult>;
     /** Get a document by key. Returns null if not found. Pass `{ workspaceId }`
      *  for a workspace-scoped collection. */
     get: <T extends Record<string, unknown> = Record<string, unknown>>(collection: string, key: string, options?: DataStoreScopeOptions) => Promise<T | null>;
@@ -2557,6 +3106,15 @@ export interface FiasDataStoreApi {
 export interface DataStoreScopeOptions {
     /** Target workspace for a `workspace`-scoped collection. */
     workspaceId?: string;
+    /**
+     * An audience of a collection with audiences (ADR-034, the manifest's
+     * `access.audiences`): where `put`/`create` places the document, or the one
+     * audience `get`/`query`/`search` look in (by default they read every
+     * audience the user reads). Ignored by `delete`. Naming one before the
+     * workspace has turned the app's roles on is refused
+     * (`ACCESS_SETUP_REQUIRED`).
+     */
+    audience?: string;
 }
 /**
  * One write in an atomic batch (see {@link FiasDataStoreApi.batch}). A `put`
@@ -2566,9 +3124,12 @@ export interface DataStoreScopeOptions {
 export type DataStoreBatchOp = {
     op: 'put';
     collection: string;
-    key: string;
+    /** Omit to create with a server-generated key (collections with audiences). */
+    key?: string;
     data: Record<string, unknown>;
     workspaceId?: string;
+    /** Where to place (or move) the document — see {@link DataStoreScopeOptions.audience}. */
+    audience?: string;
 } | {
     op: 'delete';
     collection: string;
@@ -2586,6 +3147,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. */
@@ -2615,11 +3183,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[]>;
@@ -2632,6 +3216,132 @@ export interface FiasWorkspacesApi {
     /** Remove a member by username (owner/admin, or yourself; keeps the one-owner invariant). */
     removeMember: (workspaceId: string, username: string) => Promise<void>;
 }
+/**
+ * The current user's access in one workspace where only workspace TIERS
+ * (owner/admin/member/viewer) apply: an app that declares no roles, or a
+ * workspace outside an organization, where roles never apply.
+ */
+export interface FiasTierAccess {
+    mode: 'tier';
+    workspaceId: string;
+    /**
+     * The user's tier in this workspace, or `null` when they have none: not a
+     * member, an expired or removed membership, or a workspace this app cannot
+     * see from where it is open.
+     */
+    tier: WorkspaceRole | null;
+    /** ISO-8601 expiry of the user's membership, or `null` when it does not expire. */
+    expiresAt: string | null;
+}
+/**
+ * An app that declares roles (manifest `access`), in an org workspace that has
+ * not turned them on: it runs on TIERS until an owner activates roles. Collections that existed before the app declared roles work
+ * as before; one created already protected is refused with
+ * `ACCESS_SETUP_REQUIRED`.
+ */
+export interface FiasLegacyAccess {
+    mode: 'legacy';
+    workspaceId: string;
+    tier: WorkspaceRole;
+    /** ISO-8601 expiry of the user's membership, or `null` when it does not expire. */
+    expiresAt: string | null;
+}
+/** One app role the user holds that counts now. */
+export interface FiasAccessRole {
+    /** The role id your manifest declares. */
+    id: string;
+    /** ISO-8601 expiry of this assignment, or `null` when it does not expire. */
+    expiresAt: string | null;
+}
+/**
+ * An app that declares roles, in an org workspace where they are on: the
+ * user's roles that count at their current tier, and the permissions those
+ * roles grant. A role whose `minTier` the user's tier does not meet is left
+ * out — it grants nothing until they are promoted.
+ */
+export interface FiasRolesAccess {
+    mode: 'roles';
+    workspaceId: string;
+    tier: WorkspaceRole;
+    /** ISO-8601 expiry of the user's membership, or `null` when it does not expire. */
+    expiresAt: string | null;
+    roles: FiasAccessRole[];
+    /** The permission ids the user holds here, sorted. */
+    permissions: string[];
+    /**
+     * The audiences (manifest `access.audiences`) those permissions read, and
+     * the ones they may place documents in. Across the app — a collection lists
+     * which of them it uses, and reading one also needs the collection's own
+     * read permission. Empty while the workspace is still placing its existing
+     * documents. Absent from hosts that predate audiences.
+     */
+    audiences?: {
+        readable: string[];
+        disclosable: string[];
+    };
+}
+/**
+ * The current user's own access in a workspace, from `useFiasAccess()`.
+ *
+ * `mode` says which model answered: `'tier'` for an app without roles (or a
+ * workspace outside an organization, where roles never apply), `'legacy'`
+ * for an app whose roles this workspace has not turned on yet, and
+ * `'roles'` when they are on. Handle a `mode` you do not recognise by hiding
+ * the controls it would gate, never by showing them.
+ *
+ * **A UI hint, never security.** The platform checks every read and write on
+ * arrival; this only lets you hide controls a user could not use anyway.
+ */
+export type FiasAccess = FiasTierAccess | FiasLegacyAccess | FiasRolesAccess;
+/** What `useFiasAccess()` returns. */
+export interface FiasAccessState {
+    /** The user's access, or `null` while loading, on error, or with no workspace given. */
+    access: FiasAccess | null;
+    /**
+     * True until the first answer for this workspace. A later ask (focus,
+     * `access_update`, `refetch()`) keeps the answer it has and does not set it.
+     */
+    isLoading: boolean;
+    /** A failure other than "no access here" (which is `access.tier === null`). */
+    error: Error | null;
+    /**
+     * Whether the user holds `permission` here: true only in `'roles'` mode,
+     * with that permission. Always false in `'tier'` and `'legacy'` mode, where
+     * permissions are not in force — branch on `access.mode` (and the tier)
+     * there.
+     */
+    can: (permission: string) => boolean;
+    /**
+     * Whether the user reads `audience` here — true only in `'roles'` mode. A
+     * UI hint like `can()`: the platform only ever returns documents of the
+     * audiences the user reads. Reading a document also needs its collection's
+     * `readPermission`; this does not check that — `can()` it too.
+     */
+    canReadAudience: (audience: string) => boolean;
+    /** Whether the user may place documents in `audience` here — true only in `'roles'` mode. */
+    canDiscloseTo: (audience: string) => boolean;
+    /**
+     * Ask again. The answer is a snapshot and is NOT pushed when the user's
+     * access changes elsewhere, so call this when it may have: after the app
+     * changes a membership itself, or when the platform refuses an action with
+     * `FORBIDDEN` / `NOT_A_MEMBER`. A refetch of the same workspace keeps the
+     * current answer until the new one arrives.
+     */
+    refetch: () => void;
+    /**
+     * Open Fias's access sheet for the workspace the person is acting in: their
+     * own access to this app's data, why, asking for more, and — for an access
+     * manager — managing roles. Drawn by Fias; the app passes nothing and
+     * changes nothing itself. Resolves once the person closes it (and refetches
+     * when their access changed); rejects with `NOT_IN_WORKSPACE` in a Personal
+     * workspace, where app roles never apply, `SHEET_BUSY` while another Fias
+     * sheet is open, or `ACCESS_UNAVAILABLE` where no Fias host can draw it (the
+     * dev harness). Requires `data:workspace`.
+     */
+    openAccessDialog: () => Promise<{
+        changed: boolean;
+    }>;
+}
 /**
  * IAP product type (mirrors Apple StoreKit).
  */