@epilot/cli 0.1.98 → 0.1.101

package/README.md

@@ -29,7 +29,7 @@ npm install -g @epilot/cli
 
 <!-- usage-help -->
 ```
-epilot v0.1.98 — CLI for epilot APIs
+epilot v0.1.101 — CLI for epilot APIs
 
 USAGE
   epilot <api> <operationId> [params...] [flags]

package/definitions/dashboard.json

@@ -17,6 +17,9 @@
     {
       "name": "Dashboards"
     },
+    {
+      "name": "Insights"
+    },
     {
       "name": "Visualisations"
     },
@@ -33,6 +36,53 @@
         "tags": [
           "Dashboards"
         ],
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/Search"
+          },
+          {
+            "$ref": "#/components/parameters/CreatedBy"
+          },
+          {
+            "$ref": "#/components/parameters/CreatedAfter"
+          },
+          {
+            "$ref": "#/components/parameters/CreatedBefore"
+          },
+          {
+            "$ref": "#/components/parameters/UpdatedAfter"
+          },
+          {
+            "$ref": "#/components/parameters/UpdatedBefore"
+          },
+          {
+            "$ref": "#/components/parameters/SharedWith"
+          },
+          {
+            "$ref": "#/components/parameters/Owner"
+          },
+          {
+            "$ref": "#/components/parameters/AccessibleTo"
+          },
+          {
+            "$ref": "#/components/parameters/Favorite"
+          },
+          {
+            "$ref": "#/components/parameters/FavoritesFirst"
+          },
+          {
+            "$ref": "#/components/parameters/Sort"
+          },
+          {
+            "$ref": "#/components/parameters/Order"
+          },
+          {
+            "$ref": "#/components/parameters/Limit"
+          },
+          {
+            "$ref": "#/components/parameters/Offset"
+          }
+        ],
         "responses": {
           "200": {
             "description": "List of dashboards available to the user",
@@ -46,8 +96,15 @@
                       "items": {
                         "$ref": "#/components/schemas/Dashboard"
                       }
+                    },
+                    "pagination": {
+                      "$ref": "#/components/schemas/Pagination"
                     }
-                  }
+                  },
+                  "required": [
+                    "results",
+                    "pagination"
+                  ]
                 }
               }
             }
@@ -85,6 +142,81 @@
         }
       }
     },
+    "/v1/dashboard/dashboards/favorites": {
+      "get": {
+        "operationId": "listFavoriteDashboardIds",
+        "summary": "listFavoriteDashboardIds",
+        "description": "Returns the current user's favorited dashboard ids, with no dashboard metadata. Lets a\nclient decide whether to default to a favorites-only view without first fetching the full\ndashboards list.\n",
+        "tags": [
+          "Dashboards"
+        ],
+        "responses": {
+          "200": {
+            "description": "The current user's favorited dashboard ids",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "dashboard_ids": {
+                      "type": "array",
+                      "items": {
+                        "$ref": "#/components/schemas/DashboardID"
+                      }
+                    },
+                    "total": {
+                      "type": "integer"
+                    }
+                  },
+                  "required": [
+                    "dashboard_ids",
+                    "total"
+                  ]
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/v1/dashboard/dashboards/{id}/favorite": {
+      "parameters": [
+        {
+          "name": "id",
+          "in": "path",
+          "required": true,
+          "schema": {
+            "$ref": "#/components/schemas/DashboardID"
+          }
+        }
+      ],
+      "put": {
+        "operationId": "favoriteDashboard",
+        "summary": "favoriteDashboard",
+        "description": "Marks the dashboard as favorited by the current user. Idempotent — favoriting an\nalready-favorited dashboard is not an error. Requires only view-level access to the\ndashboard (unlike the edit-level check on `PATCH .../dashboards/{id}`).\n",
+        "tags": [
+          "Dashboards"
+        ],
+        "responses": {
+          "204": {
+            "description": "The dashboard is now favorited by the current user"
+          }
+        }
+      },
+      "delete": {
+        "operationId": "unfavoriteDashboard",
+        "summary": "unfavoriteDashboard",
+        "description": "Removes the current user's favorite for the dashboard. Idempotent — unfavoriting a\ndashboard that was not favorited is not an error, and neither is unfavoriting one that no\nlonger exists or is no longer shared with you. Requires no access to the dashboard, so that\na stale favorite always remains removable.\n",
+        "tags": [
+          "Dashboards"
+        ],
+        "responses": {
+          "204": {
+            "description": "The dashboard is no longer favorited by the current user"
+          }
+        }
+      }
+    },
     "/v1/dashboard/dashboards/{id}": {
       "parameters": [
         {
@@ -146,6 +278,36 @@
           }
         }
       },
+      "patch": {
+        "operationId": "patchDashboard",
+        "summary": "patchDashboard",
+        "description": "Partially update a dashboard by ID. Update content (title/tiles) and/or manage sharing\n(owners, shared_with, org_access) — only owners may change sharing.\n`owners` and `shared_with` replace the whole array (send the complete list); omit them to leave\nsharing unchanged, or send `shared_with: []` to revoke all per-user grants.\n",
+        "tags": [
+          "Dashboards"
+        ],
+        "requestBody": {
+          "description": "The dashboard fields to update",
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/DashboardPatch"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "The updated dashboard",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Dashboard"
+                }
+              }
+            }
+          }
+        }
+      },
       "delete": {
         "operationId": "deleteDashboard",
         "summary": "deleteDashboard",
@@ -167,6 +329,265 @@
         }
       }
     },
+    "/v1/dashboard/insights": {
+      "get": {
+        "operationId": "listInsights",
+        "summary": "listInsights",
+        "description": "List insights (saved charts) available to the user",
+        "tags": [
+          "Insights"
+        ],
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/Search"
+          },
+          {
+            "$ref": "#/components/parameters/VisualisationIdFilter"
+          },
+          {
+            "$ref": "#/components/parameters/TagsFilter"
+          },
+          {
+            "$ref": "#/components/parameters/TagsMatch"
+          },
+          {
+            "$ref": "#/components/parameters/CreatedBy"
+          },
+          {
+            "$ref": "#/components/parameters/CreatedAfter"
+          },
+          {
+            "$ref": "#/components/parameters/CreatedBefore"
+          },
+          {
+            "$ref": "#/components/parameters/UpdatedAfter"
+          },
+          {
+            "$ref": "#/components/parameters/UpdatedBefore"
+          },
+          {
+            "$ref": "#/components/parameters/SharedWith"
+          },
+          {
+            "$ref": "#/components/parameters/Owner"
+          },
+          {
+            "$ref": "#/components/parameters/AccessibleTo"
+          },
+          {
+            "$ref": "#/components/parameters/Sort"
+          },
+          {
+            "$ref": "#/components/parameters/Order"
+          },
+          {
+            "$ref": "#/components/parameters/Limit"
+          },
+          {
+            "$ref": "#/components/parameters/Offset"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "List of insights available to the user",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "results": {
+                      "type": "array",
+                      "items": {
+                        "$ref": "#/components/schemas/Insight"
+                      }
+                    },
+                    "pagination": {
+                      "$ref": "#/components/schemas/Pagination"
+                    }
+                  },
+                  "required": [
+                    "results",
+                    "pagination"
+                  ]
+                }
+              }
+            }
+          }
+        }
+      },
+      "post": {
+        "operationId": "createInsight",
+        "summary": "createInsight",
+        "description": "Create a new insight (saved chart). The caller becomes the owner.",
+        "tags": [
+          "Insights"
+        ],
+        "requestBody": {
+          "description": "The insight to create",
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/Insight"
+              }
+            }
+          }
+        },
+        "responses": {
+          "201": {
+            "description": "The created insight",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Insight"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/v1/dashboard/insights/tags": {
+      "get": {
+        "operationId": "listInsightTags",
+        "summary": "listInsightTags",
+        "description": "List the distinct tags used by insights in the organization (for filter facets)",
+        "tags": [
+          "Insights"
+        ],
+        "responses": {
+          "200": {
+            "description": "Distinct tags used by insights in the organization",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "results": {
+                      "type": "array",
+                      "items": {
+                        "type": "string"
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/v1/dashboard/insights/{id}": {
+      "parameters": [
+        {
+          "name": "id",
+          "in": "path",
+          "required": true,
+          "schema": {
+            "$ref": "#/components/schemas/InsightID"
+          }
+        }
+      ],
+      "get": {
+        "operationId": "getInsight",
+        "summary": "getInsight",
+        "description": "Get insight by ID",
+        "tags": [
+          "Insights"
+        ],
+        "responses": {
+          "200": {
+            "description": "The insight with the passed ID",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Insight"
+                }
+              }
+            }
+          }
+        }
+      },
+      "put": {
+        "operationId": "putInsight",
+        "summary": "putInsight",
+        "description": "Replace an insight's content by ID. Sharing is managed via patchInsight.",
+        "tags": [
+          "Insights"
+        ],
+        "requestBody": {
+          "description": "The updated insight",
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/Insight"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "The insight with the passed ID",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Insight"
+                }
+              }
+            }
+          }
+        }
+      },
+      "patch": {
+        "operationId": "patchInsight",
+        "summary": "patchInsight",
+        "description": "Partially update an insight by ID. Update content (name/description/visualisation/tags) and/or\nmanage sharing (owners, shared_with, org_access) — only owners may change sharing.\n`owners` and `shared_with` replace the whole array (send the complete list); omit them to leave\nsharing unchanged, or send `shared_with: []` to revoke all per-user grants.\n",
+        "tags": [
+          "Insights"
+        ],
+        "requestBody": {
+          "description": "The insight fields to update",
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/InsightPatch"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "The updated insight",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Insight"
+                }
+              }
+            }
+          }
+        }
+      },
+      "delete": {
+        "operationId": "deleteInsight",
+        "summary": "deleteInsight",
+        "description": "Delete an insight by ID. Only owners may delete.",
+        "tags": [
+          "Insights"
+        ],
+        "responses": {
+          "200": {
+            "description": "The deleted insight",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Insight"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
     "/v1/dashboard/visualisations": {
       "get": {
         "operationId": "listAvailableVisualisations",
@@ -251,72 +672,313 @@
         "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
       },
       "Dashboard": {
+        "description": "A dashboard configuration. A dashboard is a canvas whose tiles arrange and\nposition insights (saved charts). Tiles may reference an insight by `insight_id`\nor, for backwards compatibility, embed a visualisation inline.\n",
+        "allOf": [
+          {
+            "$ref": "#/components/schemas/AccessControl"
+          },
+          {
+            "type": "object",
+            "properties": {
+              "id": {
+                "$ref": "#/components/schemas/DashboardID"
+              },
+              "title": {
+                "type": "string",
+                "example": "Employee Dashboard"
+              },
+              "tiles": {
+                "type": "array",
+                "items": {
+                  "$ref": "#/components/schemas/DashboardTile"
+                },
+                "example": [
+                  {
+                    "id": "e4af1297-1fd6-440f-9846-f475f580d40f",
+                    "coordinates": {},
+                    "insight_id": "8d2e1c7a-3b4f-4a2e-9c1d-2f3a4b5c6d7e"
+                  }
+                ]
+              },
+              "favorited": {
+                "description": "Whether the requesting user has favorited this dashboard.",
+                "type": "boolean",
+                "readOnly": true,
+                "example": false
+              }
+            },
+            "required": [
+              "title",
+              "tiles"
+            ]
+          }
+        ]
+      },
+      "DashboardTileID": {
+        "description": "Unique identifier for a tile in a dashboard",
+        "type": "string",
+        "format": "uuid",
+        "example": "e4af1297-1fd6-440f-9846-f475f580d40f"
+      },
+      "SharePermission": {
+        "description": "Permission level granted to a user (or the whole organization) on a shared resource.\n`view` allows read-only access; `edit` additionally allows updating the content.\nFull control (delete and managing sharing) is reserved for owners.\n",
+        "type": "string",
+        "enum": [
+          "view",
+          "edit"
+        ],
+        "example": "view"
+      },
+      "ShareGrant": {
+        "description": "Grants a single user a permission level on a resource",
         "type": "object",
-        "description": "Adashboard configuration with tiles",
         "properties": {
-          "id": {
-            "$ref": "#/components/schemas/DashboardID"
+          "user_id": {
+            "description": "The id of the user the resource is shared with",
+            "type": "string",
+            "example": "10598"
           },
-          "title": {
+          "permission": {
+            "$ref": "#/components/schemas/SharePermission"
+          }
+        },
+        "required": [
+          "user_id",
+          "permission"
+        ]
+      },
+      "OrgAccess": {
+        "description": "Optional organization-wide grant. When set, every user in the resource's organization\nis granted this permission level. `null` (or omitted) means the resource is not shared\norg-wide.\n",
+        "anyOf": [
+          {
+            "type": "string",
+            "enum": [
+              "view",
+              "edit"
+            ]
+          },
+          {
+            "enum": [
+              null
+            ]
+          }
+        ],
+        "example": "view"
+      },
+      "AccessControl": {
+        "description": "Ownership and sharing metadata common to dashboards and insights. `created_*`/`updated_*`\nfields are managed by the server. `owners`, `shared_with` and `org_access` describe who\nmay access the resource. New resources are private to their creator until shared.\n",
+        "type": "object",
+        "properties": {
+          "created_by": {
+            "description": "Id of the user who created the resource",
+            "type": "string",
+            "readOnly": true,
+            "example": "10598"
+          },
+          "created_at": {
+            "type": "string",
+            "format": "date-time",
+            "readOnly": true
+          },
+          "updated_by": {
+            "description": "Id of the user who last updated the resource",
             "type": "string",
-            "example": "Employee Dashboard"
+            "readOnly": true,
+            "example": "10598"
           },
-          "tiles": {
+          "updated_at": {
+            "type": "string",
+            "format": "date-time",
+            "readOnly": true
+          },
+          "owner_org_id": {
+            "description": "Id of the organisation that owns the resource. Set at creation time and immutable.",
+            "type": "string",
+            "readOnly": true,
+            "example": "739224"
+          },
+          "owners": {
+            "description": "User ids with full control over the resource (view, edit, delete and manage sharing).\nThe creator is always an owner. There must always be at least one owner.\n",
             "type": "array",
             "items": {
-              "$ref": "#/components/schemas/DashboardTile"
+              "type": "string"
             },
             "example": [
-              {
-                "id": "e4af1297-1fd6-440f-9846-f475f580d40f",
-                "coordinates": {},
-                "visualisation": "timechart",
-                "visualisation_config": {
-                  "query": {
-                    "dataset": "entity_operations",
-                    "measure": "count_operations",
-                    "filters": [
-                      {
-                        "operation": [
-                          "createEntity"
-                        ]
-                      },
-                      {
-                        "entity_schema": [
-                          "opportunity"
-                        ]
-                      }
-                    ],
-                    "dimensions": [
-                      {
-                        "time_with_granularity": "month"
-                      },
-                      {
-                        "entity_attribute": "source.title"
-                      }
-                    ]
-                  },
-                  "options": {
-                    "type": "line"
-                  }
+              "10598"
+            ]
+          },
+          "shared_with": {
+            "description": "Per-user sharing grants",
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/ShareGrant"
+            }
+          },
+          "org_access": {
+            "$ref": "#/components/schemas/OrgAccess"
+          }
+        }
+      },
+      "AccessControlUpdate": {
+        "description": "Sharing fields that can be mutated via PATCH (owners only). `owners` and `shared_with` are\nfull replacements of their arrays, not merges — omit a field to leave it unchanged.\n",
+        "type": "object",
+        "properties": {
+          "owners": {
+            "description": "Replaces the entire list of owner user ids. Must keep at least one owner (else 400).\nOmit to leave owners unchanged.\n",
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "shared_with": {
+            "description": "Replaces the entire list of per-user grants — any existing grant not included is removed.\nOmit to leave sharing unchanged; send an empty array to revoke all per-user grants.\n",
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/ShareGrant"
+            }
+          },
+          "org_access": {
+            "$ref": "#/components/schemas/OrgAccess"
+          }
+        }
+      },
+      "DashboardPatch": {
+        "description": "Fields that can be partially updated on a dashboard",
+        "allOf": [
+          {
+            "$ref": "#/components/schemas/AccessControlUpdate"
+          },
+          {
+            "type": "object",
+            "properties": {
+              "title": {
+                "type": "string",
+                "example": "Employee Dashboard"
+              },
+              "tiles": {
+                "type": "array",
+                "items": {
+                  "$ref": "#/components/schemas/DashboardTile"
                 }
               }
-            ]
+            }
           }
-        },
-        "required": [
-          "title",
-          "tiles"
         ]
       },
-      "DashboardTileID": {
-        "description": "Unique identifier for a tile in a dashboard",
+      "InsightID": {
+        "description": "Unique identifier for an insight (a saved chart / visualisation)",
         "type": "string",
         "format": "uuid",
-        "example": "e4af1297-1fd6-440f-9846-f475f580d40f"
+        "example": "8d2e1c7a-3b4f-4a2e-9c1d-2f3a4b5c6d7e"
+      },
+      "Insight": {
+        "description": "An insight is a saved, reusable chart definition (a visualisation plus its query/options).\nInsights exist independently of dashboards: they can be created, shared and edited on their\nown, and referenced by one or more dashboard tiles via `insight_id`.\n",
+        "allOf": [
+          {
+            "$ref": "#/components/schemas/AccessControl"
+          },
+          {
+            "type": "object",
+            "properties": {
+              "id": {
+                "$ref": "#/components/schemas/InsightID"
+              },
+              "name": {
+                "description": "Human readable name of the insight",
+                "type": "string",
+                "example": "Opportunities created by journeys every month"
+              },
+              "description": {
+                "type": "string",
+                "example": "Monthly count of opportunities grouped by source journey"
+              },
+              "visualisation_id": {
+                "$ref": "#/components/schemas/VisualisationId"
+              },
+              "visualisation_config": {
+                "$ref": "#/components/schemas/VisualisationConfig"
+              },
+              "tags": {
+                "$ref": "#/components/schemas/Tags"
+              }
+            },
+            "required": [
+              "name",
+              "visualisation_id"
+            ]
+          }
+        ]
+      },
+      "InsightPatch": {
+        "description": "Fields that can be partially updated on an insight",
+        "allOf": [
+          {
+            "$ref": "#/components/schemas/AccessControlUpdate"
+          },
+          {
+            "type": "object",
+            "properties": {
+              "name": {
+                "type": "string"
+              },
+              "description": {
+                "type": "string"
+              },
+              "visualisation_id": {
+                "$ref": "#/components/schemas/VisualisationId"
+              },
+              "visualisation_config": {
+                "$ref": "#/components/schemas/VisualisationConfig"
+              },
+              "tags": {
+                "$ref": "#/components/schemas/Tags"
+              }
+            }
+          }
+        ]
+      },
+      "Tags": {
+        "description": "Free-form labels for grouping and filtering insights",
+        "type": "array",
+        "items": {
+          "type": "string"
+        },
+        "example": [
+          "revenue",
+          "marketing"
+        ]
+      },
+      "Pagination": {
+        "description": "Offset-based pagination metadata for list responses",
+        "type": "object",
+        "properties": {
+          "total": {
+            "description": "Total number of results matching the query (ignoring limit/offset)",
+            "type": "integer"
+          },
+          "limit": {
+            "description": "Page size used for this response",
+            "type": "integer"
+          },
+          "offset": {
+            "description": "Number of results skipped before this page",
+            "type": "integer"
+          },
+          "has_more": {
+            "description": "Whether more results exist beyond this page",
+            "type": "boolean"
+          }
+        },
+        "required": [
+          "total",
+          "limit",
+          "offset",
+          "has_more"
+        ]
       },
       "DashboardTile": {
         "type": "object",
+        "description": "A positioned tile on a dashboard canvas. A tile references a saved insight via\n`insight_id`. Inline `visualisation_id`/`visualisation_config` remain supported for\nbackwards compatibility (ad-hoc tiles that are not backed by a shared insight).\n",
         "properties": {
           "id": {
             "$ref": "#/components/schemas/DashboardTileID"
@@ -328,6 +990,10 @@
             "type": "string",
             "example": "Number of opportunities created by journeys every month"
           },
+          "insight_id": {
+            "description": "Reference to a saved insight rendered by this tile",
+            "$ref": "#/components/schemas/InsightID"
+          },
           "visualisation_id": {
             "$ref": "#/components/schemas/VisualisationId"
           },
@@ -461,6 +1127,211 @@
         }
       }
     },
+    "parameters": {
+      "Search": {
+        "name": "q",
+        "in": "query",
+        "required": false,
+        "description": "Free-text search over name/title and description (case-insensitive substring).",
+        "schema": {
+          "type": "string"
+        }
+      },
+      "VisualisationIdFilter": {
+        "name": "visualisation_id",
+        "in": "query",
+        "required": false,
+        "description": "Filter insights by one or more visualisation ids.",
+        "style": "form",
+        "explode": true,
+        "schema": {
+          "type": "array",
+          "items": {
+            "$ref": "#/components/schemas/VisualisationId"
+          }
+        }
+      },
+      "TagsFilter": {
+        "name": "tags",
+        "in": "query",
+        "required": false,
+        "description": "Filter by one or more tags (see tags_match for any/all semantics).",
+        "style": "form",
+        "explode": true,
+        "schema": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        }
+      },
+      "TagsMatch": {
+        "name": "tags_match",
+        "in": "query",
+        "required": false,
+        "description": "Whether a result must match any (default) or all of the given tags.",
+        "schema": {
+          "type": "string",
+          "enum": [
+            "any",
+            "all"
+          ],
+          "default": "any"
+        }
+      },
+      "CreatedBy": {
+        "name": "created_by",
+        "in": "query",
+        "required": false,
+        "description": "Filter by the id of the creating user.",
+        "schema": {
+          "type": "string"
+        }
+      },
+      "CreatedAfter": {
+        "name": "created_after",
+        "in": "query",
+        "required": false,
+        "schema": {
+          "type": "string",
+          "format": "date-time"
+        }
+      },
+      "CreatedBefore": {
+        "name": "created_before",
+        "in": "query",
+        "required": false,
+        "schema": {
+          "type": "string",
+          "format": "date-time"
+        }
+      },
+      "UpdatedAfter": {
+        "name": "updated_after",
+        "in": "query",
+        "required": false,
+        "schema": {
+          "type": "string",
+          "format": "date-time"
+        }
+      },
+      "UpdatedBefore": {
+        "name": "updated_before",
+        "in": "query",
+        "required": false,
+        "schema": {
+          "type": "string",
+          "format": "date-time"
+        }
+      },
+      "SharedWith": {
+        "name": "shared_with",
+        "in": "query",
+        "required": false,
+        "description": "Filter to resources shared with any of the given user ids.",
+        "style": "form",
+        "explode": true,
+        "schema": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        }
+      },
+      "Owner": {
+        "name": "owner",
+        "in": "query",
+        "required": false,
+        "description": "Filter to resources owned by any of the given user ids.",
+        "style": "form",
+        "explode": true,
+        "schema": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        }
+      },
+      "AccessibleTo": {
+        "name": "accessible_to",
+        "in": "query",
+        "required": false,
+        "description": "Filter to resources the given user id may view (owner, shared, org-wide or legacy).",
+        "schema": {
+          "type": "string"
+        }
+      },
+      "Favorite": {
+        "name": "favorite",
+        "in": "query",
+        "required": false,
+        "description": "Dashboards only. Filter to only (`true`) or exclude (`false`) the requesting user's\nfavorited dashboards. A user with zero favorites and `favorite=true` gets an empty page,\nnot the unfiltered list.\n",
+        "schema": {
+          "type": "boolean"
+        }
+      },
+      "FavoritesFirst": {
+        "name": "favorites_first",
+        "in": "query",
+        "required": false,
+        "description": "Dashboards only. No filtering — sorts the requesting user's favorited dashboards first,\npreserving the existing secondary ordering (`sort`/`order`) otherwise.\n",
+        "schema": {
+          "type": "boolean"
+        }
+      },
+      "Sort": {
+        "name": "sort",
+        "in": "query",
+        "required": false,
+        "description": "Field to sort by. `name` and `title` are aliases for the resource's display name and are normalised per resource: dashboards sort by `title` and insights by `name`, whichever of the two values is sent. String sorts are case-insensitive.",
+        "schema": {
+          "type": "string",
+          "enum": [
+            "created_at",
+            "updated_at",
+            "name",
+            "title"
+          ],
+          "default": "updated_at"
+        }
+      },
+      "Order": {
+        "name": "order",
+        "in": "query",
+        "required": false,
+        "description": "Sort direction. Defaults to ascending (preserving the pre-migration order).",
+        "schema": {
+          "type": "string",
+          "enum": [
+            "asc",
+            "desc"
+          ],
+          "default": "asc"
+        }
+      },
+      "Limit": {
+        "name": "limit",
+        "in": "query",
+        "required": false,
+        "description": "Maximum results to return (max 200). Omit to return all matching results (pagination is opt-in).",
+        "schema": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 200
+        }
+      },
+      "Offset": {
+        "name": "offset",
+        "in": "query",
+        "required": false,
+        "description": "Number of results to skip, for pagination. Use with limit (page N = offset N*limit).",
+        "schema": {
+          "type": "integer",
+          "minimum": 0,
+          "default": 0
+        }
+      }
+    },
     "securitySchemes": {
       "EpilotAuth": {
         "type": "http",

package/definitions/entity.json

@@ -3947,7 +3947,7 @@
               "description": "ISO 8601 timestamp to filter jobs created after this time (e.g., 2023-01-01T00:00:00Z).",
               "type": "string",
               "format": "date-time",
-              "example": "2023-01-01T00:00:00Z"
+              "example": "2023-01-01T00:00:00.000Z"
             }
           },
           {
@@ -5097,6 +5097,17 @@
                 "items": {
                   "type": "string"
                 }
+              },
+              "widget_visibility": {
+                "type": "object",
+                "description": "Per-widget on/off state for the entity-details widget grid, keyed by widget id (a capability widget's `component`, or `summary` for the synthesized summary card). Holds only the admin's deviations from each widget's declared default: a widget absent from this map falls back to its ui_hook `default_visible`, and then to visible. Do not seed this map from migrations — doing so would freeze today's defaults into the schema.",
+                "additionalProperties": {
+                  "type": "boolean"
+                },
+                "example": {
+                  "next_best_action": true,
+                  "address_map": false
+                }
               }
             }
           },
@@ -7448,6 +7459,11 @@
               "$ref": "#/components/schemas/Attribute"
             }
           },
+          "variant_overridable": {
+            "type": "boolean",
+            "default": false,
+            "description": "Allow conditional variants of the entity to override the values managed by this\ncapability. Only meaningful on schemas that declare `conditions` and on capabilities\nthat render an attribute group (`EntityAttributes:Group` ui hook), e.g. pricing tiers.\nAttributes carried by the capability opt in individually via their own\n`variant_overridable` flag.\n"
+          },
           "_purpose": {
             "type": "array",
             "items": {
@@ -7555,6 +7571,16 @@
                   "required": [
                     "action"
                   ]
+                },
+                "default_visible": {
+                  "type": "boolean",
+                  "description": "Whether this widget is switched on by default for entity types that have the capability. Only meaningful on the `EntityDetailsV2:Widget` hook. Defaults to true when omitted. An admin's explicit choice in the entity builder is stored in the schema's `ui_config.widget_visibility` and wins over this.",
+                  "example": false
+                },
+                "pricing_tier_setting": {
+                  "type": "string",
+                  "description": "The pricing-tier settings key an organisation must have enabled to use this widget. Omit for widgets available to everyone. Resolved against `GET /v2/pricing-tiers/me` as `override_settings[key].enabled ?? settings[key].enabled`. Note this is commercial packaging enforced in the UI, not a security control — the key must also be added to the pricing tier settings list in epilot-admin-portal, or it can never be switched on for a tier.",
+                  "example": "entity_address_maps"
                 }
               },
               "required": [

package/definitions/integration-toolkit.json

@@ -2,7 +2,7 @@
   "openapi": "3.0.3",
   "info": {
     "title": "Integration Toolkit API",
-    "version": "1.8.0",
+    "version": "1.10.0",
     "description": "API for integrating with external systems in a standardised way."
   },
   "tags": [
@@ -3891,6 +3891,16 @@
             }
           }
         ],
+        "requestBody": {
+          "required": false,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/ExecuteErpImportRequest"
+              }
+            }
+          }
+        },
         "responses": {
           "200": {
             "description": "Execution started",
@@ -3911,6 +3921,16 @@
           "409": {
             "$ref": "#/components/responses/Conflict"
           },
+          "422": {
+            "description": "The verdict carries warnings and `ack_warnings` was not true",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponseBase"
+                }
+              }
+            }
+          },
           "500": {
             "$ref": "#/components/responses/InternalServerError"
           }
@@ -4005,6 +4025,57 @@
           }
         }
       },
+      "ExecuteErpImportRequest": {
+        "type": "object",
+        "description": "Confirmation options. Required only when the verdict carries warnings — a clean import needs no body at all.",
+        "properties": {
+          "ack_warnings": {
+            "type": "boolean",
+            "description": "The caller has seen `validation.issues` and accepts them. Required when `validation.warnings` is greater than 0; ignored otherwise."
+          }
+        }
+      },
+      "ErpImportIssue": {
+        "type": "object",
+        "description": "A problem found during validation, scoped to the file as a whole rather than to individual rows. See `code` for the kinds reported.",
+        "required": [
+          "code",
+          "severity",
+          "message"
+        ],
+        "properties": {
+          "code": {
+            "type": "string",
+            "description": "Enum of possible issue codes.\n",
+            "enum": [
+              "UNIQUE_ID_COLUMN_MISSING",
+              "MAPPED_COLUMN_MISSING",
+              "MALFORMED_ROW",
+              "INVALID_ENCODING",
+              "EMPTY_FILE",
+              "TOO_MANY_ROWS"
+            ]
+          },
+          "severity": {
+            "type": "string",
+            "enum": [
+              "warning",
+              "blocking"
+            ]
+          },
+          "message": {
+            "type": "string",
+            "description": "User-facing explanation. Lists at most 10 column names; `columns` has all of them."
+          },
+          "columns": {
+            "type": "array",
+            "description": "The columns this issue is about, so clients render names rather than parsing the message.",
+            "items": {
+              "type": "string"
+            }
+          }
+        }
+      },
       "ErpImportValidation": {
         "type": "object",
         "description": "Validate-phase summary: what the file will create, and whether it may be confirmed. Absent until the validate phase completes. No per-row detail is kept — a rejected file is corrected and imported again.",
@@ -4031,6 +4102,13 @@
               "type": "integer"
             },
             "description": "Distinct entities the file expresses, keyed by entity slug."
+          },
+          "issues": {
+            "type": "array",
+            "description": "Whole-file issues. At most 20 are kept; the count of everything found is in blocking and warnings. Warnings here are what `ack_warnings` on `:execute` acknowledges.",
+            "items": {
+              "$ref": "#/components/schemas/ErpImportIssue"
+            }
           }
         }
       },
@@ -4055,16 +4133,21 @@
         "type": "object",
         "description": "Why the import failed — present if and only if status = FAILED.",
         "required": [
-          "type",
+          "code",
           "message"
         ],
         "properties": {
-          "type": {
+          "code": {
             "type": "string",
-            "description": "VALIDATION_BLOCKED = blocking row issues (see `validation`); PROCESSING_ERROR = a named, deterministic failure — retrying the same file cannot help; INTERNAL_ERROR = crashed or never started, so retry.",
+            "description": "Enum of possible error codes.\n",
             "enum": [
               "VALIDATION_BLOCKED",
-              "PROCESSING_ERROR",
+              "FILE_FORMAT_UNSUPPORTED",
+              "FILE_UNAVAILABLE",
+              "VALIDATE_TIMEOUT",
+              "IMPORT_TIMEOUT",
+              "USE_CASE_NOT_USABLE",
+              "IMPORT_NO_PROGRESS",
               "INTERNAL_ERROR"
             ]
           },
@@ -4125,7 +4208,7 @@
           },
           "status": {
             "type": "string",
-            "description": "PENDING → VALIDATING → READY → PROCESSING → IMPORTED, with FAILED reachable from any working status, and CANCELLING → CANCELLED reachable from VALIDATING or PROCESSING via :abort. IMPORTED, FAILED and CANCELLED are terminal and final.\nIMPORTED means every row was handed to the platform, not that the platform finished — per-row outcomes live in monitoring, filtered by correlation_id. A file that fails validation is FAILED with error.type = VALIDATION_BLOCKED.\nREADY is legitimately idle for as long as the user takes to confirm, so it carries no running work and never goes stale.\nCANCELLING is transient and cooperative: the abort has been recorded but the worker only notices at its next batch boundary. Rows already published stay published — a stop is not a rollback.",
+            "description": "PENDING → VALIDATING → READY → PROCESSING → IMPORTED, with FAILED reachable from any working status, and CANCELLING → CANCELLED reachable from VALIDATING or PROCESSING via :abort. IMPORTED, FAILED and CANCELLED are terminal and final.\nIMPORTED means every row was handed to the platform, not that the platform finished — per-row outcomes live in monitoring, filtered by correlation_id. A file that fails validation is FAILED with error.code = VALIDATION_BLOCKED.\nREADY is legitimately idle for as long as the user takes to confirm, so it carries no running work and never goes stale.\nCANCELLING is transient and cooperative: the abort has been recorded but the worker only notices at its next batch boundary. Rows already published stay published — a stop is not a rollback.",
             "enum": [
               "PENDING",
               "VALIDATING",

package/dist/bin/epilot.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   API_LIST
-} from "../chunk-5Y4OYCNI.js";
+} from "../chunk-CR6NZAXB.js";
 
 // bin/epilot.ts
 import { runMain } from "citty";
@@ -11,7 +11,7 @@ import { defineCommand } from "citty";
 var main = defineCommand({
   meta: {
     name: "epilot",
-    version: "0.1.98",
+    version: "0.1.101",
     description: "CLI for epilot APIs"
   },
   args: {
@@ -30,8 +30,8 @@ var main = defineCommand({
     auth: () => import("../auth-WMXFMPWE.js").then((m) => m.default),
     profile: () => import("../profile-OZJL5ZPT.js").then((m) => m.default),
     config: () => import("../config-DGZIMLZK.js").then((m) => m.default),
-    completion: () => import("../completion-W5V6EYUZ.js").then((m) => m.default),
-    upgrade: () => import("../upgrade-S2DSGM2Z.js").then((m) => m.default),
+    completion: () => import("../completion-JKVTLZX7.js").then((m) => m.default),
+    upgrade: () => import("../upgrade-SWIOU3HC.js").then((m) => m.default),
     "access-token": () => import("../access-token-WWE6BDJH.js").then((m) => m.default),
     address: () => import("../address-EH3C4CVB.js").then((m) => m.default),
     "address-suggestions": () => import("../address-suggestions-RRSLOBFW.js").then((m) => m.default),
@@ -134,13 +134,13 @@ process.stderr.on("error", (err) => {
   if (err.code === "EPIPE") process.exit(0);
   throw err;
 });
-var VERSION = true ? "0.1.98" : (await null).default.version;
+var VERSION = true ? "0.1.101" : (await null).default.version;
 var reorderedArgv = hoistFlagsAfterSubcommand(process.argv.slice(2));
 process.argv = [process.argv[0], process.argv[1], ...reorderedArgv];
 var args = process.argv.slice(2);
 var completionsIdx = args.indexOf("--_completions");
 if (completionsIdx >= 0) {
-  const { handleCompletions } = await import("../completion-W5V6EYUZ.js");
+  const { handleCompletions } = await import("../completion-JKVTLZX7.js");
   handleCompletions(args[completionsIdx + 1], args[completionsIdx + 2]);
   process.exit(0);
 }

package/dist/{chunk-5Y4OYCNI.js → chunk-CR6NZAXB.js}

@@ -485,13 +485,24 @@ var API_LIST = [
     kebabName: "dashboard",
     title: "Dashboard API",
     serverUrl: "https://dashboard.sls.epilot.io",
-    operationCount: 7,
+    operationCount: 18,
     operationIds: [
       "listDashboards",
       "createDashboard",
+      "listFavoriteDashboardIds",
+      "favoriteDashboard",
+      "unfavoriteDashboard",
       "getDashboard",
       "putDashboard",
+      "patchDashboard",
       "deleteDashboard",
+      "listInsights",
+      "createInsight",
+      "listInsightTags",
+      "getInsight",
+      "putInsight",
+      "patchInsight",
+      "deleteInsight",
       "listAvailableVisualisations",
       "listAvailableExamples"
     ]

package/dist/{completion-W5V6EYUZ.js → completion-JKVTLZX7.js}

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   API_LIST
-} from "./chunk-5Y4OYCNI.js";
+} from "./chunk-CR6NZAXB.js";
 import {
   DIM,
   GREEN,

package/dist/{upgrade-S2DSGM2Z.js → upgrade-SWIOU3HC.js}

@@ -72,7 +72,7 @@ ${GREEN}${BOLD}Upgraded to @epilot/cli@${latest}${RESET}
   }
 });
 var getCurrentVersion = () => {
-  if (true) return "0.1.98";
+  if (true) return "0.1.101";
   try {
     const output = execSync("npm ls -g @epilot/cli --depth=0 --json 2>/dev/null", {
       encoding: "utf-8",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@epilot/cli",
-  "version": "0.1.98",
+  "version": "0.1.101",
   "description": "CLI for epilot APIs",
   "type": "module",
   "bin": {