@fias/arche-sdk 2.3.0 → 2.10.0

package/dist/generated/surfaces.js

@@ -10,7 +10,7 @@
  * fails CI if this file is out of sync.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.useElevenLabsVoiceDesign = exports.AUDIO_VOICE_DESIGN_SURFACE_KEY = exports.useElevenLabsVoiceChanger = exports.AUDIO_VOICE_CHANGER_SURFACE_KEY = exports.useElevenLabsTts = exports.AUDIO_TTS_SURFACE_KEY = exports.useElevenLabsStt = exports.AUDIO_SPEECH_TO_TEXT_SURFACE_KEY = exports.useElevenLabsSfx = exports.AUDIO_SOUND_EFFECTS_SURFACE_KEY = exports.useElevenLabsMusic = exports.AUDIO_MUSIC_SURFACE_KEY = exports.useLyriaMusic = exports.AUDIO_LYRIA_MUSIC_SURFACE_KEY = exports.useElevenLabsForcedAlignment = exports.AUDIO_FORCED_ALIGNMENT_SURFACE_KEY = exports.useElevenLabsAudioIsolation = exports.AUDIO_AUDIO_ISOLATION_SURFACE_KEY = void 0;
+exports.useIntegrationWebSearch = exports.INTEGRATION_WEB_SEARCH_SURFACE_KEY = exports.useSmartVectorize = exports.IMAGE_SMART_VECTORIZE_SURFACE_KEY = exports.useSmartUpscale = exports.IMAGE_SMART_UPSCALE_SURFACE_KEY = exports.useSmartSearchReplace = exports.IMAGE_SMART_SEARCH_REPLACE_SURFACE_KEY = exports.useSmartSearchRecolor = exports.IMAGE_SMART_SEARCH_RECOLOR_SURFACE_KEY = exports.useSmartReplaceBackground = exports.IMAGE_SMART_REPLACE_BACKGROUND_SURFACE_KEY = exports.useSmartRemoveBackground = exports.IMAGE_SMART_REMOVE_BACKGROUND_SURFACE_KEY = exports.useSmartOutpaint = exports.IMAGE_SMART_OUTPAINT_SURFACE_KEY = exports.useSmartInpaint = exports.IMAGE_SMART_INPAINT_SURFACE_KEY = exports.useSmartImageToImage = exports.IMAGE_SMART_IMAGE_TO_IMAGE_SURFACE_KEY = exports.useSmartErase = exports.IMAGE_SMART_ERASE_SURFACE_KEY = exports.useSmartControl = exports.IMAGE_SMART_CONTROL_SURFACE_KEY = exports.useElevenLabsVoiceDesign = exports.AUDIO_VOICE_DESIGN_SURFACE_KEY = exports.useElevenLabsVoiceChanger = exports.AUDIO_VOICE_CHANGER_SURFACE_KEY = exports.useElevenLabsTts = exports.AUDIO_TTS_SURFACE_KEY = exports.useElevenLabsStt = exports.AUDIO_SPEECH_TO_TEXT_SURFACE_KEY = exports.useElevenLabsSfx = exports.AUDIO_SOUND_EFFECTS_SURFACE_KEY = exports.useElevenLabsMusic = exports.AUDIO_MUSIC_SURFACE_KEY = exports.useLyriaMusic = exports.AUDIO_LYRIA_MUSIC_SURFACE_KEY = exports.useElevenLabsForcedAlignment = exports.AUDIO_FORCED_ALIGNMENT_SURFACE_KEY = exports.useElevenLabsAudioIsolation = exports.AUDIO_AUDIO_ISOLATION_SURFACE_KEY = void 0;
 const hooks_1 = require("../hooks");
 exports.AUDIO_AUDIO_ISOLATION_SURFACE_KEY = 'audio.audio-isolation';
 /**
@@ -84,4 +84,100 @@ exports.AUDIO_VOICE_DESIGN_SURFACE_KEY = 'audio.voice-design';
  */
 const useElevenLabsVoiceDesign = () => (0, hooks_1.useSurface)(exports.AUDIO_VOICE_DESIGN_SURFACE_KEY);
 exports.useElevenLabsVoiceDesign = useElevenLabsVoiceDesign;
