@pitcher/cli-scripts 2.13.0 → 2.14.0

package/README.md

@@ -352,7 +352,7 @@ p org get --api-key myapikey
 
 ## To run the `analytics` command:
 
-Read rollup analytics totals for an organization or instance. Requires an org-admin API key — a non-admin key returns an auth error.
+Read rollup analytics totals (`org`/`instance`), KPI metrics, and content/user engagement analytics. `org`/`instance` are Django rollups; `kpi` and the 7 verbs below hit the **clickhouse-api** service (`clickhouse.pitcher.com`) via the same env resolution as everything else — `--org`/`--url` pick the environment (routed via `x-original-domain`). Access **follows the key user's real role**: `popularity`, `users`, `files`, and `canvases` need an **org-admin** key; `engagement`, `viewers`, and `sessions` work with a member key. `kpi` and `sessions` return the raw payload; the other row-heavy verbs return a shaped envelope (`summary`, `rows`, `total_count`, `returned`, `has_more`, and sometimes `truncated`/`warnings`) capped by `--limit` (default 20, max 100). Date-range verbs default to a **30-day window** when `--start-date`/`--end-date` are omitted. `viewers` and `sessions` require `--canvas-id`; `sessions` also requires `--user`.
 
 ```bash
 # Organization-wide rollups (org-admin key required)
@@ -368,6 +368,30 @@ p analytics instance --instance-id 01... --api-key myapikey
 p analytics kpi --instance-id 01... --type total-members --api-key myapikey
 p analytics kpi --instance-id 01... --type total-active-users \
   --start-date 2026-01-01 --end-date 2026-01-31 --api-key myapikey
+
+# DSR/content engagement rows (member key)
+p analytics engagement --instance-id 01... --engagement-level high --limit 50 --api-key myapikey
+
+# Most-viewed canvases / view-analysis (org-admin key)
+p analytics popularity --instance-id 01... --sort-by total_views --sort-order DESC --api-key myapikey
+
+# User roster (org-admin key)
+p analytics users --instance-id 01... --api-key myapikey
+
+# Active-user statistics instead of the roster (org-admin key)
+p analytics users --instance-id 01... --stats --start-date 2026-01-01 --end-date 2026-01-31 --api-key myapikey
+
+# File usage analytics (org-admin key)
+p analytics files --instance-id 01... --file-type pdf --sort-by views --sort-order desc --api-key myapikey
+
+# Per-section canvas engagement list (org-admin key)
+p analytics canvases --instance-id 01... --group-ids 01GROUPID... --api-key myapikey
+
+# DSR canvas viewers — who viewed a given canvas (member key)
+p analytics viewers --instance-id 01... --canvas-id 01CANVASID... --viewer-type external --api-key myapikey
+
+# Per-viewer session event timeline for a DSR canvas (member key)
+p analytics sessions --instance-id 01... --canvas-id 01CANVASID... --user rep@example.com --api-key myapikey
 ```
 
 ## To run the `users` command:

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

@@ -25,4 +25,152 @@ export interface AnalyticsKpiOpts extends CommonOpts {
  * `total-members` need none) — that validation stays server-side.
  */
 export declare function runAnalyticsKpi(opts: AnalyticsKpiOpts, deps?: AnalyticsDeps): Promise<Envelope<unknown>>;
