infaira-canvas 0.1.10 → 0.3.0

package/README.md

@@ -11,6 +11,13 @@ CLI toolkit for building and publishing widgets for the **InfAIra Canvas (ICan)*
 1. **Scaffold** a new widget project with all required files
 2. **Upload** a built widget bundle to an ICan portal
 
+Widgets scaffolded with this CLI can call:
+
+- **ICan native actions** — `icanContext.executeAction('Buildings', 'List', { siteId })`
+- **Mythos workflow actions** — `icanContext.executeAction('mythos:Inventory', 'UpdateStock', { sku, qty })`
+
+The only difference at the call site is the `mythos:` prefix on the model name. The ICan backend handles routing (set `MYTHOS_BASE_URL` on the backend to enable). See **section 2a** of the bundled `ICan-Widget-Development-Guide.md` for the full Mythos integration walkthrough.
+
 ---
 
 ## Installation

package/dist/commands/init.js

@@ -288,20 +288,57 @@ 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;
 }
 
+/** A Mythos action published and callable from this widget. Returned by
+ *  IContextProvider.listMythosActions. Invoke one via
+ *  executeAction('mythos:' + model_name, action_name, params). */
+export interface IMythosAction {
+  model_id: string;
+  model_name: string;
+  action_id: string;
+  action_name: string;
+  description?: string;
+  capability?: string;
+}
+
 export interface IContextProvider {
   environment: 'dev' | 'prod';
   orchUrl?: string;
   userKey: string;
   root: string;
   scriptFiles?: string[];
+  /** Invoke a model action.
+   *  - 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.
+   *  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,13 +1,15 @@
 {
   "name": "infaira-canvas",
-  "version": "0.1.10",
-  "description": "InfAIra Canvas CLI — Widget development toolkit for InfAIra Canvas",
+  "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",
+    "mythos",
     "widget",
     "cli",
-    "scaffold"
+    "scaffold",
+    "workflow"
   ],
   "homepage": "https://infaira.co",
   "license": "MIT",

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

@@ -38,7 +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 Orch model |
+| `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 |
@@ -73,6 +76,114 @@ The dev harness always sets `environment: 'dev'`. The portal always sets `enviro
 
 ---
 
+## 2a. Calling Mythos actions — the `mythos:` prefix
+
+ICan widgets can invoke actions running in the Mythos workflow engine through the exact same `executeAction` call, just by prefixing the `model` argument with `mythos:`. The host backend inspects the prefix and routes the request to the Mythos engine via the shared JWT.
+
+```tsx
+// 1. Discover what's available (call once at mount and cache)
+const actions = await icanContext.listMythosActions?.();
+// → [{ model_id, model_name: 'Inventory', action_id, action_name: 'UpdateStock', description }]
+
+// 2. Invoke a Mythos action — only the `mythos:` prefix differs from a
+//    native ICan call
+const result = await icanContext.executeAction(
+  'mythos:Inventory',     // <- the prefix is what triggers Mythos routing
+  'UpdateStock',
+  { sku: 'ABC-123', qty: 5 },
+);
+// → { run_id: '...', status: 'ok', output?: {...} }
+```
+
+### When to use Mythos vs native
+
+| Use Mythos when… | Use native ICan when… |
+|---|---|
+| The logic is a multi-step workflow with branches, retries, or external calls | The call is a direct read/write to a backing service (Locations, Assets, etc.) |
+| You want the call recorded in Mythos's execution log + debugger | You don't need step-level tracing |
+| Multiple widgets need to call the same business operation | The operation is widget-local |
+| You want to publish the same logic over a REST endpoint too | The widget owns the orchestration |
+
+### Failure modes to handle
+
+`executeAction('mythos:...')` can reject with:
+
+- **`mythos integration not configured`** — the ICan backend doesn't have `MYTHOS_BASE_URL` set. Surface this to the user and fall back gracefully.
+- **`mythos model "X" not found or not published`** — the action either doesn't exist or isn't toggled `published: true` in Mythos.
+- **HTTP / network errors** — same as any `executeAction` call.
+
+`listMythosActions` is also `undefined` when integration is disabled — so guard with `?.()`.
+
+```tsx
+const handleRun = async () => {
+  try {
+    const r = await icanContext.executeAction('mythos:Inventory', 'UpdateStock', { sku, qty });
+    setResult(r);
+  } catch (e) {
+    setError(e instanceof Error ? e.message : 'Failed');
+  }
+};
+```
+
+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`
 
 Widgets can expose a settings form in the portal. Users open it by clicking the ⚙ button on a widget cell in edit mode. You define the fields in `registerWidget`:

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

@@ -594,7 +594,10 @@ interface IContextProvider {
   orchUrl?:     string;
   apiKey?:      string;
 
-  // Fetch data from Orch
+  // Invoke an action. Prefix model with `mythos:` to route to the Mythos
+  // workflow engine instead of the default ICan native pipeline:
+  //   executeAction('Buildings', 'List', { siteId })            → ICan native
+  //   executeAction('mythos:Inventory', 'UpdateStock', { ... }) → Mythos engine
   executeAction(
     model: string,
     action: string,
@@ -602,6 +605,16 @@ interface IContextProvider {
     options?: IActionOptions
   ): Promise<unknown>;
 
+  // List Mythos actions callable via executeAction('mythos:...', ...).
+  // Optional — present only when MYTHOS_BASE_URL is set on the ICan backend.
+  listMythosActions?(): Promise<Array<{
+    model_id: string;
+    model_name: string;
+    action_id: string;
+    action_name: string;
+    description?: string;
+  }>>;
+
   executeService(
     app: string,
     service: string,

package/templates/ican.d.ts

@@ -701,17 +701,81 @@ declare module "ican/context" {
       email?: string;
       roles?: string[];
     };
-    /** Invoke a registered model action on this dashboard. */
+    /**
+     * Invoke a model action on this dashboard.
+     *
+     * Routing happens server-side by inspecting `model`:
+     *   - `executeAction('Buildings', 'List', { siteId })`
+     *       → ICan native action (existing Orch pipeline).
+     *   - `executeAction('mythos:Inventory', 'UpdateStock', { sku, qty })`
+     *       → routed to the Mythos engine via the `mythos:` prefix. Resolves
+     *         to the published Mythos action with that (model_name, action_name)
+     *         and POSTs to `/api/models/{id}/actions/{id}/run`.
+     *
+     * 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.
+     * Optional — present only when the ICan backend has MYTHOS_BASE_URL set.
+     * Widgets that build action pickers (settings panels, etc.) call this
+     * 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. */
     log(level: "info" | "warn" | "error", ...args: unknown[]): void;
   }
