@supalytics/cli 0.4.1 → 0.4.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@supalytics/cli",
-  "version": "0.4.1",
+  "version": "0.4.3",
   "description": "CLI for Supalytics web analytics",
   "type": "module",
   "bin": {

package/src/api.ts

@@ -159,7 +159,7 @@ export interface PropertyBreakdownResponse {
  */
 export async function listEvents(
   site: string,
-  period: string = "30d",
+  dateRange: string | [string, string] = "30d",
   limit: number = 100,
   isDev: boolean = false
 ): Promise<EventsResponse> {
@@ -177,7 +177,13 @@ export async function listEvents(
     );
   }
 
-  const params = new URLSearchParams({ period, limit: String(limit), domain: site });
+  const params = new URLSearchParams({ limit: String(limit), domain: site });
+  if (Array.isArray(dateRange)) {
+    params.set("start", dateRange[0]);
+    params.set("end", dateRange[1]);
+  } else {
+    params.set("period", dateRange);
+  }
   if (isDev) {
     params.set("is_dev", "true");
   }
@@ -199,7 +205,7 @@ export async function listEvents(
 export async function getEventProperties(
   site: string,
   eventName: string,
-  period: string = "30d",
+  dateRange: string | [string, string] = "30d",
   isDev: boolean = false
 ): Promise<PropertyKeysResponse> {
   const apiKey = await getApiKeyForSite(site);
@@ -208,7 +214,13 @@ export async function getEventProperties(
     throw new Error(`Not authenticated. Run \`supalytics login\` first.`);
   }
 
-  const params = new URLSearchParams({ period, domain: site });
+  const params = new URLSearchParams({ domain: site });
+  if (Array.isArray(dateRange)) {
+    params.set("start", dateRange[0]);
+    params.set("end", dateRange[1]);
+  } else {
+    params.set("period", dateRange);
+  }
   if (isDev) {
     params.set("is_dev", "true");
   }
@@ -232,7 +244,7 @@ export async function getPropertyBreakdown(
   site: string,
   eventName: string,
   propertyKey: string,
-  period: string = "30d",
+  dateRange: string | [string, string] = "30d",
   limit: number = 100,
   includeRevenue: boolean = false,
   isDev: boolean = false
@@ -244,11 +256,16 @@ export async function getPropertyBreakdown(
   }
 
   const params = new URLSearchParams({
-    period,
     limit: String(limit),
     include_revenue: String(includeRevenue),
     domain: site,
   });
+  if (Array.isArray(dateRange)) {
+    params.set("start", dateRange[0]);
+    params.set("end", dateRange[1]);
+  } else {
+    params.set("period", dateRange);
+  }
   if (isDev) {
     params.set("is_dev", "true");
   }
@@ -351,7 +368,7 @@ export interface AnnotationsResponse {
  */
 export async function listAnnotations(
   site: string,
-  period: string = "30d"
+  dateRange: string | [string, string] = "30d"
 ): Promise<AnnotationsResponse> {
   const apiKey = await getApiKeyForSite(site);
 
@@ -367,36 +384,13 @@ export async function listAnnotations(
     );
   }
 
-  // Valid periods
-  const validPeriods = ["7d", "14d", "30d", "90d", "12mo", "all"] as const;
-  if (!validPeriods.includes(period as typeof validPeriods[number])) {
-    throw new Error(`Invalid period "${period}". Valid periods: ${validPeriods.join(", ")}`);
-  }
-
-  // Calculate date range from period
-  const endDate = new Date();
-  let startDate = new Date();
-
-  if (period === "7d") {
-    startDate.setDate(endDate.getDate() - 7);
-  } else if (period === "14d") {
-    startDate.setDate(endDate.getDate() - 14);
-  } else if (period === "30d") {
-    startDate.setDate(endDate.getDate() - 30);
-  } else if (period === "90d") {
-    startDate.setDate(endDate.getDate() - 90);
-  } else if (period === "12mo") {
-    startDate.setMonth(endDate.getMonth() - 12);
-  } else if (period === "all") {
-    startDate = new Date("2020-01-01");
+  const params = new URLSearchParams({ domain: site });
+  if (Array.isArray(dateRange)) {
+    params.set("start_date", dateRange[0]);
+    params.set("end_date", dateRange[1]);
   }
-
-  const formatDate = (d: Date) => d.toISOString().split("T")[0];
-  const params = new URLSearchParams({
-    domain: site,
-    start_date: formatDate(startDate),
-    end_date: formatDate(endDate),
-  });
+  // Annotations API only supports start_date/end_date, not period.
+  // String values like "all" are left without date params so the API returns everything.
 
   const response = await fetch(`${API_BASE}/v1/annotations?${params}`, {
     headers: { Authorization: `Bearer ${apiKey}` },
@@ -734,6 +728,235 @@ export async function getJourneyStats(
   return response.json();
 }
 
+// Funnels API types
+export interface FunnelStep {
+  id: string;
+  step_order: number;
+  name: string;
+  type: string; // 'page' | 'event' | 'purchase' | 'trial'
+  match_type?: string | null;
+  match_value?: string | null;
+  property_key?: string | null;
+  property_value?: string | null;
+}
+
+export interface FunnelItem {
+  id: string;
+  name: string;
+  description?: string | null;
+  mode: string; // 'ordered' | 'unordered'
+  steps: FunnelStep[];
+  created_at: string;
+  updated_at: string;
+}
+
+export interface FunnelsListResponse {
+  data: FunnelItem[];
+  meta: { domain: string };
+}
+
+export interface FunnelResponse {
+  data: FunnelItem;
+  meta: { domain: string };
+}
+
+export interface FunnelAnalysisRow {
+  step_order: number;
+  step_type: string;
+  match_type: string | null;
+  match_value: string | null;
+  property_key: string | null;
+  property_value: string | null;
+  visitors: number;
+  conversion_rate_from_start: number;
+  conversion_rate_from_prev: number;
+}
+
+export interface FunnelAnalysisResponse {
+  data: FunnelAnalysisRow[];
+  meta: {
+    domain: string;
+    date_range: [string, string];
+    query_ms: number;
+  };
+}
+
+export interface FunnelStepInput {
+  name: string;
+  type: string;
+  match_type?: string;
+  match_value?: string;
+  property_key?: string;
+  property_value?: string;
+}
+
+/**
+ * List all funnels for a site
+ */
+export async function listFunnels(site: string): Promise<FunnelsListResponse> {
+  const apiKey = await getApiKeyForSite(site);
+
+  if (!apiKey) {
+    const sites = await getSites();
+    if (sites.length === 0) {
+      throw new Error(
+        "No sites configured. Run `supalytics login` to authenticate."
+      );
+    }
+    throw new Error(
+      `Not authenticated or site '${site}' not found. Available sites: ${sites.join(", ")}`
+    );
+  }
+
+  const params = new URLSearchParams({ domain: site });
+  const response = await fetch(`${API_BASE}/v1/funnels?${params}`, {
+    headers: { Authorization: `Bearer ${apiKey}` },
+  });
+
+  if (!response.ok) {
+    const error = (await response.json()) as ApiError;
+    throw new Error(error.message || error.error || `HTTP ${response.status}`);
+  }
+
+  return response.json();
+}
+
+/**
+ * Get a single funnel
+ */
+export async function getFunnel(
+  site: string,
+  funnelId: string
+): Promise<FunnelResponse> {
+  const apiKey = await getApiKeyForSite(site);
+
+  if (!apiKey) {
+    throw new Error(`Not authenticated. Run \`supalytics login\` first.`);
+  }
+
+  const params = new URLSearchParams({ domain: site });
+  const response = await fetch(`${API_BASE}/v1/funnels/${funnelId}?${params}`, {
+    headers: { Authorization: `Bearer ${apiKey}` },
+  });
+
+  if (!response.ok) {
+    const error = (await response.json()) as ApiError;
+    throw new Error(error.message || error.error || `HTTP ${response.status}`);
+  }
+
+  return response.json();
+}
+
+/**
+ * Create a funnel
+ */
+export async function createFunnel(
+  site: string,
+  data: {
+    name: string;
+    description?: string;
+    mode?: string;
+    steps: FunnelStepInput[];
+  }
+): Promise<FunnelResponse> {
+  const apiKey = await getApiKeyForSite(site);
+
+  if (!apiKey) {
+    throw new Error(`Not authenticated. Run \`supalytics login\` first.`);
+  }
+
+  const response = await fetch(`${API_BASE}/v1/funnels`, {
+    method: "POST",
+    headers: {
+      Authorization: `Bearer ${apiKey}`,
+      "Content-Type": "application/json",
+    },
+    body: JSON.stringify({ ...data, domain: site }),
+  });
+
+  if (!response.ok) {
+    const error = (await response.json()) as ApiError;
+    throw new Error(error.message || error.error || `HTTP ${response.status}`);
+  }
+
+  return response.json();
+}
+
+/**
+ * Update a funnel
+ */
+export async function updateFunnel(
+  site: string,
+  funnelId: string,
+  data: {
+    name?: string;
+    description?: string;
+    mode?: string;
+    steps?: FunnelStepInput[];
+  }
+): Promise<FunnelResponse> {
+  const apiKey = await getApiKeyForSite(site);
+
+  if (!apiKey) {
+    throw new Error(`Not authenticated. Run \`supalytics login\` first.`);
+  }
+
+  const response = await fetch(`${API_BASE}/v1/funnels/${funnelId}`, {
+    method: "PUT",
+    headers: {
+      Authorization: `Bearer ${apiKey}`,
+      "Content-Type": "application/json",
+    },
+    body: JSON.stringify({ ...data, domain: site }),
+  });
+
+  if (!response.ok) {
+    const error = (await response.json()) as ApiError;
+    throw new Error(error.message || error.error || `HTTP ${response.status}`);
+  }
+
+  return response.json();
+}
+
+/**
+ * Run funnel analysis
+ */
+export async function analyzeFunnel(
+  site: string,
+  funnelId: string,
+  dateRange: string | [string, string] = "30d",
+  isDev: boolean = false
+): Promise<FunnelAnalysisResponse> {
+  const apiKey = await getApiKeyForSite(site);
+
+  if (!apiKey) {
+    throw new Error(`Not authenticated. Run \`supalytics login\` first.`);
+  }
+
+  const body: Record<string, unknown> = { domain: site, is_dev: isDev };
+  if (Array.isArray(dateRange)) {
+    body.date_range = dateRange;
+  } else {
+    body.date_range = dateRange;
+  }
+
+  const response = await fetch(`${API_BASE}/v1/funnels/${funnelId}/analyze`, {
+    method: "POST",
+    headers: {
+      Authorization: `Bearer ${apiKey}`,
+      "Content-Type": "application/json",
+    },
+    body: JSON.stringify(body),
+  });
+
+  if (!response.ok) {
+    const error = (await response.json()) as ApiError;
+    throw new Error(error.message || error.error || `HTTP ${response.status}`);
+  }
+
+  return response.json();
+}
+
 /**
  * Format revenue in cents to dollars
  */

package/src/commands/annotations.ts

@@ -2,6 +2,23 @@ import chalk from "chalk"
 import { Command } from "commander"
 import { createAnnotation, deleteAnnotation, listAnnotations } from "../api"
 import { getDefaultSite } from "../config"
+import { parsePeriod } from "../ui"
+
+/**
+ * Merge subcommand options with parent command options.
+ * Commander doesn't propagate options like -s/--site and --json
+ * from parent to subcommands, so we check both.
+ */
+function mergedOpts(cmd: Command): Record<string, unknown> {
+	const parentOpts = cmd.parent?.opts() || {}
+	const ownOpts = cmd.opts()
+	return { ...parentOpts, ...ownOpts }
+}
+
+async function resolveSiteOption(cmd: Command): Promise<string | undefined> {
+	const opts = mergedOpts(cmd)
+	return (opts.site as string) || (await getDefaultSite())
+}
 
 const annotationsExamples = `
 Examples:
@@ -23,10 +40,10 @@ Examples:
 export const annotationsCommand = new Command("annotations")
 	.description("Manage chart annotations")
 	.addHelpText("after", annotationsExamples)
-	.argument("[period]", "Time period: 7d, 14d, 30d, 90d, 12mo, all", "30d")
 	.option("-s, --site <site>", "Site to query")
+	.option("-p, --period <period>", "Time period: 7d, 14d, 30d, 90d, 12mo, all", "30d")
 	.option("--json", "Output as JSON")
-	.action(async (period, options) => {
+	.action(async (options) => {
 		const site = options.site || (await getDefaultSite())
 
 		if (!site) {
@@ -39,7 +56,7 @@ export const annotationsCommand = new Command("annotations")
 		}
 
 		try {
-			const response = await listAnnotations(site, period)
+			const response = await listAnnotations(site, parsePeriod(options.period))
 
 			if (options.json) {
 				console.log(JSON.stringify(response, null, 2))
@@ -80,8 +97,9 @@ annotationsCommand
 	.option("-s, --site <site>", "Site to query")
 	.option("-d, --description <text>", "Optional description")
 	.option("--json", "Output as JSON")
-	.action(async (date, title, options) => {
-		const site = options.site || (await getDefaultSite())
+	.action(async (date, title, _options, cmd) => {
+		const options = mergedOpts(cmd)
+		const site = await resolveSiteOption(cmd)
 
 		if (!site) {
 			console.error(
@@ -99,7 +117,7 @@ annotationsCommand
 		}
 
 		try {
-			const annotation = await createAnnotation(site, date, title, options.description)
+			const annotation = await createAnnotation(site, date, title, options.description as string | undefined)
 
 			if (options.json) {
 				console.log(JSON.stringify(annotation, null, 2))
@@ -126,8 +144,8 @@ annotationsCommand
 	.command("remove <id>")
 	.description("Remove an annotation")
 	.option("-s, --site <site>", "Site to query")
-	.action(async (id, options) => {
-		const site = options.site || (await getDefaultSite())
+	.action(async (id, _options, cmd) => {
+		const site = await resolveSiteOption(cmd)
 
 		if (!site) {
 			console.error(

package/src/commands/completions.ts

@@ -10,7 +10,7 @@ _supalytics_completions() {
     cur="\${COMP_WORDS[COMP_CWORD]}"
     prev="\${COMP_WORDS[COMP_CWORD-1]}"
 
-    commands="init login logout sites default remove stats pages referrers countries trend query events realtime completions help"
+    commands="init login logout sites default remove stats pages referrers countries trend query events annotations realtime completions help"
 
     # Main command completion
     if [[ \${COMP_CWORD} -eq 1 ]]; then
@@ -21,7 +21,7 @@ _supalytics_completions() {
     # Subcommand options
     case "\${COMP_WORDS[1]}" in
         stats)
-            opts="today yesterday week month year 7d 14d 30d 90d 12mo all --site --start --end --filter --all --no-revenue --json"
+            opts="--site --period --start --end --filter --all --no-revenue --json"
             ;;
         pages|referrers|countries)
             opts="--site --period --start --end --limit --filter --no-revenue --json"
@@ -35,6 +35,9 @@ _supalytics_completions() {
         events)
             opts="--site --period --property --limit --no-revenue --json"
             ;;
+        annotations)
+            opts="--site --period --json add remove"
+            ;;
         realtime)
             opts="--site --json --watch"
             ;;
@@ -86,6 +89,7 @@ _supalytics() {
         'trend:Daily visitor trend'
         'query:Flexible query with custom metrics and dimensions'
         'events:List and explore custom events'
+        'annotations:Manage chart annotations'
         'realtime:Live visitors on your site right now'
         'completions:Generate shell completions'
         'help:Display help for command'
@@ -118,19 +122,14 @@ _supalytics() {
             case \$words[1] in
                 stats)
                     _arguments \\
-                        '1: :->period' \\
                         '--site[Site to query]:domain:' \\
+                        '--period[Time period]:period:(today yesterday week month year 7d 14d 30d 90d 12mo all)' \\
                         '--start[Start date]:date:' \\
                         '--end[End date]:date:' \\
                         '*--filter[Filter]:filter:' \\
                         '--all[Show detailed breakdown]' \\
                         '--no-revenue[Exclude revenue metrics]' \\
                         '--json[Output as JSON]'
-                    case \$state in
-                        period)
-                            _describe 'period' period_opts
-                            ;;
-                    esac
                     ;;
                 pages|referrers|countries)
                     _arguments \\
@@ -180,6 +179,12 @@ _supalytics() {
                         '--no-revenue[Exclude revenue]' \\
                         '--json[Output as JSON]'
                     ;;
+                annotations)
+                    _arguments \\
+                        '--site[Site to query]:domain:' \\
+                        '--period[Time period]:period:(7d 14d 30d 90d 12mo all)' \\
+                        '--json[Output as JSON]'
+                    ;;
                 realtime)
                     _arguments \\
                         '--site[Site to query]:domain:' \\
@@ -236,13 +241,14 @@ complete -c supalytics -n "__fish_use_subcommand" -a "countries" -d "Traffic by
 complete -c supalytics -n "__fish_use_subcommand" -a "trend" -d "Daily visitor trend"
 complete -c supalytics -n "__fish_use_subcommand" -a "query" -d "Flexible query with custom metrics"
 complete -c supalytics -n "__fish_use_subcommand" -a "events" -d "List and explore custom events"
+complete -c supalytics -n "__fish_use_subcommand" -a "annotations" -d "Manage chart annotations"
 complete -c supalytics -n "__fish_use_subcommand" -a "realtime" -d "Live visitors right now"
 complete -c supalytics -n "__fish_use_subcommand" -a "completions" -d "Generate shell completions"
 complete -c supalytics -n "__fish_use_subcommand" -a "help" -d "Display help for command"
 
 # Stats options
-complete -c supalytics -n "__fish_seen_subcommand_from stats" -a "today yesterday week month year 7d 14d 30d 90d 12mo all"
 complete -c supalytics -n "__fish_seen_subcommand_from stats" -l site -s s -d "Site to query"
+complete -c supalytics -n "__fish_seen_subcommand_from stats" -l period -s p -d "Time period" -a "today yesterday week month year 7d 14d 30d 90d 12mo all"
 complete -c supalytics -n "__fish_seen_subcommand_from stats" -l start -d "Start date"
 complete -c supalytics -n "__fish_seen_subcommand_from stats" -l end -d "End date"
 complete -c supalytics -n "__fish_seen_subcommand_from stats" -l filter -s f -d "Filter"
@@ -293,6 +299,11 @@ complete -c supalytics -n "__fish_seen_subcommand_from events" -l limit -s l -d
 complete -c supalytics -n "__fish_seen_subcommand_from events" -l no-revenue -d "Exclude revenue"
 complete -c supalytics -n "__fish_seen_subcommand_from events" -l json -d "Output as JSON"
 
+# Annotations options
+complete -c supalytics -n "__fish_seen_subcommand_from annotations" -l site -s s -d "Site to query"
+complete -c supalytics -n "__fish_seen_subcommand_from annotations" -l period -s p -d "Time period" -a "7d 14d 30d 90d 12mo all"
+complete -c supalytics -n "__fish_seen_subcommand_from annotations" -l json -d "Output as JSON"
+
 # Realtime options
 complete -c supalytics -n "__fish_seen_subcommand_from realtime" -l site -s s -d "Site to query"
 complete -c supalytics -n "__fish_seen_subcommand_from realtime" -l json -d "Output as JSON"

package/src/commands/countries.ts

@@ -2,7 +2,7 @@ import { Command } from "commander";
 import chalk from "chalk";
 import { query, formatNumber } from "../api";
 import { getDefaultSite } from "../config";
-import { sparkBar, formatRevenue } from "../ui";
+import { sparkBar, formatRevenue, parsePeriod } from "../ui";
 
 export const countriesCommand = new Command("countries")
   .description("Traffic by country")
@@ -25,7 +25,7 @@ export const countriesCommand = new Command("countries")
 
     const dateRange = options.start && options.end
       ? [options.start, options.end] as [string, string]
-      : options.period;
+      : parsePeriod(options.period);
 
     const filters = options.filter
       ? options.filter.map((f: string) => {

package/src/commands/events.ts

@@ -8,6 +8,7 @@ import {
 	type PropertyKeysResponse,
 } from "../api"
 import { getDefaultSite } from "../config"
+import { parsePeriod } from "../ui"
 
 const eventsExamples = `
 Examples:
@@ -20,6 +21,10 @@ Examples:
   # Get breakdown of a property
   supalytics events signup --property plan
 
+  # With custom date range
+  supalytics events --start 2026-01-01 --end 2026-01-31
+  supalytics events signup --start 2026-01-01 --end 2026-01-31
+
   # Without revenue
   supalytics events signup --property plan --no-revenue`
 
@@ -52,6 +57,8 @@ export const eventsCommand = new Command("events")
 	.argument("[event]", "Event name to explore")
 	.option("-s, --site <site>", "Site to query")
 	.option("-p, --period <period>", "Time period: 7d, 14d, 30d, 90d, 12mo, all", "30d")
+	.option("--start <date>", "Start date (YYYY-MM-DD)")
+	.option("--end <date>", "End date (YYYY-MM-DD)")
 	.option("--property <key>", "Get breakdown for a specific property")
 	.option("-l, --limit <number>", "Number of results", "20")
 	.option("--no-revenue", "Exclude revenue metrics")
@@ -59,6 +66,9 @@ export const eventsCommand = new Command("events")
 	.option("-t, --test", "Test mode: query localhost data instead of production")
 	.action(async (event, options) => {
 		const site = options.site || (await getDefaultSite())
+		const dateRange = options.start && options.end
+			? [options.start, options.end] as [string, string]
+			: parsePeriod(options.period)
 
 		if (!site) {
 			console.error(
@@ -74,7 +84,7 @@ export const eventsCommand = new Command("events")
 			if (!event) {
 				const response = await listEvents(
 					site,
-					options.period,
+					dateRange,
 					parseInt(options.limit),
 					options.test || false
 				)
@@ -110,7 +120,7 @@ export const eventsCommand = new Command("events")
 					site,
 					event,
 					options.property,
-					options.period,
+					dateRange,
 					parseInt(options.limit),
 					options.revenue !== false,
 					options.test || false
@@ -146,8 +156,8 @@ export const eventsCommand = new Command("events")
 
 			// If just event name, show event stats + properties
 			const [eventsResponse, propsResponse] = await Promise.all([
-				listEvents(site, options.period, 100, options.test || false), // Get all events to find this one
-				getEventProperties(site, event, options.period, options.test || false),
+				listEvents(site, dateRange, 100, options.test || false), // Get all events to find this one
+				getEventProperties(site, event, dateRange, options.test || false),
 			])
 
 			// Find the specific event stats