coss 0.3.0 → 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.d.ts CHANGED
@@ -70,7 +70,7 @@ interface HttpClientOptions {
70
70
  interface ApiRequest {
71
71
  /** Disable automatic retries for operations without server-side deduplication. */
72
72
  retry?: boolean;
73
- method: "GET" | "POST" | "PATCH" | "DELETE";
73
+ method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
74
74
  /** Path including the version prefix, e.g. `/v1/emails`. */
75
75
  path: string;
76
76
  /** Query parameters; `undefined` values are left out. */
@@ -95,11 +95,59 @@ declare class HttpClient {
95
95
  request<T>(request: ApiRequest): Promise<CossResult<T>>;
96
96
  }
97
97
  //#endregion
98
+ //#region src/types/environment.d.ts
99
+ /** Environment wire types (hand-written mirrors of the API's `Environment` schema). */
100
+ /** A project or organization, as named in the dashboard. */
101
+ interface NamedResource {
102
+ id: string;
103
+ name: string;
104
+ /** As in dashboard URLs. */
105
+ slug: string;
106
+ }
107
+ /** `GET /v1/environment`: the environment the API key belongs to. */
108
+ interface Environment {
109
+ object: "environment";
110
+ id: string;
111
+ name: string;
112
+ slug: string;
113
+ /** `live` delivers email; `sandbox` (`coss_test_` keys) never does. */
114
+ mode: "live" | "sandbox";
115
+ project: NamedResource;
116
+ organization: NamedResource & {
117
+ /** The organization's pinned API version (for requests without `Coss-Version`). */
118
+ api_version: string;
119
+ };
120
+ /** The API key making the request. */
121
+ api_key: {
122
+ id: string;
123
+ name: string | null;
124
+ /** The key's first characters, as shown in the dashboard. */
125
+ start: string | null;
126
+ };
127
+ }
128
+ /** `DELETE /v1/api_key`: the key revoked itself. */
129
+ interface DeletedApiKey {
130
+ object: "api_key";
131
+ id: string;
132
+ deleted: true;
133
+ }
134
+ //#endregion
135
+ //#region src/resources/api-key.d.ts
136
+ type ReadOptions$18 = Pick<RequestOptions, "signal">;
137
+ /** `coss.apiKey`: the API key the client was created with. */
138
+ declare class ApiKeyResource {
139
+ #private;
140
+ /** @internal Use `new Coss().apiKey`. */
141
+ constructor(http: HttpClient);
142
+ /** Revokes the client's own API key, at once: every later request with it fails. */
143
+ revoke(options?: ReadOptions$18): Promise<CossResult<DeletedApiKey>>;
144
+ }
145
+ //#endregion
98
146
  //#region src/types/audit-event.d.ts
99
147
  /** Audit log wire types (hand-written mirrors of the API's schemas). */
100
148
  /**
101
- * `user`: a member, in the dashboard. `api_key`: a request made with an API key. `system`: COSS
102
- * itself, including COSS support.
149
+ * `user`: a member, in the dashboard. `api_key`: a request made with an API key. `system`: coss.com
150
+ * itself, including coss.com support.
103
151
  */
104
152
  type AuditActorType = "user" | "api_key" | "system";
105
153
  /** One change to the organization. */
@@ -111,7 +159,7 @@ interface AuditEvent {
111
159
  actor_type: AuditActorType;
112
160
  /** The user's or API key's id; `null` for the system. */
113
161
  actor_id: string | null;
114
- /** The user's email, the API key's id, or `COSS support` (copied when recorded). */
162
+ /** The user's email, the API key's id, or `coss.com support` (copied when recorded). */
115
163
  actor_label: string;
116
164
  /** `<resource>.<verb>`, e.g. `api_key.created`, `domain.deleted`, `member.role_changed`. */
117
165
  action: string;
@@ -151,13 +199,165 @@ interface ListAuditEventsParams {
151
199
  after?: string;
152
200
  }
153
201
  //#endregion
202
+ //#region src/types/email-template.d.ts
203
+ /** Wire types of email templates (`coss.email.templates`). */
204
+ /** A variable's type. `list` is an array of objects with the declared `fields`. */
205
+ type TemplateVariableType = "string" | "number" | "boolean" | "list";
206
+ type TemplateScalarType = "string" | "number" | "boolean";
207
+ /** A declared variable, used in the template as `{{name}}`. */
208
+ interface TemplateVariable {
209
+ name: string;
210
+ type: TemplateVariableType;
211
+ /** Sends must pass it unless it has a `default`. */
212
+ required: boolean;
213
+ /** Used when a send leaves it out. */
214
+ default?: string | number | boolean;
215
+ description?: string;
216
+ /** A list's item fields. */
217
+ fields?: {
218
+ name: string;
219
+ type: TemplateScalarType;
220
+ required: boolean;
221
+ }[];
222
+ }
223
+ /** A variable to declare. `required` defaults to true. */
224
+ interface TemplateVariableParams {
225
+ /** 1-64 letters, digits and underscores, not starting with a digit. */
226
+ name: string;
227
+ type: TemplateVariableType;
228
+ required?: boolean;
229
+ /** Not for lists. */
230
+ default?: string | number | boolean;
231
+ description?: string;
232
+ /** Required for lists, only for lists. */
233
+ fields?: {
234
+ name: string;
235
+ type: TemplateScalarType;
236
+ required?: boolean;
237
+ }[];
238
+ }
239
+ /** One locale's subject, HTML and text templates. */
240
+ interface TemplateContent {
241
+ /** A BCP 47 language tag, e.g. `"en"` or `"pt-BR"`. */
242
+ locale: string;
243
+ subject: string;
244
+ html: string | null;
245
+ text: string | null;
246
+ }
247
+ /** One locale's templates. Provide `html`, `text`, or both. */
248
+ interface TemplateContentParams {
249
+ locale: string;
250
+ subject: string;
251
+ html?: string | null;
252
+ text?: string | null;
253
+ }
254
+ /** A problem that keeps a draft from being published, at a line and column of one field. */
255
+ interface TemplateProblem {
256
+ locale: string;
257
+ field: "subject" | "html" | "text";
258
+ message: string;
259
+ line: number;
260
+ column: number;
261
+ }
262
+ interface EmailTemplate {
263
+ object: "email_template";
264
+ id: string;
265
+ /** Send it by this name in any environment that has a template with the same alias. */
266
+ alias: string | null;
267
+ name: string;
268
+ description: string | null;
269
+ /** The version sends use; `null` until the draft is first published. */
270
+ published_version: number | null;
271
+ /** ISO 8601 timestamp, or `null`. */
272
+ published_at: string | null;
273
+ /** Whether the draft was changed since it was last published. */
274
+ has_unpublished_changes: boolean;
275
+ created_at: string;
276
+ updated_at: string;
277
+ }
278
+ /** A template's draft (`version: null`) or a published version (which never changes). */
279
+ interface EmailTemplateVersion {
280
+ object: "email_template_version";
281
+ template_id: string;
282
+ version: number | null;
283
+ /** Counts the draft's saves; pass it back to refuse overwriting someone else's changes. */
284
+ revision: number;
285
+ /** The locale sends fall back to. */
286
+ default_locale: string;
287
+ variables: TemplateVariable[];
288
+ /** Example values for previews and test sends. */
289
+ sample_variables: Record<string, unknown>;
290
+ contents: TemplateContent[];
291
+ /** Problems of a draft; always empty for published versions. */
292
+ problems: TemplateProblem[];
293
+ published_at: string | null;
294
+ created_at: string;
295
+ updated_at: string;
296
+ }
297
+ interface TemplateDraftParams {
298
+ /** Defaults to the first entry of `contents` (or `"en"`). */
299
+ default_locale?: string;
300
+ variables?: TemplateVariableParams[];
301
+ sample_variables?: Record<string, unknown>;
302
+ contents?: TemplateContentParams[];
303
+ }
304
+ /** Parameters of `coss.email.templates.create`. */
305
+ interface CreateEmailTemplateParams extends TemplateDraftParams {
306
+ name: string;
307
+ /** 1-64 lower-case letters, digits, `-` and `_`, e.g. `"welcome"`. */
308
+ alias?: string;
309
+ description?: string;
310
+ }
311
+ /** Parameters of `coss.email.templates.update`. */
312
+ interface UpdateEmailTemplateParams {
313
+ name?: string;
314
+ /** `null` removes the alias. */
315
+ alias?: string | null;
316
+ description?: string | null;
317
+ }
318
+ /** Parameters of `coss.email.templates.updateDraft`: replaces the whole draft. */
319
+ interface UpdateEmailTemplateDraftParams extends TemplateDraftParams {
320
+ /** The `revision` you read: refused (`template_revision_mismatch`) if the draft changed since. */
321
+ revision?: number;
322
+ }
323
+ /** Parameters of `coss.email.templates.publish`. */
324
+ interface PublishEmailTemplateParams {
325
+ /** The draft `revision` you reviewed: refused if the draft changed since. */
326
+ revision?: number;
327
+ }
328
+ interface ListEmailTemplatesParams {
329
+ /** 1-100, default 50. */
330
+ limit?: number;
331
+ /** Cursor: the `id` of the last template of the previous page. */
332
+ after?: string;
333
+ }
334
+ interface ListEmailTemplateVersionsParams {
335
+ /** 1-20, default 10. */
336
+ limit?: number;
337
+ /** Cursor: the `version` of the last version of the previous page. */
338
+ after?: number;
339
+ }
340
+ interface DeletedEmailTemplate {
341
+ object: "email_template";
342
+ id: string;
343
+ deleted: true;
344
+ }
345
+ /** The template an email was rendered from. */
346
+ interface EmailTemplateReference {
347
+ id: string;
348
+ /** `null` for a dashboard test send of the draft. */
349
+ version: number | null;
350
+ locale: string;
351
+ }
352
+ //#endregion
154
353
  //#region src/types/suppression.d.ts
155
354
  /** Suppression list wire types (hand-written mirrors of the API's schemas). */
156
355
  /**
157
356
  * Why an address is suppressed. `bounce`: a permanent bounce. `complaint`: a spam complaint.
158
357
  * `manual`: added one by one through the API or the dashboard. `import`: added by a bulk import.
358
+ * `unsubscribe`: the recipient's one-click unsubscribe, scoped to the email's category.
159
359
  */
160
- type SuppressionReason = "bounce" | "complaint" | "manual" | "import";
360
+ type SuppressionReason = "bounce" | "complaint" | "manual" | "import" | "unsubscribe";
161
361
  /** An entry of the API key's environment's suppression list. */
162
362
  interface Suppression {
163
363
  object: "suppression";
@@ -292,7 +492,7 @@ interface EmailRecipient {
292
492
  /** ISO 8601 timestamp of the latest event for this recipient, or `null`. */
293
493
  last_event_at: string | null;
294
494
  }
295
- type EmailEventType = "email.sent" | "email.delivered" | "email.delivery_delayed" | "email.bounced" | "email.complained" | "email.failed" | "email.suppressed" | "email.scheduled" | "email.canceled" | "email.opened" | "email.clicked" | "email.rescheduled";
495
+ type EmailEventType = "email.sent" | "email.delivered" | "email.delivery_delayed" | "email.bounced" | "email.complained" | "email.failed" | "email.suppressed" | "email.scheduled" | "email.canceled" | "email.opened" | "email.clicked" | "email.rescheduled" | "email.unsubscribed";
296
496
  /** Details of an event; which member is present depends on the event type. */
297
497
  interface EmailEventData {
298
498
  bounce?: {
@@ -367,23 +567,35 @@ interface TrackingOptions {
367
567
  /** Add an invisible pixel to the HTML body and record `email.opened` events. */
368
568
  opens?: boolean;
369
569
  /**
370
- * Send HTML links through a COSS redirect and record `email.clicked` events. Links with a
570
+ * Send HTML links through a coss.com redirect and record `email.clicked` events. Links with a
371
571
  * `data-coss-no-track` attribute are left alone.
372
572
  */
373
573
  clicks?: boolean;
574
+ /**
575
+ * Add one-click unsubscribe headers (`List-Unsubscribe` and `List-Unsubscribe-Post`, RFC 8058).
576
+ * An unsubscribe suppresses the recipient for this email's category and records
577
+ * `email.unsubscribed`. Needs a `category`, a single recipient, no `List-Unsubscribe` header of
578
+ * your own and at most 13 custom headers.
579
+ */
580
+ unsubscribe?: boolean;
374
581
  }
375
- /** Body of `POST /v1/emails`. */
376
- interface SendEmailParams {
582
+ /**
583
+ * A React element, such as `<WelcomeEmail name="Ada" />`. Described by its shape so the SDK needs
584
+ * no React types: any JSX element fits.
585
+ */
586
+ interface ReactEmailElement {
587
+ type: unknown;
588
+ props: unknown;
589
+ key: unknown;
590
+ }
591
+ /** What every send has, with or without a template. */
592
+ interface SendEmailBaseParams {
377
593
  /** `"you@example.com"` or `"Your Name <you@example.com>"`. */
378
594
  from: string;
379
595
  to: string | string[];
380
596
  cc?: string | string[];
381
597
  bcc?: string | string[];
382
598
  reply_to?: string | string[];
383
- subject: string;
384
- /** At least one of `html` or `text` is required. */
385
- html?: string;
386
- text?: string;
387
599
  /** Custom headers. Names are case-insensitive; reserved names such as `subject` are rejected. */
388
600
  headers?: Record<string, string>;
389
601
  tags?: EmailTag[];
@@ -402,6 +614,44 @@ interface SendEmailParams {
402
614
  attachments?: EmailAttachmentParams[];
403
615
  tracking?: TrackingOptions;
404
616
  }
617
+ /** A send with its own subject and body. */
618
+ interface SendEmailContentParams extends SendEmailBaseParams {
619
+ subject: string;
620
+ /** At least one of `html`, `text` or `react` is required. */
621
+ html?: string;
622
+ /** Without it, an `html` email goes out with a text part generated from the HTML. */
623
+ text?: string;
624
+ /**
625
+ * A [React Email](https://react.email) component, rendered by the SDK into `html` and, unless you
626
+ * pass `text`, into `text` too. Needs the optional peer dependency `@react-email/render`
627
+ * (`npm install @react-email/render`). Can't be combined with `html`; never sent to the API as is.
628
+ */
629
+ react?: ReactEmailElement;
630
+ template_id?: never;
631
+ template_version?: never;
632
+ locale?: never;
633
+ variables?: never;
634
+ }
635
+ /** A send of a published email template (`coss.email.templates`). */
636
+ interface SendEmailTemplateParams extends SendEmailBaseParams {
637
+ /** The template's id or alias. */
638
+ template_id: string;
639
+ /** A published version to send; defaults to the latest one. */
640
+ template_version?: number;
641
+ /**
642
+ * The locale to send, e.g. `"pt-BR"`. Falls back to the language (`"pt"`), then to the
643
+ * template's default locale.
644
+ */
645
+ locale?: string;
646
+ /** Values for the template's variables, keyed by name. */
647
+ variables?: Record<string, unknown>;
648
+ subject?: never;
649
+ html?: never;
650
+ text?: never;
651
+ react?: never;
652
+ }
653
+ /** A send: a subject and body (or `react`, which the SDK renders before sending), or a template. */
654
+ type SendEmailParams = SendEmailContentParams | SendEmailTemplateParams;
405
655
  /** Parameters of `coss.email.reschedule`. */
406
656
  interface RescheduleEmailParams {
407
657
  /**
@@ -417,6 +667,8 @@ interface RescheduleEmailParams {
417
667
  interface EmailTracking {
418
668
  opens: boolean;
419
669
  clicks: boolean;
670
+ /** Whether the email carries one-click unsubscribe headers (RFC 8058). */
671
+ unsubscribe: boolean;
420
672
  open_count: number;
421
673
  /** ISO 8601 timestamps, or `null`. */
422
674
  first_opened_at: string | null;
@@ -425,7 +677,7 @@ interface EmailTracking {
425
677
  first_clicked_at: string | null;
426
678
  last_clicked_at: string | null;
427
679
  }
428
- /** A link COSS rewrote for click tracking. */
680
+ /** A link coss.com rewrote for click tracking. */
429
681
  interface EmailLink {
430
682
  object: "email_link";
431
683
  id: string;
@@ -480,6 +732,8 @@ interface Email {
480
732
  scheduled_at: string | null;
481
733
  /** The batch that sent the email (`coss.email.sendBatch`), or `null` if it was sent alone. */
482
734
  batch_id: string | null;
735
+ /** The template the email was rendered from, or `null` if it was sent without one. */
736
+ template: EmailTemplateReference | null;
483
737
  }
484
738
  /** An email in a list (`coss.email.list`): everything but its content. */
485
739
  type EmailSummary = Omit<Email, "html" | "text" | "headers" | "attachments">;
@@ -517,19 +771,19 @@ interface EmailBatch {
517
771
  }
518
772
  //#endregion
519
773
  //#region src/resources/audit-events.d.ts
520
- type ReadOptions$12 = Pick<RequestOptions, "signal">;
774
+ type ReadOptions$17 = Pick<RequestOptions, "signal">;
521
775
  /**
522
776
  * `coss.auditEvents`: the organization's audit log, newest first: changes made by members, API
523
- * keys and COSS support. Organization-wide, whichever environment the key belongs to.
777
+ * keys and coss.com support. Organization-wide, whichever environment the key belongs to.
524
778
  */
525
779
  declare class AuditEventsResource {
526
780
  #private;
527
781
  /** @internal Use `new Coss().auditEvents`. */
528
782
  constructor(http: HttpClient);
529
783
  /** Lists audit events, newest first. Pass the last `id` as `after` while `has_more` is true. */
530
- list(params?: ListAuditEventsParams, options?: ReadOptions$12): Promise<CossResult<List<AuditEvent>>>;
784
+ list(params?: ListAuditEventsParams, options?: ReadOptions$17): Promise<CossResult<List<AuditEvent>>>;
531
785
  /** Retrieves one audit event. */
532
- get(id: string, options?: ReadOptions$12): Promise<CossResult<AuditEvent>>;
786
+ get(id: string, options?: ReadOptions$17): Promise<CossResult<AuditEvent>>;
533
787
  }
534
788
  //#endregion
535
789
  //#region src/types/billing.d.ts
@@ -538,7 +792,7 @@ declare class AuditEventsResource {
538
792
  * schemas). Amounts are integers in cents (USD); unit prices are dollar decimal strings.
539
793
  */
540
794
  type PlanKey = "free" | "pro" | "scale" | "enterprise";
541
- type Meter = "email.recipients" | "sms.segments" | "video.participant_minutes" | "scheduling.bookings";
795
+ type Meter = "email.recipients" | "email.dedicated_ip" | "sms.segments" | "video.participant_minutes" | "scheduling.bookings";
542
796
  type BillingHoldReason = "delinquent" | "spend_limit" | "admin";
543
797
  /** `GET /v1/billing`: the organization's plan, the current month so far, and its standing. */
544
798
  interface Billing {
@@ -596,12 +850,23 @@ interface Billing {
596
850
  brand: string | null;
597
851
  last4: string | null;
598
852
  } | null;
853
+ /** Add-ons of the contract in effect, charged on top of the plan. */
854
+ add_ons: {
855
+ /** e.g. `dedicated_ips`. */
856
+ key: string;
857
+ name: string;
858
+ quantity: number;
859
+ /** The price per unit and interval (cents). */
860
+ unit_amount: number;
861
+ interval: "month" | "quarter" | "year";
862
+ }[];
599
863
  features: {
600
864
  tracking_domains: boolean;
601
865
  audit_log: boolean;
602
866
  log_drains: boolean;
603
867
  sso: boolean;
604
868
  scim: boolean;
869
+ dedicated_ips: boolean;
605
870
  };
606
871
  /** Resource limits (`null`: unlimited). */
607
872
  limits: {
@@ -725,16 +990,16 @@ interface ListCreditsParams {
725
990
  }
726
991
  //#endregion
727
992
  //#region src/resources/billing.d.ts
728
- type ReadOptions$11 = Pick<RequestOptions, "signal">;
993
+ type ReadOptions$16 = Pick<RequestOptions, "signal">;
729
994
  /** `coss.billing.invoices`: the organization's invoices, newest first. */
730
995
  declare class BillingInvoicesResource {
731
996
  #private;
732
997
  /** @internal Use `new Coss().billing.invoices`. */
733
998
  constructor(http: HttpClient);
734
999
  /** Lists invoices (without lines). Pass the last `id` as `after` while `has_more` is true. */
735
- list(params?: ListInvoicesParams, options?: ReadOptions$11): Promise<CossResult<List<InvoiceSummary>>>;
1000
+ list(params?: ListInvoicesParams, options?: ReadOptions$16): Promise<CossResult<List<InvoiceSummary>>>;
736
1001
  /** Retrieves one invoice with its lines. */
737
- get(id: string, options?: ReadOptions$11): Promise<CossResult<Invoice>>;
1002
+ get(id: string, options?: ReadOptions$16): Promise<CossResult<Invoice>>;
738
1003
  }
739
1004
  /** `coss.billing.credits`: the organization's credits and what's left of them. */
740
1005
  declare class BillingCreditsResource {
@@ -742,7 +1007,7 @@ declare class BillingCreditsResource {
742
1007
  /** @internal Use `new Coss().billing.credits`. */
743
1008
  constructor(http: HttpClient);
744
1009
  /** Lists credits, newest first (usable ones by default). */
745
- list(params?: ListCreditsParams, options?: ReadOptions$11): Promise<CossResult<List<Credit>>>;
1010
+ list(params?: ListCreditsParams, options?: ReadOptions$16): Promise<CossResult<List<Credit>>>;
746
1011
  }
747
1012
  /**
748
1013
  * `coss.billing`: the organization's plan, usage, invoices and credits (read only; plan changes
@@ -755,9 +1020,9 @@ declare class BillingResource {
755
1020
  /** @internal Use `new Coss().billing`. */
756
1021
  constructor(http: HttpClient);
757
1022
  /** The plan, the current month's usage and estimate, standing and what the plan includes. */
758
- get(options?: ReadOptions$11): Promise<CossResult<Billing>>;
1023
+ get(options?: ReadOptions$16): Promise<CossResult<Billing>>;
759
1024
  /** Billable usage per meter and bucket (the current month, by day, by default), oldest first. */
760
- usage(params?: ListUsageParams, options?: ReadOptions$11): Promise<CossResult<List<Usage>>>;
1025
+ usage(params?: ListUsageParams, options?: ReadOptions$16): Promise<CossResult<List<Usage>>>;
761
1026
  }
762
1027
  //#endregion
763
1028
  //#region src/types/domain.d.ts
@@ -796,7 +1061,7 @@ interface DomainRecord {
796
1061
  found: string[];
797
1062
  }
798
1063
  /**
799
- * `pending` until the CNAME points at COSS and its certificate is issued, `active` once tracking
1064
+ * `pending` until the CNAME points at coss.com and its certificate is issued, `active` once tracking
800
1065
  * links of emails sent from the domain use it, `temporary_failure` when an active hostname stopped
801
1066
  * working (emails fall back to the default tracking host meanwhile), and `failed` when setup gave
802
1067
  * up (72 hours) — call `domains.verify` to start over. `deleting` is a removal in progress.
@@ -835,7 +1100,7 @@ interface ReceivingDomainRecord {
835
1100
  /** The mail exchange the record must point at. */
836
1101
  value: string;
837
1102
  priority: number;
838
- /** `verified` once the most preferred MX records point at COSS. */
1103
+ /** `verified` once the most preferred MX records point at coss.com. */
839
1104
  status: DomainRecordStatus;
840
1105
  /** What DNS returned when it did not match. */
841
1106
  found: string[];
@@ -850,6 +1115,39 @@ interface ReceivingDomain {
850
1115
  created_at: string;
851
1116
  last_checked_at: string | null;
852
1117
  }
1118
+ /**
1119
+ * `configured` when the BIMI record is valid and DMARC is enforced, `invalid` when a record exists
1120
+ * but something is wrong (see `issues`), `missing` when there is no record, and `not_checked` until
1121
+ * DNS has been consulted. coss.com checks DNS only: mailbox providers still validate the logo and the
1122
+ * certificate.
1123
+ */
1124
+ type BimiStatus = "not_checked" | "missing" | "invalid" | "configured";
1125
+ /** What keeps a domain's logo from showing, as far as DNS tells. */
1126
+ type BimiIssueCode = "dmarc_missing" | "dmarc_not_enforced" | "dmarc_partial" | "record_multiple" | "record_invalid" | "logo_missing" | "logo_not_https" | "certificate_missing" | "certificate_not_https";
1127
+ /** The last BIMI check of a domain (brand logos in inboxes; the certificate is your own). */
1128
+ interface DomainBimi {
1129
+ status: BimiStatus;
1130
+ /**
1131
+ * Where the BIMI record was found, or looked up when there is none: `default._bimi.<domain>`,
1132
+ * or the organizational domain's when only it has one.
1133
+ */
1134
+ name: string;
1135
+ /** The `v=BIMI1` record found. */
1136
+ record: string | null;
1137
+ /** The record's logo URL (`l=`). */
1138
+ logo_url: string | null;
1139
+ /** The record's VMC or CMC certificate URL (`a=`). */
1140
+ certificate_url: string | null;
1141
+ /**
1142
+ * The DMARC policy that applies to the domain (the organizational domain's `sp` when it has no
1143
+ * record of its own), `null` without a DMARC record.
1144
+ */
1145
+ dmarc_policy: "none" | "quarantine" | "reject" | null;
1146
+ issues: {
1147
+ code: BimiIssueCode;
1148
+ message: string;
1149
+ }[];
1150
+ }
853
1151
  /** A sending domain of the organization. */
854
1152
  interface Domain {
855
1153
  object: "domain";
@@ -874,6 +1172,8 @@ interface Domain {
874
1172
  tracking: TrackingDomain | null;
875
1173
  /** The receiving hostname, or `null` when the domain doesn't receive email. */
876
1174
  receiving: ReceivingDomain | null;
1175
+ /** The last BIMI check: whether mailbox providers can find the domain's brand logo. */
1176
+ bimi: DomainBimi;
877
1177
  }
878
1178
  /** Body of `POST /v1/domains`. */
879
1179
  interface CreateDomainParams {
@@ -900,6 +1200,201 @@ interface CreateReceivingDomainParams {
900
1200
  hostname: string;
901
1201
  }
902
1202
  //#endregion
1203
+ //#region src/types/dmarc.d.ts
1204
+ /** DMARC wire types (hand-written mirrors of the API's `DomainDmarc` and `DmarcReport` schemas). */
1205
+ type DmarcPolicy = "none" | "quarantine" | "reject";
1206
+ /** Where a domain is on the path from `p=none` to `p=reject`. */
1207
+ type DmarcStage = "not_checked" | "no_record" | "monitoring" | "quarantine" | "reject";
1208
+ /**
1209
+ * `publish` a first record, `add_reporting` (send reports to coss.com), `complete_rollout` (drop
1210
+ * `pct`/`t=y`) or `tighten` to the next policy.
1211
+ */
1212
+ type DmarcNextStepKind = "publish" | "add_reporting" | "complete_rollout" | "tighten";
1213
+ type DmarcCheckId = "coverage" | "recent" | "complete" | "time_at_policy" | "coss_pass_rate" | "pass_rate" | "sources";
1214
+ /** The DMARC record found at `_dmarc.<domain>` by the latest DNS check. */
1215
+ interface DmarcPublishedRecord {
1216
+ /** The `v=DMARC1` TXT record as published. */
1217
+ value: string;
1218
+ p: DmarcPolicy | null;
1219
+ sp: DmarcPolicy | null;
1220
+ np: DmarcPolicy | null;
1221
+ adkim: "r" | "s" | null;
1222
+ aspf: "r" | "s" | null;
1223
+ /** Removed by RFC 9989 but still honored by many receivers. */
1224
+ pct: number | null;
1225
+ t: "y" | "n" | null;
1226
+ /** Aggregate report addresses. */
1227
+ rua: string[];
1228
+ }
1229
+ /** Messages from one source IP with one From domain, over the report summary's period. */
1230
+ interface DmarcSource {
1231
+ source_ip: string;
1232
+ /** The domain in the messages' From header. */
1233
+ header_from: string;
1234
+ messages: number;
1235
+ /** Messages that passed DMARC. */
1236
+ passing: number;
1237
+ /** Signed with the domain's coss.com DKIM keys or sent from its coss.com MAIL FROM domain. */
1238
+ via_coss: boolean;
1239
+ }
1240
+ /** One readiness check gating `DomainDmarc.next`. */
1241
+ interface DmarcCheck {
1242
+ id: DmarcCheckId;
1243
+ ok: boolean;
1244
+ message: string;
1245
+ }
1246
+ /** The next step on the path to `p=reject`. */
1247
+ interface DmarcNextStep {
1248
+ kind: DmarcNextStepKind;
1249
+ policy: DmarcPolicy;
1250
+ /** The TXT record to publish at `_dmarc.<domain>`. */
1251
+ record: string;
1252
+ }
1253
+ /** A domain's DMARC status: its record, the guided next step and recent reports. */
1254
+ interface DomainDmarc {
1255
+ object: "domain_dmarc";
1256
+ domain_id: string;
1257
+ /** Where the domain's aggregate reports go; `null` when the deployment doesn't receive email. */
1258
+ report_address: string | null;
1259
+ /** The domain's own record. `null`: none found (or an invalid one), or DNS not checked yet. */
1260
+ record: DmarcPublishedRecord | null;
1261
+ /** The policy receivers apply: the domain's own, else its organizational domain's (`sp`, else `p`). */
1262
+ policy: DmarcPolicy | null;
1263
+ /** The organizational domain whose record applies, when the domain publishes none of its own. */
1264
+ inherited_from: string | null;
1265
+ /** ISO 8601 timestamp: when a DNS check first saw the current policy. */
1266
+ policy_since: string | null;
1267
+ stage: DmarcStage;
1268
+ /** The policy applies only partly (`pct` below 100, or `t=y`). */
1269
+ partial: boolean;
1270
+ /** The published record sends aggregate reports to `report_address`. */
1271
+ reporting: boolean;
1272
+ /** Whether `next` is safe to publish now. */
1273
+ ready: boolean;
1274
+ /** `null` at `p=reject`. */
1275
+ next: DmarcNextStep | null;
1276
+ checks: DmarcCheck[];
1277
+ warnings: string[];
1278
+ report_summary: {
1279
+ /** ISO 8601 timestamps of the summarized period (the last 14 days). */
1280
+ period_start: string;
1281
+ period_end: string;
1282
+ reports: number;
1283
+ messages: number;
1284
+ passing: number;
1285
+ coss_messages: number;
1286
+ coss_passing: number;
1287
+ first_report_at: string | null;
1288
+ last_report_at: string | null;
1289
+ /** The 50 sources with the most messages in the period. */
1290
+ sources: DmarcSource[];
1291
+ };
1292
+ }
1293
+ /** The policy a reporter found when it evaluated the mail. */
1294
+ interface DmarcPolicyPublished {
1295
+ domain: string;
1296
+ p: string | null;
1297
+ sp: string | null;
1298
+ np: string | null;
1299
+ adkim: string | null;
1300
+ aspf: string | null;
1301
+ pct: number | null;
1302
+ testing: string | null;
1303
+ }
1304
+ /** A DMARC aggregate report, without its rows (lists). */
1305
+ interface DmarcReportSummary {
1306
+ object: "dmarc_report";
1307
+ id: string;
1308
+ domain_id: string;
1309
+ reporter: {
1310
+ org_name: string;
1311
+ email: string | null;
1312
+ };
1313
+ /** The reporter's own id of the report. */
1314
+ report_id: string;
1315
+ /** ISO 8601 timestamps. */
1316
+ period_start: string;
1317
+ period_end: string;
1318
+ policy_published: DmarcPolicyPublished;
1319
+ messages: number;
1320
+ passing: number;
1321
+ /** The report listed more rows than are kept (10,000); totals cover the kept rows. */
1322
+ truncated: boolean;
1323
+ /** ISO 8601 timestamp. */
1324
+ received_at: string;
1325
+ }
1326
+ /** One row of a report: messages from one source IP with one outcome. */
1327
+ interface DmarcReportRecord {
1328
+ source_ip: string;
1329
+ count: number;
1330
+ /** What the receiver did with the messages. */
1331
+ disposition: DmarcPolicy;
1332
+ /** Aligned DKIM result. */
1333
+ dkim: "pass" | "fail";
1334
+ /** Aligned SPF result. */
1335
+ spf: "pass" | "fail";
1336
+ dmarc_pass: boolean;
1337
+ header_from: string;
1338
+ envelope_from: string | null;
1339
+ via_coss: boolean;
1340
+ auth_results: {
1341
+ dkim: {
1342
+ domain: string;
1343
+ selector: string | null;
1344
+ result: string;
1345
+ }[];
1346
+ spf: {
1347
+ domain: string;
1348
+ scope: string | null;
1349
+ result: string;
1350
+ }[];
1351
+ };
1352
+ reasons: {
1353
+ type: string;
1354
+ comment: string | null;
1355
+ }[];
1356
+ }
1357
+ /** A DMARC aggregate report with its rows. */
1358
+ interface DmarcReport extends DmarcReportSummary {
1359
+ records: DmarcReportRecord[];
1360
+ }
1361
+ /** Query of `coss.domains.dmarc.reports.list`. */
1362
+ interface ListDmarcReportsParams {
1363
+ /** 1-100, default 20. */
1364
+ limit?: number;
1365
+ /** The `id` of the last report of the previous page. */
1366
+ after?: string;
1367
+ }
1368
+ //#endregion
1369
+ //#region src/resources/dmarc.d.ts
1370
+ type ReadOptions$15 = Pick<RequestOptions, "signal">;
1371
+ /** `coss.domains.dmarc.reports`: the aggregate reports received about a domain. */
1372
+ declare class DmarcReportsResource {
1373
+ #private;
1374
+ /** @internal Use `new Coss().domains.dmarc.reports`. */
1375
+ constructor(http: HttpClient);
1376
+ /** Lists the domain's reports, newest first, without their rows. */
1377
+ list(domainId: string, params?: ListDmarcReportsParams, options?: ReadOptions$15): Promise<CossResult<List<DmarcReportSummary>>>;
1378
+ /** Retrieves one report with its rows. */
1379
+ get(domainId: string, reportId: string, options?: ReadOptions$15): Promise<CossResult<DmarcReport>>;
1380
+ }
1381
+ /**
1382
+ * `coss.domains.dmarc`: a domain's DMARC record, the guided path from `p=none` to `p=reject`, and
1383
+ * the aggregate reports mailbox providers send to its `report_address`.
1384
+ */
1385
+ declare class DmarcResource {
1386
+ #private;
1387
+ /** The domain's aggregate reports. */
1388
+ readonly reports: DmarcReportsResource;
1389
+ /** @internal Use `new Coss().domains.dmarc`. */
1390
+ constructor(http: HttpClient);
1391
+ /**
1392
+ * The domain's DMARC status: its published record, the record to publish next and whether
1393
+ * the last 14 days of reports say that is safe (`ready`), and a summary of those reports.
1394
+ */
1395
+ get(domainId: string, options?: ReadOptions$15): Promise<CossResult<DomainDmarc>>;
1396
+ }
1397
+ //#endregion
903
1398
  //#region src/resources/receiving-domains.d.ts
904
1399
  type DeleteOptions$1 = Pick<RequestOptions, "signal">;
905
1400
  /**
@@ -942,7 +1437,7 @@ declare class TrackingDomainsResource {
942
1437
  }
943
1438
  //#endregion
944
1439
  //#region src/resources/domains.d.ts
945
- type ReadOptions$10 = Pick<RequestOptions, "signal">;
1440
+ type ReadOptions$14 = Pick<RequestOptions, "signal">;
946
1441
  /**
947
1442
  * `coss.domains`: the domains live (`coss_live_…`) keys may send from. Domains belong to the
948
1443
  * organization, so every API key of the organization sees the same ones.
@@ -953,6 +1448,8 @@ declare class DomainsResource {
953
1448
  readonly tracking: TrackingDomainsResource;
954
1449
  /** Each domain's receiving hostname: start and stop receiving email at it. */
955
1450
  readonly receiving: ReceivingDomainsResource;
1451
+ /** Each domain's DMARC status, guidance and aggregate reports. */
1452
+ readonly dmarc: DmarcResource;
956
1453
  /** @internal Use `new Coss().domains`. */
957
1454
  constructor(http: HttpClient);
958
1455
  /**
@@ -961,9 +1458,9 @@ declare class DomainsResource {
961
1458
  */
962
1459
  create(params: CreateDomainParams, options?: RequestOptions): Promise<CossResult<Domain>>;
963
1460
  /** Lists the organization's domains, ordered by name. */
964
- list(options?: ReadOptions$10): Promise<CossResult<List<Domain>>>;
1461
+ list(options?: ReadOptions$14): Promise<CossResult<List<Domain>>>;
965
1462
  /** Retrieves a domain with the result of the last DNS check. */
966
- get(id: string, options?: ReadOptions$10): Promise<CossResult<Domain>>;
1463
+ get(id: string, options?: ReadOptions$14): Promise<CossResult<Domain>>;
967
1464
  /**
968
1465
  * Checks the domain's records now instead of waiting for the next background check. A `failed`
969
1466
  * domain starts verification over with fresh DKIM records, which have to be published again.
@@ -971,7 +1468,103 @@ declare class DomainsResource {
971
1468
  */
972
1469
  verify(id: string, options?: RequestOptions): Promise<CossResult<Domain>>;
973
1470
  /** Removes the domain. Emails already sent are unaffected; live keys can no longer use it. */
974
- delete(id: string, options?: ReadOptions$10): Promise<CossResult<DeletedDomain>>;
1471
+ delete(id: string, options?: ReadOptions$14): Promise<CossResult<DeletedDomain>>;
1472
+ }
1473
+ //#endregion
1474
+ //#region src/types/dedicated-ip.d.ts
1475
+ /** Dedicated IP wire types (hand-written mirrors of the API's `DedicatedIpPool` schema). */
1476
+ type DedicatedIpPoolStatus = "not_enabled" | "waiting" | "provisioning" | "warming" | "ready" | "releasing";
1477
+ /** `GET /v1/dedicated_ips`: the organization's dedicated IPs (the Dedicated IPs add-on). */
1478
+ interface DedicatedIpPool {
1479
+ object: "dedicated_ip_pool";
1480
+ /**
1481
+ * `warming`: live emails go through the pool while its IPs warm up (what they can't take yet
1482
+ * leaves from shared IPs); `ready`: at least 95% of the last 7 days' deliveries left from them.
1483
+ */
1484
+ status: DedicatedIpPoolStatus;
1485
+ /** The pool's IPs, with their deliveries in the last 7 days. */
1486
+ ips: {
1487
+ ip: string;
1488
+ delivered_7d: number;
1489
+ }[];
1490
+ /** Share (0–1) of the last 7 days' deliveries from the pool's IPs; `null` below 1,000. */
1491
+ dedicated_share: number | null;
1492
+ /** What is holding the pool up, if anything. */
1493
+ message: string | null;
1494
+ created_at: string | null;
1495
+ /** When it was first `ready`. */
1496
+ ready_at: string | null;
1497
+ }
1498
+ //#endregion
1499
+ //#region src/resources/dedicated-ips.d.ts
1500
+ type ReadOptions$13 = Pick<RequestOptions, "signal">;
1501
+ /**
1502
+ * `coss.email.dedicatedIps`: the organization's own sending IPs (the Dedicated IPs add-on),
1503
+ * managed and warmed up automatically.
1504
+ */
1505
+ declare class DedicatedIpsResource {
1506
+ #private;
1507
+ /** @internal Use `new Coss().email.dedicatedIps`. */
1508
+ constructor(http: HttpClient);
1509
+ /** The pool's status and IPs (`not_enabled` without the add-on). */
1510
+ get(options?: ReadOptions$13): Promise<CossResult<DedicatedIpPool>>;
1511
+ }
1512
+ //#endregion
1513
+ //#region src/resources/email-templates.d.ts
1514
+ type ReadOptions$12 = Pick<RequestOptions, "signal">;
1515
+ /** `coss.email.templates.versions`: a template's published versions. */
1516
+ declare class EmailTemplateVersionsResource {
1517
+ #private;
1518
+ /** @internal Use `new Coss().email.templates.versions`. */
1519
+ constructor(http: HttpClient);
1520
+ /** Published versions, newest first. */
1521
+ list(template: string, params?: ListEmailTemplateVersionsParams, options?: ReadOptions$12): Promise<CossResult<List<EmailTemplateVersion>>>;
1522
+ get(template: string, version: number, options?: ReadOptions$12): Promise<CossResult<EmailTemplateVersion>>;
1523
+ /**
1524
+ * Replaces the draft with this version's content; publish the draft to send it again. Never
1525
+ * automatically retried: every restore is a new draft revision, so a repeat could overwrite an
1526
+ * edit saved in between.
1527
+ */
1528
+ restore(template: string, version: number, options?: ReadOptions$12): Promise<CossResult<EmailTemplateVersion>>;
1529
+ }
1530
+ /**
1531
+ * `coss.email.templates`: the environment's email templates. Templates are addressed by id or
1532
+ * alias. Edit the draft, publish it, then send with `coss.email.send({ template_id, variables })`.
1533
+ */
1534
+ declare class EmailTemplatesResource {
1535
+ #private;
1536
+ /** Published versions. */
1537
+ readonly versions: EmailTemplateVersionsResource;
1538
+ /** @internal Use `new Coss().email.templates`. */
1539
+ constructor(http: HttpClient);
1540
+ /**
1541
+ * Creates a template and its draft. Never automatically retried: the API doesn't deduplicate it
1542
+ * (a template with an `alias` can't be created twice, though).
1543
+ */
1544
+ create(params: CreateEmailTemplateParams, options?: RequestOptions): Promise<CossResult<EmailTemplate>>;
1545
+ /** The environment's templates, newest first. */
1546
+ list(params?: ListEmailTemplatesParams, options?: ReadOptions$12): Promise<CossResult<List<EmailTemplate>>>;
1547
+ get(template: string, options?: ReadOptions$12): Promise<CossResult<EmailTemplate>>;
1548
+ /** Changes its name, alias or description. */
1549
+ update(template: string, params: UpdateEmailTemplateParams, options?: ReadOptions$12): Promise<CossResult<EmailTemplate>>;
1550
+ /** Deletes it with every version. Emails already sent keep their content. */
1551
+ delete(template: string, options?: ReadOptions$12): Promise<CossResult<DeletedEmailTemplate>>;
1552
+ /** The draft, with `problems` that keep it from being published. */
1553
+ getDraft(template: string, options?: ReadOptions$12): Promise<CossResult<EmailTemplateVersion>>;
1554
+ /**
1555
+ * Replaces the whole draft. Sends keep using the published version until you publish. Never
1556
+ * automatically retried: every save is a new revision, so a repeat whose first attempt was saved
1557
+ * would fail with `template_revision_mismatch` (or, without `revision`, overwrite an edit saved
1558
+ * in between). Read the draft again before retrying.
1559
+ */
1560
+ updateDraft(template: string, params: UpdateEmailTemplateDraftParams, options?: ReadOptions$12): Promise<CossResult<EmailTemplateVersion>>;
1561
+ /**
1562
+ * Publishes the draft as the next version, which sends use from then on. Automatically retried
1563
+ * only with a `revision`: a draft without changes since the last publish returns that version,
1564
+ * and one saved again since is refused. Without it, a retry could publish someone else's newer
1565
+ * edits as yet another version.
1566
+ */
1567
+ publish(template: string, params?: PublishEmailTemplateParams, options?: ReadOptions$12): Promise<CossResult<EmailTemplateVersion>>;
975
1568
  }
976
1569
  //#endregion
977
1570
  //#region src/types/received-email.d.ts
@@ -1063,7 +1656,7 @@ interface DeletedReceivedEmail {
1063
1656
  id: string;
1064
1657
  deleted: true;
1065
1658
  }
1066
- /** The environment's own domain under COSS's inbound domain: any address at it is received. */
1659
+ /** The environment's own domain under coss.com's inbound domain: any address at it is received. */
1067
1660
  interface InboundAddress {
1068
1661
  object: "inbound_address";
1069
1662
  environment_id: string;
@@ -1071,7 +1664,7 @@ interface InboundAddress {
1071
1664
  }
1072
1665
  //#endregion
1073
1666
  //#region src/resources/received-emails.d.ts
1074
- type ReadOptions$9 = Pick<RequestOptions, "signal">;
1667
+ type ReadOptions$11 = Pick<RequestOptions, "signal">;
1075
1668
  /**
1076
1669
  * `coss.email.received`: emails received by the API key's environment, at its inbound address
1077
1670
  * (`address()`) or at a receiving domain (`coss.domains.receiving`). An `email.received` webhook
@@ -1082,24 +1675,24 @@ declare class ReceivedEmailsResource {
1082
1675
  /** @internal Use `new Coss().email.received`. */
1083
1676
  constructor(http: HttpClient);
1084
1677
  /** Lists received emails, newest first, without bodies. Pass the last `id` as `after` while `has_more` is true. */
1085
- list(params?: ListReceivedEmailsParams, options?: ReadOptions$9): Promise<CossResult<List<ReceivedEmailSummary>>>;
1678
+ list(params?: ListReceivedEmailsParams, options?: ReadOptions$11): Promise<CossResult<List<ReceivedEmailSummary>>>;
1086
1679
  /** Retrieves a received email with its headers and bodies. */
1087
- get(id: string, options?: ReadOptions$9): Promise<CossResult<ReceivedEmail>>;
1680
+ get(id: string, options?: ReadOptions$11): Promise<CossResult<ReceivedEmail>>;
1088
1681
  /** The whole message as received (`message/rfc822` bytes). */
1089
- getRaw(id: string, options?: ReadOptions$9): Promise<CossResult<Uint8Array>>;
1682
+ getRaw(id: string, options?: ReadOptions$11): Promise<CossResult<Uint8Array>>;
1090
1683
  /** An attachment's bytes (untrusted: its declared type is the attachment's `content_type`). */
1091
- getAttachment(id: string, attachmentId: string, options?: ReadOptions$9): Promise<CossResult<Uint8Array>>;
1684
+ getAttachment(id: string, attachmentId: string, options?: ReadOptions$11): Promise<CossResult<Uint8Array>>;
1092
1685
  /**
1093
1686
  * The environment's inbound domain: email to any address at it (`support@<domain>`) is
1094
1687
  * received, with no DNS setup.
1095
1688
  */
1096
- address(options?: ReadOptions$9): Promise<CossResult<InboundAddress>>;
1689
+ address(options?: ReadOptions$11): Promise<CossResult<InboundAddress>>;
1097
1690
  /** Deletes a received email with its raw message and attachments right away. */
1098
- delete(id: string, options?: ReadOptions$9): Promise<CossResult<DeletedReceivedEmail>>;
1691
+ delete(id: string, options?: ReadOptions$11): Promise<CossResult<DeletedReceivedEmail>>;
1099
1692
  }
1100
1693
  //#endregion
1101
1694
  //#region src/resources/suppressions.d.ts
1102
- type ReadOptions$8 = Pick<RequestOptions, "signal">;
1695
+ type ReadOptions$10 = Pick<RequestOptions, "signal">;
1103
1696
  /**
1104
1697
  * `coss.email.suppressions`: the suppression list of the API key's environment. Sends skip
1105
1698
  * suppressed recipients; permanent bounces and complaints are added automatically.
@@ -1118,20 +1711,20 @@ declare class SuppressionResource {
1118
1711
  * and reported in `invalid`; entries already on the list count as `existing`. If a request
1119
1712
  * fails, the earlier batches stay imported: importing everything again is safe.
1120
1713
  */
1121
- import(params: ImportSuppressionsParams, options?: ReadOptions$8): Promise<CossResult<SuppressionImport>>;
1714
+ import(params: ImportSuppressionsParams, options?: ReadOptions$10): Promise<CossResult<SuppressionImport>>;
1122
1715
  /**
1123
1716
  * The whole list as CSV (`address,scope,reason,created_at,email_id,id`, oldest first), which
1124
1717
  * `import` (or the dashboard) accepts again.
1125
1718
  */
1126
- export(params?: ExportSuppressionsParams, options?: ReadOptions$8): Promise<CossResult<string>>;
1719
+ export(params?: ExportSuppressionsParams, options?: ReadOptions$10): Promise<CossResult<string>>;
1127
1720
  /** Lists entries, newest first. Pass the last `id` as `after` while `has_more` is true. */
1128
- list(params?: ListSuppressionsParams, options?: ReadOptions$8): Promise<CossResult<List<Suppression>>>;
1721
+ list(params?: ListSuppressionsParams, options?: ReadOptions$10): Promise<CossResult<List<Suppression>>>;
1129
1722
  /** Whether a send to `address` (with `category`, if given) would skip it. */
1130
- check(params: CheckSuppressionParams, options?: ReadOptions$8): Promise<CossResult<SuppressionCheck>>;
1723
+ check(params: CheckSuppressionParams, options?: ReadOptions$10): Promise<CossResult<SuppressionCheck>>;
1131
1724
  /** Retrieves one entry. */
1132
- get(id: string, options?: ReadOptions$8): Promise<CossResult<Suppression>>;
1725
+ get(id: string, options?: ReadOptions$10): Promise<CossResult<Suppression>>;
1133
1726
  /** Removes an entry, so later sends reach the address again (e.g. when a recipient resubscribes). */
1134
- remove(id: string, options?: ReadOptions$8): Promise<CossResult<DeletedSuppression>>;
1727
+ remove(id: string, options?: ReadOptions$10): Promise<CossResult<DeletedSuppression>>;
1135
1728
  }
1136
1729
  //#endregion
1137
1730
  //#region src/types/tracking.d.ts
@@ -1146,14 +1739,20 @@ interface TrackingRule {
1146
1739
  opens: boolean;
1147
1740
  /** Whether clicks are tracked. */
1148
1741
  clicks: boolean;
1742
+ /**
1743
+ * Whether emails get one-click unsubscribe headers (only emails with a category and a single
1744
+ * recipient).
1745
+ */
1746
+ unsubscribe: boolean;
1149
1747
  /** ISO 8601 timestamp. */
1150
1748
  created_at: string;
1151
1749
  /** ISO 8601 timestamp. */
1152
1750
  updated_at: string;
1153
1751
  }
1154
1752
  /**
1155
- * Open and click tracking settings of the API key's environment. For each of `opens` and
1156
- * `clicks`, a send's own `tracking` wins, then its category's rule, then `default`, then off.
1753
+ * Open and click tracking and one-click unsubscribe settings of the API key's environment. For
1754
+ * each of `opens`, `clicks` and `unsubscribe`, a send's own `tracking` wins, then its category's
1755
+ * rule, then `default`, then off.
1157
1756
  */
1158
1757
  interface TrackingSettings {
1159
1758
  object: "tracking_settings";
@@ -1164,11 +1763,13 @@ interface TrackingSettings {
1164
1763
  }
1165
1764
  /**
1166
1765
  * Body of `PATCH /v1/tracking_settings/default` and `…/categories/{category}`: at least one
1167
- * field. Fields left out keep their value; a new rule starts with both off.
1766
+ * field. Fields left out keep their value; a new rule starts with all off.
1168
1767
  */
1169
1768
  interface UpdateTrackingRuleParams {
1170
1769
  opens?: boolean;
1171
1770
  clicks?: boolean;
1771
+ /** Add one-click unsubscribe headers to emails with a category and a single recipient. */
1772
+ unsubscribe?: boolean;
1172
1773
  }
1173
1774
  /** Returned when a rule is removed. */
1174
1775
  interface DeletedTrackingRule {
@@ -1179,32 +1780,32 @@ interface DeletedTrackingRule {
1179
1780
  }
1180
1781
  //#endregion
1181
1782
  //#region src/resources/tracking.d.ts
1182
- type ReadOptions$7 = Pick<RequestOptions, "signal">;
1783
+ type ReadOptions$9 = Pick<RequestOptions, "signal">;
1183
1784
  /**
1184
1785
  * `coss.email.tracking`: which emails of the API key's environment have their opens and clicks
1185
- * tracked. Emails keep the settings that applied when they were sent; a send's own `tracking`
1186
- * option wins over them.
1786
+ * tracked and get one-click unsubscribe headers. Emails keep the settings that applied when they
1787
+ * were sent; a send's own `tracking` option wins over them.
1187
1788
  */
1188
1789
  declare class TrackingResource {
1189
1790
  #private;
1190
1791
  /** @internal Use `new Coss().email.tracking`. */
1191
1792
  constructor(http: HttpClient);
1192
1793
  /** The environment default and the category rules. */
1193
- get(options?: ReadOptions$7): Promise<CossResult<TrackingSettings>>;
1794
+ get(options?: ReadOptions$9): Promise<CossResult<TrackingSettings>>;
1194
1795
  /**
1195
1796
  * Sets the environment default, which applies to emails without a rule for their category.
1196
1797
  * Fields left out keep their value; a new default starts with both off.
1197
1798
  */
1198
- updateDefault(params: UpdateTrackingRuleParams, options?: ReadOptions$7): Promise<CossResult<TrackingRule>>;
1799
+ updateDefault(params: UpdateTrackingRuleParams, options?: ReadOptions$9): Promise<CossResult<TrackingRule>>;
1199
1800
  /** Removes the environment default: emails without a category rule are then not tracked. */
1200
- removeDefault(options?: ReadOptions$7): Promise<CossResult<DeletedTrackingRule>>;
1801
+ removeDefault(options?: ReadOptions$9): Promise<CossResult<DeletedTrackingRule>>;
1201
1802
  /**
1202
1803
  * Sets the rule for emails sent with `category`, which wins over the default. Fields left out
1203
1804
  * keep their value; a new rule starts with both off.
1204
1805
  */
1205
- updateCategory(category: string, params: UpdateTrackingRuleParams, options?: ReadOptions$7): Promise<CossResult<TrackingRule>>;
1806
+ updateCategory(category: string, params: UpdateTrackingRuleParams, options?: ReadOptions$9): Promise<CossResult<TrackingRule>>;
1206
1807
  /** Removes a category's rule: its emails follow the environment default again. */
1207
- removeCategory(category: string, options?: ReadOptions$7): Promise<CossResult<DeletedTrackingRule>>;
1808
+ removeCategory(category: string, options?: ReadOptions$9): Promise<CossResult<DeletedTrackingRule>>;
1208
1809
  }
1209
1810
  //#endregion
1210
1811
  //#region src/resources/email.d.ts
@@ -1217,13 +1818,19 @@ declare class EmailResource {
1217
1818
  readonly tracking: TrackingResource;
1218
1819
  /** Emails the environment received. */
1219
1820
  readonly received: ReceivedEmailsResource;
1821
+ /** The environment's email templates. */
1822
+ readonly templates: EmailTemplatesResource;
1823
+ /** The organization's dedicated IPs. */
1824
+ readonly dedicatedIps: DedicatedIpsResource;
1220
1825
  /** @internal Use `new Coss().email`. */
1221
1826
  constructor(http: HttpClient);
1222
1827
  /**
1223
- * Sends an email. It is returned `queued` and handed to the delivery provider moments later:
1828
+ * Sends an email, with its own subject and body or from a published template (`template_id`
1829
+ * and `variables`). It is returned `queued` and handed to the delivery provider moments later:
1224
1830
  * `get` it or listen for the `email.sent` / `email.failed` webhooks for the outcome. Safe to
1225
1831
  * retry: the request always carries an `Idempotency-Key` (yours, or a generated one reused
1226
- * across automatic retries), so the API never sends it twice.
1832
+ * across automatic retries), so the API never sends it twice. A `react` component is rendered
1833
+ * once, before the first attempt.
1227
1834
  */
1228
1835
  send(params: SendEmailParams, options?: RequestOptions): Promise<CossResult<Email>>;
1229
1836
  /**
@@ -1233,6 +1840,8 @@ declare class EmailResource {
1233
1840
  * the whole batch. Larger lists need several calls, each with its own key.
1234
1841
  */
1235
1842
  sendBatch(emails: SendEmailParams[], options?: RequestOptions): Promise<CossResult<EmailBatch>>;
1843
+ /** Retrieves a batch sent by `sendBatch`, with its emails' current statuses in request order. */
1844
+ getBatch(id: string, options?: Pick<RequestOptions, "signal">): Promise<CossResult<EmailBatch>>;
1236
1845
  /** Retrieves an email sent from the same environment as the API key. */
1237
1846
  get(id: string, options?: Pick<RequestOptions, "signal">): Promise<CossResult<Email>>;
1238
1847
  /**
@@ -1258,10 +1867,21 @@ declare class EmailResource {
1258
1867
  listLinks(id: string, options?: Pick<RequestOptions, "signal">): Promise<CossResult<List<EmailLink>>>;
1259
1868
  }
1260
1869
  //#endregion
1870
+ //#region src/resources/environment.d.ts
1871
+ type ReadOptions$8 = Pick<RequestOptions, "signal">;
1872
+ /** `coss.environment`: which environment, project and organization the API key belongs to. */
1873
+ declare class EnvironmentResource {
1874
+ #private;
1875
+ /** @internal Use `new Coss().environment`. */
1876
+ constructor(http: HttpClient);
1877
+ /** The API key's environment, its project and organization, and the key itself. */
1878
+ get(options?: ReadOptions$8): Promise<CossResult<Environment>>;
1879
+ }
1880
+ //#endregion
1261
1881
  //#region src/types/hooks.d.ts
1262
1882
  /**
1263
1883
  * Hooks wire types (webhooks as a service): you send a message to one of your applications once,
1264
- * COSS delivers it to every endpoint its users registered, signed, with retries.
1884
+ * coss.com delivers it to every endpoint its users registered, signed, with retries.
1265
1885
  */
1266
1886
  /** One of your customers (or users), with their own endpoints and portal. */
1267
1887
  interface HookApplication {
@@ -1418,7 +2038,7 @@ interface RecoverHookEndpointParams {
1418
2038
  /** Requeue failed deliveries of messages sent since then (ISO 8601 string or `Date`). */
1419
2039
  since: string | Date;
1420
2040
  }
1421
- /** A recovery: COSS requeues the matching failed deliveries in the background. */
2041
+ /** A recovery: coss.com requeues the matching failed deliveries in the background. */
1422
2042
  interface HookEndpointRecovery {
1423
2043
  object: "hook_endpoint_recovery";
1424
2044
  id: string;
@@ -1530,7 +2150,7 @@ interface HookPortalSession {
1530
2150
  }
1531
2151
  //#endregion
1532
2152
  //#region src/resources/hooks.d.ts
1533
- type ReadOptions$6 = Pick<RequestOptions, "signal">;
2153
+ type ReadOptions$7 = Pick<RequestOptions, "signal">;
1534
2154
  /** `coss.hooks.applications`: your customers, each with their own endpoints and portal. */
1535
2155
  declare class HookApplicationsResource {
1536
2156
  #private;
@@ -1539,12 +2159,12 @@ declare class HookApplicationsResource {
1539
2159
  /** Creates an application. Never automatically retried (the API does not deduplicate it). */
1540
2160
  create(params: CreateHookApplicationParams, options?: RequestOptions): Promise<CossResult<HookApplication>>;
1541
2161
  /** Lists the environment's applications, newest first. */
1542
- list(params?: ListHookApplicationsParams, options?: ReadOptions$6): Promise<CossResult<List<HookApplication>>>;
2162
+ list(params?: ListHookApplicationsParams, options?: ReadOptions$7): Promise<CossResult<List<HookApplication>>>;
1543
2163
  /** Retrieves an application by its id or uid. */
1544
- get(application: string, options?: ReadOptions$6): Promise<CossResult<HookApplication>>;
1545
- update(application: string, params: UpdateHookApplicationParams, options?: ReadOptions$6): Promise<CossResult<HookApplication>>;
2164
+ get(application: string, options?: ReadOptions$7): Promise<CossResult<HookApplication>>;
2165
+ update(application: string, params: UpdateHookApplicationParams, options?: ReadOptions$7): Promise<CossResult<HookApplication>>;
1546
2166
  /** Deletes the application with its endpoints and portal sessions. */
1547
- delete(application: string, options?: ReadOptions$6): Promise<CossResult<DeletedHookApplication>>;
2167
+ delete(application: string, options?: ReadOptions$7): Promise<CossResult<DeletedHookApplication>>;
1548
2168
  }
1549
2169
  /** `coss.hooks.eventTypes`: the catalog of messages you send, which your users subscribe from. */
1550
2170
  declare class HookEventTypesResource {
@@ -1554,12 +2174,12 @@ declare class HookEventTypesResource {
1554
2174
  /** Creates an event type. Never automatically retried (a retry would find it existing). */
1555
2175
  create(params: CreateHookEventTypeParams, options?: RequestOptions): Promise<CossResult<HookEventType>>;
1556
2176
  /** Lists event types by name (archived ones only with `include_archived`). */
1557
- list(params?: ListHookEventTypesParams, options?: ReadOptions$6): Promise<CossResult<List<HookEventType>>>;
1558
- get(name: string, options?: ReadOptions$6): Promise<CossResult<HookEventType>>;
2177
+ list(params?: ListHookEventTypesParams, options?: ReadOptions$7): Promise<CossResult<List<HookEventType>>>;
2178
+ get(name: string, options?: ReadOptions$7): Promise<CossResult<HookEventType>>;
1559
2179
  /** Changes its description, schema or examples, or archives or restores it. */
1560
- update(name: string, params: UpdateHookEventTypeParams, options?: ReadOptions$6): Promise<CossResult<HookEventType>>;
2180
+ update(name: string, params: UpdateHookEventTypeParams, options?: ReadOptions$7): Promise<CossResult<HookEventType>>;
1561
2181
  /** Archives it: hidden from the portal and new subscriptions. */
1562
- archive(name: string, options?: ReadOptions$6): Promise<CossResult<HookEventType>>;
2182
+ archive(name: string, options?: ReadOptions$7): Promise<CossResult<HookEventType>>;
1563
2183
  }
1564
2184
  /** `coss.hooks.endpoints`: an application's endpoints (usually added by its users in the portal). */
1565
2185
  declare class HookEndpointsResource {
@@ -1568,23 +2188,23 @@ declare class HookEndpointsResource {
1568
2188
  constructor(http: HttpClient);
1569
2189
  /** Creates an endpoint; the result carries its secret. Never automatically retried. */
1570
2190
  create(application: string, params: CreateHookEndpointParams, options?: RequestOptions): Promise<CossResult<HookEndpointWithSecret>>;
1571
- list(application: string, options?: ReadOptions$6): Promise<CossResult<List<HookEndpoint>>>;
1572
- get(application: string, id: string, options?: ReadOptions$6): Promise<CossResult<HookEndpoint>>;
1573
- update(application: string, id: string, params: UpdateHookEndpointParams, options?: ReadOptions$6): Promise<CossResult<HookEndpoint>>;
1574
- delete(application: string, id: string, options?: ReadOptions$6): Promise<CossResult<DeletedHookEndpoint>>;
2191
+ list(application: string, options?: ReadOptions$7): Promise<CossResult<List<HookEndpoint>>>;
2192
+ get(application: string, id: string, options?: ReadOptions$7): Promise<CossResult<HookEndpoint>>;
2193
+ update(application: string, id: string, params: UpdateHookEndpointParams, options?: ReadOptions$7): Promise<CossResult<HookEndpoint>>;
2194
+ delete(application: string, id: string, options?: ReadOptions$7): Promise<CossResult<DeletedHookEndpoint>>;
1575
2195
  /** The endpoint's current signing secret. */
1576
- getSecret(application: string, id: string, options?: ReadOptions$6): Promise<CossResult<HookEndpointSecret>>;
2196
+ getSecret(application: string, id: string, options?: ReadOptions$7): Promise<CossResult<HookEndpointSecret>>;
1577
2197
  /** Replaces the signing secret. Never automatically retried (a second roll would stop the first). */
1578
2198
  rollSecret(application: string, id: string, params?: RollHookEndpointSecretParams, options?: RequestOptions): Promise<CossResult<HookEndpointWithSecret>>;
1579
2199
  /** Requeues the endpoint's failed deliveries of messages sent since `since` (in the background). */
1580
2200
  recover(application: string, id: string, params: RecoverHookEndpointParams, options?: RequestOptions): Promise<CossResult<HookEndpointRecovery>>;
1581
- getRecovery(application: string, id: string, recoveryId: string, options?: ReadOptions$6): Promise<CossResult<HookEndpointRecovery>>;
2201
+ getRecovery(application: string, id: string, recoveryId: string, options?: ReadOptions$7): Promise<CossResult<HookEndpointRecovery>>;
1582
2202
  /** Sends a message to this endpoint only. Never automatically retried. */
1583
2203
  sendTest(application: string, id: string, params: SendHookTestParams, options?: RequestOptions): Promise<CossResult<HookMessage>>;
1584
2204
  /** The endpoint's deliveries, newest first. */
1585
- listDeliveries(application: string, id: string, params?: ListHookDeliveriesParams, options?: ReadOptions$6): Promise<CossResult<List<HookDelivery>>>;
2205
+ listDeliveries(application: string, id: string, params?: ListHookDeliveriesParams, options?: ReadOptions$7): Promise<CossResult<List<HookDelivery>>>;
1586
2206
  }
1587
- /** `coss.hooks.messages`: send a message once; COSS delivers it to every subscribed endpoint. */
2207
+ /** `coss.hooks.messages`: send a message once; coss.com delivers it to every subscribed endpoint. */
1588
2208
  declare class HookMessagesResource {
1589
2209
  #private;
1590
2210
  /** @internal Use `new Coss().hooks.messages`. */
@@ -1595,19 +2215,19 @@ declare class HookMessagesResource {
1595
2215
  */
1596
2216
  send(params: SendHookMessageParams, options?: RequestOptions): Promise<CossResult<HookMessage>>;
1597
2217
  /** The application's messages, newest first. */
1598
- list(application: string, params?: ListHookMessagesParams, options?: ReadOptions$6): Promise<CossResult<List<HookMessage>>>;
1599
- get(application: string, id: string, options?: ReadOptions$6): Promise<CossResult<HookMessage>>;
2218
+ list(application: string, params?: ListHookMessagesParams, options?: ReadOptions$7): Promise<CossResult<List<HookMessage>>>;
2219
+ get(application: string, id: string, options?: ReadOptions$7): Promise<CossResult<HookMessage>>;
1600
2220
  /** One delivery per endpoint the message went to. */
1601
- listDeliveries(application: string, id: string, options?: ReadOptions$6): Promise<CossResult<List<HookDelivery>>>;
2221
+ listDeliveries(application: string, id: string, options?: ReadOptions$7): Promise<CossResult<List<HookDelivery>>>;
1602
2222
  }
1603
2223
  /** `coss.hooks.deliveries`: one message's delivery to one endpoint. */
1604
2224
  declare class HookDeliveriesResource {
1605
2225
  #private;
1606
2226
  /** @internal Use `new Coss().hooks.deliveries`. */
1607
2227
  constructor(http: HttpClient);
1608
- get(application: string, id: string, options?: ReadOptions$6): Promise<CossResult<HookDelivery>>;
2228
+ get(application: string, id: string, options?: ReadOptions$7): Promise<CossResult<HookDelivery>>;
1609
2229
  /** Every HTTP request of the delivery, oldest first. */
1610
- listAttempts(application: string, id: string, options?: ReadOptions$6): Promise<CossResult<List<HookAttempt>>>;
2230
+ listAttempts(application: string, id: string, options?: ReadOptions$7): Promise<CossResult<List<HookAttempt>>>;
1611
2231
  /** Queues a finished delivery for one more attempt. Never automatically retried. */
1612
2232
  retry(application: string, id: string, options?: RequestOptions): Promise<CossResult<HookDelivery>>;
1613
2233
  }
@@ -1624,7 +2244,7 @@ declare class HookPortalResource {
1624
2244
  }
1625
2245
  /**
1626
2246
  * `coss.hooks`: webhooks as a service. Send a message to one of your applications once
1627
- * (`coss.hooks.messages.send`); COSS delivers it to every endpoint its users registered, signed
2247
+ * (`coss.hooks.messages.send`); coss.com delivers it to every endpoint its users registered, signed
1628
2248
  * (Standard Webhooks), with retries, and gives them a portal to manage it all.
1629
2249
  */
1630
2250
  declare class HooksResource {
@@ -1644,7 +2264,7 @@ declare class HooksResource {
1644
2264
  * `api`: a request to the API. `email`: an email event. `webhook`: a webhook delivery attempt.
1645
2265
  * `risk`: a risk assessment or its feedback.
1646
2266
  */
1647
- type LogSource = "api" | "email" | "webhook" | "risk";
2267
+ type LogSource = "api" | "email" | "webhook" | "risk" | "smtp";
1648
2268
  /**
1649
2269
  * `error`: 5xx responses, bounces, complaints, failures. `warning`: 4xx responses, delays,
1650
2270
  * suppressions, failed webhook attempts that will be retried. `info`: everything else.
@@ -1658,7 +2278,7 @@ interface Log {
1658
2278
  occurred_at: string;
1659
2279
  source: LogSource;
1660
2280
  level: LogLevel;
1661
- /** `api.request`, `webhook.attempt`, or an email event type such as `email.delivered`. */
2281
+ /** `api.request`, `webhook.attempt`, `webhook.forward` (`coss listen`), or an email event type such as `email.delivered`. */
1662
2282
  type: string;
1663
2283
  /** A one-line summary. */
1664
2284
  message: string;
@@ -1730,7 +2350,7 @@ interface LogDrain {
1730
2350
  sources: LogDrainSource[];
1731
2351
  /** A disabled drain receives nothing, and lines logged meanwhile are not kept for it. */
1732
2352
  enabled: boolean;
1733
- /** `manual`, or `failing`: a batch failed every attempt, so COSS disabled it. */
2353
+ /** `manual`, or `failing`: a batch failed every attempt, so coss.com disabled it. */
1734
2354
  disabled_reason: "manual" | "failing" | null;
1735
2355
  /** ISO 8601 timestamp; `null` while enabled. */
1736
2356
  disabled_at: string | null;
@@ -1747,7 +2367,7 @@ interface DeletedLogDrain {
1747
2367
  deleted: true;
1748
2368
  }
1749
2369
  interface CreateLogDrainParams {
1750
- /** An `https://` URL COSS posts batches to. */
2370
+ /** An `https://` URL coss.com posts batches to. */
1751
2371
  url: string;
1752
2372
  description?: string | null;
1753
2373
  /** Defaults to every source. */
@@ -1805,16 +2425,16 @@ interface ListLogDrainBatchesParams {
1805
2425
  type LogDrainLine = Log | AuditEvent;
1806
2426
  //#endregion
1807
2427
  //#region src/resources/log-drains.d.ts
1808
- type ReadOptions$5 = Pick<RequestOptions, "signal">;
2428
+ type ReadOptions$6 = Pick<RequestOptions, "signal">;
1809
2429
  /** `coss.logDrains.batches`: a drain's delivery log, each batch with every HTTP attempt. */
1810
2430
  declare class LogDrainBatchesResource {
1811
2431
  #private;
1812
2432
  /** @internal Use `new Coss().logDrains.batches`. */
1813
2433
  constructor(http: HttpClient);
1814
2434
  /** Lists the drain's batches, newest first. Pass the last `id` as `after` while `has_more` is true. */
1815
- list(drainId: string, params?: ListLogDrainBatchesParams, options?: ReadOptions$5): Promise<CossResult<List<LogDrainBatch>>>;
2435
+ list(drainId: string, params?: ListLogDrainBatchesParams, options?: ReadOptions$6): Promise<CossResult<List<LogDrainBatch>>>;
1816
2436
  /** Retrieves one batch of the drain. */
1817
- get(drainId: string, id: string, options?: ReadOptions$5): Promise<CossResult<LogDrainBatch>>;
2437
+ get(drainId: string, id: string, options?: ReadOptions$6): Promise<CossResult<LogDrainBatch>>;
1818
2438
  }
1819
2439
  /**
1820
2440
  * `coss.logDrains`: HTTPS endpoints the environment's log is streamed to (API requests, email
@@ -1835,21 +2455,21 @@ declare class LogDrainsResource {
1835
2455
  */
1836
2456
  create(params: CreateLogDrainParams, options?: RequestOptions): Promise<CossResult<LogDrainWithSecret>>;
1837
2457
  /** Lists the environment's drains, oldest first. Secrets are never included. */
1838
- list(options?: ReadOptions$5): Promise<CossResult<List<LogDrain>>>;
2458
+ list(options?: ReadOptions$6): Promise<CossResult<List<LogDrain>>>;
1839
2459
  /** Retrieves a drain of the API key's environment. */
1840
- get(id: string, options?: ReadOptions$5): Promise<CossResult<LogDrain>>;
2460
+ get(id: string, options?: ReadOptions$6): Promise<CossResult<LogDrain>>;
1841
2461
  /**
1842
2462
  * Changes the URL, description, sources or `enabled` flag. The signing secret stays the same.
1843
- * Disabling drops the lines still waiting for the drain; enabling it again (also after COSS
2463
+ * Disabling drops the lines still waiting for the drain; enabling it again (also after coss.com
1844
2464
  * disabled it for failing) sends lines logged from then on.
1845
2465
  */
1846
- update(id: string, params: UpdateLogDrainParams, options?: ReadOptions$5): Promise<CossResult<LogDrain>>;
2466
+ update(id: string, params: UpdateLogDrainParams, options?: ReadOptions$6): Promise<CossResult<LogDrain>>;
1847
2467
  /** Deletes the drain and its batch log. To pause it instead, update `enabled` to false. */
1848
- delete(id: string, options?: ReadOptions$5): Promise<CossResult<DeletedLogDrain>>;
2468
+ delete(id: string, options?: ReadOptions$6): Promise<CossResult<DeletedLogDrain>>;
1849
2469
  }
1850
2470
  //#endregion
1851
2471
  //#region src/resources/logs.d.ts
1852
- type ReadOptions$4 = Pick<RequestOptions, "signal">;
2472
+ type ReadOptions$5 = Pick<RequestOptions, "signal">;
1853
2473
  /**
1854
2474
  * `coss.logs`: the API key's environment log, newest first: API requests made with its keys,
1855
2475
  * email events and webhook delivery attempts.
@@ -1862,9 +2482,9 @@ declare class LogsResource {
1862
2482
  * Lists log lines, newest first (the last hour unless `from`/`to` say otherwise). Pass the last
1863
2483
  * `id` as `after` while `has_more` is true.
1864
2484
  */
1865
- list(params?: ListLogsParams, options?: ReadOptions$4): Promise<CossResult<List<Log>>>;
2485
+ list(params?: ListLogsParams, options?: ReadOptions$5): Promise<CossResult<List<Log>>>;
1866
2486
  /** Retrieves one log line. */
1867
- get(id: string, options?: ReadOptions$4): Promise<CossResult<Log>>;
2487
+ get(id: string, options?: ReadOptions$5): Promise<CossResult<Log>>;
1868
2488
  }
1869
2489
  //#endregion
1870
2490
  //#region src/types/reputation.d.ts
@@ -1891,7 +2511,7 @@ interface ReputationCheck {
1891
2511
  interface Reputation {
1892
2512
  object: "reputation";
1893
2513
  /**
1894
- * `suspended` means live sending is refused (`account_suspended`) until COSS support
2514
+ * `suspended` means live sending is refused (`account_suspended`) until coss.com support
1895
2515
  * reinstates the organization; sandbox keys keep working.
1896
2516
  */
1897
2517
  status: ReputationStatus;
@@ -1910,9 +2530,9 @@ interface Reputation {
1910
2530
  }
1911
2531
  //#endregion
1912
2532
  //#region src/resources/reputation.d.ts
1913
- type ReadOptions$3 = Pick<RequestOptions, "signal">;
2533
+ type ReadOptions$4 = Pick<RequestOptions, "signal">;
1914
2534
  /**
1915
- * `coss.reputation`: the organization's standing with the COSS reputation guard, which suspends
2535
+ * `coss.reputation`: the organization's standing with the coss.com reputation guard, which suspends
1916
2536
  * live sending automatically when bounce or complaint rates cross its thresholds.
1917
2537
  */
1918
2538
  declare class ReputationResource {
@@ -1920,7 +2540,7 @@ declare class ReputationResource {
1920
2540
  /** @internal Use `new Coss().reputation`. */
1921
2541
  constructor(http: HttpClient);
1922
2542
  /** The current status and the latest rates measured over live environments. */
1923
- get(options?: ReadOptions$3): Promise<CossResult<Reputation>>;
2543
+ get(options?: ReadOptions$4): Promise<CossResult<Reputation>>;
1924
2544
  }
1925
2545
  //#endregion
1926
2546
  //#region src/types/risk.d.ts
@@ -2013,7 +2633,7 @@ interface RiskIpSignals {
2013
2633
  /** ISO 3166-1 alpha-2. */
2014
2634
  country: string | null;
2015
2635
  /**
2016
- * From COSS's IP privacy data provider; `null` when it isn't available or was not asked
2636
+ * From coss.com's IP privacy data provider; `null` when it isn't available or was not asked
2017
2637
  * (private addresses).
2018
2638
  */
2019
2639
  privacy: RiskIpPrivacy | null;
@@ -2346,7 +2966,7 @@ interface DeletedRiskRule {
2346
2966
  id: string;
2347
2967
  deleted: true;
2348
2968
  }
2349
- /** Result of `coss.risk.checkEmail()`: what COSS knows about an address. Nothing is stored. */
2969
+ /** Result of `coss.risk.checkEmail()`: what coss.com knows about an address. Nothing is stored. */
2350
2970
  interface RiskEmailCheck {
2351
2971
  object: "risk_email_check";
2352
2972
  email: string;
@@ -2383,7 +3003,7 @@ interface RiskContentClassification {
2383
3003
  /** The text was longer than the model reads (8,000 characters): only its beginning counted. */
2384
3004
  truncated: boolean;
2385
3005
  }
2386
- /** What `on_failure` answers while COSS can't count. */
3006
+ /** What `on_failure` answers while coss.com can't count. */
2387
3007
  type RiskLimitFailureMode = "allow" | "deny";
2388
3008
  /** One of your rate limit buckets: each key gets `burst` tokens, refilling `limit` per period. */
2389
3009
  interface RiskLimitBucket {
@@ -2425,7 +3045,7 @@ interface DeletedRiskLimitBucket {
2425
3045
  interface CheckRiskLimitParams {
2426
3046
  /** The bucket's name. */
2427
3047
  bucket: string;
2428
- /** Who or what is limited (a user id, an email or IP address…); COSS keeps only a hash. */
3048
+ /** Who or what is limited (a user id, an email or IP address…); coss.com keeps only a hash. */
2429
3049
  key: string;
2430
3050
  /** Tokens this request takes. Default 1. */
2431
3051
  cost?: number;
@@ -2444,24 +3064,24 @@ interface RiskLimit {
2444
3064
  reset_ms: number;
2445
3065
  /** When denied: milliseconds until the same request would fit; `null` if it never would. */
2446
3066
  retry_after_ms: number | null;
2447
- /** COSS couldn't count: `allowed` is the bucket's `on_failure`. */
3067
+ /** coss.com couldn't count: `allowed` is the bucket's `on_failure`. */
2448
3068
  degraded: boolean;
2449
3069
  }
2450
3070
  //#endregion
2451
3071
  //#region src/resources/risk.d.ts
2452
- type ReadOptions$2 = Pick<RequestOptions, "signal">;
3072
+ type ReadOptions$3 = Pick<RequestOptions, "signal">;
2453
3073
  /** `coss.risk.assessments`: reading past assessments (`assess` lives on `coss.risk`). */
2454
3074
  declare class RiskAssessmentsResource {
2455
3075
  #private;
2456
3076
  /** @internal Use `new Coss().risk.assessments`. */
2457
3077
  constructor(http: HttpClient);
2458
3078
  /** Retrieves one assessment. */
2459
- get(id: string, options?: ReadOptions$2): Promise<CossResult<RiskAssessment>>;
3079
+ get(id: string, options?: ReadOptions$3): Promise<CossResult<RiskAssessment>>;
2460
3080
  /**
2461
3081
  * Lists assessments, newest first (`review_status: "open"` is the review queue). Pass the last
2462
3082
  * `id` as `after` while `has_more` is true.
2463
3083
  */
2464
- list(params?: ListRiskAssessmentsParams, options?: ReadOptions$2): Promise<CossResult<List<RiskAssessment>>>;
3084
+ list(params?: ListRiskAssessmentsParams, options?: ReadOptions$3): Promise<CossResult<List<RiskAssessment>>>;
2465
3085
  }
2466
3086
  /** `coss.risk.lists`: the environment's allow and block lists. */
2467
3087
  declare class RiskListsResource {
@@ -2477,20 +3097,20 @@ declare class RiskListsResource {
2477
3097
  expires_at?: string | Date;
2478
3098
  }, options?: RequestOptions): Promise<CossResult<RiskListEntry>>;
2479
3099
  /** Lists entries, newest first. Pass the last `id` as `after` while `has_more` is true. */
2480
- list(params?: ListRiskListEntriesParams, options?: ReadOptions$2): Promise<CossResult<List<RiskListEntry>>>;
3100
+ list(params?: ListRiskListEntriesParams, options?: ReadOptions$3): Promise<CossResult<List<RiskListEntry>>>;
2481
3101
  /** Retrieves one entry. */
2482
- get(id: string, options?: ReadOptions$2): Promise<CossResult<RiskListEntry>>;
3102
+ get(id: string, options?: ReadOptions$3): Promise<CossResult<RiskListEntry>>;
2483
3103
  /** Removes an entry. */
2484
- remove(id: string, options?: ReadOptions$2): Promise<CossResult<DeletedRiskListEntry>>;
3104
+ remove(id: string, options?: ReadOptions$3): Promise<CossResult<DeletedRiskListEntry>>;
2485
3105
  }
2486
3106
  /** `coss.risk.settings`: the environment's thresholds, disabled reasons and captcha provider. */
2487
3107
  declare class RiskSettingsResource {
2488
3108
  #private;
2489
3109
  /** @internal Use `new Coss().risk.settings`. */
2490
3110
  constructor(http: HttpClient);
2491
- get(options?: ReadOptions$2): Promise<CossResult<RiskSettings>>;
3111
+ get(options?: ReadOptions$3): Promise<CossResult<RiskSettings>>;
2492
3112
  /** Changes the fields given. The captcha secret is write-only. */
2493
- update(params: UpdateRiskSettingsParams, options?: ReadOptions$2): Promise<CossResult<RiskSettings>>;
3113
+ update(params: UpdateRiskSettingsParams, options?: ReadOptions$3): Promise<CossResult<RiskSettings>>;
2494
3114
  }
2495
3115
  /**
2496
3116
  * `coss.risk.rules`: the environment's rules. After the lists, the first enabled rule whose
@@ -2501,13 +3121,13 @@ declare class RiskRulesResource {
2501
3121
  /** @internal Use `new Coss().risk.rules`. */
2502
3122
  constructor(http: HttpClient);
2503
3123
  /** Creates a rule. Not retried automatically: a retry could create it twice. */
2504
- create(params: CreateRiskRuleParams, options?: ReadOptions$2): Promise<CossResult<RiskRule>>;
3124
+ create(params: CreateRiskRuleParams, options?: ReadOptions$3): Promise<CossResult<RiskRule>>;
2505
3125
  /** Every rule, in evaluation order. */
2506
- list(options?: ReadOptions$2): Promise<CossResult<List<RiskRule>>>;
2507
- get(id: string, options?: ReadOptions$2): Promise<CossResult<RiskRule>>;
3126
+ list(options?: ReadOptions$3): Promise<CossResult<List<RiskRule>>>;
3127
+ get(id: string, options?: ReadOptions$3): Promise<CossResult<RiskRule>>;
2508
3128
  /** Changes the fields given; `conditions` replaces the whole list. */
2509
- update(id: string, params: UpdateRiskRuleParams, options?: ReadOptions$2): Promise<CossResult<RiskRule>>;
2510
- delete(id: string, options?: ReadOptions$2): Promise<CossResult<DeletedRiskRule>>;
3129
+ update(id: string, params: UpdateRiskRuleParams, options?: ReadOptions$3): Promise<CossResult<RiskRule>>;
3130
+ delete(id: string, options?: ReadOptions$3): Promise<CossResult<DeletedRiskRule>>;
2511
3131
  }
2512
3132
  /**
2513
3133
  * `coss.risk.limitBuckets`: your rate limit buckets, which `coss.risk.limit()` charges per key.
@@ -2517,24 +3137,24 @@ declare class RiskLimitBucketsResource {
2517
3137
  /** @internal Use `new Coss().risk.limitBuckets`. */
2518
3138
  constructor(http: HttpClient);
2519
3139
  /** Creates a bucket. Not retried automatically: a retry would find its name taken. */
2520
- create(params: CreateRiskLimitBucketParams, options?: ReadOptions$2): Promise<CossResult<RiskLimitBucket>>;
3140
+ create(params: CreateRiskLimitBucketParams, options?: ReadOptions$3): Promise<CossResult<RiskLimitBucket>>;
2521
3141
  /** Every bucket, by name. */
2522
- list(options?: ReadOptions$2): Promise<CossResult<List<RiskLimitBucket>>>;
2523
- get(id: string, options?: ReadOptions$2): Promise<CossResult<RiskLimitBucket>>;
3142
+ list(options?: ReadOptions$3): Promise<CossResult<List<RiskLimitBucket>>>;
3143
+ get(id: string, options?: ReadOptions$3): Promise<CossResult<RiskLimitBucket>>;
2524
3144
  /** Changes the fields given; the next check uses them. */
2525
- update(id: string, params: UpdateRiskLimitBucketParams, options?: ReadOptions$2): Promise<CossResult<RiskLimitBucket>>;
2526
- delete(id: string, options?: ReadOptions$2): Promise<CossResult<DeletedRiskLimitBucket>>;
3145
+ update(id: string, params: UpdateRiskLimitBucketParams, options?: ReadOptions$3): Promise<CossResult<RiskLimitBucket>>;
3146
+ delete(id: string, options?: ReadOptions$3): Promise<CossResult<DeletedRiskLimitBucket>>;
2527
3147
  }
2528
- /** `coss.risk.users`: what COSS remembers about your users. */
3148
+ /** `coss.risk.users`: what coss.com remembers about your users. */
2529
3149
  declare class RiskUsersResource {
2530
3150
  #private;
2531
3151
  /** @internal Use `new Coss().risk.users`. */
2532
3152
  constructor(http: HttpClient);
2533
3153
  /**
2534
- * Call when you delete a user: COSS deletes what identifies them (their mailbox, fraud reports,
3154
+ * Call when you delete a user: coss.com deletes what identifies them (their mailbox, fraud reports,
2535
3155
  * and the user id, email, IP and user agent on their assessments). Safe to repeat.
2536
3156
  */
2537
- forget(userId: string, options?: ReadOptions$2): Promise<CossResult<ForgottenRiskUser>>;
3157
+ forget(userId: string, options?: ReadOptions$3): Promise<CossResult<ForgottenRiskUser>>;
2538
3158
  }
2539
3159
  /**
2540
3160
  * `coss.risk`: assess sign-ups, logins and other events. Call it from your server and treat an
@@ -2576,24 +3196,24 @@ declare class RiskResource {
2576
3196
  * How often each reason and rule was right over the last 90 days, by your feedback, and the
2577
3197
  * reason weights that supports. Apply them with `settings.update({ reason_weights })`.
2578
3198
  */
2579
- calibration(options?: ReadOptions$2): Promise<CossResult<RiskCalibration>>;
3199
+ calibration(options?: ReadOptions$3): Promise<CossResult<RiskCalibration>>;
2580
3200
  /**
2581
3201
  * Checks an email address on its own: syntax, disposable domains, deliverability, role
2582
3202
  * accounts, free providers, the canonical mailbox, typos and domain age. Nothing is stored.
2583
3203
  */
2584
- checkEmail(email: string, options?: ReadOptions$2): Promise<CossResult<RiskEmailCheck>>;
3204
+ checkEmail(email: string, options?: ReadOptions$3): Promise<CossResult<RiskEmailCheck>>;
2585
3205
  /**
2586
3206
  * Checks an IP address on its own: Tor, cloud, hosting and VPN networks, ASN and country, and
2587
- * VPN, proxy and relay exits when COSS's privacy data is available.
3207
+ * VPN, proxy and relay exits when coss.com's privacy data is available.
2588
3208
  */
2589
- checkIp(ip: string, options?: ReadOptions$2): Promise<CossResult<RiskIpCheck>>;
3209
+ checkIp(ip: string, options?: ReadOptions$3): Promise<CossResult<RiskIpCheck>>;
2590
3210
  /**
2591
3211
  * Scores text for spam, phishing, malware and fraud. Scores only, never a verdict: you choose
2592
3212
  * the thresholds. The text is neither stored nor logged.
2593
3213
  */
2594
3214
  classify(params: {
2595
3215
  text: string;
2596
- }, options?: ReadOptions$2): Promise<CossResult<RiskContentClassification>>;
3216
+ }, options?: ReadOptions$3): Promise<CossResult<RiskContentClassification>>;
2597
3217
  /**
2598
3218
  * Takes `cost` tokens (default 1) from `key`'s share of one of your buckets
2599
3219
  * (`coss.risk.limitBuckets`). Retries reuse one `Idempotency-Key`, so they are charged once.
@@ -2667,6 +3287,36 @@ interface ReceivedEmailWebhookEvent {
2667
3287
  created_at: string;
2668
3288
  data: ReceivedEmailWebhookEventData;
2669
3289
  }
3290
+ /** Events about the organization's domains (sent to live environments only). */
3291
+ type DomainEventType = "domain.dmarc_report_received";
3292
+ /** What a webhook says about a DMARC report; never its rows or source addresses. */
3293
+ interface DomainWebhookEventData {
3294
+ organization_id: string;
3295
+ domain_id: string;
3296
+ domain: string;
3297
+ /** Retrieve the report (its rows) with `coss.domains.dmarc.reports.get`. */
3298
+ dmarc_report_id: string;
3299
+ /** The reporting organization (`org_name`). */
3300
+ reporter: string;
3301
+ /** ISO 8601 timestamps of the period the report covers. */
3302
+ period_start: string;
3303
+ period_end: string;
3304
+ messages: number;
3305
+ passing: number;
3306
+ /** ISO 8601 timestamp. */
3307
+ occurred_at: string;
3308
+ }
3309
+ /** A DMARC aggregate report about a domain arrived. `id` equals the `webhook-id` header. */
3310
+ interface DomainWebhookEvent {
3311
+ id: string;
3312
+ object: "event";
3313
+ type: DomainEventType;
3314
+ /** The API version this event is rendered in: the receiving endpoint's `api_version`. */
3315
+ api_version: string;
3316
+ /** ISO 8601 timestamp. */
3317
+ created_at: string;
3318
+ data: DomainWebhookEventData;
3319
+ }
2670
3320
  /** Changes of the organization's reputation standing (sent to live environments only). */
2671
3321
  type AccountEventType = "account.reputation_warning" | "account.reputation_recovered" | "account.suspended" | "account.reinstated";
2672
3322
  interface AccountWebhookEventData {
@@ -2811,11 +3461,11 @@ interface HookEndpointWebhookEvent {
2811
3461
  data: HookEndpointWebhookEventData;
2812
3462
  }
2813
3463
  /** The JSON body of a webhook request; narrow on `type`. */
2814
- type WebhookEvent = EmailWebhookEvent | ReceivedEmailWebhookEvent | AccountWebhookEvent | BillingWebhookEvent | RiskWebhookEvent | HookEndpointWebhookEvent;
3464
+ type WebhookEvent = EmailWebhookEvent | ReceivedEmailWebhookEvent | DomainWebhookEvent | AccountWebhookEvent | BillingWebhookEvent | RiskWebhookEvent | HookEndpointWebhookEvent;
2815
3465
  //#endregion
2816
3466
  //#region src/types/webhook-endpoint.d.ts
2817
3467
  /** Every event type an endpoint can subscribe to. */
2818
- type WebhookEventType = EmailEventType | ReceivedEmailEventType | AccountEventType | BillingEventType | RiskEventType | HookOperationalEventType;
3468
+ type WebhookEventType = EmailEventType | ReceivedEmailEventType | DomainEventType | AccountEventType | BillingEventType | RiskEventType | HookOperationalEventType;
2819
3469
  /** Why an endpoint is disabled. */
2820
3470
  type WebhookEndpointDisabledReason = "manual" | "failing";
2821
3471
  /** A URL of the API key's environment that receives signed event notifications. */
@@ -2835,7 +3485,7 @@ interface WebhookEndpoint {
2835
3485
  enabled: boolean;
2836
3486
  /**
2837
3487
  * `manual`: someone disabled it. `failing`: its deliveries failed every attempt for five days,
2838
- * so COSS disabled it. `null` while enabled.
3488
+ * so coss.com disabled it. `null` while enabled.
2839
3489
  */
2840
3490
  disabled_reason: WebhookEndpointDisabledReason | null;
2841
3491
  /** When it was disabled (ISO 8601); `null` while enabled. */
@@ -2864,7 +3514,7 @@ interface WebhookEndpointWithSecret extends WebhookEndpoint {
2864
3514
  }
2865
3515
  /** Body of `POST /v1/webhook_endpoints`. */
2866
3516
  interface CreateWebhookEndpointParams {
2867
- /** An `https://` URL COSS posts events to. */
3517
+ /** An `https://` URL coss.com posts events to. */
2868
3518
  url: string;
2869
3519
  /** A note for your own reference. */
2870
3520
  description?: string | null;
@@ -2970,7 +3620,7 @@ interface ListWebhookDeliveriesParams {
2970
3620
  }
2971
3621
  //#endregion
2972
3622
  //#region src/resources/webhook-deliveries.d.ts
2973
- type ReadOptions$1 = Pick<RequestOptions, "signal">;
3623
+ type ReadOptions$2 = Pick<RequestOptions, "signal">;
2974
3624
  /**
2975
3625
  * `coss.webhookEndpoints.deliveries`: an endpoint's delivery log. Each delivery carries every
2976
3626
  * HTTP attempt and the payload as sent.
@@ -2980,9 +3630,9 @@ declare class WebhookDeliveriesResource {
2980
3630
  /** @internal Use `new Coss().webhookEndpoints.deliveries`. */
2981
3631
  constructor(http: HttpClient);
2982
3632
  /** Lists the endpoint's deliveries, newest first. Pass the last `id` as `after` while `has_more` is true. */
2983
- list(endpointId: string, params?: ListWebhookDeliveriesParams, options?: ReadOptions$1): Promise<CossResult<List<WebhookDelivery>>>;
3633
+ list(endpointId: string, params?: ListWebhookDeliveriesParams, options?: ReadOptions$2): Promise<CossResult<List<WebhookDelivery>>>;
2984
3634
  /** Retrieves one delivery of the endpoint. */
2985
- get(endpointId: string, id: string, options?: ReadOptions$1): Promise<CossResult<WebhookDelivery>>;
3635
+ get(endpointId: string, id: string, options?: ReadOptions$2): Promise<CossResult<WebhookDelivery>>;
2986
3636
  /**
2987
3637
  * Queues a finished delivery for one more attempt, made within seconds. A delivery that is
2988
3638
  * still `pending` is returned unchanged (it is already scheduled for `next_attempt_at`).
@@ -2993,7 +3643,7 @@ declare class WebhookDeliveriesResource {
2993
3643
  }
2994
3644
  //#endregion
2995
3645
  //#region src/resources/webhook-endpoints.d.ts
2996
- type ReadOptions = Pick<RequestOptions, "signal">;
3646
+ type ReadOptions$1 = Pick<RequestOptions, "signal">;
2997
3647
  /**
2998
3648
  * `coss.webhookEndpoints`: the URLs that receive signed event notifications. Endpoints belong to
2999
3649
  * the API key's own environment, so a `coss_test_…` key only ever manages sandbox endpoints.
@@ -3012,14 +3662,14 @@ declare class WebhookEndpointsResource {
3012
3662
  */
3013
3663
  create(params: CreateWebhookEndpointParams, options?: RequestOptions): Promise<CossResult<WebhookEndpointWithSecret>>;
3014
3664
  /** Lists the environment's endpoints, oldest first. Secrets are never included. */
3015
- list(options?: ReadOptions): Promise<CossResult<List<WebhookEndpoint>>>;
3665
+ list(options?: ReadOptions$1): Promise<CossResult<List<WebhookEndpoint>>>;
3016
3666
  /** Retrieves an endpoint of the API key's environment. */
3017
- get(id: string, options?: ReadOptions): Promise<CossResult<WebhookEndpoint>>;
3667
+ get(id: string, options?: ReadOptions$1): Promise<CossResult<WebhookEndpoint>>;
3018
3668
  /**
3019
3669
  * Changes the URL, description, subscribed event types or `enabled` flag. The signing secret
3020
3670
  * stays the same (see `rollSecret`), so receivers keep verifying deliveries.
3021
3671
  */
3022
- update(id: string, params: UpdateWebhookEndpointParams, options?: ReadOptions): Promise<CossResult<WebhookEndpoint>>;
3672
+ update(id: string, params: UpdateWebhookEndpointParams, options?: ReadOptions$1): Promise<CossResult<WebhookEndpoint>>;
3023
3673
  /**
3024
3674
  * Replaces the endpoint's signing secret; the result carries the new `secret`. Until
3025
3675
  * `previous_secret_expires_at` (a day by default), deliveries are signed with both secrets, so
@@ -3035,7 +3685,100 @@ declare class WebhookEndpointsResource {
3035
3685
  */
3036
3686
  recover(id: string, params: RecoverWebhookEndpointParams, options?: RequestOptions): Promise<CossResult<WebhookEndpointRecovery>>;
3037
3687
  /** Deletes the endpoint and its delivery log. To pause it instead, update `enabled` to false. */
3038
- delete(id: string, options?: ReadOptions): Promise<CossResult<DeletedWebhookEndpoint>>;
3688
+ delete(id: string, options?: ReadOptions$1): Promise<CossResult<DeletedWebhookEndpoint>>;
3689
+ }
3690
+ //#endregion
3691
+ //#region src/types/webhook-listener.d.ts
3692
+ /** A temporary subscriber of the API key's environment, open while it is polled. */
3693
+ interface WebhookListener {
3694
+ object: "webhook_listener";
3695
+ id: string;
3696
+ /** The API version events are rendered in. */
3697
+ api_version: string;
3698
+ /** Empty: every event type. */
3699
+ event_types: string[];
3700
+ description: string | null;
3701
+ /** When it closes unless polled again (every poll moves it 10 minutes ahead). */
3702
+ expires_at: string;
3703
+ created_at: string;
3704
+ }
3705
+ /** One event handed out by a poll, to forward and acknowledge. */
3706
+ interface WebhookListenerDelivery {
3707
+ object: "webhook_listener_delivery";
3708
+ id: string;
3709
+ /** Send it back in the acknowledgement. */
3710
+ ack_token: string;
3711
+ /** The event's id: the body's `id`, and the `webhook-id` header endpoints receive. */
3712
+ event_id: string;
3713
+ event_type: string;
3714
+ /** How many polls have handed it out (more than 1 after an unacknowledged answer). */
3715
+ attempt: number;
3716
+ /** The event body, exactly as an endpoint would receive it: forward these bytes. */
3717
+ body: string;
3718
+ created_at: string;
3719
+ }
3720
+ /** Answer of `POST /v1/webhook_listeners/{id}/poll`. */
3721
+ interface WebhookListenerPoll {
3722
+ object: "webhook_listener_poll";
3723
+ listener: WebhookListener;
3724
+ /** Oldest first; empty when nothing arrived while the poll waited. */
3725
+ deliveries: WebhookListenerDelivery[];
3726
+ /** How many of the request's acknowledgements were recorded. */
3727
+ acknowledged: number;
3728
+ }
3729
+ interface DeletedWebhookListener {
3730
+ object: "webhook_listener";
3731
+ id: string;
3732
+ deleted: true;
3733
+ }
3734
+ /** Body of `POST /v1/webhook_listeners`. */
3735
+ interface CreateWebhookListenerParams {
3736
+ /** Defaults to every event type. */
3737
+ event_types?: WebhookEventType[];
3738
+ /** Defaults to the client's `apiVersion`. */
3739
+ api_version?: ApiVersion;
3740
+ /** Where the events go, for your own reference (shown in the log). */
3741
+ description?: string | null;
3742
+ }
3743
+ /** What happened to one delivery handed out earlier. */
3744
+ interface WebhookListenerAck {
3745
+ delivery_id: string;
3746
+ ack_token: string;
3747
+ /** The local server's status; `null` when nothing answered, or the event was only printed. */
3748
+ status_code: number | null;
3749
+ duration_ms: number;
3750
+ /** Why forwarding failed; `null` if it didn't. */
3751
+ error: string | null;
3752
+ }
3753
+ /** Body of `POST /v1/webhook_listeners/{id}/poll`. */
3754
+ interface PollWebhookListenerParams {
3755
+ acks?: WebhookListenerAck[];
3756
+ /** How long to wait for events, in milliseconds (default 20000, at most 25000). */
3757
+ wait_ms?: number;
3758
+ /** The most deliveries to hand out (default 10, at most 50). */
3759
+ limit?: number;
3760
+ }
3761
+ //#endregion
3762
+ //#region src/resources/webhook-listeners.d.ts
3763
+ type ReadOptions = Pick<RequestOptions, "signal">;
3764
+ /**
3765
+ * `coss.webhookListeners`: what `coss listen` uses to forward an environment's events to a local
3766
+ * server. A listener receives events created after it opens, while it is polled; it is closed by
3767
+ * `delete` or after 10 minutes without a poll.
3768
+ */
3769
+ declare class WebhookListenersResource {
3770
+ #private;
3771
+ /** @internal Use `new Coss().webhookListeners`. */
3772
+ constructor(http: HttpClient);
3773
+ /** Opens a listener. Never retried automatically: a lost answer leaves one to expire. */
3774
+ create(params?: CreateWebhookListenerParams, options?: ReadOptions): Promise<CossResult<WebhookListener>>;
3775
+ /**
3776
+ * Acknowledges earlier deliveries and waits (up to `wait_ms`) for more. Never retried
3777
+ * automatically: call it in a loop, and keep unacknowledged acks for the next call after an error.
3778
+ */
3779
+ poll(id: string, params?: PollWebhookListenerParams, options?: ReadOptions): Promise<CossResult<WebhookListenerPoll>>;
3780
+ /** Closes a listener: it receives nothing more. */
3781
+ delete(id: string, options?: ReadOptions): Promise<CossResult<DeletedWebhookListener>>;
3039
3782
  }
3040
3783
  //#endregion
3041
3784
  //#region src/client.d.ts
@@ -3062,7 +3805,7 @@ interface CossOptions {
3062
3805
  dangerouslyAllowBrowser?: boolean;
3063
3806
  }
3064
3807
  /**
3065
- * The COSS client. One API key covers every product.
3808
+ * The coss.com client. One API key covers every product.
3066
3809
  *
3067
3810
  * ```ts
3068
3811
  * const coss = new Coss({ apiKey: "coss_test_…" });
@@ -3071,17 +3814,23 @@ interface CossOptions {
3071
3814
  */
3072
3815
  export declare class Coss {
3073
3816
  readonly email: EmailResource;
3817
+ /** The API key's environment, project and organization (`coss.environment.get()`). */
3818
+ readonly environment: EnvironmentResource;
3819
+ /** The client's own API key (`coss.apiKey.revoke()`). */
3820
+ readonly apiKey: ApiKeyResource;
3074
3821
  /** Sending domains of the organization (`coss.domains.create`, `.verify`, …). */
3075
3822
  readonly domains: DomainsResource;
3076
3823
  /** Webhook endpoints of the API key's environment. */
3077
3824
  readonly webhookEndpoints: WebhookEndpointsResource;
3825
+ /** Temporary listeners `coss listen` pulls the environment's events from. */
3826
+ readonly webhookListeners: WebhookListenersResource;
3078
3827
  /** The organization's sending reputation (`coss.reputation.get()`). */
3079
3828
  readonly reputation: ReputationResource;
3080
3829
  /** The environment's log: API requests, email events, webhook attempts (`coss.logs.list()`). */
3081
3830
  readonly logs: LogsResource;
3082
3831
  /** HTTPS endpoints the environment's log is streamed to (`coss.logDrains.create()`). */
3083
3832
  readonly logDrains: LogDrainsResource;
3084
- /** The organization's audit log: changes by members, API keys and COSS support (`coss.auditEvents.list()`). */
3833
+ /** The organization's audit log: changes by members, API keys and coss.com support (`coss.auditEvents.list()`). */
3085
3834
  readonly auditEvents: AuditEventsResource;
3086
3835
  /** Hooks, webhooks as a service: `coss.hooks.messages.send()` delivers to your users' endpoints. */
3087
3836
  readonly hooks: HooksResource;
@@ -3098,7 +3847,7 @@ export declare class Coss {
3098
3847
  //#endregion
3099
3848
  //#region src/version.d.ts
3100
3849
  /** SDK version, sent in the User-Agent. A test keeps it equal to package.json's `version`. */
3101
- export declare const VERSION = "0.3.0";
3850
+ export declare const VERSION = "0.4.0";
3102
3851
  //#endregion
3103
3852
  //#region src/webhooks.d.ts
3104
3853
  /** A webhook request failed verification: reject it (e.g. respond 400). */
@@ -3122,7 +3871,7 @@ interface VerifyWebhookOptions {
3122
3871
  * const event = await verifyWebhook(await request.text(), request.headers, process.env.COSS_WEBHOOK_SECRET);
3123
3872
  * ```
3124
3873
  *
3125
- * The same check verifies messages your own users receive from COSS Hooks (`coss.hooks`): pass
3874
+ * The same check verifies messages your own users receive from coss.com Hooks (`coss.hooks`): pass
3126
3875
  * the endpoint's secret and name your payload type, e.g. `verifyWebhook<InvoicePaid>(…)`.
3127
3876
  */
3128
3877
  export declare function verifyWebhook<T = WebhookEvent>(payload: string, headers: WebhookHeaders, secret: string, options?: VerifyWebhookOptions): Promise<T>;
@@ -3139,4 +3888,4 @@ export declare function verifyWebhook<T = WebhookEvent>(payload: string, headers
3139
3888
  */
3140
3889
  export declare function verifyLogDrainBatch(payload: string, headers: WebhookHeaders, secret: string, options?: VerifyWebhookOptions): Promise<LogDrainLine[]>;
3141
3890
  //#endregion
3142
- export type { AccountEventType, AccountWebhookEvent, AccountWebhookEventData, ApiVersion, AssessRiskParams, AuditActorType, AuditEvent, AuditEventsResource, Billing, BillingCreditsResource, BillingEventType, BillingHoldReason, BillingInvoicesResource, BillingResource, BillingWebhookEvent, CheckRiskLimitParams, CheckSuppressionParams, CossError, CossErrorIssue, CossErrorType, CossOptions, CossResult, CreateDomainParams, CreateHookApplicationParams, CreateHookEndpointParams, CreateHookEventTypeParams, CreateHookPortalSessionParams, CreateLogDrainParams, CreateReceivingDomainParams, CreateRiskLimitBucketParams, CreateRiskListEntryParams, CreateRiskRuleParams, CreateSuppressionParams, CreateTrackingDomainParams, CreateWebhookEndpointParams, Credit, DeletedDomain, DeletedHookApplication, DeletedHookEndpoint, DeletedLogDrain, DeletedReceivedEmail, DeletedRiskLimitBucket, DeletedRiskListEntry, DeletedRiskRule, DeletedSuppression, DeletedTrackingRule, DeletedWebhookEndpoint, Domain, DomainRecord, DomainRecordPurpose, DomainRecordStatus, DomainStatus, DomainsResource, Email, EmailAttachment, EmailAttachmentParams, EmailBatch, EmailEvent, EmailEventData, EmailEventType, EmailFailure, EmailLink, EmailRecipient, EmailRecipientStatus, EmailResource, EmailStatus, EmailSummary, EmailTag, EmailTracking, EmailWebhookEvent, EmailWebhookEventData, ExportSuppressionsParams, FetchLike, ForgottenRiskUser, HookApplication, HookApplicationsResource, HookAttempt, HookDeliveriesResource, HookDelivery, HookDeliveryStatus, HookEndpoint, HookEndpointDisabledReason, HookEndpointRecovery, HookEndpointSecret, HookEndpointWebhookEvent, HookEndpointWebhookEventData, HookEndpointWithSecret, HookEndpointsResource, HookEventType, HookEventTypesResource, HookMessage, HookMessagesResource, HookOperationalEventType, HookPortalResource, HookPortalSession, HooksResource, ImportSuppressionEntry, ImportSuppressionsParams, InboundAddress, Invoice, InvoiceLine, InvoiceLineKind, InvoiceStatus, InvoiceSummary, List, ListAuditEventsParams, ListCreditsParams, ListEmailsParams, ListHookApplicationsParams, ListHookDeliveriesParams, ListHookEventTypesParams, ListHookMessagesParams, ListInvoicesParams, ListLogDrainBatchesParams, ListLogsParams, ListReceivedEmailsParams, ListRiskAssessmentsParams, ListRiskListEntriesParams, ListSuppressionsParams, ListUsageParams, ListWebhookDeliveriesParams, Log, LogDrain, LogDrainAttempt, LogDrainBatch, LogDrainBatchStatus, LogDrainBatchesResource, LogDrainLine, LogDrainSource, LogDrainWithSecret, LogDrainsResource, LogLevel, LogSource, LogsResource, MailFromStatus, Meter, PlanKey, ReceivedEmail, ReceivedEmailAttachment, ReceivedEmailEventType, ReceivedEmailStatus, ReceivedEmailSummary, ReceivedEmailVerdicts, ReceivedEmailWebhookEvent, ReceivedEmailWebhookEventData, ReceivedEmailsResource, ReceivingDomain, ReceivingDomainRecord, ReceivingDomainsResource, RecoverHookEndpointParams, RecoverWebhookEndpointParams, Reputation, ReputationCheck, ReputationCheckSeverity, ReputationResource, ReputationStatus, RequestOptions, RescheduleEmailParams, RiskAssessment, RiskAssessmentsResource, RiskCalibration, RiskCaptchaProvider, RiskCaptchaSignals, RiskCardFunding, RiskCheckoutSignals, RiskContentCategory, RiskContentClassification, RiskContentScores, RiskDecision, RiskDegradedSignal, RiskDeviceSignals, RiskEmailCheck, RiskEmailSignals, RiskEvent, RiskEventType, RiskFeedbackParams, RiskIpCheck, RiskIpPrivacy, RiskIpSignals, RiskLimit, RiskLimitBucket, RiskLimitBucketsResource, RiskLimitFailureMode, RiskList, RiskListEntry, RiskListEntryType, RiskListEntryValue, RiskListsResource, RiskLoginSignals, RiskOutcome, RiskReason, RiskReasonCode, RiskResource, RiskRule, RiskRuleCondition, RiskRuleField, RiskRulesResource, RiskSettings, RiskSettingsResource, RiskUsersResource, RiskWebhookEvent, RiskWebhookEventData, RollHookEndpointSecretParams, RollWebhookEndpointSecretParams, SendEmailParams, SendHookMessageParams, SendHookTestParams, Suppression, SuppressionCheck, SuppressionImport, SuppressionReason, SuppressionResource, TrackingDomain, TrackingDomainRecord, TrackingDomainStatus, TrackingDomainsResource, TrackingOptions, TrackingResource, TrackingRule, TrackingSettings, UpdateHookApplicationParams, UpdateHookEndpointParams, UpdateHookEventTypeParams, UpdateLogDrainParams, UpdateRiskLimitBucketParams, UpdateRiskRuleParams, UpdateRiskSettingsParams, UpdateTrackingRuleParams, UpdateWebhookEndpointParams, Usage, VerdictStatus, VerifyWebhookOptions, WebhookAttempt, WebhookDeliveriesResource, WebhookDelivery, WebhookDeliveryStatus, WebhookEndpoint, WebhookEndpointDisabledReason, WebhookEndpointRecovery, WebhookEndpointWithSecret, WebhookEndpointsResource, WebhookEvent, WebhookEventType, WebhookHeaders };
3891
+ export type { AccountEventType, AccountWebhookEvent, AccountWebhookEventData, ApiKeyResource, ApiVersion, AssessRiskParams, AuditActorType, AuditEvent, AuditEventsResource, Billing, BillingCreditsResource, BillingEventType, BillingHoldReason, BillingInvoicesResource, BillingResource, BillingWebhookEvent, BimiIssueCode, BimiStatus, CheckRiskLimitParams, CheckSuppressionParams, CossError, CossErrorIssue, CossErrorType, CossOptions, CossResult, CreateDomainParams, CreateEmailTemplateParams, CreateHookApplicationParams, CreateHookEndpointParams, CreateHookEventTypeParams, CreateHookPortalSessionParams, CreateLogDrainParams, CreateReceivingDomainParams, CreateRiskLimitBucketParams, CreateRiskListEntryParams, CreateRiskRuleParams, CreateSuppressionParams, CreateTrackingDomainParams, CreateWebhookEndpointParams, CreateWebhookListenerParams, Credit, DedicatedIpPool, DedicatedIpPoolStatus, DedicatedIpsResource, DeletedApiKey, DeletedDomain, DeletedEmailTemplate, DeletedHookApplication, DeletedHookEndpoint, DeletedLogDrain, DeletedReceivedEmail, DeletedRiskLimitBucket, DeletedRiskListEntry, DeletedRiskRule, DeletedSuppression, DeletedTrackingRule, DeletedWebhookEndpoint, DeletedWebhookListener, DmarcCheck, DmarcCheckId, DmarcNextStep, DmarcNextStepKind, DmarcPolicy, DmarcPolicyPublished, DmarcPublishedRecord, DmarcReport, DmarcReportRecord, DmarcReportSummary, DmarcReportsResource, DmarcResource, DmarcSource, DmarcStage, Domain, DomainBimi, DomainDmarc, DomainEventType, DomainRecord, DomainRecordPurpose, DomainRecordStatus, DomainStatus, DomainWebhookEvent, DomainWebhookEventData, DomainsResource, Email, EmailAttachment, EmailAttachmentParams, EmailBatch, EmailEvent, EmailEventData, EmailEventType, EmailFailure, EmailLink, EmailRecipient, EmailRecipientStatus, EmailResource, EmailStatus, EmailSummary, EmailTag, EmailTemplate, EmailTemplateReference, EmailTemplateVersion, EmailTemplateVersionsResource, EmailTemplatesResource, EmailTracking, EmailWebhookEvent, EmailWebhookEventData, Environment, EnvironmentResource, ExportSuppressionsParams, FetchLike, ForgottenRiskUser, HookApplication, HookApplicationsResource, HookAttempt, HookDeliveriesResource, HookDelivery, HookDeliveryStatus, HookEndpoint, HookEndpointDisabledReason, HookEndpointRecovery, HookEndpointSecret, HookEndpointWebhookEvent, HookEndpointWebhookEventData, HookEndpointWithSecret, HookEndpointsResource, HookEventType, HookEventTypesResource, HookMessage, HookMessagesResource, HookOperationalEventType, HookPortalResource, HookPortalSession, HooksResource, ImportSuppressionEntry, ImportSuppressionsParams, InboundAddress, Invoice, InvoiceLine, InvoiceLineKind, InvoiceStatus, InvoiceSummary, List, ListAuditEventsParams, ListCreditsParams, ListDmarcReportsParams, ListEmailTemplateVersionsParams, ListEmailTemplatesParams, ListEmailsParams, ListHookApplicationsParams, ListHookDeliveriesParams, ListHookEventTypesParams, ListHookMessagesParams, ListInvoicesParams, ListLogDrainBatchesParams, ListLogsParams, ListReceivedEmailsParams, ListRiskAssessmentsParams, ListRiskListEntriesParams, ListSuppressionsParams, ListUsageParams, ListWebhookDeliveriesParams, Log, LogDrain, LogDrainAttempt, LogDrainBatch, LogDrainBatchStatus, LogDrainBatchesResource, LogDrainLine, LogDrainSource, LogDrainWithSecret, LogDrainsResource, LogLevel, LogSource, LogsResource, MailFromStatus, Meter, NamedResource, PlanKey, PollWebhookListenerParams, PublishEmailTemplateParams, ReactEmailElement, ReceivedEmail, ReceivedEmailAttachment, ReceivedEmailEventType, ReceivedEmailStatus, ReceivedEmailSummary, ReceivedEmailVerdicts, ReceivedEmailWebhookEvent, ReceivedEmailWebhookEventData, ReceivedEmailsResource, ReceivingDomain, ReceivingDomainRecord, ReceivingDomainsResource, RecoverHookEndpointParams, RecoverWebhookEndpointParams, Reputation, ReputationCheck, ReputationCheckSeverity, ReputationResource, ReputationStatus, RequestOptions, RescheduleEmailParams, RiskAssessment, RiskAssessmentsResource, RiskCalibration, RiskCaptchaProvider, RiskCaptchaSignals, RiskCardFunding, RiskCheckoutSignals, RiskContentCategory, RiskContentClassification, RiskContentScores, RiskDecision, RiskDegradedSignal, RiskDeviceSignals, RiskEmailCheck, RiskEmailSignals, RiskEvent, RiskEventType, RiskFeedbackParams, RiskIpCheck, RiskIpPrivacy, RiskIpSignals, RiskLimit, RiskLimitBucket, RiskLimitBucketsResource, RiskLimitFailureMode, RiskList, RiskListEntry, RiskListEntryType, RiskListEntryValue, RiskListsResource, RiskLoginSignals, RiskOutcome, RiskReason, RiskReasonCode, RiskResource, RiskRule, RiskRuleCondition, RiskRuleField, RiskRulesResource, RiskSettings, RiskSettingsResource, RiskUsersResource, RiskWebhookEvent, RiskWebhookEventData, RollHookEndpointSecretParams, RollWebhookEndpointSecretParams, SendEmailBaseParams, SendEmailContentParams, SendEmailParams, SendEmailTemplateParams, SendHookMessageParams, SendHookTestParams, Suppression, SuppressionCheck, SuppressionImport, SuppressionReason, SuppressionResource, TemplateContent, TemplateContentParams, TemplateProblem, TemplateScalarType, TemplateVariable, TemplateVariableParams, TemplateVariableType, TrackingDomain, TrackingDomainRecord, TrackingDomainStatus, TrackingDomainsResource, TrackingOptions, TrackingResource, TrackingRule, TrackingSettings, UpdateEmailTemplateDraftParams, UpdateEmailTemplateParams, UpdateHookApplicationParams, UpdateHookEndpointParams, UpdateHookEventTypeParams, UpdateLogDrainParams, UpdateRiskLimitBucketParams, UpdateRiskRuleParams, UpdateRiskSettingsParams, UpdateTrackingRuleParams, UpdateWebhookEndpointParams, Usage, VerdictStatus, VerifyWebhookOptions, WebhookAttempt, WebhookDeliveriesResource, WebhookDelivery, WebhookDeliveryStatus, WebhookEndpoint, WebhookEndpointDisabledReason, WebhookEndpointRecovery, WebhookEndpointWithSecret, WebhookEndpointsResource, WebhookEvent, WebhookEventType, WebhookHeaders, WebhookListener, WebhookListenerAck, WebhookListenerDelivery, WebhookListenerPoll, WebhookListenersResource };