@epilot/cli 0.1.118 → 0.1.119

package/README.md

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

package/definitions/message.json

@@ -585,7 +585,7 @@
       "post": {
         "operationId": "getUnreadCounts",
         "summary": "getUnreadCounts",
-        "description": "Unread counts for several named scopes in one request.\n\nA scope is a name plus the same parameters the thread list already takes (`q`, `inbox_id`),\nso a scope's count and the list beneath it are the same predicate and agree by construction.\nThe server adds only the read-state condition; it does not re-author the caller's view.\n\nThe `organization` scope is the exception and takes no `q`: it reuses the four canonical\ncentral-inbox queries, so its numbers match `getUnread` exactly.\n\nBuckets are not symmetric, across scope types or across actors. Every scope other than\n`organization` returns `unread` alone. The `organization` scope returns all four\n(`unread`, `drafts`, `unassigned`, `spam`) for `actor: organization`, and only `unread` and\n`drafts` for `actor: user` — the agent sidebar has no Spam or Unlinked folder, so those two\nnumbers have nowhere to render and each one costs a cardinality aggregation. This is a\ndeliberate divergence from `getUnread`, which computes all four for both actors.\n\nGated on the `message-unread-counts` flag, evaluated once per request against the calling\norg. With the flag off the response is `{ \"enabled\": false, \"counts\": {} }` and no\nElasticsearch query is issued.\n",
+        "description": "Unread counts for several named scopes in one request.\n\nA scope is a name plus the same parameters the thread list already takes (`q`, `inbox_id`),\nso a scope's count and the list beneath it are the same predicate and agree by construction.\nThe server adds only the read-state condition; it does not re-author the caller's view.\n\nThe `organization` scope is the exception and takes no `q`: it reuses the four canonical\ncentral-inbox queries, so its numbers match `getUnread` exactly.\n\nWhich buckets come back varies by scope type and actor. Every scope other than `organization`\nreturns `unread` alone. An `organization` scope returns all four (`unread`, `drafts`,\n`unassigned`, `spam`) for `actor: organization`, and `unread` and `drafts` only for\n`actor: user`. `getUnread` returns all four for both actors; this endpoint omits the two that\nno per-user surface renders, since each costs an aggregation.\n\nGated on the `message-unread-counts` flag, evaluated once per request against the calling\norg. With the flag off the response is `{ \"enabled\": false, \"counts\": {} }` and no\nElasticsearch query is issued.\n",
         "tags": [
           "Messages"
         ],
@@ -611,7 +611,7 @@
             }
           },
           "400": {
-            "description": "The request names more scopes than the cap allows, repeats a scope name, or omits `q`\non a scope type that requires it. Over-cap requests are refused rather than truncated:\na silently dropped scope renders as a missing badge, which is indistinguishable from\nzero unread.\n"
+            "description": "The request names more scopes than the cap allows, repeats a scope name, or omits both\n`q` and `view` on a scope type that needs a predicate. Over-cap requests are refused rather than truncated:\na silently dropped scope renders as a missing badge, which is indistinguishable from\nzero unread.\n"
           },
           "403": {
             "description": "Forbidden"
@@ -832,7 +832,7 @@
       "post": {
         "operationId": "getAssigneeWorkload",
         "summary": "getAssigneeWorkload",
-        "description": "Return the open-thread workload for a set of user ids.\n\nFor each requested user id, returns the number of *open* threads assigned\ndirectly to that user — matching what the user sees in their central-inbox\nopen view: in inbox, not trashed, not done, and excluding notification-only\nand spam threads.\n\nOnly threads assigned directly to a user are counted; threads assigned to a\ngroup the user belongs to are not. Intended for assignment load-balancing\n(e.g. even-distribution automations) that need a consistent, inbox-aligned\nworkload per user.\n",
+        "description": "Return the open-thread workload for a set of user ids.\n\nFor each requested user id, returns the number of *open* threads assigned\ndirectly to that user \u2014 matching what the user sees in their central-inbox\nopen view: in inbox, not trashed, not done, and excluding notification-only\nand spam threads.\n\nOnly threads assigned directly to a user are counted; threads assigned to a\ngroup the user belongs to are not. Intended for assignment load-balancing\n(e.g. even-distribution automations) that need a consistent, inbox-aligned\nworkload per user.\n",
         "tags": [
           "Threads"
         ],
@@ -2695,6 +2695,117 @@
           }
         }
       },
