unitpost 0.2.1 → 0.4.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/dist/index.js CHANGED
@@ -4,7 +4,7 @@ import { createHmac, timingSafeEqual, randomUUID } from 'crypto';
4
4
  var API_VERSION = "v1";
5
5
 
6
6
  // src/http.ts
7
- var SDK_VERSION = "0.1.0";
7
+ var SDK_VERSION = "0.4.0";
8
8
  var DEFAULT_BASE_URL = "https://www.unitpost.com";
9
9
  var UnitpostError = class extends Error {
10
10
  code;
@@ -189,13 +189,19 @@ function safeJsonParse(text) {
189
189
  }
190
190
 
191
191
  // src/pagination.ts
192
- async function* paginate(client, path, params = {}) {
192
+ var FORWARD_ONLY_MESSAGE = "listAll pages forward only: `before` is not supported (use list() to page backward).";
193
+ function paginate(client, path, params = {}) {
194
+ if (params.before) throw new TypeError(FORWARD_ONLY_MESSAGE);
195
+ return pages(client, path, params);
196
+ }
197
+ async function* pages(client, path, params) {
193
198
  let after = params.after;
194
199
  for (; ; ) {
195
200
  const { data, error } = await client.request({
196
201
  method: "GET",
197
202
  path,
198
- query: { limit: params.limit, after, before: params.before }
203
+ // Filters ride along on every page; only the cursor moves.
204
+ query: { ...params, after }
199
205
  });
200
206
  if (error) throw error;
201
207
  const page = data;
@@ -259,6 +265,215 @@ var Resource = class {
259
265
  }
260
266
  http;
261
267
  };
268
+ var Sms = class extends Resource {
269
+ /** SMS templates: plain-text bodies with `{{variable}}` placeholders. */
270
+ templates;
271
+ /** SMS campaigns: a published SMS template sent to a segment. */
272
+ campaigns;
273
+ /** SMS subscription topics (independent from email topics). */
274
+ topics;
275
+ constructor(http) {
276
+ super(http);
277
+ this.templates = new SmsTemplates(http);
278
+ this.campaigns = new SmsCampaigns(http);
279
+ this.topics = new SmsTopics(http);
280
+ }
281
+ /**
282
+ * Send or schedule an SMS message.
283
+ *
284
+ * The recipient must be E.164 (`+15551234567`). Marketing sends require the
285
+ * recipient's prior express consent on record and honor recipient-local
286
+ * quiet hours (deferred, never dropped). Billing is per segment. An
287
+ * `Idempotency-Key` is generated automatically when you don't pass one.
288
+ */
289
+ send(body, opts = {}) {
290
+ return this.http.request({
291
+ method: "POST",
292
+ path: "/sms",
293
+ body,
294
+ idempotencyKey: opts.idempotencyKey ?? randomUUID()
295
+ });
296
+ }
297
+ /** Retrieve one SMS message's status and delivery state. */
298
+ get(id) {
299
+ return this.http.request({ method: "GET", path: `/sms/${enc(id)}` });
300
+ }
301
+ /**
302
+ * Cancel a queued/scheduled SMS (`{ cancel: true }` — its reserved credit is
303
+ * refunded) or move a scheduled one (`{ scheduled_at }`).
304
+ */
305
+ update(id, body) {
306
+ return this.http.request({ method: "PATCH", path: `/sms/${enc(id)}`, body });
307
+ }
308
+ /**
309
+ * List SMS messages (cursor-paginated, newest first). `participant` returns
310
+ * the whole conversation with one number: texts you sent them and their
311
+ * replies.
312
+ */
313
+ list(params = {}) {
314
+ return this.http.request({ method: "GET", path: "/sms", query: params });
315
+ }
316
+ /** Async-iterate every SMS message (same filters as `list`). */
317
+ listAll(params = {}) {
318
+ return paginate(this.http, "/sms", params);
319
+ }
320
+ /**
321
+ * List SMS brands and their setup status.
322
+ *
323
+ * A brand is the business identity carriers register before they approve a
324
+ * phone number, so this is what to poll to answer "is SMS ready yet?":
325
+ * `status` says whether you or the carrier is the blocker, and `missing`
326
+ * lists exactly what is still required.
327
+ *
328
+ * Read-only — creating a brand is a paid carrier submission and is only
329
+ * available in the dashboard.
330
+ */
331
+ brands(params = {}) {
332
+ return this.http.request({
333
+ method: "GET",
334
+ path: "/sms/brands",
335
+ query: params
336
+ });
337
+ }
338
+ /**
339
+ * List SMS phone numbers.
340
+ *
341
+ * Only numbers with `status: "active"` can send. A `ten_dlc` number has no
342
+ * `phone_number` until carriers approve it, and a `simulator` number only
343
+ * reaches verified test destinations.
344
+ *
345
+ * Read-only — requesting or releasing a number is only available in the
346
+ * dashboard.
347
+ */
348
+ numbers(params = {}) {
349
+ return this.http.request({
350
+ method: "GET",
351
+ path: "/sms/numbers",
352
+ query: params
353
+ });
354
+ }
355
+ /**
356
+ * SMS delivery stats over a rolling window: queued, sent, delivered,
357
+ * failed, suppressed, canceled, inbound and segments billed, with delivery,
358
+ * failure and suppression rates. No opens or clicks on SMS.
359
+ *
360
+ * `days` is the window size (1–365); defaults to 30 server-side.
361
+ */
362
+ stats(params = {}) {
363
+ return this.http.request({ method: "GET", path: "/sms/stats", query: params });
364
+ }
365
+ /** Read a contact's SMS consent state and immutable consent history. */
366
+ smsConsent(contactId) {
367
+ return this.http.request({
368
+ method: "GET",
369
+ path: `/contacts/${enc(contactId)}/sms-consent`
370
+ });
371
+ }
372
+ /** Record an SMS consent change (opt-in or opt-out) for a contact. */
373
+ recordSmsConsent(contactId, body) {
374
+ return this.http.request({
375
+ method: "POST",
376
+ path: `/contacts/${enc(contactId)}/sms-consent`,
377
+ body
378
+ });
379
+ }
380
+ };
381
+ var SmsTemplates = class extends Resource {
382
+ list(params = {}) {
383
+ return this.http.request({ method: "GET", path: "/sms/templates", query: params });
384
+ }
385
+ listAll(params = {}) {
386
+ return paginate(this.http, "/sms/templates", params);
387
+ }
388
+ create(body) {
389
+ return this.http.request({ method: "POST", path: "/sms/templates", body });
390
+ }
391
+ get(id) {
392
+ return this.http.request({ method: "GET", path: `/sms/templates/${enc(id)}` });
393
+ }
394
+ update(id, body) {
395
+ return this.http.request({ method: "PATCH", path: `/sms/templates/${enc(id)}`, body });
396
+ }
397
+ delete(id) {
398
+ return this.http.request({ method: "DELETE", path: `/sms/templates/${enc(id)}` });
399
+ }
400
+ };
401
+ var SmsCampaigns = class extends Resource {
402
+ list(params = {}) {
403
+ return this.http.request({ method: "GET", path: "/sms/campaigns", query: params });
404
+ }
405
+ listAll(params = {}) {
406
+ return paginate(this.http, "/sms/campaigns", params);
407
+ }
408
+ /** Create a draft. Omit `sender_id` for automatic routing. */
409
+ create(body) {
410
+ return this.http.request({ method: "POST", path: "/sms/campaigns", body });
411
+ }
412
+ get(id) {
413
+ return this.http.request({ method: "GET", path: `/sms/campaigns/${enc(id)}` });
414
+ }
415
+ /** Edit a draft (409 once sent or scheduled). */
416
+ update(id, body) {
417
+ return this.http.request({ method: "PATCH", path: `/sms/campaigns/${enc(id)}`, body });
418
+ }
419
+ /** Archive a draft or finished campaign (cancel an in-flight one first). */
420
+ delete(id) {
421
+ return this.http.request({ method: "DELETE", path: `/sms/campaigns/${enc(id)}` });
422
+ }
423
+ /**
424
+ * Send now, or pass `{ scheduled_at }` to schedule. A large audience whose
425
+ * recipient check is still running is refused with `409 preflight_pending`:
426
+ * poll `validate(id)` until it returns the report, then send again.
427
+ */
428
+ send(id, body = {}) {
429
+ return this.http.request({ method: "POST", path: `/sms/campaigns/${enc(id)}/send`, body });
430
+ }
431
+ /**
432
+ * The campaign, already `canceled`. With more than 500 queued texts (202)
433
+ * they are canceled and refunded in the background.
434
+ */
435
+ cancel(id) {
436
+ return this.http.request({ method: "POST", path: `/sms/campaigns/${enc(id)}/cancel` });
437
+ }
438
+ pause(id) {
439
+ return this.http.request({ method: "POST", path: `/sms/campaigns/${enc(id)}/pause` });
440
+ }
441
+ resume(id) {
442
+ return this.http.request({ method: "POST", path: `/sms/campaigns/${enc(id)}/resume` });
443
+ }
444
+ reschedule(id, body) {
445
+ return this.http.request({ method: "POST", path: `/sms/campaigns/${enc(id)}/reschedule`, body });
446
+ }
447
+ /**
448
+ * Who the campaign would reach if sent now (non-mutating). A large audience
449
+ * is counted in the background: the first call returns that `Job` (202).
450
+ * Call again until it returns the report; tell them apart with `object`
451
+ * (`"job"`).
452
+ */
453
+ validate(id) {
454
+ return this.http.request({ method: "GET", path: `/sms/campaigns/${enc(id)}/validate` });
455
+ }
456
+ };
457
+ var SmsTopics = class extends Resource {
458
+ list(params = {}) {
459
+ return this.http.request({ method: "GET", path: "/sms/topics", query: params });
460
+ }
461
+ listAll(params = {}) {
462
+ return paginate(this.http, "/sms/topics", params);
463
+ }
464
+ create(body) {
465
+ return this.http.request({ method: "POST", path: "/sms/topics", body });
466
+ }
467
+ get(id) {
468
+ return this.http.request({ method: "GET", path: `/sms/topics/${enc(id)}` });
469
+ }
470
+ update(id, body) {
471
+ return this.http.request({ method: "PATCH", path: `/sms/topics/${enc(id)}`, body });
472
+ }
473
+ delete(id) {
474
+ return this.http.request({ method: "DELETE", path: `/sms/topics/${enc(id)}` });
475
+ }
476
+ };
262
477
  var Email = class extends Resource {
263
478
  topics;
264
479
  campaigns;
@@ -375,6 +590,9 @@ var Contacts = class extends Resource {
375
590
  getImport(id) {
376
591
  return this.http.request({ method: "GET", path: `/contacts/imports/${enc(id)}` });
377
592
  }
593
+ cancelImport(id) {
594
+ return this.http.request({ method: "POST", path: `/contacts/imports/${enc(id)}/cancel` });
595
+ }
378
596
  };
379
597
  var ContactFields = class extends Resource {
380
598
  list(params = {}) {
@@ -392,13 +610,33 @@ var ContactFields = class extends Resource {
392
610
  update(id, body) {
393
611
  return this.http.request({ method: "PATCH", path: `/contact-fields/${enc(id)}`, body });
394
612
  }
613
+ /**
614
+ * `null` (204) when the field was deleted at once; a `Job` (202) when it
615
+ * held a value on more than 5,000 contacts and the delete runs in the
616
+ * background — follow it with `jobs.get(job.id)`.
617
+ */
395
618
  delete(id) {
396
619
  return this.http.request({ method: "DELETE", path: `/contact-fields/${enc(id)}` });
397
620
  }
621
+ /**
622
+ * The renamed `ContactField` (200), or a `Job` (202) when more than 5,000
623
+ * contacts hold the field: the key is already renamed and the values move in
624
+ * the background — follow it with `jobs.get(job.id)`. Tell them apart with
625
+ * `object` (`"contact_field"` / `"job"`).
626
+ */
398
627
  rename(id, body) {
399
628
  return this.http.request({ method: "POST", path: `/contact-fields/${enc(id)}/rename`, body });
400
629
  }
401
630
  };
631
+ var Jobs = class extends Resource {
632
+ /**
633
+ * Retrieve a background job — the `202` answer of an operation too large for
634
+ * one request. Poll until `status` is `COMPLETED`, `FAILED` or `CANCELED`.
635
+ */
636
+ get(id) {
637
+ return this.http.request({ method: "GET", path: `/jobs/${enc(id)}` });
638
+ }
639
+ };
402
640
  var Segments = class extends Resource {
403
641
  list(params = {}) {
404
642
  return this.http.request({ method: "GET", path: "/segments", query: params });
@@ -477,8 +715,13 @@ var Campaigns = class extends Resource {
477
715
  delete(id) {
478
716
  return this.http.request({ method: "DELETE", path: `/email/campaigns/${enc(id)}` });
479
717
  }
480
- send(id) {
481
- return this.http.request({ method: "POST", path: `/email/campaigns/${enc(id)}/send` });
718
+ /**
719
+ * Send a draft. `{}` (the default) arms its saved `scheduled_at` while that
720
+ * is still ahead, otherwise sends NOW; `{ scheduled_at: "<ISO 8601>" }`
721
+ * schedules it; `{ scheduled_at: null }` sends now.
722
+ */
723
+ send(id, body = {}) {
724
+ return this.http.request({ method: "POST", path: `/email/campaigns/${enc(id)}/send`, body });
482
725
  }
483
726
  cancel(id) {
484
727
  return this.http.request({ method: "POST", path: `/email/campaigns/${enc(id)}/cancel` });
@@ -494,7 +737,11 @@ var Campaigns = class extends Resource {
494
737
  reschedule(id, body) {
495
738
  return this.http.request({ method: "POST", path: `/email/campaigns/${enc(id)}/reschedule`, body });
496
739
  }
497
- /** Non-mutating pre-send validation report. */
740
+ /**
741
+ * Non-mutating pre-send validation report. A large audience is counted in
742
+ * the background: the first call returns that `Job` (202). Call again until
743
+ * it returns the report.
744
+ */
498
745
  validate(id) {
499
746
  return this.http.request({ method: "GET", path: `/email/campaigns/${enc(id)}/validate` });
500
747
  }
@@ -518,6 +765,14 @@ var Templates = class extends Resource {
518
765
  delete(id) {
519
766
  return this.http.request({ method: "DELETE", path: `/email/templates/${enc(id)}` });
520
767
  }
768
+ /**
769
+ * Send ONE test of the template to `to`, rendered with sample `variables`
770
+ * exactly as a recipient gets it. Without a verified domain only workspace
771
+ * members may receive it.
772
+ */
773
+ testSend(id, body) {
774
+ return this.http.request({ method: "POST", path: `/email/templates/${enc(id)}/test-send`, body });
775
+ }
521
776
  };
522
777
  var BrandKits = class extends Resource {
523
778
  /** List profiles (max 5). Optional `name` filters by display name. */
@@ -552,6 +807,10 @@ var Domains = class extends Resource {
552
807
  verify(id) {
553
808
  return this.http.request({ method: "POST", path: `/email/domains/${enc(id)}/verify` });
554
809
  }
810
+ /** Explain the domain's DNS: every nameserver's answer per record, and ranked findings with fixes. Read-only. */
811
+ diagnose(id) {
812
+ return this.http.request({ method: "GET", path: `/email/domains/${enc(id)}/diagnose` });
813
+ }
555
814
  };
556
815
  var Webhooks = class extends Resource {
557
816
  list(params = {}) {
@@ -577,6 +836,21 @@ var Webhooks = class extends Resource {
577
836
  test(id) {
578
837
  return this.http.request({ method: "POST", path: `/webhooks/${enc(id)}/test` });
579
838
  }
839
+ /**
840
+ * Mint a new signing secret. The response carries it exactly once; the old
841
+ * secret co-signs deliveries until `previous_secret_expires_at` (24 h).
842
+ */
843
+ rotateSecret(id) {
844
+ return this.http.request({ method: "POST", path: `/webhooks/${enc(id)}/rotate-secret` });
845
+ }
846
+ /** The endpoint's delivery log, newest first (cursor-paginated). */
847
+ listDeliveries(id, params = {}) {
848
+ return this.http.request({ method: "GET", path: `/webhooks/${enc(id)}/deliveries`, query: params });
849
+ }
850
+ /** Async-iterate every delivery of the endpoint. */
851
+ listAllDeliveries(id, params = {}) {
852
+ return paginate(this.http, `/webhooks/${enc(id)}/deliveries`, params);
853
+ }
580
854
  /**
581
855
  * Verify a webhook delivery's signature and return the parsed event. Throws
582
856
  * `WebhookVerificationError` on a missing/invalid/stale signature. Alias of the
@@ -602,7 +876,10 @@ var ApiKeys = class extends Resource {
602
876
  }
603
877
  };
604
878
  var Suppressions = class extends Resource {
605
- /** List suppressed addresses (your own + read-only platform rows). */
879
+ /**
880
+ * List your workspace's suppressed addresses. Unitpost-wide (platform)
881
+ * blocks are enforced at send time but not listed — `get(email)` explains one.
882
+ */
606
883
  list(params = {}) {
607
884
  return this.http.request({ method: "GET", path: "/suppressions", query: params });
608
885
  }
@@ -644,8 +921,14 @@ function enc(segment) {
644
921
  // src/client.ts
645
922
  var Unitpost = class {
646
923
  email;
924
+ /**
925
+ * SMS channel. Available on paid plans: on the free plan `send` returns a
926
+ * 403 with code `limit_reached`; reads keep working.
927
+ */
928
+ sms;
647
929
  contacts;
648
930
  contactFields;
931
+ jobs;
649
932
  segments;
650
933
  brandKits;
651
934
  webhooks;
@@ -658,8 +941,10 @@ var Unitpost = class {
658
941
  const options = typeof apiKeyOrOptions === "string" ? { apiKey: apiKeyOrOptions } : apiKeyOrOptions ?? {};
659
942
  const http = new HttpClient(options);
660
943
  this.email = new Email(http);
944
+ this.sms = new Sms(http);
661
945
  this.contacts = new Contacts(http);
662
946
  this.contactFields = new ContactFields(http);
947
+ this.jobs = new Jobs(http);
663
948
  this.segments = new Segments(http);
664
949
  this.brandKits = new BrandKits(http);
665
950
  this.webhooks = new Webhooks(http);