@eventpipe/cli 0.2.1

package/README.md

@@ -0,0 +1,79 @@
+# @eventpipe/cli
+
+Build **Event Pipe** code-node bundles with [esbuild](https://esbuild.github.io/), publish with an **API key**, and use **login / create / listen** against the dashboard (Supabase session + relay WebSocket).
+
+## Install
+
+```bash
+pnpm add -D @eventpipe/cli
+# or: npm i -D @eventpipe/cli
+```
+
+Global install (provides `eventpipe` and `eventpipe-cli`):
+
+```bash
+npm install -g @eventpipe/cli
+```
+
+**macOS / Linux** — from a clone of this repo, installs globally (requires Node 20+ and `npm` on `PATH`):
+
+```bash
+bash install/macos.sh
+```
+
+**Windows** — PowerShell:
+
+```powershell
+Set-ExecutionPolicy -Scope Process Bypass; .\install\windows.ps1
+```
+
+From a git checkout:
+
+```bash
+cd eventpipe-cli && pnpm install && pnpm run build
+# binaries: ./dist/cli.js
+```
+
+## Project layout
+
+| File | Purpose |
+|------|---------|
+| `eventpipe.json` | `pipelineId`, optional `nodeId` / `entry`, and `settings` (must include `pipe` v3) |
+| `src/handler.ts` | Default entry — `export async function handler(event, context)` |
+
+Runtime uses **`context.env`** for secrets (configure values in the app **Event** tab), not `process.env`.
+
+## Commands
+
+### Auth & endpoints
+
+- **`login`** — Opens the browser to complete Supabase login; saves `~/.eventpipe/credentials.json`. Uses `https://eventpipe.app` unless `EVENTPIPE_BASE_URL` is set.
+- **`create [--name <slug>]`** — `POST /api/account/endpoints` (session auth). `--name` sets the URL slug (`/api/webhook/your-slug`) if it’s free; otherwise a random id is used. With no `--name`, the URL and display label are random.
+- **`listen <webhookId> [options]`** — Connects to the relay; prints one line per webhook. **`--verbose` / `-v`** prints the full event JSON (method, headers, query, body). **`--json`** prints one JSON object per line (stdout) for scripts. **`--forward-to http://127.0.0.1:PORT/path`** replays each request to your local server (forward status on stderr).
+
+### Bundles
+
+- **`build`** — Writes `.eventpipe/*.bundle.js` and prints size + sha256 (must be ≤ 200KB).
+- **`push`** — Runs `build`, then `POST /api/account/pipelines/:pipelineId/versions` with `codeBundles`.
+
+### Environment
+
+| Variable | Used by | Description |
+|----------|---------|-------------|
+| `EVENTPIPE_BASE_URL` | login, push | Origin of the Next app (default `https://eventpipe.app`; no trailing slash) |
+| `EVENTPIPE_API_KEY` | push | Plaintext key from account API keys (`evp_...`) |
+
+Optional: `--pipeline <uuid>` (or `--flow`) overrides `pipelineId` in `eventpipe.json` for `push`.
+
+### Server requirements for `listen`
+
+The app needs a deployed **eventpipe-relay** (or compatible) service plus env vars documented in the app `.env.example`: `EVENTPIPE_RELAY_URL`, `EVENTPIPE_RELAY_WS_URL`, `EVENTPIPE_RELAY_INGEST_SECRET`, `EVENTPIPE_LISTEN_JWT_SECRET` (shared with the relay).
+
+## Example
+
+See `examples/stripe-webhook` (Stripe Balance via REST to stay under the bundle size cap).
+
+## Limits
+
+- One **code node** per project in this CLI version (multi-node flows: publish from the dashboard or extend the CLI).
+- Per-node bundle max **200KB** UTF-8 (same as the server).

package/dist/auth-fetch.d.ts

@@ -0,0 +1,5 @@
+import { type StoredCredentials } from "./credentials.js";
+export declare function fetchWithSession(url: string, init: RequestInit, cred: StoredCredentials): Promise<{
+    response: Response;
+    credentials: StoredCredentials;
+}>;

package/dist/auth-fetch.js

@@ -0,0 +1,29 @@
+import { saveCredentials } from "./credentials.js";
+export async function fetchWithSession(url, init, cred) {
+    let c = cred;
+    const headers = new Headers(init.headers);
+    headers.set("authorization", `Bearer ${c.accessToken}`);
+    let res = await fetch(url, { ...init, headers });
+    if (res.status === 401 && c.refreshToken) {
+        const r = await fetch(`${c.baseUrl}/api/cli/refresh`, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify({ refresh_token: c.refreshToken }),
+        });
+        if (r.ok) {
+            const t = (await r.json());
+            if (t.access_token && t.refresh_token) {
+                c = {
+                    ...c,
+                    accessToken: t.access_token,
+                    refreshToken: t.refresh_token,
+                };
+                await saveCredentials(c);
+                const h2 = new Headers(init.headers);
+                h2.set("authorization", `Bearer ${c.accessToken}`);
+                res = await fetch(url, { ...init, headers: h2 });
+            }
+        }
+    }
+    return { response: res, credentials: c };
+}