+      "ThreadView": {
+        "type": "object",
+        "additionalProperties": true,
+        "description": "A central-inbox view, described structurally so the server compiles the query for it. Both the\nthread list and the unread count for a view are compiled from the same description, so the two\ncannot disagree about what the view means.\n\nEvery field is optional and an omitted field adds no condition, so a view narrows the whole\nmailbox rather than being a template with required holes. Unknown fields are ignored.\n",
+        "properties": {
+          "folder": {
+            "type": "string",
+            "enum": [
+              "inbox",
+              "favorite",
+              "sent",
+              "trash",
+              "spam",
+              "unassignable",
+              "draft"
+            ],
+            "description": "Which sidebar folder's membership predicate to apply."
+          },
+          "mailbox": {
+            "type": "string",
+            "enum": [
+              "organization",
+              "agent"
+            ],
+            "description": "Whose mailbox this is. `agent` scopes to threads assigned to the caller or their groups;\n`organization` scopes to the org and is the only mailbox that carries address filtering.\n"
+          },
+          "labels": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Saved-filter labels, ANDed. Matched exactly against the tag rather than against its\ntokens, so a label whose words overlap a folder tag no longer lands in that folder.\n"
+          },
+          "purposes": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Purpose ids on linked entities, ANDed."
+          },
+          "filters": {
+            "type": "array",
+            "items": {
+              "type": "string",
+              "enum": [
+                "unread",
+                "resolved",
+                "trash"
+              ]
+            },
+            "description": "State filters, independent of the folder. `resolved` and `trash` reach the Inbox folder\nonly and are mutually exclusive there; `unread` applies anywhere.\n"
+          },
+          "from": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Sender addresses to filter on."
+          },
+          "to": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Recipient addresses to filter on."
+          },
+          "assigned_to": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Assignee user ids."
+          },
+          "include_unassigned": {
+            "type": "boolean",
+            "description": "Whether threads with no assignee join the `assigned_to` set. A separate flag rather than a\nsentinel entry in that list, so `assigned_to` holds user ids and nothing else.\n"
+          },
+          "date_from_days_ago": {
+            "type": "integer",
+            "minimum": 0,
+            "description": "Lower bound of the date range, in days before now. Omitted means the epoch."
+          },
+          "date_to_days_ago": {
+            "type": "integer",
+            "minimum": 0,
+            "description": "Upper bound of the date range, in days before now. Omitted means now."
+          },
+          "email_filter": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Addresses the user selected in the address filter. Absent and empty differ, and the\ndifference is a real UI state: absent is \"not filtering by address\", empty is \"every\naddress deselected\", which matches nothing.\n\nDistinct from the permission restriction, which the server derives and a caller cannot\nauthor.\n"
+          },
+          "text": {
+            "type": "string",
+            "description": "The user's search string, as typed. Expanded across the searched fields server-side and\nnever interpreted as query syntax, so a typed operator or a stray bracket cannot\nre-associate the predicate around it.\n"
+          },
+          "thread_ids": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Restrict the view to these threads. Exists because \"would this thread appear in the view\nthe user is looking at?\" is a real question the inbox asks when a new thread arrives, and\nit is a membership test against the view rather than a different view.\n"
+          },
+          "pinned_by": {
+            "type": "string",
+            "description": "Restrict the view to threads this user pinned. The pinned strip above the list is the same\nview with this one extra condition.\n"
+          }
+        }
+      },
       "UnreadCountScope": {
         "type": "object",
         "required": [
@@ -2714,13 +2825,18 @@
               "shared_inbox",
               "saved_view"
             ],
-            "description": "Decides which buckets come back, and whether `q` is required. `organization` returns all\nfour buckets from the canonical central-inbox queries and takes no `q`. `shared_inbox`\nand `saved_view` return `unread` alone and require the `q` their list uses.\n\nA `shared_inbox` scope additionally requires `actor: organization` and is refused with a\n400 otherwise. A shared inbox is an organization-level construct — selecting one always\nswitches the mailbox to the organization — so it has no per-user read state and the\ncombination would compute a number no surface renders. `saved_view` accepts either actor,\nbecause a view's own configuration names its mailbox.\n"
+            "description": "Decides which buckets come back, and whether `q` is required. `organization` returns all\nfour buckets from the canonical central-inbox queries and takes no `q`. `shared_inbox`\nand `saved_view` return `unread` alone. A `saved_view` scope names its view with `view_id`;\na `shared_inbox` scope needs only its `inbox_id`, since the query follows from the type.\n\nA `shared_inbox` scope additionally requires `actor: organization` and is refused with a\n400 otherwise. A shared inbox is an organization-level construct \u2014 selecting one always\nswitches the mailbox to the organization \u2014 so it has no per-user read state and the\ncombination would compute a number no surface renders. `saved_view` accepts either actor,\nbecause a view's own configuration names its mailbox.\n"
           },
           "q": {
             "type": "string",
-            "description": "The scope's own list predicate, in Lucene syntax, exactly as the caller passes it to\n`threads:search`. Required for `shared_inbox` and `saved_view`, rejected for\n`organization`. The server ANDs the read-state condition onto it and nothing else, which\nis what makes the count and the list agree. Until the predicate definition moves\nserver-side, this is the caller's authored copy.\n",
+            "description": "The scope's query, in Lucene syntax, as passed to `threads:search` for the same scope. The\nserver adds the read-state condition and nothing else, so the count matches that list.\n\nAccepted for `shared_inbox` and `saved_view`; rejected for `organization`.\n\nSuperseded by server-side compilation. It remains accepted for callers whose counts are\nenabled while compilation is not, and is ignored when compilation is enabled. It will be\nremoved once compilation is enabled everywhere counts are.\n",
             "example": "_tags.keyword:inbox AND !_tags.keyword:trash"
           },
