@pitcher/cli-scripts 2.20.0 → 2.21.0

package/README.md

@@ -2,6 +2,8 @@
 
 > Pitcher CLI Tools provide a suite of command-line utilities to streamline your workflow. For the best experience, we recommend installing the tools globally using `npm install -g @pitcher/cli-scripts`.
 
+Releases are published to npm automatically: a merge to `main` that bumps `version` in `package.json` publishes that version, and a merge without a bump publishes nothing (`.github/workflows/cli-scripts-publish.yml`; release flow in `CLAUDE.md`).
+
 ## Help
 
 ```bash
@@ -223,15 +225,12 @@ p canvases get 01CANVASID... --api-key myapikey
 
 ## To run the `shared-links` command:
 
-Create and read share links for canvases or files (returns the `short_url`).
+Create and read share links for canvases (returns the `short_url`).
 
 ```bash
 # Create a share link for a canvas
 p shared-links create --canvas-id 01CANVASID... --api-key myapikey
 
-# Create a share link for a file
-p shared-links create --file-id 01FILEID... --api-key myapikey
-
 # Fetch the existing share link for a canvas
 p shared-links get --canvas-id 01CANVASID... --api-key myapikey
 ```

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

@@ -7,10 +7,8 @@ export interface SharedLinksDeps {
 }
 export declare function runSharedLinksCreate(opts: CommonOpts & {
     canvasId?: string;
-    fileId?: string;
 }, deps?: SharedLinksDeps): Promise<Envelope<unknown>>;
 export declare function runSharedLinksGet(opts: CommonOpts & {
     canvasId?: string;
-    fileId?: string;
 }, deps?: SharedLinksDeps): Promise<Envelope<unknown>>;
 export declare function createSharedLinksCommand(): Command;

package/dist/src/commands/sharedLinks.js

@@ -4,22 +4,17 @@ import { ok, fail } from '../core/envelope.js';
 import { createCliError } from '../core/errors.js';
 import { emitEnvelope } from '../core/output.js';
 import { withAuthFlags } from './withAuth.js';
-/** Enforce exactly one of --canvas-id / --file-id. Scope is derived from the target. */
-function requireOneTarget(opts) {
-    if (opts.canvasId && opts.fileId)
-        throw createCliError('VALIDATION', 'pass exactly one of --canvas-id or --file-id');
-    if (opts.canvasId)
-        return 'canvas';
-    if (opts.fileId)
-        return 'file';
-    throw createCliError('VALIDATION', 'pass exactly one of --canvas-id or --file-id');
+/** Only canvases can be shared. */
+function requireCanvasId(opts) {
+    if (!opts.canvasId)
+        throw createCliError('VALIDATION', '--canvas-id is required');
+    return opts.canvasId;
 }
 export async function runSharedLinksCreate(opts, deps = {}) {
     try {
-        const target = requireOneTarget(opts);
+        const canvasId = requireCanvasId(opts);
         const client = clientFor(opts, deps);
-        const body = target === 'canvas' ? { canvas_id: opts.canvasId } : { file_id: opts.fileId };
-        const res = await client.post('/api/v1/shared-links/', body);
+        const res = await client.post('/api/v1/shared-links/', { canvas_id: canvasId });
         return ok(res.data);
     }
     catch (e) {
@@ -28,13 +23,10 @@ export async function runSharedLinksCreate(opts, deps = {}) {
 }
 export async function runSharedLinksGet(opts, deps = {}) {
     try {
-        const target = requireOneTarget(opts);
+        const canvasId = requireCanvasId(opts);
         const client = clientFor(opts, deps);
         // encodeURIComponent so an id containing `/` or `..` can't retarget the request path
-        const path = target === 'canvas'
-            ? `/api/v1/shared-links/canvas/${encodeURIComponent(opts.canvasId)}`
-            : `/api/v1/shared-links/file/${encodeURIComponent(opts.fileId)}`;
-        const res = await client.get(path);
+        const res = await client.get(`/api/v1/shared-links/canvas/${encodeURIComponent(canvasId)}`);
         return ok(res.data);
     }
     catch (e) {
@@ -42,17 +34,15 @@ export async function runSharedLinksGet(opts, deps = {}) {
     }
 }
 export function createSharedLinksCommand() {
-    const cmd = new Command('shared-links').description('create and read share links for canvases and files');
+    const cmd = new Command('shared-links').description('create and read share links for canvases');
     withAuthFlags(cmd.command('create'))
         .option('--canvas-id <id>', 'Canvas to share')
-        .option('--file-id <id>', 'File to share')
         .action(async (options, command) => {
         const globals = command.optsWithGlobals();
         emitEnvelope(await runSharedLinksCreate({ ...options, quiet: globals.quiet }), globals);
     });
     withAuthFlags(cmd.command('get'))
         .option('--canvas-id <id>', 'Canvas whose link to fetch')
-        .option('--file-id <id>', 'File whose link to fetch')
         .action(async (options, command) => {
         const globals = command.optsWithGlobals();
         emitEnvelope(await runSharedLinksGet({ ...options, quiet: globals.quiet }), globals);

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/sharedLinks.js

@@ -4,10 +4,9 @@ export const sharedLinksTools = [
     {
         name: 'pitcher_shared_links_create',
         title: 'Create a shared link',
-        description: 'Create a share link (short_url) for a canvas or a file. Pass exactly one of canvasId or fileId. Additive.',
+        description: 'Create a share link (short_url) for a canvas. Only canvases can be shared. Additive.',
         inputShape: {
-            canvasId: z.string().optional().describe('Canvas to share (exactly one of canvasId/fileId is required)'),
-            fileId: z.string().optional().describe('File to share (exactly one of canvasId/fileId is required)'),
+            canvasId: z.string().describe('Canvas to share'),
         },
         run: runSharedLinksCreate,
         readOnly: false,
@@ -16,10 +15,9 @@ export const sharedLinksTools = [
     {
         name: 'pitcher_shared_links_get',
         title: 'Get a shared link',
-        description: 'Retrieve the existing share link for a canvas or a file. Pass exactly one of canvasId or fileId.',
+        description: 'Retrieve the existing share link for a canvas.',
         inputShape: {
-            canvasId: z.string().optional().describe('Canvas whose link to fetch (exactly one of canvasId/fileId is required)'),
-            fileId: z.string().optional().describe('File whose link to fetch (exactly one of canvasId/fileId is required)'),
+            canvasId: z.string().describe('Canvas whose link to fetch'),
         },
         run: runSharedLinksGet,
         readOnly: true,

package/package.json

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