@contrail/extensions-sdk 1.0.28 → 1.0.30

package/lib/apps/boards.d.ts

@@ -8,7 +8,8 @@ export declare enum BoardCommand {
     RECOLOR_IMAGES = "board:recolor_images",
     ADD_CONTENT_TO_ENTITY_FROM_ELEMENTS = "board:add_content_to_entity_from_elements",
     ADD_FRAMES_FROM_TEMPLATE = "board:add_frames_from_template",
-    ADD_ITEMS_TO_CLIPBOARD = "board:add_items_to_clipboard"
+    ADD_ITEMS_TO_CLIPBOARD = "board:add_items_to_clipboard",
+    COMPOSE_CONTENT = "board:compose_content"
 }
 /** Payload for bulk-add items to clipboard (Board and Showcase). */
 export interface ClipboardItemsPayload {
@@ -17,6 +18,70 @@ export interface ClipboardItemsPayload {
         projectItemId?: string | null;
     }>;
 }
+/** One image in a composition, placed in fractions of the output box. */
+export interface ComposeContentLayer {
+    /**
+     * The content to draw. The host resolves it to an image, so no URL is needed - and none can
+     * expire between planning the layout and composing it.
+     *
+     * Supply this or {@link fileId}, not both.
+     */
+    contentId?: string;
+    /**
+     * A file to draw, for images that exist as files without a content wrapper - the output of a
+     * background-removal operation, for instance, which returns a file id.
+     *
+     * Supply this or {@link contentId}, not both.
+     */
+    fileId?: string;
+    /**
+     * Top-left corner as a fraction of the composition box, so `{x: 0.5, y: 0}` is the top middle.
+     *
+     * Fractions rather than pixels: the layout is then independent of whatever size the extension
+     * previewed it at, and the same plan can be reused at any output resolution.
+     */
+    position: {
+        x: number;
+        y: number;
+    };
+    /** Size as a fraction of the composition box. `{width: 1, height: 1}` fills it. */
+    size: {
+        width: number;
+        height: number;
+    };
+    /** Degrees clockwise about the layer's centre. */
+    rotation?: number;
+    /** 0-1. Defaults to fully opaque. */
+    opacity?: number;
+}
+export interface ComposeContentRequest {
+    /** Drawn back to front: the first layer is behind, the last on top. */
+    layers: Array<ComposeContentLayer>;
+    /**
+     * What the new content is filed against, e.g. `item:<id>`.
+     *
+     * Required: content cannot be created free-floating - the platform derives its access policies
+     * from the holder.
+     */
+    contentHolderReference: string;
+    /** Output size in pixels. The host derives one from the source images when omitted. */
+    outputSize?: {
+        width: number;
+        height: number;
+    };
+    /** Defaults to transparent, which is usually what a composed pack shot wants. */
+    backgroundColor?: string;
+    fileName?: string;
+}
+export interface ComposeContentResult {
+    contentId: string;
+    primaryFileId?: string;
+    primaryFileUrl?: string;
+    size: {
+        width: number;
+        height: number;
+    };
+}
 export interface BoardDocumentElement extends DocumentElement {
     [key: string]: any;
 }