+          "view_id": {
+            "type": "string",
+            "description": "The id of the saved view this scope counts. The server reads that view and compiles the same\nquery the thread list runs for it, so the count and the list cannot describe the view\ndifferently.\n\nRequired for `saved_view` scopes unless `q` is supplied instead; rejected for the other two\ntypes. A `shared_inbox` scope needs no predicate field at all, because its query follows from\nthe type and its `inbox_id`. An `organization` scope uses the canonical folder queries.\n\nThe view's own shared-inbox filter is read from the stored view, so `inbox_id` need not be\nsent alongside this.\n\nCompilation is enabled per organization by the `message-unread-unified-predicate` feature\nflag. While it is off, a scope supplying only a `view_id` has no query to run and its name is\nreturned in `omitted` rather than counted. A named view that this organization does not have,\nor whose stored configuration cannot be read, is omitted the same way.\n",
+            "example": "3f34ce73-089c-4d45-a5ee-c161234e41c3"
+          },
           "inbox_id": {
             "description": "Shared inbox ids, resolved to bucket ids the same way `threads:search` resolves them.",
             "oneOf": [
@@ -2751,7 +2867,7 @@
               "organization",
               "user"
             ],
-            "description": "Which read state to count against — the org's or the calling user's. Same meaning as\n`getUnread`'s path parameter, and unrelated to a scope's `type`.\n"
+            "description": "Which read state to count against \u2014 the org's or the calling user's. Same meaning as\n`getUnread`'s path parameter, and unrelated to a scope's `type`.\n"
           },
           "email_filter": {
             "type": "array",
@@ -2760,6 +2876,13 @@
             },
             "description": "Restrict every scope to messages involving these addresses."
           },
