coss-cli 0.1.1 → 0.2.0

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.
package/README.md CHANGED
@@ -7,24 +7,76 @@ log, and receive its webhook events on your machine.
7
7
  npm install -g coss-cli # or: npx coss-cli <command>
8
8
  coss login
9
9
  coss listen --forward-to localhost:3000/webhooks
10
+ coss trigger email.bounced # in another terminal: a test event, forwarded by coss listen
10
11
  ```
11
12
 
12
13
  Published from [cosscom/coss](https://github.com/cosscom/coss) by CI, with
13
14
  [provenance](https://docs.npmjs.com/generating-provenance-statements). Full guide:
14
15
  [coss.com/docs/cli](https://coss.com/docs/cli).
15
16
 
17
+ ## Install without Node.js
18
+
19
+ Each release's [GitHub release](https://github.com/cosscom/coss/releases) (`coss-cli@<version>`)
20
+ also has standalone executables (Bun's runtime built in) for macOS, Linux (glibc and musl) and
21
+ Windows, arm64 and x64, with a `SHA256SUMS`:
22
+
23
+ ```sh
24
+ brew install cosscom/tap/coss # macOS and Linux; completions included
25
+ curl -fsSL https://raw.githubusercontent.com/cosscom/coss/main/packages/cli/install.sh | sh
26
+ ```
27
+
28
+ `install.sh` picks the archive for the machine, checks it against `SHA256SUMS` and installs `coss`
29
+ into `~/.local/bin` (`COSS_INSTALL_DIR`; `COSS_VERSION` for another version). The musl builds need
30
+ `libstdc++` (`apk add libstdc++` on Alpine). macOS executables are ad-hoc signed, not notarized:
31
+ one downloaded with a browser needs `xattr -d com.apple.quarantine coss`.
32
+
16
33
  ## Commands
17
34
 
18
35
  | Command | |
19
36
  | --- | --- |
20
37
  | `coss login` | Opens the dashboard, where you pick an environment; the CLI gets a new API key of it. `--manual` pastes an existing key instead; `--no-browser` (the default over SSH) shows a link and asks for the code it displays. |
21
- | `coss logout` | Removes the saved key, and revokes it if `coss login` created it (`--revoke` revokes a pasted one too). |
38
+ | `coss logout` | Removes the saved key, and revokes it if `coss login` created it (`--revoke` revokes a pasted one too; `--all` signs every profile out). |
22
39
  | `coss whoami` | The key in use, where it comes from, and its organization, project and environment. |
23
- | `coss emails send` | A test email: `--to`, or `--simulate delivered\|bounced\|complained\|suppressed` for the mailbox simulator; `--template` with `--var name=value`; `--wait` follows it to its outcome. |
24
- | `coss logs tail` | New lines of the environment's log as they arrive: API requests, email events, webhook attempts. Filter with `--source`, `--level`, `--type`, `--status`, `-q`; `--since 15m` starts earlier. |
25
- | `coss listen` | Receives the environment's webhook events and forwards each one to `--forward-to`, signed like coss.com signs real deliveries. Verify them with `verifyWebhook` from the `coss` SDK and the signing secret it prints (it stays the same for the profile). |
40
+ | `coss profiles list` | The saved profiles: each one's environment, whether `coss login` created its key or it was pasted, and which is the default. |
41
+ | `coss use <profile>` | Makes a saved profile the default. |
42
+ | `coss init` | Sets the project in the current directory up: installs `coss` with its package manager (`--no-install` doesn't) and writes a new development key, approved in the dashboard and named after the project, to `.env.local` (Next.js) or `.env` (`--env-file` picks another). A key already there is kept unless `--force`. |
43
+ | `coss open [page]` | Opens the environment's page in the dashboard: `overview`, `emails`, `logs`, `webhooks`, `api-keys`, `domains`, `billing`, … (`--print` prints the URL). |
44
+ | `coss emails send` | A test email: `--to`, or `--simulate delivered\|bounced\|complained\|suppressed` for the mailbox simulator; `--template` with `--var name=value`; `--wait` follows it to its outcome (up to `--timeout`, 60 s). |
45
+ | `coss emails list` | The environment's emails, newest first, with where each stands. Filter with `--to`, `--status`, `--recipient-status`, `-q`, `--category`, `--batch`, `--since`/`--until`; `--limit` (20). |
46
+ | `coss emails get <id>` | An email: sender, recipients and their statuses, failure, tracking, attachments; `--text` or `--html` prints a body alone. |
47
+ | `coss emails events <id>` | Its delivery events, with the receiving server's answers. |
48
+ | `coss emails diagnose <id>` | Whether it was delivered and, if not, why and what to do (or `--to <address>` for the newest email to it). |
49
+ | `coss logs tail` | New lines of the environment's log as they arrive: API requests, email events, webhook attempts. Filter with `--source`, `--level`, `--type`, `--status`, `-q`; `--since 15m` starts earlier; `--interval` sets the poll interval (2000 ms). |
50
+ | `coss inbox` | The environment's inbound domain, then each email it receives as it arrives (`--since`, `--interval`). |
51
+ | `coss inbox get <id>` | A received email: verdicts, attachments and its text (`--html`, `--headers`); `--raw > message.eml` saves the message as received. |
52
+ | `coss listen` | Receives the environment's webhook events and forwards each one to `--forward-to`, signed like coss.com signs real deliveries. Verify them with `verifyWebhook` from the `coss` SDK and the signing secret it prints (it stays the same for the profile). `--header "Name: value"` adds a header to forwarded requests. |
53
+ | `coss trigger <event-type>` | A test event of that type, sent to the environment's subscribed endpoints and `coss listen` listeners like a real one (sandbox keys; every type but `domain.*`, `account.*`, `billing.*`). `--data '{…}'` and `-F name=value` (dotted names, JSON values) change its `data`. |
54
+ | `coss webhooks list` | The environment's webhook endpoints: URL, state and event types. |
55
+ | `coss webhooks deliveries <endpoint>` | An endpoint's deliveries, newest first (`--status failed`, `--event <id>`, `--limit`). |
56
+ | `coss webhooks retry <endpoint> <delivery>` | Sends a finished delivery to its endpoint once more. |
57
+ | `coss hooks apps list`, `coss hooks apps create <name>` | [Hooks](https://coss.com/docs/hooks) applications (`--uid`, `--metadata`). Every `<app>` below is an application's id or uid. |
58
+ | `coss hooks event-types list`, `coss hooks event-types create <name>` | The event types messages are sent as (`--description`, `--schema`, `--example`). |
59
+ | `coss hooks endpoints list <app>`, `coss hooks endpoints add <app> --url <url>` | An application's endpoints; `add` prints the new endpoint's signing secret (`--types`, `--rate-limit`). |
60
+ | `coss hooks send <app> <event-type>` | Sends a message: the payload from `--data '{…}'`, `-F name=value` fields, or the type's first example. |
61
+ | `coss hooks deliveries <app>`, `coss hooks attempts <app> <delivery>`, `coss hooks retry <app> <delivery>` | Deliveries (`--endpoint`, `--message`, `--status`), each HTTP request of one, and one more attempt. |
62
+ | `coss hooks portal <app>` | A portal link for the application's users (`--open`, `--read-only`, `--expires-in`). |
63
+ | `coss risk assess --event <event>` | Assesses an event (`--email`, `--ip`, `--user`, `--content`, `--data '{…}'`…) and prints the decision, score and reasons. Sandbox fixtures (`192.0.2.1`, `disposable.test`, `[coss-test:spam]`…) produce each decision. |
64
+ | `coss risk assessments`, `coss risk feedback <assessment> --outcome <outcome>` | Assessments (`--review open`: the review queue), and what a user turned out to be. |
65
+ | `coss risk lists list`, `coss risk lists add <allow\|block> <type> <value>`, `coss risk lists remove <entry>` | The allow and block lists (`--note`, `--expires 7d`). |
66
+ | `coss domains list` | The organization's sending domains and their status. |
67
+ | `coss domains add <domain>` | Adds a domain and prints the DNS records to publish (`--format bind` prints zone-file lines). |
68
+ | `coss domains get <domain>` | A domain's records and what the last DNS check saw (verified, missing, mismatch). `--format bind` too. |
69
+ | `coss domains verify <domain>` | Checks the records now; `--wait` keeps checking until the domain is verified, saying which records are still missing (up to `--timeout`, 600 s). |
70
+ | `coss templates list` | The environment's email templates. |
71
+ | `coss templates pull [<template>...]` | Writes drafts to `--dir` (`templates`): a folder per template with `template.json` and `<locale>.subject.txt`, `<locale>.html`, `<locale>.txt`. |
72
+ | `coss templates push [<path>...]` | Saves drafts from those files, finding templates by alias (creating missing ones); `--publish` publishes after, `--watch` pushes again whenever a file changes. |
73
+ | `coss templates preview <template>` | Renders the draft (or `--version`) without sending: `--var name=value`, `--locale`, `--open` shows the HTML, `--output` saves it. |
74
+ | `coss api <path>` | Any endpoint of the API, with the CLI's key: `coss api domains`, `coss api -X POST domains/<id>/verify`. `-f name=value` (strings) and `-F name=value` (JSON values, `@file`) are query parameters for GET and DELETE and the JSON body otherwise; `--input file.json` (or `-` for stdin) sends a body as is; `--paginate` prints every item of a list; `--raw` prints a body that isn't JSON. |
75
+ | `coss completion <shell>` | The completion script for `bash`, `zsh` or `fish`, e.g. `eval "$(coss completion zsh)"` in `~/.zshrc`. |
26
76
 
27
- Every command takes `--json` (one JSON object per line), `--profile <name>` and `--help`.
77
+ Every command takes `--json` (one JSON object per line), `--profile <name>` and `--help`; `coss --version`
78
+ prints the CLI's. Results go to stdout, progress to stderr. Exit codes: `0` done, `1` failed, `2` wrong usage,
79
+ `130` stopped with Ctrl-C.
28
80
 
29
81
  ## Configuration
30
82
 
@@ -34,16 +86,23 @@ Every command takes `--json` (one JSON object per line), `--profile <name>` and
34
86
  | `COSS_PROFILE` | The saved profile to use (default: the one `coss login` saved first). |
35
87
  | `COSS_BASE_URL` | Another API origin, e.g. `http://localhost:3001`. Remembered by `coss login`. |