@@ -59,6 +124,28 @@ export declare class BoardsApp {
     static getElements(criteria: object): Promise<Array<DocumentElement>>;
     /** Creates new content from a set of elements and assigns to an entity (item, etc) as a viewable */
     static createNewContentAndAssignToEntity(assignmentOptions: any, entity: any, elements: Array<DocumentElement>): Promise<Array<DocumentElement>>;
+    /**
+     * Composes several contents into one new image, and returns it as a new content.
+     *
+     * The extension supplies a layout - which content goes where, at what size - and the board
+     * rasterises it with the same renderer its own image export uses. Nothing is added to the
+     * board: the elements exist only for the duration of the render.
+     *
+     * This is the way to build a composed image from an extension. Reading the source images into
+     * a canvas the extension owns would taint it and make the export throw, because the image
+     * files are cross-origin.
+     *
+     * ```ts
+     * const composed = await BoardsApp.composeContent({
+     *   layers: [
+     *     { contentId: 'c1', position: { x: 0, y: 0 }, size: { width: 0.6, height: 0.6 } },
+     *     { contentId: 'c2', position: { x: 0.4, y: 0.4 }, size: { width: 0.6, height: 0.6 } },
+     *   ],
+     *   contentHolderReference: `item:${setItem.id}`,
+     * });
+     * ```
+     */
+    static composeContent(request: ComposeContentRequest): Promise<ComposeContentResult>;
     static recolorImages(imageElements: Array<DocumentElement>, hexCode: string, hexMap?: {}): Promise<Array<DocumentElement>>;
     /** Request the host to bulk-add items to the user's clipboard. */
     static addItemsToClipboard(clipboardItems: Array<{

package/lib/apps/boards.js

@@ -22,6 +22,7 @@ var BoardCommand;
     BoardCommand["ADD_CONTENT_TO_ENTITY_FROM_ELEMENTS"] = "board:add_content_to_entity_from_elements";
     BoardCommand["ADD_FRAMES_FROM_TEMPLATE"] = "board:add_frames_from_template";
     BoardCommand["ADD_ITEMS_TO_CLIPBOARD"] = "board:add_items_to_clipboard";
+    BoardCommand["COMPOSE_CONTENT"] = "board:compose_content";
 })(BoardCommand = exports.BoardCommand || (exports.BoardCommand = {}));
 class BoardsApp {
     static getCurrentBoard() {
@@ -92,6 +93,48 @@ class BoardsApp {
             return this.validateAndReturnResults(results);
         });
     }
+    /**
+     * Composes several contents into one new image, and returns it as a new content.
+     *
+     * The extension supplies a layout - which content goes where, at what size - and the board
+     * rasterises it with the same renderer its own image export uses. Nothing is added to the
+     * board: the elements exist only for the duration of the render.
+     *
+     * This is the way to build a composed image from an extension. Reading the source images into
+     * a canvas the extension owns would taint it and make the export throw, because the image
+     * files are cross-origin.
+     *
+     * ```ts
+     * const composed = await BoardsApp.composeContent({
+     *   layers: [
+     *     { contentId: 'c1', position: { x: 0, y: 0 }, size: { width: 0.6, height: 0.6 } },
+     *     { contentId: 'c2', position: { x: 0.4, y: 0.4 }, size: { width: 0.6, height: 0.6 } },
+     *   ],
+     *   contentHolderReference: `item:${setItem.id}`,
+     * });
+     * ```
+     */
+    static composeContent(request) {
+        var _a;
+        return __awaiter(this, void 0, void 0, function* () {
+            BoardsApp.validateBoardContext();
+            if (!((_a = request === null || request === void 0 ? void 0 : request.layers) === null || _a === void 0 ? void 0 : _a.length)) {
+                throw new Error('composeContent requires at least one layer.');
+            }
+            if (!(request === null || request === void 0 ? void 0 : request.contentHolderReference)) {
+                throw new Error('composeContent requires a contentHolderReference, e.g. `item:<id>`.');
+            }
+            const unsourced = request.layers.findIndex((layer) => !(layer === null || layer === void 0 ? void 0 : layer.contentId) && !(layer === null || layer === void 0 ? void 0 : layer.fileId));
+            if (unsourced >= 0) {
+                throw new Error(`composeContent layer ${unsourced} needs either a contentId or a fileId.`);
+            }
+            const results = yield (0, actions_1.getExtensionActions)().sendMessageToHost({
+                command: BoardCommand.COMPOSE_CONTENT,
+                data: request,
+            });
+            return this.validateAndReturnResults(results);
+        });
+    }
     static recolorImages(imageElements, hexCode, hexMap = {}) {
         return __awaiter(this, void 0, void 0, function* () {
             BoardsApp.validateBoardContext();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contrail/extensions-sdk",
-  "version": "1.0.28",
+  "version": "1.0.30",
   "description": "Client library for interfacing with VibeIQ's services and apps from an extension.",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",