+exports.IMAGE_SMART_CONTROL_SURFACE_KEY = 'image.smart-control';
+/**
+ * Guided generation from a control image — sketch, structure, style, or style-transfer.
+ *
+ * Permission: `entities:image_edit`
+ */
+const useSmartControl = () => (0, hooks_1.useSurface)(exports.IMAGE_SMART_CONTROL_SURFACE_KEY);
+exports.useSmartControl = useSmartControl;
+exports.IMAGE_SMART_ERASE_SURFACE_KEY = 'image.smart-erase';
+/**
+ * Remove a masked object and fill the gap with plausible background.
+ *
+ * Permission: `entities:image_edit`
+ */
+const useSmartErase = () => (0, hooks_1.useSurface)(exports.IMAGE_SMART_ERASE_SURFACE_KEY);
+exports.useSmartErase = useSmartErase;
+exports.IMAGE_SMART_IMAGE_TO_IMAGE_SURFACE_KEY = 'image.smart-image-to-image';
+/**
+ * Regenerate an image from a source + prompt, controlling how much to keep.
+ *
+ * Permission: `entities:image_edit`
+ */
+const useSmartImageToImage = () => (0, hooks_1.useSurface)(exports.IMAGE_SMART_IMAGE_TO_IMAGE_SURFACE_KEY);
+exports.useSmartImageToImage = useSmartImageToImage;
+exports.IMAGE_SMART_INPAINT_SURFACE_KEY = 'image.smart-inpaint';
+/**
+ * Replace a masked region of an image from a text prompt (Stability / Recraft / OpenAI engines).
+ *
+ * Permission: `entities:image_edit`
+ */
+const useSmartInpaint = () => (0, hooks_1.useSurface)(exports.IMAGE_SMART_INPAINT_SURFACE_KEY);
+exports.useSmartInpaint = useSmartInpaint;
+exports.IMAGE_SMART_OUTPAINT_SURFACE_KEY = 'image.smart-outpaint';
+/**
+ * Extend an image beyond its edges, inventing plausible new content.
+ *
+ * Permission: `entities:image_edit`
+ */
+const useSmartOutpaint = () => (0, hooks_1.useSurface)(exports.IMAGE_SMART_OUTPAINT_SURFACE_KEY);
+exports.useSmartOutpaint = useSmartOutpaint;
+exports.IMAGE_SMART_REMOVE_BACKGROUND_SURFACE_KEY = 'image.smart-remove-background';
+/**
+ * Remove an image background with Stability/Recraft. Returns a transparent PNG.
+ *
+ * Permission: `entities:image_edit`
+ */
+const useSmartRemoveBackground = () => (0, hooks_1.useSurface)(exports.IMAGE_SMART_REMOVE_BACKGROUND_SURFACE_KEY);
+exports.useSmartRemoveBackground = useSmartRemoveBackground;
+exports.IMAGE_SMART_REPLACE_BACKGROUND_SURFACE_KEY = 'image.smart-replace-background';
+/**
+ * Swap the background behind a subject from a prompt and/or reference, with relighting.
+ *
+ * Permission: `entities:image_edit`
+ */
+const useSmartReplaceBackground = () => (0, hooks_1.useSurface)(exports.IMAGE_SMART_REPLACE_BACKGROUND_SURFACE_KEY);
+exports.useSmartReplaceBackground = useSmartReplaceBackground;
+exports.IMAGE_SMART_SEARCH_RECOLOR_SURFACE_KEY = 'image.smart-search-recolor';
+/**
+ * Recolor a text-described object while keeping its shape.
+ *
+ * Permission: `entities:image_edit`
+ */
+const useSmartSearchRecolor = () => (0, hooks_1.useSurface)(exports.IMAGE_SMART_SEARCH_RECOLOR_SURFACE_KEY);
+exports.useSmartSearchRecolor = useSmartSearchRecolor;
+exports.IMAGE_SMART_SEARCH_REPLACE_SURFACE_KEY = 'image.smart-search-replace';
+/**
+ * Replace a text-described object with new content — no manual mask.
+ *
+ * Permission: `entities:image_edit`
+ */
+const useSmartSearchReplace = () => (0, hooks_1.useSurface)(exports.IMAGE_SMART_SEARCH_REPLACE_SURFACE_KEY);
+exports.useSmartSearchReplace = useSmartSearchReplace;
+exports.IMAGE_SMART_UPSCALE_SURFACE_KEY = 'image.smart-upscale';
+/**
+ * Increase image resolution (fast / high-quality / reimagine).
+ *
+ * Permission: `entities:image_edit`
+ */
+const useSmartUpscale = () => (0, hooks_1.useSurface)(exports.IMAGE_SMART_UPSCALE_SURFACE_KEY);
+exports.useSmartUpscale = useSmartUpscale;
+exports.IMAGE_SMART_VECTORIZE_SURFACE_KEY = 'image.smart-vectorize';
+/**
+ * Convert a raster image to a scalable SVG. Result mimeType is image/svg+xml.
+ *
+ * Permission: `entities:image_edit`
+ */
+const useSmartVectorize = () => (0, hooks_1.useSurface)(exports.IMAGE_SMART_VECTORIZE_SURFACE_KEY);
+exports.useSmartVectorize = useSmartVectorize;
+exports.INTEGRATION_WEB_SEARCH_SURFACE_KEY = 'integration.web-search';
+/**
+ * Search the live web and get a concise, cited summary — a text answer plus the source URLs it used.
+ *
+ * Permission: `entities:web_search`
+ */
+const useIntegrationWebSearch = () => (0, hooks_1.useSurface)(exports.INTEGRATION_WEB_SEARCH_SURFACE_KEY);
+exports.useIntegrationWebSearch = useIntegrationWebSearch;
 //# sourceMappingURL=surfaces.js.map

