@radjay/kit-analytics 0.0.1

package/dist/api.d.ts

@@ -0,0 +1,115 @@
+export interface KitClientOptions {
+    apiKey: string;
+}
+export interface Pagination {
+    has_previous_page: boolean;
+    has_next_page: boolean;
+    start_cursor: string | null;
+    end_cursor: string | null;
+    per_page: number;
+}
+export interface AccountUser {
+    id: number;
+    email: string;
+}
+export interface AccountInfo {
+    id: number;
+    name: string;
+    plan_type: string;
+    primary_email_address: string;
+    created_at: string;
+}
+export interface Subscriber {
+    id: number;
+    email_address: string;
+    first_name: string | null;
+    state: string;
+    created_at: string;
+}
+export interface BroadcastStats {
+    recipients: number;
+    open_rate: number;
+    click_rate: number;
+    unsubscribes: number;
+    total_clicks: number;
+    status: string;
+}
+export interface Broadcast {
+    id: number;
+    subject: string;
+    created_at: string;
+    published_at?: string | null;
+    send_at?: string | null;
+    description?: string | null;
+}
+export interface Tag {
+    id: number;
+    name: string;
+    created_at: string;
+}
+export interface Form {
+    id: number;
+    name: string;
+    type: string;
+    format: string | null;
+    created_at: string;
+    archived: boolean;
+}
+export interface Sequence {
+    id: number;
+    name: string;
+    created_at: string;
+}
+export declare class KitClient {
+    private apiKey;
+    constructor(opts: KitClientOptions);
+    private request;
+    getAccount(): Promise<{
+        user: AccountUser;
+        account: AccountInfo;
+    }>;
+    listSubscribers(opts?: {
+        status?: string;
+        tagId?: string;
+        since?: string;
+        until?: string;
+        limit?: string;
+        cursor?: string;
+    }): Promise<{
+        subscribers: Subscriber[];
+        pagination: Pagination;
+    }>;
+    listBroadcasts(opts?: {
+        status?: string;
+        limit?: string;
+        cursor?: string;
+    }): Promise<{
+        broadcasts: Broadcast[];
+        pagination: Pagination;
+    }>;
+    getBroadcastStats(id: number): Promise<{
+        broadcast: {
+            id: number;
+            stats: BroadcastStats;
+        };
+    }>;
+    listTags(opts?: {
+        cursor?: string;
+    }): Promise<{
+        tags: Tag[];
+        pagination: Pagination;
+    }>;
+    listForms(opts?: {
+        status?: string;
+        cursor?: string;
+    }): Promise<{
+        forms: Form[];
+        pagination: Pagination;
+    }>;
+    listSequences(opts?: {
+        cursor?: string;
+    }): Promise<{
+        sequences: Sequence[];
+        pagination: Pagination;
+    }>;
+}

package/dist/api.js

@@ -0,0 +1,84 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.KitClient = void 0;
+const BASE_URL = "https://api.kit.com/v4";
+class KitClient {
+    apiKey;
+    constructor(opts) {
+        this.apiKey = opts.apiKey;
+    }
+    async request(path, params) {
+        const url = new URL(`${BASE_URL}${path}`);
+        if (params) {
+            for (const [key, value] of Object.entries(params)) {
+                if (value !== undefined && value !== "") {
+                    url.searchParams.set(key, value);
+                }
+            }
+        }
+        const res = await fetch(url.toString(), {
+            headers: {
+                "X-Kit-Api-Key": this.apiKey,
+                Accept: "application/json",
+            },
+        });
+        if (!res.ok) {
+            const body = await res.text();
+            throw new Error(`Kit API error ${res.status}: ${body}`);
+        }
+        return res.json();
+    }
+    async getAccount() {
+        return this.request("/account");
+    }
+    async listSubscribers(opts) {
+        const params = {};
+        if (opts?.status)
+            params["status"] = opts.status;
+        if (opts?.tagId)
+            params["tag_id"] = opts.tagId;
+        if (opts?.since)
+            params["created_after"] = opts.since;
+        if (opts?.until)
+            params["created_before"] = opts.until;
+        if (opts?.limit)
+            params["per_page"] = opts.limit;
+        if (opts?.cursor)
+            params["after"] = opts.cursor;
+        return this.request("/subscribers", params);
+    }
+    async listBroadcasts(opts) {
+        const params = {};
+        if (opts?.status)
+            params["status"] = opts.status;
+        if (opts?.limit)
+            params["per_page"] = opts.limit;
+        if (opts?.cursor)
+            params["after"] = opts.cursor;
+        return this.request("/broadcasts", params);
+    }
+    async getBroadcastStats(id) {
+        return this.request(`/broadcasts/${id}/stats`);
+    }
+    async listTags(opts) {
+        const params = {};
+        if (opts?.cursor)
+            params["after"] = opts.cursor;
+        return this.request("/tags", params);
+    }
+    async listForms(opts) {
+        const params = {};
+        if (opts?.status)
+            params["status"] = opts.status;
+        if (opts?.cursor)
+            params["after"] = opts.cursor;
+        return this.request("/forms", params);
+    }
+    async listSequences(opts) {
+        const params = {};
+        if (opts?.cursor)
+            params["after"] = opts.cursor;
+        return this.request("/sequences", params);
+    }
+}
+exports.KitClient = KitClient;

