coss-cli 0.3.0 → 0.5.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 +7 -3
- package/dist/cli.js +1 -1
- package/dist/index.js +1 -1
- package/dist/{run-B-0EIbmN.js → run-DLGZnVHf.js} +544 -65
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -27,8 +27,8 @@ curl -fsSL https://raw.githubusercontent.com/cosscom/coss/main/packages/cli/inst
|
|
|
27
27
|
|
|
28
28
|
`install.sh` picks the archive for the machine, checks it against `SHA256SUMS` and installs `coss`
|
|
29
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
|
|
31
|
-
one downloaded with a browser
|
|
30
|
+
`libstdc++` (`apk add libstdc++` on Alpine). macOS executables are signed with coss.com's Developer
|
|
31
|
+
ID and notarized by Apple (since 0.3.0), so one downloaded with a browser runs without a warning.
|
|
32
32
|
|
|
33
33
|
## Commands
|
|
34
34
|
|
|
@@ -39,7 +39,7 @@ one downloaded with a browser needs `xattr -d com.apple.quarantine coss`.
|
|
|
39
39
|
| `coss whoami` | The key in use, where it comes from, and its organization, project and environment. |
|
|
40
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
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`.
|
|
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`. It adds notes on coss.com for coding agents to the project's `AGENTS.md` (`--no-agents` skips them) and prints the one next step for the key. |
|
|
43
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
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
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). |
|
|
@@ -50,9 +50,13 @@ one downloaded with a browser needs `xattr -d com.apple.quarantine coss`.
|
|
|
50
50
|
| `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). |
|
|
51
51
|
| `coss inbox` | The environment's inbound domain, then each email it receives as it arrives (`--since`, `--interval`). |
|
|
52
52
|
| `coss inbox get <id>` | A received email: verdicts, attachments and its text (`--html`, `--headers`); `--raw > message.eml` saves the message as received. |
|
|
53
|
+
| `coss inboxes list`, `coss inboxes create` | [Inboxes](https://coss.com/docs/inboxes): email addresses for agents (`--username`, `--domain`, `--name`, `--client-id`). |
|
|
54
|
+
| `coss inboxes threads <inbox>`, `coss inboxes thread <inbox> <thread>` | An inbox's conversations (● awaits a reply), and one read message by message (`--full` keeps the quoted text). |
|
|
55
|
+
| `coss inboxes reply <inbox> <message> --text <text>` | Replies in the message's thread from the inbox (`--all`: to everyone on it). |
|
|
53
56
|
| `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. |
|
|
54
57
|
| `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`. |
|
|
55
58
|
| `coss webhooks list` | The environment's webhook endpoints: URL, state and event types. |
|
|
59
|
+
| `coss webhooks add <url>` | Creates an endpoint and writes its signing secret to the project env file as `COSS_WEBHOOK_SECRET` (`--events`, `--description`, `--force`). |
|
|
56
60
|
| `coss webhooks deliveries <endpoint>` | An endpoint's deliveries, newest first (`--status failed`, `--event <id>`, `--limit`). |
|
|
57
61
|
| `coss webhooks retry <endpoint> <delivery>` | Sends a finished delivery to its endpoint once more. |
|
|
58
62
|
| `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. |
|
package/dist/cli.js
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
#!/usr/bin/env node
|
|
2
|
-
import { c as flushOutput, l as nodeIo, n as run } from "./run-
|
|
2
|
+
import { c as flushOutput, l as nodeIo, n as run } from "./run-DLGZnVHf.js";
|
|
3
3
|
//#region src/cli.ts
|
|
4
4
|
process.exitCode = await run(process.argv.slice(2), nodeIo());
|
|
5
5
|
await flushOutput();
|
package/dist/index.js
CHANGED
|
@@ -1 +1 @@
|
|
|
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-
|
|
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-DLGZnVHf.js";
|
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
import { access, chmod, mkdir, readFile, readdir, rename, rm, stat, writeFile } from "node:fs/promises";
|
|
2
|
-
import { API_VERSION, Coss, TEST_WEBHOOK_EVENT_TYPES, isLiveOnlyEventType } from "coss";
|
|
2
|
+
import { API_VERSION, Coss, SIMULATOR_TO, TEST_WEBHOOK_EVENT_TYPES, WEBHOOK_EVENT_TYPES, fetchSetupReport, isLiveOnlyEventType } from "coss";
|
|
3
3
|
import { parseArgs } from "node:util";
|
|
4
4
|
import { basename, dirname, join, relative, resolve } from "node:path";
|
|
5
5
|
import { spawn } from "node:child_process";
|
|
@@ -204,7 +204,7 @@ function requireArgs(positionals, count, usage) {
|
|
|
204
204
|
return positionals;
|
|
205
205
|
}
|
|
206
206
|
/** Repeatable flags that may also be comma-separated: `--events a,b --events c`. */
|
|
207
|
-
function list(value) {
|
|
207
|
+
function list$1(value) {
|
|
208
208
|
return (value === void 0 ? [] : Array.isArray(value) ? value : [value]).flatMap((item) => item.split(",")).map((item) => item.trim()).filter(Boolean);
|
|
209
209
|
}
|
|
210
210
|
/** `name=value` flags as pairs (a usage error for anything else). */
|
|
@@ -1256,7 +1256,7 @@ function checkedFormat(format) {
|
|
|
1256
1256
|
if (format !== void 0 && format !== "table" && format !== "bind") throw new UsageError(`--format takes table or bind; got "${format}".`);
|
|
1257
1257
|
return format;
|
|
1258
1258
|
}
|
|
1259
|
-
async function client$
|
|
1259
|
+
async function client$3(context) {
|
|
1260
1260
|
return clientFor(context.io, await resolveCredentials(context));
|
|
1261
1261
|
}
|
|
1262
1262
|
const domainsListCommand = defineCommand({
|
|
@@ -1269,7 +1269,7 @@ const domainsListCommand = defineCommand({
|
|
|
1269
1269
|
} },
|
|
1270
1270
|
run: async ({ context }) => {
|
|
1271
1271
|
const { out } = context;
|
|
1272
|
-
const { data, error } = await (await client$
|
|
1272
|
+
const { data, error } = await (await client$3(context)).domains.list({ signal: context.io.signal });
|
|
1273
1273
|
if (error) throw apiError("Couldn't list the domains", error);
|
|
1274
1274
|
if (out.json) {
|
|
1275
1275
|
for (const domain of data.data) out.data(domain);
|
|
@@ -1335,7 +1335,7 @@ const domainsAddCommand = defineCommand({
|
|
|
1335
1335
|
const { out } = context;
|
|
1336
1336
|
const name = onePositional(positionals, "domain", "domains add");
|
|
1337
1337
|
const format = checkedFormat(values.format);
|
|
1338
|
-
const { data, error } = await (await client$
|
|
1338
|
+
const { data, error } = await (await client$3(context)).domains.create({ name }, { signal: context.io.signal });
|
|
1339
1339
|
if (error) throw apiError(`Couldn't add ${name}`, error);
|
|
1340
1340
|
if (out.json || format === "bind") {
|
|
1341
1341
|
printDomain(out, data, format);
|
|
@@ -1365,7 +1365,7 @@ const domainsGetCommand = defineCommand({
|
|
|
1365
1365
|
run: async ({ values, positionals, context }) => {
|
|
1366
1366
|
const ref = onePositional(positionals, "domain", "domains get");
|
|
1367
1367
|
const format = checkedFormat(values.format);
|
|
1368
|
-
const domain = await findDomain(await client$
|
|
1368
|
+
const domain = await findDomain(await client$3(context), ref);
|
|
1369
1369
|
printDomain(context.out, domain, format);
|
|
1370
1370
|
return 0;
|
|
1371
1371
|
}
|
|
@@ -1813,7 +1813,7 @@ function oneId(positionals, command) {
|
|
|
1813
1813
|
if (id === void 0 || extra.length > 0) throw new UsageError(`Pass one email id: \`coss ${command} email_…\`.`);
|
|
1814
1814
|
return id;
|
|
1815
1815
|
}
|
|
1816
|
-
async function client$
|
|
1816
|
+
async function client$2(context) {
|
|
1817
1817
|
return clientFor(context.io, await resolveCredentials(context));
|
|
1818
1818
|
}
|
|
1819
1819
|
const emailsListCommand = defineCommand({
|
|
@@ -1885,15 +1885,15 @@ async function emailsList({ values, context }) {
|
|
|
1885
1885
|
const now = io.now();
|
|
1886
1886
|
const params = {
|
|
1887
1887
|
...values.to && { to: values.to },
|
|
1888
|
-
...values.status && { status: checked$1(list(values.status), EMAIL_STATUSES, "status") },
|
|
1889
|
-
...values["recipient-status"] && { recipient_status: checked$1(list(values["recipient-status"]), RECIPIENT_STATUSES, "recipient-status") },
|
|
1888
|
+
...values.status && { status: checked$1(list$1(values.status), EMAIL_STATUSES, "status") },
|
|
1889
|
+
...values["recipient-status"] && { recipient_status: checked$1(list$1(values["recipient-status"]), RECIPIENT_STATUSES, "recipient-status") },
|
|
1890
1890
|
...values.query && { q: values.query },
|
|
1891
1891
|
...values.category && { category: values.category },
|
|
1892
1892
|
...values.batch && { batch_id: values.batch },
|
|
1893
1893
|
created_after: time$1(values.since, "since", now),
|
|
1894
1894
|
created_before: time$1(values.until, "until", now)
|
|
1895
1895
|
};
|
|
1896
|
-
const coss = await client$
|
|
1896
|
+
const coss = await client$2(context);
|
|
1897
1897
|
const emails = [];
|
|
1898
1898
|
let after;
|
|
1899
1899
|
while (emails.length < limit) {
|
|
@@ -1961,7 +1961,7 @@ async function emailsGet({ values, positionals, context }) {
|
|
|
1961
1961
|
const { io, out } = context;
|
|
1962
1962
|
const id = oneId(positionals, "emails get");
|
|
1963
1963
|
if (values.text && values.html) throw new UsageError("Pass --text or --html, not both.");
|
|
1964
|
-
const { data: email, error } = await (await client$
|
|
1964
|
+
const { data: email, error } = await (await client$2(context)).email.get(id, { signal: io.signal });
|
|
1965
1965
|
if (io.signal.aborted) return 130;
|
|
1966
1966
|
if (error) throw apiError("Couldn't read the email", error);
|
|
1967
1967
|
if (out.json) {
|
|
@@ -2016,7 +2016,7 @@ const emailsEventsCommand = defineCommand({
|
|
|
2016
2016
|
run: async ({ positionals, context }) => {
|
|
2017
2017
|
const { io, out } = context;
|
|
2018
2018
|
const id = oneId(positionals, "emails events");
|
|
2019
|
-
const { data, error } = await (await client$
|
|
2019
|
+
const { data, error } = await (await client$2(context)).email.listEvents(id, { signal: io.signal });
|
|
2020
2020
|
if (io.signal.aborted) return 130;
|
|
2021
2021
|
if (error) throw apiError("Couldn't read the email's events", error);
|
|
2022
2022
|
if (data.data.length === 0 && !out.json) out.info("No events yet.");
|
|
@@ -2074,7 +2074,7 @@ function steps(out, next, indent) {
|
|
|
2074
2074
|
async function emailsDiagnose({ values, positionals, context }) {
|
|
2075
2075
|
const { io, out } = context;
|
|
2076
2076
|
if (values.to !== void 0 && positionals.length > 0) throw new UsageError("Pass an email id or --to, not both.");
|
|
2077
|
-
const coss = await client$
|
|
2077
|
+
const coss = await client$2(context);
|
|
2078
2078
|
let id;
|
|
2079
2079
|
if (values.to !== void 0) {
|
|
2080
2080
|
const { data, error } = await coss.email.list({
|
|
@@ -2130,7 +2130,7 @@ const DELIVERY_STATUSES$1 = [
|
|
|
2130
2130
|
"succeeded",
|
|
2131
2131
|
"failed"
|
|
2132
2132
|
];
|
|
2133
|
-
const LIMIT$
|
|
2133
|
+
const LIMIT$2 = {
|
|
2134
2134
|
type: "string",
|
|
2135
2135
|
value: "<n>",
|
|
2136
2136
|
description: "How many to show, 1-100 (default 50)"
|
|
@@ -2180,7 +2180,7 @@ const appsList = defineCommand({
|
|
|
2180
2180
|
summary: "List the environment's Hooks applications",
|
|
2181
2181
|
description: "Lists the environment's applications (one per customer of yours, each with its own endpoints and portal), newest first.",
|
|
2182
2182
|
flags: {
|
|
2183
|
-
limit: LIMIT$
|
|
2183
|
+
limit: LIMIT$2,
|
|
2184
2184
|
json: {
|
|
2185
2185
|
type: "boolean",
|
|
2186
2186
|
description: "One application per line, as JSON"
|
|
@@ -2255,7 +2255,7 @@ const eventTypesList = defineCommand({
|
|
|
2255
2255
|
type: "boolean",
|
|
2256
2256
|
description: "Also list archived types"
|
|
2257
2257
|
},
|
|
2258
|
-
limit: LIMIT$
|
|
2258
|
+
limit: LIMIT$2,
|
|
2259
2259
|
json: {
|
|
2260
2260
|
type: "boolean",
|
|
2261
2261
|
description: "One event type per line, as JSON"
|
|
@@ -2404,7 +2404,7 @@ const endpointsAdd = defineCommand({
|
|
|
2404
2404
|
rateLimit = Number(values["rate-limit"]);
|
|
2405
2405
|
if (!Number.isInteger(rateLimit) || rateLimit < 1 || rateLimit > 1e3) throw new UsageError("--rate-limit takes a number from 1 to 1000.");
|
|
2406
2406
|
}
|
|
2407
|
-
const types = list(values.types);
|
|
2407
|
+
const types = list$1(values.types);
|
|
2408
2408
|
const { data, error } = await (await hooksClient(context)).hooks.endpoints.create(app, {
|
|
2409
2409
|
url: values.url,
|
|
2410
2410
|
...types.length > 0 && { filter_types: types },
|
|
@@ -2507,7 +2507,7 @@ const DELIVERIES_FLAGS$1 = {
|
|
|
2507
2507
|
choices: DELIVERY_STATUSES$1,
|
|
2508
2508
|
description: "pending, succeeded or failed"
|
|
2509
2509
|
},
|
|
2510
|
-
limit: LIMIT$
|
|
2510
|
+
limit: LIMIT$2,
|
|
2511
2511
|
json: {
|
|
2512
2512
|
type: "boolean",
|
|
2513
2513
|
description: "One delivery per line, as JSON"
|
|
@@ -2926,6 +2926,347 @@ async function inboxGet({ values, positionals, context }) {
|
|
|
2926
2926
|
return 0;
|
|
2927
2927
|
}
|
|
2928
2928
|
//#endregion
|
|
2929
|
+
//#region src/commands/inboxes.ts
|
|
2930
|
+
const LIMIT$1 = {
|
|
2931
|
+
type: "string",
|
|
2932
|
+
value: "<n>",
|
|
2933
|
+
description: "How many to show, 1-100 (default 20)"
|
|
2934
|
+
};
|
|
2935
|
+
async function client$1(context) {
|
|
2936
|
+
return clientFor(context.io, await resolveCredentials(context));
|
|
2937
|
+
}
|
|
2938
|
+
const list = defineCommand({
|
|
2939
|
+
name: "inboxes list",
|
|
2940
|
+
summary: "List the environment's inboxes",
|
|
2941
|
+
description: "Lists the environment's inboxes (addresses for agents), newest first.",
|
|
2942
|
+
flags: {
|
|
2943
|
+
limit: LIMIT$1,
|
|
2944
|
+
json: {
|
|
2945
|
+
type: "boolean",
|
|
2946
|
+
description: "One inbox per line, as JSON"
|
|
2947
|
+
}
|
|
2948
|
+
},
|
|
2949
|
+
run: async ({ values, context }) => {
|
|
2950
|
+
const { data, error } = await (await client$1(context)).inboxes.list({ limit: limitOf$1(values.limit) });
|
|
2951
|
+
if (error) throw apiError("Couldn't list the inboxes", error);
|
|
2952
|
+
printList(context.out, data, {
|
|
2953
|
+
headings: [
|
|
2954
|
+
"ID",
|
|
2955
|
+
"ADDRESS",
|
|
2956
|
+
"NAME",
|
|
2957
|
+
"SENDS",
|
|
2958
|
+
"CREATED"
|
|
2959
|
+
],
|
|
2960
|
+
row: (inbox) => [
|
|
2961
|
+
inbox.id,
|
|
2962
|
+
inbox.address,
|
|
2963
|
+
inbox.display_name ?? "",
|
|
2964
|
+
inbox.can_send ? "yes" : "no",
|
|
2965
|
+
when$1(inbox.created_at)
|
|
2966
|
+
],
|
|
2967
|
+
empty: "No inboxes yet: `coss inboxes create` makes one.",
|
|
2968
|
+
more: "There are more: `coss api inboxes --paginate` lists them all."
|
|
2969
|
+
});
|
|
2970
|
+
return 0;
|
|
2971
|
+
}
|
|
2972
|
+
});
|
|
2973
|
+
const create = defineCommand({
|
|
2974
|
+
name: "inboxes create",
|
|
2975
|
+
summary: "Create an inbox: an email address for an agent",
|
|
2976
|
+
description: "Creates an inbox in the environment. Mail to it is kept as threads, and each message sends an inbox.message.received webhook (`coss listen` forwards them while you develop).",
|
|
2977
|
+
flags: {
|
|
2978
|
+
username: {
|
|
2979
|
+
type: "string",
|
|
2980
|
+
value: "<name>",
|
|
2981
|
+
description: "The part before the @ (default: a random one)"
|
|
2982
|
+
},
|
|
2983
|
+
domain: {
|
|
2984
|
+
type: "string",
|
|
2985
|
+
value: "<hostname>",
|
|
2986
|
+
description: "A receiving domain of the environment (default: its coss.com inbound domain)"
|
|
2987
|
+
},
|
|
2988
|
+
name: {
|
|
2989
|
+
type: "string",
|
|
2990
|
+
value: "<name>",
|
|
2991
|
+
description: "The name messages are sent with"
|
|
2992
|
+
},
|
|
2993
|
+
"client-id": {
|
|
2994
|
+
type: "string",
|
|
2995
|
+
value: "<id>",
|
|
2996
|
+
description: "Your own id for the inbox: creating it again returns the same inbox"
|
|
2997
|
+
},
|
|
2998
|
+
json: {
|
|
2999
|
+
type: "boolean",
|
|
3000
|
+
description: "Print the inbox as JSON"
|
|
3001
|
+
}
|
|
3002
|
+
},
|
|
3003
|
+
run: async ({ values, context }) => {
|
|
3004
|
+
const { data, error } = await (await client$1(context)).inboxes.create({
|
|
3005
|
+
...values.username !== void 0 && { username: values.username },
|
|
3006
|
+
...values.domain !== void 0 && { domain: values.domain },
|
|
3007
|
+
...values.name !== void 0 && { display_name: values.name },
|
|
3008
|
+
...values["client-id"] !== void 0 && { client_id: values["client-id"] }
|
|
3009
|
+
});
|
|
3010
|
+
if (error) throw apiError("Couldn't create the inbox", error);
|
|
3011
|
+
const { out } = context;
|
|
3012
|
+
if (out.json) out.data(data);
|
|
3013
|
+
else {
|
|
3014
|
+
out.line(`${out.style("green", "✔")} ${out.style("bold", data.address)} ${out.style("dim", data.id)}`);
|
|
3015
|
+
if (!data.can_send) out.info("It receives only: live inboxes send from a receiving domain under a verified domain (--domain).");
|
|
3016
|
+
}
|
|
3017
|
+
return 0;
|
|
3018
|
+
}
|
|
3019
|
+
});
|
|
3020
|
+
const threads = defineCommand({
|
|
3021
|
+
name: "inboxes threads",
|
|
3022
|
+
summary: "List an inbox's conversations",
|
|
3023
|
+
usage: "<inbox> [options]",
|
|
3024
|
+
description: "Lists the inbox's threads, latest activity first; ● marks one whose latest message is inbound (it awaits a reply).",
|
|
3025
|
+
flags: {
|
|
3026
|
+
limit: LIMIT$1,
|
|
3027
|
+
json: {
|
|
3028
|
+
type: "boolean",
|
|
3029
|
+
description: "One thread per line, as JSON"
|
|
3030
|
+
}
|
|
3031
|
+
},
|
|
3032
|
+
positionals: true,
|
|
3033
|
+
run: async ({ values, positionals, context }) => {
|
|
3034
|
+
const [inboxId] = requireArgs(positionals, 1, "inboxes threads <inbox>");
|
|
3035
|
+
const { data, error } = await (await client$1(context)).inboxes.threads.list(inboxId, { limit: limitOf$1(values.limit) });
|
|
3036
|
+
if (error) throw apiError("Couldn't list the threads", error);
|
|
3037
|
+
printList(context.out, data, {
|
|
3038
|
+
headings: [
|
|
3039
|
+
"",
|
|
3040
|
+
"ID",
|
|
3041
|
+
"SUBJECT",
|
|
3042
|
+
"WITH",
|
|
3043
|
+
"MESSAGES",
|
|
3044
|
+
"LAST"
|
|
3045
|
+
],
|
|
3046
|
+
row: (thread) => [
|
|
3047
|
+
thread.last_inbound_at === thread.last_message_at ? "●" : "",
|
|
3048
|
+
thread.id,
|
|
3049
|
+
printable(thread.subject ?? "(no subject)"),
|
|
3050
|
+
printable(thread.participants.join(", ")),
|
|
3051
|
+
String(thread.message_count),
|
|
3052
|
+
when$1(thread.last_message_at)
|
|
3053
|
+
],
|
|
3054
|
+
empty: "No conversations yet.",
|
|
3055
|
+
more: "There are more: raise --limit, or `coss api inboxes/<inbox>/threads --paginate`."
|
|
3056
|
+
});
|
|
3057
|
+
return 0;
|
|
3058
|
+
}
|
|
3059
|
+
});
|
|
3060
|
+
function printMessage(out, message, full) {
|
|
3061
|
+
const arrow = message.direction === "inbound" ? out.style("cyan", "←") : out.style("green", "→");
|
|
3062
|
+
out.line(`${arrow} ${out.style("bold", printable(message.from ?? "(unknown sender)"))} ${out.style("dim", `${when$1(message.created_at)} ${message.id}`)}`);
|
|
3063
|
+
if (message.direction === "outbound") out.line(` ${out.style("dim", `to ${printable(message.to.join(", "))} · ${message.status}`)}`);
|
|
3064
|
+
for (const attachment of message.attachments) out.line(` ${out.style("dim", `📎 ${printable(attachment.filename ?? "(unnamed)")}`)}`);
|
|
3065
|
+
const text = full ? message.text : message.extracted_text;
|
|
3066
|
+
out.line();
|
|
3067
|
+
out.line(text === null ? out.style("dim", "(no text)") : printable(text, true));
|
|
3068
|
+
out.line();
|
|
3069
|
+
}
|
|
3070
|
+
const INBOXES_COMMANDS = [
|
|
3071
|
+
list,
|
|
3072
|
+
create,
|
|
3073
|
+
threads,
|
|
3074
|
+
defineCommand({
|
|
3075
|
+
name: "inboxes thread",
|
|
3076
|
+
summary: "Read a conversation",
|
|
3077
|
+
usage: "<inbox> <thread> [options]",
|
|
3078
|
+
description: "Prints the thread's latest messages, oldest first, each with its own words (without the quoted conversation, unless --full). Control characters in senders' text are left out.",
|
|
3079
|
+
flags: {
|
|
3080
|
+
full: {
|
|
3081
|
+
type: "boolean",
|
|
3082
|
+
description: "Print every message's whole text, quotes included"
|
|
3083
|
+
},
|
|
3084
|
+
json: {
|
|
3085
|
+
type: "boolean",
|
|
3086
|
+
description: "Print the thread as JSON"
|
|
3087
|
+
}
|
|
3088
|
+
},
|
|
3089
|
+
positionals: true,
|
|
3090
|
+
run: async ({ values, positionals, context }) => {
|
|
3091
|
+
const [inboxId, threadId] = requireArgs(positionals, 2, "inboxes thread <inbox> <thread>");
|
|
3092
|
+
const { data, error } = await (await client$1(context)).inboxes.threads.get(inboxId, threadId);
|
|
3093
|
+
if (error) throw apiError("Couldn't read the thread", error);
|
|
3094
|
+
const { out } = context;
|
|
3095
|
+
if (out.json) {
|
|
3096
|
+
out.data(data);
|
|
3097
|
+
return 0;
|
|
3098
|
+
}
|
|
3099
|
+
out.line(out.style("bold", printable(data.subject ?? "(no subject)")));
|
|
3100
|
+
out.line(out.style("dim", `with ${printable(data.participants.join(", "))}`));
|
|
3101
|
+
out.line();
|
|
3102
|
+
for (const message of data.messages) printMessage(out, message, values.full === true);
|
|
3103
|
+
return 0;
|
|
3104
|
+
}
|
|
3105
|
+
}),
|
|
3106
|
+
defineCommand({
|
|
3107
|
+
name: "inboxes reply",
|
|
3108
|
+
summary: "Reply to a message from its inbox",
|
|
3109
|
+
usage: "<inbox> <message> --text <text> [--all]",
|
|
3110
|
+
description: "Replies in the message's thread from the inbox's address, to its sender (--all: everyone on it), with Re: and the headers mail clients thread by.",
|
|
3111
|
+
flags: {
|
|
3112
|
+
text: {
|
|
3113
|
+
type: "string",
|
|
3114
|
+
value: "<text>",
|
|
3115
|
+
description: "The reply's text"
|
|
3116
|
+
},
|
|
3117
|
+
all: {
|
|
3118
|
+
type: "boolean",
|
|
3119
|
+
description: "Reply to everyone on the message, not only the sender"
|
|
3120
|
+
},
|
|
3121
|
+
json: {
|
|
3122
|
+
type: "boolean",
|
|
3123
|
+
description: "Print the reply as JSON"
|
|
3124
|
+
}
|
|
3125
|
+
},
|
|
3126
|
+
positionals: true,
|
|
3127
|
+
run: async ({ values, positionals, context }) => {
|
|
3128
|
+
const [inboxId, messageId] = requireArgs(positionals, 2, "inboxes reply <inbox> <message> --text <text>");
|
|
3129
|
+
if (!values.text) throw new UsageError("Pass the reply with --text <text>.");
|
|
3130
|
+
const { data, error } = await (await client$1(context)).inboxes.messages.reply(inboxId, messageId, {
|
|
3131
|
+
text: values.text,
|
|
3132
|
+
...values.all && { reply_all: true }
|
|
3133
|
+
});
|
|
3134
|
+
if (error) throw apiError("Couldn't send the reply", error);
|
|
3135
|
+
const { out } = context;
|
|
3136
|
+
if (out.json) out.data(data);
|
|
3137
|
+
else out.line(`${out.style("green", "✔")} Replied to ${printable(data.to.join(", "))} ${out.style("dim", data.id)}`);
|
|
3138
|
+
return 0;
|
|
3139
|
+
}
|
|
3140
|
+
})
|
|
3141
|
+
];
|
|
3142
|
+
//#endregion
|
|
3143
|
+
//#region src/env-file.ts
|
|
3144
|
+
/**
|
|
3145
|
+
* The project's env file: where `coss init` writes `COSS_API_KEY` and `coss listen` writes
|
|
3146
|
+
* `COSS_WEBHOOK_SECRET`. One file holds both, so a handler and the CLI share them.
|
|
3147
|
+
*/
|
|
3148
|
+
/** The env file with `name=value` set: an existing line replaced, else one appended. */
|
|
3149
|
+
function setEnvVar(text, name, value) {
|
|
3150
|
+
const line = new RegExp(`^\\s*(?:export\\s+)?${name}\\s*=.*$`, "m");
|
|
3151
|
+
if (line.test(text)) return text.replace(line, () => `${name}=${value}`);
|
|
3152
|
+
return `${text}${text === "" || text.endsWith("\n") ? "" : "\n"}${name}=${value}\n`;
|
|
3153
|
+
}
|
|
3154
|
+
/** `text` without `name`'s assignments. */
|
|
3155
|
+
function removeEnvVar(text, name) {
|
|
3156
|
+
return text.replace(new RegExp(`^[ \\t]*(?:export[ \\t]+)?${name}[ \\t]*=.*(?:\\r?\\n|$)`, "gm"), "");
|
|
3157
|
+
}
|
|
3158
|
+
/** The value of `name` in an env file, without surrounding quotes. Empty when it is absent. */
|
|
3159
|
+
function readEnvValue(text, name) {
|
|
3160
|
+
return new RegExp(`^\\s*(?:export\\s+)?${name}\\s*=\\s*["']?([^"'\\s#]*)`, "m").exec(text)?.[1] ?? "";
|
|
3161
|
+
}
|
|
3162
|
+
async function readOptional$2(path) {
|
|
3163
|
+
try {
|
|
3164
|
+
return await readFile(path, "utf8");
|
|
3165
|
+
} catch {
|
|
3166
|
+
return null;
|
|
3167
|
+
}
|
|
3168
|
+
}
|
|
3169
|
+
function holdsCredential(text) {
|
|
3170
|
+
return readEnvValue(text, "COSS_API_KEY") !== "" || readEnvValue(text, "COSS_WEBHOOK_SECRET") !== "";
|
|
3171
|
+
}
|
|
3172
|
+
async function isNextProject(dir) {
|
|
3173
|
+
const text = await readOptional$2(join(dir, "package.json"));
|
|
3174
|
+
if (!text) return false;
|
|
3175
|
+
try {
|
|
3176
|
+
const pkg = JSON.parse(text);
|
|
3177
|
+
return Boolean(pkg.dependencies?.next ?? pkg.devDependencies?.next);
|
|
3178
|
+
} catch {
|
|
3179
|
+
return false;
|
|
3180
|
+
}
|
|
3181
|
+
}
|
|
3182
|
+
/**
|
|
3183
|
+
* The env file that already holds `COSS_API_KEY` or `COSS_WEBHOOK_SECRET` (`.env.local` before
|
|
3184
|
+
* `.env`, walking up from `dir`), else the file `coss init` would create: `.env.local` in a
|
|
3185
|
+
* Next.js project, `.env` otherwise.
|
|
3186
|
+
*/
|
|
3187
|
+
async function projectEnvFile(dir) {
|
|
3188
|
+
let current = resolve(dir);
|
|
3189
|
+
for (;;) {
|
|
3190
|
+
for (const name of [".env.local", ".env"]) {
|
|
3191
|
+
const path = join(current, name);
|
|
3192
|
+
const text = await readOptional$2(path);
|
|
3193
|
+
if (text !== null && holdsCredential(text)) return {
|
|
3194
|
+
path,
|
|
3195
|
+
text
|
|
3196
|
+
};
|
|
3197
|
+
}
|
|
3198
|
+
const parent = dirname(current);
|
|
3199
|
+
if (parent === current) break;
|
|
3200
|
+
current = parent;
|
|
3201
|
+
}
|
|
3202
|
+
const root = resolve(dir);
|
|
3203
|
+
const path = join(root, await isNextProject(root) ? ".env.local" : ".env");
|
|
3204
|
+
return {
|
|
3205
|
+
path,
|
|
3206
|
+
text: await readOptional$2(path)
|
|
3207
|
+
};
|
|
3208
|
+
}
|
|
3209
|
+
/** Writes `name=value` into the file. Returns whether the file changed. A new file is mode 0600. */
|
|
3210
|
+
async function writeEnvValue(file, name, value) {
|
|
3211
|
+
const next = setEnvVar(file.text ?? "", name, value);
|
|
3212
|
+
if (next === (file.text ?? "")) return false;
|
|
3213
|
+
await mkdir(dirname(file.path), { recursive: true });
|
|
3214
|
+
await writeFile(file.path, next, file.text === null ? { mode: 384 } : void 0);
|
|
3215
|
+
file.text = next;
|
|
3216
|
+
return true;
|
|
3217
|
+
}
|
|
3218
|
+
//#endregion
|
|
3219
|
+
//#region src/project-stack.ts
|
|
3220
|
+
/**
|
|
3221
|
+
* What `coss init` can see of the project, so its closing message points at the drop-in that
|
|
3222
|
+
* project already uses. Detection only reads files; it never installs anything.
|
|
3223
|
+
*/
|
|
3224
|
+
async function exists$2(path) {
|
|
3225
|
+
return access(path).then(() => true, () => false);
|
|
3226
|
+
}
|
|
3227
|
+
async function readOptional$1(path) {
|
|
3228
|
+
try {
|
|
3229
|
+
return await readFile(path, "utf8");
|
|
3230
|
+
} catch {
|
|
3231
|
+
return null;
|
|
3232
|
+
}
|
|
3233
|
+
}
|
|
3234
|
+
function dependsOn$1(pkg, name) {
|
|
3235
|
+
return Boolean(pkg.dependencies?.[name] ?? pkg.devDependencies?.[name]);
|
|
3236
|
+
}
|
|
3237
|
+
async function detectDriver(dir) {
|
|
3238
|
+
if ((await readOptional$1(join(dir, "composer.json")))?.includes("\"laravel/framework\"")) return {
|
|
3239
|
+
kind: "laravel",
|
|
3240
|
+
install: "composer require coss/laravel"
|
|
3241
|
+
};
|
|
3242
|
+
const gemfile = await readOptional$1(join(dir, "Gemfile"));
|
|
3243
|
+
if (gemfile && /^\s*gem\s+["']rails["']/m.test(gemfile)) return {
|
|
3244
|
+
kind: "rails",
|
|
3245
|
+
install: "bundle add coss-rails"
|
|
3246
|
+
};
|
|
3247
|
+
const manage = await readOptional$1(join(dir, "manage.py"));
|
|
3248
|
+
const pyproject = await readOptional$1(join(dir, "pyproject.toml"));
|
|
3249
|
+
const requirements = await readOptional$1(join(dir, "requirements.txt"));
|
|
3250
|
+
if (!((manage?.includes("django") ?? false) || /\bdjango\b/i.test(pyproject ?? "") || /\bdjango\b/i.test(requirements ?? ""))) return null;
|
|
3251
|
+
return {
|
|
3252
|
+
kind: "django",
|
|
3253
|
+
install: await exists$2(join(dir, "uv.lock")) || (pyproject?.includes("[tool.uv]") ?? false) ? "uv add coss-django" : "pip install coss-django"
|
|
3254
|
+
};
|
|
3255
|
+
}
|
|
3256
|
+
/** The mail library or framework driver in `dir`, if one is there. */
|
|
3257
|
+
async function detectProjectStack(dir, pkg) {
|
|
3258
|
+
let integration = null;
|
|
3259
|
+
if (pkg && dependsOn$1(pkg, "nodemailer")) integration = "nodemailer";
|
|
3260
|
+
else if (pkg && dependsOn$1(pkg, "better-auth")) integration = "better-auth";
|
|
3261
|
+
else if (pkg && (dependsOn$1(pkg, "next-auth") || dependsOn$1(pkg, "@auth/core"))) integration = "authjs";
|
|
3262
|
+
return {
|
|
3263
|
+
next: pkg !== null && dependsOn$1(pkg, "next"),
|
|
3264
|
+
javascript: pkg !== null,
|
|
3265
|
+
integration,
|
|
3266
|
+
driver: await detectDriver(dir)
|
|
3267
|
+
};
|
|
3268
|
+
}
|
|
3269
|
+
//#endregion
|
|
2929
3270
|
//#region src/auth/loopback.ts
|
|
2930
3271
|
/**
|
|
2931
3272
|
* The one-shot local server the dashboard redirects to after approval (RFC 8252 loopback redirect):
|
|
@@ -3217,22 +3558,12 @@ function dependsOn(pkg, name) {
|
|
|
3217
3558
|
return Boolean(pkg.dependencies?.[name] ?? pkg.devDependencies?.[name]);
|
|
3218
3559
|
}
|
|
3219
3560
|
const KEY_LINE = /^\s*(?:export\s+)?COSS_API_KEY\s*=\s*["']?([^"'\s#]*)/m;
|
|
3220
|
-
/** The env file with `name=value` set: an existing line replaced, else one appended. */
|
|
3221
|
-
function setEnvVar(text, name, value) {
|
|
3222
|
-
const line = new RegExp(`^\\s*(?:export\\s+)?${name}\\s*=.*$`, "m");
|
|
3223
|
-
if (line.test(text)) return text.replace(line, () => `${name}=${value}`);
|
|
3224
|
-
return `${text}${text === "" || text.endsWith("\n") ? "" : "\n"}${name}=${value}\n`;
|
|
3225
|
-
}
|
|
3226
|
-
/** `text` without `name`'s assignments. */
|
|
3227
|
-
function removeEnvVar(text, name) {
|
|
3228
|
-
return text.replace(new RegExp(`^[ \\t]*(?:export[ \\t]+)?${name}[ \\t]*=.*(?:\\r?\\n|$)`, "gm"), "");
|
|
3229
|
-
}
|
|
3230
3561
|
const NOTES_BEGIN = "<!-- BEGIN:coss -->";
|
|
3231
3562
|
const NOTES_END = "<!-- END:coss -->";
|
|
3232
3563
|
/**
|
|
3233
3564
|
* What a coding agent working in the project should know about coss.com, for its AGENTS.md
|
|
3234
|
-
* (`--agents`). Keep it in step with the brief that opens
|
|
3235
|
-
* (apps/site/src/lib/llms.ts).
|
|
3565
|
+
* (on by default; `--no-agents` skips them). Keep it in step with the brief that opens
|
|
3566
|
+
* https://coss.com/llms.txt (apps/site/src/lib/llms.ts).
|
|
3236
3567
|
*/
|
|
3237
3568
|
function agentNotes(envFile) {
|
|
3238
3569
|
return `${NOTES_BEGIN}
|
|
@@ -3247,11 +3578,16 @@ This project uses [coss.com](https://coss.com) (email, SMS, webhooks) through it
|
|
|
3247
3578
|
every API works and records what it would do, with events and webhooks, but nothing is
|
|
3248
3579
|
delivered. A \`coss_live_…\` key there delivers for real: don't test with it, and never switch
|
|
3249
3580
|
to one to try something (\`npx coss-cli init --force\` replaces it with a development key).
|
|
3250
|
-
- SDK methods return \`{ data, error }\` and don't throw for API failures: always check \`error
|
|
3251
|
-
Webhook handlers verify each request with
|
|
3252
|
-
|
|
3253
|
-
|
|
3254
|
-
|
|
3581
|
+
- SDK methods return \`{ data, error }\` and don't throw for API failures: always check \`error\`
|
|
3582
|
+
(and \`error.hint\`, which names the fix). Webhook handlers verify each request with
|
|
3583
|
+
\`verifyWebhook\`, which throws on a bad signature. \`npx coss-cli listen\` writes
|
|
3584
|
+
\`COSS_WEBHOOK_SECRET\` into \`${envFile}\` for that check. \`npx coss-cli webhooks add <url>\`
|
|
3585
|
+
creates an endpoint and writes that same variable (replacing a listen secret, so both sign
|
|
3586
|
+
the same way).
|
|
3587
|
+
- Commands use \`COSS_API_KEY\` from the environment. \`npx coss-cli listen --forward-to
|
|
3588
|
+
localhost:3000/<path>\` forwards webhook events to a local handler, \`npx coss-cli trigger
|
|
3589
|
+
<event type>\` sends a test event, and \`npx coss-cli logs tail\` follows the API requests and
|
|
3590
|
+
events. Send tests to \`bounce@simulator.amazonses.com\` and run \`npx coss-cli emails diagnose <id>\`.
|
|
3255
3591
|
${NOTES_END}
|
|
3256
3592
|
`;
|
|
3257
3593
|
}
|
|
@@ -3280,7 +3616,7 @@ function projectName(dir, pkg) {
|
|
|
3280
3616
|
const initCommand = defineCommand({
|
|
3281
3617
|
name: "init",
|
|
3282
3618
|
summary: "Set this project up: the SDK and a development API key",
|
|
3283
|
-
description: "Sets up the project in the current directory: installs the coss package with the project's package manager, and writes a new development (sandbox) API key to its env file as COSS_API_KEY, created in the dashboard like `coss login`'s and named after the project. It is the project's key, not the CLI's: `coss login` signs the CLI in.\n\nAn env file that already has a key keeps it, unless --force.
|
|
3619
|
+
description: "Sets up the project in the current directory: installs the coss package with the project's package manager, and writes a new development (sandbox) API key to its env file as COSS_API_KEY, created in the dashboard like `coss login`'s and named after the project. It is the project's key, not the CLI's: `coss login` signs the CLI in.\n\nAn env file that already has a key keeps it, unless --force. It also adds a short section on coss.com (docs, the development key, testing) to the project's AGENTS.md, or its CLAUDE.md when it has no AGENTS.md; running it again updates that section. --no-agents skips the notes.",
|
|
3284
3620
|
flags: {
|
|
3285
3621
|
"env-file": {
|
|
3286
3622
|
type: "string",
|
|
@@ -3297,7 +3633,11 @@ const initCommand = defineCommand({
|
|
|
3297
3633
|
},
|
|
3298
3634
|
agents: {
|
|
3299
3635
|
type: "boolean",
|
|
3300
|
-
description: "Add notes
|
|
3636
|
+
description: "Add notes for coding agents (the default; --no-agents skips them)"
|
|
3637
|
+
},
|
|
3638
|
+
"no-agents": {
|
|
3639
|
+
type: "boolean",
|
|
3640
|
+
description: "Don't add notes for coding agents to AGENTS.md"
|
|
3301
3641
|
},
|
|
3302
3642
|
"no-browser": {
|
|
3303
3643
|
type: "boolean",
|
|
@@ -3319,6 +3659,7 @@ async function init({ values, context }) {
|
|
|
3319
3659
|
const shownFile = relative(dir, envFile) || envFile;
|
|
3320
3660
|
const existingText = await readFile(envFile, "utf8").catch(() => null);
|
|
3321
3661
|
const existingKey = existingText ? KEY_LINE.exec(existingText)?.[1] ?? "" : "";
|
|
3662
|
+
let apiKey = existingKey;
|
|
3322
3663
|
const config = await readConfig(io);
|
|
3323
3664
|
const profile = config.profiles[profileName(io, config, flags.profile)] ?? null;
|
|
3324
3665
|
const baseUrl = apiBaseUrl(io, profile);
|
|
@@ -3342,6 +3683,7 @@ async function init({ values, context }) {
|
|
|
3342
3683
|
await coss.apiKey.revoke().catch(() => void 0);
|
|
3343
3684
|
throw new CliError(`${describeEnvironment(environment)} is live, so its key was revoked: \`coss init\` only writes development keys. Pick a sandbox environment.`);
|
|
3344
3685
|
}
|
|
3686
|
+
apiKey = token.api_key;
|
|
3345
3687
|
const withKey = setEnvVar(existingText ?? "", "COSS_API_KEY", token.api_key);
|
|
3346
3688
|
const text = baseUrl === "https://api.coss.com" ? removeEnvVar(withKey, "COSS_BASE_URL") : setEnvVar(withKey, "COSS_BASE_URL", baseUrl);
|
|
3347
3689
|
await mkdir(dirname(envFile), { recursive: true });
|
|
@@ -3368,42 +3710,82 @@ async function init({ values, context }) {
|
|
|
3368
3710
|
if (!out.json) out.line(`${out.style("green", "✔")} Installed the coss package.`);
|
|
3369
3711
|
}
|
|
3370
3712
|
let notesFile = null;
|
|
3371
|
-
if (values
|
|
3713
|
+
if (values["no-agents"] !== true) {
|
|
3372
3714
|
notesFile = await agentsFile(dir);
|
|
3373
3715
|
const before = await readFile(notesFile, "utf8").catch(() => "");
|
|
3374
3716
|
await writeFile(notesFile, setAgentNotes(before, agentNotes(shownFile)));
|
|
3375
3717
|
if (!out.json) out.line(`${out.style("green", "✔")} ${before.includes(NOTES_BEGIN) ? "Updated" : "Added"} the coss.com notes for coding agents in ${relative(dir, notesFile)}.`);
|
|
3376
3718
|
}
|
|
3719
|
+
const setup = await fetchSetupReport(clientFor(io, {
|
|
3720
|
+
apiKey,
|
|
3721
|
+
baseUrl
|
|
3722
|
+
}));
|
|
3723
|
+
const stack = await detectProjectStack(dir, pkg);
|
|
3724
|
+
if (setup.warning) out.warn(setup.warning);
|
|
3377
3725
|
if (out.json) {
|
|
3378
3726
|
out.data({
|
|
3379
3727
|
env_file: envFile,
|
|
3380
3728
|
key,
|
|
3381
3729
|
installed,
|
|
3382
3730
|
ignored_by_git: ignored,
|
|
3383
|
-
agents_file: notesFile
|
|
3731
|
+
agents_file: notesFile,
|
|
3732
|
+
setup
|
|
3384
3733
|
});
|
|
3385
3734
|
return 0;
|
|
3386
3735
|
}
|
|
3387
|
-
out.line(
|
|
3388
|
-
|
|
3389
|
-
|
|
3390
|
-
|
|
3736
|
+
out.line(closingMessage({
|
|
3737
|
+
stack,
|
|
3738
|
+
shownFile,
|
|
3739
|
+
setup
|
|
3740
|
+
}));
|
|
3741
|
+
return 0;
|
|
3742
|
+
}
|
|
3743
|
+
function sdkSnippetText(from, to) {
|
|
3744
|
+
return ` import { Coss } from "coss";
|
|
3391
3745
|
|
|
3392
3746
|
const coss = new Coss(); // reads COSS_API_KEY
|
|
3393
3747
|
const { data, error } = await coss.email.send({
|
|
3394
|
-
from:
|
|
3395
|
-
to:
|
|
3748
|
+
from: ${JSON.stringify(from)},
|
|
3749
|
+
to: ${JSON.stringify(to)},
|
|
3750
|
+
subject: "Hello from coss.com",
|
|
3751
|
+
text: "It works!",
|
|
3752
|
+
});`;
|
|
3753
|
+
}
|
|
3754
|
+
function nodemailerSnippet(from, to) {
|
|
3755
|
+
return ` import { cossTransport } from "coss/nodemailer";
|
|
3756
|
+
import nodemailer from "nodemailer";
|
|
3757
|
+
|
|
3758
|
+
const transport = nodemailer.createTransport(cossTransport());
|
|
3759
|
+
await transport.sendMail({
|
|
3760
|
+
from: ${JSON.stringify(from)},
|
|
3761
|
+
to: ${JSON.stringify(to)},
|
|
3396
3762
|
subject: "Hello from coss.com",
|
|
3397
3763
|
text: "It works!",
|
|
3398
|
-
})
|
|
3764
|
+
});`;
|
|
3765
|
+
}
|
|
3766
|
+
function sdkSnippet(isNext, shownFile, from, to) {
|
|
3767
|
+
return `Send an email from your server code${isNext ? " (a route handler or server action)" : ""}:
|
|
3399
3768
|
|
|
3400
|
-
|
|
3769
|
+
${sdkSnippetText(from, to)}
|
|
3401
3770
|
|
|
3402
|
-
|
|
3771
|
+
Development keys never deliver email, but every send has its events and webhooks.${isNext ? "" : `\nLoad ${shownFile} in your app, e.g. node --env-file=${shownFile} server.js.`}`;
|
|
3772
|
+
}
|
|
3773
|
+
/** The closing message: the drop-in this project already uses, then the one next step. */
|
|
3774
|
+
function closingMessage(options) {
|
|
3775
|
+
const { stack, shownFile, setup } = options;
|
|
3776
|
+
const from = setup.from ?? "hello@example.com";
|
|
3777
|
+
const parts = [];
|
|
3778
|
+
if (stack.driver) parts.push(`Install the ${stack.driver.kind} driver yourself:\n\n ${stack.driver.install}`);
|
|
3779
|
+
if (stack.integration === "nodemailer") parts.push(`Send with Nodemailer:\n\n${nodemailerSnippet(from, SIMULATOR_TO)}`);
|
|
3780
|
+
else if (stack.integration === "better-auth") parts.push("Send Better Auth's emails with `coss/better-auth` (https://coss.com/docs/integrations.md).");
|
|
3781
|
+
else if (stack.integration === "authjs") parts.push("Send Auth.js emails with `coss/authjs` (https://coss.com/docs/integrations.md).");
|
|
3782
|
+
else if (stack.javascript || !stack.driver) parts.push(sdkSnippet(stack.next, shownFile, from, SIMULATOR_TO));
|
|
3783
|
+
parts.push(setup.next);
|
|
3784
|
+
parts.push(`Next:
|
|
3403
3785
|
coss listen --forward-to localhost:3000/webhooks receive webhook events locally
|
|
3404
3786
|
coss logs tail follow the environment's log
|
|
3405
|
-
https://coss.com/docs guides and the API reference
|
|
3406
|
-
return
|
|
3787
|
+
https://coss.com/docs guides and the API reference`);
|
|
3788
|
+
return `\n${parts.join("\n\n")}`;
|
|
3407
3789
|
}
|
|
3408
3790
|
/** Whether git ignores the file: `null` outside a repository (or without git). */
|
|
3409
3791
|
async function ignoredByGit(io, dir, file) {
|
|
@@ -3420,7 +3802,7 @@ async function ignoredByGit(io, dir, file) {
|
|
|
3420
3802
|
//#endregion
|
|
3421
3803
|
//#region src/version.ts
|
|
3422
3804
|
/** The package version (`coss --version`, the forwarded requests' user agent). */
|
|
3423
|
-
const VERSION = "0.
|
|
3805
|
+
const VERSION = "0.5.0";
|
|
3424
3806
|
//#endregion
|
|
3425
3807
|
//#region src/listen/forward.ts
|
|
3426
3808
|
/** Posting an event to the local URL, as coss.com would post it to an endpoint. */
|
|
@@ -3535,12 +3917,18 @@ function report(out, forwarded, printJson) {
|
|
|
3535
3917
|
out.line(`${time} ${out.style("cyan", delivery.event_type)} ${out.style("dim", delivery.event_id)}${outcome}${retry}`);
|
|
3536
3918
|
if (printJson) out.line(toJson(JSON.parse(delivery.body), 2));
|
|
3537
3919
|
}
|
|
3538
|
-
/**
|
|
3920
|
+
/**
|
|
3921
|
+
* The signing secret for this project. An existing `COSS_WEBHOOK_SECRET` in the env file wins, so
|
|
3922
|
+
* a handler's secret is not rotated; otherwise the profile's `listen_secret`, otherwise a new one.
|
|
3923
|
+
* It is written to the env file, and to the profile when the CLI key came from the profile.
|
|
3924
|
+
*/
|
|
3539
3925
|
async function signingSecret(io, credentials) {
|
|
3540
|
-
const
|
|
3541
|
-
|
|
3542
|
-
const
|
|
3543
|
-
|
|
3926
|
+
const file = await projectEnvFile(io.cwd);
|
|
3927
|
+
const existing = file.text ? readEnvValue(file.text, "COSS_WEBHOOK_SECRET") : "";
|
|
3928
|
+
const fromProfile = credentials.profile?.listen_secret;
|
|
3929
|
+
const secret = isSecret(existing) ? existing : isSecret(fromProfile) ? fromProfile : generateSecret();
|
|
3930
|
+
const wrote = await writeEnvValue(file, "COSS_WEBHOOK_SECRET", secret);
|
|
3931
|
+
if (credentials.source === "profile" && credentials.profile?.listen_secret !== secret) {
|
|
3544
3932
|
const config = await readConfig(io);
|
|
3545
3933
|
const profile = config.profiles[credentials.profileName];
|
|
3546
3934
|
if (profile) {
|
|
@@ -3548,7 +3936,11 @@ async function signingSecret(io, credentials) {
|
|
|
3548
3936
|
await writeConfig(io, config);
|
|
3549
3937
|
}
|
|
3550
3938
|
}
|
|
3551
|
-
return
|
|
3939
|
+
return {
|
|
3940
|
+
secret,
|
|
3941
|
+
file: relative(io.cwd, file.path) || file.path,
|
|
3942
|
+
wrote
|
|
3943
|
+
};
|
|
3552
3944
|
}
|
|
3553
3945
|
async function openListener(coss, params) {
|
|
3554
3946
|
const { data, error } = await coss.webhookListeners.create({
|
|
@@ -3563,7 +3955,7 @@ async function run$1(context, values) {
|
|
|
3563
3955
|
const { io, out } = context;
|
|
3564
3956
|
const target = typeof values["forward-to"] === "string" ? normalizeTarget(values["forward-to"]) : null;
|
|
3565
3957
|
const headers = (values.header ?? []).map(parseHeader);
|
|
3566
|
-
const eventTypes = list(values.events);
|
|
3958
|
+
const eventTypes = list$1(values.events);
|
|
3567
3959
|
const credentials = await resolveCredentials(context);
|
|
3568
3960
|
const coss = clientFor(io, credentials, {
|
|
3569
3961
|
timeout: CLIENT_TIMEOUT_MS,
|
|
@@ -3573,7 +3965,7 @@ async function run$1(context, values) {
|
|
|
3573
3965
|
if (error) throw apiError("Couldn't read the environment", error);
|
|
3574
3966
|
if (environment.mode === "live" && values.live !== true) throw new CliError(`${describeEnvironment(environment)} is a live environment: you would receive its real events. Pass --live to listen anyway, or sign in to a sandbox environment.`);
|
|
3575
3967
|
if (environment.mode === "sandbox" && eventTypes.some((type) => LIVE_ONLY_PREFIXES.some((prefix) => type.startsWith(prefix)))) out.warn("account.* and billing.* events only reach live environments: you won't see them here.");
|
|
3576
|
-
const secret = await signingSecret(io, credentials);
|
|
3968
|
+
const { secret, file: secretFile, wrote: wroteSecret } = await signingSecret(io, credentials);
|
|
3577
3969
|
const listenerParams = {
|
|
3578
3970
|
eventTypes,
|
|
3579
3971
|
apiVersion: typeof values["api-version"] === "string" ? values["api-version"] : environment.organization.api_version,
|
|
@@ -3581,7 +3973,8 @@ async function run$1(context, values) {
|
|
|
3581
3973
|
};
|
|
3582
3974
|
let listener = await openListener(coss, listenerParams);
|
|
3583
3975
|
out.info(`${out.style("green", "Ready!")} Listening to ${describeEnvironment(environment)}${target ? `, forwarding to ${target}` : ""}.`);
|
|
3584
|
-
out.info(`
|
|
3976
|
+
out.info(`COSS_WEBHOOK_SECRET=${secret}`);
|
|
3977
|
+
out.info(`${wroteSecret ? "Saved" : "Using"} COSS_WEBHOOK_SECRET in ${secretFile} (API version ${listener.api_version}).`);
|
|
3585
3978
|
out.info(out.style("dim", "Press Ctrl-C to stop."));
|
|
3586
3979
|
let pending = [];
|
|
3587
3980
|
let failures = 0;
|
|
@@ -3831,13 +4224,13 @@ const logsTailCommand = defineCommand({
|
|
|
3831
4224
|
});
|
|
3832
4225
|
async function logsTail({ values, context }) {
|
|
3833
4226
|
const { io, out } = context;
|
|
3834
|
-
const sources = checked(list(values.source), SOURCES, "source");
|
|
3835
|
-
const levels = checked(list(values.level), LEVELS, "level");
|
|
4227
|
+
const sources = checked(list$1(values.source), SOURCES, "source");
|
|
4228
|
+
const levels = checked(list$1(values.level), LEVELS, "level");
|
|
3836
4229
|
const filters = {
|
|
3837
4230
|
...sources.length > 0 && { source: sources },
|
|
3838
4231
|
...levels.length > 0 && { level: levels },
|
|
3839
|
-
...values.type && { type: list(values.type) },
|
|
3840
|
-
...values.status && { status: list(values.status) },
|
|
4232
|
+
...values.type && { type: list$1(values.type) },
|
|
4233
|
+
...values.status && { status: list$1(values.status) },
|
|
3841
4234
|
...values.query && { q: values.query }
|
|
3842
4235
|
};
|
|
3843
4236
|
const intervalMs = values.interval === void 0 ? 2e3 : Number(values.interval);
|
|
@@ -5336,7 +5729,7 @@ const webhooksListCommand = defineCommand({
|
|
|
5336
5729
|
return 0;
|
|
5337
5730
|
}
|
|
5338
5731
|
if (data.data.length === 0) {
|
|
5339
|
-
out.info("No webhook endpoints.
|
|
5732
|
+
out.info("No webhook endpoints. `coss webhooks add https://…` creates one, or `coss listen` receives events here.");
|
|
5340
5733
|
return 0;
|
|
5341
5734
|
}
|
|
5342
5735
|
for (const endpoint of data.data) {
|
|
@@ -5438,6 +5831,90 @@ const webhooksRetryCommand = defineCommand({
|
|
|
5438
5831
|
return 0;
|
|
5439
5832
|
}
|
|
5440
5833
|
});
|
|
5834
|
+
const webhooksAddCommand = defineCommand({
|
|
5835
|
+
name: "webhooks add",
|
|
5836
|
+
summary: "Create an endpoint and save its signing secret",
|
|
5837
|
+
usage: "<url> [options]",
|
|
5838
|
+
description: "Creates a webhook endpoint at <url>. The signing secret is returned once and written to the project env file as COSS_WEBHOOK_SECRET, which verifyWebhook and `coss listen` both use (a previous value is replaced, so local forwarding and this endpoint sign the same way). Creation is not retried. If this URL already has an endpoint, it is left as it is unless --force.",
|
|
5839
|
+
flags: {
|
|
5840
|
+
description: {
|
|
5841
|
+
type: "string",
|
|
5842
|
+
value: "<text>",
|
|
5843
|
+
description: "A note stored on the endpoint"
|
|
5844
|
+
},
|
|
5845
|
+
events: {
|
|
5846
|
+
type: "string",
|
|
5847
|
+
multiple: true,
|
|
5848
|
+
value: "<types>",
|
|
5849
|
+
description: "Only these event types (default: every event, including later ones)"
|
|
5850
|
+
},
|
|
5851
|
+
force: {
|
|
5852
|
+
type: "boolean",
|
|
5853
|
+
description: "Create another endpoint when this URL already has one"
|
|
5854
|
+
},
|
|
5855
|
+
json: {
|
|
5856
|
+
type: "boolean",
|
|
5857
|
+
description: "Print the endpoint as JSON, including its signing secret"
|
|
5858
|
+
}
|
|
5859
|
+
},
|
|
5860
|
+
positionals: true,
|
|
5861
|
+
run: addEndpoint
|
|
5862
|
+
});
|
|
5863
|
+
async function addEndpoint({ values, positionals, context }) {
|
|
5864
|
+
const { io, out } = context;
|
|
5865
|
+
const [url] = requireArgs(positionals, 1, "webhooks add <url>");
|
|
5866
|
+
if (url === void 0 || !/^https?:\/\//i.test(url)) throw new UsageError("Pass an http(s) URL: `coss webhooks add https://example.com/webhooks`.");
|
|
5867
|
+
const events = list$1(values.events);
|
|
5868
|
+
const unknown = events.filter((type) => !WEBHOOK_EVENT_TYPES.includes(type));
|
|
5869
|
+
if (unknown.length > 0) throw new UsageError(`Unknown event type ${unknown.map((type) => `"${type}"`).join(", ")}. See https://coss.com/docs/webhooks.`);
|
|
5870
|
+
const coss = clientFor(io, await resolveCredentials(context));
|
|
5871
|
+
const listed = await coss.webhookEndpoints.list({ signal: io.signal });
|
|
5872
|
+
if (listed.error) throw apiError("Couldn't list the webhook endpoints", listed.error);
|
|
5873
|
+
const existing = listed.data.data.filter((endpoint) => endpoint.url === url);
|
|
5874
|
+
if (existing.length > 0 && values.force !== true) {
|
|
5875
|
+
if (out.json) out.data({
|
|
5876
|
+
created: false,
|
|
5877
|
+
endpoints: existing
|
|
5878
|
+
});
|
|
5879
|
+
else {
|
|
5880
|
+
const ids = existing.map((endpoint) => endpoint.id).join(", ");
|
|
5881
|
+
out.line(`${url} already has ${ids}.`);
|
|
5882
|
+
out.info("Its signing secret was shown only when it was created. Pass --force to create another endpoint.");
|
|
5883
|
+
}
|
|
5884
|
+
return 0;
|
|
5885
|
+
}
|
|
5886
|
+
const { data, error } = await coss.webhookEndpoints.create({
|
|
5887
|
+
url,
|
|
5888
|
+
...values.description ? { description: values.description } : {},
|
|
5889
|
+
...events.length > 0 ? { event_types: events } : {}
|
|
5890
|
+
}, { signal: io.signal });
|
|
5891
|
+
if (error) throw apiError("Couldn't create the webhook endpoint", error);
|
|
5892
|
+
const file = await projectEnvFile(io.cwd);
|
|
5893
|
+
const previous = file.text ? readEnvValue(file.text, "COSS_WEBHOOK_SECRET") : "";
|
|
5894
|
+
let wrote = false;
|
|
5895
|
+
try {
|
|
5896
|
+
wrote = await writeEnvValue(file, "COSS_WEBHOOK_SECRET", data.secret);
|
|
5897
|
+
} catch (cause) {
|
|
5898
|
+
out.info(`COSS_WEBHOOK_SECRET=${data.secret}`);
|
|
5899
|
+
throw new CliError(`Created ${data.id}, but couldn't save its signing secret (${cause instanceof Error ? cause.message : "write failed"}). Store the secret above; the API will not show it again.`);
|
|
5900
|
+
}
|
|
5901
|
+
const shown = relative(io.cwd, file.path) || file.path;
|
|
5902
|
+
const replaced = previous !== "" && previous !== data.secret;
|
|
5903
|
+
if (out.json) {
|
|
5904
|
+
out.data({
|
|
5905
|
+
...data,
|
|
5906
|
+
created: true,
|
|
5907
|
+
env_file: shown,
|
|
5908
|
+
replaced_existing_secret: replaced
|
|
5909
|
+
});
|
|
5910
|
+
return 0;
|
|
5911
|
+
}
|
|
5912
|
+
out.line(`${out.style("green", "✔")} ${data.id} ${data.url}`);
|
|
5913
|
+
out.info(`COSS_WEBHOOK_SECRET=${data.secret}`);
|
|
5914
|
+
const where = replaced ? `Saved COSS_WEBHOOK_SECRET in ${shown}, replacing the previous value.` : wrote ? `Saved COSS_WEBHOOK_SECRET in ${shown}.` : `COSS_WEBHOOK_SECRET in ${shown} already matches.`;
|
|
5915
|
+
out.info(`${where} coss listen signs with it too.`);
|
|
5916
|
+
return 0;
|
|
5917
|
+
}
|
|
5441
5918
|
//#endregion
|
|
5442
5919
|
//#region src/commands/whoami.ts
|
|
5443
5920
|
const whoamiCommand = defineCommand({
|
|
@@ -5578,9 +6055,11 @@ const COMMANDS = [
|
|
|
5578
6055
|
logsTailCommand,
|
|
5579
6056
|
inboxCommand,
|
|
5580
6057
|
inboxGetCommand,
|
|
6058
|
+
...INBOXES_COMMANDS,
|
|
5581
6059
|
listenCommand,
|
|
5582
6060
|
triggerCommand,
|
|
5583
6061
|
webhooksListCommand,
|
|
6062
|
+
webhooksAddCommand,
|
|
5584
6063
|
webhooksDeliveriesCommand,
|
|
5585
6064
|
webhooksRetryCommand,
|
|
5586
6065
|
...HOOKS_COMMANDS,
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "coss-cli",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.5.0",
|
|
4
4
|
"description": "The coss.com command line: sign in, send test emails and text messages, tail your environment's log, and forward webhook events to localhost with `coss listen`.",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"homepage": "https://coss.com/docs/cli",
|
|
@@ -43,7 +43,7 @@
|
|
|
43
43
|
"test": "bun test"
|
|
44
44
|
},
|
|
45
45
|
"dependencies": {
|
|
46
|
-
"coss": "^0.
|
|
46
|
+
"coss": "^0.10.0"
|
|
47
47
|
},
|
|
48
48
|
"devDependencies": {
|
|
49
49
|
"@arethetypeswrong/core": "0.18.5",
|