package/dist/base-url.d.ts

@@ -0,0 +1,2 @@
+export declare const DEFAULT_EVENTPIPE_BASE_URL = "https://eventpipe.app";
+export declare function resolveEventpipeBaseUrl(): string;

package/dist/base-url.js

@@ -0,0 +1,8 @@
+export const DEFAULT_EVENTPIPE_BASE_URL = "https://eventpipe.app";
+export function resolveEventpipeBaseUrl() {
+    const fromEnv = process.env.EVENTPIPE_BASE_URL?.replace(/\/$/, "").trim();
+    if (fromEnv) {
+        return fromEnv;
+    }
+    return DEFAULT_EVENTPIPE_BASE_URL;
+}

package/dist/build-bundle.d.ts

@@ -0,0 +1,12 @@
+export type BuildResult = {
+    bundleCode: string;
+    bundleHash: string;
+    bundleSizeBytes: number;
+    outFile: string;
+};
+export declare function buildBundle(params: {
+    projectDir: string;
+    entryRelative: string;
+    nodeId: string;
+    pipe: unknown;
+}): Promise<BuildResult>;

package/dist/build-bundle.js

@@ -0,0 +1,48 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, relative, resolve } from "node:path";
+import * as esbuild from "esbuild";
+import { collectCodeNodeIds } from "./code-node-ids.js";
+import { BUNDLE_MAX_BYTES, GLOBAL_NAME } from "./constants.js";
+import { byteLenUtf8, sha256Utf8 } from "./hash.js";
+export async function buildBundle(params) {
+    const codeIds = collectCodeNodeIds(params.pipe);
+    if (codeIds.length === 0) {
+        throw new Error("settings.pipe must contain at least one code node");
+    }
+    if (!codeIds.includes(params.nodeId)) {
+        throw new Error(`nodeId "${params.nodeId}" is not a code node id in settings.pipe`);
+    }
+    const userEntry = resolve(params.projectDir, params.entryRelative);
+    const epDir = resolve(params.projectDir, ".eventpipe");
+    await mkdir(epDir, { recursive: true });
+    const shimPath = resolve(epDir, `${params.nodeId}.reexport.ts`);
+    const relToShim = relative(dirname(shimPath), userEntry).replace(/\\/g, "/");
+    const shim = `export { handler } from "${relToShim}";\n`;
+    await writeFile(shimPath, shim, "utf8");
+    const outFile = resolve(epDir, `${params.nodeId}.bundle.js`);
+    await esbuild.build({
+        absWorkingDir: params.projectDir,
+        entryPoints: [shimPath],
+        bundle: true,
+        platform: "node",
+        format: "iife",
+        globalName: GLOBAL_NAME,
+        outfile: outFile,
+        minify: true,
+        target: "es2022",
+        logLevel: "warning",
+    });
+    const raw = await readFile(outFile, "utf8");
+    const footer = `\n;var handler = ${GLOBAL_NAME}.handler;\n`;
+    const bundleCode = (raw + footer).trim();
+    await writeFile(outFile, bundleCode, "utf8");
+    if (!bundleCode.includes("handler")) {
+        throw new Error("Bundle validation failed: output must reference handler");
+    }
+    const bundleSizeBytes = byteLenUtf8(bundleCode);
+    if (bundleSizeBytes > BUNDLE_MAX_BYTES) {
+        throw new Error(`Bundle is ${bundleSizeBytes} bytes (max ${BUNDLE_MAX_BYTES}). Use smaller dependencies or fetch-based APIs.`);
+    }
+    const bundleHash = sha256Utf8(bundleCode);
+    return { bundleCode, bundleHash, bundleSizeBytes, outFile };
+}

