@volter/live 0.5.211 → 0.5.213

package/src/asset-library.ts

@@ -0,0 +1,104 @@
+/**
+ * THE ASSET LIBRARY, as the session's `/__editor/asset-library/*` routes answer it (editor-core's
+ * `server/asset-library-routes.ts`, which takes these shapes from here): search a source, list an asset's files, and
+ * download one into the project. `editor.assetLibrary` reaches it through `EditorClient`, so a request carries the
+ * session's connection token as every other one does.
+ */
+import type { EditorClient } from './client.js';
+
+/** An asset as a search answers it. */
+export interface OnlineAsset {
+  id: string;
+  source: 'polyhaven' | 'ambientcg' | 'local';
+  name: string;
+  type: 'model' | 'animation' | 'source' | 'hdri' | 'texture' | 'material';
+  thumbnailUrl: string;
+  categories: string[];
+  tags: string[];
+  downloadCount?: number;
+  license?: string;
+  author?: string;
+  sourceUrl?: string;
+  cloudHosted?: boolean;
+  variantId?: string;
+  variantCount?: number;
+  sizeBytes?: number;
+  animationCount?: number;
+  deliveryKinds?: ('local-ssd' | 'cloud' | 'remote')[];
+  addedAt?: string;
+  capabilities?: {
+    previewable: boolean;
+    importable: boolean;
+    runtimeReady: boolean;
+    animated: boolean;
+    deliveryAvailable: boolean;
+    health: 'healthy' | 'source-only' | 'unsupported';
+  };
+}
+
+/** One file of an asset that can be downloaded (`files`); `download` takes it with the asset. */
+export interface AssetFileOption {
+  label: string;
+  format: string;
+  url: string;
+  sizeBytes?: number;
+  /** Additional files that must be downloaded alongside the main URL (GLTF includes). */
+  includes?: { relativePath: string; url: string; size: number }[];
+}
+
+/** `GET /search`'s query. `type` is the kind the source names (`model`, `hdri`, …; `all` in the local catalog). */
+export interface AssetSearchQuery {
+  source: OnlineAsset['source'];
+  type: string;
+  q?: string;
+  category?: string;
+  offset?: number;
+  limit?: number;
+}
+
+/** `POST /download`'s body: the asset and the file `files` offered for it. `license` is the search result's, which the
+ *  route records for a remote source; the local catalog's own license is recorded whatever is passed. */
+export interface AssetDownloadRequest {
+  source: OnlineAsset['source'];
+  id: string;
+  name: string;
+  url: string;
+  format: string;
+  includes?: AssetFileOption['includes'];
+  license?: string;
+}
+
+/** What a download answers: the file's path under the project's `public/`, the provenance operation that wrote it, and
+ *  `ledgerError` when the asset and its license could not be recorded in `.volter/assets.json`. */
+export interface AssetDownloadResult {
+  ok: true;
+  path: string;
+  provenanceOperationId?: string;
+  ledgerError?: string;
+  alreadyExists?: boolean;
+}
+
+/** `editor.assetLibrary`: the routes, one call each. */
+export class LiveAssetLibrary {
+  readonly #client: EditorClient;
+
+  constructor(client: EditorClient) {
+    this.#client = client;
+  }
+
+  /** Search one source: `{ assets, total }`, each asset with its tags, license, author and source address. */
+  async search(query: AssetSearchQuery): Promise<{ assets: OnlineAsset[]; total: number }> {
+    return this.#client.assetLibraryRequest('GET', 'search', query);
+  }
+
+  /** The files an asset can be downloaded as. */
+  async files(asset: { source: OnlineAsset['source']; id: string }): Promise<{ files: AssetFileOption[] }> {
+    return this.#client.assetLibraryRequest('GET', 'files', asset);
+  }
+
+  /** Download one file of an asset into the project's `public/asset-library/`, recording the asset and its license in
+   *  the project's `.volter/assets.json`. */
+  async download(request: AssetDownloadRequest): Promise<AssetDownloadResult> {
+    return this.#client.assetLibraryRequest('POST', 'download', request);
+  }
+}