@fias/arche-sdk 2.3.0 → 2.11.0

package/dist/provider.test.js

@@ -24,9 +24,17 @@ const MockProvider = jest.fn(({ children }) => children);
 jest.mock('./context', () => ({
     FiasBridgeContext: { Provider: MockProvider },
 }));
-// Capture React hook calls
-let capturedEffectCleanup = null;
+// Capture React hook calls.
+// UPDATED (Phase 6): the provider now has multiple effects (bridge init +
+// unhandledrejection listener) — collect EVERY cleanup and run them all,
+// instead of keeping only the last one (which silently pointed the old
+// single-cleanup tests at whichever effect happened to run last).
+let capturedEffectCleanups = [];
 const mockSetReady = jest.fn();
+function runAllEffectCleanups() {
+    for (const cleanup of capturedEffectCleanups)
+        cleanup();
+}
 jest.mock('react', () => {
     const actual = jest.requireActual('react');
     return {
@@ -36,7 +44,7 @@ jest.mock('react', () => {
         useEffect: jest.fn((cb) => {
             const cleanup = cb();
             if (typeof cleanup === 'function') {
-                capturedEffectCleanup = cleanup;
+                capturedEffectCleanups.push(cleanup);
             }
         }),
     };
@@ -44,7 +52,7 @@ jest.mock('react', () => {
 describe('FiasProvider', () => {
     beforeEach(() => {
         jest.clearAllMocks();
-        capturedEffectCleanup = null;
+        capturedEffectCleanups = [];
         mockBridge.waitForInit.mockResolvedValue(undefined);
     });
     it('uses getBridge() singleton via useMemo', () => {
@@ -66,8 +74,8 @@ describe('FiasProvider', () => {
     it('does NOT call bridge.destroy() on cleanup (StrictMode safety)', () => {
         const { FiasProvider } = require('./provider');
         FiasProvider({ children: null });
-        expect(capturedEffectCleanup).toBeDefined();
-        capturedEffectCleanup();
+        expect(capturedEffectCleanups.length).toBeGreaterThan(0);
+        runAllEffectCleanups();
         expect(mockBridge.destroy).not.toHaveBeenCalled();
     });
     it('does not call ready if unmounted before init resolves', async () => {
@@ -77,8 +85,8 @@ describe('FiasProvider', () => {
         }));
         const { FiasProvider } = require('./provider');
         FiasProvider({ children: null });
-        // Run cleanup before init resolves (simulates unmount)
-        capturedEffectCleanup();
+        // Run cleanups before init resolves (simulates unmount)
+        runAllEffectCleanups();
         resolveInit();
         await Promise.resolve();
         await Promise.resolve();
@@ -93,4 +101,52 @@ describe('FiasProvider', () => {
         expect(result).toBeNull();
     });
 });
+describe('PluginErrorBoundary', () => {
+    beforeEach(() => {
+        jest.clearAllMocks();
+    });
+    it('getDerivedStateFromError captures the thrown error', () => {
+        const { PluginErrorBoundary } = require('./provider');
+        const err = new Error('Permission denied: user:profile:read not granted');
+        expect(PluginErrorBoundary.getDerivedStateFromError(err)).toEqual({ error: err });
+    });
+    it('renders children when there is no error', () => {
+        const { PluginErrorBoundary } = require('./provider');
+        const boundary = new PluginErrorBoundary({ children: 'the-app' });
+        boundary.state = { error: null, resetCount: 0 };
+        // UPDATED (Phase 6): children are wrapped in a keyed Fragment so a reset
+        // (key bump) remounts the crashed subtree instead of reusing its state.
+        const rendered = boundary.render();
+        expect(rendered.props.children).toBe('the-app');
+        expect(rendered.key).toBe('0');
+    });
+    it('renders the error screen (not children) once an error is captured', () => {
+        const { PluginErrorBoundary, FiasErrorScreen } = require('./provider');
+        const err = new Error('Permission denied: user:profile:read not granted');
+        const boundary = new PluginErrorBoundary({ children: 'the-app' });
+        boundary.state = { error: err, resetCount: 0 };
+        const rendered = boundary.render();
+        expect(rendered.type).toBe(FiasErrorScreen);
+        expect(rendered.props.error).toBe(err);
+        // The error screen gets a reset handler ("Try again").
+        expect(rendered.props.onReset).toBe(boundary.handleReset);
+    });
+    it('componentDidCatch logs instead of failing silently', () => {
+        const { PluginErrorBoundary } = require('./provider');
+        const spy = jest.spyOn(console, 'error').mockImplementation(() => { });
+        const boundary = new PluginErrorBoundary({ children: null });
+        const err = new Error('boom');
+        boundary.componentDidCatch(err, { componentStack: '\n at App' });
+        expect(spy).toHaveBeenCalledWith(expect.stringContaining('[fias-sdk]'), err, expect.any(String));
+        spy.mockRestore();
+    });
+    it('FiasErrorScreen surfaces the error message', () => {
+        const { FiasErrorScreen } = require('./provider');
+        const el = FiasErrorScreen({
+            error: new Error('Permission denied: user:profile:read not granted'),
+        });
+        expect(el.props.role).toBe('alert');
+        expect(JSON.stringify(el)).toContain('user:profile:read');
+    });
+});
 //# sourceMappingURL=provider.test.js.map

package/dist/provider.test.js.map

@@ -1 +1 @@
-{"version":3,"file":"provider.test.js","sourceRoot":"","sources":["../src/provider.test.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"provider.test.js","sourceRoot":"","sources":["../src/provider.test.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -95,6 +95,20 @@ export interface EntityInvocationApi {
      */
     streamingText: string;
 }
+/**
+ * Client-side entity invocation API available via the `useClientEntity()`
+ * hook. The client-side counterpart to {@link EntityInvocationApi}: invokes
+ * an on-device entity (grammar check, background removal, …) by ID through
+ * the bridge's generic `client_entity_invoke` op. Requires the
+ * `entities:client_invoke` permission. The typed result flows back through
+ * the returned promise — supply the entity's input/output types at the call
+ * site, e.g. `invoke<GrammarCheckInput, GrammarCheckResult>(id, input)`.
+ */
+export interface ClientEntityApi {
+    invoke: <TInput = unknown, TResult = unknown>(entityId: string, input: TInput) => Promise<TResult>;
+    isLoading: boolean;
+    error: Error | null;
+}
 /**
  * How a plugin picks a text model for `useEntityInvocation({ entityId, ... })`:
  *
@@ -114,9 +128,27 @@ export type TextCapabilityId = 'text-fast' | 'text-standard' | 'text-advanced';
 export type TextEntitySelector = string | {
     capability: TextCapabilityId;
 };
+/**
+ * An image sent to a vision-capable model alongside `input` (e.g. OCR,
+ * chart/figure understanding, visual Q&A). Base64-encoded bytes plus the MIME
+ * type — no `data:` prefix.
+ */
+export interface EntityInvocationImage {
+    /** MIME type, e.g. `'image/jpeg'`, `'image/png'`, `'image/webp'`, `'image/gif'`. */
+    mediaType: string;
+    /** Base64-encoded image bytes, WITHOUT a `data:<type>;base64,` prefix. */
+    dataBase64: string;
+}
 export interface EntityInvocationParams {
     entityId: TextEntitySelector;
     input: string;
+    /**
+     * Optional image inputs for a vision-capable model. The resolved model must
+     * support vision or the call is rejected. Sent together with `input` as a
+     * single user message. Billed like any other invocation (the 20% markup
+     * applies). Bounded per call — keep images small (downscale before sending).
+     */
+    images?: EntityInvocationImage[];
     parameters?: Record<string, unknown>;
     /** System prompt to send to the AI model. The arche/plugin provides context; the entity provides the capability. */
     systemPrompt?: string;
@@ -311,25 +343,86 @@ export interface ImageGenerationApi {
     error: Error | null;
 }
 /**
- * Result of background removal via the `client_entity_invoke` bridge op
- * targeting the imgly background-removal entity. A transparent PNG.
+ * Parameters for on-device translation via the `client_entity_invoke` bridge
+ * op targeting the NLLB-200 translation entity.
+ */
+export interface TranslateParams {
+    /** Text to translate. */
+    text: string;
+    /**
+     * Target language as a FLORES-200 code (e.g. `'fra_Latn'`). Pick from
+     * `NLLB_LANGUAGES` for a ready-made label/code list.
+     */
+    targetLang: string;
+    /**
+     * Source language as a FLORES-200 code. Omit to auto-detect on-device.
+     * Supplying it skips detection (faster; avoids misdetection on short text).
+     */
+    sourceLang?: string;
+}
+/**
+ * Result of on-device translation. Produced entirely in the host page by a
+ * WASM model — text never leaves the user's device.
+ */
+export interface TranslationResult {
+    /** The translated text. */
+    translation: string;
+    /** The FLORES-200 source code actually used (detected, or the one passed in). */
+    detectedSourceLang: string;
+}
+/**
+ * Issue categories surfaced by the grammar_check client-side entity.
  *
- * The blob is processed entirely in the host page using a WASM/ONNX model —
- * bytes never leave the user's device. Inputs are capped at 25 MiB
- * (26,214,400 bytes); larger inputs reject with an error.
+ * NOTE: duplicated from the executor's type (the SDK is dependency-free and
+ * cannot import from the platform client). Kept in lockstep by review.
  */
-export interface ImageRemoveBackgroundResult {
-    image: Blob;
+export type GrammarCategory = 'spelling' | 'grammar' | 'style' | 'readability';
+/** A single grammar/spelling/style/readability issue. */
+export interface GrammarIssue {
+    /** Inclusive start character offset into the submitted text. */
+    start: number;
+    /** Exclusive end character offset into the submitted text. */
+    end: number;
+    /** Human-readable description of the issue. */
+    message: string;
+    category: GrammarCategory;
+    /** Stable rule identifier, e.g. `retext-spell:colour`. */
+    ruleId: string;
+    /** Suggested replacements (may be empty). */
+    suggestions: string[];
+}
+/** Optional readability summary returned when the readability category is requested. */
+export interface GrammarReadability {
+    /** Number of sentences flagged as hard to read. */
+    hardToReadSentences: number;
+}
+/** Input to the grammar_check client-side entity. */
+export interface GrammarCheckInput {
+    /** The text to check. Capped at 100,000 characters. */
+    text: string;
+    /** Categories to report. Omitted/empty means all categories. */
+    categories?: GrammarCategory[];
+    /** Words the user added to their personal dictionary (never flagged as misspelled). */
+    customDictionary?: string[];
 }
 /**
- * Background removal API available via useBackgroundRemoval() hook.
+ * Result of a grammar check via the `client_entity_invoke` bridge op
+ * targeting the grammar_check entity. The text is checked entirely in the
+ * host page (no AI, no network) — it never leaves the user's device.
  */
-export interface BackgroundRemovalApi {
-    removeBackground: (image: Blob) => Promise<Blob>;
-    isLoading: boolean;
-    /** The Blob returned by the most recent successful call, or null. */
-    result: Blob | null;
-    error: Error | null;
+export interface GrammarCheckResult {
+    issues: GrammarIssue[];
+    readability?: GrammarReadability;
+}
+/**
+ * A selectable language for the NLLB translator: a human label paired with
+ * its FLORES-200 code. See `NLLB_LANGUAGES` for the curated list.
+ */
+export interface NllbLanguageOption {
+    /** Display label, e.g. `'Spanish'`. */
+    label: string;
+    /** FLORES-200 code, e.g. `'spa_Latn'`. */
+    code: string;
 }
 /**
  * Audio sub-type discriminator. v1 ships music only; future entries
@@ -403,6 +496,23 @@ export interface AudioGenerationApi {
  */
 export interface FiasNavigationApi {
     navigateTo: (path: string) => void;
+    /**
+     * Navigate the host to ANOTHER arche's page (`/a/<archeId>`).
+     *
+     * Unlike `navigateTo` (scoped to this arche's own route space), this
+     * crosses arches via the host-mediated `open_arche` bridge op. The host
+     * validates the id format and performs the navigation itself — the iframe
+     * sandbox is never loosened. Requires the `navigation:open_arche`
+     * permission in the manifest.
+     *
+     * @param archeId Target arche id (`arc_<32hex>` or `arche_<slug>`).
+     * @param opts.newTab Best-effort open in a new tab (keeps the current arche
+     *   open). Browsers may block the popup since user activation does not cross
+     *   the iframe→host boundary; the host falls back to same-tab navigation.
+     */
+    openArche: (archeId: string, opts?: {
+        newTab?: boolean;
+    }) => void;
     currentPath: string;
 }
 /**
@@ -719,7 +829,22 @@ export interface ArcheAssetsApi {
 /**
  * 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' | 'data_create_collection' | 'data_list_collections' | 'data_delete_collection' | 'data_put' | 'data_get' | 'data_query' | 'data_delete' | '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' | 'arche_assets_list' | 'arche_assets_index' | 'arche_assets_get_url';
+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';
+/**
+ * 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`).
+ */
+export type SubscriptionEndedReason = 'authorization_revoked' | 'lease_expired' | 'collection_deleted' | 'limit' | 'transport_error' | 'unsubscribed';
+/**
+ * State reported by useDataSubscription().
+ */
+export interface DataSubscriptionState {
+    status: 'subscribing' | 'active' | 'ended';
+    /** Set once status === 'ended'. */
+    endedReason?: SubscriptionEndedReason;
+}
 /**
  * Step navigation API available via useStepNavigation() hook.
  */
@@ -745,7 +870,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';
+export type HostToPluginMessageType = 'init' | 'response' | 'theme_update' | 'navigate_update' | 'step_navigate' | 'stream_token' | 'preview_state_capture' | 'preview_state_restore' | 'subscription_event' | 'subscription_ended';
 /**
  * Base message structure for all bridge communication.
  */
@@ -762,6 +887,13 @@ export interface BridgeResponse<T = unknown> {
     messageId: string;
     payload: T;
     error?: string;
+    /**
+     * Machine-readable failure code accompanying `error` (e.g. a server bridge
+     * code like `BRIDGE_TOKEN_EXPIRED`, or the host's `BRIDGE_ERROR` fallback).
+     * Plain wire field — the SDK constructs a `FiasBridgeError` from
+     * `error` + `errorCode` locally; Errors are never structured-cloned.
+     */
+    errorCode?: string;
 }
 /**
  * Init message sent by the host to the plugin on load.
@@ -771,6 +903,25 @@ export interface BridgeResponse<T = unknown> {
  * include them still works — the SDK then assumes protocol version 1
  * (the first published contract).
  */
+/**
+ * Asset URLs for ONE platform-vendored library (see `useFiasVendoredAssets`) —
+ * a file-key → absolute-URL map whose keys are defined by that library's
+ * registry entry. For `pdfjs-dist`: `mainModule`, `worker`, `cMapUrl`,
+ * `standardFontDataUrl`. All URLs share one pinned, immutable CDN version prefix
+ * so a library's main module and worker are always the same build.
+ */
+export type FiasVendoredLibraryAssets = Record<string, string>;
+/**
+ * Self-hosted vendored-library asset URLs, delivered in the init payload to
+ * plugins that declare the `sandbox:vendored-libraries` permission. Keyed by
+ * import specifier (e.g. `'pdfjs-dist'`). `null`/absent when the host's CDN
+ * isn't configured — the plugin then can't load vendored libraries and should
+ * degrade gracefully.
+ *
+ * The shape mirrors `@fias/platform-resources`' registry output, duplicated here
+ * so the SDK stays dependency-free (it ships inside plugin iframes).
+ */
+export type FiasVendoredAssets = Record<string, FiasVendoredLibraryAssets>;
 export interface BridgeInitMessage {
     type: 'init';
     messageId: string;
@@ -779,6 +930,12 @@ export interface BridgeInitMessage {
         permissions: PluginPermission[];
         theme: FiasTheme;
         currentPath: string;
+        /**
+         * Self-hosted vendored-library asset URLs (keyed by import specifier) —
+         * present only when the plugin declared `sandbox:vendored-libraries` and the
+         * host's CDN is configured. Optional for backwards compat with older hosts.
+         */
+        vendoredAssets?: FiasVendoredAssets | null;
         /**
          * Bridge protocol version the HOST speaks. Optional for backwards
          * compat with hosts pre-dating the versioning work — absence is
@@ -806,6 +963,12 @@ export interface BridgeReadyMessage {
     payload: {
         /** Bridge protocol version this SDK speaks. */
         sdkProtocolVersion: number;
+        /**
+         * Whether this SDK understands the preview state capture/restore protocol
+         * (`preview_state_capture` / `preview_state_restore` / `preview_state`).
+         * The host gates capture/restore on this so older SDKs are unaffected.
+         */
+        supportsPreviewState?: boolean;
     };
 }
 /**
@@ -813,9 +976,36 @@ export interface BridgeReadyMessage {
  */
 export interface DataStoreCollection {
     name: string;
-    userScope: 'user' | 'shared';
+    userScope: 'user' | 'shared' | 'workspace';
+    /** True when documents are embedded for semantic search (`data:search`). */
+    searchable?: boolean;
+    /** Dot-path into `data` that is embedded; present only when `searchable`. */
+    searchField?: string | null;
+    /** Min workspace role to write / read (workspace-scoped only); null = default. */
+    writeMinRole?: WorkspaceRole | null;
+    readMinRole?: WorkspaceRole | null;
+    /** Who may write (shared-scoped only): see {@link DataStoreWritePolicy}. */
+    writePolicy?: DataStoreWritePolicy;
     createdAt: string;
 }
+/**
+ * Write policy for a `shared`-scope collection. Shared collections are
+ * read-by-all; the write policy narrows who may WRITE:
+ *
+ *   - 'any' (default): every user of the arche may write any document.
+ *   - 'author': creating a NEW key is open to everyone, but overwriting or
+ *     deleting an existing document requires being its author (the last
+ *     successful writer) or an arche collaborator. Use for shared catalogs /
+ *     caches where users publish their own entries.
+ *   - 'collaborators': only arche collaborators (owner/publisher) may write.
+ *     Use for curated content like a category taxonomy.
+ *
+ * Tighten-only after creation: re-declaring a STRICTER policy on an existing
+ * collection upgrades it when the caller is a collaborator (and is silently
+ * kept as-is for other users, so a shipped `ensure` call stays safe), while
+ * loosening is refused.
+ */
+export type DataStoreWritePolicy = 'any' | 'author' | 'collaborators';
 /**
  * A document returned from the data store.
  */
@@ -823,6 +1013,15 @@ export interface DataStoreDocument<T = Record<string, unknown>> {
     key: string;
     data: T;
     updatedAt: string;
+    /**
+     * Present on SHARED-scope documents only: whether the document's last writer
+     * is an active arche collaborator (owner/publisher). The trust signal for
+     * shared content — e.g. refuse to feed a document into an AI prompt unless
+     * it was authored by a collaborator. The raw author identity is never
+     * exposed. Requires a platform/SDK version with write-policy support;
+     * absent otherwise.
+     */
+    authoredByCollaborator?: boolean;
 }
 /**
  * Filter condition for querying documents.
@@ -859,6 +1058,28 @@ export interface DataStoreQueryResult<T = Record<string, unknown>> {
     /** Cursor for next page, or null if no more results */
     nextCursor: string | null;
 }
+/**
+ * Options for semantic search over a searchable collection.
+ */
+export interface DataStoreSearchOptions {
+    /** Max matches (1-50, default 50). */
+    topK?: number;
+    /** Cosine-similarity floor (0-1, default 0.5). */
+    minSimilarity?: number;
+    /** Optional JSONB facet filters applied alongside the vector match. */
+    filters?: DataStoreQueryFilter[];
+}
+/**
+ * A single semantic-search match.
+ */
+export interface DataStoreSearchMatch<T = Record<string, unknown>> {
+    key: string;
+    data: T;
+    /** Cosine similarity in [0, 1]; higher is closer. */
+    similarity: number;
+    /** Present on shared-scope matches: see {@link DataStoreDocument.authoredByCollaborator}. */
+    authoredByCollaborator?: boolean;
+}
 /**
  * Data Store API available via useFiasDataStore() hook.
  *
@@ -869,22 +1090,147 @@ export interface DataStoreQueryResult<T = Record<string, unknown>> {
  * or 'shared' (all users of the arche share data).
  */
 export interface FiasDataStoreApi {
-    /** Create a named collection. Default scope is 'user'. */
+    /**
+     * Create a named collection. Default scope is 'user'. Pass
+     * `searchable: { field }` to make the collection semantically searchable over
+     * a designated text field — documents written to it are embedded
+     * (asynchronously, managed by the platform) and queryable via `search()`.
+     * Searching requires the `data:search` permission.
+     */
     createCollection: (name: string, options?: {
-        userScope?: 'user' | 'shared';
+        userScope?: 'user' | 'shared' | 'workspace';
+        searchable?: {
+            field: string;
+        };
+        /** Workspace-scoped only: raise the min role to write / read this
+         *  collection above the default (write ≥ member, read ≥ viewer). */
+        writeMinRole?: WorkspaceRole;
+        readMinRole?: WorkspaceRole;
+        /** Shared-scoped only: who may write. See {@link DataStoreWritePolicy}. */
+        writePolicy?: DataStoreWritePolicy;
     }) => Promise<DataStoreCollection>;
     /** List all collections for this arche. */
     listCollections: () => Promise<DataStoreCollection[]>;
     /** Delete a collection and all its documents. */
     deleteCollection: (name: string) => Promise<void>;
-    /** Write (upsert) a document by key. */
-    put: <T extends Record<string, unknown> = Record<string, unknown>>(collection: string, key: string, data: T) => Promise<void>;
-    /** Get a document by key. Returns null if not found. */
-    get: <T extends Record<string, unknown> = Record<string, unknown>>(collection: string, key: string) => Promise<T | null>;
-    /** Query documents with filters, sorting, and pagination. */
-    query: <T extends Record<string, unknown> = Record<string, unknown>>(collection: string, options?: DataStoreQueryOptions) => Promise<DataStoreQueryResult<T>>;
-    /** Delete a document by key. */
-    delete: (collection: string, key: string) => Promise<void>;
+    /**
+     * Write (upsert) a document by key. For a `workspace`-scoped collection pass
+     * `{ workspaceId }`; the caller must be an active member with write access
+     * (owner/admin/member). See {@link FiasWorkspacesApi}.
+     */
+    put: <T extends Record<string, unknown> = Record<string, unknown>>(collection: string, key: string, data: T, options?: DataStoreScopeOptions) => Promise<void>;
+    /** 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>;
+    /**
+     * Like {@link get}, but returns the full document envelope — key,
+     * `updatedAt`, and (for shared-scope documents) the
+     * {@link DataStoreDocument.authoredByCollaborator} trust signal — instead of
+     * the bare data. Use when the caller needs provenance, e.g. before feeding
+     * shared content into an AI prompt.
+     */
+    getDocument: <T extends Record<string, unknown> = Record<string, unknown>>(collection: string, key: string, options?: DataStoreScopeOptions) => Promise<DataStoreDocument<T> | null>;
+    /** Query documents with filters, sorting, and pagination. For a
+     *  `workspace`-scoped collection pass `scope: { workspaceId }`; the caller must
+     *  be an active member (any role can read). */
+    query: <T extends Record<string, unknown> = Record<string, unknown>>(collection: string, options?: DataStoreQueryOptions, scope?: DataStoreScopeOptions) => Promise<DataStoreQueryResult<T>>;
+    /**
+     * Semantic search over a `searchable` collection. Charges the caller's
+     * credits for the query embedding. Requires the `data:search` permission. For
+     * a `workspace`-scoped collection pass `scope: { workspaceId }` (any active
+     * member can search).
+     */
+    search: <T extends Record<string, unknown> = Record<string, unknown>>(collection: string, query: string, options?: DataStoreSearchOptions, scope?: DataStoreScopeOptions) => Promise<DataStoreSearchMatch<T>[]>;
+    /** Delete a document by key. Pass `{ workspaceId }` for a workspace-scoped
+     *  collection (requires owner/admin/member). */
+    delete: (collection: string, key: string, options?: DataStoreScopeOptions) => Promise<void>;
+    /**
+     * Apply up to 25 put/delete operations in a SINGLE transaction — all-or-
+     * nothing. Use for data-integrity flows (e.g. issuing a ledger entry AND
+     * updating a running total together) where a sequence of separate calls could
+     * leave a half-applied state. A batch may span collections and scopes; any
+     * failure (bad key, role denial, quota) rolls the whole batch back.
+     */
+    batch: (operations: DataStoreBatchOp[]) => Promise<void>;
+}
+/** Per-call scope options for workspace-scoped Data Store documents. */
+export interface DataStoreScopeOptions {
+    /** Target workspace for a `workspace`-scoped collection. */
+    workspaceId?: string;
+}
+/**
+ * One write in an atomic batch (see {@link FiasDataStoreApi.batch}). A `put`
+ * upserts a document; a `delete` removes one. `workspaceId` targets a
+ * workspace-scoped collection.
+ */
+export type DataStoreBatchOp = {
+    op: 'put';
+    collection: string;
+    key: string;
+    data: Record<string, unknown>;
+    workspaceId?: string;
+} | {
+    op: 'delete';
+    collection: string;
+    key: string;
+    workspaceId?: string;
+};
+/** Role a user holds within a workspace, in descending privilege. */
+export type WorkspaceRole = 'owner' | 'admin' | 'member' | 'viewer';
+/** A workspace (tenant) the caller belongs to. */
+export interface DataStoreWorkspace {
+    workspaceId: string;
+    displayName: string;
+    /** The calling user's role in this workspace. */
+    role: WorkspaceRole;
+    createdAt: string;
+    /** Soft-archive timestamp; null while active. */
+    archivedAt: string | null;
+}
+/** A member of a workspace. Members are addressed by username — the platform
+ *  userId is internal and never exposed to plugins or users. */
+export interface DataStoreWorkspaceMember {
+    username: string;
+    role: WorkspaceRole;
+    grantedAt: string;
+    /** ISO-8601 expiry, or null for a permanent membership. Owners never expire. */
+    expiresAt: string | null;
+}
+/**
+ * Workspace tenancy API available via the `useFiasWorkspaces()` hook.
+ *
+ * Lets a plugin model team/org workspaces with role-gated membership
+ * (owner/admin/member/viewer) over `workspace`-scoped Data Store collections.
+ * The creating user becomes the founding owner. Role rules (enforced server-side):
+ *   - owner: manage the workspace + members, read/write docs
+ *   - admin: manage members (not owners), read/write docs
+ *   - member: read/write docs
+ *   - viewer: read docs only
+ * A workspace always keeps at least one owner.
+ *
+ * Requires the `data:workspace` permission in fias-plugin.json. Reading/writing
+ * the workspace's documents additionally uses `useFiasDataStore` (`data:store`)
+ * with the `{ workspaceId }` option.
+ */
+export interface FiasWorkspacesApi {
+    /** Create a workspace; the caller becomes its owner. */
+    create: (displayName: string) => 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: (workspaceId: string) => Promise<void>;
+    /** List a workspace's members (any member). */
+    listMembers: (workspaceId: string) => Promise<DataStoreWorkspaceMember[]>;
+    /** Add a member by username, with a role (owner/admin; cannot grant above your
+     *  own role). Optionally time-bound the membership with an ISO-8601 `expiresAt`
+     *  (owners cannot expire). Rejects with `USER_NOT_FOUND` if no such user. */
+    addMember: (workspaceId: string, username: string, role: WorkspaceRole, expiresAt?: string) => Promise<DataStoreWorkspaceMember>;
+    /** Change a member's role by username (owner/admin; keeps the one-owner invariant). */
+    updateMember: (workspaceId: string, username: string, role: WorkspaceRole) => Promise<DataStoreWorkspaceMember>;
+    /** Remove a member by username (owner/admin, or yourself; keeps the one-owner invariant). */
+    removeMember: (workspaceId: string, username: string) => Promise<void>;
 }
 /**
  * IAP product type (mirrors Apple StoreKit).