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 ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 SendDart
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md ADDED
@@ -0,0 +1,377 @@
1
+ # senddart-cli
2
+
3
+ Official command-line interface for the [SendDart](https://www.senddart.com) email API. Wraps the [`senddart`](https://www.npmjs.com/package/senddart) Node.js SDK.
4
+
5
+ ## Install
6
+
7
+ ```bash
8
+ npm i -g senddart-cli
9
+ ```
10
+
11
+ Requires Node.js 18+.
12
+
13
+ ## Authentication
14
+
15
+ Set your API key once:
16
+
17
+ ```bash
18
+ export SENDDART_API_KEY=mb_xxxxxxxxx
19
+ ```
20
+
21
+ Or pass `--api-key mb_xxxxxxxxx` to any command. Use `SENDDART_BASE_URL` (or `--base-url`) to target a different API host.
22
+
23
+ ## Output
24
+
25
+ Every command prints the API response as pretty-printed JSON. Pass `--json` for raw compact JSON (handy for piping to `jq`). On failure a JSON error object is printed to **stderr** and the command exits `1`; stdout stays JSON-only either way, so `senddart … | jq` never has to strip a diagnostic.
26
+
27
+ The error object is always `{ statusCode, name, message }` — branch on `name`, never on `message`:
28
+
29
+ | Where it came from | `statusCode` | `name` |
30
+ |---|---|---|
31
+ | The API rejected the request | the HTTP status | the API's reason, e.g. `validation_error`, `daily_quota_exceeded` |
32
+ | The request never reached the API | `0` | `network_error` |
33
+ | The CLI rejected your flags before sending | `null` | `cli_error` |
34
+
35
+ Some API errors are a superset of that envelope and the extra fields are printed too: `limit` on plan/quota rejections, `reputation` on a reputation gate, and `sent`/`sent_count` on a partially applied `emails batch`.
36
+
37
+ One endpoint reports failure inside a `200` body rather than as an error: `webhooks test` returns `{ ok: false, error }` when the delivery did not land. The CLI prints that body to stdout and still exits `1`, so `senddart webhooks test wh_123 && deploy` behaves as you would expect.
38
+
39
+ `--help` works at every level: `senddart --help`, `senddart emails --help`, `senddart emails send --help`.
40
+
41
+ ### Pagination
42
+
43
+ List commands take `--limit` (integer `1`–`100`, default `20`) plus one of `--after` / `--before` — cursors are item ids, and passing both is rejected. Responses are `{ "object": "list", "has_more": bool, "data": [...] }`; page forward by feeding the last `data[].id` back as `--after`.
44
+
45
+ Two default page sizes exist. `domains list`, `api-keys list`, `topics list`, `contacts list`, `contacts segments`, `contacts topics`, `segments list`, `segments contacts`, `campaigns list`, `contact-properties list`, `polls list`, `emails receiving list` and `emails receiving attachments` skip the default `20` when you pass no pagination flag — but they do **not** return the whole collection: the response is capped at **1,000** rows, and `has_more` is `true` when that cap truncated it, so keep paging with `--after`. Everything else caps at 20 unless you raise `--limit`: `emails list`, `templates list`, `webhooks list`, `audiences list`, `automations list`, `automations runs`, `events list` and `logs list`.
46
+
47
+ A few endpoints are deliberately unpaginated and take no cursor flags — `emails sources`, `emails attachments`, `emails receiving addresses` and `campaigns engagement` (whose three lists are each capped at 500 rows server-side).
48
+
49
+ ## Usage
50
+
51
+ ### Emails
52
+
53
+ ```bash
54
+ senddart emails send --from 'Acme <hi@yourdomain.com>' --to 'delivered@test.senddart.com' --subject 'hello' --html '<p>hi</p>'
55
+ senddart emails send --to 'ada@yourdomain.com,rae@yourdomain.com' \
56
+ --template-id tmpl_welcome --variables '{"first_name":"Ada"}' --scheduled-at 2026-08-01T09:00:00Z
57
+ senddart emails list --limit 20
58
+ senddart emails list --status delivered --search 'invoice'
59
+ senddart emails list --folder scheduled # mailbox folder: outbox | sent | scheduled | failed (anything else is a 422)
60
+ senddart emails sources # per-source metrics: one row per campaign/automation + api and individual one-off roll-ups
61
+ senddart emails get em_123
62
+ senddart emails update em_123 --scheduled-at 2026-08-02T09:00:00Z
63
+ senddart emails cancel em_123
64
+ senddart emails attachments em_123
65
+ senddart emails attachment em_123 att_456
66
+ ```
67
+
68
+ `--to`, `--cc`, `--bcc` and `--reply-to` are repeatable and accept comma-separated values.
69
+
70
+ `--from` and `--subject` are required for an ordinary send but **optional** with `--template-id` / `--template-alias`, as the two template examples in this section show: omit them and the template's own stored from and subject are used. Supply them and your values win for good — the flags are sent verbatim, so editing and republishing the template stops changing the from and subject that command sends. The body still re-renders from the template on every send; only those two fields stop tracking it. An empty value is a choice rather than an omission: `--subject ''` ships a blank subject line, and `--from ''` is rejected with `422 missing_required_field`.
71
+
72
+ `delivered@test.senddart.com` above is the mailbox simulator: it is intercepted before the provider is contacted and synthesizes the documented outcome (`bounced@`, `complained@` and `suppressed@` produce the other three; `delivered@`, `bounced@` and `complained@` also accept a `+label` suffix, `suppressed@` does not). Two things to know when you script against it — it only fires on an **immediate** send, so pairing it with a future `--scheduled-at` skips the simulator and the address is treated as suppressed (`422`); and quota is debited per recipient exactly like a real send. Documentation domains (`example.com`, `example.net`, `example.org`, anything under `.test` / `.invalid` / `.localhost` / `.example`) are blocked outright and never reach a mailbox, so do not use them as stand-in recipients.
73
+
74
+ Attach files with `--attachment <path>` (read and base64-encoded locally) or `--attachment-url <url>` (fetched server-side). Both are repeatable; the API caps an attachment at 25 MB and a message at 40 MB decoded, and the CLI checks local files against those limits before sending.
75
+
76
+ ```bash
77
+ senddart emails send --from hi@yourdomain.com --to delivered@test.senddart.com --subject 'Your invoice' \
78
+ --text 'Attached.' --attachment ./invoice.pdf
79
+ senddart emails send --to delivered@test.senddart.com \
80
+ --template-alias welcome --variables '{"first_name":"Ada"}'
81
+ ```
82
+
83
+ `--idempotency-key` accepts **1–255 characters**, measured after the server trims the value — 255, not 256 — and is honoured by `emails send`, `emails batch`, `emails receiving reply`, and `emails receiving forward`. The CLI sends the key verbatim and lets the server be the authority: an out-of-range key comes back as `400 invalid_idempotency_key`. Reusing a key with a different body is rejected (`409 invalid_idempotent_request`); replaying it with the same body returns the original response instead of sending twice. Every other command ignores the header, so a retry there creates a second resource.
84
+
85
+ Batch-send up to 100 emails in one request from a JSON file (an array of send payloads) or inline JSON:
86
+
87
+ ```bash
88
+ senddart emails batch --file ./batch.json
89
+ senddart emails batch --data '[{"from":"hi@yourdomain.com","to":["delivered@test.senddart.com"],"subject":"hi","text":"hello"}]'
90
+ ```
91
+
92
+ ### Received (inbound) email
93
+
94
+ ```bash
95
+ senddart emails receiving list --limit 20
96
+ senddart emails receiving addresses # per-address inbound stats
97
+ senddart emails receiving get rem_123
98
+ senddart emails receiving attachments rem_123
99
+ senddart emails receiving attachment rem_123 att_456 --output invoice.pdf # default filename: the attachment id
100
+ senddart emails receiving raw rem_123 --output message.eml # default filename: <id>.eml
101
+ senddart emails receiving forward rem_123 --from you@yourdomain.com --to delivered@test.senddart.com
102
+ senddart emails receiving reply rem_123 --from you@yourdomain.com --html '<p>thanks!</p>'
103
+ senddart emails receiving delete rem_123
104
+ ```
105
+
106
+ `attachment` and `raw` download binary content: the file is written to `--output` (or the default filename) and the CLI prints where it was saved. `reply` requires at least one of `--html` / `--text`.
107
+
108
+ ### Domains
109
+
110
+ ```bash
111
+ senddart domains add yourdomain.com
112
+ senddart domains list
113
+ senddart domains get dom_123
114
+ senddart domains verify dom_123
115
+ senddart domains update dom_123 --click-tracking --tls enforced
116
+ senddart domains update dom_123 --custom-return-path mail --receiving
117
+ senddart domains mx-check yourdomain.com
118
+ senddart domains records-csv dom_123 --output dns.csv # default filename: <id>-dns-records.csv
119
+ senddart domains delete dom_123
120
+ ```
121
+
122
+ `records-csv` answers `text/csv`, not JSON, so the CLI writes it to `--output` (or the default filename) and prints where it landed — the same shape as the `emails receiving` binary downloads.
123
+
124
+ One-click DNS — detect the provider, then apply the records via its API (auto-verifies after):
125
+
126
+ ```bash
127
+ senddart domains dns detect dom_123
128
+ senddart domains dns cloudflare dom_123 --token cf_api_token
129
+ senddart domains dns godaddy dom_123 --key gd_key --secret gd_secret
130
+ senddart domains dns namecheap dom_123 --api-user ncuser --key nc_api_key
131
+ ```
132
+
133
+ Claim a domain already verified by another account (start the claim, add the TXT record it returns, then verify):
134
+
135
+ ```bash
136
+ senddart domains claim start yourdomain.com
137
+ senddart domains claim get dom_123
138
+ senddart domains claim verify dom_123
139
+ ```
140
+
141
+ ### Contacts (domain-first)
142
+
143
+ Each sending domain has its own contact pool, so `contacts create` and `contacts list` need to be told which container to use — exactly one of `--domain <domain>` or `--audience-id <id>`; passing neither, or both, is a usage error:
144
+
145
+ ```bash
146
+ senddart contacts create --domain yourdomain.com --email ada@yourdomain.com --first-name Ada
147
+ senddart contacts list --domain yourdomain.com
148
+ senddart contacts list --domain yourdomain.com --segment-id seg_123
149
+ senddart contacts list --audience-id aud_123 # plain audiences instead of a domain pool
150
+ senddart contacts get ada@yourdomain.com --domain yourdomain.com # or by contact id, no --domain needed
151
+ senddart contacts update con_123 --unsubscribed
152
+ senddart contacts add-to-segment con_123 seg_123
153
+ senddart contacts remove-from-segment con_123 seg_123
154
+ senddart contacts topics con_123
155
+ senddart contacts set-topics con_123 --topics '[{"id":"top_123","subscription":"opt_out"}]'
156
+ senddart contacts delete con_123
157
+ ```
158
+
159
+ Bulk-import a CSV. Files up to 5 MB / 10,000 rows go inline with `--csv`; anything larger is uploaded directly to storage first — mint a presigned URL, `PUT` the file to it, then finish the import with the `storage_key` it returned:
160
+
161
+ ```bash
162
+ senddart contacts import aud_123 --csv ./contacts.csv --segment-id seg_123
163
+ senddart contacts import-upload aud_123 --csv ./big-list.csv # → { storage_key, upload_url, max_bytes, ... }
164
+ curl -X PUT --upload-file ./big-list.csv "$UPLOAD_URL"
165
+ senddart contacts import aud_123 --storage-key "$STORAGE_KEY"
166
+ ```
167
+
168
+ `import` takes exactly one of `--csv` / `--storage-key`. The `upload_url` is a short-lived bearer credential — don't log it or paste it into a shared shell history.
169
+
170
+ When the source is already structured, `contacts batch` imports a JSON array instead of a CSV (upsert by email, max 10,000 per call, exactly one of `--file` / `--data`):
171
+
172
+ ```bash
173
+ senddart contacts batch aud_123 --file ./contacts.json # audience as the positional…
174
+ senddart contacts batch --audience-id aud_123 --file ./contacts.json # …or as the flag, like every other contacts command
175
+ senddart contacts batch aud_123 --data '[{"email":"ada@yourdomain.com","first_name":"Ada"}]' --on-conflict skip
176
+ # Domain-first: import straight into a domain's pool, no audience id needed.
177
+ senddart contacts batch --domain yourdomain.com --file ./contacts.json
178
+ ```
179
+
180
+ ### Contact properties & audiences
181
+
182
+ ```bash
183
+ senddart contact-properties create --key company --type string --fallback-value 'your company'
184
+ senddart contact-properties list
185
+ senddart contact-properties update prop_123 --fallback-value 'n/a'
186
+ senddart contact-properties update prop_123 --clear-fallback
187
+ senddart contact-properties delete prop_123
188
+
189
+ senddart audiences create --name Newsletter
190
+ senddart audiences list
191
+ senddart audiences update aud_123 --name 'Newsletter EU'
192
+ senddart audiences import-sheet aud_123 --url 'https://docs.google.com/spreadsheets/d/...' --segment-name 'July leads'
193
+ senddart audiences delete aud_123
194
+ ```
195
+
196
+ ### Segments & topics
197
+
198
+ ```bash
199
+ senddart segments create --domain yourdomain.com --name VIP
200
+ senddart segments create --domain yourdomain.com --name Actives --filter '{"status":"subscribed"}'
201
+ senddart segments list --domain yourdomain.com
202
+ senddart segments contacts seg_123
203
+
204
+ senddart topics create --domain yourdomain.com --name 'Product updates' --default-subscription opt_in
205
+ senddart topics list --domain yourdomain.com
206
+ ```
207
+
208
+ ### Campaigns
209
+
210
+ ```bash
211
+ senddart campaigns create --domain yourdomain.com --from 'Acme <hi@yourdomain.com>' \
212
+ --subject 'Summer sale' --html '<p>50% off</p>' --segment-id seg_123
213
+ senddart campaigns create --domain yourdomain.com --from 'Acme <hi@yourdomain.com>' \
214
+ --subject 'Weekly digest' --html '<p>...</p>' --recurrence weekly --unsubscribe-policy domain \
215
+ --followups '[{"condition":"not_opened","delay":"2 days","html":"<p>Did you see this?</p>"}]'
216
+ senddart campaigns send camp_123
217
+ senddart campaigns send camp_123 --scheduled-at 2026-08-01T09:00:00Z
218
+ senddart campaigns send camp_123 --scheduled-at 'in 1 min'
219
+ senddart campaigns stats camp_123
220
+ senddart campaigns engagement camp_123 # who opened, clicked and replied (each list capped at 500 rows)
221
+ senddart campaigns ab camp_123
222
+ senddart campaigns cancel camp_123
223
+ ```
224
+
225
+ ### Templates
226
+
227
+ ```bash
228
+ senddart templates create --name Welcome --subject 'Hi {{first_name}}' --html '<p>Welcome!</p>'
229
+ senddart templates list
230
+ senddart templates duplicate tmpl_123 --name 'Welcome v2'
231
+ senddart templates publish tmpl_123
232
+
233
+ # Declare the variables the template uses, with their types and fallbacks
234
+ senddart templates update tmpl_123 \
235
+ --variables '[{"key":"first_name","type":"string","fallback_value":"there"},{"key":"seats","type":"number","fallback_value":1}]'
236
+ ```
237
+
238
+ `--variables` is the template's declared-variable registry, not the per-send values: a JSON array of `{"key","type"?,"fallback_value"?}` (max 50 entries; `type` is `string` or `number`, and a `number` fallback must parse as a number). A send prefers a declared fallback when the caller omits that variable, so a template with no registry has no fallbacks. Pass `[]` to clear it. Edits land on the draft — `templates publish` makes them live.
239
+
240
+ ### Automations & events
241
+
242
+ ```bash
243
+ senddart automations create --name 'Welcome series' --domain yourdomain.com --trigger contact.created
244
+ senddart automations add-step auto_123 --type send_email --config '{"template_id":"tmpl_welcome"}'
245
+ senddart automations update-step auto_123 step_456 --type wait_for_event --config '{"event":"email.opened","timeout":"12 hours"}'
246
+ senddart automations delete-step auto_123 step_456
247
+ senddart automations update auto_123 --status enabled
248
+
249
+ # update-step replaces the step outright, so --type is required and --config is
250
+ # the complete new config. A step's graph key is immutable — delete and re-add
251
+ # with `add-step --key` to re-key it.
252
+ senddart automations runs auto_123
253
+ senddart automations runs auto_123 --status failed,skipped # filtered before paging; repeatable
254
+ senddart automations run auto_123 run_456
255
+ senddart automations stop auto_123
256
+
257
+ # Author (or extend) the step graph from a prompt — the automation must be stopped, and this spends AI credits
258
+ senddart automations ai auto_123 --prompt 'Welcome new signups, then nudge anyone who has not opened after 2 days'
259
+ senddart automations ai auto_123 --prompt 'Send the upgrade nudge' --attach-from step_3 --attach-type condition_met
260
+
261
+ # Fire a custom event — only yourdomain.com's automations are triggered
262
+ senddart events send --domain yourdomain.com --name signup.completed --email ada@yourdomain.com --data '{"plan":"pro"}'
263
+ senddart events list
264
+ senddart events create --name signup.completed --schema '{"plan":"string"}'
265
+ senddart events update evt_123 --schema '{"plan":"string","seats":"number"}' # the name is immutable
266
+ ```
267
+
268
+ ### Webhooks, API keys, logs, polls
269
+
270
+ ```bash
271
+ senddart webhooks create --endpoint https://yourapp.com/hooks --events email.delivered,email.bounced
272
+ senddart webhooks rotate wh_123
273
+ senddart webhooks test wh_123
274
+ senddart webhooks verify --secret whsec_xxx --payload-file ./delivery.json \
275
+ --svix-id msg_123 --svix-timestamp 1754000000 --svix-signature 'v1,base64sig'
276
+
277
+ senddart api-keys list
278
+
279
+ senddart logs list --limit 100 --method POST --status 429
280
+ senddart logs get log_123
281
+
282
+ senddart polls list
283
+ senddart polls get em_123
284
+ ```
285
+
286
+ `webhooks verify` is the only command that makes no HTTP request: it recomputes the delivery signature locally and prints `{ valid, reason }`. It is also the only command that needs **no API key** — it never contacts the API, so a webhook receiver can run it without holding a send-capable key. Pass the **exact raw body bytes** your endpoint received via `--payload` or `--payload-file` — re-serialized JSON will not match. `--tolerance <seconds>` caps timestamp skew (default `300`; `0` skips the freshness check). Note the exit code is `0` whenever the check ran, whatever the verdict — branch on `.valid`, not on `$?` (unlike `webhooks test`, which exits `1` on a failed delivery).
287
+
288
+ #### API keys are read-only from the CLI
289
+
290
+ `api-keys list` is the whole group. There is no `create`, `update` or `delete`, and that is deliberate: **keys are created, re-scoped and revoked in the [SendDart dashboard](https://www.senddart.com/app/api-keys)**, behind a signed-in session.
291
+
292
+ Every CLI invocation authenticates with an API key, so keeping key lifecycle out of the CLI means a key that leaks — from a shell history, a CI log, a `.env` someone pasted — cannot mint itself a replacement, widen its own permission or domain scope, or revoke the keys around it. Its blast radius stays fixed at what it could already do. The API enforces the same rule: `POST /api-keys`, `PATCH /api-keys/:id` and `DELETE /api-keys/:id` answer `403 dashboard_only` to any API-key caller.
293
+
294
+ `api-keys list` still shows everything you need to audit: each key's non-secret prefix, permission, domain scoping and `last_used_at`.
295
+
296
+ ## Command names vs. SDK method names
297
+
298
+ The CLI's verbs are deliberately shorter than the corresponding SDK methods. A
299
+ subcommand is already scoped by its resource path, so the CLI names every list
300
+ after its plural noun and every download after the thing downloaded:
301
+
302
+ | CLI command | SDK method (`senddart` npm naming) |
303
+ |---|---|
304
+ | `emails attachments <id>` | `emails.listAttachments` |
305
+ | `emails receiving addresses` | `emails.receiving.listAddresses` |
306
+ | `emails receiving attachments <id>` | `emails.receiving.listAttachments` |
307
+ | `emails receiving raw <id>` | `emails.receiving.getRaw` |
308
+ | `automations ai <id>` | `automations.createWithAi` |
309
+ | `contacts import-upload <audienceId>` | `contacts.createImportUpload` |
310
+
311
+ This is a shell-surface convention, not drift: the CLI applies the same
312
+ shortening rule to every endpoint rather than to some.
313
+
314
+ The right-hand column is the Node.js SDK's spelling, because that is the library
315
+ this CLI calls. Seven of the eight client libraries put the same method on the
316
+ same nested resource and differ only in each language's casing and accessor
317
+ syntax — `listAttachments` in npm, PHP (`$senddart->emails->receiving`) and
318
+ Java (`emails().receiving()`), `list_attachments` in Python, Ruby and Rust,
319
+ `ListAttachments` in Go (`client.Emails.Receiving`). The .NET SDK is the
320
+ exception: it is a flat client, so read `EmailListAttachmentsAsync`,
321
+ `ReceivedEmailListAddressesAsync`, `ReceivedEmailListAttachmentsAsync`,
322
+ `ReceivedEmailGetRawAsync`, `AutomationCreateWithAiAsync` and
323
+ `ContactImportCreateUploadAsync` instead of the dotted names above.
324
+
325
+ ## Documentation
326
+
327
+ Full API docs: <https://www.senddart.com/docs>
328
+
329
+ ## License
330
+
331
+ MIT
332
+
333
+ ## Recovery and tracking contracts
334
+
335
+ Use a stable, unique operation key for each intended send, batch, reply, or
336
+ forward. Keep the same key and payload when recovering that operation. These
337
+ are the supported idempotent send endpoints; events do not implement this
338
+ header. Existing calls without options still work.
339
+
340
+ ```sh
341
+ senddart emails receiving reply rem_123 --from me@yourdomain.com --text "Thanks" --idempotency-key reply-operation-1
342
+ senddart emails receiving forward rem_123 --from me@yourdomain.com --to team@yourdomain.com --idempotency-key forward-operation-1
343
+ senddart domains tracking-health dom_123
344
+ ```
345
+
346
+ Automatic retries consider only 429/503. They stop on an original email `id`,
347
+ positive `sent_count`, nonempty `sent` or `reserved`, or `batch_incomplete`.
348
+ An ordinary rate limit can retry; a generic 503 can retry a read or a send with
349
+ the same supported key. Other writes retry only documented pre-processing
350
+ rejections (`service_unavailable`, `sending_service_unavailable`,
351
+ `sending_configuration_unavailable`, `contacts_busy`, `contacts_timeout`).
352
+ No network/body-read failure, 409, 422, or other 5xx is retried automatically.
353
+ The default transport refuses redirects; a custom transport/client must enforce
354
+ its own policy.
355
+
356
+ On a failed or unconfirmed send, inspect `id` with the email retrieval method
357
+ before creating another send. A 422 with an ID can identify an uncertain
358
+ provider handoff; 422 does not always mean nothing happened. For interrupted
359
+ batches, `sent` contains confirmed sends, `reserved` contains the original
360
+ attempted prefix (including uncertain handoffs), and `unsent_count` counts the
361
+ never-attempted tail. Do not resend the full batch or the reserved prefix under
362
+ a new key. Reconcile original IDs first, then submit only known unattempted
363
+ items as a new operation. Recovery fields remain available in the full error
364
+ body as well as language-specific fields/accessors.
365
+
366
+ Tracking health returns `custom_host`, `status` (`shared`, `ready`, or
367
+ `unavailable`), and `checked_at`. Configure custom tracking through the domain
368
+ API and check health before relying on it. A healthy endpoint cannot guarantee
369
+ an open event: recipients may block images, and coupon redemption alone is not
370
+ proof that the tracking pixel loaded. SDKs preserve supplied HTML/text and do
371
+ not infer opens or rewrite editor spacing.
372
+
373
+ Campaign cancellation also stops pending follow-ups for an already-sent
374
+ campaign while retaining its sent history. Permanent received-email deletion
375
+ acknowledges a durable cleanup request; attachment/object cleanup can finish
376
+ asynchronously. Retrying that deletion is safe; it cannot be undone after the
377
+ purge request is accepted.
@@ -0,0 +1,14 @@
1
+ #!/usr/bin/env node
2
+ 'use strict';
3
+
4
+ const { main } = require('../src/cli');
5
+
6
+ main(process.argv.slice(2)).then(
7
+ (code) => {
8
+ process.exitCode = code;
9
+ },
10
+ (err) => {
11
+ process.stderr.write(`${err && err.message ? err.message : err}\n`);
12
+ process.exitCode = 1;
13
+ },
14
+ );
package/package.json ADDED
@@ -0,0 +1,43 @@
1
+ {
2
+ "name": "senddart-cli",
3
+ "version": "1.0.0",
4
+ "description": "Official command-line interface for the SendDart email API.",
5
+ "keywords": [
6
+ "senddart",
7
+ "email",
8
+ "cli",
9
+ "api",
10
+ "transactional"
11
+ ],
12
+ "license": "MIT",
13
+ "author": "SendDart",
14
+ "homepage": "https://www.senddart.com",
15
+ "repository": {
16
+ "type": "git",
17
+ "url": "git+https://github.com/shekhu10/senddart-sdks.git",
18
+ "directory": "senddart-cli"
19
+ },
20
+ "bugs": {
21
+ "url": "https://github.com/shekhu10/senddart-sdks/issues"
22
+ },
23
+ "bin": {
24
+ "senddart": "bin/senddart.js"
25
+ },
26
+ "main": "src/cli.js",
27
+ "files": [
28
+ "bin",
29
+ "src",
30
+ "README.md",
31
+ "LICENSE"
32
+ ],
33
+ "scripts": {
34
+ "test": "node --test \"test/**/*.test.js\""
35
+ },
36
+ "engines": {
37
+ "node": ">=18"
38
+ },
39
+ "dependencies": {
40
+ "commander": "^12.1.0",
41
+ "senddart": "^1.0.0"
42
+ }
43
+ }
package/src/cli.js ADDED
@@ -0,0 +1,179 @@
1
+ 'use strict';
2
+
3
+ const { Command } = require('commander');
4
+ const { CliError } = require('./helpers');
5
+
6
+ const VERSION = require('../package.json').version;
7
+
8
+ const RESOURCES = [
9
+ require('./commands/emails'),
10
+ require('./commands/domains'),
11
+ require('./commands/contacts'),
12
+ require('./commands/contact_properties'),
13
+ require('./commands/audiences'),
14
+ require('./commands/segments'),
15
+ require('./commands/topics'),
16
+ require('./commands/campaigns'),
17
+ require('./commands/templates'),
18
+ require('./commands/automations'),
19
+ require('./commands/webhooks'),
20
+ require('./commands/apikeys'),
21
+ require('./commands/events'),
22
+ require('./commands/logs'),
23
+ require('./commands/polls'),
24
+ ];
25
+
26
+ /**
27
+ * Build the execution context. Everything side-effectful (client construction,
28
+ * writing, environment) is injectable so tests can run the command layer with
29
+ * a mocked SDK client.
30
+ */
31
+ function createContext(overrides = {}) {
32
+ return {
33
+ createClient(apiKey, options) {
34
+ const { SendDart } = require('senddart');
35
+ return new SendDart(apiKey, options);
36
+ },
37
+ // Pure, offline signature check. The SDK exports it as a standalone
38
+ // function precisely so it can be used WITHOUT a client — `webhooks verify`
39
+ // makes no HTTP request, so it must not demand an API key it never sends.
40
+ verifyWebhook(payload, headers, secret, options) {
41
+ const { verifyWebhookSignature } = require('senddart');
42
+ return verifyWebhookSignature(payload, headers, secret, options);
43
+ },
44
+ stdout: (s) => process.stdout.write(s),
45
+ stderr: (s) => process.stderr.write(s),
46
+ env: process.env,
47
+ exitCode: 0,
48
+ ...overrides,
49
+ };
50
+ }
51
+
52
+ /** Resolve auth/base-url flags (falling back to env) into an SDK client. */
53
+ function getClient(ctx, opts) {
54
+ const apiKey = opts.apiKey || ctx.env.SENDDART_API_KEY;
55
+ if (!apiKey) {
56
+ throw new CliError('Missing API key. Set the SENDDART_API_KEY environment variable or pass --api-key.');
57
+ }
58
+ const baseUrl = opts.baseUrl || ctx.env.SENDDART_BASE_URL;
59
+ return ctx.createClient(apiKey, baseUrl ? { baseUrl } : {});
60
+ }
61
+
62
+ /** Print a success payload: pretty JSON by default, raw compact with --json. */
63
+ function print(ctx, data, opts) {
64
+ const s = opts.json ? JSON.stringify(data) : JSON.stringify(data, null, 2);
65
+ ctx.stdout(`${s}\n`);
66
+ }
67
+
68
+ /**
69
+ * Print an API/CLI error to stderr and mark the run failed. `--json` means
70
+ * "raw compact JSON output" for BOTH streams — an error printed pretty while
71
+ * the flag asked for compact made the flag a half-truth.
72
+ */
73
+ function fail(ctx, error, opts = {}) {
74
+ ctx.stderr(`${opts.json ? JSON.stringify(error) : JSON.stringify(error, null, 2)}\n`);
75
+ ctx.exitCode = 1;
76
+ }
77
+
78
+ /**
79
+ * Build the toolkit passed to each resource module: `group` creates a
80
+ * top-level resource command, `leaf` a subcommand carrying the shared
81
+ * auth/output flags, and `act` wires a handler that receives the SDK client
82
+ * and returns its `{ data, error }` result.
83
+ */
84
+ function makeToolkit(program, ctx) {
85
+ // Commands declared `local` make no HTTP request, so they neither resolve a
86
+ // client nor advertise the auth flags. Declared once, on the leaf; `act` reads
87
+ // it back rather than taking a second, drift-prone copy of the same fact.
88
+ const localCommands = new WeakSet();
89
+
90
+ function group(name, description) {
91
+ return program.command(name).description(description);
92
+ }
93
+ function leaf(parent, spec, description, options = {}) {
94
+ const cmd = parent.command(spec).description(description);
95
+ if (options.local) {
96
+ localCommands.add(cmd);
97
+ } else {
98
+ cmd
99
+ .option('--api-key <key>', 'API key (default: SENDDART_API_KEY env var)')
100
+ .option('--base-url <url>', 'API base URL (default: SENDDART_BASE_URL env var)');
101
+ }
102
+ // `--json` still applies: a local command prints its result like any other.
103
+ return cmd.option('--json', 'raw compact JSON output (default: pretty-printed)');
104
+ }
105
+ function act(cmd, handler) {
106
+ cmd.action(async (...cbArgs) => {
107
+ const command = cbArgs[cbArgs.length - 1];
108
+ const args = cbArgs.slice(0, -1);
109
+ const opts = command.opts();
110
+ try {
111
+ const client = localCommands.has(cmd) ? undefined : getClient(ctx, opts);
112
+ const result = await handler({ client, ctx, opts, args });
113
+ if (result && result.error) return fail(ctx, result.error, opts);
114
+ print(ctx, result ? result.data : null, opts);
115
+ // Some endpoints answer 200 while reporting a failed operation in the
116
+ // body (e.g. POST /webhooks/:id/test → { ok: false }). A handler flags
117
+ // that with `failed` so the body is still printed but the shell sees 1.
118
+ if (result && result.failed) ctx.exitCode = 1;
119
+ return undefined;
120
+ } catch (err) {
121
+ if (err instanceof CliError) {
122
+ return fail(ctx, { statusCode: null, name: 'cli_error', message: err.message }, opts);
123
+ }
124
+ throw err;
125
+ }
126
+ });
127
+ return cmd;
128
+ }
129
+ return { group, leaf, act };
130
+ }
131
+
132
+ /** Assemble the full commander program for the given context. */
133
+ function buildProgram(ctx) {
134
+ const program = new Command();
135
+ program
136
+ .name('senddart')
137
+ .description('Official SendDart CLI — send email, manage domains, contacts, campaigns and more.')
138
+ .version(VERSION)
139
+ .exitOverride()
140
+ .configureOutput({
141
+ writeOut: (s) => ctx.stdout(s),
142
+ writeErr: (s) => ctx.stderr(s),
143
+ })
144
+ .addHelpText(
145
+ 'after',
146
+ '\nAuthentication:\n Set SENDDART_API_KEY (or pass --api-key to any command).\n Set SENDDART_BASE_URL (or --base-url) to target a different API host.\n\nExamples:\n senddart emails send --from \'Acme <hi@yourdomain.com>\' --to delivered@test.senddart.com --subject hello --html \'<p>hi</p>\'\n senddart contacts list --domain yourdomain.com\n senddart events send --domain yourdomain.com --name signup.completed --email ada@example.com --data \'{"plan":"pro"}\'',
147
+ );
148
+
149
+ const toolkit = makeToolkit(program, ctx);
150
+ for (const resource of RESOURCES) resource.register(toolkit);
151
+ return program;
152
+ }
153
+
154
+ /**
155
+ * Parse and execute argv (user args only, no node/script prefix).
156
+ * Returns the exit code; never calls process.exit itself.
157
+ */
158
+ async function run(ctx, argv) {
159
+ const program = buildProgram(ctx);
160
+ try {
161
+ await program.parseAsync(argv, { from: 'user' });
162
+ } catch (err) {
163
+ // Commander throws for --help/--version (exitCode 0) and usage errors
164
+ // (exitCode 1) because of exitOverride; the message is already printed.
165
+ if (err && typeof err.exitCode === 'number' && String(err.code || '').startsWith('commander.')) {
166
+ if (err.exitCode !== 0) ctx.exitCode = err.exitCode;
167
+ return ctx.exitCode;
168
+ }
169
+ throw err;
170
+ }
171
+ return ctx.exitCode;
172
+ }
173
+
174
+ /** Entry point used by bin/senddart.js. */
175
+ function main(argv) {
176
+ return run(createContext(), argv);
177
+ }
178
+
179
+ module.exports = { createContext, buildProgram, run, main };
@@ -0,0 +1,16 @@
1
+ 'use strict';
2
+
3
+ const { withPagination, pagination } = require('../helpers');
4
+
5
+ // `list` is the whole group on purpose. Creating, re-scoping and revoking keys
6
+ // happens in the dashboard, behind a signed-in session — so a key that leaks
7
+ // cannot mint itself a replacement or widen its own access from the CLI.
8
+ function register({ group, leaf, act }) {
9
+ const apiKeys = group('api-keys', 'Inspect API keys (create/revoke live in the dashboard)');
10
+
11
+ act(withPagination(leaf(apiKeys, 'list', 'List API keys')), ({ client, opts }) =>
12
+ client.apiKeys.list(pagination(opts)),
13
+ );
14
+ }
15
+
16
+ module.exports = { register };