@contrail/extensions-sdk 1.0.23 → 1.0.24

package/lib/apps/boards.d.ts

@@ -10,6 +10,7 @@ export declare enum BoardCommand {
     ADD_FRAMES_FROM_TEMPLATE = "board:add_frames_from_template",
     ADD_ITEMS_TO_CLIPBOARD = "board:add_items_to_clipboard"
 }
+/** Payload for bulk-add items to clipboard (Board and Showcase). */
 export interface ClipboardItemsPayload {
     clipboardItems: Array<{
         itemId: string;
@@ -56,8 +57,10 @@ export declare class BoardsApp {
     static deleteElements(elements: Array<BoardDocumentElement>): void;
     static modifyElements(changeObjects: Array<BoardDocumentElementChanges>): void;
     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>>;
     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<{
         itemId: string;
         projectItemId?: string | null;

package/lib/apps/boards.js

@@ -76,6 +76,7 @@ class BoardsApp {
             return this.validateAndReturnResults(results);
         });
     }
+    /** Creates new content from a set of elements and assigns to an entity (item, etc) as a viewable */
     static createNewContentAndAssignToEntity(assignmentOptions, entity, elements) {
         return __awaiter(this, void 0, void 0, function* () {
             BoardsApp.validateBoardContext();
@@ -101,6 +102,7 @@ class BoardsApp {
             return this.validateAndReturnResults(results);
         });
     }
+    /** Request the host to bulk-add items to the user's clipboard. */
     static addItemsToClipboard(clipboardItems) {
         BoardsApp.validateBoardContext();
         if (clipboardItems === null || clipboardItems === void 0 ? void 0 : clipboardItems.length) {

package/lib/apps/plan.d.ts

@@ -2,14 +2,68 @@ import { PlanContext } from './app-context';
 export declare enum PlanCommand {
     ADD_ROWS = "plan:add_rows",
     SHOW_MESSAGE = "plan:show_message",
-    CLEAR_SELECTED_ROWS = "plan:clear_selected_rows"
+    CLEAR_SELECTED_ROWS = "plan:clear_selected_rows",
+    ADD_PLACEHOLDERS = "plan:add_placeholders",
+    ADD_PLACEHOLDERS_WITH_ITEMS = "plan:add_placeholders_with_items"
+}
+/**
+ * A row on a plan. Beyond the item linkage below, properties are the org-configured
+ * type-property slugs of the `plan-placeholder` type (`gender`, `targetVolume`, ...).
+ */
+export interface PlanPlaceholder {
+    id?: string;
+    itemFamilyId?: string;
+    itemOptionId?: string;
+    [key: string]: any;
+}
+/** Optional placement and history behavior for the add-placeholder commands. */
+export interface AddPlaceholdersOptions {
+    /** Row index to insert at. Omit to append to the end of the plan. */
+    targetRowIndex?: number;
+    /** Skip the undo/redo entry. Intended for bulk programmatic writes. */
+    skipRecordingUndoRedo?: boolean;
 }
 export declare class PlanApp {
     static getCurrentPlan(): PlanContext;
     static getAllPlanPlaceholders(): any[];
     static getFilteredPlanPlaceholders(): any[];
+    /**
+     * Creates new rows on the plan from property data, and returns them.
+     *
+     * The rows are created through the plan's own row-creation path, so they appear in the grid
+     * immediately, are undoable, and are broadcast to other users viewing the plan. The property
+     * values supplied on each placeholder are set on the created row.
+     *
+     * Any placeholder carrying an `itemFamilyId`/`itemOptionId` is routed through item assignment,
+     * exactly as {@link addPlaceholdersWithItems} would handle it.
+     *
+     * Note that {@link getAllPlanPlaceholders} continues to return the snapshot taken when the
+     * extension was opened — it will not include these rows. Use the returned array instead.
+     */
+    static addPlaceholders(placeholders: Array<PlanPlaceholder>, options?: AddPlaceholdersOptions): Promise<Array<PlanPlaceholder>>;
+    /**
+     * Creates new rows on the plan for existing items, and returns them.
+     *
+     * Each placeholder must carry an `itemFamilyId` or `itemOptionId`. The plan resolves the item,
+     * creates the project item, and applies carryover — the behavior the deprecated
+     * {@link addRows} provides, under a name that says what it does.
+     *
+     * To create rows that are not backed by an item, use {@link addPlaceholders}.
+     */
+    static addPlaceholdersWithItems(placeholders: Array<PlanPlaceholder>, options?: AddPlaceholdersOptions): Promise<Array<PlanPlaceholder>>;
+    /**
+     * Adds rows to the plan for existing items.
+     *
+     * @deprecated The name is misleading: this only adds rows for existing **items**, and property
+     * values on a placeholder without an `itemFamilyId`/`itemOptionId` are silently discarded. It
+     * also returns nothing, so the created rows are not available to the caller.
+     *
+     * Use {@link addPlaceholdersWithItems} for item-backed rows, or {@link addPlaceholders} to
+     * create rows from property data. Retained for existing extensions.
+     */
     static addRows(collectionElements: Array<any>): void;
     static clearSelectedRows(): void;
     static showMessage(message: string): void;
     private static validatePlanContext;
+    private static validateAndReturnResults;
 }

package/lib/apps/plan.js

@@ -1,4 +1,13 @@
 "use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.PlanApp = exports.PlanCommand = void 0;
 const actions_1 = require("../actions/actions");
@@ -8,6 +17,8 @@ var PlanCommand;
     PlanCommand["ADD_ROWS"] = "plan:add_rows";
     PlanCommand["SHOW_MESSAGE"] = "plan:show_message";
     PlanCommand["CLEAR_SELECTED_ROWS"] = "plan:clear_selected_rows";
+    PlanCommand["ADD_PLACEHOLDERS"] = "plan:add_placeholders";
+    PlanCommand["ADD_PLACEHOLDERS_WITH_ITEMS"] = "plan:add_placeholders_with_items";
 })(PlanCommand = exports.PlanCommand || (exports.PlanCommand = {}));
 class PlanApp {
     static getCurrentPlan() {
@@ -32,6 +43,64 @@ class PlanApp {
         const filteredResults = allPlanPlaceholders.filter((placeholder) => filteredPlanPlaceholderIds.includes(placeholder.id));
         return filteredResults;
     }
+    /**
+     * Creates new rows on the plan from property data, and returns them.
+     *
+     * The rows are created through the plan's own row-creation path, so they appear in the grid
+     * immediately, are undoable, and are broadcast to other users viewing the plan. The property
+     * values supplied on each placeholder are set on the created row.
+     *
+     * Any placeholder carrying an `itemFamilyId`/`itemOptionId` is routed through item assignment,
+     * exactly as {@link addPlaceholdersWithItems} would handle it.
+     *
+     * Note that {@link getAllPlanPlaceholders} continues to return the snapshot taken when the
+     * extension was opened — it will not include these rows. Use the returned array instead.
+     */
+    static addPlaceholders(placeholders, options) {
+        return __awaiter(this, void 0, void 0, function* () {
+            PlanApp.validatePlanContext();
+            if (!(placeholders === null || placeholders === void 0 ? void 0 : placeholders.length)) {
+                return [];
+            }
+            const results = yield (0, actions_1.getExtensionActions)().sendMessageToHost({
+                command: PlanCommand.ADD_PLACEHOLDERS,
+                data: { placeholders, options },
+            });
+            return PlanApp.validateAndReturnResults(results);
+        });
+    }
+    /**
+     * Creates new rows on the plan for existing items, and returns them.
+     *
+     * Each placeholder must carry an `itemFamilyId` or `itemOptionId`. The plan resolves the item,
+     * creates the project item, and applies carryover — the behavior the deprecated
+     * {@link addRows} provides, under a name that says what it does.
+     *
+     * To create rows that are not backed by an item, use {@link addPlaceholders}.
+     */
+    static addPlaceholdersWithItems(placeholders, options) {
+        return __awaiter(this, void 0, void 0, function* () {
+            PlanApp.validatePlanContext();
+            if (!(placeholders === null || placeholders === void 0 ? void 0 : placeholders.length)) {
+                return [];
+            }
+            const results = yield (0, actions_1.getExtensionActions)().sendMessageToHost({
+                command: PlanCommand.ADD_PLACEHOLDERS_WITH_ITEMS,
+                data: { placeholders, options },
+            });
+            return PlanApp.validateAndReturnResults(results);
+        });
+    }
+    /**
+     * Adds rows to the plan for existing items.
+     *
+     * @deprecated The name is misleading: this only adds rows for existing **items**, and property
+     * values on a placeholder without an `itemFamilyId`/`itemOptionId` are silently discarded. It
+     * also returns nothing, so the created rows are not available to the caller.
+     *
+     * Use {@link addPlaceholdersWithItems} for item-backed rows, or {@link addPlaceholders} to
+     * create rows from property data. Retained for existing extensions.
+     */
     static addRows(collectionElements) {
         PlanApp.validatePlanContext();
         if (collectionElements === null || collectionElements === void 0 ? void 0 : collectionElements.length) {
@@ -50,10 +119,18 @@ class PlanApp {
         actions.sendMessageToHost({ command: PlanCommand.SHOW_MESSAGE, data: message });
     }
     static validatePlanContext() {
+        var _a, _b;
         const context = (0, app_context_1.getAppContext)();
-        if (context.appContext.vibeIQApp !== app_context_1.VibeIQAppType.PLAN || !context.appContext.plan) {
+        if (((_a = context.appContext) === null || _a === void 0 ? void 0 : _a.vibeIQApp) !== app_context_1.VibeIQAppType.PLAN || !((_b = context.appContext) === null || _b === void 0 ? void 0 : _b.plan)) {
             throw new Error('App extension has not been initialized with Plan context.');
         }
     }
+    static validateAndReturnResults(results) {
+        var _a;
+        if (!results.success) {
+            throw new Error((_a = results.error) !== null && _a !== void 0 ? _a : 'App operation failed.');
+        }
+        return results.data;
+    }
 }
 exports.PlanApp = PlanApp;

package/lib/apps/showcase.d.ts

@@ -15,10 +15,12 @@ export interface ShowcaseDocumentElementChanges {
 }
 export interface AddElementsToShowcasePayload {
     elements: Array<ShowcaseDocumentElement>;
+    /** If omitted, elements are added to the currently active frame. */
     frameId?: string;
 }
 export interface ModifyElementsInShowcasePayload {
     changeObjects: Array<ShowcaseDocumentElementChanges>;
+    /** If omitted, elements are modified on the currently active frame. */
     frameId?: string;
 }
 export interface AddCanvasFrameToShowcasePayload {
@@ -40,11 +42,21 @@ export declare type NavigateToFrameInShowcasePayload = {
 };
 export interface NavigateToFrameResult {
     frameId: string;
+    /** 0-based position of the frame within the showcase's frames. */
     frameIndex: number;
 }
 export declare class ShowcaseApp {
     static getCurrentShowcase(): any;
+    /**
+     * Adds elements to a frame in the showcase.
+     * If `frameId` is omitted, elements are added to the currently active frame.
+     * Otherwise, elements are added to the frame matching `frameId`.
+     */
     static addElements(elements: Array<ShowcaseDocumentElement>, frameId?: string): void;
+    /**
+     * Adds a new canvas frame (lineboard page) containing the given elements
+     * and returns the created frame.
+     */
     static addCanvasFrame(elements: Array<ShowcaseDocumentElement>, frameOptions?: {
         name?: string;
         size?: {
@@ -52,8 +64,19 @@ export declare class ShowcaseApp {
             height: number;
         };
     }): Promise<any>;
+    /**
+     * Modifies existing elements in a frame in the showcase.
+     * If `frameId` is omitted, elements are modified on the currently active frame.
+     * Otherwise, elements are modified on the frame matching `frameId`.
+     */
     static modifyElements(changeObjects: Array<ShowcaseDocumentElementChanges>, frameId?: string): void;
+    /**
+     * Changes the showcase's current (visible) frame and resolves with the frame that is now active.
+     * Target the frame either by `frameId` or by its 0-based `frameIndex` within `showcase.frames`.
+     * The returned promise rejects if the id or index does not match a frame.
+     */
     static navigateToFrame(target: NavigateToFrameInShowcasePayload): Promise<NavigateToFrameResult>;
+    /** Request the host to bulk-add items to the user's clipboard. */
     static addItemsToClipboard(clipboardItems: Array<{
         itemId: string;
         projectItemId?: string | null;

package/lib/apps/showcase.js

@@ -26,6 +26,11 @@ class ShowcaseApp {
         ShowcaseApp.validateShowcaseContext();
         return (_a = (0, app_context_1.getAppContext)().appContext) === null || _a === void 0 ? void 0 : _a.showcase;
     }
+    /**
+     * Adds elements to a frame in the showcase.
+     * If `frameId` is omitted, elements are added to the currently active frame.
+     * Otherwise, elements are added to the frame matching `frameId`.
+     */
     static addElements(elements, frameId) {
         ShowcaseApp.validateShowcaseContext();
         if (elements === null || elements === void 0 ? void 0 : elements.length) {
@@ -33,6 +38,10 @@ class ShowcaseApp {
             (0, actions_1.getExtensionActions)().sendMessageToHost({ command: ShowcaseCommand.ADD_ELEMENTS, data });
         }
     }
+    /**
+     * Adds a new canvas frame (lineboard page) containing the given elements
+     * and returns the created frame.
+     */
     static addCanvasFrame(elements, frameOptions) {
         return __awaiter(this, void 0, void 0, function* () {
             ShowcaseApp.validateShowcaseContext();
@@ -46,6 +55,11 @@ class ShowcaseApp {
             }
         });
     }
+    /**
+     * Modifies existing elements in a frame in the showcase.
+     * If `frameId` is omitted, elements are modified on the currently active frame.
+     * Otherwise, elements are modified on the frame matching `frameId`.
+     */
     static modifyElements(changeObjects, frameId) {
         ShowcaseApp.validateShowcaseContext();
         if (changeObjects === null || changeObjects === void 0 ? void 0 : changeObjects.length) {
@@ -53,6 +67,11 @@ class ShowcaseApp {
             (0, actions_1.getExtensionActions)().sendMessageToHost({ command: ShowcaseCommand.MODIFY_ELEMENTS, data });
         }
     }
+    /**
+     * Changes the showcase's current (visible) frame and resolves with the frame that is now active.
+     * Target the frame either by `frameId` or by its 0-based `frameIndex` within `showcase.frames`.
+     * The returned promise rejects if the id or index does not match a frame.
+     */
     static navigateToFrame(target) {
         return __awaiter(this, void 0, void 0, function* () {
             ShowcaseApp.validateShowcaseContext();
@@ -66,6 +85,7 @@ class ShowcaseApp {
             return ShowcaseApp.validateAndReturnResults(results);
         });
     }
+    /** Request the host to bulk-add items to the user's clipboard. */
     static addItemsToClipboard(clipboardItems) {
         ShowcaseApp.validateShowcaseContext();
         if (clipboardItems === null || clipboardItems === void 0 ? void 0 : clipboardItems.length) {

package/package.json

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

package/lib/extensions/connection-timeout.d.ts

@@ -1,7 +0,0 @@
-export declare class ExtensionConnectionTimeoutError extends Error {
-    constructor(timeoutMs: number);
-}
-export declare class HostConnectionTimeoutError extends Error {
-    constructor(timeoutMs: number);
-}
-export declare function withConnectionTimeout<T>(promise: Promise<T>, timeoutMs: number, createError: () => Error): Promise<T>;

package/lib/extensions/connection-timeout.js

@@ -1,34 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.withConnectionTimeout = exports.HostConnectionTimeoutError = exports.ExtensionConnectionTimeoutError = void 0;
-class ExtensionConnectionTimeoutError extends Error {
-    constructor(timeoutMs) {
-        super(`Extension connection to host timed out after ${timeoutMs}ms. Ensure the host calls registerHostWithAppExtension after the extension iframe has loaded.`);
-        this.name = 'ExtensionConnectionTimeoutError';
-        Object.setPrototypeOf(this, ExtensionConnectionTimeoutError.prototype);
-    }
-}
-exports.ExtensionConnectionTimeoutError = ExtensionConnectionTimeoutError;
-class HostConnectionTimeoutError extends Error {
-    constructor(timeoutMs) {
-        super(`Host connection to extension timed out after ${timeoutMs}ms. Ensure the extension calls registerAppExtension() on load and the iframe has loaded.`);
-        this.name = 'HostConnectionTimeoutError';
-        Object.setPrototypeOf(this, HostConnectionTimeoutError.prototype);
-    }
-}
-exports.HostConnectionTimeoutError = HostConnectionTimeoutError;
-function withConnectionTimeout(promise, timeoutMs, createError) {
-    return new Promise((resolve, reject) => {
-        const timer = setTimeout(() => reject(createError()), timeoutMs);
-        promise
-            .then((value) => {
-            clearTimeout(timer);
-            resolve(value);
-        })
-            .catch((err) => {
-            clearTimeout(timer);
-            reject(err);
-        });
-    });
-}
-exports.withConnectionTimeout = withConnectionTimeout;