@mcnekoneko/hookstream-cli 0.1.1 → 0.1.3

package/dist/api.d.ts

@@ -0,0 +1,52 @@
+import type { ChannelConfig, RelayEvent, SignatureAlgorithm } from "./types";
+export type CreateChannelInput = {
+    id: string;
+    token?: string;
+    eventHeader?: string;
+    maxHistory?: number;
+    signature?: {
+        header: string;
+        algorithm: SignatureAlgorithm;
+        secret: string;
+        prefix?: string;
+    };
+};
+export type TestResult = {
+    ok: boolean;
+    channelId: string;
+    webhookStatus: number;
+    eventReceived: boolean;
+    eventId?: string;
+    roundTripMs?: number;
+    error?: string;
+};
+export declare class HookstreamClient {
+    private readonly url;
+    private readonly adminKey;
+    constructor(url: string, adminKey: string);
+    private headers;
+    listChannels(): Promise<ChannelConfig[]>;
+    createChannel(input: CreateChannelInput): Promise<ChannelConfig>;
+    deleteChannel(id: string): Promise<{
+        deleted: string;
+    }>;
+    /**
+     * End-to-end test: subscribe to SSE, send a test webhook, verify delivery.
+     */
+    testChannel(channelId: string, opts?: {
+        token?: string;
+        timeoutMs?: number;
+    }): Promise<TestResult>;
+    /**
+     * Subscribe to a channel's SSE stream. Calls `onEvent` for each received
+     * event. Returns when the stream closes or `signal` is aborted.
+     */
+    subscribe(channelId: string, opts: {
+        token?: string;
+        lastEventId?: string;
+        onEvent: (event: RelayEvent) => void;
+        onKeepalive?: () => void;
+        onError?: (error: Error) => void;
+        signal?: AbortSignal;
+    }): Promise<void>;
+}

package/dist/api.js

