@fias/arche-sdk 1.9.0 → 1.11.0

package/dist/index.mjs

@@ -497,6 +497,60 @@ function useImageGeneration() {
   );
   return { generate, isLoading, result, error };
 }
+function useAudioGeneration() {
+  const bridge = useBridge();
+  const [isLoading, setIsLoading] = useState2(false);
+  const [result, setResult] = useState2(null);
+  const [error, setError] = useState2(null);
+  const generate = useCallback(
+    async (params) => {
+      setIsLoading(true);
+      setError(null);
+      try {
+        const res = await bridge.request("audio_generate", params, 18e4);
+        setResult(res);
+        return res;
+      } catch (err) {
+        const e = err instanceof Error ? err : new Error(String(err));
+        setError(e);
+        throw e;
+      } finally {
+        setIsLoading(false);
+      }
+    },
+    [bridge]
+  );
+  return { generate, isLoading, result, error };
+}
+function useSurface(surfaceKey, timeoutMs = 18e4) {
+  const bridge = useBridge();
+  const [isLoading, setIsLoading] = useState2(false);
+  const [result, setResult] = useState2(null);
+  const [error, setError] = useState2(null);
+  const invoke = useCallback(
+    async (params) => {
+      setIsLoading(true);
+      setError(null);
+      try {
+        const res = await bridge.request(
+          "surface_invoke",
+          { surfaceKey, params },
+          timeoutMs
+        );
+        setResult(res);
+        return res;
+      } catch (err) {
+        const e = err instanceof Error ? err : new Error(String(err));
+        setError(e);
+        throw e;
+      } finally {
+        setIsLoading(false);
+      }
+    },
+    [bridge, surfaceKey, timeoutMs]
+  );
+  return { invoke, isLoading, result, error };
+}
 function useFiasNavigation() {
   const bridge = useBridge();
   const [currentPath, setCurrentPath] = useState2(bridge.getCurrentPath());
@@ -760,32 +814,44 @@ function useFiasStore() {
     ]
   );
 }
-var FILES_DOWNLOAD_URL_REFRESH_BUFFER_MS = 6e4;
+var DOWNLOAD_URL_REFRESH_BUFFER_MS = 6e4;
 var downloadUrlCache = /* @__PURE__ */ new Map();
 var downloadUrlInflight = /* @__PURE__ */ new Map();
