@radjay/kit-analytics 0.0.2 → 0.0.3

package/README.md

@@ -0,0 +1,53 @@
+# @radjay/kit-analytics
+
+CLI tool for pulling newsletter data from [Kit.com](https://kit.com) via the Kit API v4.
+
+## Install
+
+```bash
+npm install -g @radjay/kit-analytics
+```
+
+## Configuration
+
+Provide your Kit API key via any of these methods (in priority order):
+
+1. `--api-key` flag
+2. `--api-key-cmd` flag (shell command, e.g. `--api-key-cmd "op read ..."`)
+3. `KIT_API_KEY` environment variable
+4. `.env` file in the current directory
+5. `~/.config/kit-analytics/config.json` (`api_key` field)
+
+## Commands
+
+| Command | Description |
+|---|---|
+| `account` | Display account info (name, plan, subscriber count) |
+| `subscribers` | List subscribers with filtering by status, tag, date range |
+| `broadcasts` | List sent emails with stats (open rate, click rate, etc.) |
+| `tags` | List all tags with subscriber counts |
+| `forms` | List all forms with subscriber counts |
+| `sequences` | List all sequences with subscriber counts |
+
+## Examples
+
+```bash
+# Verify setup
+kit-analytics account
+
+# Active subscribers added this month
+kit-analytics subscribers --status active --since 2025-02-01
+
+# Broadcast performance
+kit-analytics broadcasts --limit 10
+
+# JSON output
+kit-analytics tags --format json
+```
+
+## Global Options
+
+- `--api-key <key>` — Kit API key
+- `--api-key-cmd <cmd>` — shell command to retrieve API key
+- `--format <json|table>` — output format (default: `table`)
+- `--help` — show help

package/dist/api.d.ts

@@ -42,6 +42,27 @@ export interface Broadcast {
     send_at?: string | null;
     description?: string | null;
 }
+export interface BroadcastDetail {
+    id: number;
+    publication_id: number;
+    created_at: string;
+    subject: string;
+    preview_text: string | null;
+    description: string | null;
+    content: string | null;
+    public: boolean;
+    published_at: string | null;
+    send_at: string | null;
+    thumbnail_alt: string | null;
+    thumbnail_url: string | null;
+    public_url: string | null;
+    email_address: string | null;
+    email_template: {
+        id: number;
+        name: string;
+    } | null;
+    subscriber_filter: unknown[];
+}
 export interface Tag {
     id: number;
     name: string;
@@ -87,6 +108,9 @@ export declare class KitClient {
         broadcasts: Broadcast[];
         pagination: Pagination;
     }>;
+    getBroadcast(id: number): Promise<{
+        broadcast: BroadcastDetail;
+    }>;
     getBroadcastStats(id: number): Promise<{
         broadcast: {
             id: number;

package/dist/api.js

@@ -57,6 +57,9 @@ class KitClient {
             params["after"] = opts.cursor;
         return this.request("/broadcasts", params);
     }
+    async getBroadcast(id) {
+        return this.request(`/broadcasts/${id}`);
+    }
     async getBroadcastStats(id) {
         return this.request(`/broadcasts/${id}/stats`);
     }

package/dist/commands/broadcast.d.ts

@@ -0,0 +1,2 @@
+import { Command } from "commander";
+export declare function broadcastCommand(): Command;

package/dist/commands/broadcast.js

@@ -0,0 +1,42 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.broadcastCommand = broadcastCommand;
+const commander_1 = require("commander");
+const formatter_js_1 = require("../formatter.js");
+function broadcastCommand() {
+    return new commander_1.Command("broadcast")
+        .description("Get a single broadcast by ID (includes HTML content)")
+        .argument("<id>", "Broadcast ID")
+        .option("--content-only", "Output only the HTML content")
+        .action(async function (id) {
+        const client = this.opts()["__client"];
+        const format = this.opts()["__format"];
+        const opts = this.opts();
+        const res = await client.getBroadcast(Number(id));
+        const b = res.broadcast;
+        if (opts.contentOnly) {
+            console.log(b.content ?? "");
+            return;
+        }
+        if (format === "json") {
+            console.log(JSON.stringify(b, null, 2));
+            return;
+        }
+        (0, formatter_js_1.output)({
+            id: b.id,
+            subject: b.subject,
+            preview_text: b.preview_text ?? "",
+            email_address: b.email_address ?? "",
+            email_template: b.email_template?.name ?? "",
+            public: b.public,
+            public_url: b.public_url ?? "",
+            published_at: b.published_at ?? "",
+            send_at: b.send_at ?? "",
+            created_at: b.created_at,
+        }, format);
+        if (b.content) {
+            console.log("\n--- Content ---\n");
+            console.log(b.content);
+        }
+    });
+}

package/dist/index.js

@@ -2,9 +2,11 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 const commander_1 = require("commander");
+const resolve_key_1 = require("@radjay/resolve-key");
 const api_js_1 = require("./api.js");
 const account_js_1 = require("./commands/account.js");
 const subscribers_js_1 = require("./commands/subscribers.js");
+const broadcast_js_1 = require("./commands/broadcast.js");
 const broadcasts_js_1 = require("./commands/broadcasts.js");
 const tags_js_1 = require("./commands/tags.js");
 const forms_js_1 = require("./commands/forms.js");
@@ -15,12 +17,20 @@ program
     .description("Pull Kit.com newsletter analytics via Kit API v4")
     .version("0.0.2")
     .option("--api-key <key>", "Kit API key (overrides KIT_API_KEY env var)")
+    .option("--api-key-cmd <cmd>", "Shell command that outputs the API key")
     .option("--format <format>", "Output format: json or table", "table");
 program.hook("preAction", () => {
     const opts = program.opts();
-    const apiKey = opts.apiKey || process.env["KIT_API_KEY"];
+    const apiKey = (0, resolve_key_1.resolveKey)({
+        flag: opts.apiKey,
+        keyCmd: opts.apiKeyCmd,
+        envVar: "KIT_API_KEY",
+        appName: "kit-analytics",
+    });
     if (!apiKey) {
-        console.error("Error: Kit API key is required. Set KIT_API_KEY env var or pass --api-key.");
+        console.error("Error: Kit API key is required.\n" +
+            "  Set KIT_API_KEY env var, pass --api-key, use --api-key-cmd,\n" +
+            "  add it to a .env file, or save it in ~/.config/kit-analytics/config.json.");
         process.exit(1);
     }
     const client = new api_js_1.KitClient({ apiKey });
@@ -34,6 +44,7 @@ program.hook("preAction", () => {
 // Register commands — each command pulls client/format from its own opts
 program.addCommand((0, account_js_1.accountCommand)());
 program.addCommand((0, subscribers_js_1.subscribersCommand)());
+program.addCommand((0, broadcast_js_1.broadcastCommand)());
 program.addCommand((0, broadcasts_js_1.broadcastsCommand)());
 program.addCommand((0, tags_js_1.tagsCommand)());
 program.addCommand((0, forms_js_1.formsCommand)());

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@radjay/kit-analytics",
-  "version": "0.0.2",
+  "version": "0.0.3",
   "description": "CLI tool to pull Kit.com newsletter analytics via Kit API v4",
   "bin": {
     "kit-analytics": "./dist/index.js"
@@ -11,6 +11,7 @@
     "clean": "rm -rf dist"
   },
   "dependencies": {
+    "@radjay/resolve-key": "workspace:*",
     "commander": "^13.1.0"
   },
   "devDependencies": {