@@ -0,0 +1,212 @@
+export class HookstreamClient {
+    url;
+    adminKey;
+    constructor(url, adminKey) {
+        this.url = url;
+        this.adminKey = adminKey;
+    }
+    headers() {
+        return {
+            Authorization: `Bearer ${this.adminKey}`,
+            "Content-Type": "application/json",
+        };
+    }
+    async listChannels() {
+        const res = await fetch(`${this.url}/admin/channels`, {
+            headers: this.headers(),
+        });
+        const data = (await res.json());
+        if (!res.ok)
+            throw new Error(data.error);
+        return data;
+    }
+    async createChannel(input) {
+        const res = await fetch(`${this.url}/admin/channels`, {
+            method: "POST",
+            headers: this.headers(),
+            body: JSON.stringify(input),
+        });
+        const data = (await res.json());
+        if (!res.ok)
+            throw new Error(data.error);
+        return data;
+    }
+    async deleteChannel(id) {
+        const res = await fetch(`${this.url}/admin/channels/${id}`, {
+            method: "DELETE",
+            headers: this.headers(),
+        });
+        const data = (await res.json());
+        if (!res.ok)
+            throw new Error(data.error);
+        return data;
+    }
+    /**
+     * End-to-end test: subscribe to SSE, send a test webhook, verify delivery.
+     */
+    async testChannel(channelId, opts = {}) {
+        const timeoutMs = opts.timeoutMs ?? 10_000;
+        const testPayload = {
+            _hookstream_test: true,
+            ts: Date.now(),
+            nonce: crypto.randomUUID(),
+        };
+        const sseUrl = `${this.url}/${channelId}/events`;
+        const webhookUrl = `${this.url}/${channelId}`;
+        // 1. Connect to SSE
+        const sseHeaders = {};
+        if (opts.token)
+            sseHeaders.Authorization = `Bearer ${opts.token}`;
+        const sseRes = await fetch(sseUrl, { headers: sseHeaders });
+        if (!sseRes.ok) {
+            return {
+                ok: false,
+                channelId,
+                webhookStatus: 0,
+                eventReceived: false,
+                error: `SSE connect failed: HTTP ${sseRes.status}`,
+            };
+        }
+        const reader = sseRes.body?.getReader();
+        if (!reader) {
+            return {
+                ok: false,
+                channelId,
+                webhookStatus: 0,
+                eventReceived: false,
+                error: "SSE response has no readable body",
+            };
+        }
+        const decoder = new TextDecoder();
+        const startMs = Date.now();
+        // 2. Send test webhook
+        const webhookRes = await fetch(webhookUrl, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify(testPayload),
+        });
+        if (!webhookRes.ok) {
+            reader.cancel().catch(() => { });
+            const body = await webhookRes.text().catch(() => "");
+            return {
+                ok: false,
+                channelId,
+                webhookStatus: webhookRes.status,
+                eventReceived: false,
+                error: `Webhook POST failed: HTTP ${webhookRes.status} ${body}`,
+            };
+        }
+        const webhookData = (await webhookRes.json());
+        // 3. Read SSE stream until we see our test event or timeout
+        let buffer = "";
+        const deadline = Date.now() + timeoutMs;
+        while (Date.now() < deadline) {
+            const remaining = deadline - Date.now();
+            const readPromise = reader.read();
+            const timeoutPromise = new Promise((resolve) => setTimeout(() => resolve({ done: true, value: undefined }), remaining));
+            const { done, value } = await Promise.race([readPromise, timeoutPromise]);
+            if (done && !value)
+                break;
+            if (value)
+                buffer += decoder.decode(value, { stream: true });
+            // Parse SSE frames from buffer
+            const frames = buffer.split("\n\n");
+            buffer = frames.pop() ?? "";
+            for (const frame of frames) {
+                const dataLine = frame.split("\n").find((l) => l.startsWith("data: "));
+                if (!dataLine)
+                    continue;
+                try {
+                    const event = JSON.parse(dataLine.slice(6));
+                    if (event.id === webhookData.id) {
+                        const roundTripMs = Date.now() - startMs;
+                        reader.cancel().catch(() => { });
+                        return {
+                            ok: true,
+                            channelId,
+                            webhookStatus: webhookRes.status,
+                            eventReceived: true,
+                            eventId: event.id,
+                            roundTripMs,
+                        };
+                    }
+                }
+                catch {
+                    // not our event, continue
+                }
+            }
+        }
+        reader.cancel().catch(() => { });
+        return {
+            ok: false,
+            channelId,
+            webhookStatus: webhookRes.status,
+            eventReceived: false,
+            error: `Timeout: event not received within ${timeoutMs}ms`,
+        };
+    }
+    /**
+     * Subscribe to a channel's SSE stream. Calls `onEvent` for each received
+     * event. Returns when the stream closes or `signal` is aborted.
+     */
+    async subscribe(channelId, opts) {
+        const sseUrl = `${this.url}/${channelId}/events`;
+        const headers = {};
+        if (opts.token)
+            headers.Authorization = `Bearer ${opts.token}`;
+        if (opts.lastEventId)
+            headers["Last-Event-ID"] = opts.lastEventId;
+        const res = await fetch(sseUrl, { headers, signal: opts.signal });
+        if (!res.ok) {
+            const body = await res.text().catch(() => "");
+            throw new Error(`SSE connect failed: HTTP ${res.status} ${body}`);
+        }
+        const reader = res.body?.getReader();
+        if (!reader)
+            throw new Error("SSE response has no readable body");
+        const decoder = new TextDecoder();
+        let buffer = "";
+        try {
+            while (true) {
+                if (opts.signal?.aborted)
+                    break;
+                const { done, value } = await reader.read();
+                if (done)
+                    break;
+                buffer += decoder.decode(value, { stream: true });
+                const frames = buffer.split("\n\n");
+                buffer = frames.pop() ?? "";
+                for (const frame of frames) {
+                    // Keepalive
+                    if (frame.trim() === ":keepalive") {
+                        opts.onKeepalive?.();
+                        continue;
+                    }
+                    const dataLine = frame
+                        .split("\n")
+                        .find((l) => l.startsWith("data: "));
+                    if (!dataLine)
+                        continue;
+                    try {
+                        const event = JSON.parse(dataLine.slice(6));
+                        opts.onEvent(event);
+                    }
+                    catch {
+                        // skip malformed frames
+                    }
+                }
+            }
+        }
+        catch (err) {
+            if (opts.signal?.aborted)
+                return;
+            if (opts.onError)
+                opts.onError(err);
+            else
+                throw err;
+        }
+        finally {
+            reader.cancel().catch(() => { });
+        }
+    }
+}