+          "user_groups": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "The caller's group ids, as `group_<id>`, with the same meaning and constraints as on\n`threads:search`. Read only when a scope carries a `view`. Entries not matching\n`group_<id>` are dropped. Not an authorization input.\n"
+          },
           "scopes": {
             "type": "array",
             "minItems": 1,
@@ -2791,7 +2914,7 @@
           },
           "omitted": {
             "type": "array",
-            "description": "Names of scopes that were accepted but could not be counted — today, a shared inbox whose\nids matched no bucket in this org. Listed explicitly so a caller can tell an omission apart\nfrom a mis-spelled scope name, both of which are otherwise just a missing key in `counts`.\n",
+            "description": "Names of scopes that were accepted but could not be counted. Each appears here and is\nabsent from `counts`, so an omission is distinguishable from a mis-spelled scope name.\n\nCauses, not distinguishable from this field: a `shared_inbox` scope whose ids matched no\nbucket in the organization; a scope with no query to run because compilation is disabled for\nthe organization and no `q` was supplied; and a `view_id` naming a view this organization\ndoes not have or whose stored configuration cannot be read.\n",
             "items": {
               "type": "string"
             }
@@ -2827,9 +2950,6 @@
       },
       "SearchParamsV2": {
         "type": "object",
-        "required": [
-          "q"
-        ],
         "properties": {
           "inbox_id": {
             "oneOf": [
@@ -2852,10 +2972,25 @@
             ]
           },
           "q": {
-            "description": "Lucene query syntax supported with ElasticSearch",
+            "description": "Lucene query syntax supported with ElasticSearch.\n\nSend this or `view`, not both. At least one is required; a request with neither is refused\nwith a 400. An empty string is accepted and returns no hits.\n",
             "type": "string",
             "example": "subject:\"Request for solar panel price\" AND _tags:INBOX"
           },
+          "view": {
+            "allOf": [
+              {
+                "$ref": "#/components/schemas/ThreadView"
+              }
+            ],
+            "description": "A view for the server to compile into the query, instead of supplying `q`. When a view is\npresent and compilation is enabled for the calling organization, the compiled query runs and\n`q` is not consulted.\n\nRead by `threads:search` and `threads:searchIds` only. This schema is shared with\n`messages:search`, which compiles no view and ignores the field, so a request there must\nsupply `q`.\n\nCompilation is enabled per organization by the `message-unread-unified-predicate` feature\nflag. While it is off, `q` runs and a request supplying only a view returns no hits.\n"
+          },
+          "user_groups": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "The caller's group ids, as `group_<id>`. Read only when a `view` is compiled, where they\ndetermine the agent mailbox's assignee condition and which shared inboxes, and therefore\nwhich addresses, are reachable. Required for those conditions to be correct, because group\nmembership is not present on the id token this service parses.\n\nEntries not matching `group_<id>` are dropped.\n\nNot an authorization input, and not treated as one: naming groups the caller is not in\nwidens what the response includes, exactly as supplying a broader `q` does. Access control\nis enforced elsewhere.\n"
+          },
           "fields": {
             "$ref": "#/components/schemas/FieldsParam"
           },
@@ -2913,6 +3048,21 @@
       "SearchIDParams": {
         "type": "object",
         "properties": {
+          "view": {
+            "allOf": [
+              {
+                "$ref": "#/components/schemas/ThreadView"
+              }
+            ],
+            "description": "The view to compile, with the same meaning as on `threads:search`. Present here because\nthis endpoint returns the ordered id set *for that list*: if one compiled its view and the\nother ran an authored `q`, the two would disagree inside a single feature, which is the\ndrift this replaces.\n"
+          },
+          "user_groups": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "The caller's group ids, with the same meaning and caveats as on `threads:search`."
+          },
           "inbox_id": {
             "oneOf": [
               {
@@ -3160,7 +3310,7 @@
           },
           "label_name": {
             "type": "string",
-            "description": "Resolved taxonomy classification display name (e.g. `Verärgert`), when the label is a classification. Absent for free-form tags."
+            "description": "Resolved taxonomy classification display name (e.g. `Ver\u00e4rgert`), when the label is a classification. Absent for free-form tags."
           }
         }
       },
@@ -3183,7 +3333,7 @@
           },
           "label_name": {
             "type": "string",
-            "description": "Resolved taxonomy classification display name (e.g. `Verärgert`), when the label is a classification. Absent for free-form tags."
+            "description": "Resolved taxonomy classification display name (e.g. `Ver\u00e4rgert`), when the label is a classification. Absent for free-form tags."
           }
         }
       },
@@ -3400,7 +3550,7 @@
           "timestamp": {
             "type": "string",
             "description": "Timestamp of the event",
-            "example": "2024-01-01T00:00:00Z"
+            "example": "2024-01-01T00:00:00.000Z"
           },
           "message_id": {
             "type": "string",

package/dist/bin/epilot.js

@@ -11,7 +11,7 @@ import { defineCommand } from "citty";
 var main = defineCommand({
   meta: {
     name: "epilot",
-    version: "0.1.118",
+    version: "0.1.119",
     description: "CLI for epilot APIs"
   },
   args: {
@@ -31,7 +31,7 @@ var main = defineCommand({
     profile: () => import("../profile-OZJL5ZPT.js").then((m) => m.default),
     config: () => import("../config-DGZIMLZK.js").then((m) => m.default),
     completion: () => import("../completion-CPMUSY3E.js").then((m) => m.default),
-    upgrade: () => import("../upgrade-4B7QBPBL.js").then((m) => m.default),
+    upgrade: () => import("../upgrade-LASQG4TZ.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,7 +134,7 @@ process.stderr.on("error", (err) => {
   if (err.code === "EPIPE") process.exit(0);
   throw err;
 });
-var VERSION = true ? "0.1.118" : (await null).default.version;
+var VERSION = true ? "0.1.119" : (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);

package/dist/{upgrade-4B7QBPBL.js → upgrade-LASQG4TZ.js}

@@ -72,7 +72,7 @@ ${GREEN}${BOLD}Upgraded to @epilot/cli@${latest}${RESET}
   }
 });
 var getCurrentVersion = () => {
-  if (true) return "0.1.118";
+  if (true) return "0.1.119";
   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.118",
+  "version": "0.1.119",
   "description": "CLI for epilot APIs",
   "type": "module",
   "bin": {