package/dist/commands/account.d.ts

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

package/dist/commands/account.js

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.accountCommand = accountCommand;
+const commander_1 = require("commander");
+const formatter_js_1 = require("../formatter.js");
+function accountCommand() {
+    return new commander_1.Command("account")
+        .description("Display account info")
+        .action(async function () {
+        const client = this.opts()["__client"];
+        const format = this.opts()["__format"];
+        const res = await client.getAccount();
+        (0, formatter_js_1.output)({
+            name: res.account.name,
+            plan: res.account.plan_type,
+            email: res.account.primary_email_address,
+            created_at: res.account.created_at,
+        }, format);
+    });
+}

package/dist/commands/broadcasts.d.ts

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

package/dist/commands/broadcasts.js

@@ -0,0 +1,35 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.broadcastsCommand = broadcastsCommand;
+const commander_1 = require("commander");
+const formatter_js_1 = require("../formatter.js");
+function broadcastsCommand() {
+    return new commander_1.Command("broadcasts")
+        .description("List broadcasts with stats (defaults to completed only)")
+        .option("--status <status>", "Filter by stats status (completed, scheduled, all)", "completed")
+        .option("--limit <n>", "Max results per page")
+        .action(async function () {
+        const client = this.opts()["__client"];
+        const format = this.opts()["__format"];
+        const opts = this.opts();
+        const res = await client.listBroadcasts({ limit: opts.limit });
+        const rows = [];
+        for (const b of res.broadcasts) {
+            const statsRes = await client.getBroadcastStats(b.id);
+            const s = statsRes.broadcast.stats;
+            if (opts.status !== "all" && s.status !== opts.status)
+                continue;
+            rows.push({
+                id: b.id,
+                subject: b.subject ?? "",
+                created_at: b.created_at,
+                recipients: s.recipients,
+                open_rate: `${s.open_rate.toFixed(1)}%`,
+                click_rate: `${s.click_rate.toFixed(1)}%`,
+                unsubscribes: s.unsubscribes,
+                status: s.status,
+            });
+        }
+        (0, formatter_js_1.output)(rows, format);
+    });
+}

package/dist/commands/forms.d.ts

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

package/dist/commands/forms.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formsCommand = formsCommand;
+const commander_1 = require("commander");
+const formatter_js_1 = require("../formatter.js");
+function formsCommand() {
+    return new commander_1.Command("forms")
+        .description("List all forms")
+        .action(async function () {
+        const client = this.opts()["__client"];
+        const format = this.opts()["__format"];
+        const res = await client.listForms();
+        const rows = res.forms.map((f) => ({
+            id: f.id,
+            name: f.name,
+            type: f.type,
+            archived: f.archived,
+            created_at: f.created_at,
+        }));
+        (0, formatter_js_1.output)(rows, format);
+    });
+}

package/dist/commands/sequences.d.ts

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

package/dist/commands/sequences.js

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sequencesCommand = sequencesCommand;
+const commander_1 = require("commander");
+const formatter_js_1 = require("../formatter.js");
+function sequencesCommand() {
+    return new commander_1.Command("sequences")
+        .description("List all sequences")
+        .action(async function () {
+        const client = this.opts()["__client"];
+        const format = this.opts()["__format"];
+        const res = await client.listSequences();
+        const rows = res.sequences.map((s) => ({
+            id: s.id,
+            name: s.name,
+            created_at: s.created_at,
+        }));
+        (0, formatter_js_1.output)(rows, format);
+    });
+}

package/dist/commands/subscribers.d.ts

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

package/dist/commands/subscribers.js