+export interface AnalyticsEngagementOpts extends CommonOpts {
+    instanceId?: string;
+    startDate?: string;
+    endDate?: string;
+    limit?: number;
+    page?: number;
+    engagementLevel?: string;
+    search?: string;
+    view?: string;
+    groupIds?: string;
+    sortBy?: string;
+    sortOrder?: string;
+    hideMemberFiles?: boolean;
+}
+/**
+ * DSR/content engagement rows from the clickhouse-api analytics service.
+ * Row-heavy (member gate) — shaped through `shapeAnalytics` to cap the
+ * payload at `--limit` and surface a truncation notice, since the native
+ * response can carry hundreds of rows per page.
+ */
+export declare function runAnalyticsEngagement(opts: AnalyticsEngagementOpts, deps?: AnalyticsDeps): Promise<Envelope<unknown>>;
+export interface AnalyticsPopularityOpts extends CommonOpts {
+    instanceId?: string;
+    startDate?: string;
+    endDate?: string;
+    limit?: number;
+    page?: number;
+    sortBy?: string;
+    sortOrder?: string;
+    groupIds?: string;
+}
+/**
+ * Most-viewed canvases from the clickhouse-api analytics service. There is no
+ * dedicated `popularity` route — this maps to `GET /analytics/canvases/stats`
+ * with `type=view-analysis` forced (always sent, never taken from opts).
+ * Row-heavy, so shaped through `shapeAnalytics` like `engagement`.
+ */
+export declare function runAnalyticsPopularity(opts: AnalyticsPopularityOpts, deps?: AnalyticsDeps): Promise<Envelope<unknown>>;
+export interface AnalyticsUsersOpts extends CommonOpts {
+    instanceId?: string;
+    stats?: boolean;
+    limit?: number;
+    page?: number;
+    startDate?: string;
+    endDate?: string;
+    groupIds?: string;
+}
+/**
+ * User roster (default) or active-user statistics (`--stats`) from the
+ * clickhouse-api analytics service. The two branches hit different routes
+ * with different params — verified against `packages/clickhouse-api/src/routes/users.ts`:
+ *
+ * - Default → `GET /analytics/users/list`: `instance_id` only. Full roster,
+ *   no dates, no page size. (`show_internal_users` is resolved server-side
+ *   from an org LD flag — the route never reads it as a query param, so the
+ *   CLI does not expose it.)
+ * - `--stats` → `GET /analytics/users/stats`: requires `start_date`/`end_date`
+ *   (defaulted via `withDefaultWindow`), and `type` is ALWAYS forced to
+ *   `'active-users'` — the wire default `type=all` returns a shape with no
+ *   `.items`, which would otherwise silently shape to an empty row set. The
+ *   page-size param on this route is the camelCase `pageSize` (verified
+ *   `users.ts:230`) — the one route in the CLI that reads camelCase on the wire.
+ */
+export declare function runAnalyticsUsers(opts: AnalyticsUsersOpts, deps?: AnalyticsDeps): Promise<Envelope<unknown>>;
+export interface AnalyticsFilesOpts extends CommonOpts {
+    instanceId?: string;
+    startDate?: string;
+    endDate?: string;
+    limit?: number;
+    page?: number;
+    fileType?: string;
+    filter?: string;
+    sortBy?: string;
+    sortOrder?: string;
+    metadataFilters?: string;
+    groupIds?: string;
+    userEmails?: string;
+    hideMemberFiles?: boolean;
+}
+/**
+ * File usage analytics from the clickhouse-api analytics service. There is
+ * no dedicated "list" type on the wire — `type` is ALWAYS forced to `'all'`
+ * (verified `files.ts`/`files-analytics.service.ts`): the `default` branch of
+ * `getFileUsageAnalysisData` throws `Unsupported type`, and only `type=all`
+ * yields the paginated row list. `page_size` is snake_case on this
+ * route (unlike `users/stats`). `sort_order` must be uppercased on the wire —
+ * the server zod is `z.enum(['ASC','DESC'])`.
+ */
+export declare function runAnalyticsFiles(opts: AnalyticsFilesOpts, deps?: AnalyticsDeps): Promise<Envelope<unknown>>;
+export interface AnalyticsCanvasesOpts extends CommonOpts {
+    instanceId?: string;
+    startDate?: string;
+    endDate?: string;
+    limit?: number;
+    page?: number;
+    groupIds?: string;
+}
+/**
+ * Per-section canvas engagement list from the clickhouse-api analytics
+ * service. There is no dedicated "list" type on the wire — `type` is ALWAYS
+ * forced to `'section-list'` (verified `canvases.ts`/`canvases-analytics.service.ts`):
+ * `getCanvasAnalysisData` has exactly one supported case (`section-list`); its
+ * `default` branch throws `Unsupported type`, so any other value would hard-fail
+ * server-side. `--status`/`--filter` are deliberately NOT exposed — the
+ * `section-list` code path (`fetchSectionsList`) ignores `filter`/`search`/`status`
+ * entirely, so they'd be dead flags. There is also no `sort_order` on this route.
+ */
+export declare function runAnalyticsCanvases(opts: AnalyticsCanvasesOpts, deps?: AnalyticsDeps): Promise<Envelope<unknown>>;
+export interface AnalyticsViewersOpts extends CommonOpts {
+    instanceId?: string;
+    canvasId?: string;
+    limit?: number;
+    page?: number;
+    viewerType?: string;
+    sortBy?: string;
+    sortOrder?: string;
+    search?: string;
+    startDate?: string;
+    endDate?: string;
+}
+/**
+ * DSR canvas viewers (who-viewed) from the clickhouse-api analytics service.
+ * Maps to `GET /analytics/canvas-details/viewers` (member-gated, not admin) —
+ * verified `canvas-details.ts` ~L578-1147. Unlike the other row-heavy verbs,
+ * this route has its OWN server-side default window, so dates are NOT run
+ * through `withDefaultWindow` here — `start_date`/`end_date` are sent only
+ * when the caller supplies them. `sort_order` must be lowercased on the
+ * wire — the server zod is `z.enum(['asc','desc'])` (opposite of `files`,
+ * which uppercases). `sort_by` is validated client-side against the server
+ * enum so bad values fail fast with VALIDATION instead of a server 400.
+ */
+export declare function runAnalyticsViewers(opts: AnalyticsViewersOpts, deps?: AnalyticsDeps): Promise<Envelope<unknown>>;
+export interface AnalyticsSessionsOpts extends CommonOpts {
+    instanceId?: string;
+    canvasId?: string;
+    userEmail?: string;
+    startDate?: string;
+    endDate?: string;
+}
+/**
+ * Per-viewer session event timeline (DSR drill-down) from the clickhouse-api
+ * analytics service. Maps to `GET /analytics/canvas-details/sessions`
+ * (member-gated) — verified `canvas-details.ts` ~L1152-1329. Returns RAW
+ * (like `kpi`), NOT run through `shapeAnalytics` — an event timeline must not
+ * be truncated. Like `viewers`, this route has its own server-side default
+ * window, so dates are sent only when the caller supplies them.
+ */
+export declare function runAnalyticsSessions(opts: AnalyticsSessionsOpts, deps?: AnalyticsDeps): Promise<Envelope<unknown>>;
 export declare function createAnalyticsCommand(): Command;