36
88
  | `COSS_DASHBOARD_URL` | Another dashboard for `coss login`, e.g. `http://localhost:3000`. |
89
+ | `COSS_NO_UPDATE_CHECK` | `1` turns the update notice off. |
37
90
 
38
91
  Keys are saved in `$XDG_CONFIG_HOME/coss/config.json` (`~/.config/coss`, `%APPDATA%\coss` on Windows),
39
92
  readable only by you. No flag takes a key: command lines are visible to other local processes.
40
93
 
94
+ Once a day, in a terminal, the CLI asks the npm registry for its latest version (a plain `GET` of
95
+ `https://registry.npmjs.org/coss-cli/latest`, nothing else is sent) and prints one line on stderr
96
+ when there is a newer one. It never runs with `--json`, in CI (`CI`) or when stderr isn't a terminal.
97
+
41
98
  ## Development
42
99
 
43
100
  ```sh
44
101
  bun run --cwd packages/cli build # tsdown, publint, attw
45
102
  bun run --cwd packages/cli test
46
103
  node packages/cli/dist/cli.js --help
104
+ bun run --cwd packages/cli build:binaries [native|linux-x64|…] # standalone executables
105
+ bun packages/cli/scripts/smoke-binary.ts packages/cli/binaries/stage/linux-x64/coss
47
106
  ```