@@ -0,0 +1,34 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.subscribersCommand = subscribersCommand;
+const commander_1 = require("commander");
+const formatter_js_1 = require("../formatter.js");
+function subscribersCommand() {
+    return new commander_1.Command("subscribers")
+        .description("List subscribers")
+        .option("--status <status>", "Filter by status (active, cancelled, bounced, complained)")
+        .option("--tag <tag_id>", "Filter by tag ID")
+        .option("--since <date>", "Created after date (ISO 8601)")
+        .option("--until <date>", "Created before date (ISO 8601)")
+        .option("--limit <n>", "Max results per page")
+        .action(async function () {
+        const client = this.opts()["__client"];
+        const format = this.opts()["__format"];
+        const opts = this.opts();
+        const res = await client.listSubscribers({
+            status: opts.status,
+            tagId: opts.tag,
+            since: opts.since,
+            until: opts.until,
+            limit: opts.limit,
+        });
+        const rows = res.subscribers.map((s) => ({
+            id: s.id,
+            email: s.email_address,
+            first_name: s.first_name ?? "",
+            state: s.state,
+            created_at: s.created_at,
+        }));
+        (0, formatter_js_1.output)(rows, format);
+    });
+}

package/dist/commands/tags.d.ts

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

package/dist/commands/tags.js

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.tagsCommand = tagsCommand;
+const commander_1 = require("commander");
+const formatter_js_1 = require("../formatter.js");
+function tagsCommand() {
+    return new commander_1.Command("tags")
+        .description("List all tags")
+        .action(async function () {
+        const client = this.opts()["__client"];
+        const format = this.opts()["__format"];
+        const res = await client.listTags();
+        const rows = res.tags.map((t) => ({
+            id: t.id,
+            name: t.name,
+            created_at: t.created_at,
+        }));
+        (0, formatter_js_1.output)(rows, format);
+    });
+}

package/dist/formatter.d.ts

@@ -0,0 +1,2 @@
+export declare function formatTable(rows: Record<string, unknown>[]): string;
+export declare function output(data: unknown, format: string): void;

package/dist/formatter.js

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatTable = formatTable;
+exports.output = output;
+function formatTable(rows) {
+    if (rows.length === 0)
+        return "(no data)";
+    const keys = Object.keys(rows[0]);
+    const widths = keys.map((k) => Math.max(k.length, ...rows.map((r) => String(r[k] ?? "").length)));
+    const header = keys.map((k, i) => k.padEnd(widths[i])).join("  ");
+    const separator = widths.map((w) => "-".repeat(w)).join("  ");
+    const body = rows
+        .map((r) => keys.map((k, i) => String(r[k] ?? "").padEnd(widths[i])).join("  "))
+        .join("\n");
+    return `${header}\n${separator}\n${body}`;
+}
+function output(data, format) {
+    if (format === "json") {
+        console.log(JSON.stringify(data, null, 2));
+    }
+    else {
+        if (Array.isArray(data)) {
+            console.log(formatTable(data));
+        }
+        else {
+            console.log(formatTable([data]));
+        }
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,44 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const commander_1 = require("commander");
+const api_js_1 = require("./api.js");
+const account_js_1 = require("./commands/account.js");
+const subscribers_js_1 = require("./commands/subscribers.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");
+const sequences_js_1 = require("./commands/sequences.js");
+const program = new commander_1.Command();
+program
+    .name("kit-analytics")
+    .description("Pull Kit.com newsletter analytics via Kit API v4")
+    .version("0.0.1")
+    .option("--api-key <key>", "Kit API key (overrides KIT_API_KEY env var)")
+    .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"];
+    if (!apiKey) {
+        console.error("Error: Kit API key is required. Set KIT_API_KEY env var or pass --api-key.");
+        process.exit(1);
+    }
+    const client = new api_js_1.KitClient({ apiKey });
+    const format = opts.format;
+    // Bind the client to all subcommands via metadata
+    for (const cmd of program.commands) {
+        cmd.setOptionValue("__client", client);
+        cmd.setOptionValue("__format", format);
+    }
+});
+// 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, broadcasts_js_1.broadcastsCommand)());
+program.addCommand((0, tags_js_1.tagsCommand)());
+program.addCommand((0, forms_js_1.formsCommand)());
+program.addCommand((0, sequences_js_1.sequencesCommand)());
+program.parseAsync(process.argv).catch((err) => {
+    console.error(`Error: ${err.message}`);
+    process.exit(1);
+});

package/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "@radjay/kit-analytics",
+  "version": "0.0.1",
+  "description": "CLI tool to pull Kit.com newsletter analytics via Kit API v4",
+  "bin": {
+    "kit-analytics": "./dist/index.js"
+  },
+  "files": ["dist"],
+  "scripts": {
+    "build": "tsc",
+    "clean": "rm -rf dist"
+  },
+  "dependencies": {
+    "commander": "^13.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.13.4",
+    "typescript": "^5.7.3"
+  }
+}