infaira-canvas 0.2.0 → 0.3.0

package/dist/commands/init.js

@@ -288,9 +288,15 @@ import LocalizationMessages from '../localization.json';
 // ─── Types ────────────────────────────────────────────────────────────────────
 
 export interface IActionOptions {
+  /** Parse response body as JSON before resolving. */
   json?: boolean;
+  /** Stable identifier for cancellation. Required when cancelPrevious is set. */
   key?: string;
+  /** When true and "key" is also set, any prior in-flight call sharing the
+   *  same key is cancelled (its Promise resolves to null). Use for live-filter
+   *  widgets where only the latest call result should land in state. */
   cancelPrevious?: boolean;
+  /** Skip the 100ms batch window and fire immediately. */
   executeImmediately?: boolean;
 }
 
@@ -316,13 +322,23 @@ export interface IContextProvider {
    *  - executeAction('Buildings', 'List', { siteId })      → ICan native
    *  - executeAction('mythos:Inventory', 'UpdateStock', p) → Mythos engine
    *  The 'mythos:' prefix is the only difference at the call site; the
-   *  ICan backend routes the call appropriately. */
+   *  ICan backend routes the call appropriately.
+   *  options.cancelPrevious + options.key: when set, an in-flight call with
+   *  the same key is cancelled (resolves null) and the new call wins. */
   executeAction(model: string, action: string, parameters: unknown, options?: IActionOptions): Promise<unknown>;
   executeService(app: string, service: string, parameters: unknown, options?: IActionOptions): Promise<unknown>;
   /** List Mythos actions callable via executeAction('mythos:...', ...).
    *  Optional — present only when MYTHOS_BASE_URL is configured on the ICan
    *  backend. Treat absence as "Mythos integration disabled". */
   listMythosActions?(): Promise<IMythosAction[]>;
+  /** Fire a Mythos external event with an optional payload. */
+  fireMythosEvent?(eventType: string, payload?: Record<string, unknown>): Promise<void>;
+  /** Build an IDataFunction over a Mythos collection for DataList/DataTable. */
+  fromMythosCollection?(model: string, collection: string): (
+    max: number,
+    lastPageToken: string,
+    args?: { search?: string } & Record<string, unknown>,
+  ) => Promise<{ items: Array<Record<string, unknown>>; pageToken: string }>;
   fireEvent(eventId: string): Promise<void>;
   hasAppRole(app: string, role: string): boolean;
   themeName?: string;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "infaira-canvas",
-  "version": "0.2.0",
-  "description": "InfAIra Canvas CLI — scaffold widgets that talk to ICan and Mythos.",
+  "version": "0.3.0",
+  "description": "InfAIra Canvas CLI — scaffold widgets that talk to ICan and Mythos (actions, events, public portals, paginated collections).",
   "keywords": [
     "infaira",
     "ican",

package/templates/ICan-Widget-Development-Guide.md

@@ -38,8 +38,10 @@ In the portal, `icanContext` is always defined — the widget is never mounted u
 | `language` | `string` | Active language code, e.g. `'en'` |
 | `themeName` | `string \| undefined` | e.g. `'Dark'`, `'Glass Light'` |
 | `themeType` | `'Dark' \| 'Light' \| 'Glass-Dark' \| 'Glass-Light' \| undefined` | Structured theme type for chart colours |
-| `executeAction` | `(model, action, params?, options?) => Promise<unknown>` | Call an action. ICan native by default; prefix `model` with `mythos:` to route to the Mythos engine instead. |
+| `executeAction` | `(model, action, params?, options?) => Promise<unknown>` | Call an action. ICan native by default; prefix `model` with `mythos:` to route to the Mythos engine instead. `options.cancelPrevious` + `options.key` to deduplicate live-filter calls. |
 | `listMythosActions` | `() => Promise<IMythosAction[]> \| undefined` | List Mythos actions callable from this widget. Present only when the ICan backend has `MYTHOS_BASE_URL` configured. |
+| `fireMythosEvent` | `(event_type, payload?) => Promise<void> \| undefined` | Fire a named external event into the Mythos bus. Triggers any matching Mythos event handlers. |
+| `fromMythosCollection` | `(model, collection) => IDataFunction \| undefined` | Build a paginated data source over a Mythos collection — drops into DataList / DataTable. |
 | `fireEvent` | `(eventId) => Promise<void>` | Trigger a portal event |
 | `hasAppRole` | `(app, role) => boolean` | Check if the user has a role |
 | `$L` | `(code, params?) => string` | Translate a localisation key |
@@ -125,6 +127,61 @@ const handleRun = async () => {
 
 A working reference widget lives at `Widgets/ICan widgets/mythosdemo/` — pick an action, fill params, run, render the response.
 
+### Cancelling stale calls (`options.cancelPrevious`)
+
+Widgets that fire on every keystroke — search bars, live filters — end up racing requests against themselves. Use `cancelPrevious` + `key` to ensure only the latest call's result lands:
+
+```tsx
+const onSearch = (text: string) => {
+  icanContext.executeAction(
+    'mythos:Inventory',
+    'Search',
+    { q: text },
+    { cancelPrevious: true, key: 'inventory-search' },
+  ).then((res) => {
+    if (res !== null) setResults(res);   // null means this call was cancelled
+  });
+};
+```
+
+Calls with the same `key` are tracked; when a newer one is issued, older ones resolve to `null` instead of delivering stale data into your state.
+
+### Firing Mythos events
+
+`icanContext.fireMythosEvent('order_placed', { id: 4821 })` publishes the event into Mythos's bus. Any Mythos workflow with a matching External Event trigger fires. Useful for widget → workflow dispatch where you don't need a return value.
+
+```tsx
+await icanContext.fireMythosEvent?.('user_logged_in', { userId });
+```
+
+Optional — `fireMythosEvent` is `undefined` when Mythos integration is disabled. Guard with `?.()`.
+
+### Reading from a Mythos collection
+
+`icanContext.fromMythosCollection(model, collection)` returns a function with the same shape ICan's DataList / DataTable already accept:
+
+```tsx
+const fetchPage = icanContext.fromMythosCollection!('Inventory', 'items');
+
+<DataList
+  dataFunction={fetchPage}
+  pageSize={50}
+  renderItem={(item) => <div>{item.sku} — {item.qty}</div>}
+/>
+```
+
+The function takes `(max, lastPageToken, args?)` and returns `{ items, pageToken }`. Empty `pageToken` means "no more pages". Supports `args.search` for text filtering against the collection's searchable fields.
+
+### Public portals (anonymous Mythos access)
+
+When a widget runs on a `is_public: true` portal, the host calls `/api/public/execute-batch` instead of the authenticated endpoint. For `mythos:` calls in that batch:
+
+- The Mythos action **must** have `no_auth: true` set in its API Route config
+- The call is forwarded to Mythos's public route `/api/<scope>/models/{name}/actions/{name}` with no JWT
+- Mythos enforces `no_auth` at its middleware layer — actions without that flag return `401` to the widget
+
+No code change in the widget itself — the same `executeAction('mythos:X', 'Y', params)` call works in both authenticated and public portals.
+
 ---
 
 ## 3. Widget settings panel — `IWidgetPropConfig`

package/templates/ican.d.ts

@@ -714,11 +714,16 @@ declare module "ican/context" {
      *
      * Both call shapes return a Promise that resolves to the action's output
      * envelope. For Mythos, the envelope is `{ run_id, status, output? }`.
+     *
+     * `options.cancelPrevious` + `options.key`: when an in-flight call shares
+     * the same key, its Promise resolves to `null` and the newer call wins.
+     * Designed for live-filter widgets where only the latest result matters.
      */
     executeAction(
       model: string,
       action: string,
-      params?: Record<string, unknown>
+      params?: Record<string, unknown>,
+      options?: { cancelPrevious?: boolean; key?: string }
     ): Promise<unknown>;
     /**
      * List every Mythos action published and callable from this widget.
@@ -727,6 +732,31 @@ declare module "ican/context" {
      * once at mount and cache the result themselves.
      */
     listMythosActions?: () => Promise<IMythosAction[]>;
+    /**
+     * Fire an external event into the Mythos engine. The event_type matches
+     * what Mythos event-handlers subscribe to (configured in the model's
+     * Events tab). Mirrors UXP's fireEvent, with an optional payload.
+     * Optional — present only when MYTHOS_BASE_URL is configured.
+     */
+    fireMythosEvent?: (
+      eventType: string,
+      payload?: Record<string, unknown>
+    ) => Promise<void>;
+    /**
+     * Build an IDataFunction over a Mythos collection — drop-in data source
+     * for DataList / DataTable. Mirrors UXP's fromLucyDataCollection.
+     *   const fn = icanContext.fromMythosCollection('Inventory', 'items')
+     *   const { items, pageToken } = await fn(50, '', { search: 'foo' })
+     * Optional — present only when MYTHOS_BASE_URL is configured.
+     */
+    fromMythosCollection?: (
+      model: string,
+      collection: string
+    ) => (
+      max: number,
+      lastPageToken: string,
+      args?: { search?: string } & Record<string, unknown>
+    ) => Promise<{ items: Array<Record<string, unknown>>; pageToken: string }>;
     /** Resolve a relative ICan backend path against the portal base URL. */
     resolveUrl(path: string): string;
     /** Logging helper namespaced to this widget instance. */

package/templates/index.html

@@ -1443,6 +1443,22 @@
           { model_id: 'dev-model-2', model_name: 'Buildings', action_id: 'dev-action-2', action_name: 'List',         description: 'Dev stub' },
         ]);
       },
+      fireMythosEvent: function (eventType, payload) {
+        console.log('[ICan Dev] fireMythosEvent:', eventType, payload);
+        return Promise.resolve();
+      },
+      fromMythosCollection: function (model, collection) {
+        return function (max, lastPageToken, args) {
+          console.log('[ICan Dev] fromMythosCollection:', model, collection, { max: max, lastPageToken: lastPageToken, args: args });
+          // Return one page of synthetic docs so DataList renders something.
+          return Promise.resolve({
+            items: Array.from({ length: Math.min(max, 5) }, function (_, i) {
+              return { id: 'dev-' + i, name: model + ' row ' + i, value: i * 10 };
+            }),
+            pageToken: '',
+          });
+        };
+      },
       fireEvent: function (id) {
         console.log('[ICan Dev] fireEvent:', id);
         return Promise.resolve();

package/templates/ui.html

@@ -1142,6 +1142,21 @@
           { model_id: 'dev-model-2', model_name: 'Buildings', action_id: 'dev-action-2', action_name: 'List',         description: 'Dev stub' },
         ]);
       },
+      fireMythosEvent: function (eventType, payload) {
+        console.log('[ICan Dev] fireMythosEvent:', eventType, payload);
+        return Promise.resolve();
+      },
+      fromMythosCollection: function (model, collection) {
+        return function (max, lastPageToken, args) {
+          console.log('[ICan Dev] fromMythosCollection:', model, collection, { max: max, lastPageToken: lastPageToken, args: args });
+          return Promise.resolve({
+            items: Array.from({ length: Math.min(max, 5) }, function (_, i) {
+              return { id: 'dev-' + i, name: model + ' row ' + i, value: i * 10 };
+            }),
+            pageToken: '',
+          });
+        };
+      },
       fireEvent:      function (id) {
         console.log('[ICan Dev] fireEvent:', id);
         return Promise.resolve();