@pitcher/cli-scripts 2.19.0 → 2.20.1

package/dist/src/commands/analytics.d.ts

@@ -22,7 +22,9 @@ export interface AnalyticsKpiOpts extends CommonOpts {
  * org/instance rollups (Django), this hits `clickhouse.pitcher.com` with the
  * org api-key; the caller inherits the key user's real role. Dates are required
  * by the server for activity-metric types (inventory counts like
- * `total-members` need none) — that validation stays server-side.
+ * `total-members` need none) — that validation stays server-side, as does the
+ * set of valid `type` values (a bad one comes back as a 400 listing them). There
+ * is no aggregate `all` type, so `--type` is required.
  */
 export declare function runAnalyticsKpi(opts: AnalyticsKpiOpts, deps?: AnalyticsDeps): Promise<Envelope<unknown>>;
 export interface AnalyticsEngagementOpts extends CommonOpts {

package/dist/src/commands/analytics.js

@@ -32,16 +32,20 @@ export async function runAnalyticsInstance(opts, deps = {}) {
  * org/instance rollups (Django), this hits `clickhouse.pitcher.com` with the
  * org api-key; the caller inherits the key user's real role. Dates are required
  * by the server for activity-metric types (inventory counts like
- * `total-members` need none) — that validation stays server-side.
+ * `total-members` need none) — that validation stays server-side, as does the
+ * set of valid `type` values (a bad one comes back as a 400 listing them). There
+ * is no aggregate `all` type, so `--type` is required.
  */
 export async function runAnalyticsKpi(opts, deps = {}) {
     try {
         if (!opts.instanceId)
             throw createCliError('VALIDATION', '--instance-id is required for analytics kpi');
+        if (!opts.type)
+            throw createCliError('VALIDATION', '--type is required for analytics kpi');
         const client = clickhouseClientFor(opts, deps);
         const params = {
             instance_id: opts.instanceId,
-            type: opts.type || 'all',
+            type: opts.type,
         };
         if (opts.startDate)
             params.start_date = opts.startDate;
@@ -376,7 +380,7 @@ export function createAnalyticsCommand() {
     });
     withAuthFlags(cmd.command('kpi'))
         .option('--instance-id <id>', 'Instance ID (required)')
-        .option('--type <type>', "KPI type, e.g. total-members, total-active-users (default 'all')")
+        .option('--type <type>', 'KPI type, e.g. total-members, total-active-users (required)')
         .option('--start-date <iso>', 'Window start (ISO date; required by the server for activity metrics)')
         .option('--end-date <iso>', 'Window end (ISO date; required by the server for activity metrics)')
         .option('--group-ids <csv>', 'Comma-separated distribution-group IDs to scope by')

package/dist/src/mcp/prompts/analytics.js

@@ -79,6 +79,9 @@ export const analyticsPrompts = [
                 '1. Call `pitcher_analytics_viewers` with the `canvasId` to list viewers and their per-viewer engagement.',
                 '2. To drill into a specific viewer, call `pitcher_analytics_sessions` with the same `canvasId` plus that viewer’s ' +
                     '`userEmail` (both come from step 1) to get their raw session event timeline.',
+                '   A session is one `Entered` of the queried id itself (canvas or section), paired by `event_pair_id`; ' +
+                    'an `Entered` with an empty `event_pair_id` counts as one session on its own. ' +
+                    'Sections listed by `pitcher_analytics_canvases` are valid `canvasId` inputs for both tools.',
                 '3. Summarize who viewed, how much they engaged, and — if you drilled in — what that viewer did. Works with a member key.',
             ].join('\n');
             return [{ role: 'user', content: { type: 'text', text } }];

package/dist/src/mcp/resources/analyticsCatalog.d.ts

@@ -1,3 +1,3 @@
 import type { ResourceDescriptor } from './types.js';
-export declare const ANALYTICS_CATALOG = "# Pitcher analytics catalog\n\nTen read-only verbs, each an MCP tool named `pitcher_analytics_<verb>`. Pick the verb that matches the\nquestion, then call its tool. All are read-only; org scope + auth come from the server's API key (never a\ntool input) \u2014 you only pass `instanceId` (and, where noted, `canvasId`/`userEmail`).\n\n## Key tiers\n- **org-admin key required:** org, popularity, users, files, canvases\n- **instance-admin or org-admin:** instance\n- **member key OK (access follows the key user's real role):** kpi, engagement, viewers, sessions\n\n## Time model\n- **Rollup (no window):** org, instance \u2014 lifetime/current totals.\n- **Date-range, 30-day default:** kpi (activity types need dates), engagement, popularity, `users` with\n  `stats: true`, files, canvases \u2014 omit dates to get the last 30 days. (`users` without `stats` is a\n  full roster with no window.)\n- **Date-range, server default window:** viewers, sessions \u2014 omit dates and the service picks the window.\n\n## Verbs\n\n| Verb (tool) | Returns | Time | Key | Example question |\n|---|---|---|---|---|\n| `org` | Organization-wide rollup totals (Django) | rollup | org-admin | \"How is the whole org doing overall?\" |\n| `instance` | Single-instance rollup totals (Django) | rollup | instance-admin | \"Totals for this one workspace?\" |\n| `kpi` | KPI metrics for an instance (members, active users, \u2026) | date-range | member | \"How many active users last month?\" |\n| `engagement` | Per-DSR/content engagement rows (capped list + summary) | date-range | member | \"Which content is being engaged with?\" |\n| `popularity` | Most-viewed canvases, ranked (view-analysis) | date-range | org-admin | \"Top 10 most-viewed decks this quarter?\" |\n| `users` | User roster, or active-user stats with `stats: true` | roster: none / stats: date-range | org-admin | \"Who are my active users this month?\" |\n| `files` | File usage analytics (views/opens/engagement per file) | date-range | org-admin | \"Which files get opened the most?\" |\n| `canvases` | Per-section canvas engagement list | date-range | org-admin | \"How are my canvas sections performing?\" |\n| `viewers` | Who viewed a specific DSR canvas (per-viewer engagement) | date-range | member | \"Who viewed this DSR, and how much?\" |\n| `sessions` | One viewer's session event timeline for a DSR canvas (raw) | date-range | member | \"What did this viewer do inside the DSR?\" |\n\n## Shaping\nRow-heavy verbs (engagement, popularity, users, files, canvases, viewers) return a capped envelope:\n`summary` + `rows` (default 20, max 100 \u2014 raise with `limit`) + `total_count`/`returned`/`has_more`,\nand a `truncated` note when more rows exist. `kpi` and `sessions` return the raw payload (a KPI scalar set\nand an uncapped event timeline, respectively) \u2014 never truncated.\n\n## DSR drill-down\nFor \"who viewed X and what did they do\": call `viewers` (with `canvasId`) to list viewers, then `sessions`\n(with the same `canvasId` + the viewer's `userEmail`) to see that viewer's event timeline.\n\n## Notes\n- `popularity` maps to the canvases view-analysis endpoint (there is no separate popularity route).\n- Results can include user identities/emails \u2014 treat as customer data and handle per policy.\n";
+export declare const ANALYTICS_CATALOG = "# Pitcher analytics catalog\n\nTen read-only verbs, each an MCP tool named `pitcher_analytics_<verb>`. Pick the verb that matches the\nquestion, then call its tool. All are read-only; org scope + auth come from the server's API key (never a\ntool input) \u2014 you only pass `instanceId` (and, where noted, `canvasId`/`userEmail`).\n\n## Key tiers\n- **org-admin key required:** org, popularity, users, files, canvases\n- **instance-admin or org-admin:** instance\n- **member key OK (access follows the key user's real role):** kpi, engagement, viewers, sessions\n\n## Time model\n- **Rollup (no window):** org, instance \u2014 lifetime/current totals.\n- **Date-range, 30-day default:** kpi (activity types need dates), engagement, popularity, `users` with\n  `stats: true`, files, canvases \u2014 omit dates to get the last 30 days. (`users` without `stats` is a\n  full roster with no window.)\n- **Date-range, server default window:** viewers, sessions \u2014 omit dates and the service picks the window.\n\n## Verbs\n\n| Verb (tool) | Returns | Time | Key | Example question |\n|---|---|---|---|---|\n| `org` | Organization-wide rollup totals (Django) | rollup | org-admin | \"How is the whole org doing overall?\" |\n| `instance` | Single-instance rollup totals (Django) | rollup | instance-admin | \"Totals for this one workspace?\" |\n| `kpi` | KPI metrics for an instance (members, active users, \u2026) | date-range | member | \"How many active users last month?\" |\n| `engagement` | Per-DSR/content engagement rows (capped list + summary) | date-range | member | \"Which content is being engaged with?\" |\n| `popularity` | Most-viewed canvases, ranked (view-analysis) | date-range | org-admin | \"Top 10 most-viewed decks this quarter?\" |\n| `users` | User roster, or active-user stats with `stats: true` | roster: none / stats: date-range | org-admin | \"Who are my active users this month?\" |\n| `files` | File usage analytics (views/opens/engagement per file) | date-range | org-admin | \"Which files get opened the most?\" |\n| `canvases` | Per-section canvas engagement list | date-range | org-admin | \"How are my canvas sections performing?\" |\n| `viewers` | Who viewed a specific DSR canvas (per-viewer engagement) | date-range | member | \"Who viewed this DSR, and how much?\" |\n| `sessions` | One viewer's session event timeline for a DSR canvas (raw) | date-range | member | \"What did this viewer do inside the DSR?\" |\n\n## Shaping\nRow-heavy verbs (engagement, popularity, users, files, canvases, viewers) return a capped envelope:\n`summary` + `rows` (default 20, max 100 \u2014 raise with `limit`) + `total_count`/`returned`/`has_more`,\nand a `truncated` note when more rows exist. `kpi` and `sessions` return the raw payload (a KPI scalar set\nand an uncapped event timeline, respectively) \u2014 never truncated.\n\n## DSR drill-down\nFor \"who viewed X and what did they do\": call `viewers` (with `canvasId`) to list viewers, then `sessions`\n(with the same `canvasId` + the viewer's `userEmail`) to see that viewer's event timeline.\nA session is one `Entered` of the queried id itself (a canvas or a section), paired by `event_pair_id`; an\n`Entered` with an empty `event_pair_id` counts as one session on its own.\n`session_count` is counted the same way as the overview's `total_sessions`. `canvases` lists sections, and their\nids are valid `canvasId` inputs for `viewers` and `sessions`.\n\n## Notes\n- `popularity` maps to the canvases view-analysis endpoint (there is no separate popularity route).\n- Results can include user identities/emails \u2014 treat as customer data and handle per policy.\n";
 export declare const analyticsCatalogResource: ResourceDescriptor;

package/dist/src/mcp/resources/analyticsCatalog.js

@@ -45,6 +45,10 @@ and an uncapped event timeline, respectively) — never truncated.
 ## DSR drill-down
 For "who viewed X and what did they do": call \`viewers\` (with \`canvasId\`) to list viewers, then \`sessions\`
 (with the same \`canvasId\` + the viewer's \`userEmail\`) to see that viewer's event timeline.
+A session is one \`Entered\` of the queried id itself (a canvas or a section), paired by \`event_pair_id\`; an
+\`Entered\` with an empty \`event_pair_id\` counts as one session on its own.
+\`session_count\` is counted the same way as the overview's \`total_sessions\`. \`canvases\` lists sections, and their
+ids are valid \`canvasId\` inputs for \`viewers\` and \`sessions\`.
 
 ## Notes
 - \`popularity\` maps to the canvases view-analysis endpoint (there is no separate popularity route).

package/dist/src/mcp/tools/analytics.js

@@ -25,7 +25,7 @@ export const analyticsTools = [
             '(inventory counts like total-members do not).',
         inputShape: {
             instanceId: z.string().describe('Instance ID (required)'),
-            type: z.string().optional().describe("KPI type, e.g. total-members, total-active-users (default 'all')"),
+            type: z.string().describe('KPI type, e.g. total-members, total-active-users (required)'),
             startDate: z.string().optional().describe('Window start, ISO date (required by the server for activity metrics)'),
             endDate: z.string().optional().describe('Window end, ISO date (required by the server for activity metrics)'),
             groupIds: z.string().optional().describe('Comma-separated distribution-group IDs to scope by'),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pitcher/cli-scripts",
-  "version": "2.19.0",
+  "version": "2.20.1",
   "description": "The Pitcher CLI for various tasks in its ecosystem.",
   "author": "Pitcher AG",
   "license": "MIT",