48
107
 
49
108
  ## License
package/dist/cli.js CHANGED
@@ -1,15 +1,8 @@
1
1
  #!/usr/bin/env node
2
- import { c as nodeIo, n as run } from "./run-BkqzCyd1.js";
2
+ import { c as flushOutput, l as nodeIo, n as run } from "./run-BurjNVF6.js";
3
3
  //#region src/cli.ts
4
- /** Resolves once everything written to `stream` so far has reached the OS (pipes are async). */
5
- function flushed(stream) {
6
- return new Promise((resolve) => {
7
- if (stream.writableLength === 0) return resolve();
8
- stream.write("", () => resolve());
9
- });
10
- }
11
4
  process.exitCode = await run(process.argv.slice(2), nodeIo());
12
- await Promise.all([flushed(process.stdout), flushed(process.stderr)]);
5
+ await flushOutput();
13
6
  process.exit();
14
7
  //#endregion
15
8
  export {};
package/dist/index.d.ts CHANGED
@@ -1,6 +1,8 @@
1
+ import { Coss } from "coss";
1
2
  //#region src/io.d.ts
2
3
  interface OutputStream {
3
- write(text: string): void;
4
+ /** Text, or bytes as they are (`coss api --raw`). */
5
+ write(chunk: string | Uint8Array): void;
4
6
  isTTY?: boolean;
5
7
  }
