@supalytics/cli 0.4.1 → 0.4.3

package/src/commands/funnels.ts

@@ -0,0 +1,485 @@
+import chalk from "chalk"
+import { Command } from "commander"
+import {
+	listFunnels,
+	getFunnel,
+	createFunnel,
+	updateFunnel,
+	analyzeFunnel,
+	formatNumber,
+	formatPercent,
+	type FunnelStepInput,
+	type FunnelAnalysisRow,
+} from "../api"
+import { getDefaultSite } from "../config"
+import { parsePeriod, sparkBar } 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()
+	// Own opts take priority, but fall back to parent for unset values
+	return { ...parentOpts, ...ownOpts }
+}
+
+async function resolveSiteOption(cmd: Command): Promise<string | undefined> {
+	const opts = mergedOpts(cmd)
+	return (opts.site as string) || (await getDefaultSite())
+}
+
+const funnelsExamples = `
+Examples:
+  # List all funnels
+  supalytics funnels
+
+  # View a funnel with conversion analysis
+  supalytics funnels view <id>
+
+  # View with custom date range
+  supalytics funnels view <id> -p 90d
+
+  # Create a funnel
+  supalytics funnels create "Signup Flow" --step "page:/pricing" --step "event:signup_clicked" --step "purchase"
+
+  # Create with page matching
+  supalytics funnels create "Blog to Signup" --step "page:starts_with:/blog" --step "page:/signup" --step "event:account_created"
+
+  # Create an ordered funnel
+  supalytics funnels create "Checkout" --mode ordered --step "page:/cart" --step "page:/checkout" --step "purchase"
+
+  # Update funnel name
+  supalytics funnels update <id> --name "New Name"
+
+  # Update funnel steps
+  supalytics funnels update <id> --step "page:/pricing" --step "purchase"`
+
+/**
+ * Parse a step definition string into a FunnelStepInput.
+ *
+ * Formats:
+ *   page:/pricing              → page, exact, /pricing
+ *   page:starts_with:/blog     → page, starts_with, /blog
+ *   page:contains:pricing      → page, contains, pricing
+ *   page:regex:^/blog/.*       → page, regex, ^/blog/.*
+ *   event:signup_clicked       → event, match_value=signup_clicked
+ *   event:signup:plan:pro      → event, match_value=signup, property_key=plan, property_value=pro
+ *   purchase                   → purchase type
+ *   trial                      → trial type
+ */
+function parseStep(definition: string): FunnelStepInput {
+	const parts = definition.split(":")
+
+	// Simple types: "purchase" or "trial"
+	if (parts.length === 1) {
+		const type = parts[0].toLowerCase()
+		if (type === "purchase" || type === "trial") {
+			return { name: type === "purchase" ? "Purchase" : "Trial start", type }
+		}
+		throw new Error(
+			`Invalid step: "${definition}". Use "page:<path>", "event:<name>", "purchase", or "trial"`
+		)
+	}
+
+	const type = parts[0].toLowerCase()
+
+	if (type === "page") {
+		// Check for explicit match type: page:starts_with:/blog
+		const matchTypes = ["exact", "starts_with", "contains", "regex"]
+		if (parts.length >= 3 && matchTypes.includes(parts[1])) {
+			const matchType = parts[1]
+			const matchValue = parts.slice(2).join(":")
+			return {
+				name: `Visit ${matchValue}`,
+				type: "page",
+				match_type: matchType,
+				match_value: matchValue,
+			}
+		}
+		// Default: page:/pricing → exact match
+		const matchValue = parts.slice(1).join(":")
+		return {
+			name: `Visit ${matchValue}`,
+			type: "page",
+			match_type: "exact",
+			match_value: matchValue,
+		}
+	}
+
+	if (type === "event") {
+		const eventName = parts[1]
+		// event:signup:plan:pro → event with property filter
+		if (parts.length >= 4) {
+			return {
+				name: eventName,
+				type: "event",
+				match_value: eventName,
+				property_key: parts[2],
+				property_value: parts.slice(3).join(":"),
+			}
+		}
+		return {
+			name: eventName,
+			type: "event",
+			match_value: eventName,
+		}
+	}
+
+	throw new Error(
+		`Invalid step type "${type}". Use "page", "event", "purchase", or "trial"`
+	)
+}
+
+/**
+ * Get a human-readable label for a step
+ */
+function stepLabel(step: { type: string; match_type?: string | null; match_value?: string | null; name?: string }): string {
+	if (step.type === "purchase") return "Purchase"
+	if (step.type === "trial") return "Trial start"
+	if (step.type === "page") {
+		const prefix = step.match_type && step.match_type !== "exact" ? `${step.match_type}: ` : ""
+		return `${prefix}${step.match_value || step.name || "page"}`
+	}
+	if (step.type === "event") {
+		return step.match_value || step.name || "event"
+	}
+	return step.name || step.type
+}
+
+/**
+ * Render funnel analysis results
+ */
+function renderAnalysis(rows: FunnelAnalysisRow[], funnel: { name: string; description?: string | null; mode: string; steps: Array<{ name: string; type: string; match_type?: string | null; match_value?: string | null }> }) {
+	console.log()
+	console.log(chalk.bold(funnel.name))
+	if (funnel.description) {
+		console.log(chalk.dim(`  ${funnel.description}`))
+	}
+	console.log(chalk.dim(`  Mode: ${funnel.mode}`))
+	console.log()
+
+	if (rows.length === 0) {
+		console.log(chalk.dim("  No data for the selected period"))
+		console.log()
+		return
+	}
+
+	const maxVisitors = Math.max(...rows.map((r) => r.visitors))
+
+	for (const row of rows) {
+		// ClickHouse may return "ps.<col>" instead of "<col>" for joined columns
+		const rawRow = row as Record<string, unknown>
+		const stepOrder = row.step_order ?? (rawRow["ps.step_order"] as number)
+		const stepType = row.step_type ?? (rawRow["ps.step_type"] as string)
+		const matchType = row.match_type ?? (rawRow["ps.match_type"] as string | null)
+		const matchValue = row.match_value ?? (rawRow["ps.match_value"] as string | null)
+		const stepNum = `Step ${stepOrder}:`
+		const label = stepLabel({
+			type: stepType,
+			match_type: matchType,
+			match_value: matchValue,
+			name: funnel.steps[stepOrder - 1]?.name,
+		})
+		const visitors = formatNumber(row.visitors)
+		const bar = sparkBar(row.visitors, maxVisitors, 16)
+		const pct = formatPercent(row.conversion_rate_from_start)
+
+		let dropoff = ""
+		if (stepOrder > 1) {
+			const drop = row.conversion_rate_from_prev - 100
+			dropoff = chalk.red(` (${drop >= 0 ? "+" : ""}${drop.toFixed(1)}%)`)
+		}
+
+		console.log(
+			`  ${chalk.dim(stepNum.padEnd(8))} ${label.padEnd(30)} ${visitors.padStart(10)} visitors  ${bar}  ${pct.padStart(6)}${dropoff}`
+		)
+	}
+
+	// Overall conversion
+	if (rows.length >= 2) {
+		const first = rows[0]
+		const last = rows[rows.length - 1]
+		const overall = first.visitors > 0 ? (last.visitors / first.visitors) * 100 : 0
+		console.log()
+		console.log(
+			chalk.bold(`  Overall conversion: ${formatPercent(overall)}`) +
+				chalk.dim(` (${formatNumber(first.visitors)} → ${formatNumber(last.visitors)})`)
+		)
+	}
+	console.log()
+}
+
+export const funnelsCommand = new Command("funnels")
+	.description("Manage and analyze conversion funnels")
+	.addHelpText("after", funnelsExamples)
+	.option("-s, --site <site>", "Site to query")
+	.option("--json", "Output as JSON")
+	.action(async (options) => {
+		const site = options.site || (await getDefaultSite())
+
+		if (!site) {
+			console.error(
+				chalk.red(
+					"Error: No site specified. Use --site or set a default with `supalytics login --site`"
+				)
+			)
+			process.exit(1)
+		}
+
+		try {
+			const response = await listFunnels(site)
+
+			if (options.json) {
+				console.log(JSON.stringify(response, null, 2))
+				return
+			}
+
+			console.log()
+			console.log(chalk.bold("Funnels"))
+			console.log()
+
+			if (response.data.length === 0) {
+				console.log(chalk.dim("  No funnels found"))
+				console.log()
+				console.log(
+					chalk.dim(
+						'  Create one with: supalytics funnels create "Name" --step "page:/pricing" --step "purchase"'
+					)
+				)
+				console.log()
+				return
+			}
+
+			for (const funnel of response.data) {
+				const stepCount = funnel.steps?.length || 0
+				const created = new Date(funnel.created_at).toISOString().split("T")[0]
+				console.log(
+					`  ${chalk.cyan(funnel.name.padEnd(30))} ${String(stepCount).padStart(2)} steps  ${funnel.mode.padEnd(10)}  ${chalk.dim(created)}`
+				)
+				if (funnel.description) {
+					console.log(`  ${chalk.dim(funnel.description)}`)
+				}
+				console.log(chalk.dim(`  id: ${funnel.id}`))
+				console.log()
+			}
+		} catch (error) {
+			console.error(chalk.red(`Error: ${(error as Error).message}`))
+			process.exit(1)
+		}
+	})
+
+// Subcommand: view
+funnelsCommand
+	.command("view <id>")
+	.description("View funnel details and conversion analysis")
+	.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("--json", "Output as JSON")
+	.action(async (id, _options, cmd) => {
+		const options = mergedOpts(cmd)
+		const site = await resolveSiteOption(cmd)
+
+		if (!site) {
+			console.error(
+				chalk.red(
+					"Error: No site specified. Use --site or set a default with `supalytics login --site`"
+				)
+			)
+			process.exit(1)
+		}
+
+		try {
+			const dateRange =
+				options.start && options.end
+					? ([options.start, options.end] as [string, string])
+					: parsePeriod(options.period as string)
+
+			// Fetch funnel definition and run analysis in parallel
+			const [funnelResponse, analysisResponse] = await Promise.all([
+				getFunnel(site, id),
+				analyzeFunnel(site, id, dateRange),
+			])
+
+			if (options.json) {
+				console.log(
+					JSON.stringify(
+						{
+							funnel: funnelResponse.data,
+							analysis: analysisResponse.data,
+							meta: analysisResponse.meta,
+						},
+						null,
+						2
+					)
+				)
+				return
+			}
+
+			const [startDate, endDate] = analysisResponse.meta.date_range
+			console.log(chalk.dim(`  ${startDate} → ${endDate}  (${analysisResponse.meta.query_ms}ms)`))
+
+			renderAnalysis(analysisResponse.data, funnelResponse.data)
+		} catch (error) {
+			console.error(chalk.red(`Error: ${(error as Error).message}`))
+			process.exit(1)
+		}
+	})
+
+// Subcommand: create
+funnelsCommand
+	.command("create <name>")
+	.description("Create a new funnel")
+	.option("-s, --site <site>", "Site to query")
+	.option("--step <definition>", "Step definition (repeatable)", (val: string, prev: string[]) => prev.concat(val), [] as string[])
+	.option("--mode <mode>", "Funnel mode: ordered or unordered", "unordered")
+	.option("-d, --description <text>", "Optional description")
+	.option("--json", "Output as JSON")
+	.action(async (name, _options, cmd) => {
+		const options = mergedOpts(cmd)
+		const site = await resolveSiteOption(cmd)
+
+		if (!site) {
+			console.error(
+				chalk.red(
+					"Error: No site specified. Use --site or set a default with `supalytics login --site`"
+				)
+			)
+			process.exit(1)
+		}
+
+		const steps = options.step as string[] | undefined
+		if (!steps || steps.length === 0) {
+			console.error(chalk.red("Error: At least one --step is required"))
+			console.error(
+				chalk.dim('  Example: --step "page:/pricing" --step "event:signup" --step "purchase"')
+			)
+			process.exit(1)
+		}
+
+		if (!["ordered", "unordered"].includes(options.mode as string)) {
+			console.error(chalk.red("Error: --mode must be 'ordered' or 'unordered'"))
+			process.exit(1)
+		}
+
+		try {
+			const parsedSteps: FunnelStepInput[] = steps.map((s: string) => parseStep(s))
+
+			const response = await createFunnel(site, {
+				name,
+				description: options.description as string | undefined,
+				mode: options.mode as string | undefined,
+				steps: parsedSteps,
+			})
+
+			if (options.json) {
+				console.log(JSON.stringify(response, null, 2))
+				return
+			}
+
+			console.log()
+			console.log(chalk.green("Funnel created"))
+			console.log()
+			console.log(`  ${chalk.bold(response.data.name)}`)
+			if (response.data.description) {
+				console.log(`  ${chalk.dim(response.data.description)}`)
+			}
+			console.log(chalk.dim(`  Mode: ${response.data.mode}`))
+			console.log()
+
+			for (const step of response.data.steps) {
+				console.log(
+					`  ${chalk.dim(`Step ${step.step_order}:`)} ${stepLabel(step)}`
+				)
+			}
+			console.log()
+			console.log(chalk.dim(`  id: ${response.data.id}`))
+			console.log()
+		} catch (error) {
+			console.error(chalk.red(`Error: ${(error as Error).message}`))
+			process.exit(1)
+		}
+	})
+
+// Subcommand: update
+funnelsCommand
+	.command("update <id>")
+	.description("Update an existing funnel")
+	.option("-s, --site <site>", "Site to query")
+	.option("--name <name>", "New funnel name")
+	.option("-d, --description <text>", "New description")
+	.option("--mode <mode>", "Funnel mode: ordered or unordered")
+	.option("--step <definition>", "Replace steps (repeatable)", (val: string, prev: string[]) => prev.concat(val), [] as string[])
+	.option("--json", "Output as JSON")
+	.action(async (id, _options, cmd) => {
+		const options = mergedOpts(cmd)
+		const site = await resolveSiteOption(cmd)
+
+		if (!site) {
+			console.error(
+				chalk.red(
+					"Error: No site specified. Use --site or set a default with `supalytics login --site`"
+				)
+			)
+			process.exit(1)
+		}
+
+		if (options.mode && !["ordered", "unordered"].includes(options.mode as string)) {
+			console.error(chalk.red("Error: --mode must be 'ordered' or 'unordered'"))
+			process.exit(1)
+		}
+
+		const updateData: {
+			name?: string
+			description?: string
+			mode?: string
+			steps?: FunnelStepInput[]
+		} = {}
+
+		if (options.name) updateData.name = options.name as string
+		if (options.description) updateData.description = options.description as string
+		if (options.mode) updateData.mode = options.mode as string
+		const updateSteps = options.step as string[] | undefined
+		if (updateSteps && updateSteps.length > 0) {
+			updateData.steps = updateSteps.map((s: string) => parseStep(s))
+		}
+
+		if (Object.keys(updateData).length === 0) {
+			console.error(chalk.red("Error: No updates specified"))
+			console.error(chalk.dim("  Use --name, --description, --mode, or --step"))
+			process.exit(1)
+		}
+
+		try {
+			const response = await updateFunnel(site, id, updateData)
+
+			if (options.json) {
+				console.log(JSON.stringify(response, null, 2))
+				return
+			}
+
+			console.log()
+			console.log(chalk.green("Funnel updated"))
+			console.log()
+			console.log(`  ${chalk.bold(response.data.name)}`)
+			if (response.data.description) {
+				console.log(`  ${chalk.dim(response.data.description)}`)
+			}
+			console.log(chalk.dim(`  Mode: ${response.data.mode}`))
+			console.log()
+
+			for (const step of response.data.steps) {
+				console.log(
+					`  ${chalk.dim(`Step ${step.step_order}:`)} ${stepLabel(step)}`
+				)
+			}
+			console.log()
+		} catch (error) {
+			console.error(chalk.red(`Error: ${(error as Error).message}`))
+			process.exit(1)
+		}
+	})