package/dist/src/commands/analytics.js

@@ -4,6 +4,7 @@ import { ok, fail } from '../core/envelope.js';
 import { createCliError } from '../core/errors.js';
 import { emitEnvelope } from '../core/output.js';
 import { withAuthFlags } from './withAuth.js';
+import { shapeAnalytics, pageSizeFor, withDefaultWindow, todayIso } from '../core/analytics-shape.js';
 export async function runAnalyticsOrg(opts, deps = {}) {
     try {
         const client = clientFor(opts, deps);
@@ -57,6 +58,306 @@ export async function runAnalyticsKpi(opts, deps = {}) {
         return fail(toCliError(e));
     }
 }
+/**
+ * DSR/content engagement rows from the clickhouse-api analytics service.
+ * Row-heavy (member gate) — shaped through `shapeAnalytics` to cap the
+ * payload at `--limit` and surface a truncation notice, since the native
+ * response can carry hundreds of rows per page.
+ */
+export async function runAnalyticsEngagement(opts, deps = {}) {
+    try {
+        if (!opts.instanceId)
+            throw createCliError('VALIDATION', '--instance-id is required for analytics engagement');
+        const client = clickhouseClientFor(opts, deps);
+        const windowed = withDefaultWindow(opts, todayIso());
+        const params = {
+            instance_id: opts.instanceId,
+            start_date: windowed.startDate,
+            end_date: windowed.endDate,
+            page_size: pageSizeFor(opts.limit),
+        };
+        if (opts.page !== undefined)
+            params.page = opts.page;
+        if (opts.engagementLevel)
+            params.engagement_level = opts.engagementLevel;
+        if (opts.search)
+            params.search = opts.search;
+        if (opts.view)
+            params.view = opts.view;
+        if (opts.groupIds)
+            params.group_ids = opts.groupIds;
+        if (opts.sortBy)
+            params.sort_by = opts.sortBy;
+        if (opts.sortOrder)
+            params.sort_order = opts.sortOrder;
+        if (opts.hideMemberFiles)
+            params.hide_member_files = 'true';
+        const res = await client.get('/analytics/engagement', { params });
+        return ok(shapeAnalytics(res.data, (n) => ({ summary: n.metrics, rows: n.data?.data ?? [], totalCount: n.data?.total }), {
+            limit: opts.limit,
+        }));
+    }
+    catch (e) {
+        return fail(toCliError(e));
+    }
+}
+/**
+ * Most-viewed canvases from the clickhouse-api analytics service. There is no
+ * dedicated `popularity` route — this maps to `GET /analytics/canvases/stats`
+ * with `type=view-analysis` forced (always sent, never taken from opts).
+ * Row-heavy, so shaped through `shapeAnalytics` like `engagement`.
+ */
+export async function runAnalyticsPopularity(opts, deps = {}) {
+    try {
+        if (!opts.instanceId)
+            throw createCliError('VALIDATION', '--instance-id is required for analytics popularity');
+        const client = clickhouseClientFor(opts, deps);
+        const windowed = withDefaultWindow(opts, todayIso());
+        const params = {
+            instance_id: opts.instanceId,
+            start_date: windowed.startDate,
+            end_date: windowed.endDate,
+            type: 'view-analysis',
+            sort_by: opts.sortBy || 'total_views',
+            sort_order: opts.sortOrder || 'DESC',
+            page_size: pageSizeFor(opts.limit),
+        };
+        if (opts.page !== undefined)
+            params.page = opts.page;
+        if (opts.groupIds)
+            params.group_ids = opts.groupIds;
+        const res = await client.get('/analytics/canvases/stats', { params });
+        return ok(shapeAnalytics(res.data, (n) => ({ summary: n.metrics, rows: n.data ?? [], totalCount: n.pagination?.total }), {
+            limit: opts.limit,
+        }));
+    }
+    catch (e) {
+        return fail(toCliError(e));
+    }
+}
+/**
+ * User roster (default) or active-user statistics (`--stats`) from the
+ * clickhouse-api analytics service. The two branches hit different routes
+ * with different params — verified against `packages/clickhouse-api/src/routes/users.ts`:
+ *
+ * - Default → `GET /analytics/users/list`: `instance_id` only. Full roster,
+ *   no dates, no page size. (`show_internal_users` is resolved server-side
+ *   from an org LD flag — the route never reads it as a query param, so the
+ *   CLI does not expose it.)
+ * - `--stats` → `GET /analytics/users/stats`: requires `start_date`/`end_date`
+ *   (defaulted via `withDefaultWindow`), and `type` is ALWAYS forced to
+ *   `'active-users'` — the wire default `type=all` returns a shape with no
+ *   `.items`, which would otherwise silently shape to an empty row set. The
+ *   page-size param on this route is the camelCase `pageSize` (verified
+ *   `users.ts:230`) — the one route in the CLI that reads camelCase on the wire.
+ */
+export async function runAnalyticsUsers(opts, deps = {}) {
+    try {
+        if (!opts.instanceId)
+            throw createCliError('VALIDATION', '--instance-id is required for analytics users');
+        const client = clickhouseClientFor(opts, deps);
+        if (!opts.stats) {
+            const params = { instance_id: opts.instanceId };
+            const res = await client.get('/analytics/users/list', { params });
+            return ok(shapeAnalytics(res.data, (n) => ({ summary: undefined, rows: n.data ?? [] }), { limit: opts.limit }));
+        }
+        const windowed = withDefaultWindow(opts, todayIso());
+        const params = {
+            instance_id: opts.instanceId,
+            start_date: windowed.startDate,
+            end_date: windowed.endDate,
+            type: 'active-users',
+            pageSize: pageSizeFor(opts.limit),
+        };
+        if (opts.page !== undefined)
+            params.page = opts.page;
+        if (opts.groupIds)
+            params.group_ids = opts.groupIds;
+        const res = await client.get('/analytics/users/stats', { params });
+        return ok(shapeAnalytics(res.data, (n) => ({ summary: n.metrics, rows: n.data?.items ?? [], totalCount: n.data?.total }), {
+            limit: opts.limit,
+        }));
+    }
+    catch (e) {
+        return fail(toCliError(e));
+    }
+}
+/**
+ * File usage analytics from the clickhouse-api analytics service. There is
+ * no dedicated "list" type on the wire — `type` is ALWAYS forced to `'all'`
+ * (verified `files.ts`/`files-analytics.service.ts`): the `default` branch of
+ * `getFileUsageAnalysisData` throws `Unsupported type`, and only `type=all`
+ * yields the paginated row list. `page_size` is snake_case on this
+ * route (unlike `users/stats`). `sort_order` must be uppercased on the wire —
+ * the server zod is `z.enum(['ASC','DESC'])`.
+ */
+export async function runAnalyticsFiles(opts, deps = {}) {
+    try {
+        if (!opts.instanceId)
+            throw createCliError('VALIDATION', '--instance-id is required for analytics files');
+        const client = clickhouseClientFor(opts, deps);
+        const windowed = withDefaultWindow(opts, todayIso());
+        const params = {
+            instance_id: opts.instanceId,
+            start_date: windowed.startDate,
+            end_date: windowed.endDate,
+            type: 'all',
+            page_size: pageSizeFor(opts.limit),
+        };
+        if (opts.page !== undefined)
+            params.page = opts.page;
+        if (opts.fileType)
+            params.file_type = opts.fileType;
+        if (opts.filter)
+            params.filter = opts.filter;
+        if (opts.sortBy)
+            params.sort_by = opts.sortBy;
+        if (opts.sortOrder)
+            params.sort_order = opts.sortOrder.toUpperCase();
+        if (opts.metadataFilters)
+            params.metadata_filters = opts.metadataFilters;
+        if (opts.groupIds)
+            params.group_ids = opts.groupIds;
+        if (opts.userEmails)
+            params.user_emails = opts.userEmails;
+        if (opts.hideMemberFiles)
+            params.hide_member_files = 'true';
+        const res = await client.get('/analytics/files', { params });
+        return ok(shapeAnalytics(res.data, (n) => ({ summary: n.metrics, rows: n.data?.data ?? [], totalCount: n.data?.pagination?.total }), { limit: opts.limit }));
+    }
+    catch (e) {
+        return fail(toCliError(e));
+    }
+}
+/**
+ * Per-section canvas engagement list from the clickhouse-api analytics
+ * service. There is no dedicated "list" type on the wire — `type` is ALWAYS
+ * forced to `'section-list'` (verified `canvases.ts`/`canvases-analytics.service.ts`):
+ * `getCanvasAnalysisData` has exactly one supported case (`section-list`); its
+ * `default` branch throws `Unsupported type`, so any other value would hard-fail
+ * server-side. `--status`/`--filter` are deliberately NOT exposed — the
+ * `section-list` code path (`fetchSectionsList`) ignores `filter`/`search`/`status`
+ * entirely, so they'd be dead flags. There is also no `sort_order` on this route.
+ */
+export async function runAnalyticsCanvases(opts, deps = {}) {
+    try {
+        if (!opts.instanceId)
+            throw createCliError('VALIDATION', '--instance-id is required for analytics canvases');
+        const client = clickhouseClientFor(opts, deps);
+        const windowed = withDefaultWindow(opts, todayIso());
+        const params = {
+            instance_id: opts.instanceId,
+            start_date: windowed.startDate,
+            end_date: windowed.endDate,
+            type: 'section-list',
+            page_size: pageSizeFor(opts.limit),
+        };
+        if (opts.page !== undefined)
+            params.page = opts.page;
+        if (opts.groupIds)
+            params.group_ids = opts.groupIds;
+        const res = await client.get('/analytics/canvases', { params });
+        return ok(shapeAnalytics(res.data, (n) => ({ summary: n.metrics, rows: n.data?.items ?? [], totalCount: n.data?.total }), {
+            limit: opts.limit,
+        }));
+    }
+    catch (e) {
+        return fail(toCliError(e));
+    }
+}
+const VIEWERS_SORT_BY = new Set([
+    'email',
+    'session_count',
+    'total_engagement_time',
+    'last_active',
+    'sections_viewed',
+    'files_viewed',
+]);
+/**
+ * DSR canvas viewers (who-viewed) from the clickhouse-api analytics service.
+ * Maps to `GET /analytics/canvas-details/viewers` (member-gated, not admin) —
+ * verified `canvas-details.ts` ~L578-1147. Unlike the other row-heavy verbs,
+ * this route has its OWN server-side default window, so dates are NOT run
+ * through `withDefaultWindow` here — `start_date`/`end_date` are sent only
+ * when the caller supplies them. `sort_order` must be lowercased on the
+ * wire — the server zod is `z.enum(['asc','desc'])` (opposite of `files`,
+ * which uppercases). `sort_by` is validated client-side against the server
+ * enum so bad values fail fast with VALIDATION instead of a server 400.
+ */
+export async function runAnalyticsViewers(opts, deps = {}) {
+    try {
+        if (!opts.instanceId)
+            throw createCliError('VALIDATION', '--instance-id is required for analytics viewers');
+        if (!opts.canvasId)
+            throw createCliError('VALIDATION', '--canvas-id is required for analytics viewers');
+        if (opts.sortBy && !VIEWERS_SORT_BY.has(opts.sortBy)) {
+            throw createCliError('VALIDATION', `--sort-by must be one of: ${Array.from(VIEWERS_SORT_BY).join(', ')}`);
+        }
+        const client = clickhouseClientFor(opts, deps);
+        const params = {
+            instance_id: opts.instanceId,
+            canvas_id: opts.canvasId,
+            page_size: pageSizeFor(opts.limit),
+        };
+        if (opts.viewerType)
+            params.viewer_type = opts.viewerType;
+        if (opts.sortBy)
+            params.sort_by = opts.sortBy;
+        if (opts.sortOrder)
+            params.sort_order = opts.sortOrder.toLowerCase();
+        if (opts.search)
+            params.search = opts.search;
+        if (opts.page !== undefined)
+            params.page = opts.page;
+        if (opts.startDate)
+            params.start_date = opts.startDate;
+        if (opts.endDate)
+            params.end_date = opts.endDate;
+        const res = await client.get('/analytics/canvas-details/viewers', { params });
+        return ok(shapeAnalytics(res.data, (n) => ({
+            summary: { canvas_name: n.canvas_name, ...n.overview },
+            rows: n.viewers?.items ?? [],
+            totalCount: n.viewers?.total,
+            warnings: n._meta?.partial ? [`partial: ${(n._meta.unavailable || []).join(', ')}`] : undefined,
+        }), { limit: opts.limit }));
+    }
+    catch (e) {
+        return fail(toCliError(e));
+    }
+}
+/**
+ * Per-viewer session event timeline (DSR drill-down) from the clickhouse-api
+ * analytics service. Maps to `GET /analytics/canvas-details/sessions`
+ * (member-gated) — verified `canvas-details.ts` ~L1152-1329. Returns RAW
+ * (like `kpi`), NOT run through `shapeAnalytics` — an event timeline must not
+ * be truncated. Like `viewers`, this route has its own server-side default
+ * window, so dates are sent only when the caller supplies them.
+ */
+export async function runAnalyticsSessions(opts, deps = {}) {
+    try {
+        if (!opts.instanceId)
+            throw createCliError('VALIDATION', '--instance-id is required for analytics sessions');
+        if (!opts.canvasId)
+            throw createCliError('VALIDATION', '--canvas-id is required for analytics sessions');
+        if (!opts.userEmail)
+            throw createCliError('VALIDATION', '--user is required for analytics sessions');
+        const client = clickhouseClientFor(opts, deps);
+        const params = {
+            instance_id: opts.instanceId,
+            canvas_id: opts.canvasId,
+            user_email: opts.userEmail,
+        };
+        if (opts.startDate)
+            params.start_date = opts.startDate;
+        if (opts.endDate)
+            params.end_date = opts.endDate;
+        const res = await client.get('/analytics/canvas-details/sessions', { params });
+        return ok(res.data);
+    }
+    catch (e) {
+        return fail(toCliError(e));
+    }
+}
 export function createAnalyticsCommand() {
     const cmd = new Command('analytics').description('read rollup analytics totals (requires an org-admin API key)');
     withAuthFlags(cmd.command('org'))
@@ -84,5 +385,108 @@ export function createAnalyticsCommand() {
         const globals = command.optsWithGlobals();
         emitEnvelope(await runAnalyticsKpi({ ...options, quiet: globals.quiet }), globals);
     });
+    withAuthFlags(cmd.command('engagement'))
+        .option('--instance-id <id>', 'Instance ID (required)')
+        .option('--start-date <iso>', 'Window start (ISO date; defaults to 30 days ago)')
+        .option('--end-date <iso>', 'Window end (ISO date; defaults to today)')
+        .option('--engagement-level <level>', "Engagement level filter (default 'all')")
+        .option('--view <view>', "View context (default 'dsr')")
+        .option('--search <term>', 'Search term')
+        .option('--group-ids <csv>', 'Comma-separated distribution-group IDs')
+        .option('--sort-by <field>', 'Sort field')
+        .option('--sort-order <dir>', 'Sort direction')
+        .option('--hide-member-files', 'Exclude rep-uploaded files')
+        .option('--page <n>', 'Page number', (v) => parseInt(v, 10))
+        .option('--limit <n>', 'Max rows to return (default 20, max 100)', (v) => parseInt(v, 10))
+        .description('DSR/content engagement rows from the clickhouse analytics service')
+        .action(async (options, command) => {
+        const globals = command.optsWithGlobals();
+        emitEnvelope(await runAnalyticsEngagement({ ...options, quiet: globals.quiet }), globals);
+    });
+    withAuthFlags(cmd.command('popularity'))
+        .option('--instance-id <id>', 'Instance ID (required)')
+        .option('--start-date <iso>', 'Window start (ISO date; defaults to 30 days ago)')
+        .option('--end-date <iso>', 'Window end (ISO date; defaults to today)')
+        .option('--sort-by <field>', "Sort field (default 'total_views')")
+        .option('--sort-order <dir>', "Sort direction (default 'DESC')")
+        .option('--group-ids <csv>', 'Comma-separated distribution-group IDs')
+        .option('--page <n>', 'Page number', (v) => parseInt(v, 10))
+        .option('--limit <n>', 'Max rows to return (default 20, max 100)', (v) => parseInt(v, 10))
+        .description('most-viewed canvases (view-analysis) from the clickhouse analytics service')
+        .action(async (options, command) => {
+        const globals = command.optsWithGlobals();
+        emitEnvelope(await runAnalyticsPopularity({ ...options, quiet: globals.quiet }), globals);
+    });
+    withAuthFlags(cmd.command('users'))
+        .option('--instance-id <id>', 'Instance ID (required)')
+        .option('--stats', 'Return active-user statistics instead of the user roster')
+        .option('--start-date <iso>', 'Window start (ISO date; --stats only, defaults to 30 days ago)')
+        .option('--end-date <iso>', 'Window end (ISO date; --stats only, defaults to today)')
+        .option('--group-ids <csv>', 'Comma-separated distribution-group IDs (--stats only)')
+        .option('--page <n>', 'Page number (--stats only)', (v) => parseInt(v, 10))
+        .option('--limit <n>', 'Max rows to return (default 20, max 100)', (v) => parseInt(v, 10))
+        .description('user roster (default) or active-user statistics (--stats) from the clickhouse analytics service (admin key)')
+        .action(async (options, command) => {
+        const globals = command.optsWithGlobals();
+        emitEnvelope(await runAnalyticsUsers({ ...options, quiet: globals.quiet }), globals);
+    });
+    withAuthFlags(cmd.command('files'))
+        .option('--instance-id <id>', 'Instance ID (required)')
+        .option('--start-date <iso>', 'Window start (ISO date; defaults to 30 days ago)')
+        .option('--end-date <iso>', 'Window end (ISO date; defaults to today)')
+        .option('--file-type <type>', 'Filter by file type')
+        .option('--filter <term>', 'Search term')
+        .option('--sort-by <field>', 'Sort field')
+        .option('--sort-order <dir>', 'Sort direction (asc/desc, normalized to ASC/DESC)')
+        .option('--metadata-filters <json>', 'Metadata filters')
+        .option('--group-ids <csv>', 'Comma-separated distribution-group IDs')
+        .option('--user-emails <csv>', 'Comma-separated user emails to scope by')
+        .option('--hide-member-files', 'Exclude rep-uploaded files')
+        .option('--page <n>', 'Page number', (v) => parseInt(v, 10))
+        .option('--limit <n>', 'Max rows to return (default 20, max 100)', (v) => parseInt(v, 10))
+        .description('file usage analytics (admin key) from the clickhouse analytics service')
+        .action(async (options, command) => {
+        const globals = command.optsWithGlobals();
+        emitEnvelope(await runAnalyticsFiles({ ...options, quiet: globals.quiet }), globals);
+    });
+    withAuthFlags(cmd.command('canvases'))
+        .option('--instance-id <id>', 'Instance ID (required)')
+        .option('--start-date <iso>', 'Window start (ISO date; defaults to 30 days ago)')
+        .option('--end-date <iso>', 'Window end (ISO date; defaults to today)')
+        .option('--group-ids <csv>', 'Comma-separated distribution-group IDs')
+        .option('--page <n>', 'Page number', (v) => parseInt(v, 10))
+        .option('--limit <n>', 'Max rows to return (default 20, max 100)', (v) => parseInt(v, 10))
+        .description('per-section canvas engagement list (admin key) from the clickhouse analytics service')
+        .action(async (options, command) => {
+        const globals = command.optsWithGlobals();
+        emitEnvelope(await runAnalyticsCanvases({ ...options, quiet: globals.quiet }), globals);
+    });
+    withAuthFlags(cmd.command('viewers'))
+        .option('--instance-id <id>', 'Instance ID (required)')
+        .option('--canvas-id <id>', 'Canvas ID (required)')
+        .option('--viewer-type <type>', "Viewer type filter: all, internal, external (default 'all')")
+        .option('--sort-by <field>', 'Sort field: email, session_count, total_engagement_time, last_active, sections_viewed, files_viewed')
+        .option('--sort-order <dir>', "Sort direction (asc/desc, normalized to lowercase, default 'desc')")
+        .option('--search <term>', 'Search term')
+        .option('--start-date <iso>', 'Window start (ISO date; server default applies if omitted)')
+        .option('--end-date <iso>', 'Window end (ISO date; server default applies if omitted)')
+        .option('--page <n>', 'Page number', (v) => parseInt(v, 10))
+        .option('--limit <n>', 'Max rows to return (default 20, max 100)', (v) => parseInt(v, 10))
+        .description('DSR canvas viewers (who viewed) from the clickhouse analytics service')
+        .action(async (options, command) => {
+        const globals = command.optsWithGlobals();
+        emitEnvelope(await runAnalyticsViewers({ ...options, quiet: globals.quiet }), globals);
+    });
+    withAuthFlags(cmd.command('sessions'))
+        .option('--instance-id <id>', 'Instance ID (required)')
+        .option('--canvas-id <id>', 'Canvas ID (required)')
+        .option('--user <email>', 'Viewer user email (required)')
+        .option('--start-date <iso>', 'Window start (ISO date; server default applies if omitted)')
+        .option('--end-date <iso>', 'Window end (ISO date; server default applies if omitted)')
+        .description('per-viewer session event timeline for a DSR canvas (clickhouse analytics service)')
+        .action(async (options, command) => {
+        const globals = command.optsWithGlobals();
+        emitEnvelope(await runAnalyticsSessions({ ...options, userEmail: options.user, quiet: globals.quiet }), globals);
+    });
     return cmd;
 }