package/dist/generated/surfaces.js.map

@@ -1 +1 @@
-{"version":3,"file":"surfaces.js","sourceRoot":"","sources":["../../src/generated/surfaces.ts"],"names":[],"mappings":";AAAA;;;;;;;;;GASG;;;AAEH,oCAAsC;AAkBzB,QAAA,iCAAiC,GAAG,uBAAgC,CAAC;AAElF;;;;GAIG;AACI,MAAM,2BAA2B,GAAG,GAAG,EAAE,CAC9C,IAAA,kBAAU,EACR,yCAAiC,CAClC,CAAC;AAHS,QAAA,2BAA2B,+BAGpC;AAwBS,QAAA,kCAAkC,GAAG,wBAAiC,CAAC;AAEpF;;;;GAIG;AACI,MAAM,4BAA4B,GAAG,GAAG,EAAE,CAC/C,IAAA,kBAAU,EACR,0CAAkC,CACnC,CAAC;AAHS,QAAA,4BAA4B,gCAGrC;AA2BS,QAAA,6BAA6B,GAAG,mBAA4B,CAAC;AAE1E;;;;GAIG;AACI,MAAM,aAAa,GAAG,GAAG,EAAE,CAChC,IAAA,kBAAU,EAAqC,qCAA6B,CAAC,CAAC;AADnE,QAAA,aAAa,iBACsD;AAoBnE,QAAA,uBAAuB,GAAG,aAAsB,CAAC;AAE9D;;;;GAIG;AACI,MAAM,kBAAkB,GAAG,GAAG,EAAE,CACrC,IAAA,kBAAU,EAA+C,+BAAuB,CAAC,CAAC;AADvE,QAAA,kBAAkB,sBACqD;AAmBvE,QAAA,+BAA+B,GAAG,qBAA8B,CAAC;AAE9E;;;;GAIG;AACI,MAAM,gBAAgB,GAAG,GAAG,EAAE,CACnC,IAAA,kBAAU,EAA2C,uCAA+B,CAAC,CAAC;AAD3E,QAAA,gBAAgB,oBAC2D;AAsB3E,QAAA,gCAAgC,GAAG,sBAA+B,CAAC;AAEhF;;;;GAIG;AACI,MAAM,gBAAgB,GAAG,GAAG,EAAE,CACnC,IAAA,kBAAU,EAA2C,wCAAgC,CAAC,CAAC;AAD5E,QAAA,gBAAgB,oBAC4D;AAyB5E,QAAA,qBAAqB,GAAG,WAAoB,CAAC;AAE1D;;;;GAIG;AACI,MAAM,gBAAgB,GAAG,GAAG,EAAE,CACnC,IAAA,kBAAU,EAA2C,6BAAqB,CAAC,CAAC;AADjE,QAAA,gBAAgB,oBACiD;AAoBjE,QAAA,+BAA+B,GAAG,qBAA8B,CAAC;AAE9E;;;;GAIG;AACI,MAAM,yBAAyB,GAAG,GAAG,EAAE,CAC5C,IAAA,kBAAU,EACR,uCAA+B,CAChC,CAAC;AAHS,QAAA,yBAAyB,6BAGlC;AAkBS,QAAA,8BAA8B,GAAG,oBAA6B,CAAC;AAE5E;;;;GAIG;AACI,MAAM,wBAAwB,GAAG,GAAG,EAAE,CAC3C,IAAA,kBAAU,EACR,sCAA8B,CAC/B,CAAC;AAHS,QAAA,wBAAwB,4BAGjC"}
+{"version":3,"file":"surfaces.js","sourceRoot":"","sources":["../../src/generated/surfaces.ts"],"names":[],"mappings":"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"}