package/dist/cli-version.d.ts

@@ -0,0 +1,3 @@
+export declare function readInstalledCliVersion(): Promise<string>;
+export declare function fetchLatestPublishedVersion(): Promise<string | null>;
+export declare function isPublishedVersionNewer(installed: string, published: string): boolean;

package/dist/cli-version.js

@@ -0,0 +1,48 @@
+import { readFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+const NPM_LATEST_URL = "https://registry.npmjs.org/@eventpipe%2fcli/latest";
+export async function readInstalledCliVersion() {
+    const dir = dirname(fileURLToPath(import.meta.url));
+    const pkgPath = join(dir, "..", "package.json");
+    const raw = await readFile(pkgPath, "utf8");
+    const pkg = JSON.parse(raw);
+    return typeof pkg.version === "string" ? pkg.version : "0.0.0";
+}
+export async function fetchLatestPublishedVersion() {
+    try {
+        const ac = new AbortController();
+        const t = setTimeout(() => ac.abort(), 5_000);
+        const res = await fetch(NPM_LATEST_URL, {
+            signal: ac.signal,
+            headers: { accept: "application/json" },
+        });
+        clearTimeout(t);
+        if (!res.ok) {
+            return null;
+        }
+        const data = (await res.json());
+        return typeof data.version === "string" ? data.version : null;
+    }
+    catch {
+        return null;
+    }
+}
+function compareSemverLike(a, b) {
+    const coreA = a.replace(/^v/, "").split(/[-+]/)[0] ?? "0";
+    const coreB = b.replace(/^v/, "").split(/[-+]/)[0] ?? "0";
+    const partsA = coreA.split(".").map((x) => Number.parseInt(x, 10) || 0);
+    const partsB = coreB.split(".").map((x) => Number.parseInt(x, 10) || 0);
+    const n = Math.max(partsA.length, partsB.length);
+    for (let i = 0; i < n; i++) {
+        const da = partsA[i] ?? 0;
+        const db = partsB[i] ?? 0;
+        if (da !== db) {
+            return da - db;
+        }
+    }
+    return 0;
+}
+export function isPublishedVersionNewer(installed, published) {
+    return compareSemverLike(published, installed) > 0;
+}

package/dist/cli.d.ts

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

package/dist/cli.js

@@ -0,0 +1,221 @@
+#!/usr/bin/env node
+import { readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { buildBundle } from "./build-bundle.js";
+import { collectCodeNodeIds } from "./code-node-ids.js";
+import { loadManifest } from "./config.js";
+import { publishVersion } from "./publish.js";
+import { applyPublishedStudioSources, codeNodeUsesLibrary } from "./studio-sources.js";
+import { cmdLogin } from "./cmd-login.js";
+import { cmdCreate } from "./cmd-create.js";
+import { resolveEventpipeBaseUrl } from "./base-url.js";
+import { fetchLatestPublishedVersion, isPublishedVersionNewer, readInstalledCliVersion, } from "./cli-version.js";
+import { cmdUpdate } from "./cmd-update.js";
+import { cmdListen } from "./cmd-listen.js";
+import { parseListenArgv } from "./listen-args.js";
+function usage() {
+    console.log(`eventpipe — Event Pipe CLI
+
+Environment:
+  EVENTPIPE_BASE_URL   App origin (default: https://eventpipe.app); override for self-hosted
+  EVENTPIPE_API_KEY    Account API key (x-api-key) for push when not using session
+  EVENTPIPE_SKIP_UPDATE_CHECK   Set to 1 to disable the npm version hint on stderr
+
+Commands:
+  login                  Browser login (stores ~/.eventpipe/credentials.json)
+  create [--name <s>]    Create a webhook endpoint (requires login)
+  listen <webhookId> [--verbose|-v] [--json] [--forward-to <url>]
+                         Stream webhooks; --verbose prints full JSON event; --json one NDJSON line per event;
+                         --forward-to replays the request to your local server (status on stderr)
+  build [--dir <path>]   Bundle TS into .eventpipe/
+  push [--dir <path>]    build + POST /api/account/pipelines/:id/versions (needs EVENTPIPE_API_KEY)
+  update                 npm install -g @eventpipe/cli@latest
+  help
+
+eventpipe.json must define pipelineId and settings.pipe (v3) for build/push.
+`);
+}
+async function maybeSuggestUpdate() {
+    try {
+        if (process.env.EVENTPIPE_SKIP_UPDATE_CHECK === "1") {
+            return;
+        }
+        const v = await readInstalledCliVersion();
+        const latest = await fetchLatestPublishedVersion();
+        if (!latest || !isPublishedVersionNewer(v, latest)) {
+            return;
+        }
+        console.error(`\nA newer @eventpipe/cli is available (latest: ${latest}). Run: eventpipe update\n`);
+    }
+    catch {
+        /* ignore */
+    }
+}
+function parseDir(argv) {
+    let dir = process.cwd();
+    for (let i = 0; i < argv.length; i++) {
+        if (argv[i] === "--dir" && argv[i + 1]) {
+            dir = resolve(argv[++i]);
+        }
+    }
+    return dir;
+}
+function parsePipelineOverride(argv) {
+    for (let i = 0; i < argv.length; i++) {
+        if ((argv[i] === "--pipeline" || argv[i] === "--flow") && argv[i + 1]) {
+            return argv[++i].trim();
+        }
+    }
+    return undefined;
+}
+function resolveTargets(manifest, ids) {
+    if (manifest.codeNodes) {
+        return manifest.codeNodes;
+    }
+    const entry = manifest.entry && manifest.entry.length > 0 ? manifest.entry : "src/handler.ts";
+    const nodeId = manifest.nodeId?.trim();
+    if (nodeId) {
+        return { [entry]: nodeId };
+    }
+    if (ids.length === 0) {
+        throw new Error("No code node ids found in settings.pipe");
+    }
+    if (ids.length === 1) {
+        return { [entry]: ids[0] };
+    }
+    throw new Error("Multiple code nodes detected in your flow. You must specify a 'codeNodes' map in eventpipe.json (e.g. { \"src/node.ts\": \"uuid\" }).");
+}
+async function cmdBuild(projectDir) {
+    const manifest = await loadManifest(projectDir);
+    const pipe = manifest.settings.pipe;
+    const ids = collectCodeNodeIds(pipe);
+    const targets = resolveTargets(manifest, ids);
+    for (const [entryRelative, nodeId] of Object.entries(targets)) {
+        const r = await buildBundle({
+            projectDir,
+            entryRelative,
+            nodeId,
+            pipe,
+        });
+        console.log(`OK bundle (${entryRelative} -> ${nodeId}) ${r.bundleSizeBytes} bytes sha256:${r.bundleHash.slice(0, 12)}…`);
+        console.log(`Written ${r.outFile}`);
+    }
+}
+async function cmdPush(projectDir, pipelineOverride) {
+    const base = resolveEventpipeBaseUrl();
+    const key = process.env.EVENTPIPE_API_KEY?.trim();
+    if (!key) {
+        throw new Error("EVENTPIPE_API_KEY is required for push");
+    }
+    const manifest = await loadManifest(projectDir);
+    const pipelineId = pipelineOverride ?? manifest.pipelineId;
+    const pipe = manifest.settings.pipe;
+    const ids = collectCodeNodeIds(pipe);
+    const targets = resolveTargets(manifest, ids);
+    const bundles = [];
+    const sourcesByNodeId = {};
+    let totalSize = 0;
+    for (const [entryRelative, nodeId] of Object.entries(targets)) {
+        const sourcePath = resolve(projectDir, entryRelative);
+        sourcesByNodeId[nodeId] = await readFile(sourcePath, "utf8");
+        const built = await buildBundle({
+            projectDir,
+            entryRelative,
+            nodeId,
+            pipe,
+        });
+        bundles.push({
+            nodeId,
+            bundleCode: built.bundleCode,
+            bundleHash: built.bundleHash,
+        });
+        totalSize += built.bundleSizeBytes;
+    }
+    const flowSourceCode = ids.length === 1 && ids[0] ? sourcesByNodeId[ids[0]] ?? "" : "";
+    const mergedPipe = applyPublishedStudioSources(pipe, {
+        sourcesByNodeId,
+        flowSourceCode,
+    });
+    const manifestForPublish = {
+        ...manifest,
+        settings: { ...manifest.settings, pipe: mergedPipe },
+    };
+    const sourceCode = ids.length > 0 && ids[0] && !codeNodeUsesLibrary(mergedPipe, ids[0])
+        ? sourcesByNodeId[ids[0]] ?? null
+        : null;
+    const result = await publishVersion({
+        baseUrl: base,
+        apiKey: key,
+        pipelineId,
+        manifest: manifestForPublish,
+        bundles,
+        sourceCode,
+    });
+    if (result.error) {
+        throw new Error(result.error);
+    }
+    console.log(`Published pipeline ${pipelineId} version ${result.version} (${result.bundleSizeBytes ?? totalSize} bytes in ${bundles.length} bundles)`);
+}
+async function main() {
+    const argv = process.argv.slice(2);
+    const cmd = argv[0];
+    if (!cmd || cmd === "-h" || cmd === "--help" || cmd === "help") {
+        usage();
+        process.exit(cmd && cmd !== "help" ? 0 : 1);
+    }
+    if (cmd === "-v" || cmd === "--version") {
+        const v = await readInstalledCliVersion();
+        console.log(v);
+        return;
+    }
+    if (cmd === "login") {
+        await cmdLogin();
+        void maybeSuggestUpdate();
+        return;
+    }
+    if (cmd === "create") {
+        await cmdCreate(argv.slice(1));
+        void maybeSuggestUpdate();
+        return;
+    }
+    if (cmd === "update") {
+        await cmdUpdate();
+        return;
+    }
+    if (cmd === "listen") {
+        let parsed;
+        try {
+            parsed = parseListenArgv(argv.slice(1));
+        }
+        catch (e) {
+            console.error(e instanceof Error ? e.message : e);
+            console.error("Usage: eventpipe listen <webhookId> [--verbose|-v] [--json] [--forward-to <url>]");
+            process.exit(1);
+        }
+        if (!parsed.webhookId) {
+            console.error("Usage: eventpipe listen <webhookId> [--verbose|-v] [--json] [--forward-to <url>]");
+            process.exit(1);
+        }
+        void maybeSuggestUpdate();
+        await cmdListen(parsed.webhookId, parsed.options);
+        return;
+    }
+    const projectDir = parseDir(argv);
+    const pipelineOverride = parsePipelineOverride(argv);
+    if (cmd === "build") {
+        await cmdBuild(projectDir);
+        void maybeSuggestUpdate();
+        return;
+    }
+    if (cmd === "push") {
+        await cmdPush(projectDir, pipelineOverride);
+        void maybeSuggestUpdate();
+        return;
+    }
+    usage();
+    process.exit(1);
+}
+main().catch((e) => {
+    console.error(e instanceof Error ? e.message : e);
+    process.exit(1);
+});

package/dist/cmd-create.d.ts

@@ -0,0 +1 @@
+export declare function cmdCreate(argv: string[]): Promise<void>;

package/dist/cmd-create.js

@@ -0,0 +1,34 @@
+import { loadCredentials } from "./credentials.js";
+import { fetchWithSession } from "./auth-fetch.js";
+function parseName(argv) {
+    for (let i = 0; i < argv.length; i++) {
+        if (argv[i] === "--name" && argv[i + 1]) {
+            return argv[++i].trim();
+        }
+    }
+    return "";
+}
+export async function cmdCreate(argv) {
+    const cred = await loadCredentials();
+    if (!cred) {
+        throw new Error("Run eventpipe login first (or set credentials via eventpipe login)");
+    }
+    const name = parseName(argv);
+    const { response } = await fetchWithSession(`${cred.baseUrl}/api/account/endpoints`, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ name: name || undefined }),
+    }, cred);
+    const data = (await response.json());
+    if (!response.ok) {
+        throw new Error(data.error ?? response.statusText);
+    }
+    if (!data.webhookId || !data.webhookUrl) {
+        throw new Error("Unexpected response from API");
+    }
+    if (data.slugUnavailable && data.requestedSlug) {
+        console.log(`⚠ Slug "${data.requestedSlug}" is already taken; created with a random id instead.`);
+    }
+    const labelNote = data.label ? ` (${data.label})` : "";
+    console.log(`✓ Endpoint created: ${data.webhookUrl}${labelNote}`);
+}