package/dist/config.d.ts

@@ -0,0 +1,9 @@
+export type Profile = {
+    url: string;
+    adminKey: string;
+};
+export type Config = Record<string, Profile>;
+export declare function loadConfig(): Config;
+export declare function saveConfig(config: Config): void;
+export declare function getProfile(name?: string): Profile | undefined;
+export declare function runConfigure(profileName?: string): Promise<void>;

package/dist/config.js

@@ -0,0 +1,45 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { createInterface } from "node:readline/promises";
+const CONFIG_DIR = join(homedir(), ".config", "hookstream-cli");
+const CONFIG_FILE = join(CONFIG_DIR, "config.json");
+export function loadConfig() {
+    if (!existsSync(CONFIG_FILE))
+        return {};
+    try {
+        return JSON.parse(readFileSync(CONFIG_FILE, "utf-8"));
+    }
+    catch {
+        return {};
+    }
+}
+export function saveConfig(config) {
+    if (!existsSync(CONFIG_DIR))
+        mkdirSync(CONFIG_DIR, { recursive: true });
+    writeFileSync(CONFIG_FILE, `${JSON.stringify(config, null, 2)}\n`, "utf-8");
+}
+export function getProfile(name = "default") {
+    return loadConfig()[name];
+}
+export async function runConfigure(profileName = "default") {
+    const config = loadConfig();
+    const existing = config[profileName];
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    console.log(profileName === "default"
+        ? "Configure hookstream CLI (default profile)"
+        : `Configure hookstream CLI (profile: ${profileName})`);
+    const url = await rl.question(`Worker URL${existing?.url ? ` [${existing.url}]` : ""}: `);
+    const adminKey = await rl.question(`Admin key${existing?.adminKey ? " [****]" : ""}: `);
+    rl.close();
+    config[profileName] = {
+        url: url.trim() || existing?.url || "",
+        adminKey: adminKey.trim() || existing?.adminKey || "",
+    };
+    if (!config[profileName].url || !config[profileName].adminKey) {
+        console.error("Error: URL and admin key are required.");
+        process.exit(1);
+    }
+    saveConfig(config);
+    console.log(`\nSaved profile '${profileName}' to ${CONFIG_FILE}`);
+}

package/dist/index.d.ts

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

package/dist/index.js