package/dist/hooks.d.ts

@@ -1,8 +1,15 @@
-import type { FiasUser, FiasTheme, FiasStorageApi, EntityInvocationApi, ImageGenerationApi, ImageEntityFilter, ImageEntitySummary, BackgroundRemovalApi, AudioGenerationApi, FiasNavigationApi, StepNavigationApi, StepNavigationOptions, FiasDataStoreApi, FiasStoreApi, VaultDocumentsApi, VaultDocumentDownloadUrl, ArcheAssetsApi } from './types';
+import type { FiasUser, FiasTheme, FiasStorageApi, DataSubscriptionState, EntityInvocationApi, ClientEntityApi, ImageGenerationApi, ImageEntityFilter, ImageEntitySummary, BackgroundRemovalApi, NllbLanguageOption, AudioGenerationApi, FiasNavigationApi, StepNavigationApi, StepNavigationOptions, FiasDataStoreApi, FiasWorkspacesApi, FiasStoreApi, VaultDocumentsApi, VaultDocumentDownloadUrl, ArcheAssetsApi } from './types';
 /**
  * Access the current user's profile information.
  * Requires the `user:profile:read` permission in fias-plugin.json.
  *
+ * If the `get_user` bridge request fails — most commonly because the plugin
+ * called this hook without declaring `user:profile:read` — the error is
+ * thrown during render so it surfaces to the nearest error boundary
+ * (`FiasProvider` installs one). Previously a failed/denied request left the
+ * hook permanently returning `null`, indistinguishable from "still loading",
+ * so a UI that gated on `if (!user)` hung on an infinite spinner forever.
+ *
  * @returns The current user's profile or null while loading.
  */
 export declare function useFiasUser(): FiasUser | null;
@@ -14,6 +21,22 @@ export declare function useFiasUser(): FiasUser | null;
  * @returns The current theme tokens or null while loading.
  */
 export declare function useFiasTheme(): FiasTheme | null;
+/**
+ * Self-hosted asset URLs for a platform-vendored library, for plugins that
+ * declare the `sandbox:vendored-libraries` permission. Returns a file-key → URL
+ * map (for `pdfjs-dist`: `{ mainModule, worker, cMapUrl, standardFontDataUrl }`),
+ * or `null` when the host's CDN is unconfigured or the library isn't vendored
+ * (the plugin should then degrade gracefully).
+ *
+ * Delivered in the init payload (no gated request); values are static for the
+ * session. The import specifier is already pinned to its main module via the
+ * host importmap, so a plugin typically only needs `worker` (pass to the
+ * pdf-core loader's `workerModuleUrl`) and the CMap/font directories.
+ *
+ * @param importSpecifier The vendored library's bare module name (e.g. `'pdfjs-dist'`).
+ * @returns The library's asset URLs, or null if unavailable.
+ */
+export declare function useFiasVendoredAssets(importSpecifier: string): Record<string, string> | null;
 /**
  * Access the plugin's sandboxed storage.
  * Requires the `storage:sandbox` permission in fias-plugin.json.
@@ -92,6 +115,66 @@ export declare function useImageEntities(filter?: ImageEntityFilter): {
  * (sourced from the entity's `pluginInvocable.rateLimitPerMinute`).
  */
 export declare function useBackgroundRemoval(): BackgroundRemovalApi;
