@contrail/extensions-sdk 1.0.33 → 1.0.35

package/lib/apps/app-context.d.ts

@@ -1,4 +1,5 @@
 import { User } from '@contrail/entity-types';
+import { DocumentGenerationIntent } from './document-generation';
 interface Document {
     id: string;
     name: string;
@@ -122,6 +123,11 @@ export interface BoardContext {
     rootWorkspaceId?: string;
     typeId?: string;
     workspaceId?: string;
+    /**
+     * Why the host opened this extension, when it opened it against generated
+     * content. Absent on an ordinary launch from a menu.
+     */
+    documentGenerationIntent?: DocumentGenerationIntent;
 }
 export interface ShowcaseContext {
     id: string;

package/lib/apps/document-generation.d.ts

@@ -0,0 +1,107 @@
+/**
+ * The contract for an extension that generates board content.
+ *
+ * Any extension that stamps `documentGenerationConfigId` onto elements is
+ * claiming a block of someone's board, and the board offers Refresh, Configure,
+ * Select all and Details against that claim. Those only work if the extension
+ * holds up its end, which is this file.
+ *
+ * 1. Write a `document-generation-config` shaped like {@link DocumentGenerationConfigRecord}
+ *    - `kind: 'app'` at minimum, or the board treats it as the built-in
+ *      generator's and that editor will fail on the missing fields.
+ * 2. Stamp that config's id onto EVERY element you create, and scope every read
+ *    and delete to elements carrying it. Elements without the stamp are someone
+ *    else's.
+ * 3. Read {@link DocumentGenerationApp.getIntent} on launch and honour the mode.
+ *    `regenerate` means: same spec, latest data, no questions asked.
+ * 4. When `headless` is true, render nothing and wait for nobody. Finish with
+ *    {@link DocumentGenerationApp.complete} or {@link DocumentGenerationApp.fail} -
+ *    the host has no other way to tell success from an extension that gave up.
+ * 5. Declare `supportsDocumentGeneration` in app.yml, and
+ *    `supportsHeadlessRegenerate` if you honour rule 4.
+ */
+export declare const GENERATION_COMMAND: {
+    readonly progress: "generation:progress";
+    readonly complete: "generation:complete";
+    readonly failed: "generation:failed";
+};
+export declare type DocumentGenerationMode = 'create' | 'edit' | 'regenerate';
+export interface DocumentGenerationIntent {
+    mode: DocumentGenerationMode;
+    /** Absent for `create`. */
+    documentGenerationConfigId?: string;
+    /** True when no UI will be seen and no user is waiting. */
+    headless?: boolean;
+}
+/** One row of the board's details panel. The host renders these verbatim. */
+export interface GenerationSummaryRow {
+    label: string;
+    value: string;
+}
+export interface GenerationSource {
+    /** An entity name the platform can read, e.g. `assortment`. */
+    kind: string;
+    id: string;
+    label?: string;
+}
+export interface GenerationReference {
+    appIdentifier: string;
+    extensionIdentifier: string;
+    /**
+     * Which of the app's generators made this, when it has more than one.
+     * Names the generator, never its output - the same extension may produce
+     * frames of cards, a chart or a table.
+     */
+    generatorId?: string;
+    generatorVersion?: string;
+}
+/**
+ * The fields the board reads off a `document-generation-config`. Anything else -
+ * `spec` in particular - is the extension's own and the host never interprets it.
+ */
+export interface DocumentGenerationConfigRecord {
+    id?: string;
+    /** `app` for anything an installed app generated; `native` is the built-in generator. */
+    kind: 'app';
+    name: string;
+    documentId: string;
+    generatorRef: GenerationReference;
+    /** Drives the source links and the staleness check. */
+    sources: GenerationSource[];
+    /** Opaque to the host: whatever the layout needs to run again. */
+    spec: unknown;
+    specVersion: number;
+    /** What the details panel shows. Written by the extension; nothing else can. */
+    summary?: GenerationSummaryRow[];
+    /** What the board may offer against this content. `headlessRefresh` enables Refresh. */
+    capabilities?: {
+        headlessRefresh?: boolean;
+    };
+    lastGeneratedOn?: string;
+    anchor?: {
+        x: number;
+        y: number;
+    };
+}
+export interface GenerationResult {
+    created: number;
+    updated: number;
+    deleted: number;
+    unchanged: number;
+    /**
+     * False when the run replaced its elements wholesale rather than diffing, so
+     * the counts describe a rewrite. Defaults to true.
+     */
+    isDiff?: boolean;
+}
+export declare class DocumentGenerationApp {
+    /** Why the host opened this extension. Absent when it was opened from a menu. */
+    static getIntent(): DocumentGenerationIntent | undefined;
+    static isHeadless(): boolean;
+    /** Optional. Gives the host something to show while a long run proceeds. */
+    static progress(message: string): void;
+    /** Required to end a headless run that succeeded. */
+    static complete(result: GenerationResult): void;
+    /** Required to end a headless run that failed. The message reaches the board. */
+    static fail(message: string): void;
+}

package/lib/apps/document-generation.js

@@ -0,0 +1,56 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DocumentGenerationApp = exports.GENERATION_COMMAND = void 0;
+const actions_1 = require("../actions/actions");
+const app_context_1 = require("./app-context");
+/**
+ * The contract for an extension that generates board content.
+ *
+ * Any extension that stamps `documentGenerationConfigId` onto elements is
+ * claiming a block of someone's board, and the board offers Refresh, Configure,
+ * Select all and Details against that claim. Those only work if the extension
+ * holds up its end, which is this file.
+ *
+ * 1. Write a `document-generation-config` shaped like {@link DocumentGenerationConfigRecord}
+ *    - `kind: 'app'` at minimum, or the board treats it as the built-in
+ *      generator's and that editor will fail on the missing fields.
+ * 2. Stamp that config's id onto EVERY element you create, and scope every read
+ *    and delete to elements carrying it. Elements without the stamp are someone
+ *    else's.
+ * 3. Read {@link DocumentGenerationApp.getIntent} on launch and honour the mode.
+ *    `regenerate` means: same spec, latest data, no questions asked.
+ * 4. When `headless` is true, render nothing and wait for nobody. Finish with
+ *    {@link DocumentGenerationApp.complete} or {@link DocumentGenerationApp.fail} -
+ *    the host has no other way to tell success from an extension that gave up.
+ * 5. Declare `supportsDocumentGeneration` in app.yml, and
+ *    `supportsHeadlessRegenerate` if you honour rule 4.
+ */
+exports.GENERATION_COMMAND = {
+    progress: 'generation:progress',
+    complete: 'generation:complete',
+    failed: 'generation:failed',
+};
+class DocumentGenerationApp {
+    /** Why the host opened this extension. Absent when it was opened from a menu. */
+    static getIntent() {
+        var _a, _b, _c;
+        return (_c = (_b = (_a = (0, app_context_1.getAppContext)()) === null || _a === void 0 ? void 0 : _a.appContext) === null || _b === void 0 ? void 0 : _b.board) === null || _c === void 0 ? void 0 : _c.documentGenerationIntent;
+    }
+    static isHeadless() {
+        var _a;
+        return ((_a = DocumentGenerationApp.getIntent()) === null || _a === void 0 ? void 0 : _a.headless) === true;
+    }
+    /** Optional. Gives the host something to show while a long run proceeds. */
+    static progress(message) {
+        (0, actions_1.getExtensionActions)().sendMessageToHost({ command: exports.GENERATION_COMMAND.progress, data: { message } });
+    }
+    /** Required to end a headless run that succeeded. */
+    static complete(result) {
+        (0, actions_1.getExtensionActions)().sendMessageToHost({ command: exports.GENERATION_COMMAND.complete, data: result });
+    }
+    /** Required to end a headless run that failed. The message reaches the board. */
+    static fail(message) {
+        (0, actions_1.getExtensionActions)().sendMessageToHost({ command: exports.GENERATION_COMMAND.failed, data: { message } });
+    }
+}
+exports.DocumentGenerationApp = DocumentGenerationApp;

package/lib/apps/index.d.ts

@@ -1,4 +1,5 @@
 export { getAppContext, AppContext, BoardContext, PlanContext, PlanFilterCriterion, PlanSortCriterion, PlanViewState, ShowcaseContext, VibeIQAppType, } from './app-context';
+export * from './document-generation';
 export * from './boards';
 export * from './plan';
 export * from './showcase';

package/lib/apps/index.js

@@ -18,6 +18,7 @@ exports.VibeIQAppType = exports.getAppContext = void 0;
 var app_context_1 = require("./app-context");
 Object.defineProperty(exports, "getAppContext", { enumerable: true, get: function () { return app_context_1.getAppContext; } });
 Object.defineProperty(exports, "VibeIQAppType", { enumerable: true, get: function () { return app_context_1.VibeIQAppType; } });
+__exportStar(require("./document-generation"), exports);
 __exportStar(require("./boards"), exports);
 __exportStar(require("./plan"), exports);
 __exportStar(require("./showcase"), exports);

package/lib/apps/plan.d.ts

@@ -8,7 +8,8 @@ export declare enum PlanCommand {
     GET_PLACEHOLDERS = "plan:get_placeholders",
     GET_VIEW_STATE = "plan:get_view_state",
     ASSIGN_ITEMS = "plan:assign_items",
-    SCROLL_TO_PLACEHOLDER = "plan:scroll_to_placeholder"
+    SCROLL_TO_PLACEHOLDER = "plan:scroll_to_placeholder",
+    UPDATE_PLACEHOLDERS = "plan:update_placeholders"
 }
 /**
  * A row on a plan. Beyond the item linkage below, properties are the org-configured
@@ -43,6 +44,45 @@ export interface PlaceholderItemAssignment {
     /** The item to assign — an item family or an item option. */
     itemId: string;
 }
+/**
+ * Edits to one existing row, keyed by property slug.
+ *
+ * Only two kinds of property can be written this way:
+ *
+ * - `isDropped` — `true` drops the row, `false` restores it.
+ * - Assortment-item properties (`forecast`, `targetVolume`, ...) — plan-placeholder properties
+ *   that also exist on the `assortment-item` type and on neither `item` nor `project-item`.
+ *
+ * Item and project-item properties are refused: edit those entities directly and the plan picks the
+ * change up through propagation.
+ *
+ * Values take the shape {@link PlanApp.getPlaceholders} returns. An object-reference or user-list
+ * property takes the referenced object (with its `id`) or `null`.
+ */
+export interface PlaceholderChange {
+    /** The row to edit. */
+    id: string;
+    changes: {
+        [propertySlug: string]: any;
+    };
+}
+export interface UpdatePlaceholdersOptions {
+    /** Skip the undo/redo entry. Intended for bulk programmatic writes. */
+    skipRecordingUndoRedo?: boolean;
+}
+/** One property edit the plan declined, and why. The row's other edits are still applied. */
+export interface RejectedPlaceholderChange {
+    placeholderId: string;
+    propertySlug: string;
+    /** Human-readable, e.g. `This value is calculated with a formula.` */
+    reason: string;
+}
+export interface UpdatePlaceholdersResult {
+    /** The edited rows as they are after the write, formulas re-evaluated. */
+    placeholders: Array<PlanPlaceholder>;
+    /** Edits refused by the row's own rules — permissions, rule sets, value validation, drop checks. */
+    rejectedChanges: Array<RejectedPlaceholderChange>;
+}
 export interface ScrollToPlaceholderOptions {
     /**
      * Also bring this column into view horizontally.
@@ -155,6 +195,32 @@ export declare class PlanApp {
      * Requires the plan to be editable.
      */
     static assignItems(assignments: Array<PlaceholderItemAssignment>): Promise<void>;
+    /**
+     * Edits existing rows: drops or restores them, and sets assortment-item properties such as
+     * forecasts. See {@link PlaceholderChange} for what can be written.
+     *
+     * Runs the same write path as a grid edit, so formulas re-evaluate, the change is undoable, it is
+     * persisted, and it is broadcast to other users. Resolves once the write has been applied, with
+     * the updated rows.
+     *
+     * Two kinds of failure are reported differently:
+     *
+     * - **Throws, and writes nothing,** when the request is wrong: a row id not on this plan, or a
+     *   property that cannot be written through this method. These are bugs in the caller.
+     * - **Rejects individual edits,** listed in `rejectedChanges`, when a row's own rules refuse them:
+     *   the property is read-only, a formula, or locked by a rule set; the value fails validation; or
+     *   the row cannot be dropped. Every other edit is applied, as a paste into the grid would be.
+     *
+     * ```ts
+     * const { rejectedChanges } = await PlanApp.updatePlaceholders([
+     *   { id: rowA, changes: { isDropped: true } },
+     *   { id: rowB, changes: { forecast: 1200 } },
+     * ]);
+     * ```
+     *
+     * Requires the plan to be editable.
+     */
+    static updatePlaceholders(placeholderChanges: Array<PlaceholderChange>, options?: UpdatePlaceholdersOptions): Promise<UpdatePlaceholdersResult>;
     /**
      * Scrolls the plan's grid so a row is in view.
      *

package/lib/apps/plan.js

@@ -23,6 +23,7 @@ var PlanCommand;
     PlanCommand["GET_VIEW_STATE"] = "plan:get_view_state";
     PlanCommand["ASSIGN_ITEMS"] = "plan:assign_items";
     PlanCommand["SCROLL_TO_PLACEHOLDER"] = "plan:scroll_to_placeholder";
+    PlanCommand["UPDATE_PLACEHOLDERS"] = "plan:update_placeholders";
 })(PlanCommand = exports.PlanCommand || (exports.PlanCommand = {}));
 class PlanApp {
     static getCurrentPlan() {
@@ -172,6 +173,44 @@ class PlanApp {
             PlanApp.validateAndReturnResults(results);
         });
     }
+    /**
+     * Edits existing rows: drops or restores them, and sets assortment-item properties such as
+     * forecasts. See {@link PlaceholderChange} for what can be written.
+     *
+     * Runs the same write path as a grid edit, so formulas re-evaluate, the change is undoable, it is
+     * persisted, and it is broadcast to other users. Resolves once the write has been applied, with
+     * the updated rows.
+     *
+     * Two kinds of failure are reported differently:
+     *
+     * - **Throws, and writes nothing,** when the request is wrong: a row id not on this plan, or a
+     *   property that cannot be written through this method. These are bugs in the caller.
+     * - **Rejects individual edits,** listed in `rejectedChanges`, when a row's own rules refuse them:
+     *   the property is read-only, a formula, or locked by a rule set; the value fails validation; or
+     *   the row cannot be dropped. Every other edit is applied, as a paste into the grid would be.
+     *
+     * ```ts
+     * const { rejectedChanges } = await PlanApp.updatePlaceholders([
+     *   { id: rowA, changes: { isDropped: true } },
+     *   { id: rowB, changes: { forecast: 1200 } },
+     * ]);
+     * ```
+     *
+     * Requires the plan to be editable.
+     */
+    static updatePlaceholders(placeholderChanges, options) {
+        return __awaiter(this, void 0, void 0, function* () {
+            PlanApp.validatePlanContext();
+            if (!(placeholderChanges === null || placeholderChanges === void 0 ? void 0 : placeholderChanges.length)) {
+                return { placeholders: [], rejectedChanges: [] };
+            }
+            const results = yield (0, actions_1.getExtensionActions)().sendMessageToHost({
+                command: PlanCommand.UPDATE_PLACEHOLDERS,
+                data: { placeholderChanges, options },
+            });
+            return PlanApp.validateAndReturnResults(results);
+        });
+    }
     /**
      * Scrolls the plan's grid so a row is in view.
      *

package/package.json

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