@contrail/extensions-sdk 1.0.34 → 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contrail/extensions-sdk",
-  "version": "1.0.34",
+  "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",