@cesdk/engine 1.58.0-nightly.20250808 → 1.58.0-nightly.20250810

package/index.d.ts

@@ -271,11 +271,83 @@ export declare class AssetAPI {
     addLocalSource(id: string, supportedMimeTypes?: string[], applyAsset?: (asset: CompleteAssetResult) => Promise<DesignBlockId | undefined>, applyAssetToBlock?: (asset: CompleteAssetResult, block: DesignBlockId) => Promise<void>): void;
     /**
      * Creates a new local asset source from a JSON string containing asset definitions.
+     *
+     * The JSON structure should contain a `version` field, an `id` field specifying the asset source identifier,
+     * and an `assets` array with asset definitions. Each asset should have an `id`, localized `label` object,
+     * and a `meta` object containing asset-specific properties like `uri`, `thumbUri`, `blockType`, etc.
+     *
+     * @category Asset Source Management
      * @param contentJSON - The JSON string containing the asset definitions.
      * @param basePath - An optional base path with which \{\{base_url\}\} strings in the assets should be replaced. If no value is provided, settings.basePath is used.
-     * @returns The ID of the newly created asset source or an error if that could not be created.
+     * @returns The ID of the newly created asset source (as specified in the JSON's `id` field).
+     *
+     * @example
+     * ```javascript
+     * const json = JSON.stringify({
+     *   "version": "2.0.0",
+     *   "id": "my.custom.assets",
+     *   "assets": [
+     *     {
+     *       "id": "sample_asset",
+     *       "label": { "en": "Sample Asset" },
+     *       "meta": {
+     *         "uri": "https://example.com/asset.jpg",
+     *         "thumbUri": "https://example.com/thumb.jpg",
+     *         "blockType": "//ly.img.ubq/image"
+     *       }
+     *     }
+     *   ]
+     * });
+     * const sourceId = await engine.asset.addLocalAssetSourceFromJSONString(json);
+     * console.log('Created asset source:', sourceId); // "my.custom.assets"
+     * ```
      */
     addLocalAssetSourceFromJSONString(contentJSON: string, basePath?: string): Promise<string>;
+    /**
+     * Creates a new local asset source from a JSON URI.
+     *
+     * Loads and parses a JSON file from the specified URI to create an asset source. The JSON structure
+     * should contain a `version` field, an `id` field specifying the asset source identifier, and an
+     * `assets` array with asset definitions. The created asset source will have the ID specified in the
+     * JSON's `id` field, and all assets defined in the JSON will be added to the source.
+     *
+     * Note: The parent directory of the content.json URI will be used as the base path for resolving
+     * relative URLs in the asset definitions (e.g., `{{base_url}}` placeholders).
+     *
+     * @category Asset Source Management
+     * @param contentURI - The URI for the JSON file to load and parse.
+     * @returns The ID of the newly created asset source (as specified in the JSON's `id` field).
+     *
+     * @example
+     * ```javascript
+     * // Load audio assets from IMG.LY's CDN
+     * const sourceId = await engine.asset.addLocalAssetSourceFromJSONURI(
+     *   'https://cdn.img.ly/assets/demo/v2/ly.img.audio/content.json'
+     * );
+     * console.log('Loaded asset source:', sourceId); // "ly.img.audio"
+     *
+     * // The parent directory (https://cdn.img.ly/assets/demo/v2/ly.img.audio/)
+     * // will be used as base path for resolving relative asset URLs
+     *
+     * // The JSON at this URL contains audio assets with structure like:
+     * // {
+     * //   "version": "2.0.0",
+     * //   "id": "ly.img.audio",
+     * //   "assets": [
+     * //     {
+     * //       "id": "dance_harder",
+     * //       "label": { "en": "Dance Harder" },
+     * //       "meta": {
+     * //         "uri": "https://cdn.img.ly/.../dance_harder.m4a",
+     * //         "blockType": "//ly.img.ubq/audio",
+     * //         "mimeType": "audio/x-m4a"
+     * //       }
+     * //     }
+     * //   ]
+     * // }
+     * ```
+     */
+    addLocalAssetSourceFromJSONURI(contentURI: string): Promise<string>;
     /**
      * Remove a registered asset source.
      *