@@ -0,0 +1,225 @@
+#!/usr/bin/env node
+import { Command, InvalidArgumentError } from "commander";
+import { HookstreamClient } from "./api";
+import { getProfile, runConfigure } from "./config";
+const program = new Command();
+program
+    .name("hookstream")
+    .description("CLI for managing hookstream channels")
+    .option("-p, --profile <name>", "Config profile to use", "default")
+    .option("-u, --url <url>", "Worker URL (overrides profile)")
+    .option("-k, --admin-key <key>", "Admin key (overrides profile)");
+function getClient() {
+    const opts = program.opts();
+    // Priority: flag > env var > profile
+    const url = opts.url ?? process.env.HOOKSTREAM_URL ?? getProfile(opts.profile)?.url;
+    const adminKey = opts.adminKey ??
+        process.env.HOOKSTREAM_ADMIN_KEY ??
+        getProfile(opts.profile)?.adminKey;
+    if (!url) {
+        console.error(`Error: Worker URL is required.\n  Run: hookstream configure --profile ${opts.profile}`);
+        process.exit(1);
+    }
+    if (!adminKey) {
+        console.error(`Error: Admin key is required.\n  Run: hookstream configure --profile ${opts.profile}`);
+        process.exit(1);
+    }
+    return new HookstreamClient(url.replace(/\/$/, ""), adminKey);
+}
+// ─── configure ───────────────────────────────────────────────────────────────
+program
+    .command("configure")
+    .description("Save Worker URL and admin key to a config profile")
+    .action(async () => {
+    const profileName = program.opts().profile;
+    await runConfigure(profileName);
+});
+// ─── channels ────────────────────────────────────────────────────────────────
+const channels = program.command("channels").description("Manage channels");
+channels
+    .command("list")
+    .description("List all channels")
+    .action(async () => {
+    try {
+        const client = getClient();
+        const list = await client.listChannels();
+        if (list.length === 0) {
+            console.log("No channels found.");
+            return;
+        }
+        for (const ch of list) {
+            const sig = ch.signature
+                ? ` sig:${ch.signature.algorithm}(${ch.signature.header})`
+                : "";
+            const tok = ch.token ? " token:✓" : "";
+            const ev = ch.eventHeader ? ` event:${ch.eventHeader}` : "";
+            console.log(`  ${ch.id.padEnd(24)} maxHistory:${ch.maxHistory}${sig}${tok}${ev}  [${ch.createdAt}]`);
+        }
+    }
+    catch (err) {
+        console.error(`Error: ${err.message}`);
+        process.exit(1);
+    }
+});
+channels
+    .command("create")
+    .description("Create a channel")
+    .requiredOption("--id <id>", "Channel ID (a-z0-9_-, max 64)")
+    .option("--token <token>", "Bearer token for SSE access")
+    .option("--event-header <header>", "Header to read event type from")
+    .option("--max-history <n>", "Ring buffer size for reconnect replay", (v) => {
+    const n = parseInt(v, 10);
+    if (Number.isNaN(n) || n < 1)
+        throw new InvalidArgumentError("Must be a positive integer.");
+    return n;
+}, 50)
+    .option("--sig-header <header>", "Signature header name")
+    .option("--sig-algorithm <alg>", "Signature algorithm (hmac-sha256-hex|hmac-sha256-base64)")
+    .option("--sig-secret <secret>", "HMAC secret")
+    .option("--sig-prefix <prefix>", "Prefix to strip before comparing (e.g. sha256=)")
+    .action(async (opts) => {
+    try {
+        const client = getClient();
+        // Build signature config if provided
+        let signature;
+        if (opts.sigHeader || opts.sigAlgorithm || opts.sigSecret) {
+            if (!opts.sigHeader || !opts.sigAlgorithm || !opts.sigSecret) {
+                console.error("Error: --sig-header, --sig-algorithm, and --sig-secret are all required when configuring signature verification.");
+                process.exit(1);
+            }
+            if (opts.sigAlgorithm !== "hmac-sha256-hex" &&
+                opts.sigAlgorithm !== "hmac-sha256-base64") {
+                console.error("Error: --sig-algorithm must be 'hmac-sha256-hex' or 'hmac-sha256-base64'.");
+                process.exit(1);
+            }
+            signature = {
+                header: opts.sigHeader,
+                algorithm: opts.sigAlgorithm,
+                secret: opts.sigSecret,
+                prefix: opts.sigPrefix,
+            };
+        }
+        const ch = await client.createChannel({
+            id: opts.id,
+            token: opts.token,
+            eventHeader: opts.eventHeader,
+            maxHistory: opts.maxHistory,
+            signature,
+        });
+        console.log(`Channel created: ${ch.id}`);
+        console.log(JSON.stringify(ch, null, 2));
+    }
+    catch (err) {
+        console.error(`Error: ${err.message}`);
+        process.exit(1);
+    }
+});
+channels
+    .command("delete <id>")
+    .description("Delete a channel")
+    .action(async (id) => {
+    try {
+        const client = getClient();
+        const result = await client.deleteChannel(id);
+        console.log(`Deleted: ${result.deleted}`);
+    }
+    catch (err) {
+        console.error(`Error: ${err.message}`);
+        process.exit(1);
+    }
+});
+channels
+    .command("subscribe <id>")
+    .description("Subscribe to a channel's SSE stream and print events in real-time")
+    .option("--token <token>", "Bearer token for SSE (if channel requires auth)")
+    .option("--last-event-id <id>", "Resume from a specific event ID")
+    .option("--json", "Output raw JSON per event (one line per event)")
+    .action(async (id, opts) => {
+    const client = getClient();
+    const baseUrl = program.opts().url ?? getProfile(program.opts().profile)?.url ?? "";
+    if (!opts.json) {
+        console.log(`Subscribing to: ${baseUrl}/${id}/events`);
+        if (opts.lastEventId)
+            console.log(`  Last-Event-ID: ${opts.lastEventId}`);
+        console.log("  Press Ctrl+C to stop\n");
+    }
+    const ac = new AbortController();
+    process.on("SIGINT", () => ac.abort());
+    process.on("SIGTERM", () => ac.abort());
+    try {
+        await client.subscribe(id, {
+            token: opts.token,
+            lastEventId: opts.lastEventId,
+            signal: ac.signal,
+            onEvent: (event) => {
+                if (opts.json) {
+                    console.log(JSON.stringify(event));
+                }
+                else {
+                    const time = new Date(event.timestamp).toLocaleTimeString();
+                    console.log(`[${time}] event=${event.event} id=${event.id}`);
+                    console.log(`  ${JSON.stringify(event.payload, null, 2).split("\n").join("\n  ")}`);
+                    console.log();
+                }
+            },
+            onKeepalive: () => {
+                if (!opts.json) {
+                    process.stdout.write(".");
+                }
+            },
+        });
+        if (!opts.json)
+            console.log("\nStream closed.");
+    }
+    catch (err) {
+        if (ac.signal.aborted) {
+            if (!opts.json)
+                console.log("\nDisconnected.");
+        }
+        else {
+            console.error(`Error: ${err.message}`);
+            process.exit(1);
+        }
+    }
+});
+channels
+    .command("test <id>")
+    .description("End-to-end test: subscribe SSE → send test webhook → verify delivery")
+    .option("--token <token>", "Bearer token for SSE (if channel requires auth)")
+    .option("--timeout <ms>", "Timeout in milliseconds", (v) => {
+    const n = parseInt(v, 10);
+    if (Number.isNaN(n) || n < 1)
+        throw new InvalidArgumentError("Must be a positive integer.");
+    return n;
+}, 10_000)
+    .action(async (id, opts) => {
+    try {
+        const client = getClient();
+        console.log(`Testing channel: ${id}`);
+        console.log(`  SSE:     ${program.opts().url ?? getProfile(program.opts().profile)?.url}/${id}/events`);
+        console.log(`  Webhook: ${program.opts().url ?? getProfile(program.opts().profile)?.url}/${id}`);
+        console.log();
+        const result = await client.testChannel(id, {
+            token: opts.token,
+            timeoutMs: opts.timeout,
+        });
+        if (result.ok) {
+            console.log(`✅ PASS`);
+            console.log(`  Webhook POST:  HTTP ${result.webhookStatus}`);
+            console.log(`  SSE received:  ${result.eventId}`);
+            console.log(`  Round-trip:    ${result.roundTripMs}ms`);
+        }
+        else {
+            console.log(`❌ FAIL`);
+            if (result.webhookStatus)
+                console.log(`  Webhook POST:  HTTP ${result.webhookStatus}`);
+            console.log(`  Error:         ${result.error}`);
+            process.exit(1);
+        }
+    }
+    catch (err) {
+        console.error(`Error: ${err.message}`);
+        process.exit(1);
+    }
+});
+program.parse();

package/dist/types.d.ts

@@ -0,0 +1,23 @@
+export type SignatureAlgorithm = "hmac-sha256-hex" | "hmac-sha256-base64";
+export type SignatureConfig = {
+    header: string;
+    algorithm: SignatureAlgorithm;
+    prefix?: string;
+    secret: string;
+};
+export type ChannelConfig = {
+    id: string;
+    signature?: Omit<SignatureConfig, "secret">;
+    token?: string;
+    eventHeader?: string;
+    maxHistory: number;
+    createdAt: string;
+};
+export type RelayEvent = {
+    id: string;
+    channel: string;
+    event: string;
+    timestamp: string;
+    source?: string;
+    payload: unknown;
+};

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mcnekoneko/hookstream-cli",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "CLI for managing hookstream channels",
   "type": "module",
   "bin": {