@tenderprompt/cli 0.1.9 → 0.1.10

package/README.md

@@ -157,6 +157,8 @@ tender app analytics export catalog artifact_123 --range 30d --json
 tender app analytics export query artifact_123 --spec chart.json --format csv
 
 tender app analytics suggestions artifact_123 --range 30d --json
+
+tender app analytics charts templates --json
 ```
 
 Safe write previews:
@@ -178,6 +180,8 @@ Agents should combine `capabilities --include-catalog` with local source-code
 inspection. For example, inspect where the app calls
 `__TP_ANALYTICS.invoke(...)`, propose a chart spec, validate it with
 `analytics query`, and only then create a saved chart.
+Use `charts templates --json` for reusable chart shapes; adapt any placeholders
+to observed events, paths, or promoted property keys before querying or saving.
 
 ## Safety Model
 

package/dist/index.js

@@ -266,6 +266,7 @@ Commands:
   tender app analytics suggestions <app-id>   Generate starter chart suggestions
   tender app analytics dashboards <app-id>    List or create dashboards
   tender app analytics export <kind> <app-id> Export catalog metadata or query rows
+  tender app analytics charts templates       Print reusable chart spec templates
   tender app analytics charts create <app-id> Create a saved chart
 
 Examples:
@@ -277,6 +278,7 @@ Examples:
   tender app analytics export query artifact_123 --spec chart.json --format csv
   tender app analytics suggestions artifact_123 --range 2026-04-01..2026-04-30 --json
   tender app analytics dashboards artifact_123 --create "Agent dashboard" --json
+  tender app analytics charts templates --json
   tender app analytics charts create artifact_123 --dashboard analytics_dashboard_123 --title "Signup funnel" --spec funnel.json --json`;
 }
 function analyticsSummaryHelp() {
@@ -340,6 +342,16 @@ Examples:
   tender app analytics dashboards artifact_123 --create "Agent dashboard" --dry-run --json
   tender app analytics dashboards artifact_123 --create "Agent dashboard" --json`;
 }
+function analyticsChartsTemplatesHelp() {
+    return `Usage: tender app analytics charts templates [--json]
+
+Print reusable chart spec templates for agents. Adapt templates to observed
+events, paths, and property keys from analytics capabilities before querying or
+saving.
+
+Examples:
+  tender app analytics charts templates --json`;
+}
 function analyticsChartsCreateHelp() {
     return `Usage: tender app analytics charts create <app-id> --dashboard <dashboard-id> --title <title> --spec <file|-> [--dry-run] [--base-url <url>] [--token <token>] [--profile <name>] [--json]
 
@@ -725,6 +737,7 @@ function tenderCliCapabilities() {
                 when: "When understanding app analytics or creating saved charts.",
                 commands: [
                     "tender app analytics capabilities <artifact-id> --include-catalog --range 30d --json",
+                    "tender app analytics charts templates --json",
                     "tender app analytics query <artifact-id> --spec chart.json --json",
                     "tender app analytics export query <artifact-id> --spec chart.json --format csv",
                     "tender app analytics dashboards <artifact-id> --create \"Agent dashboard\" --dry-run --json",
@@ -782,6 +795,12 @@ function tenderCliCapabilities() {
                 requiresAuth: true,
                 writes: false,
             },
+            {
+                command: "tender app analytics charts templates --json",
+                purpose: "Print reusable chart spec templates for agents to adapt to observed analytics data.",
+                requiresAuth: false,
+                writes: false,
+            },
         ],
         security: [
             "Prefer artifact-scoped device tokens.",
@@ -2555,6 +2574,21 @@ function parseAnalyticsDashboardsArgs(args) {
     }
     return { command: "app analytics dashboards", artifactId, name, dryRun, ...parsed };
 }
+function parseAnalyticsChartsTemplatesArgs(args) {
+    if (args.includes("--help") || args.includes("-h")) {
+        return { command: "help", topic: "app analytics charts templates" };
+    }
+    let json = false;
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index];
+        if (arg === "--json") {
+            json = true;
+            continue;
+        }
+        throw new TenderCliUsageError(`Unknown analytics charts templates option: ${arg}`);
+    }
+    return { command: "app analytics charts templates", json };
+}
 function parseAnalyticsExportCatalogArgs(args) {
     if (args.includes("--help") || args.includes("-h")) {
         return { command: "help", topic: "app analytics export catalog" };
@@ -2632,6 +2666,244 @@ function parseAnalyticsExportQueryArgs(args) {
         ...parsed,
     };
 }
+function analyticsChartTemplates() {
+    return [
+        {
+            id: "daily_custom_events",
+            title: "Daily custom events",
+            visualization: "line",
+            purpose: "Track app-owned business events over time.",
+            usableAsIs: true,
+            adaptWith: [
+                "Use when the catalog has observed custom events.",
+                "Switch the range preset to 7d or 90d when the user's question asks for that window.",
+            ],
+            spec: {
+                version: 1,
+                dataset: "events",
+                visualization: "line",
+                metric: { name: "custom_event_count" },
+                groupBy: [{ field: "day" }],
+                filters: [],
+                range: { preset: "30d" },
+                sort: [{ field: "label", direction: "asc" }],
+                limit: 30,
+            },
+        },
+        {
+            id: "top_custom_events",
+            title: "Top custom events",
+            visualization: "bar",
+            purpose: "Show which app-owned events happen most often.",
+            usableAsIs: true,
+            adaptWith: [
+                "Use this before proposing deeper charts so the agent can see the dominant event shape.",
+            ],
+            spec: {
+                version: 1,
+                dataset: "events",
+                visualization: "bar",
+                metric: { name: "custom_event_count" },
+                groupBy: [{ field: "event_name" }],
+                filters: [],
+                range: { preset: "30d" },
+                sort: [{ field: "value", direction: "desc" }],
+                limit: 10,
+            },
+        },
+        {
+            id: "top_request_paths",
+            title: "Top request paths",
+            visualization: "bar",
+            purpose: "Find the generated app routes receiving the most traffic.",
+            usableAsIs: true,
+            adaptWith: [
+                "Use only when the capabilities catalog reports request paths.",
+                "Inspect the local source to understand what the busiest routes represent.",
+            ],
+            spec: {
+                version: 1,
+                dataset: "events",
+                visualization: "bar",
+                metric: { name: "request_count" },
+                groupBy: [{ field: "path" }],
+                filters: [],
+                range: { preset: "30d" },
+                sort: [{ field: "value", direction: "desc" }],
+                limit: 10,
+            },
+        },
+        {
+            id: "event_funnel_by_name",
+            title: "Event funnel",
+            visualization: "funnel",
+            purpose: "Measure ordered conversion through observed custom event names.",
+            usableAsIs: false,
+            placeholders: {
+                eventNames: ["<start_event>", "<middle_event>", "<conversion_event>"],
+            },
+            adaptWith: [
+                "Replace placeholders with ordered event names from catalog classification or observed events.",
+                "Use only event names observed for the selected app.",
+                "Validate with analytics query before saving because funnel order changes the meaning.",
+            ],
+            spec: {
+                version: 1,
+                dataset: "events",
+                visualization: "funnel",
+                metric: { name: "custom_event_count" },
+                groupBy: [{ field: "event_name" }],
+                filters: [
+                    {
+                        field: "event_name",
+                        op: "in",
+                        value: ["<start_event>", "<middle_event>", "<conversion_event>"],
+                    },
+                ],
+                range: { preset: "30d" },
+                sort: [{ field: "label", direction: "asc" }],
+                limit: 3,
+            },
+        },
+        {
+            id: "request_path_funnel",
+            title: "Request path funnel",
+            visualization: "funnel",
+            purpose: "Measure ordered conversion through observed request paths.",
+            usableAsIs: false,
+            placeholders: {
+                paths: ["/<start_path>", "/<middle_path>", "/<conversion_path>"],
+            },
+            adaptWith: [
+                "Use when catalog classification includes a path-based funnel or the source code shows ordered route milestones.",
+                "Replace placeholders with exact observed paths from the selected app.",
+                "Do not include repeated activity routes unless source context says they are milestones.",
+            ],
+            spec: {
+                version: 1,
+                dataset: "events",
+                visualization: "funnel",
+                metric: { name: "request_count" },
+                groupBy: [{ field: "path" }],
+                filters: [
+                    {
+                        field: "path",
+                        op: "in",
+                        value: ["/<start_path>", "/<middle_path>", "/<conversion_path>"],
+                    },
+                ],
+                range: { preset: "30d" },
+                sort: [{ field: "label", direction: "asc" }],
+                limit: 3,
+            },
+        },
+        {
+            id: "property_breakdown",
+            title: "Property breakdown",
+            visualization: "bar",
+            purpose: "Compare a promoted dimension property observed in events.",
+            usableAsIs: false,
+            placeholders: {
+                property: "<promoted_dimension_property>",
+            },
+            adaptWith: [
+                "Use a property key promoted by capabilities chartSpec.groupBy, such as property:plan.",
+                "Choose stable categorical properties with enough observations to compare.",
+            ],
+            spec: {
+                version: 1,
+                dataset: "events",
+                visualization: "bar",
+                metric: { name: "custom_event_count" },
+                groupBy: [{ field: "property:<promoted_dimension_property>" }],
+                filters: [],
+                range: { preset: "30d" },
+                sort: [{ field: "value", direction: "desc" }],
+                limit: 10,
+            },
+        },
+        {
+            id: "average_metric_property",
+            title: "Average metric property",
+            visualization: "line",
+            purpose: "Track an observed numeric event property over time.",
+            usableAsIs: false,
+            placeholders: {
+                metric: "avg:<promoted_metric_property>",
+            },
+            adaptWith: [
+                "Use a numeric property key promoted by capabilities chartSpec.metrics.",
+                "Prefer averages for scores, durations, quantities, or ordinal values.",
+            ],
+            spec: {
+                version: 1,
+                dataset: "events",
+                visualization: "line",
+                metric: { name: "avg:<promoted_metric_property>" },
+                groupBy: [{ field: "day" }],
+                filters: [],
+                range: { preset: "30d" },
+                sort: [{ field: "label", direction: "asc" }],
+                limit: 30,
+            },
+        },
+        {
+            id: "single_number_total",
+            title: "Single number total",
+            visualization: "number",
+            purpose: "Show one headline count for a selected event or request segment.",
+            usableAsIs: false,
+            placeholders: {
+                eventName: "<event_name>",
+            },
+            adaptWith: [
+                "Use when a dashboard needs a compact KPI card.",
+                "Replace the event filter with an observed conversion or outcome event.",
+            ],
+            spec: {
+                version: 1,
+                dataset: "events",
+                visualization: "number",
+                metric: { name: "custom_event_count" },
+                groupBy: [],
+                filters: [{ field: "event_name", op: "=", value: "<event_name>" }],
+                range: { preset: "30d" },
+                sort: [],
+                limit: 1,
+            },
+        },
+    ];
+}
+function runAnalyticsChartsTemplates(command, io) {
+    const templates = analyticsChartTemplates();
+    const payload = {
+        ok: true,
+        command: command.command,
+        templates,
+        next: [
+            "Run tender app analytics capabilities <artifact-id> --include-catalog --range 30d --json.",
+            "Choose a template and replace placeholders with observed events, paths, or promoted property keys.",
+            "Validate with tender app analytics query <artifact-id> --spec chart.json --json.",
+            "Preview saved writes with tender app analytics dashboards ... --dry-run and charts create ... --dry-run.",
+        ],
+    };
+    if (command.json) {
+        io.stdout(JSON.stringify(payload, null, 2));
+    }
+    else {
+        io.stdout([
+            "Analytics chart templates",
+            "",
+            ...templates.map((template) => {
+                const marker = template.usableAsIs ? "usable as-is" : "adapt before use";
+                return `- ${template.id}: ${template.title} (${marker})`;
+            }),
+            "",
+            "Use --json to copy full chart specs.",
+        ].join("\n"));
+    }
+    return 0;
+}
 function parseAnalyticsChartsCreateArgs(args) {
     if (args.includes("--help") || args.includes("-h")) {
         return { command: "help", topic: "app analytics charts create" };
@@ -2781,6 +3053,18 @@ function parseTenderArgs(args) {
             resourceArgs[3] === "query") {
             return parseAnalyticsExportQueryArgs(resourceArgs.slice(4));
         }
+        if (resourceArgs[1] === "analytics" &&
+            resourceArgs[2] === "charts" &&
+            resourceArgs[3] === "templates") {
+            return parseAnalyticsChartsTemplatesArgs(resourceArgs.slice(4));
+        }
+        if (resourceArgs[1] === "analytics" &&
+            resourceArgs[2] === "charts" &&
+            (resourceArgs[3] === undefined ||
+                resourceArgs[3] === "--help" ||
+                resourceArgs[3] === "-h")) {
+            return { command: "help", topic: "app analytics charts templates" };
+        }
         if (resourceArgs[1] === "analytics" &&
             resourceArgs[2] === "charts" &&
             resourceArgs[3] === "create") {
@@ -5503,6 +5787,9 @@ export async function runTenderCli(args, io = {
             else if (command.topic === "app analytics export query") {
                 io.stdout(analyticsExportQueryHelp());
             }
+            else if (command.topic === "app analytics charts templates") {
+                io.stdout(analyticsChartsTemplatesHelp());
+            }
             else if (command.topic === "app analytics charts create") {
                 io.stdout(analyticsChartsCreateHelp());
             }
@@ -5601,6 +5888,9 @@ export async function runTenderCli(args, io = {
         if (command.command === "app analytics export query") {
             return await runAnalyticsExportQuery(command, io, runtime);
         }
+        if (command.command === "app analytics charts templates") {
+            return runAnalyticsChartsTemplates(command, io);
+        }
         if (command.command === "app analytics charts create") {
             return await runAnalyticsChartsCreate(command, io, runtime);
         }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@tenderprompt/cli",
-	"version": "0.1.9",
+	"version": "0.1.10",
 	"type": "module",
 	"bin": {
 		"tender": "bin/tender.js"