package/dist/cmd-listen.d.ts

@@ -0,0 +1,2 @@
+import type { ListenOptions } from "./listen-args.js";
+export declare function cmdListen(webhookId: string, options: ListenOptions): Promise<void>;

package/dist/cmd-listen.js

@@ -0,0 +1,90 @@
+import WebSocket from "ws";
+import { forwardWebhookToLocal } from "./forward-local.js";
+import { loadCredentials } from "./credentials.js";
+import { fetchWithSession } from "./auth-fetch.js";
+function formatKb(bytes) {
+    return (bytes / 1024).toFixed(1);
+}
+export async function cmdListen(webhookId, options) {
+    const wid = webhookId.trim();
+    if (!wid) {
+        throw new Error("webhook id is required");
+    }
+    const cred = await loadCredentials();
+    if (!cred) {
+        throw new Error("Run eventpipe login first");
+    }
+    const { response } = await fetchWithSession(`${cred.baseUrl}/api/cli/listen-token`, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ webhookId: wid }),
+    }, cred);
+    const data = (await response.json());
+    if (!response.ok) {
+        throw new Error(data.error ?? response.statusText);
+    }
+    if (!data.token || !data.relayWsUrl) {
+        throw new Error(data.error ?? "listen-token misconfigured on server (EVENTPIPE_RELAY_WS_URL / EVENTPIPE_LISTEN_JWT_SECRET)");
+    }
+    const wsUrl = data.relayWsUrl;
+    console.log(`🔌 Conectado a ${wid}`);
+    if (options.forwardTo) {
+        console.error(`↪ forwarding to ${options.forwardTo}`);
+    }
+    const ws = new WebSocket(wsUrl);
+    await new Promise((resolve, reject) => {
+        const shutdown = () => {
+            try {
+                ws.close();
+            }
+            catch {
+                /* ignore */
+            }
+            resolve();
+        };
+        process.once("SIGINT", shutdown);
+        process.once("SIGTERM", shutdown);
+        ws.on("open", () => {
+            ws.send(JSON.stringify({ type: "auth", token: data.token }));
+        });
+        ws.on("message", (buf) => {
+            void (async () => {
+                try {
+                    const msg = JSON.parse(buf.toString());
+                    if (msg.type === "ready") {
+                        return;
+                    }
+                    if (msg.type !== "webhook") {
+                        return;
+                    }
+                    const summary = msg.summary ?? "webhook";
+                    const bytes = typeof msg.bytes === "number" ? msg.bytes : 0;
+                    const event = (msg.event ?? {});
+                    if (options.json) {
+                        console.log(JSON.stringify({ summary, bytes, event }));
+                    }
+                    else {
+                        console.log(`📩 ${summary} (${formatKb(bytes)}KB)`);
+                        if (options.verbose) {
+                            console.log(JSON.stringify(event, null, 2));
+                        }
+                    }
+                    if (options.forwardTo) {
+                        const r = await forwardWebhookToLocal(options.forwardTo, event);
+                        if (r.error) {
+                            console.error(`↪ forward failed: ${r.error}`);
+                        }
+                        else {
+                            console.error(`↪ forwarded (${r.status})`);
+                        }
+                    }
+                }
+                catch {
+                    /* ignore */
+                }
+            })();
+        });
+        ws.on("close", () => resolve());
+        ws.on("error", (e) => reject(e));
+    });
+}

package/dist/cmd-login.d.ts

@@ -0,0 +1 @@
+export declare function cmdLogin(): Promise<void>;