+/**
+ * Invoke a client-side ("on-device") entity through the bridge's generic
+ * `client_entity_invoke` op. Client-side entities execute entirely in the
+ * browser (e.g. the nspell + retext grammar checker, the imgly WASM
+ * background remover) — input never leaves the device and there is no
+ * per-call credit cost.
+ *
+ * This is the client-side counterpart to {@link useEntityInvocation}, which
+ * invokes server-side, credit-billed AI entities. Target an entity by its ID
+ * and supply the input shape that entity documents; the typed result flows
+ * back through the returned promise:
+ *
+ * ```tsx
+ * const { invoke, isLoading, error } = useClientEntity();
+ * const { issues } = await invoke<GrammarCheckInput, GrammarCheckResult>(
+ *   GRAMMAR_CHECK_ENTITY_ID,
+ *   { text },
+ * );
+ * ```
+ *
+ * Requires the `entities:client_invoke` permission in `fias-plugin.json`.
+ * Per-entity rate limits (each entity's `pluginInvocable.rateLimitPerMinute`)
+ * are enforced by the host.
+ *
+ * Input limits are enforced **host-side by each entity's executor**, not by
+ * this hook — being generic, it cannot know a given entity's caps (e.g. the
+ * grammar entity's 100,000-character limit). Oversized/invalid input is
+ * rejected after it crosses the bridge, surfacing as a rejected promise /
+ * `error`. If you want to fail fast before the round-trip, pre-validate in
+ * your own code against the limits the entity documents.
+ */
+export declare function useClientEntity(): ClientEntityApi;
+/**
+ * Entity ID of the NLLB-200 on-device translation entity. Exported so plugins
+ * can target it via the generic {@link useClientEntity} hook, with
+ * `TranslateParams` / `TranslationResult` as the I/O types.
+ *
+ * SYNC NOTE: must match `NLLB_TRANSLATION_ENTITY_ID` in
+ * `packages/entities/src/integrations/nllb-translation/config.ts`. The
+ * architecture test `sdk-entity-id-constants-match.test.ts` pins this —
+ * drift fails CI.
+ */
+export declare const NLLB_TRANSLATION_ENTITY_ID = "ent_intg_nllb_xlate_000000000000";
+/**
+ * Curated list of target languages for the NLLB translator, as
+ * label/FLORES-200-code pairs. Not exhaustive (NLLB supports 200 languages) —
+ * a convenient default set for building a picker. Sorted by label.
+ */
+export declare const NLLB_LANGUAGES: readonly NllbLanguageOption[];
+/**
+ * Entity ID of the grammar_check client-side entity. Exported so plugins can
+ * target it via the generic {@link useClientEntity} hook. Literal here so the
+ * SDK stays bundle-clean (no `@fias/entities` runtime dep).
+ *
+ * SYNC NOTE: must match `GRAMMAR_CHECK_ENTITY_ID` in
+ * `packages/entities/src/integrations/grammar-check/config.ts`. The
+ * architecture test `sdk-entity-id-constants-match.test.ts` pins this —
+ * drift fails CI.
+ */
+export declare const GRAMMAR_CHECK_ENTITY_ID = "ent_intg_grammar_check_000000000";
 /**
  * Generate audio (music today; future speech/SFX sub-types via the same
  * hook) via the bridge's `audio_generate` op. Returns an array of clips
@@ -135,9 +218,10 @@ export declare function useSurface<TParams, TResult>(surfaceKey: string, timeout
     error: Error | null;
 };
 /**
- * Navigate within the plugin's route space.
+ * Navigate within the plugin's route space (`navigateTo`), or open another
+ * arche's page (`openArche`, requires the `navigation:open_arche` permission).
  *
- * @returns Navigation API (navigateTo, currentPath).
+ * @returns Navigation API (navigateTo, openArche, currentPath).
  */
 export declare function useFiasNavigation(): FiasNavigationApi;
 /**
@@ -190,6 +274,26 @@ export declare function useStepNavigation(initialStep?: string, options?: StepNa
  * });
  */
 export declare function useFiasDataStore(): FiasDataStoreApi;
+/**
+ * Access workspace tenancy — team/org workspaces with role-gated membership
+ * (owner/admin/member/viewer) over `workspace`-scoped Data Store collections
+ * (ADR-010). The creating user becomes the founding owner; a workspace always
+ * keeps at least one owner.
+ *
+ * Requires the `data:workspace` permission in fias-plugin.json. To read/write a
+ * workspace's documents, use `useFiasDataStore()` with `{ workspaceId }` on a
+ * collection created with `userScope: 'workspace'`.
+ *
+ * @example
+ * const workspaces = useFiasWorkspaces();
+ * const ws = await workspaces.create('Acme Corp');
+ * await workspaces.addMember(ws.workspaceId, otherUserId, 'member');
+ * // then, with useFiasDataStore():
+ * await dataStore.put('ledger', 'tx-1', { amount: 100 }, { workspaceId: ws.workspaceId });
+ *
+ * @returns Workspace API with lifecycle + membership methods.
+ */
+export declare function useFiasWorkspaces(): FiasWorkspacesApi;
 /**
  * Access the in-arche purchase (IAP) store.
  * Provides product listing, purchase initiation, entitlement checking,
@@ -240,4 +344,127 @@ export declare function useVaultDocuments(): VaultDocumentsApi;
  *   // entries[i].signedUrl is a short-lived URL you can use as <img src>
  */
 export declare function useArcheAssets(): ArcheAssetsApi;