package/src/commands/pages.ts

@@ -2,7 +2,7 @@ import { Command } from "commander";
 import chalk from "chalk";
 import { query, formatNumber } from "../api";
 import { getDefaultSite } from "../config";
-import { sparkBar, truncate, formatRevenue } from "../ui";
+import { sparkBar, truncate, formatRevenue, parsePeriod } from "../ui";
 
 export const pagesCommand = new Command("pages")
   .description("Top pages by visitors")
@@ -25,7 +25,7 @@ export const pagesCommand = new Command("pages")
 
     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/query.ts

@@ -2,7 +2,7 @@ import chalk from "chalk"
 import { Command } from "commander"
 import { formatDuration, formatNumber, formatPercent, query } from "../api"
 import { getDefaultSite } from "../config"
-import { type TableColumn, table } from "../ui"
+import { type TableColumn, table, parsePeriod } from "../ui"
 
 const queryExamples = `
 Examples:
@@ -75,7 +75,7 @@ export const queryCommand = new Command("query")
 		const dateRange =
 			options.start && options.end
 				? ([options.start, options.end] as [string, string])
-				: options.period
+				: parsePeriod(options.period)
 
 		// Parse metrics
 		const metrics = options.metrics.split(",").map((m: string) => m.trim())

package/src/commands/referrers.ts

@@ -2,7 +2,7 @@ import { Command } from "commander";
 import chalk from "chalk";
 import { query, formatNumber } from "../api";
 import { getDefaultSite } from "../config";
-import { sparkBar, truncate, formatRevenue } from "../ui";
+import { sparkBar, truncate, formatRevenue, parsePeriod } from "../ui";
 
 export const referrersCommand = new Command("referrers")
   .description("Top referrers")
@@ -25,7 +25,7 @@ export const referrersCommand = new Command("referrers")
 
     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) => {