senddart-cli 1.0.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/LICENSE +21 -0
- package/README.md +377 -0
- package/bin/senddart.js +14 -0
- package/package.json +43 -0
- package/src/cli.js +179 -0
- package/src/commands/apikeys.js +16 -0
- package/src/commands/audiences.js +46 -0
- package/src/commands/automations.js +157 -0
- package/src/commands/campaigns.js +153 -0
- package/src/commands/contact_properties.js +49 -0
- package/src/commands/contacts.js +227 -0
- package/src/commands/domains.js +175 -0
- package/src/commands/emails.js +330 -0
- package/src/commands/events.js +63 -0
- package/src/commands/logs.js +23 -0
- package/src/commands/polls.js +19 -0
- package/src/commands/segments.js +51 -0
- package/src/commands/templates.js +96 -0
- package/src/commands/topics.js +56 -0
- package/src/commands/webhooks.js +111 -0
- package/src/helpers.js +107 -0
|
@@ -0,0 +1,96 @@
|
|
|
1
|
+
'use strict';
|
|
2
|
+
|
|
3
|
+
const { parseJson, clean, withPagination, pagination } = require('../helpers');
|
|
4
|
+
|
|
5
|
+
/**
|
|
6
|
+
* `variables` is the template's declared-variable registry, not the per-send
|
|
7
|
+
* values: a JSON array of `{"key","type"?,"fallback_value"?}` (max 50, `type`
|
|
8
|
+
* is 'string' | 'number', a number's fallback must parse as a number). The send
|
|
9
|
+
* path prefers a declared fallback when a caller omits the variable, so a
|
|
10
|
+
* template with no registry has no fallbacks — which is why this could not be
|
|
11
|
+
* left to the dashboard. Passing `[]` clears the registry.
|
|
12
|
+
*/
|
|
13
|
+
const VARIABLES_HELP =
|
|
14
|
+
'declared variables as a JSON array of {"key","type"?,"fallback_value"?} (max 50; [] clears them)';
|
|
15
|
+
|
|
16
|
+
function register({ group, leaf, act }) {
|
|
17
|
+
const templates = group('templates', 'Manage email templates');
|
|
18
|
+
|
|
19
|
+
act(
|
|
20
|
+
leaf(templates, 'create', 'Create a template')
|
|
21
|
+
.requiredOption('--name <name>', 'template name')
|
|
22
|
+
.option('--subject <subject>', 'subject line')
|
|
23
|
+
.option('--html <html>', 'HTML body')
|
|
24
|
+
.option('--text <text>', 'plain-text body')
|
|
25
|
+
.option('--from <from>', 'default sender')
|
|
26
|
+
.option('--reply-to <address>', 'default reply-to')
|
|
27
|
+
.option('--alias <alias>', 'stable handle for sending by alias')
|
|
28
|
+
.option('--variables <json>', VARIABLES_HELP),
|
|
29
|
+
({ client, opts }) =>
|
|
30
|
+
client.templates.create(
|
|
31
|
+
clean({
|
|
32
|
+
name: opts.name,
|
|
33
|
+
subject: opts.subject,
|
|
34
|
+
html: opts.html,
|
|
35
|
+
text: opts.text,
|
|
36
|
+
from: opts.from,
|
|
37
|
+
reply_to: opts.replyTo,
|
|
38
|
+
alias: opts.alias,
|
|
39
|
+
variables: parseJson(opts.variables, '--variables'),
|
|
40
|
+
}),
|
|
41
|
+
),
|
|
42
|
+
);
|
|
43
|
+
|
|
44
|
+
act(leaf(templates, 'get <id>', 'Retrieve a template'), ({ client, args: [id] }) =>
|
|
45
|
+
client.templates.get(id),
|
|
46
|
+
);
|
|
47
|
+
|
|
48
|
+
act(withPagination(leaf(templates, 'list', 'List templates')), ({ client, opts }) =>
|
|
49
|
+
client.templates.list(pagination(opts)),
|
|
50
|
+
);
|
|
51
|
+
|
|
52
|
+
act(
|
|
53
|
+
leaf(templates, 'update <id>', "Update a template's draft")
|
|
54
|
+
.option('--name <name>', 'template name')
|
|
55
|
+
.option('--subject <subject>', 'subject line')
|
|
56
|
+
.option('--html <html>', 'HTML body')
|
|
57
|
+
.option('--text <text>', 'plain-text body')
|
|
58
|
+
.option('--from <from>', 'default sender')
|
|
59
|
+
.option('--reply-to <address>', 'default reply-to')
|
|
60
|
+
.option('--alias <alias>', 'stable handle')
|
|
61
|
+
.option('--variables <json>', VARIABLES_HELP),
|
|
62
|
+
({ client, opts, args: [id] }) =>
|
|
63
|
+
client.templates.update(
|
|
64
|
+
id,
|
|
65
|
+
clean({
|
|
66
|
+
name: opts.name,
|
|
67
|
+
subject: opts.subject,
|
|
68
|
+
html: opts.html,
|
|
69
|
+
text: opts.text,
|
|
70
|
+
from: opts.from,
|
|
71
|
+
reply_to: opts.replyTo,
|
|
72
|
+
alias: opts.alias,
|
|
73
|
+
variables: parseJson(opts.variables, '--variables'),
|
|
74
|
+
}),
|
|
75
|
+
),
|
|
76
|
+
);
|
|
77
|
+
|
|
78
|
+
act(
|
|
79
|
+
leaf(templates, 'duplicate <id>', 'Duplicate a template')
|
|
80
|
+
.option('--name <name>', 'name for the copy')
|
|
81
|
+
.option('--alias <alias>', 'alias for the copy'),
|
|
82
|
+
({ client, opts, args: [id] }) =>
|
|
83
|
+
client.templates.duplicate(id, clean({ name: opts.name, alias: opts.alias })),
|
|
84
|
+
);
|
|
85
|
+
|
|
86
|
+
act(
|
|
87
|
+
leaf(templates, 'publish <id>', 'Publish a template (make its latest draft live)'),
|
|
88
|
+
({ client, args: [id] }) => client.templates.publish(id),
|
|
89
|
+
);
|
|
90
|
+
|
|
91
|
+
act(leaf(templates, 'delete <id>', 'Delete a template'), ({ client, args: [id] }) =>
|
|
92
|
+
client.templates.remove(id),
|
|
93
|
+
);
|
|
94
|
+
}
|
|
95
|
+
|
|
96
|
+
module.exports = { register };
|
|
@@ -0,0 +1,56 @@
|
|
|
1
|
+
'use strict';
|
|
2
|
+
|
|
3
|
+
const { clean, withPagination, pagination } = require('../helpers');
|
|
4
|
+
|
|
5
|
+
function register({ group, leaf, act }) {
|
|
6
|
+
const topics = group('topics', 'Manage subscription topics (scoped to a sending domain)');
|
|
7
|
+
|
|
8
|
+
act(
|
|
9
|
+
leaf(topics, 'create', 'Create a topic on a sending domain')
|
|
10
|
+
.requiredOption('--domain <domain>', 'the sending domain this topic belongs to')
|
|
11
|
+
.requiredOption('--name <name>', 'topic name')
|
|
12
|
+
.option('--default-subscription <mode>', "'opt_in' | 'opt_out' (default: opt_in)", 'opt_in')
|
|
13
|
+
.option('--visibility <visibility>', "'public' | 'private'")
|
|
14
|
+
.option('--description <text>', 'topic description'),
|
|
15
|
+
({ client, opts }) =>
|
|
16
|
+
client.topics.create(
|
|
17
|
+
clean({
|
|
18
|
+
domain: opts.domain,
|
|
19
|
+
name: opts.name,
|
|
20
|
+
default_subscription: opts.defaultSubscription,
|
|
21
|
+
visibility: opts.visibility,
|
|
22
|
+
description: opts.description,
|
|
23
|
+
}),
|
|
24
|
+
),
|
|
25
|
+
);
|
|
26
|
+
|
|
27
|
+
act(
|
|
28
|
+
withPagination(
|
|
29
|
+
leaf(topics, 'list', "List a domain's topics").requiredOption(
|
|
30
|
+
'--domain <domain>',
|
|
31
|
+
'the sending domain whose topics to list',
|
|
32
|
+
),
|
|
33
|
+
),
|
|
34
|
+
({ client, opts }) => client.topics.list({ domain: opts.domain, ...pagination(opts) }),
|
|
35
|
+
);
|
|
36
|
+
|
|
37
|
+
act(leaf(topics, 'get <id>', 'Retrieve a topic'), ({ client, args: [id] }) => client.topics.get(id));
|
|
38
|
+
|
|
39
|
+
act(
|
|
40
|
+
leaf(topics, 'update <id>', 'Update a topic')
|
|
41
|
+
.option('--name <name>', 'new name')
|
|
42
|
+
.option('--description <text>', 'new description')
|
|
43
|
+
.option('--visibility <visibility>', "'public' | 'private'"),
|
|
44
|
+
({ client, opts, args: [id] }) =>
|
|
45
|
+
client.topics.update(
|
|
46
|
+
id,
|
|
47
|
+
clean({ name: opts.name, description: opts.description, visibility: opts.visibility }),
|
|
48
|
+
),
|
|
49
|
+
);
|
|
50
|
+
|
|
51
|
+
act(leaf(topics, 'delete <id>', 'Delete a topic'), ({ client, args: [id] }) =>
|
|
52
|
+
client.topics.remove(id),
|
|
53
|
+
);
|
|
54
|
+
}
|
|
55
|
+
|
|
56
|
+
module.exports = { register };
|
|
@@ -0,0 +1,111 @@
|
|
|
1
|
+
'use strict';
|
|
2
|
+
|
|
3
|
+
const fs = require('node:fs');
|
|
4
|
+
const { CliError, collect, clean, toInt, withPagination, pagination } = require('../helpers');
|
|
5
|
+
|
|
6
|
+
function register({ group, leaf, act }) {
|
|
7
|
+
const webhooks = group('webhooks', 'Manage webhooks');
|
|
8
|
+
|
|
9
|
+
act(
|
|
10
|
+
leaf(webhooks, 'create', 'Create a webhook (the signing secret is shown once)')
|
|
11
|
+
.requiredOption('--endpoint <url>', 'the HTTPS endpoint to deliver events to')
|
|
12
|
+
.requiredOption(
|
|
13
|
+
'--events <event>',
|
|
14
|
+
"events to subscribe to (repeatable or comma-separated), e.g. 'email.delivered,email.bounced'",
|
|
15
|
+
collect,
|
|
16
|
+
)
|
|
17
|
+
.option('--secret <secret>', 'caller-supplied signing secret (otherwise generated)'),
|
|
18
|
+
({ client, opts }) =>
|
|
19
|
+
client.webhooks.create(clean({ endpoint: opts.endpoint, events: opts.events, secret: opts.secret })),
|
|
20
|
+
);
|
|
21
|
+
|
|
22
|
+
act(leaf(webhooks, 'get <id>', 'Retrieve a webhook'), ({ client, args: [id] }) =>
|
|
23
|
+
client.webhooks.get(id),
|
|
24
|
+
);
|
|
25
|
+
|
|
26
|
+
act(withPagination(leaf(webhooks, 'list', 'List webhooks')), ({ client, opts }) =>
|
|
27
|
+
client.webhooks.list(pagination(opts)),
|
|
28
|
+
);
|
|
29
|
+
|
|
30
|
+
act(
|
|
31
|
+
leaf(webhooks, 'update <id>', 'Update a webhook')
|
|
32
|
+
.option('--endpoint <url>', 'new endpoint URL')
|
|
33
|
+
.option('--events <event>', 'new event list (repeatable or comma-separated)', collect)
|
|
34
|
+
.option('--status <status>', "'enabled' | 'disabled'"),
|
|
35
|
+
({ client, opts, args: [id] }) =>
|
|
36
|
+
client.webhooks.update(
|
|
37
|
+
id,
|
|
38
|
+
clean({ endpoint: opts.endpoint, events: opts.events, status: opts.status }),
|
|
39
|
+
),
|
|
40
|
+
);
|
|
41
|
+
|
|
42
|
+
act(
|
|
43
|
+
leaf(webhooks, 'rotate <id>', 'Rotate the signing secret (new secret shown once)'),
|
|
44
|
+
({ client, args: [id] }) => client.webhooks.rotate(id),
|
|
45
|
+
);
|
|
46
|
+
|
|
47
|
+
// The API answers 200 even when the delivery failed — the outcome lives in
|
|
48
|
+
// `ok`. Print the body either way, but exit 1 on a failed delivery so the
|
|
49
|
+
// command is usable in a shell `&&` chain.
|
|
50
|
+
act(
|
|
51
|
+
leaf(webhooks, 'test <id>', 'Send a synchronous test delivery (exits 1 when ok is false)'),
|
|
52
|
+
async ({ client, args: [id] }) => {
|
|
53
|
+
const result = await client.webhooks.test(id);
|
|
54
|
+
if (result.error) return result;
|
|
55
|
+
return { data: result.data, failed: !!result.data && result.data.ok === false };
|
|
56
|
+
},
|
|
57
|
+
);
|
|
58
|
+
|
|
59
|
+
act(leaf(webhooks, 'delete <id>', 'Delete a webhook'), ({ client, args: [id] }) =>
|
|
60
|
+
client.webhooks.remove(id),
|
|
61
|
+
);
|
|
62
|
+
|
|
63
|
+
// Verify a delivery's signature LOCALLY — pure computation, no HTTP request (SDK-4).
|
|
64
|
+
//
|
|
65
|
+
// Registered with `local: true`, so no SDK client (and therefore no API key)
|
|
66
|
+
// is resolved: this command never reaches the network, and demanding
|
|
67
|
+
// SENDDART_API_KEY for it pushed people into putting a send-capable key on
|
|
68
|
+
// the very webhook receiver whose job is to distrust its input.
|
|
69
|
+
act(
|
|
70
|
+
leaf(webhooks, 'verify', 'Verify a webhook delivery signature locally (no HTTP request, no API key)', { local: true })
|
|
71
|
+
.requiredOption('--secret <secret>', 'the endpoint signing secret')
|
|
72
|
+
.option('--payload <raw>', 'the raw request body string (exact bytes the server sent)')
|
|
73
|
+
.option('--payload-file <path>', 'path to a file containing the raw request body')
|
|
74
|
+
.requiredOption('--svix-id <id>', 'the svix-id header')
|
|
75
|
+
.requiredOption('--svix-timestamp <ts>', 'the svix-timestamp header')
|
|
76
|
+
.requiredOption('--svix-signature <sig>', 'the svix-signature header')
|
|
77
|
+
.option('--tolerance <seconds>', 'max timestamp skew in seconds (default 300; 0 = skip the freshness check)'),
|
|
78
|
+
({ ctx, opts }) => {
|
|
79
|
+
if (opts.payload && opts.payloadFile) throw new CliError('Provide only one of --payload or --payload-file.');
|
|
80
|
+
let payload;
|
|
81
|
+
if (opts.payloadFile) {
|
|
82
|
+
try { payload = fs.readFileSync(opts.payloadFile, 'utf8'); }
|
|
83
|
+
catch (err) { throw new CliError(`Cannot read --payload-file ${opts.payloadFile}: ${err.message}`); }
|
|
84
|
+
} else if (opts.payload != null) {
|
|
85
|
+
payload = opts.payload;
|
|
86
|
+
} else {
|
|
87
|
+
throw new CliError('Provide --payload <raw> or --payload-file <path>.');
|
|
88
|
+
}
|
|
89
|
+
const headers = {
|
|
90
|
+
'svix-id': opts.svixId,
|
|
91
|
+
'svix-timestamp': opts.svixTimestamp,
|
|
92
|
+
'svix-signature': opts.svixSignature,
|
|
93
|
+
};
|
|
94
|
+
const options = {};
|
|
95
|
+
if (opts.tolerance != null) {
|
|
96
|
+
// Parsed, not coerced. `Number('5m')` is NaN, and the SDK's freshness
|
|
97
|
+
// gate is `if (toleranceSec > 0)` — which NaN fails — so a typo'd
|
|
98
|
+
// tolerance used to SKIP the replay-window check silently and report a
|
|
99
|
+
// stale delivery as valid. A bad value is a usage error instead.
|
|
100
|
+
const tolerance = toInt(opts.tolerance, '--tolerance');
|
|
101
|
+
if (tolerance < 0) throw new CliError('--tolerance must be 0 or greater.');
|
|
102
|
+
options.toleranceSec = tolerance;
|
|
103
|
+
}
|
|
104
|
+
// A pure, synchronous local computation returning { valid, reason }.
|
|
105
|
+
// Wrapped in the {data,error} shape the CLI runner prints.
|
|
106
|
+
return { data: ctx.verifyWebhook(payload, headers, opts.secret, options), error: null };
|
|
107
|
+
},
|
|
108
|
+
);
|
|
109
|
+
}
|
|
110
|
+
|
|
111
|
+
module.exports = { register };
|
package/src/helpers.js
ADDED
|
@@ -0,0 +1,107 @@
|
|
|
1
|
+
'use strict';
|
|
2
|
+
|
|
3
|
+
const fs = require('node:fs');
|
|
4
|
+
const path = require('node:path');
|
|
5
|
+
|
|
6
|
+
/** Error whose message is reported as a CLI usage error (exit 1, no stack). */
|
|
7
|
+
class CliError extends Error {}
|
|
8
|
+
|
|
9
|
+
/**
|
|
10
|
+
* Commander collector for repeatable flags. Each occurrence may itself be
|
|
11
|
+
* comma-separated: `--to a@b.com --to c@d.com,e@f.com` → [a@b.com, c@d.com, e@f.com].
|
|
12
|
+
*/
|
|
13
|
+
function collect(value, previous) {
|
|
14
|
+
return (previous || []).concat(
|
|
15
|
+
String(value)
|
|
16
|
+
.split(',')
|
|
17
|
+
.map((s) => s.trim())
|
|
18
|
+
.filter(Boolean),
|
|
19
|
+
);
|
|
20
|
+
}
|
|
21
|
+
|
|
22
|
+
/**
|
|
23
|
+
* Commander collector for repeatable flags whose values must stay verbatim
|
|
24
|
+
* (file paths, URLs) — unlike `collect`, it never splits on commas.
|
|
25
|
+
*/
|
|
26
|
+
function append(value, previous) {
|
|
27
|
+
return (previous || []).concat(value);
|
|
28
|
+
}
|
|
29
|
+
|
|
30
|
+
/** Parse a JSON-valued flag, failing with a friendly message. */
|
|
31
|
+
function parseJson(value, flagName) {
|
|
32
|
+
if (value === undefined) return undefined;
|
|
33
|
+
try {
|
|
34
|
+
return JSON.parse(value);
|
|
35
|
+
} catch {
|
|
36
|
+
throw new CliError(`Invalid JSON for ${flagName}: ${value}`);
|
|
37
|
+
}
|
|
38
|
+
}
|
|
39
|
+
|
|
40
|
+
/** Parse an integer-valued flag. */
|
|
41
|
+
function toInt(value, flagName) {
|
|
42
|
+
if (value === undefined) return undefined;
|
|
43
|
+
const n = Number(value);
|
|
44
|
+
if (!Number.isInteger(n)) throw new CliError(`${flagName} must be an integer, got: ${value}`);
|
|
45
|
+
return n;
|
|
46
|
+
}
|
|
47
|
+
|
|
48
|
+
/** Drop undefined values so we only send what the user set. */
|
|
49
|
+
function clean(obj) {
|
|
50
|
+
const out = {};
|
|
51
|
+
for (const [k, v] of Object.entries(obj)) {
|
|
52
|
+
if (v !== undefined) out[k] = v;
|
|
53
|
+
}
|
|
54
|
+
return out;
|
|
55
|
+
}
|
|
56
|
+
|
|
57
|
+
/**
|
|
58
|
+
* Add the standard cursor-pagination flags to a list command. The API accepts
|
|
59
|
+
* an integer 1-100 and rejects `--after` together with `--before`.
|
|
60
|
+
*
|
|
61
|
+
* Omitting `--limit` does NOT mean "20 everywhere" and never means "everything":
|
|
62
|
+
* lib/api/pagination.ts applies its 20 default only to the `forceLimit` list
|
|
63
|
+
* routes, while the rest fall back to UNPAGINATED_MAX (1,000) — and both set
|
|
64
|
+
* `has_more` truthfully when the page was truncated. The old help text said
|
|
65
|
+
* "default 20" flatly, which understated ~1,000-row first pages on
|
|
66
|
+
* domains/contacts/segments/topics/campaigns/polls/api-keys/contact-properties
|
|
67
|
+
* and their friends. Page with `--after` and trust `has_more`, not a number.
|
|
68
|
+
*/
|
|
69
|
+
function withPagination(cmd) {
|
|
70
|
+
return cmd
|
|
71
|
+
.option('--limit <n>', 'max results per page (integer 1-100). Omitted: the endpoint default (20 on most lists, up to 1000 on the rest) — keep paging while has_more is true')
|
|
72
|
+
.option('--after <cursor>', 'cursor: the id of the last item on the previous page')
|
|
73
|
+
.option('--before <cursor>', 'cursor: the id of the first item on the next page');
|
|
74
|
+
}
|
|
75
|
+
|
|
76
|
+
/**
|
|
77
|
+
* Build the SDK pagination params object from parsed options. `after` and
|
|
78
|
+
* `before` are mutually exclusive (the API answers 422); catch that locally so
|
|
79
|
+
* the user gets a usage error instead of a round-trip.
|
|
80
|
+
*/
|
|
81
|
+
function pagination(opts) {
|
|
82
|
+
if (opts.after !== undefined && opts.before !== undefined) {
|
|
83
|
+
throw new CliError('Use either --after or --before, not both.');
|
|
84
|
+
}
|
|
85
|
+
return clean({
|
|
86
|
+
limit: toInt(opts.limit, '--limit'),
|
|
87
|
+
after: opts.after,
|
|
88
|
+
before: opts.before,
|
|
89
|
+
});
|
|
90
|
+
}
|
|
91
|
+
|
|
92
|
+
/**
|
|
93
|
+
* Write a non-JSON API payload to disk and return the printable `{ data }`
|
|
94
|
+
* summary the command layer expects. A few endpoints answer with bytes
|
|
95
|
+
* (attachments, raw RFC822) or text (a domain's records.csv) rather than JSON,
|
|
96
|
+
* so the file is saved and stdout keeps its JSON-only contract.
|
|
97
|
+
*/
|
|
98
|
+
function saveFile(filePath, contents) {
|
|
99
|
+
const abs = path.resolve(filePath);
|
|
100
|
+
const buf = typeof contents === 'string' ? Buffer.from(contents, 'utf8') : Buffer.from(contents);
|
|
101
|
+
fs.writeFileSync(abs, buf);
|
|
102
|
+
return { data: { object: 'file', path: abs, bytes: buf.length } };
|
|
103
|
+
}
|
|
104
|
+
|
|
105
|
+
module.exports = {
|
|
106
|
+
CliError, collect, append, parseJson, toInt, clean, withPagination, pagination, saveFile,
|
|
107
|
+
};
|