+/**
+ * Preserve transient UI state across a builder-preview rebuild.
+ *
+ * In the arche builder, editing code (or a background cross-device sync)
+ * rebuilds the preview, which reloads the iframe and wipes the plugin's
+ * in-memory state — losing, for example, a report the user just generated.
+ * This hook lets you opt that state into host-side preservation: just before
+ * the reload the host snapshots `getState()`, and after the reload it hands the
+ * value back to `onRestore`.
+ *
+ * Inert outside the builder preview (the host never requests a capture), so
+ * it's safe to leave in production plugin code.
+ *
+ * @param key       Stable namespace for this slice of state (so multiple calls
+ *                  don't collide). Use a literal like `'report'`.
+ * @param getState  Returns the current serializable state. Must be JSON-safe.
+ * @param onRestore Receives the snapshot after a reload. Reads the latest
+ *                  closure via a ref, so you don't need a stable identity.
+ *
+ * @example
+ * const [report, setReport] = useState<Report | null>(null);
+ * useFiasPreviewState('report', () => report, (saved) => setReport(saved as Report));
+ */
+export declare function useFiasPreviewState<T>(key: string, getState: () => T, onRestore: (state: T) => void): void;
+/**
+ * Subscribes to realtime change events for a datastore collection
+ * (ADR-012 Phase M4). Notify-then-refetch: the platform pushes a minimal
+ * "this collection changed" invalidation and `onInvalidate` decides what to
+ * refetch — typically re-running the `useFiasDataStore().query(...)` your
+ * component renders from.
+ *
+ * Requires the `data:store` permission (same as reading the collection —
+ * a live invalidation grants nothing polling couldn't retrieve).
+ *
+ * Semantics and guarantees:
+ * - Best-effort, at-most-once delivery: events can be lost or duplicated;
+ *   the initial refetch fires AFTER the subscription is live, so a write
+ *   racing the subscribe is never missed.
+ * - `onInvalidate` runs single-flight with one trailing call: a burst of
+ *   events during an in-flight refetch coalesces into exactly one more.
+ * - The host renews authorization periodically; when it definitively ends
+ *   (`status: 'ended'`), `endedReason` says why — `collection_deleted` and
+ *   `authorization_revoked` are terminal, others may warrant resubscribing
+ *   (unmount/remount or toggle `enabled`).
+ * - Scope-aware: shared collections notify on any user's writes; user-scoped
+ *   collections only on yours; workspace-scoped need `workspaceId` and an
+ *   active membership.
+ *
+ * @example
+ * const dataStore = useFiasDataStore();
+ * const [scores, setScores] = useState<DataStoreDocument[]>([]);
+ * const refresh = useCallback(async () => {
+ *   const res = await dataStore.query('scores', { limit: 50 });
+ *   setScores(res.documents);
+ * }, [dataStore]);
+ * const { status } = useDataSubscription('scores', refresh);
+ */
+export declare function useDataSubscription(collection: string, onInvalidate: () => void | Promise<void>, options?: {
+    workspaceId?: string;
+    enabled?: boolean;
+}): DataSubscriptionState;
+/** Metadata of a user document this arche holds a grant for. */
+export interface VaultUserDocumentSummary {
+    documentId: string;
+    name: string;
+    mimeType: string | null;
+    sizeBytes: number | null;
+    sensitivity: string;
+    createdAt: string;
+    updatedAt: string;
+}
+/** Result of the host picker: what the user picked and confirmed, or a
+ * cancel. A cancel is a normal outcome — never treat it as an error. */
+export type VaultUserDocumentPickResult = {
+    canceled: true;
+} | {
+    documents: Array<Pick<VaultUserDocumentSummary, 'documentId' | 'name' | 'mimeType' | 'sizeBytes'>>;
+};
+export interface VaultUserDocumentsApi {
+    /**
+     * Open the HOST's Vault picker + consent sheet. The user hand-picks
+     * documents and explicitly confirms the grant; your plugin never sees
+     * their vault listing — only the picked documents come back. Must be
+     * called from a user gesture (a button click), and only works in the
+     * published plugin (the preview always resolves `{ canceled: true }`).
+     */
+    pick(options?: {
+        maxDocuments?: number;
+    }): Promise<VaultUserDocumentPickResult>;
+    /** Documents the user has granted this arche (empty until they pick). */
+    list(options?: {
+        limit?: number;
+        offset?: number;
+    }): Promise<VaultUserDocumentSummary[]>;
+    /**
+     * Read one granted document. `includeContent: true` returns UTF-8 text
+     * for text documents (a binary document rejects with BINARY_DOCUMENT —
+     * use getDownloadUrl for those). Rejects with DOCUMENT_NOT_FOUND once
+     * the user revokes access in Vault → App Access — handle that path.
+     */
+    get(documentId: string, options?: {
+        includeContent?: boolean;
+    }): Promise<{
+        document: VaultUserDocumentSummary;
+        content: string | null;
+    }>;
+    /** 1-hour signed URL for a granted document's bytes (images, PDFs, …). */
+    getDownloadUrl(documentId: string): Promise<{
+        url: string;
+        expiresAt: number;
+        contentType: string | null;
+    }>;
+}
+/**
+ * Consented access to documents the USER already owns — the only SDK
+ * surface that reaches data your plugin did not create. Requires the
+ * `vault:user-documents:read` permission. Every access is user-consented
+ * (per-document grants created in the host picker, revocable any time in
+ * Vault → App Access) and audited by the platform. Proprietary-sensitivity
+ * documents are never grantable. For documents your plugin CREATES, use
+ * `useVaultDocuments` instead.
+ */
+export declare function useVaultUserDocuments(): VaultUserDocumentsApi;
 //# sourceMappingURL=hooks.d.ts.map