package/dist/src/core/analytics-shape.d.ts

@@ -0,0 +1,24 @@
+export interface ShapedResult<T> {
+    summary: unknown;
+    rows: T[];
+    total_count: number;
+    returned: number;
+    has_more: boolean;
+    truncated?: string;
+    warnings?: string[];
+}
+export declare function shapeAnalytics<T>(native: unknown, adapter: (n: any) => {
+    summary: unknown;
+    rows: T[];
+    totalCount?: number;
+    warnings?: string[];
+}, opts?: {
+    limit?: number;
+}): ShapedResult<T>;
+export declare function pageSizeFor(limit?: number): number;
+/** Today as an ISO day string (UTC) — what callers pass as `nowIso` to `withDefaultWindow`. */
+export declare function todayIso(): string;
+export declare function withDefaultWindow<T extends {
+    startDate?: string;
+    endDate?: string;
+}>(opts: T, nowIso: string): T;

package/dist/src/core/analytics-shape.js

@@ -0,0 +1,58 @@
+import { createCliError } from './errors.js';
+const DEFAULT_LIMIT = 20;
+const MAX_LIMIT = 100;
+export function shapeAnalytics(native, adapter, opts = {}) {
+    const { summary, rows, totalCount, warnings } = adapter(native);
+    const limit = pageSizeFor(opts.limit);
+    const all = Array.isArray(rows) ? rows : [];
+    const capped = all.slice(0, limit);
+    const total = totalCount ?? all.length;
+    const has_more = total > capped.length;
+    return {
+        summary,
+        rows: capped,
+        total_count: total,
+        returned: capped.length,
+        has_more,
+        ...(has_more
+            ? { truncated: `Showing ${capped.length} of ${total.toLocaleString('en-US')} — narrow with --limit or filters` }
+            : {}),
+        ...(warnings && warnings.length ? { warnings } : {}),
+    };
+}
+// Deliberately separate from src/core/pagination.ts (caps at 500, no default) —
+// that helper serves a different set of routes. Analytics defaults to 20 and
+// caps at 100, matching the viewers route's server-side cap. Also the single
+// place the row limit is normalized (shapeAnalytics delegates here): a
+// non-finite limit (NaN from `parseInt('abc')`, ±Infinity) falls back to the
+// default, and 0/negative floors to 1 — so an invalid `--limit` never sends a
+// bad page_size to the wire nor slices client rows to an empty set.
+export function pageSizeFor(limit) {
+    const n = Number.isFinite(limit) ? limit : DEFAULT_LIMIT;
+    return Math.min(Math.max(n, 1), MAX_LIMIT);
+}
+function subUtcDays(iso, days) {
+    const d = new Date(`${iso}T00:00:00Z`);
+    if (Number.isNaN(d.getTime())) {
+        throw createCliError('VALIDATION', `Invalid date '${iso}' — expected ISO YYYY-MM-DD`);
+    }
+    d.setUTCDate(d.getUTCDate() - days);
+    return d.toISOString().slice(0, 10);
+}
+/** Today as an ISO day string (UTC) — what callers pass as `nowIso` to `withDefaultWindow`. */
+export function todayIso() {
+    return new Date().toISOString().slice(0, 10);
+}
+// Completes whichever bound is missing independently — both present is left
+// untouched; both absent get a 30-day window ending at nowIso; only end_date
+// given derives start_date as end-30; only start_date given fills end_date
+// with nowIso. The point is that a lone bound never leaves the other
+// undefined, which axios would silently drop from the wire (both are required
+// server-side).
+export function withDefaultWindow(opts, nowIso) {
+    if (opts.startDate && opts.endDate)
+        return opts;
+    const endDate = opts.endDate ?? nowIso;
+    const startDate = opts.startDate ?? subUtcDays(endDate, 30);
+    return { ...opts, startDate, endDate };
+}

package/package.json

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