6
8
  /** `fetch` as the CLI calls it (the SDK's `FetchLike` too). */
@@ -17,12 +19,30 @@ interface CliIo {
17
19
  sleep(ms: number, signal?: AbortSignal): Promise<void>;
18
20
  /** Opens `url` in the default browser; `false` when none could be started. */
19
21
  openBrowser(url: string): Promise<boolean>;
22
+ /** Everything piped to stdin, as text (`coss api --input -`). */
23
+ readStdin(): Promise<string>;
20
24
  /** Asks a question on stderr and reads one line (not echoed when `secret`). */
21
25
  prompt(question: string, options?: {
22
26
  secret?: boolean;
23
27
  }): Promise<string>;
28
+ /**
29
+ * Calls `onChange` with the name of each file that changes in `dir` (not its subdirectories)
30
+ * until `signal` aborts (`coss templates push --watch`).
31
+ */
32
+ watch(dir: string, signal: AbortSignal, onChange: (file: string) => void): void;
24
33
  /** This machine's name (names the CLI's API key and listener). */
25
34
  hostname(): string;
35
+ /** The directory the command runs in (`coss init`'s project). */
36
+ cwd: string;
37
+ /**
38
+ * Runs a program (a package manager, `git`) and resolves with its exit code, `null` when it
39
+ * couldn't be started. Its output goes to stderr (stdout stays the result), or nowhere when
40
+ * `quiet`.
41
+ */
42
+ exec(command: string, args: string[], options: {
43
+ cwd: string;
44
+ quiet?: boolean;
45
+ }): Promise<number | null>;
26
46
  /** Where `config.json` lives. */
27
47
  configDir: string;
28
48
  /** Aborted on Ctrl-C (SIGINT) and SIGTERM. */
@@ -33,6 +53,13 @@ export declare function defaultConfigDir(env: Record<string, string | undefined>
33
53
  /** The real process: its environment, streams, network and signals. */
34
54
  export declare function nodeIo(): CliIo;
35
55
  //#endregion
56
+ //#region src/commands/api.d.ts
57
+ /**
58
+ * Lists page with `after` set to the last item's `id`, except those of items without one (the
59
+ * API reference's `after` of each list says which field it takes).
60
+ */
61
+ export declare const CURSOR_FIELDS: Readonly<Record<string, string>>;
62
+ //#endregion
36
63
  //#region src/listen/sign.d.ts
37
64
  export declare function generateSecret(): string;
38
65
  export declare function sign(secret: string, id: string, timestamp: number, body: string): string;
package/dist/index.js CHANGED
@@ -1 +1 @@
1
- export { t as HELP, r as VERSION, s as defaultConfigDir, i as generateSecret, c as nodeIo, n as run, a as sign, o as signatureHeaders } from "./run-BkqzCyd1.js";
1
+ export { u as CURSOR_FIELDS, t as HELP, r as VERSION, s as defaultConfigDir, i as generateSecret, l as nodeIo, n as run, a as sign, o as signatureHeaders } from "./run-BurjNVF6.js";