+
+  /**
+   * A single Mythos action published as callable from a widget. Returned by
+   * `icanContext.listMythosActions()`. To invoke one, call
+   * `icanContext.executeAction('mythos:' + model_name, action_name, params)`.
+   */
+  export interface IMythosAction {
+    model_id: string;
+    model_name: string;
+    action_id: string;
+    action_name: string;
+    description?: string;
+    capability?: string;
+  }
 }
 
 // ─── Global runtime declarations ─────────────────────────────────────────────

package/templates/index.html

@@ -1419,13 +1419,46 @@
       orchUrl: localStorage.getItem(LS_ORCH_URL) || '',
       apiKey:  localStorage.getItem(LS_API_KEY)  || '',
       executeAction: function (model, action, params) {
-        console.log('[ICan Dev] executeAction:', model, action, params);
+        // Mythos-routed calls use the `mythos:<ModelName>` prefix in production.
+        // In the dev harness we just log them distinctively so authors can see
+        // whether their widget is targeting ICan native or Mythos.
+        var isMythos = typeof model === 'string' && model.toLowerCase().indexOf('mythos:') === 0;
+        console.log('[ICan Dev]' + (isMythos ? ' [Mythos]' : '') + ' executeAction:', model, action, params);
+        if (isMythos) {
+          // Mock the Mythos response envelope: { run_id, status, output }.
+          return Promise.resolve({ run_id: 'dev-' + Date.now(), status: 'ok', output: {} });
+        }
         return Promise.resolve([]);
       },
       executeService: function (app, service, params) {
         console.log('[ICan Dev] executeService:', app, service, params);
         return Promise.resolve(null);
       },
+      listMythosActions: function () {
+        // Dev stub — returns a couple of synthetic actions so widgets that
+        // populate dropdowns from discovery don't render empty.
+        console.log('[ICan Dev] listMythosActions');
+        return Promise.resolve([
+          { model_id: 'dev-model-1', model_name: 'Inventory',  action_id: 'dev-action-1', action_name: 'UpdateStock', description: 'Dev stub' },
+          { 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

@@ -1123,13 +1123,40 @@
       orchUrl:        localStorage.getItem(LS_ORCH_URL) || '',
       apiKey:         localStorage.getItem(LS_API_KEY)  || '',
       executeAction:  function (model, action, params) {
-        console.log('[ICan Dev] executeAction:', model, action, params);
+        // Mythos-routed calls use the `mythos:<ModelName>` prefix.
+        var isMythos = typeof model === 'string' && model.toLowerCase().indexOf('mythos:') === 0;
+        console.log('[ICan Dev]' + (isMythos ? ' [Mythos]' : '') + ' executeAction:', model, action, params);
+        if (isMythos) {
+          return Promise.resolve({ run_id: 'dev-' + Date.now(), status: 'ok', output: {} });
+        }
         return Promise.resolve([]);
       },
       executeService: function (app, service, params) {
         console.log('[ICan Dev] executeService:', app, service, params);
         return Promise.resolve(null);
       },
+      listMythosActions: function () {
+        console.log('[ICan Dev] listMythosActions');
+        return Promise.resolve([
+          { model_id: 'dev-model-1', model_name: 'Inventory',  action_id: 'dev-action-1', action_name: 'UpdateStock', description: 'Dev stub' },
+          { 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();