@contrail/extensions-sdk 1.0.24 → 1.0.26

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

@@ -37,6 +37,43 @@ export interface AppContext {
     };
     user?: User;
 }
+/** One active filter condition on the plan. */
+export interface PlanFilterCriterion {
+    /** The property being filtered, e.g. `gender`. */
+    slug: string;
+    label?: string;
+    propertyType?: string;
+    /**
+     * The condition, as a FilterConditionType value: `equals`, `not_equal_to`, `is_any_of`,
+     * `is_none_of`, `contains`, `starts_with`, `ends_with`, `less_than`, `greater_than`,
+     * `greater_than_or_equal`, `less_than_or_equal`, `is_empty`, `is_not_empty`, `is_in_list`,
+     * `are_any_empty`.
+     */
+    conditionType: string;
+    /** The value compared against. An array for the `is_any_of` / `is_none_of` conditions. */
+    value?: any;
+    /** How this condition joins the previous one. Absent on the first criterion. */
+    conjunction?: 'and' | 'or';
+    includeEmptyValues?: boolean;
+}
+export interface PlanSortCriterion {
+    slug: string;
+    label?: string;
+    /** A SortDirection value: `ASC`, `DESC`, `LIST_ORDER_ASC` or `LIST_ORDER_DESC`. */
+    direction: string;
+}
+/**
+ * What the user is currently looking at, beyond the rows themselves.
+ *
+ * Lets an extension scope itself the way the grid is scoped — e.g. a goals tool can hide goals for
+ * a gender the user has filtered out, rather than reporting them as unmet.
+ */
+export interface PlanViewState {
+    /** True when at least one filter condition is active. */
+    hasFilter: boolean;
+    filters: Array<PlanFilterCriterion>;
+    sorts: Array<PlanSortCriterion>;
+}
 export interface PlanContext {
     id: string;
     name: string;
@@ -46,7 +83,20 @@ export interface PlanContext {
     itemIds?: string[];
     planPlaceholders?: any[];
     filteredPlanPlaceholderIds?: string[];
+    /**
+     * Whether a filter is active.
+     *
+     * @deprecated Superseded by `viewState`, which also says *what* the filter is. Retained because
+     * existing extensions read it; equivalent to `viewState.hasFilter`.
+     */
     hasFilter: boolean;
+    /**
+     * The filter and sorts in effect **when this extension opened**.
+     *
+     * Absent on hosts that predate this field, so guard before reading. For current state — after
+     * the user has changed the filter — `await` {@link PlanApp.getViewState}.
+     */
+    viewState?: PlanViewState;
 }
 export interface BoardContext {
     id: string;

package/lib/apps/index.d.ts

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

package/lib/apps/plan.d.ts

@@ -1,10 +1,12 @@
-import { PlanContext } from './app-context';
+import { PlanContext, PlanViewState } from './app-context';
 export declare enum PlanCommand {
     ADD_ROWS = "plan:add_rows",
     SHOW_MESSAGE = "plan:show_message",
     CLEAR_SELECTED_ROWS = "plan:clear_selected_rows",
     ADD_PLACEHOLDERS = "plan:add_placeholders",
-    ADD_PLACEHOLDERS_WITH_ITEMS = "plan:add_placeholders_with_items"
+    ADD_PLACEHOLDERS_WITH_ITEMS = "plan:add_placeholders_with_items",
+    GET_PLACEHOLDERS = "plan:get_placeholders",
+    GET_VIEW_STATE = "plan:get_view_state"
 }
 /**
  * A row on a plan. Beyond the item linkage below, properties are the org-configured
@@ -23,10 +25,89 @@ export interface AddPlaceholdersOptions {
     /** Skip the undo/redo entry. Intended for bulk programmatic writes. */
     skipRecordingUndoRedo?: boolean;
 }
+/**
+ * Which rows {@link PlanApp.getPlaceholders} should return. Mirrors the plan's own data scopes.
+ *
+ * - `all` — every row on the plan, ignoring filters (the default)
+ * - `filtered` — the user's active filter applied
+ * - `displayed` — filter plus focused item family, i.e. what the grid is actually showing
+ * - `selected` — only the currently selected rows
+ */
+export declare type PlanPlaceholderScope = 'all' | 'filtered' | 'displayed' | 'selected';
+export interface GetPlaceholdersOptions {
+    /** Defaults to `all`. */
+    scope?: PlanPlaceholderScope;
+    /**
+     * Return only these property slugs, to keep the payload small on large plans.
+     * `id`, `itemFamilyId` and `itemOptionId` are always included.
+     */
+    propertySlugs?: Array<string>;
+}
 export declare class PlanApp {
     static getCurrentPlan(): PlanContext;
+    /**
+     * The plan's rows **as they were when this extension opened**.
+     *
+     * Synchronous and free, because it reads the context snapshot the host sent at startup. That
+     * snapshot is never re-sent, so it will not contain rows created since (including ones this
+     * extension created itself), edits made in the grid, or other users' changes.
+     *
+     * Use this for a one-shot read on open. For current state, `await` {@link getPlaceholders} —
+     * which also refreshes what this method returns.
+     */
     static getAllPlanPlaceholders(): any[];
+    /**
+     * The snapshot narrowed to the user's active filter — the same startup snapshot as
+     * {@link getAllPlanPlaceholders}, and equally subject to going stale.
+     *
+     * Note this filters the snapshot by the `filteredPlanPlaceholderIds` captured at startup, so it
+     * reflects the filter *at open time*. If the user changes the filter while the extension is open,
+     * use `getPlaceholders({ scope: 'filtered' })` instead.
+     */
     static getFilteredPlanPlaceholders(): any[];
+    /**
+     * The plan's rows **as they are right now**, read from the host on demand.
+     *
+     * Asynchronous, because it round-trips to the plan. Returns fully hydrated rows — property
+     * defaults applied and formulas evaluated — so it is the only way to see the real state of rows
+     * created during this session, or edits the user has made in the grid since it opened.
+     *
+     * ### How this differs from {@link getAllPlanPlaceholders}
+     *
+     * | | `getAllPlanPlaceholders()` | `getPlaceholders()` |
+     * | --- | --- | --- |
+     * | Source | startup context snapshot | live host state |
+     * | Call | synchronous | `await` |
+     * | Sees later changes | no | yes |
+     * | Scope | all, or filter-at-open-time | `all` / `filtered` / `displayed` / `selected` |
+     *
+     * ### Side effect
+     *
+     * A **full, unprojected** read (no `scope`, or `scope: 'all'`, and no `propertySlugs`) replaces
+     * the cached snapshot, so `getAllPlanPlaceholders()` returns the fresh rows afterwards. A
+     * filtered or projected read deliberately does not, since a partial result is not a valid
+     * substitute for the snapshot.
+     *
+     * Reading is always permitted, including on a view-only plan.
+     */
+    static getPlaceholders(options?: GetPlaceholdersOptions): Promise<Array<PlanPlaceholder>>;
+    /**
+     * The filter and sorts in effect **right now**.
+     *
+     * Use this to scope an extension the way the grid is scoped. If the user has filtered the plan to
+     * `gender = mens`, a goals tool can hide goals for other genders rather than reporting them as
+     * unmet, and can avoid offering to create rows that would immediately fall out of that filter.
+     *
+     * ### How this differs from the launch context
+     *
+     * `getCurrentPlan().viewState` is the state captured when the extension opened — synchronous and
+     * free, but blind to any filter change since. This method round-trips to the host for current
+     * state, and refreshes `viewState` on the cached context so the synchronous read agrees with it
+     * afterwards.
+     *
+     * Reading is always permitted, including on a view-only plan.
+     */
+    static getViewState(): Promise<PlanViewState>;
     /**
      * Creates new rows on the plan from property data, and returns them.
      *

package/lib/apps/plan.js

@@ -19,18 +19,38 @@ var PlanCommand;
     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["GET_PLACEHOLDERS"] = "plan:get_placeholders";
+    PlanCommand["GET_VIEW_STATE"] = "plan:get_view_state";
 })(PlanCommand = exports.PlanCommand || (exports.PlanCommand = {}));
 class PlanApp {
     static getCurrentPlan() {
         PlanApp.validatePlanContext();
         return (0, app_context_1.getAppContext)().appContext.plan;
     }
+    /**
+     * The plan's rows **as they were when this extension opened**.
+     *
+     * Synchronous and free, because it reads the context snapshot the host sent at startup. That
+     * snapshot is never re-sent, so it will not contain rows created since (including ones this
+     * extension created itself), edits made in the grid, or other users' changes.
+     *
+     * Use this for a one-shot read on open. For current state, `await` {@link getPlaceholders} —
+     * which also refreshes what this method returns.
+     */
     static getAllPlanPlaceholders() {
         var _a;
         PlanApp.validatePlanContext();
         const plan = PlanApp.getCurrentPlan();
         return (_a = plan === null || plan === void 0 ? void 0 : plan.planPlaceholders) !== null && _a !== void 0 ? _a : [];
     }
+    /**
+     * The snapshot narrowed to the user's active filter — the same startup snapshot as
+     * {@link getAllPlanPlaceholders}, and equally subject to going stale.
+     *
+     * Note this filters the snapshot by the `filteredPlanPlaceholderIds` captured at startup, so it
+     * reflects the filter *at open time*. If the user changes the filter while the extension is open,
+     * use `getPlaceholders({ scope: 'filtered' })` instead.
+     */
     static getFilteredPlanPlaceholders() {
         var _a;
         PlanApp.validatePlanContext();
@@ -43,6 +63,87 @@ class PlanApp {
         const filteredResults = allPlanPlaceholders.filter((placeholder) => filteredPlanPlaceholderIds.includes(placeholder.id));
         return filteredResults;
     }
+    /**
+     * The plan's rows **as they are right now**, read from the host on demand.
+     *
+     * Asynchronous, because it round-trips to the plan. Returns fully hydrated rows — property
+     * defaults applied and formulas evaluated — so it is the only way to see the real state of rows
+     * created during this session, or edits the user has made in the grid since it opened.
+     *
+     * ### How this differs from {@link getAllPlanPlaceholders}
+     *
+     * | | `getAllPlanPlaceholders()` | `getPlaceholders()` |
+     * | --- | --- | --- |
+     * | Source | startup context snapshot | live host state |
+     * | Call | synchronous | `await` |
+     * | Sees later changes | no | yes |
+     * | Scope | all, or filter-at-open-time | `all` / `filtered` / `displayed` / `selected` |
+     *
+     * ### Side effect
+     *
+     * A **full, unprojected** read (no `scope`, or `scope: 'all'`, and no `propertySlugs`) replaces
+     * the cached snapshot, so `getAllPlanPlaceholders()` returns the fresh rows afterwards. A
+     * filtered or projected read deliberately does not, since a partial result is not a valid
+     * substitute for the snapshot.
+     *
+     * Reading is always permitted, including on a view-only plan.
+     */
+    static getPlaceholders(options) {
+        var _a, _b, _c;
+        return __awaiter(this, void 0, void 0, function* () {
+            PlanApp.validatePlanContext();
+            const results = yield (0, actions_1.getExtensionActions)().sendMessageToHost({
+                command: PlanCommand.GET_PLACEHOLDERS,
+                data: { options },
+            });
+            const placeholders = (_a = PlanApp.validateAndReturnResults(results)) !== null && _a !== void 0 ? _a : [];
+            const isFullRead = (!(options === null || options === void 0 ? void 0 : options.scope) || options.scope === 'all') && !((_b = options === null || options === void 0 ? void 0 : options.propertySlugs) === null || _b === void 0 ? void 0 : _b.length);
+            if (isFullRead) {
+                // getAppContext() hands back the live singleton, so this updates what the sync getters see.
+                const plan = (_c = (0, app_context_1.getAppContext)().appContext) === null || _c === void 0 ? void 0 : _c.plan;
+                if (plan) {
+                    plan.planPlaceholders = placeholders;
+                }
+            }
+            return placeholders;
+        });
+    }
+    /**
+     * The filter and sorts in effect **right now**.
+     *
+     * Use this to scope an extension the way the grid is scoped. If the user has filtered the plan to
+     * `gender = mens`, a goals tool can hide goals for other genders rather than reporting them as
+     * unmet, and can avoid offering to create rows that would immediately fall out of that filter.
+     *
+     * ### How this differs from the launch context
+     *
+     * `getCurrentPlan().viewState` is the state captured when the extension opened — synchronous and
+     * free, but blind to any filter change since. This method round-trips to the host for current
+     * state, and refreshes `viewState` on the cached context so the synchronous read agrees with it
+     * afterwards.
+     *
+     * Reading is always permitted, including on a view-only plan.
+     */
+    static getViewState() {
+        var _a, _b;
+        return __awaiter(this, void 0, void 0, function* () {
+            PlanApp.validatePlanContext();
+            const results = yield (0, actions_1.getExtensionActions)().sendMessageToHost({
+                command: PlanCommand.GET_VIEW_STATE,
+            });
+            const viewState = (_a = PlanApp.validateAndReturnResults(results)) !== null && _a !== void 0 ? _a : {
+                hasFilter: false,
+                filters: [],
+                sorts: [],
+            };
+            // getAppContext() hands back the live singleton, so this updates what getCurrentPlan() sees.
+            const plan = (_b = (0, app_context_1.getAppContext)().appContext) === null || _b === void 0 ? void 0 : _b.plan;
+            if (plan) {
+                plan.viewState = viewState;
+            }
+            return viewState;
+        });
+    }
     /**
      * Creates new rows on the plan from property data, and returns them.
      *

package/package.json

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