@eventpipe/cli 0.2.2 → 0.2.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (5) hide show
  1. package/README.md +81 -151
  2. package/dist/cli.js +15 -6
  3. package/dist/publish.d.ts +9 -1
  4. package/dist/publish.js +28 -14
  5. package/package.json +2 -2
package/README.md CHANGED
@@ -1,10 +1,8 @@
1
1
  # Event Pipe CLI
2
2
 
3
- Official command-line tool for **[Event Pipe](https://eventpipe.app)** — build code-node bundles, publish new versions of your flows, and manage webhooks from the terminal.
3
+ Official command-line tool for **[Event Pipe](https://eventpipe.app)** — bundle code nodes with [esbuild](https://esbuild.github.io/), **publish new pipeline versions**, create webhook endpoints, and stream events to your machine.
4
4
 
5
- **Website:** [eventpipe.app](https://eventpipe.app)
6
-
7
- Use this CLI when you want to work locally with TypeScript, automate publishes with an API key, stream incoming webhooks to your machine, or forward them to a dev server.
5
+ **Website:** [eventpipe.app](https://eventpipe.app) · **npm:** [`@eventpipe/cli`](https://www.npmjs.com/package/@eventpipe/cli)
8
6
 
9
7
  ---
10
8
 
@@ -12,17 +10,18 @@ Use this CLI when you want to work locally with TypeScript, automate publishes w
12
10
 
13
11
  | Area | What the CLI does |
14
12
  |------|-------------------|
15
- | **Account** | Sign in with your browser (`login`) — same account as on the web app. |
16
- | **Webhooks** | Create new webhook endpoints (`create`) and stream events in real time (`listen`). |
17
- | **Code & deploy** | Bundle your handler with esbuild (`build`) and upload a new pipeline version (`push`). |
18
- | **Tooling** | Check the installed version, update from npm, and opt out of update hints in CI. |
13
+ | **Publish** | Run **`eventpipe push`** after **`eventpipe login`** to upload a new pipeline version (same API as Pipe Studio). |
14
+ | **CI** | Set **`EVENTPIPE_API_KEY`** so **`push`** works without a browser. |
15
+ | **Webhooks** | **`create`** endpoints and **`listen`** to the relay (with optional **`--forward-to`** for local replay). |
16
+ | **Tooling** | **`eventpipe update`**, **`--version`**, and optional npm version hints on stderr. |
19
17
 
20
18
  ---
21
19
 
22
20
  ## Requirements
23
21
 
24
22
  - **Node.js 20 or newer** ([nodejs.org](https://nodejs.org))
25
- - An Event Pipe account (sign up at [eventpipe.app](https://eventpipe.app))
23
+ - An Event Pipe account ([sign up](https://eventpipe.app))
24
+ - For **`push`**: a **pipeline** already created in the app, and its **`pipelineId`** (UUID) in **`eventpipe.json`**
26
25
 
27
26
  ---
28
27
 
@@ -30,36 +29,24 @@ Use this CLI when you want to work locally with TypeScript, automate publishes w
30
29
 
31
30
  ### Global (recommended)
32
31
 
33
- Installs the `eventpipe` and `eventpipe-cli` commands on your PATH:
34
-
35
32
  ```bash
36
33
  npm install -g @eventpipe/cli
37
34
  ```
38
35
 
39
- ### Per project (dev dependency)
36
+ This provides **`eventpipe`** and **`eventpipe-cli`** on your `PATH`.
37
+
38
+ ### Per project
40
39
 
41
40
  ```bash
42
41
  npm add -D @eventpipe/cli
43
- # or: pnpm add -D @eventpipe/cli
44
42
  ```
45
43
 
46
- Run with `npx eventpipe …` or add an npm script.
44
+ Run with **`npx eventpipe …`** or npm scripts.
47
45
 
48
46
  ### Install scripts (from a clone of this repo)
49
47
 
50
- If you cloned the repository, you can use the helper scripts (they check Node 20+ and run a global install):
51
-
52
- **macOS / Linux**
53
-
54
- ```bash
55
- bash install/macos.sh
56
- ```
57
-
58
- **Windows (PowerShell)**
59
-
60
- ```powershell
61
- Set-ExecutionPolicy -Scope Process Bypass; .\install\windows.ps1
62
- ```
48
+ **macOS / Linux:** `bash install/macos.sh`
49
+ **Windows (PowerShell):** `Set-ExecutionPolicy -Scope Process Bypass; .\install\windows.ps1`
63
50
 
64
51
  ### Develop from source
65
52
 
@@ -71,179 +58,122 @@ node dist/cli.js --help
71
58
 
72
59
  ---
73
60
 
74
- ## Quick start
75
-
76
- 1. **Sign in** (opens the browser; credentials are saved under your home directory):
77
-
78
- ```bash
79
- eventpipe login
80
- ```
81
-
82
- By default this uses **[https://eventpipe.app](https://eventpipe.app)**. Set `EVENTPIPE_BASE_URL` only if you use a self-hosted app.
83
-
84
- 2. **Create a webhook endpoint** (optional slug for a readable URL):
61
+ ## Publishing pipeline versions (`build` + `push`)
85
62
 
86
- ```bash
87
- eventpipe create --name my-endpoint
88
- ```
63
+ Publishing creates a **new immutable version** of your pipeline by calling **`POST /api/account/pipelines/{pipelineId}/versions`** with bundled code — the same endpoint the [web app](https://eventpipe.app) uses.
89
64
 
90
- Note the **webhook id** from the output or from the [dashboard](https://eventpipe.app).
65
+ ### 1. Get `pipelineId`
91
66
 
92
- 3. **Listen for events** (replace with your webhook id):
67
+ In **Pipe Studio**, open your pipeline and copy its **UUID** from the URL or settings.
93
68
 
94
- ```bash
95
- eventpipe listen <webhookId>
96
- ```
69
+ ### 2. Add `eventpipe.json` (minimal single code node)
97
70
 
98
- 4. **In a project with `eventpipe.json`**, build and publish:
71
+ The **`code`** node id in **`settings.pipe`** must match the code node you bundle (default file: **`src/handler.ts`**).
99
72
 
100
- ```bash
101
- eventpipe build
102
- export EVENTPIPE_API_KEY=evp_your_key # from Account → API keys on the app
103
- eventpipe push
104
- ```
105
-
106
- ---
107
-
108
- ## Commands
109
-
110
- ### `eventpipe login`
111
-
112
- Opens your browser to complete sign-in (session stored for the CLI). Credentials are written to **`~/.eventpipe/credentials.json`** (Unix) or the equivalent under your user profile on Windows.
113
-
114
- - **Default app URL:** `https://eventpipe.app`
115
- - **Override:** set `EVENTPIPE_BASE_URL` to your own deployment origin (no trailing slash), e.g. `https://app.example.com`.
116
-
117
- ---
118
-
119
- ### `eventpipe create [--name <slug>]`
120
-
121
- Creates a new webhook endpoint using your logged-in session.
122
-
123
- | Option | Meaning |
124
- |--------|---------|
125
- | `--name <slug>` | If the slug is free, your webhook URL can use that path; if it is taken, the CLI creates the endpoint with a random id and may warn you. |
126
- | *(none)* | URL and label are generated for you. |
73
+ ```json
74
+ {
75
+ "pipelineId": "YOUR_PIPELINE_UUID",
76
+ "settings": {
77
+ "pipe": {
78
+ "schemaVersion": 3,
79
+ "nodes": [
80
+ { "id": "code", "type": "code", "config": {} }
81
+ ],
82
+ "edges": []
83
+ }
84
+ }
85
+ }
86
+ ```
127
87
 
128
- You’ll see the public webhook URL in the output. Manage endpoints in the [web app](https://eventpipe.app).
88
+ ### 3. Handler entry (`src/handler.ts`)
129
89
 
130
- ---
90
+ ```typescript
91
+ type FlowEvent = {
92
+ method: string;
93
+ headers: Record<string, string>;
94
+ body: unknown;
95
+ };
131
96
 
132
- ### `eventpipe listen <webhookId> [options]`
97
+ type FlowContext = { env?: Record<string, string> };
133
98
 
134
- Connects to Event Pipe’s relay and prints **one line per incoming webhook** on stdout. Use this to debug integrations or pipe events into scripts.
99
+ export async function handler(event: FlowEvent, _context: FlowContext) {
100
+ return { ok: true, received: event.body };
101
+ }
102
+ ```
135
103
 
136
- | Option | Short | Description |
137
- |--------|-------|-------------|
138
- | `--verbose` | `-v` | Print the full event payload (method, headers, query, body) as formatted JSON after the summary line. |
139
- | `--json` | | Print **one JSON object per line** (NDJSON) on stdout — good for tooling and `jq`. |
140
- | `--forward-to <url>` | | Replay each event as an HTTP request to your URL (e.g. local server). Forward result messages go to **stderr** so stdout stays clean for `--json`. |
104
+ In production, secrets are read from **`context.env`** (set in the app **Event** tab), not from `process.env` inside the bundle.
141
105
 
142
- **Examples**
106
+ ### 4. Sign in and push
143
107
 
144
108
  ```bash
145
- eventpipe listen abc123
146
- eventpipe listen abc123 -v
147
- eventpipe listen abc123 --json | jq .
148
- eventpipe listen abc123 --forward-to http://127.0.0.1:3000/webhook
109
+ eventpipe login
110
+ eventpipe push
149
111
  ```
150
112
 
151
- **Requirements:** you must have run **`eventpipe login`** first. The hosted app must be configured with a compatible relay service (see your deployment docs / `.env.example` for relay-related variables).
152
-
153
- ---
154
-
155
- ### `eventpipe build [--dir <path>]`
156
-
157
- Reads **`eventpipe.json`** in the project (or `--dir`), bundles your code nodes with [esbuild](https://esbuild.github.io/), and writes artifacts under **`.eventpipe/`** (sizes and hashes are printed). Each bundle must stay within the **200KB** limit (same as the server).
158
-
159
- ---
160
-
161
- ### `eventpipe push [--dir <path>]`
162
-
163
- Runs **`build`**, then uploads a **new version** of your pipeline to Event Pipe using your **API key** (not the browser session).
113
+ - **`login`** opens the browser and saves session under **`~/.eventpipe/credentials.json`**. Default app is **`https://eventpipe.app`** (override with **`EVENTPIPE_BASE_URL`** for self-hosted).
114
+ - **`push`** runs **`build`** then uploads bundles. If **`EVENTPIPE_API_KEY`** is set, it is used **instead of** session (typical for **CI**).
164
115
 
165
- | Need | Detail |
166
- |------|--------|
167
- | `EVENTPIPE_API_KEY` | **Required.** Create an API key in the app (format like `evp_…`). |
168
- | `EVENTPIPE_BASE_URL` | Optional; defaults to `https://eventpipe.app`. |
169
- | `--pipeline <uuid>` or `--flow <uuid>` | Optional; overrides `pipelineId` in `eventpipe.json` for this push only. |
170
-
171
- Example:
116
+ ### CI example
172
117
 
173
118
  ```bash
174
119
  export EVENTPIPE_API_KEY=evp_xxxxxxxx
120
+ # optional for self-hosted: export EVENTPIPE_BASE_URL=https://your-app.example.com
175
121
  eventpipe push --dir ./my-flow
176
122
  ```
177
123
 
178
- ---
124
+ ### Override pipeline id
179
125
 
180
- ### `eventpipe update`
181
-
182
- Runs **`npm install -g @eventpipe/cli@latest`** so you get the newest published CLI (uses `npm` on your PATH; on Windows the CLI invokes `npm.cmd` as needed).
183
-
184
- ---
185
-
186
- ### `eventpipe --version` / `eventpipe -v`
187
-
188
- Prints the installed package version.
126
+ ```bash
127
+ eventpipe push --pipeline <uuid>
128
+ # alias: --flow <uuid>
129
+ ```
189
130
 
190
131
  ---
191
132
 
192
- ### `eventpipe help` / `eventpipe --help`
133
+ ## Other commands (summary)
193
134
 
194
- Prints built-in usage.
135
+ | Command | Purpose |
136
+ |---------|---------|
137
+ | **`eventpipe login`** | Browser sign-in; stores session. |
138
+ | **`eventpipe create [--name <slug>]`** | New webhook endpoint (requires login). |
139
+ | **`eventpipe listen <id> [--json] [-v] [--forward-to <url>]`** | Stream webhooks from the relay. |
140
+ | **`eventpipe build [--dir <path>]`** | Esbuild → `.eventpipe/`; prints size and hash (max **200KB** per bundle). |
141
+ | **`eventpipe update`** | Runs **`npm install -g @eventpipe/cli@latest`**. |
142
+ | **`eventpipe -v` / `--version`** | Print CLI version. |
143
+ | **`eventpipe help`** | Built-in usage. |
195
144
 
196
145
  ---
197
146
 
198
- ## Project layout (for `build` / `push`)
147
+ ## Project layout
199
148
 
200
149
  | File / folder | Role |
201
150
  |---------------|------|
202
- | **`eventpipe.json`** | **`pipelineId`**, flow **`settings`** (must include `pipe` v3), and optional **`nodeId`**, **`entry`**, or **`codeNodes`** map. |
203
- | **`src/handler.ts`** | Default entry if you don’t set `entry` — export `handler(event, context)`. |
204
- | **`.eventpipe/`** | Generated bundles (created by `build` / `push`). |
205
-
206
- **Secrets at runtime:** in the cloud, your flow uses **`context.env`** for configured secrets (set in the app’s **Event** / pipeline UI), not `process.env` in the bundle.
207
-
208
- ---
209
-
210
- ## Environment variables
211
-
212
- | Variable | When it matters | Description |
213
- |----------|-----------------|-------------|
214
- | **`EVENTPIPE_BASE_URL`** | `login`, `push` | App origin, no trailing slash. **Default:** `https://eventpipe.app`. Use your own origin for self-hosted deployments. |
215
- | **`EVENTPIPE_API_KEY`** | `push` | Account API key (`evp_…`). Required to publish versions from the CLI. |
216
- | **`EVENTPIPE_SKIP_UPDATE_CHECK`** | any | Set to `1` to disable the occasional **“newer version on npm”** message on stderr (useful in CI). |
151
+ | **`eventpipe.json`** | **`pipelineId`**, **`settings.pipe`** (v3), optional **`nodeId`**, **`entry`**, or **`codeNodes`** for multi-file graphs. |
152
+ | **`src/handler.ts`** | Default entry when **`entry`** is omitted. |
153
+ | **`.eventpipe/`** | Generated bundles (from **`build`** / **`push`**). |
217
154
 
218
155
  ---
219
156
 
220
157
  ## Update hints
221
158
 
222
- After most commands, the CLI may check npm for a **newer `@eventpipe/cli`** and print a short message on **stderr** suggesting:
223
-
224
- ```bash
225
- eventpipe update
226
- ```
227
-
228
- To turn this off, set `EVENTPIPE_SKIP_UPDATE_CHECK=1`.
159
+ After most commands, the CLI may check npm for a newer **`@eventpipe/cli`** and print a short message on **stderr** suggesting **`eventpipe update`**. Set **`EVENTPIPE_SKIP_UPDATE_CHECK=1`** to disable (e.g. in CI).
229
160
 
230
161
  ---
231
162
 
232
- ## Example project
163
+ ## Example
233
164
 
234
- See **`examples/stripe-webhook`** in this repository for a sample layout and Stripe-oriented flow.
165
+ See **`examples/stripe-webhook`** for a fuller project (multi-node **`codeNodes`** example).
235
166
 
236
167
  ---
237
168
 
238
- ## Limits (current CLI)
169
+ ## Limits
239
170
 
240
- - **Single-code-node focus:** one primary code-node workflow per project is the happy path; multi-node flows may need publishing from the **[dashboard](https://eventpipe.app)** or extending the CLI.
241
- - **Bundle size:** **200KB** UTF-8 per code-node bundle (enforced locally and on the server).
171
+ - **Single-code-node** workflows are the simplest; multi-node graphs may need a **`codeNodes`** map or publishing from the [dashboard](https://eventpipe.app).
172
+ - **200KB** UTF-8 per code-node bundle (same as the server).
242
173
 
243
174
  ---
244
175
 
245
176
  ## Getting help
246
177
 
247
- - **Product & docs:** [eventpipe.app](https://eventpipe.app)
248
- - **CLI usage:** `eventpipe help`
249
- - **Issues:** use your repository’s issue tracker if you develop the CLI from source.
178
+ - **Product:** [eventpipe.app](https://eventpipe.app) — platform docs include **CLI** and **API reference**.
179
+ - **This repo:** `eventpipe help`
package/dist/cli.js CHANGED
@@ -8,6 +8,7 @@ import { publishVersion } from "./publish.js";
8
8
  import { applyPublishedStudioSources, codeNodeUsesLibrary } from "./studio-sources.js";
9
9
  import { cmdLogin } from "./cmd-login.js";
10
10
  import { cmdCreate } from "./cmd-create.js";
11
+ import { loadCredentials } from "./credentials.js";
11
12
  import { resolveEventpipeBaseUrl } from "./base-url.js";
12
13
  import { fetchLatestPublishedVersion, isPublishedVersionNewer, readInstalledCliVersion, } from "./cli-version.js";
13
14
  import { cmdUpdate } from "./cmd-update.js";
@@ -18,7 +19,7 @@ function usage() {
18
19
 
19
20
  Environment:
20
21
  EVENTPIPE_BASE_URL App origin (default: https://eventpipe.app); override for self-hosted
21
- EVENTPIPE_API_KEY Account API key (x-api-key) for push when not using session
22
+ EVENTPIPE_API_KEY Optional; for push in CI/automation (overrides session if set)
22
23
  EVENTPIPE_SKIP_UPDATE_CHECK Set to 1 to disable the npm version hint on stderr
23
24
 
24
25
  Commands:
@@ -28,7 +29,7 @@ Commands:
28
29
  Stream webhooks; --verbose prints full JSON event; --json one NDJSON line per event;
29
30
  --forward-to replays the request to your local server (status on stderr)
30
31
  build [--dir <path>] Bundle TS into .eventpipe/
31
- push [--dir <path>] build + POST /api/account/pipelines/:id/versions (needs EVENTPIPE_API_KEY)
32
+ push [--dir <path>] build + publish (session after login, or EVENTPIPE_API_KEY)
32
33
  update npm install -g @eventpipe/cli@latest
33
34
  help
34
35
 
@@ -102,11 +103,19 @@ async function cmdBuild(projectDir) {
102
103
  }
103
104
  }
104
105
  async function cmdPush(projectDir, pipelineOverride) {
105
- const base = resolveEventpipeBaseUrl();
106
106
  const key = process.env.EVENTPIPE_API_KEY?.trim();
107
- if (!key) {
108
- throw new Error("EVENTPIPE_API_KEY is required for push");
107
+ const cred = await loadCredentials();
108
+ let auth = null;
109
+ if (key) {
110
+ auth = { type: "apiKey", apiKey: key };
109
111
  }
112
+ else if (cred) {
113
+ auth = { type: "session", cred };
114
+ }
115
+ if (!auth) {
116
+ throw new Error("Run eventpipe login first, or set EVENTPIPE_API_KEY for push (e.g. in CI)");
117
+ }
118
+ const base = auth.type === "session" ? auth.cred.baseUrl : resolveEventpipeBaseUrl();
110
119
  const manifest = await loadManifest(projectDir);
111
120
  const pipelineId = pipelineOverride ?? manifest.pipelineId;
112
121
  const pipe = manifest.settings.pipe;
@@ -145,7 +154,7 @@ async function cmdPush(projectDir, pipelineOverride) {
145
154
  : null;
146
155
  const result = await publishVersion({
147
156
  baseUrl: base,
148
- apiKey: key,
157
+ auth,
149
158
  pipelineId,
150
159
  manifest: manifestForPublish,
151
160
  bundles,
package/dist/publish.d.ts CHANGED
@@ -1,4 +1,5 @@
1
1
  import type { EventpipeManifest } from "./config.js";
2
+ import type { StoredCredentials } from "./credentials.js";
2
3
  export type PublishResult = {
3
4
  success?: boolean;
4
5
  version?: number;
@@ -6,9 +7,16 @@ export type PublishResult = {
6
7
  bundleSizeBytes?: number;
7
8
  error?: string;
8
9
  };
10
+ export type PublishAuth = {
11
+ type: "apiKey";
12
+ apiKey: string;
13
+ } | {
14
+ type: "session";
15
+ cred: StoredCredentials;
16
+ };
9
17
  export declare function publishVersion(params: {
10
18
  baseUrl: string;
11
- apiKey: string;
19
+ auth: PublishAuth;
12
20
  pipelineId: string;
13
21
  manifest: EventpipeManifest;
14
22
  bundles: Array<{
package/dist/publish.js CHANGED
@@ -1,20 +1,34 @@
1
+ import { fetchWithSession } from "./auth-fetch.js";
1
2
  export async function publishVersion(params) {
2
- const res = await fetch(`${params.baseUrl}/api/account/pipelines/${params.pipelineId}/versions`, {
3
- method: "POST",
4
- headers: {
5
- "content-type": "application/json",
6
- "x-api-key": params.apiKey,
3
+ const url = `${params.baseUrl}/api/account/pipelines/${params.pipelineId}/versions`;
4
+ const body = JSON.stringify({
5
+ sourceCode: params.sourceCode ?? null,
6
+ buildMeta: {
7
+ bundler: "eventpipe-cli",
8
+ generatedAt: new Date().toISOString(),
7
9
  },
8
- body: JSON.stringify({
9
- sourceCode: params.sourceCode ?? null,
10
- buildMeta: {
11
- bundler: "eventpipe-cli",
12
- generatedAt: new Date().toISOString(),
13
- },
14
- settings: params.manifest.settings,
15
- codeBundles: params.bundles,
16
- }),
10
+ settings: params.manifest.settings,
11
+ codeBundles: params.bundles,
17
12
  });
13
+ let res;
14
+ if (params.auth.type === "apiKey") {
15
+ res = await fetch(url, {
16
+ method: "POST",
17
+ headers: {
18
+ "content-type": "application/json",
19
+ "x-api-key": params.auth.apiKey,
20
+ },
21
+ body,
22
+ });
23
+ }
24
+ else {
25
+ const out = await fetchWithSession(url, {
26
+ method: "POST",
27
+ headers: { "content-type": "application/json" },
28
+ body,
29
+ }, params.auth.cred);
30
+ res = out.response;
31
+ }
18
32
  const data = (await res.json());
19
33
  if (!res.ok) {
20
34
  return { error: data?.error ?? res.statusText };
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@eventpipe/cli",
3
- "version": "0.2.2",
4
- "description": "Build and publish Event Pipe flow bundles (API key auth)",
3
+ "version": "0.2.3",
4
+ "description": "Build and publish Event Pipe flow bundles (session or API key)",
5
5
  "type": "module",
6
6
  "bin": {
7
7
  "eventpipe": "./dist/cli.js",