@supalytics/cli 0.3.5 → 0.3.6

package/package.json

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

package/src/api.ts

@@ -327,3 +327,150 @@ export async function getRealtime(site: string, isDev: boolean = false): Promise
 
   return response.json();
 }
+
+// Annotations API types
+export interface AnnotationItem {
+  id: string;
+  date: string; // YYYY-MM-DD
+  title: string;
+  description?: string;
+  created_by: string;
+  created_at: string;
+}
+
+export interface AnnotationsResponse {
+  data: AnnotationItem[];
+  meta: {
+    domain: string;
+    date_range: [string | null, string | null];
+  };
+}
+
+/**
+ * List annotations for a site
+ */
+export async function listAnnotations(
+  site: string,
+  period: string = "30d"
+): Promise<AnnotationsResponse> {
+  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(", ")}`
+    );
+  }
+
+  // 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 formatDate = (d: Date) => d.toISOString().split("T")[0];
+  const params = new URLSearchParams({
+    domain: site,
+    start_date: formatDate(startDate),
+    end_date: formatDate(endDate),
+  });
+
+  const response = await fetch(`${API_BASE}/v1/annotations?${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 an annotation
+ */
+export async function createAnnotation(
+  site: string,
+  date: string,
+  title: string,
+  description?: string
+): Promise<AnnotationItem> {
+  const apiKey = await getApiKeyForSite(site);
+
+  if (!apiKey) {
+    throw new Error(`Not authenticated. Run \`supalytics login\` first.`);
+  }
+
+  const response = await fetch(`${API_BASE}/v1/annotations`, {
+    method: "POST",
+    headers: {
+      Authorization: `Bearer ${apiKey}`,
+      "Content-Type": "application/json",
+    },
+    body: JSON.stringify({
+      domain: site,
+      date,
+      title,
+      description,
+    }),
+  });
+
+  if (!response.ok) {
+    const error = (await response.json()) as ApiError;
+    throw new Error(error.message || error.error || `HTTP ${response.status}`);
+  }
+
+  return response.json();
+}
+
+/**
+ * Delete an annotation
+ */
+export async function deleteAnnotation(
+  site: string,
+  annotationId: string
+): Promise<void> {
+  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/annotations/${annotationId}?${params}`,
+    {
+      method: "DELETE",
+      headers: { Authorization: `Bearer ${apiKey}` },
+    }
+  );
+
+  if (!response.ok) {
+    const error = (await response.json()) as ApiError;
+    throw new Error(error.message || error.error || `HTTP ${response.status}`);
+  }
+}

package/src/commands/annotations.ts

@@ -0,0 +1,139 @@
+import { Command } from "commander";
+import chalk from "chalk";
+import { listAnnotations, createAnnotation, deleteAnnotation } from "../api";
+import { getDefaultSite } from "../config";
+
+const annotationsDescription = `Manage chart annotations.
+
+Examples:
+  # List all annotations
+  supalytics annotations
+
+  # List annotations for a specific period
+  supalytics annotations -p 90d
+
+  # Add an annotation
+  supalytics annotations add 2025-01-15 "Launched v2.0"
+
+  # Add an annotation with description
+  supalytics annotations add 2025-01-15 "Launched v2.0" -d "Major redesign with new dashboard"
+
+  # Remove an annotation
+  supalytics annotations remove <id>`;
+
+export const annotationsCommand = new Command("annotations")
+  .description(annotationsDescription)
+  .argument("[period]", "Time period: 7d, 14d, 30d, 90d, 12mo, all", "30d")
+  .option("-s, --site <site>", "Site to query")
+  .option("--json", "Output as JSON")
+  .action(async (period, 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 listAnnotations(site, period);
+
+      if (options.json) {
+        console.log(JSON.stringify(response, null, 2));
+        return;
+      }
+
+      const [startDate, endDate] = response.meta.date_range;
+      console.log();
+      console.log(chalk.bold("Annotations"), chalk.dim(`${startDate} → ${endDate}`));
+      console.log();
+
+      if (response.data.length === 0) {
+        console.log(chalk.dim("  No annotations found"));
+        console.log();
+        console.log(chalk.dim("  Add one with: supalytics annotations add <date> <title>"));
+        console.log();
+        return;
+      }
+
+      for (const annotation of response.data) {
+        console.log(`  ${chalk.cyan(annotation.date)}  ${annotation.title}`);
+        if (annotation.description) {
+          console.log(`              ${chalk.dim(annotation.description)}`);
+        }
+        console.log(chalk.dim(`              id: ${annotation.id}`));
+      }
+      console.log();
+    } catch (error) {
+      console.error(chalk.red(`Error: ${(error as Error).message}`));
+      process.exit(1);
+    }
+  });
+
+// Subcommand: add
+annotationsCommand
+  .command("add <date> <title>")
+  .description("Add an annotation")
+  .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());
+
+    if (!site) {
+      console.error(chalk.red("Error: No site specified. Use --site or set a default with `supalytics login --site`"));
+      process.exit(1);
+    }
+
+    // Validate date format
+    if (!/^\d{4}-\d{2}-\d{2}$/.test(date)) {
+      console.error(chalk.red("Error: Date must be in YYYY-MM-DD format"));
+      process.exit(1);
+    }
+
+    try {
+      const annotation = await createAnnotation(site, date, title, options.description);
+
+      if (options.json) {
+        console.log(JSON.stringify(annotation, null, 2));
+        return;
+      }
+
+      console.log();
+      console.log(chalk.green("Annotation added"));
+      console.log();
+      console.log(`  ${chalk.cyan(annotation.date)}  ${annotation.title}`);
+      if (annotation.description) {
+        console.log(`              ${chalk.dim(annotation.description)}`);
+      }
+      console.log(chalk.dim(`              id: ${annotation.id}`));
+      console.log();
+    } catch (error) {
+      console.error(chalk.red(`Error: ${(error as Error).message}`));
+      process.exit(1);
+    }
+  });
+
+// Subcommand: remove
+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());
+
+    if (!site) {
+      console.error(chalk.red("Error: No site specified. Use --site or set a default with `supalytics login --site`"));
+      process.exit(1);
+    }
+
+    try {
+      await deleteAnnotation(site, id);
+
+      console.log();
+      console.log(chalk.green("Annotation removed"));
+      console.log();
+    } catch (error) {
+      console.error(chalk.red(`Error: ${(error as Error).message}`));
+      process.exit(1);
+    }
+  });

package/src/index.ts

@@ -13,6 +13,7 @@ import { queryCommand } from "./commands/query";
 import { eventsCommand } from "./commands/events";
 import { realtimeCommand } from "./commands/realtime";
 import { completionsCommand } from "./commands/completions";
+import { annotationsCommand } from "./commands/annotations";
 import { initCommand } from "./commands/init";
 import { updateCommand } from "./commands/update";
 
@@ -93,6 +94,7 @@ program.addCommand(trendCommand);
 program.addCommand(queryCommand);
 program.addCommand(eventsCommand);
 program.addCommand(realtimeCommand);
+program.addCommand(annotationsCommand);
 program.addCommand(completionsCommand);
 
 // Utility commands