@fias/arche-sdk 2.29.0 → 2.31.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-037) — 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-037 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,105 @@ 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;
+    /**
+     * Where the person came from, when a Fias tool opened this arche — the forge
+     * page's "Open FiasWorks Studio", say (ADR-037 D8) — or null. `useOpener`
+     * reads it without taking the chrome over. A host older than this field
+     * sends none (read it as null).
+     */
+    opener?: FiasOpener | null;
+}
+/** A Fias tool this arche was opened from (ADR-037 D8). */
+export interface FiasOpener {
+    /** What it is: a Fias Forge, or an arche in the Arche Builder. */
+    kind: 'forge' | 'builder';
+    /** The arche's name as the person knows it ("My Arche"). */
+    name: string;
+}
+/** 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' | 'opener';
+/**
+ * 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.
  */
@@ -1782,8 +1907,10 @@ export interface CommunityAssetUrl {
 }
 export interface CommunityAssetPublishInput {
     /**
-     * The `fileId` from a `useImageGeneration()` result — the image must be one
-     * YOU created or uploaded, in your own Fias files.
+     * The `fileId` of an image the user made IN THIS APP: a `useImageGeneration()`
+     * result, or a picture uploaded through `useVaultDocuments().upload()`. A
+     * file in the user's Documents (even one they granted you) is not
+     * publishable by id — save your own copy with `upload()` first.
      *
      * Required here, while `ImageGenerationResult.fileId` is OPTIONAL (it is
      * absent if the generated image was never written to the user's files). That
@@ -1811,7 +1938,8 @@ export interface CommunityAssetPublishInput {
  * One item's outcome from `publishMany`. Items succeed or fail INDEPENDENTLY —
  * a single rejected page must not sink a whole book — and retrying only the
  * failures is safe: publishing the same bytes twice returns the first result
- * rather than creating a duplicate.
+ * rather than creating a duplicate. An item the user can't pay the safety check
+ * for fails with `INSUFFICIENT_CREDITS`; the ones before it still went through.
  */
 export type CommunityAssetPublishResult = {
     clientRef: string | null;
@@ -1842,8 +1970,14 @@ export type CommunityAssetReportReason = 'sexual' | 'violence' | 'hate' | 'illeg
 export interface CommunityAssetsApi {
     /**
      * Publish one image you created so other users of this arche can see it.
-     * Free. It becomes visible only after moderation — expect
+     * It becomes visible only after moderation — expect
      * `status: 'pending_moderation'` back, not `'published'`.
+     *
+     * The user pays for each picture's safety check (0.6 credits, charged when it
+     * runs; publishing the same bytes again costs nothing). A user who can't pay
+     * for it — and for their pictures still waiting to be checked — is refused
+     * with `INSUFFICIENT_CREDITS` before anything is stored; tell them, rather
+     * than retrying.
      */
     publish: (input: CommunityAssetPublishInput) => Promise<CommunityAsset>;
     /** Publish up to 20 at once; each item succeeds or fails on its own. */
@@ -1966,6 +2100,123 @@ export interface FiasConnectionsApi {
     /** 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–100 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>;
+}
+/**
+ * Where the person came from, and what you can do about it (ADR-037 D8) —
+ * `useOpener()`.
+ */
+export interface FiasOpenerApi {
+    /** The Fias tool that opened this arche, or null — then show neither action. */
+    opener: FiasOpener | null;
+    /** Take the person back to `opener`. Does nothing without one. */
+    returnTo: () => void;
+    /**
+     * Offer one of YOUR files (a Vault file this arche created) to `opener`:
+     * Fias shows the person a sheet naming the file and the destination, and
+     * their Send moves it — into a Fias Forge's `public/`, or an Arche Builder
+     * arche's asset library. `name` is the name it should land as. Requires
+     * `opener:send`. Resolves `{ sent: true, name }` once it arrived (the name
+     * it landed as), or `{ canceled: true }`. Rejects with `NO_OPENER` without
+     * an `opener`, `SHEET_BUSY` while another Fias sheet is open, and
+     * `SEND_UNAVAILABLE` where there is none (the dev harness).
+     */
+    send: (file: {
+        fileId: string;
+        name?: string;
+    }) => Promise<FiasSendToOpenerResult>;
+}
+export type FiasSendToOpenerResult = {
+    sent: true;
+    name: string;
+} | {
+    canceled: true;
+};
+/** 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;
@@ -2164,7 +2415,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
@@ -2204,18 +2455,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.
  */
@@ -2241,7 +2507,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.
  */
@@ -2358,6 +2624,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
@@ -2432,6 +2704,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.
@@ -2601,9 +2887,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;
     }[];
 }
 /**
@@ -2614,6 +2906,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.
@@ -2639,6 +2939,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.
@@ -2727,6 +3033,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.
@@ -2761,7 +3069,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
@@ -2771,7 +3086,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>;
@@ -2821,6 +3159,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`
@@ -2830,9 +3177,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;
@@ -2919,6 +3269,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).
  */