@cesdk/engine 1.7.0-alpha.1 → 1.7.0-alpha.2

package/index.d.ts

@@ -25,34 +25,77 @@ export declare interface Asset {
 }
 
 /**
- * API to query for assets.
- *
- * Could be remote or local.
- *
- * @typeParam QData - The shape of queries made against this API
  * @public
  */
-export declare interface AssetAPI<QData extends AssetQueryData> {
-    /** The unique id of the API */
-    id: string;
-    /** Find all asset for the given type and the provided query data.  */
-    findAssets(type: string, queryData?: QData): Promise<AssetsQueryResult>;
-    /** For a given type return every available group */
-    getGroups: (type: string) => Promise<string[]>;
-    /** Return all registered/available types */
-    getTypes: () => string[];
-    /** The given type is registered. */
-    hasType: (type: string) => boolean;
-    /** Credits for the source/api */
-    credits?: {
+export declare class AssetAPI {
+    #private;
+
+    /**
+     * Adds a custom asset source. Its ID has to be unique.
+     * @param source - The asset source.
+     */
+    addSource(source: AssetSource): void;
+    /**
+     * Removes an asset source with the given ID.
+     * @param id - The ID to refer to the asset source.
+     */
+    removeSource(id: string): void;
+    /**
+     * Finds all registered asset sources.
+     * @returns A list with the IDs of all registered asset sources.
+     */
+    findAllSources(): string[];
+    /**
+     * Finds all asset sources which support the given asset type.
+     * @returns A list of the IDs of the supported asset sources.
+     */
+    findSourcesByType(type: string): string[];
+    /**
+     * Finds assets of a given type in a specific asset source.
+     * @param id - The ID of the asset source.
+     * @param type - The asset type to look for.
+     * @param query - All the options to filter the search results by.
+     * @returns The search results.
+     */
+    findAssetsInSource(id: string, type: string, query: AssetQueryData): Promise<AssetsQueryResult>;
+    /**
+     * Queries the asset source's groups for a certain asset type.
+     * @param id - The ID of the asset source.
+     * @param type - The asset type to filter by.
+     * @returns The asset groups.
+     */
+    getGroupsInSource(id: string, type: string): Promise<string[]>;
+    /**
+     * Queries the asset source's supported asset types.
+     * @param id - The ID of the asset source.
+     * @returns A list of the asset source's supported types.
+     */
+    getTypesInSource(id: string): string[];
+    /**
+     * Checks whether the asset source supports the given asset type.
+     * @param id - The ID of the asset source.
+     * @param type - The asset type to check.
+     * @returns A boolean indicating whether the type is supported.
+     */
+    hasTypeInSource(id: string, type: string): boolean;
+    /**
+     * Queries the asset source's credits info.
+     * @param id - The ID of the asset source.
+     * @returns The asset source's credits info consisting of a name and an optional URL.
+     */
+    getSourceCredits(id: string): {
         name: string;
-        url?: string;
-    };
-    /** General license for all asset from this source */
-    license?: {
+        url: string | undefined;
+    } | undefined;
+    /**
+     * Queries the asset source's license info.
+     * @param id - The ID of the asset source.
+     * @returns The asset source's license info consisting of a name and an optional URL.
+     */
+    getSourceLicense(id: string): {
         name: string;
-        url?: string;
-    };
+        url: string | undefined;
+    } | undefined;
 }
 
 /**
@@ -81,6 +124,8 @@ export declare interface AssetDefinition extends Asset {
 export declare interface AssetQueryData {
     /** A query string used for (fuzzy) searching of labels and tags */
     query?: string;
+    /** The current page queried for paginated views. */
+    page: number;
     /**
      * Tags are searched with the query parameter, but this search is fuzzy.
      * If one needs to get assets with exactly the tag (from a tag cloud or filter)
@@ -102,21 +147,6 @@ export declare interface AssetQueryData {
     perPage: number;
 }
 
-/**
- * The registry of all available assets and sources registered in the engine.
- * @public
- */
-export declare interface AssetRegistry {
-    /** Returns all sources available in the engine */
-    getSources(type?: string): AssetSource[];
-    /** Returns a source with the given id or undefined if not found */
-    getSource(id: string): AssetSource | undefined;
-    /** Adds a source to this registry. */
-    addSource(source: AssetSource): void;
-    /** Removes a source from this registry. */
-    removeSource(id: string): void;
-}
-
 /**
  * Single asset result of a query from the engine.
  * @public
@@ -188,17 +218,52 @@ declare interface AssetResult_2 {
     };
 }
 
+/** @public */
+declare interface AssetResultContext {
+    sourceId: string;
+    createdByRole: string;
+}
+
+declare interface AssetResultCredits {
+    name: string;
+    url: string;
+}
+
+declare interface AssetResultLicense {
+    name: string;
+    url: string;
+}
+
+declare interface AssetResultUtm {
+    source: string;
+    medium: string;
+}
+
 /**
  * A source of assets
  * @public
  */
-export declare interface AssetSource extends AssetAPI<PaginatedAssetQueryData> {
-    /**
-     * Can the source add, update and remove assets dynamically? If `false`
-     * methods like `addAsset` `updateAsset` and `removeAsset` will throw and
-     * error.
-     */
-    canManageAssets?: boolean;
+export declare interface AssetSource {
+    /** The unique id of the API */
+    id: string;
+    /** Find all asset for the given type and the provided query data.  */
+    findAssets(type: string, queryData: AssetQueryData): Promise<AssetsQueryResult>;
+    /** For a given type return every available group */
+    getGroups: (type: string) => Promise<string[]>;
+    /** Return all registered/available types */
+    getTypes: () => string[];
+    /** The given type is registered. */
+    hasType: (type: string) => boolean;
+    /** Credits for the source/api */
+    credits?: {
+        name: string;
+        url?: string;
+    };
+    /** General license for all asset from this source */
+    license?: {
+        name: string;
+        url?: string;
+    };
     /**
      * Indicates if the asset shall be downloaded to handle the raw data instead
      * of an URL reference. Do this if you do not want to depend on
@@ -211,6 +276,12 @@ export declare interface AssetSource extends AssetAPI<PaginatedAssetQueryData> {
      * @returns the asset or undefined if no asset with the given id could be found
      */
     getAsset(id: string): Promise<AssetResult | undefined>;
+    /**
+     * Can the source add, update and remove assets dynamically? If `false`
+     * methods like `addAsset` `updateAsset` and `removeAsset` will throw an
+     * error.
+     */
+    canManageAssets?: boolean;
     /**
      * Adds the given asset to this source. Throws an error if `canManageAssets`
      * is `false`.
@@ -316,9 +387,10 @@ export declare class BlockAPI {
      * Performs an internal update to resolve the final layout for the blocks.
      * @param handle - The design block element to export.
      * @param mimeType - The mime type of the output file.
+     * @param options - The options for exporting the block type
      * @returns A promise that resolves with the exported image or is rejected with an error.
      */
-    export(handle: DesignBlockId, mimeType?: MimeType_2): Promise<Blob>;
+    export(handle: DesignBlockId, mimeType?: MimeType_2, options?: ExportOptions): Promise<Blob>;
 
     /**
      * Loads existing blocks from the given string.
@@ -1392,7 +1464,7 @@ declare class CreativeEngine {
     scene: SceneAPI;
     variable: VariableAPI;
     editor: EditorAPI;
-
+    asset: AssetAPI;
     event: EventAPI;
 
     /**
@@ -1632,8 +1704,44 @@ export declare class EventAPI {
     subscribe(blocks: DesignBlockId[], callback: (events: BlockEvent[]) => void): () => void;
 }
 
+/**
+ * @public
+ */
+export declare type ExportOptions = {
+    /**
+     * The PNG compression level to use, when exporting to PNG.
+     *
+     * Valid values are 0 to 9, higher means smaller, but slower.
+     * Quality is not affected.
+     * Ignored for other encodings.
+     * @defaultValue 5.
+     */
+    pngCompressionLevel?: number;
+    /**
+     * The JPEG quality to use when encoding to JPEG.
+     *
+     * Valid values are (0-1], higher means better quality.
+     * Ignored for other encodings.
+     *
+     * @defaultValue 0.9
+     */
+    jpegQuality?: number;
+    /**
+     * An optional target width used in conjunction with target height.
+     * If used, the block will be rendered large enough, that it fills the target
+     * size entirely while maintaining its aspect ratio.
+     */
+    targetWidth?: number;
+    /**
+     * An optional target height used in conjunction with target width.
+     * If used, the block will be rendered large enough, that it fills the target
+     * size entirely while maintaining its aspect ratio.
+     */
+    targetHeight?: number;
+};
+
 /** @public */
-declare interface ExportOptions {
+declare interface ExportOptions_2 {
     jpegQuality: number;
     pngCompressionLevel: number;
     useTargetSize: boolean;
@@ -1662,6 +1770,50 @@ declare type Extensions = {
  */
 export declare type FillType = 'Solid' | 'Gradient';
 
+declare interface FindAssetResult {
+    id: string;
+    type: string;
+    groups: Vector<string>;
+    thumbUri: string;
+    width: number;
+    height: number;
+    meta: UnorderedMap<string, string>;
+    locale: string;
+    label: string;
+    tags: Vector<string>;
+    context: AssetResultContext;
+    credits: AssetResultCredits;
+    license: AssetResultLicense;
+    utm: AssetResultUtm;
+}
+
+declare interface FindAssetsQuery {
+    perPage: number;
+    page: number;
+    query: string;
+    tags: string[];
+    groups: string[];
+    excludeGroups: string[];
+    locale: string;
+}
+
+declare interface FindAssetsQueryCpp {
+    perPage: number;
+    page: number;
+    query: string;
+    tags: Vector<string>;
+    groups: Vector<string>;
+    excludeGroups: Vector<string>;
+    locale: string;
+}
+
+declare interface FindAssetsResult {
+    assets: Vector<FindAssetResult>;
+    currentPage: number;
+    nextPage: number;
+    total: number;
+}
+
 /** @public */
 declare interface Flip {
     horizontal: boolean;
@@ -1780,12 +1932,6 @@ declare type PageFormatDefinition = Preset & {
     bleedMargin?: number;
 };
 
-/** @public */
-export declare interface PaginatedAssetQueryData extends AssetQueryData {
-    /** The current page queried for paginated views. */
-    page: number;
-}
-
 /**
  * - Absolute: Position in absolute design units.
  * - Percent: Position in relation to the block's parent's size in percent, where 1.0 means 100%.
@@ -2031,6 +2177,13 @@ declare type TypefaceDefinition = Preset & {
     }[];
 };
 
+declare interface UnorderedMap<K, V> {
+    size: () => number;
+    get: (key: K) => V;
+    set: (key: K, value: V) => void;
+    keys: () => Vector<K>;
+}
+
 /**
  * @public
  */