-async function fetchFileDownloadUrl(fileId) {
+async function fetchVaultDocumentDownloadUrl(documentId) {
   const now = Date.now();
-  const cached = downloadUrlCache.get(fileId);
-  if (cached && now < cached.expiresAt - FILES_DOWNLOAD_URL_REFRESH_BUFFER_MS) {
-    return { url: cached.url, expiresAt: cached.expiresAt };
+  const cached = downloadUrlCache.get(documentId);
+  if (cached && now < cached.expiresAt - DOWNLOAD_URL_REFRESH_BUFFER_MS) {
+    return { url: cached.url, expiresAt: cached.expiresAt, contentType: cached.contentType };
   }
-  const inflight = downloadUrlInflight.get(fileId);
+  const inflight = downloadUrlInflight.get(documentId);
   if (inflight) return inflight;
   const bridge = getBridge();
-  const promise = bridge.request("files_download_url", { fileId }).then((result) => {
-    downloadUrlCache.set(fileId, { url: result.url, expiresAt: result.expiresAt });
-    return result;
+  const promise = bridge.request(
+    "vault_documents_download_url",
+    { documentId }
+  ).then((result) => {
+    const normalized = {
+      url: result.url,
+      expiresAt: new Date(result.expiresAt).getTime(),
+      contentType: result.contentType
+    };
+    downloadUrlCache.set(documentId, {
+      url: normalized.url,
+      expiresAt: normalized.expiresAt,
+      contentType: normalized.contentType
+    });
+    return normalized;
   }).finally(() => {
-    downloadUrlInflight.delete(fileId);
+    downloadUrlInflight.delete(documentId);
   });
-  downloadUrlInflight.set(fileId, promise);
+  downloadUrlInflight.set(documentId, promise);
   return promise;
 }
-function useFiasFiles() {
+function useVaultDocuments() {
   const bridge = useBridge();
   const list = useCallback(
     async (options) => {
-      return bridge.request("files_list", {
+      return bridge.request("vault_documents_list", {
         search: options?.search,
         limit: options?.limit,
         cursor: options?.cursor
@@ -794,13 +860,15 @@ function useFiasFiles() {
     [bridge]
   );
   const read = useCallback(
-    async (fileId) => {
-      return bridge.request("files_read", { fileId });
+    async (documentId) => {
+      return bridge.request("vault_documents_read", {
+        documentId
+      });
     },
     [bridge]
   );
   const getDownloadUrl = useCallback(
-    (fileId) => fetchFileDownloadUrl(fileId),
+    (documentId) => fetchVaultDocumentDownloadUrl(documentId),
     // The hook closes over the React context's bridge, but the resolver
     // uses the singleton — they are the same instance in practice. Keeping
     // `bridge` in the deps for symmetry with other hooks that do go through
@@ -809,7 +877,7 @@ function useFiasFiles() {
   );
   const write = useCallback(
     async (params) => {
-      return bridge.request("files_write", {
+      return bridge.request("vault_documents_write", {
         name: params.name,
         content: params.content,
         contentType: params.contentType,
@@ -819,21 +887,21 @@ function useFiasFiles() {
     [bridge]
   );
   const update = useCallback(
-    async (fileId, params) => {
-      await bridge.request("files_update", {
-        fileId,
+    async (documentId, params) => {
+      await bridge.request("vault_documents_update", {
+        documentId,
         name: params.name,
         tags: params.tags
       });
-      downloadUrlCache.delete(fileId);
+      downloadUrlCache.delete(documentId);
     },
     [bridge]
   );
-  const deleteFile = useCallback(
-    async (fileId) => {
-      await bridge.request("files_delete", { fileId });
-      downloadUrlCache.delete(fileId);
-      downloadUrlInflight.delete(fileId);
+  const deleteDocument = useCallback(
+    async (documentId) => {
+      await bridge.request("vault_documents_delete", { documentId });
+      downloadUrlCache.delete(documentId);
+      downloadUrlInflight.delete(documentId);
     },
     [bridge]
   );
@@ -844,11 +912,76 @@ function useFiasFiles() {
       getDownloadUrl,
       write,
       update,
-      delete: deleteFile
+      delete: deleteDocument
     }),
-    [list, read, getDownloadUrl, write, update, deleteFile]
+    [list, read, getDownloadUrl, write, update, deleteDocument]
   );
 }
+function useArcheAssets() {
+  const bridge = useBridge();
+  const list = useCallback(
+    async (options) => {
+      return bridge.request("arche_assets_list", {
+        cursor: options?.cursor,
+        limit: options?.limit
+      });
+    },
+    [bridge]
+  );
+  const getUrl = useCallback(
+    async (assetId) => {
+      return bridge.request("arche_assets_get_url", { assetId });
+    },
+    [bridge]
+  );
+  return useMemo2(() => ({ list, getUrl }), [list, getUrl]);
+}
+
+// src/generated/surfaces.ts
+var AUDIO_AUDIO_ISOLATION_SURFACE_KEY = "audio.audio-isolation";
+var useElevenLabsAudioIsolation = () => useSurface(
+  AUDIO_AUDIO_ISOLATION_SURFACE_KEY
+);
+var AUDIO_FORCED_ALIGNMENT_SURFACE_KEY = "audio.forced-alignment";
+var useElevenLabsForcedAlignment = () => useSurface(
+  AUDIO_FORCED_ALIGNMENT_SURFACE_KEY
+);
+var AUDIO_LYRIA_MUSIC_SURFACE_KEY = "audio.lyria-music";
+var useLyriaMusic = () => useSurface(AUDIO_LYRIA_MUSIC_SURFACE_KEY);
+var AUDIO_MUSIC_SURFACE_KEY = "audio.music";
+var useElevenLabsMusic = () => useSurface(AUDIO_MUSIC_SURFACE_KEY);
+var AUDIO_SOUND_EFFECTS_SURFACE_KEY = "audio.sound-effects";
+var useElevenLabsSfx = () => useSurface(AUDIO_SOUND_EFFECTS_SURFACE_KEY);
+var AUDIO_SPEECH_TO_TEXT_SURFACE_KEY = "audio.speech-to-text";
+var useElevenLabsStt = () => useSurface(AUDIO_SPEECH_TO_TEXT_SURFACE_KEY);
+var AUDIO_TTS_SURFACE_KEY = "audio.tts";
+var useElevenLabsTts = () => useSurface(AUDIO_TTS_SURFACE_KEY);
+var AUDIO_VOICE_CHANGER_SURFACE_KEY = "audio.voice-changer";
+var useElevenLabsVoiceChanger = () => useSurface(
+  AUDIO_VOICE_CHANGER_SURFACE_KEY
+);
+var AUDIO_VOICE_DESIGN_SURFACE_KEY = "audio.voice-design";
+var useElevenLabsVoiceDesign = () => useSurface(
+  AUDIO_VOICE_DESIGN_SURFACE_KEY
+);
+
+// src/generated/permissions.ts
+var VALID_PLUGIN_PERMISSIONS = [
+  "assets:read",
+  "data:store",
+  "entities:audio_generate",
+  "entities:image_generate",
+  "entities:invoke",
+  "storage:sandbox",
+  "store:purchase",
+  "theme:read",
+  "user:profile:read",
+  "vault:documents:read",
+  "vault:documents:write"
+];
+function isValidPluginPermission(perm) {
+  return VALID_PLUGIN_PERMISSIONS.includes(perm);
+}
 
 // src/fias.ts
 var fias = {
@@ -2703,28 +2836,51 @@ function getFontPairingById(id) {
   return FONT_PAIRINGS.find((f) => f.id === id) ?? FONT_PAIRINGS[0];
 }
 export {
+  AUDIO_AUDIO_ISOLATION_SURFACE_KEY,
+  AUDIO_FORCED_ALIGNMENT_SURFACE_KEY,
+  AUDIO_LYRIA_MUSIC_SURFACE_KEY,
+  AUDIO_MUSIC_SURFACE_KEY,
+  AUDIO_SOUND_EFFECTS_SURFACE_KEY,
+  AUDIO_SPEECH_TO_TEXT_SURFACE_KEY,
+  AUDIO_TTS_SURFACE_KEY,
+  AUDIO_VOICE_CHANGER_SURFACE_KEY,
+  AUDIO_VOICE_DESIGN_SURFACE_KEY,
   DARK_THEME,
   FONT_PAIRINGS,
   FiasBridge,
   FiasProvider,
   LIGHT_THEME,
   THEME_CATALOG,
-  fetchFileDownloadUrl,
+  VALID_PLUGIN_PERMISSIONS,
+  fetchVaultDocumentDownloadUrl,
   fias,
   getBridge,
   getDefaultTheme,
   getFontPairingById,
   getThemeById,
+  isValidPluginPermission,
   resetBridge,
+  useArcheAssets,
+  useAudioGeneration,
+  useElevenLabsAudioIsolation,
+  useElevenLabsForcedAlignment,
+  useElevenLabsMusic,
+  useElevenLabsSfx,
+  useElevenLabsStt,
+  useElevenLabsTts,
+  useElevenLabsVoiceChanger,
+  useElevenLabsVoiceDesign,
   useEntityInvocation,
   useFiasDataStore,
-  useFiasFiles,
   useFiasNavigation,
   useFiasStorage,
   useFiasStore,
   useFiasTheme,
   useFiasUser,
   useImageGeneration,
+  useLyriaMusic,
   usePersistentState,
-  useStepNavigation
+  useStepNavigation,
+  useSurface,
+  useVaultDocuments
 };

package/dist/types.d.ts

@@ -1,7 +1,14 @@
 /**
  * Permission scopes that plugins can request in their manifest.
+ *
+ * Re-exported from `./generated/permissions`, which is produced by
+ * `pnpm generate:sdk-types` from `@fias/db-types`'s canonical list. The
+ * `sdk-permissions-match-db-types.test.ts` architecture trip-wire ensures
+ * the generated file stays in lockstep.
  */
-export type PluginPermission = 'user:profile:read' | 'entities:invoke' | 'entities:image_generate' | 'storage:sandbox' | 'theme:read' | 'data:store' | 'store:purchase' | 'files:read' | 'files:write';
+import type { PluginPermission } from './generated/permissions';
+export type { PluginPermission };
+export { VALID_PLUGIN_PERMISSIONS, isValidPluginPermission } from './generated/permissions';
 /**
  * User profile data available via useFiasUser() hook.
  */
@@ -99,18 +106,49 @@ export interface EntityInvocationParams {
  * Image generation parameters for useImageGeneration() hook.
  */
 export interface ImageGenerationParams {
-    /** Entity ID of an image model (e.g., ent_modeldef_dalle3) */
+    /** Entity ID of an image model (e.g., ent_modeldef_gpt_image_1_5) */
     entityId: string;
     /** Text prompt describing the image to generate */
     prompt: string;
     /** Image size/aspect ratio (model-specific, e.g., '1024x1024', '16:9') */
     size?: string;
-    /** Quality level (model-specific, e.g., 'standard', 'hd') */
+    /** Quality level (model-specific, e.g., 'low', 'medium', 'high') */
     quality?: string;
-    /** Artistic style (model-specific, e.g., 'vivid', 'natural') */
+    /** Artistic style (model-specific, e.g., 'realistic_image', 'digital_illustration') */
     style?: string;
     /** Additional provider-specific parameters */
     providerParams?: Record<string, unknown>;
+    /**
+     * Optional reference image for image-to-image generation. Provide ONE of:
+     *
+     * - `{ archeAssetId }` — a published asset from this arche's library
+     *   (uses the `assets:read` permission scope to read bytes server-side).
+     * - `{ fileId }` — a Vault Document this arche owns (uses
+     *   `vault:documents:read` to read bytes server-side). For images
+     *   previously generated via `useImageGeneration`, pass `result.fileId`.
+     * - `{ dataUrl }` — a `data:` URL with base64-encoded PNG/JPEG/WEBP
+     *   bytes. Use only when the source isn't already in the asset library
+     *   or vault; subject to a payload-size cap (~8 MB).
+     *
+     * The selected image model must support reference images (e.g. the
+     * Stability AI entities `ent_modeldef_stable_img_core`,
+     * `ent_modeldef_stable_img_ultra`, `ent_modeldef_sd3_large`). Models
+     * that don't support it return INVALID_PARAMS rather than silently
+     * ignoring the reference.
+     */
+    referenceImage?: {
+        archeAssetId: string;
+    } | {
+        fileId: string;
+    } | {
+        dataUrl: string;
+    };
+    /**
+     * How closely the output should follow the reference image. 0 = ignore
+     * the reference, 1 = copy it almost exactly. Default 0.5 when a
+     * `referenceImage` is provided.
+     */
+    referenceStrength?: number;
 }
 /**
  * Image generation result.
@@ -138,6 +176,73 @@ export interface ImageGenerationApi {
     result: ImageGenerationResult | null;
     error: Error | null;
 }
+/**
+ * Audio sub-type discriminator. v1 ships music only; future entries
+ * (`'speech'`, `'sfx'`, ...) extend the unions on `AudioGenerationParams`,
+ * `AudioGenerationResult`, and the bridge dispatch in lockstep.
+ */
+export type AudioType = 'music';
+/**
+ * Audio generation parameters for useAudioGeneration() hook.
+ *
+ * Discriminated union by `audioType` so future sub-types can carry their
+ * own parameter shape (e.g., speech adds voice/style, SFX adds duration
+ * range) without breaking music callers.
+ */
+export type AudioGenerationParams = MusicAudioGenerationParams;
+/** Parameters for music audio generation (Lyria today). */
+export interface MusicAudioGenerationParams {
+    audioType: 'music';
+    /** Entity ID of a music model (e.g., ent_modeldef_lyria2) OR a PluginAudioConfig configId. */
+    entityId: string;
+    /** Text prompt describing the music to generate. */
+    prompt: string;
+    /** Optional negative prompt — sounds or styles to avoid. */
+    negativePrompt?: string;
+    /** Optional seed for deterministic regeneration. */
+    seed?: number;
+    /** Number of clips to generate (1–4 for Lyria 2). */
+    sampleCount?: number;
+    /** Requested duration in seconds (Lyria 2 emits a fixed 30 s clip). */
+    durationSeconds?: number;
+}
+/**
+ * Audio generation result. Always returns an array of clips so multi-clip
+ * generations (sampleCount > 1) and single-clip generations share one shape.
+ */
+export interface AudioGenerationResult {
+    /** Audio sub-type discriminator matching the request. */
+    audioType: AudioType;
+    /** Generated audio clips. */
+    clips: Array<{
+        /** Same-origin signed proxy URL for `<audio src>`. Expires after ~1 hour. */
+        audioUrl: string;
+        /** S3 reference for the clip (use for persistent storage / re-signing). */
+        audioRef: string;
+        /** User-file record id (best-effort; undefined if the write failed). */
+        fileId?: string;
+        /** MIME type — `audio/wav` today. */
+        mimeType: string;
+        sampleRate: number;
+        durationSeconds: number;
+        sizeBytes: number;
+    }>;
+    /** Sum of `clips[].durationSeconds`. */
+    totalDurationSeconds: number;
+    /** Provider that generated the audio. */
+    provider: string;
+    /** Provider-side model name. */
+    model: string;
+}
+/**
+ * Audio generation API available via useAudioGeneration() hook.
+ */
+export interface AudioGenerationApi {
+    generate: (params: AudioGenerationParams) => Promise<AudioGenerationResult>;
+    isLoading: boolean;
+    result: AudioGenerationResult | null;
+    error: Error | null;
+}
 /**
  * Navigation API available via useFiasNavigation() hook.
  */
@@ -146,16 +251,17 @@ export interface FiasNavigationApi {
     currentPath: string;
 }
 /**
- * A file owned by the calling arche in the user's Fias file system.
+ * A document owned by the calling arche in the user's Vault.
  *
- * Files written via useFiasFiles() (or generated via useImageGeneration())
- * are scoped by `source_arche_id`. Listing only returns files the calling
- * arche created — files from other arches are never visible.
- */
-export interface FiasFile {
-    fileId: string;
-    fileName: string;
-    contentType: string;
+ * Documents written via useVaultDocuments() (or generated via
+ * useImageGeneration()) are scoped by `source_arche_id`. Listing only
+ * returns documents the calling arche created — documents from other
+ * arches are never visible.
+ */
+export interface VaultDocumentSummary {
+    documentId: string;
+    name: string;
+    mimeType: string;
     sizeBytes: number;
     /** ISO 8601 timestamp. */
     createdAt: string;
@@ -164,31 +270,34 @@ export interface FiasFile {
     /** Free-form tags, set by the arche on write/update. */
     tags: string[];
     /**
-     * Folder path within the user's file tree. The platform places arche-owned
-     * files in `/My-Fias/{ArcheName}/` by default; users can move them via
-     * the MyData UI without breaking arche access (listing is scoped by
-     * source_arche_id, not folder).
+     * Folder the document lives in. The platform places arche-owned
+     * writes into `/My-Fias/Arches/<archeId>/` by default; users can move
+     * them via the My Data UI without breaking arche access (listing is
+     * scoped by `source_arche_id`, not folder).
      */
-    folderPath: string | null;
+    folderId: string | null;
 }
-export interface FiasFilesListOptions {
+export interface VaultDocumentsListOptions {
     search?: string;
     limit?: number;
     cursor?: string;
 }
-export interface FiasFilesListResult {
-    files: FiasFile[];
+export interface VaultDocumentsListResult {
+    documents: VaultDocumentSummary[];
     nextCursor: string | null;
 }
-export interface FiasFilesDownloadUrl {
+export interface VaultDocumentDownloadUrl {
     url: string;
     /** Epoch milliseconds when the presigned URL expires. */
     expiresAt: number;
+    /** MIME type of the document, or null when unset on the row. */
+    contentType: string | null;
 }
-export interface FiasFilesWriteParams {
+export interface VaultDocumentWriteParams {
     /**
-     * File name (no leading slash). Must be unique per arche per user; same-name
-     * writes overwrite the existing file's content but keep the same fileId.
+     * Document name (no leading slash). Must be unique per arche per
+     * user; same-name writes create a new row with the same name (no
+     * implicit overwrite — call `delete` first if that's what you want).
      */
     name: string;
     /** UTF-8 string content. Use for JSON, text, or base64-encoded binaries. */
@@ -198,54 +307,103 @@ export interface FiasFilesWriteParams {
     /** Free-form tags. */
     tags?: string[];
 }
-export interface FiasFilesUpdateParams {
-    /** New file name. */
+export interface VaultDocumentUpdateParams {
+    /** New document name. */
     name?: string;
     /** Replaces the tag list. */
     tags?: string[];
 }
 /**
- * Files API available via useFiasFiles() hook.
+ * Vault Documents API available via useVaultDocuments() hook.
  *
- * Provides access to the user's Fias file system, scoped to files this arche
- * owns (via `source_arche_id`). Files are visible to the user in MyData under
- * `/My-Fias/{ArcheName}/`, but the SDK lists by ownership — moving a file in
- * MyData does not hide it from the arche.
+ * Provides access to the user's Vault Documents, scoped to documents
+ * this arche owns (via `source_arche_id`). Documents are visible to
+ * the user in My Data under `/My-Fias/Arches/<archeId>/`, but the SDK
+ * lists by ownership — moving a document in My Data does not hide it
+ * from the arche.
  *
  * Permissions:
- *   - `files:read` — list, read, getDownloadUrl
- *   - `files:write` — write, update, delete
+ *   - `vault:documents:read` — list, read, getDownloadUrl
+ *   - `vault:documents:write` — write, update, delete
  *
- * Note: images returned from useImageGeneration() are auto-saved into the
- * arche's folder and the result includes a `fileId`. Pass that fileId here
- * to refresh the presigned URL after the original ~1h TTL expires.
- */
-export interface FiasFilesApi {
-    /** List files owned by this arche. Paginated. */
-    list: (options?: FiasFilesListOptions) => Promise<FiasFilesListResult>;
-    /** Read the UTF-8 content of a file. */
-    read: (fileId: string) => Promise<{
+ * Note: images returned from useImageGeneration() are auto-saved into
+ * the arche's folder and the result includes a `documentId`. Pass that
+ * documentId here to refresh the presigned URL after the original ~1h
+ * TTL expires.
+ */
+export interface VaultDocumentsApi {
+    /** List documents owned by this arche. Paginated. */
+    list: (options?: VaultDocumentsListOptions) => Promise<VaultDocumentsListResult>;
+    /** Read the UTF-8 content of a document. */
+    read: (documentId: string) => Promise<{
         content: string;
         contentType: string;
     }>;
     /**
-     * Get a fresh presigned download URL for a fileId. The result is cached
-     * client-side and refreshed automatically before expiry.
+     * Get a fresh presigned download URL for a documentId. The result is
+     * cached client-side and refreshed automatically before expiry.
      */
-    getDownloadUrl: (fileId: string) => Promise<FiasFilesDownloadUrl>;
-    /** Create or overwrite a file. Returns the fileId. */
-    write: (params: FiasFilesWriteParams) => Promise<{
-        fileId: string;
+    getDownloadUrl: (documentId: string) => Promise<VaultDocumentDownloadUrl>;
+    /** Create a document. Returns the documentId. */
+    write: (params: VaultDocumentWriteParams) => Promise<{
+        documentId: string;
     }>;
-    /** Rename or retag a file. */
-    update: (fileId: string, params: FiasFilesUpdateParams) => Promise<void>;
-    /** Soft-delete a file (recoverable from the Trash in MyData for 7 days). */
-    delete: (fileId: string) => Promise<void>;
+    /** Rename or retag a document. */
+    update: (documentId: string, params: VaultDocumentUpdateParams) => Promise<void>;
+    /** Soft-delete a document (recoverable from Trash in My Data). */
+    delete: (documentId: string) => Promise<void>;
+}
+/**
+ * One entry from the arche's published asset manifest. Surfaced to
+ * plugins via `useArcheAssets().list()`.
+ *
+ * `signedUrl` is a short-lived (~5 min default) URL that loads through
+ * api.fias.ai's signed proxy. Plugins should use `getUrl(assetId)` to
+ * refresh after expiry rather than caching URLs across sessions.
+ */
+export interface ArcheAsset {
+    assetId: string;
+    signedUrl: string;
+    /** Unix-seconds expiry of `signedUrl`. */
+    expiresAt: number;
+    contentType: 'image/png' | 'image/jpeg' | 'image/webp';
+    width: number;
+    height: number;
+    sizeBytes: number;
+    /** Display name set by the contributor. May be null if not provided. */
+    name: string | null;
+    /** Alt text — recommended for accessibility-aware rendering. */
+    altText: string | null;
+    /** Tags set by the contributor for filtering. Empty array if none. */
+    tags: string[];
+}
+export interface ArcheAssetsListOptions {
+    cursor?: string;
+    /** 1..100. Default 50. */
+    limit?: number;
+}
+export interface ArcheAssetsListResult {
+    entries: ArcheAsset[];
+    nextCursor: string | null;
+}
+/**
+ * Asset library API. Permission: `assets:read`.
+ *
+ * The library is a contributor-curated set of images pinned to this
+ * arche's published version — once the contributor publishes, the set
+ * is immutable for that version's runtime. New uploads on the
+ * contributor's side affect future published versions only.
+ */
+export interface ArcheAssetsApi {
+    /** Page through the published asset manifest. */
+    list: (options?: ArcheAssetsListOptions) => Promise<ArcheAssetsListResult>;
+    /** Refresh the signed URL for a single asset. */
+    getUrl: (assetId: string) => Promise<ArcheAsset>;
 }
 /**
  * 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' | 'image_generate' | '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' | 'files_list' | 'files_read' | 'files_download_url' | 'files_write' | 'files_update' | 'files_delete';
+export type PluginToHostMessageType = 'ready' | 'resize' | 'toast' | 'get_user' | 'get_theme' | 'storage_read' | 'storage_write' | 'storage_list' | 'storage_delete' | 'entity_invoke' | 'image_generate' | '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_download_url' | 'vault_documents_write' | 'vault_documents_update' | 'vault_documents_delete' | 'arche_assets_list' | 'arche_assets_get_url';
 /**
  * Step navigation API available via useStepNavigation() hook.
  */