package/dist/hooks.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"hooks.d.ts","sourceRoot":"","sources":["../src/hooks.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EACV,QAAQ,EACR,SAAS,EACT,cAAc,EACd,mBAAmB,EAGnB,kBAAkB,EAGlB,iBAAiB,EACjB,kBAAkB,EAElB,oBAAoB,EACpB,kBAAkB,EAGlB,iBAAiB,EACjB,iBAAiB,EACjB,qBAAqB,EACrB,gBAAgB,EAIhB,YAAY,EAMZ,iBAAiB,EAGjB,wBAAwB,EAUxB,cAAc,EAMf,MAAM,SAAS,CAAC;AA4EjB;;;;;GAKG;AACH,wBAAgB,WAAW,IAAI,QAAQ,GAAG,IAAI,CAe7C;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,IAAI,SAAS,GAAG,IAAI,CAS/C;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,IAAI,cAAc,CAqC/C;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,mBAAmB,IAAI,mBAAmB,CAoCzD;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,kBAAkB,IAAI,kBAAkB,CA2BvD;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,CAAC,EAAE,iBAAiB,GAAG;IAC5D,QAAQ,EAAE,kBAAkB,EAAE,CAAC;IAC/B,SAAS,EAAE,OAAO,CAAC;IACnB,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IACpB,OAAO,EAAE,MAAM,IAAI,CAAC;CACrB,CAiCA;AAkBD;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,IAAI,oBAAoB,CAqC3D;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,kBAAkB,IAAI,kBAAkB,CA2BvD;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,SAAS,SAAU;qBAOjE,OAAO,KAAG,OAAO,CAAC,OAAO,CAAC;;;;EAuB5C;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,IAAI,iBAAiB,CA6BrD;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,EAClC,GAAG,EAAE,MAAM,EACX,YAAY,EAAE,CAAC,GACd,CAAC,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,KAAK,IAAI,CAAC,CA4C5C;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,iBAAiB,CAC/B,WAAW,CAAC,EAAE,MAAM,EACpB,OAAO,CAAC,EAAE,qBAAqB,GAC9B,iBAAiB,CAiEnB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,gBAAgB,IAAI,gBAAgB,CAyFnD;AAED;;;;;;;;GAQG;AACH,wBAAgB,YAAY,IAAI,YAAY,CAqG3C;AA6BD;;;;;GAKG;AACH,wBAAsB,6BAA6B,CACjD,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,wBAAwB,CAAC,CAoCnC;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,iBAAiB,IAAI,iBAAiB,CAsNrD;AAiBD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,cAAc,IAAI,cAAc,CAgC/C"}
+{"version":3,"file":"hooks.d.ts","sourceRoot":"","sources":["../src/hooks.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EACV,QAAQ,EACR,SAAS,EACT,cAAc,EACd,qBAAqB,EACrB,mBAAmB,EAGnB,eAAe,EACf,kBAAkB,EAGlB,iBAAiB,EACjB,kBAAkB,EAElB,oBAAoB,EACpB,kBAAkB,EAClB,kBAAkB,EAGlB,iBAAiB,EACjB,iBAAiB,EACjB,qBAAqB,EACrB,gBAAgB,EAQhB,iBAAiB,EAIjB,YAAY,EAMZ,iBAAiB,EAGjB,wBAAwB,EAUxB,cAAc,EAMf,MAAM,SAAS,CAAC;AAsFjB;;;;;;;;;;;;GAYG;AACH,wBAAgB,WAAW,IAAI,QAAQ,GAAG,IAAI,CAuB7C;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,IAAI,SAAS,GAAG,IAAI,CAS/C;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,qBAAqB,CAAC,eAAe,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,CAG5F;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,IAAI,cAAc,CAiD/C;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,mBAAmB,IAAI,mBAAmB,CAoCzD;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,kBAAkB,IAAI,kBAAkB,CA2BvD;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,CAAC,EAAE,iBAAiB,GAAG;IAC5D,QAAQ,EAAE,kBAAkB,EAAE,CAAC;IAC/B,SAAS,EAAE,OAAO,CAAC;IACnB,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IACpB,OAAO,EAAE,MAAM,IAAI,CAAC;CACrB,CAiCA;AAkBD;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,IAAI,oBAAoB,CAqC3D;AASD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAgB,eAAe,IAAI,eAAe,CA+BjD;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,0BAA0B,qCAAqC,CAAC;AAE7E;;;;GAIG;AACH,eAAO,MAAM,cAAc,EAAE,SAAS,kBAAkB,EAwCvD,CAAC;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,uBAAuB,qCAAqC,CAAC;AAE1E;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,kBAAkB,IAAI,kBAAkB,CA2BvD;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,SAAS,SAAU;qBAOjE,OAAO,KAAG,OAAO,CAAC,OAAO,CAAC;;;;EAuB5C;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,IAAI,iBAAiB,CAoCrD;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,EAClC,GAAG,EAAE,MAAM,EACX,YAAY,EAAE,CAAC,GACd,CAAC,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,KAAK,IAAI,CAAC,CAkD5C;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,iBAAiB,CAC/B,WAAW,CAAC,EAAE,MAAM,EACpB,OAAO,CAAC,EAAE,qBAAqB,GAC9B,iBAAiB,CAmEnB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,gBAAgB,IAAI,gBAAgB,CAoKnD;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,iBAAiB,IAAI,iBAAiB,CAgHrD;AAED;;;;;;;;GAQG;AACH,wBAAgB,YAAY,IAAI,YAAY,CAkG3C;AA6BD;;;;;GAKG;AACH,wBAAsB,6BAA6B,CACjD,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,wBAAwB,CAAC,CAoCnC;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,iBAAiB,IAAI,iBAAiB,CAkMrD;AAaD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,cAAc,IAAI,cAAc,CAgC/C;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,EACnC,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,MAAM,CAAC,EACjB,SAAS,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,GAC5B,IAAI,CAcN;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAgB,mBAAmB,CACjC,UAAU,EAAE,MAAM,EAClB,YAAY,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,EACxC,OAAO,CAAC,EAAE;IAAE,WAAW,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,OAAO,CAAA;CAAE,GACpD,qBAAqB,CAuFvB;AAMD,gEAAgE;AAChE,MAAM,WAAW,wBAAwB;IACvC,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;wEACwE;AACxE,MAAM,MAAM,2BAA2B,GACnC;IAAE,QAAQ,EAAE,IAAI,CAAA;CAAE,GAClB;IACE,SAAS,EAAE,KAAK,CACd,IAAI,CAAC,wBAAwB,EAAE,YAAY,GAAG,MAAM,GAAG,UAAU,GAAG,WAAW,CAAC,CACjF,CAAC;CACH,CAAC;AAEN,MAAM,WAAW,qBAAqB;IACpC;;;;;;OAMG;IACH,IAAI,CAAC,OAAO,CAAC,EAAE;QAAE,YAAY,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,2BAA2B,CAAC,CAAC;IAChF,yEAAyE;IACzE,IAAI,CAAC,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,wBAAwB,EAAE,CAAC,CAAC;IACzF;;;;;OAKG;IACH,GAAG,CACD,UAAU,EAAE,MAAM,EAClB,OAAO,CAAC,EAAE;QAAE,cAAc,CAAC,EAAE,OAAO,CAAA;KAAE,GACrC,OAAO,CAAC;QAAE,QAAQ,EAAE,wBAAwB,CAAC;QAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,CAAC,CAAC;IAC3E,0EAA0E;IAC1E,cAAc,CACZ,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,CAAC,CAAC;CAC5E;AAED;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,IAAI,qBAAqB,CA2D7D"}