coss 0.3.0 → 0.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.ts CHANGED
@@ -1,3104 +1,7 @@
1
- //#region src/api-version.d.ts
2
- /**
3
- * API versions this SDK knows, oldest first: a hand-written mirror of `API_VERSIONS` in the API
4
- * (`apps/api/test/sdk-contract.test.ts` keeps them equal).
5
- */
6
- export declare const API_VERSIONS: readonly ["2026-10-10"];
7
- /** A dated API version, sent as the `Coss-Version` header. */
8
- type ApiVersion = (typeof API_VERSIONS)[number];
9
- /** The version this SDK's types describe, sent with every request unless `apiVersion` overrides it. */
10
- export declare const API_VERSION: ApiVersion;
11
- //#endregion
12
- //#region src/core/errors.d.ts
13
- /** Error types returned by the API, plus the client-side `connection_error` and `timeout_error`. */
14
- type CossErrorType = "invalid_request_error" | "authentication_error" | "permission_error" | "not_found_error" | "idempotency_error" | "rate_limit_error" | "billing_error" | "api_error" | "connection_error" | "timeout_error";
15
- /** One field-level validation problem (`invalid_request_error` / `validation_error`). */
16
- interface CossErrorIssue {
17
- path: string;
18
- message: string;
19
- }
20
- /**
21
- * A failed request. API errors mirror the API's `{ "error": { … } }` envelope; failures that never
22
- * produced a response (network, timeout, abort) have `status: null`.
23
- */
24
- interface CossError {
25
- type: CossErrorType;
26
- /** Machine-readable reason, e.g. `invalid_api_key`, `validation_error`, `aborted`. */
27
- code: string;
28
- message: string;
29
- /** HTTP status, or `null` when no response was received. */
30
- status: number | null;
31
- /** The API's `X-Request-Id`. Include it when contacting support. */
32
- request_id: string | null;
33
- /** The request parameter the error relates to, when there is one. */
34
- param?: string;
35
- issues?: CossErrorIssue[];
36
- }
37
- type CossResult<T> = {
38
- data: T;
39
- error: null;
40
- } | {
41
- data: null;
42
- error: CossError;
43
- };
44
- //#endregion
45
- //#region src/core/http.d.ts
46
- /** Any WHATWG-compatible `fetch` (global fetch, undici, a test double, `app.fetch` adapters …). */
47
- type FetchLike = (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
48
- /** Per-request options accepted by every resource method. */
49
- interface RequestOptions {
50
- /**
51
- * Sent as `Idempotency-Key` on POST requests. When omitted a random UUID is generated; either way
52
- * the same key is reused for every retry of the call, so a retried send is never duplicated.
53
- */
54
- idempotencyKey?: string;
55
- /** Aborting cancels the in-flight attempt and any pending retry. */
56
- signal?: AbortSignal;
57
- }
58
- interface HttpClientOptions {
59
- apiKey: string;
60
- baseUrl: string;
61
- fetch: FetchLike;
62
- /** Per-attempt timeout in milliseconds. */
63
- timeout: number;
64
- maxRetries: number;
65
- /** Sent as `Coss-Version` with every request. */
66
- apiVersion: string;
67
- /** Waits between retries; must resolve early when `signal` aborts. Overridable for tests. */
68
- sleep?: (ms: number, signal?: AbortSignal) => Promise<void>;
69
- }
70
- interface ApiRequest {
71
- /** Disable automatic retries for operations without server-side deduplication. */
72
- retry?: boolean;
73
- method: "GET" | "POST" | "PATCH" | "DELETE";
74
- /** Path including the version prefix, e.g. `/v1/emails`. */
75
- path: string;
76
- /** Query parameters; `undefined` values are left out. */
77
- query?: Record<string, string | number | undefined>;
78
- /** Serialized as JSON. */
79
- body?: unknown;
80
- /**
81
- * `text` returns the raw body of a successful response (e.g. CSV) instead of parsing JSON;
82
- * `bytes` returns it as a `Uint8Array` (a received email's raw message, an attachment).
83
- */
84
- responseType?: "json" | "text" | "bytes";
85
- idempotencyKey?: string;
86
- signal?: AbortSignal;
87
- }
88
- /**
89
- * The request pipeline shared by all resources: auth + JSON, a per-attempt timeout, retries with
90
- * backoff, and mapping every failure to a `CossError`. It never throws for API or network errors.
91
- */
92
- declare class HttpClient {
93
- #private;
94
- constructor(options: HttpClientOptions);
95
- request<T>(request: ApiRequest): Promise<CossResult<T>>;
96
- }
97
- //#endregion
98
- //#region src/types/audit-event.d.ts
99
- /** Audit log wire types (hand-written mirrors of the API's schemas). */
100
- /**
101
- * `user`: a member, in the dashboard. `api_key`: a request made with an API key. `system`: COSS
102
- * itself, including COSS support.
103
- */
104
- type AuditActorType = "user" | "api_key" | "system";
105
- /** One change to the organization. */
106
- interface AuditEvent {
107
- object: "audit_event";
108
- id: string;
109
- /** ISO 8601 timestamp. */
110
- created_at: string;
111
- actor_type: AuditActorType;
112
- /** The user's or API key's id; `null` for the system. */
113
- actor_id: string | null;
114
- /** The user's email, the API key's id, or `COSS support` (copied when recorded). */
115
- actor_label: string;
116
- /** `<resource>.<verb>`, e.g. `api_key.created`, `domain.deleted`, `member.role_changed`. */
117
- action: string;
118
- /** What was changed: `domain`, `api_key`, `member`… */
119
- target_type: string | null;
120
- target_id: string | null;
121
- /** A readable name for the target when it was changed. */
122
- target_label: string | null;
123
- /** `null` for organization-wide changes (domains, members…). */
124
- project_id: string | null;
125
- /** `null` for organization-wide changes (domains, members…). */
126
- environment_id: string | null;
127
- /** Details of the change; API changes include their `request_id`. */
128
- metadata: Record<string, unknown>;
129
- client_ip: string | null;
130
- user_agent: string | null;
131
- }
132
- type OneOrMany$1<T> = T | readonly T[];
133
- /** Query of `GET /v1/audit_events`. Lists may be given as arrays or comma-separated strings. */
134
- interface ListAuditEventsParams {
135
- /** Actions, e.g. `"api_key.created"`; an entry ending in `.` (`"domain."`) matches a whole resource. */
136
- action?: OneOrMany$1<string>;
137
- actor_type?: OneOrMany$1<AuditActorType>;
138
- /** Only changes made by this user or API key. */
139
- actor_id?: string;
140
- /** Only changes to this resource, e.g. a `dom_…` id. */
141
- target_id?: string;
142
- /** Only changes in this environment. */
143
- environment_id?: string;
144
- /** Only events at or after this time. */
145
- from?: string | Date;
146
- /** Only events before this time. */
147
- to?: string | Date;
148
- /** 1-100, default 50. */
149
- limit?: number;
150
- /** The `id` of the last event of the previous page. */
151
- after?: string;
152
- }
153
- //#endregion
154
- //#region src/types/suppression.d.ts
155
- /** Suppression list wire types (hand-written mirrors of the API's schemas). */
156
- /**
157
- * Why an address is suppressed. `bounce`: a permanent bounce. `complaint`: a spam complaint.
158
- * `manual`: added one by one through the API or the dashboard. `import`: added by a bulk import.
159
- */
160
- type SuppressionReason = "bounce" | "complaint" | "manual" | "import";
161
- /** An entry of the API key's environment's suppression list. */
162
- interface Suppression {
163
- object: "suppression";
164
- id: string;
165
- /** The bare, lower-cased address. */
166
- address: string;
167
- /** `"*"` (every email) or a category: only emails sent with that `category` skip the address. */
168
- scope: string;
169
- reason: SuppressionReason;
170
- /** The email whose bounce or complaint added this entry. */
171
- email_id: string | null;
172
- /** ISO 8601 timestamp. */
173
- created_at: string;
174
- }
175
- /** Body of `POST /v1/suppressions`. */
176
- interface CreateSuppressionParams {
177
- /** Display names are ignored; matching is case-insensitive. */
178
- address: string;
179
- /** `"*"` (the default) suppresses every email; a category only suppresses those emails. */
180
- scope?: string;
181
- }
182
- /** Query of `GET /v1/suppressions`. */
183
- interface ListSuppressionsParams {
184
- address?: string;
185
- scope?: string;
186
- /** 1-100, default 50. */
187
- limit?: number;
188
- /** The `id` of the last entry of the previous page. */
189
- after?: string;
190
- }
191
- /** Query of `GET /v1/suppressions/check`. */
192
- interface CheckSuppressionParams {
193
- address: string;
194
- /** The category of the email you plan to send. Without it, only `"*"` entries count. */
195
- category?: string;
196
- }
197
- /** Whether a send would skip an address. */
198
- interface SuppressionCheck {
199
- object: "suppression_check";
200
- address: string;
201
- suppressed: boolean;
202
- /** The entries that match. */
203
- suppressions: Suppression[];
204
- }
205
- /** Response of `DELETE /v1/suppressions/{id}`. */
206
- interface DeletedSuppression {
207
- object: "suppression";
208
- id: string;
209
- deleted: true;
210
- }
211
- /** One entry of `POST /v1/suppressions/import`. */
212
- interface ImportSuppressionEntry {
213
- address: string;
214
- /** `"*"` (the default) or a category. */
215
- scope?: string;
216
- }
217
- /** Input of `coss.email.suppressions.import()`; the SDK sends 1,000 entries per request. */
218
- interface ImportSuppressionsParams {
219
- suppressions: ImportSuppressionEntry[];
220
- }
221
- /** What an import did. */
222
- interface SuppressionImport {
223
- object: "suppression_import";
224
- /** Entries added. */
225
- created: number;
226
- /** Valid entries that were already on the list (or repeated in the import); unchanged. */
227
- existing: number;
228
- /** Skipped entries; `index` is the entry's position in `suppressions`. */
229
- invalid: Array<{
230
- index: number;
231
- address: string;
232
- message: string;
233
- }>;
234
- }
235
- /** Query of `GET /v1/suppressions/export`. */
236
- interface ExportSuppressionsParams {
237
- scope?: string;
238
- reason?: SuppressionReason;
239
- }
240
- //#endregion
241
- //#region src/types/email.d.ts
242
- /** A `name`/`value` pair attached to an email for your own filtering and analytics. */
243
- interface EmailTag {
244
- name: string;
245
- value: string;
246
- }
247
- /**
248
- * A file to attach (at most 20 per email, 25 MB combined). Executables and other file types the
249
- * delivery provider refuses (such as `.exe` or `.js`) are rejected.
250
- */
251
- interface EmailAttachmentParams {
252
- /** The name recipients see. Must include an extension, e.g. `"invoice.pdf"`. */
253
- filename: string;
254
- /** The file's bytes, base64-encoded (no line breaks or `data:` prefix). */
255
- content: string;
256
- /** Media type such as `"application/pdf"`. Defaults from the filename's extension. */
257
- content_type?: string;
258
- /**
259
- * Makes the attachment inline: reference it from `html` as `<img src="cid:logo@acme">`
260
- * (without angle brackets here).
261
- */
262
- content_id?: string;
263
- }
264
- /** Metadata of a sent attachment. The content itself is never returned. */
265
- interface EmailAttachment {
266
- id: string;
267
- filename: string;
268
- content_type: string;
269
- /** Set for inline attachments. */
270
- content_id: string | null;
271
- /** Size in bytes. */
272
- size: number;
273
- }
274
- /**
275
- * Whether the email was handed to the delivery provider. `scheduled` emails wait for their
276
- * `scheduled_at`; `canceled` ones were canceled before that. Delivery is tracked per recipient.
277
- */
278
- type EmailStatus = "queued" | "sent" | "failed" | "scheduled" | "canceled";
279
- /**
280
- * Delivery status of one recipient. It only moves forward: `queued` → `sent` →
281
- * `delivery_delayed` → `delivered`, then `bounced` / `suppressed` / `failed`, then `complained`.
282
- * `suppressed` means the address is on the environment's suppression list (for every email or for
283
- * the email's `category`), so it was skipped. `canceled` means the scheduled email was canceled.
284
- */
285
- type EmailRecipientStatus = "queued" | "sent" | "delivery_delayed" | "delivered" | "bounced" | "suppressed" | "complained" | "failed" | "canceled";
286
- /** One distinct recipient address of an email. */
287
- interface EmailRecipient {
288
- /** The bare, lower-cased address. */
289
- address: string;
290
- type: "to" | "cc" | "bcc";
291
- status: EmailRecipientStatus;
292
- /** ISO 8601 timestamp of the latest event for this recipient, or `null`. */
293
- last_event_at: string | null;
294
- }
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";
296
- /** Details of an event; which member is present depends on the event type. */
297
- interface EmailEventData {
298
- bounce?: {
299
- type: "permanent" | "transient" | "undetermined";
300
- sub_type: string;
301
- diagnostic_code: string | null;
302
- };
303
- complaint?: {
304
- feedback_type: string | null;
305
- sub_type: string | null;
306
- };
307
- delay?: {
308
- type: string;
309
- expires_at: string | null;
310
- diagnostic_code: string | null;
311
- };
312
- delivery?: {
313
- smtp_response: string | null;
314
- };
315
- failure?: {
316
- code: string;
317
- message: string;
318
- };
319
- /** Only for `email.suppressed`: the entry that matched the recipient. */
320
- suppression?: {
321
- id: string;
322
- scope: string;
323
- reason: SuppressionReason;
324
- };
325
- /** Only for `email.opened`. */
326
- open?: {
327
- user_agent: string | null;
328
- };
329
- /** Only for `email.clicked`: the original link and its index among the tracked links. */
330
- click?: {
331
- url: string;
332
- link_position: number;
333
- user_agent: string | null;
334
- };
335
- /** Only for `email.rescheduled`: the new time and the one it replaced. */
336
- reschedule?: {
337
- scheduled_at: string;
338
- previous_scheduled_at: string;
339
- };
340
- }
341
- /** A delivery event of an email. */
342
- interface EmailEvent {
343
- object: "email_event";
344
- id: string;
345
- email_id: string;
346
- type: EmailEventType;
347
- /**
348
- * The recipient this event is about; `null` for the whole email (`email.sent`, `email.failed`),
349
- * and for opens and clicks of an email with several recipients.
350
- */
351
- recipient: string | null;
352
- /** ISO 8601 timestamp. */
353
- occurred_at: string;
354
- data: EmailEventData;
355
- }
356
- /** A list response. */
357
- interface List<T> {
358
- object: "list";
359
- data: T[];
360
- has_more: boolean;
361
- }
362
- /**
363
- * Overrides the environment's tracking settings for one email. Omitted fields keep the configured
364
- * setting (the email's category rule, else the environment default, else off).
365
- */
366
- interface TrackingOptions {
367
- /** Add an invisible pixel to the HTML body and record `email.opened` events. */
368
- opens?: boolean;
369
- /**
370
- * Send HTML links through a COSS redirect and record `email.clicked` events. Links with a
371
- * `data-coss-no-track` attribute are left alone.
372
- */
373
- clicks?: boolean;
374
- }
375
- /** Body of `POST /v1/emails`. */
376
- interface SendEmailParams {
377
- /** `"you@example.com"` or `"Your Name <you@example.com>"`. */
378
- from: string;
379
- to: string | string[];
380
- cc?: string | string[];
381
- bcc?: string | string[];
382
- reply_to?: string | string[];
383
- subject: string;
384
- /** At least one of `html` or `text` is required. */
385
- html?: string;
386
- text?: string;
387
- /** Custom headers. Names are case-insensitive; reserved names such as `subject` are rejected. */
388
- headers?: Record<string, string>;
389
- tags?: EmailTag[];
390
- /**
391
- * What kind of email this is, e.g. `"marketing"`. Recipients suppressed for this category (or
392
- * for every email) are skipped.
393
- */
394
- category?: string;
395
- /**
396
- * Send at this time instead of now: an ISO 8601 date-time with an offset, e.g.
397
- * `"2026-10-11T09:00:00Z"`, at most 30 days ahead. A time that is not in the future sends
398
- * immediately. Until it is sent, move it with `coss.email.reschedule(id, …)` or cancel it with
399
- * `coss.email.cancel(id)`.
400
- */
401
- scheduled_at?: string;
402
- attachments?: EmailAttachmentParams[];
403
- tracking?: TrackingOptions;
404
- }
405
- /** Parameters of `coss.email.reschedule`. */
406
- interface RescheduleEmailParams {
407
- /**
408
- * The new time: an ISO 8601 date-time with an offset, at most 30 days ahead. A time that is not
409
- * in the future sends the email right away.
410
- */
411
- scheduled_at: string;
412
- }
413
- /**
414
- * Open and click tracking as resolved when the email was sent, with engagement so far. Opens can
415
- * be inflated by mail clients that prefetch images, clicks by link scanners.
416
- */
417
- interface EmailTracking {
418
- opens: boolean;
419
- clicks: boolean;
420
- open_count: number;
421
- /** ISO 8601 timestamps, or `null`. */
422
- first_opened_at: string | null;
423
- last_opened_at: string | null;
424
- click_count: number;
425
- first_clicked_at: string | null;
426
- last_clicked_at: string | null;
427
- }
428
- /** A link COSS rewrote for click tracking. */
429
- interface EmailLink {
430
- object: "email_link";
431
- id: string;
432
- email_id: string;
433
- /** Index of the link among the email's tracked links, in document order. */
434
- position: number;
435
- url: string;
436
- click_count: number;
437
- first_clicked_at: string | null;
438
- last_clicked_at: string | null;
439
- }
440
- /** Why an email failed as a whole. */
441
- interface EmailFailure {
442
- /**
443
- * E.g. `all_recipients_suppressed`, `domain_not_verified`, `content_rejected`,
444
- * `attachments_unavailable`, `dispatch_failed` or `provider_error`.
445
- */
446
- code: string;
447
- message: string;
448
- }
449
- /** An email as returned by the API. Recipient fields are always arrays. */
450
- interface Email {
451
- object: "email";
452
- id: string;
453
- from: string;
454
- to: string[];
455
- cc: string[];
456
- bcc: string[];
457
- reply_to: string[];
458
- subject: string;
459
- html: string | null;
460
- text: string | null;
461
- /** Header names are lower-cased. */
462
- headers: Record<string, string>;
463
- tags: EmailTag[];
464
- category: string | null;
465
- status: EmailStatus;
466
- /** Why the email failed; `null` unless `status` is `"failed"`. */
467
- failure: EmailFailure | null;
468
- /** Every distinct recipient across `to`, `cc` and `bcc`, with its delivery status. */
469
- recipients: EmailRecipient[];
470
- /** Attachment metadata; the content is discarded once the email is sent. */
471
- attachments: EmailAttachment[];
472
- /** `true` when sent with a sandbox (`coss_test_…`) key: nothing is actually delivered. */
473
- sandbox: boolean;
474
- tracking: EmailTracking;
475
- /** ISO 8601 timestamp. */
476
- created_at: string;
477
- /** ISO 8601 timestamp, or `null` until the provider accepts the message. */
478
- sent_at: string | null;
479
- /** ISO 8601 timestamp the email was scheduled for, or `null` if no schedule was provided. */
480
- scheduled_at: string | null;
481
- /** The batch that sent the email (`coss.email.sendBatch`), or `null` if it was sent alone. */
482
- batch_id: string | null;
483
- }
484
- /** An email in a list (`coss.email.list`): everything but its content. */
485
- type EmailSummary = Omit<Email, "html" | "text" | "headers" | "attachments">;
486
- /** Filters of `coss.email.list`. Emails are returned newest first. */
487
- interface ListEmailsParams {
488
- /** Only emails with this recipient (in `to`, `cc` or `bcc`; the bare address, any case). */
489
- to?: string;
490
- /** Only emails with a recipient in one of these statuses (with `to`, that recipient's). */
491
- recipient_status?: EmailRecipientStatus[];
492
- /** Only emails in these statuses. */
493
- status?: EmailStatus[];
494
- /** Free text, matched against the subject and the `to` addresses. */
495
- q?: string;
496
- /** Only emails of this category. */
497
- category?: string;
498
- /** Only the emails of this batch. */
499
- batch_id?: string;
500
- /** Only emails created at or after this time. */
501
- created_after?: Date | string;
502
- /** Only emails created before this time. */
503
- created_before?: Date | string;
504
- /** 1-100, default 20. */
505
- limit?: number;
506
- /** Cursor: the `id` of the last email of the previous page. */
507
- after?: string;
508
- }
509
- /** Emails sent together by `coss.email.sendBatch`. */
510
- interface EmailBatch {
511
- object: "email_batch";
512
- id: string;
513
- /** The batch's emails, in the order they were passed. */
514
- data: Email[];
515
- /** ISO 8601 timestamp. */
516
- created_at: string;
517
- }
518
- //#endregion
519
- //#region src/resources/audit-events.d.ts
520
- type ReadOptions$12 = Pick<RequestOptions, "signal">;
521
- /**
522
- * `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.
524
- */
525
- declare class AuditEventsResource {
526
- #private;
527
- /** @internal Use `new Coss().auditEvents`. */
528
- constructor(http: HttpClient);
529
- /** 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>>>;
531
- /** Retrieves one audit event. */
532
- get(id: string, options?: ReadOptions$12): Promise<CossResult<AuditEvent>>;
533
- }
534
- //#endregion
535
- //#region src/types/billing.d.ts
536
- /**
537
- * Billing wire types (hand-written mirrors of the API's `Billing`, `Usage`, `Invoice` and `Credit`
538
- * schemas). Amounts are integers in cents (USD); unit prices are dollar decimal strings.
539
- */
540
- type PlanKey = "free" | "pro" | "scale" | "enterprise";
541
- type Meter = "email.recipients" | "sms.segments" | "video.participant_minutes" | "scheduling.bookings";
542
- type BillingHoldReason = "delinquent" | "spend_limit" | "admin";
543
- /** `GET /v1/billing`: the organization's plan, the current month so far, and its standing. */
544
- interface Billing {
545
- object: "billing";
546
- organization_id: string;
547
- /** The plan in effect now (`free` without a contract). */
548
- plan: PlanKey;
549
- /** The contract in effect; `null` on the Free plan. */
550
- contract: {
551
- id: string;
552
- kind: "self_serve" | "sales" | "internal";
553
- effective_from: string;
554
- effective_until: string | null;
555
- /** End of a committed term. */
556
- term_end: string | null;
557
- auto_renew: boolean;
558
- } | null;
559
- /** A plan change that takes effect later (a downgrade, a cancellation). */
560
- scheduled_change: {
561
- effective_at: string;
562
- plan: PlanKey;
563
- } | null;
564
- /** `past_due`: an invoice is overdue; `delinquent`: past its grace period (live sending is held). */
565
- status: "active" | "past_due" | "delinquent";
566
- /** Billing holds on live sending (sandbox keys keep working). */
567
- holds: {
568
- reason: BillingHoldReason;
569
- since: string;
570
- }[];
571
- currency: "usd";
572
- /** The current billing month (UTC). */
573
- period: {
574
- start: string;
575
- end: string;
576
- };
577
- usage: {
578
- meter: Meter;
579
- quantity: number;
580
- /** The plan's monthly allowance where usage stops (Free), else `null`. */
581
- included: number | null;
582
- }[];
583
- /** This month so far, as it would be invoiced if it ended now (cents). */
584
- estimate: {
585
- usage: number;
586
- discount: number;
587
- credit: number;
588
- total: number;
589
- };
590
- /** Unused credit usable this month (cents). */
591
- credit_remaining: number;
592
- /** Usage beyond the credit past which live sending is held (cents); `null`: none. */
593
- spend_limit: number | null;
594
- payment_method: {
595
- type: string;
596
- brand: string | null;
597
- last4: string | null;
598
- } | null;
599
- features: {
600
- tracking_domains: boolean;
601
- audit_log: boolean;
602
- log_drains: boolean;
603
- sso: boolean;
604
- scim: boolean;
605
- };
606
- /** Resource limits (`null`: unlimited). */
607
- limits: {
608
- domains: number | null;
609
- members: number | null;
610
- webhook_endpoints_per_environment: number | null;
611
- };
612
- }
613
- /** Billable usage of one meter in one bucket. */
614
- interface Usage {
615
- object: "usage";
616
- meter: Meter;
617
- /** e.g. `country=US` for SMS; `null` for none. */
618
- dimension: string | null;
619
- /** Set with `group_by: "environment"`. */
620
- environment_id: string | null;
621
- start: string;
622
- end: string;
623
- quantity: number;
624
- }
625
- interface ListUsageParams {
626
- /** Start (inclusive, ISO 8601). Defaults to the start of the current billing month. */
627
- from?: string;
628
- /** End (exclusive). Defaults to now. At most 400 days after `from` (7 by hour). */
629
- to?: string;
630
- /** Bucket size (UTC). Defaults to `day`. */
631
- granularity?: "hour" | "day" | "month";
632
- /** Split each bucket per environment. */
633
- group_by?: "environment";
634
- /** Only this meter. */
635
- meter?: Meter;
636
- }
637
- type InvoiceStatus = "open" | "paid" | "void" | "uncollectible";
638
- type InvoiceLineKind = "plan_fee" | "proration" | "usage" | "credit" | "discount" | "commitment_fee" | "commitment_shortfall" | "add_on" | "adjustment" | "write_off";
639
- interface InvoiceLine {
640
- object: "invoice_line";
641
- id: string;
642
- kind: InvoiceLineKind;
643
- description: string;
644
- meter: Meter | null;
645
- dimension: string | null;
646
- quantity: number | null;
647
- /** Units covered by an allowance or committed volume (not charged). */
648
- included_quantity: number | null;
649
- /** Dollars per unit, e.g. `"0.0004"`; `null` when the price varies by volume. */
650
- unit_price: string | null;
651
- /** Cents. */
652
- amount: number;
653
- period: {
654
- start: string;
655
- end: string;
656
- };
657
- }
658
- /** An invoice without its lines (lists and webhook events). Amounts in cents. */
659
- interface InvoiceSummary {
660
- object: "invoice";
661
- id: string;
662
- number: string | null;
663
- kind: "period" | "plan_change" | "one_off" | "final";
664
- status: InvoiceStatus;
665
- currency: "usd";
666
- period: {
667
- start: string;
668
- end: string;
669
- };
670
- subtotal: number;
671
- discount: number;
672
- credit: number;
673
- tax: number;
674
- total: number;
675
- amount_paid: number;
676
- amount_due: number;
677
- collection_method: "charge_automatically" | "send_invoice";
678
- due_at: string | null;
679
- finalized_at: string | null;
680
- paid_at: string | null;
681
- voided_at: string | null;
682
- /** A page to view (and pay) the invoice. */
683
- hosted_url: string | null;
684
- pdf_url: string | null;
685
- }
686
- interface Invoice extends InvoiceSummary {
687
- lines: InvoiceLine[];
688
- }
689
- interface ListInvoicesParams {
690
- /** Only invoices in this status. */
691
- status?: InvoiceStatus;
692
- /** Continue after this id (the last of the previous page). */
693
- after?: string;
694
- /** At most this many (1-100, default 20). */
695
- limit?: number;
696
- }
697
- /** Credit the organization can spend: dollars (cents) or free units of a meter. */
698
- interface Credit {
699
- object: "credit";
700
- id: string;
701
- /** `amount`: dollars (`amount` and `remaining` in cents); `units`: free units of `meter`. */
702
- kind: "amount" | "units";
703
- amount: number;
704
- remaining: number;
705
- /** What a `units` credit covers. */
706
- meter: Meter | null;
707
- /** What an `amount` credit pays for (`null`: any usage). */
708
- meters: Meter[] | null;
709
- /** `any`: also fees and other charges. */
710
- applies_to: "usage" | "any";
711
- source: "fee" | "commitment" | "support" | "promotion" | "refund" | "sla";
712
- description: string;
713
- effective_at: string;
714
- expires_at: string | null;
715
- voided_at: string | null;
716
- created_at: string;
717
- }
718
- interface ListCreditsParams {
719
- /** `active` (default): usable now or later, with something left; `all`: every credit. */
720
- status?: "active" | "all";
721
- /** Continue after this id (the last of the previous page). */
722
- after?: string;
723
- /** At most this many (1-100, default 20). */
724
- limit?: number;
725
- }
726
- //#endregion
727
- //#region src/resources/billing.d.ts
728
- type ReadOptions$11 = Pick<RequestOptions, "signal">;
729
- /** `coss.billing.invoices`: the organization's invoices, newest first. */
730
- declare class BillingInvoicesResource {
731
- #private;
732
- /** @internal Use `new Coss().billing.invoices`. */
733
- constructor(http: HttpClient);
734
- /** 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>>>;
736
- /** Retrieves one invoice with its lines. */
737
- get(id: string, options?: ReadOptions$11): Promise<CossResult<Invoice>>;
738
- }
739
- /** `coss.billing.credits`: the organization's credits and what's left of them. */
740
- declare class BillingCreditsResource {
741
- #private;
742
- /** @internal Use `new Coss().billing.credits`. */
743
- constructor(http: HttpClient);
744
- /** Lists credits, newest first (usable ones by default). */
745
- list(params?: ListCreditsParams, options?: ReadOptions$11): Promise<CossResult<List<Credit>>>;
746
- }
747
- /**
748
- * `coss.billing`: the organization's plan, usage, invoices and credits (read only; plan changes
749
- * are made in the dashboard). Organization-wide, whichever environment the key belongs to.
750
- */
751
- declare class BillingResource {
752
- #private;
753
- readonly invoices: BillingInvoicesResource;
754
- readonly credits: BillingCreditsResource;
755
- /** @internal Use `new Coss().billing`. */
756
- constructor(http: HttpClient);
757
- /** The plan, the current month's usage and estimate, standing and what the plan includes. */
758
- get(options?: ReadOptions$11): Promise<CossResult<Billing>>;
759
- /** 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>>>;
761
- }
762
- //#endregion
763
- //#region src/types/domain.d.ts
764
- /**
765
- * Sending domain wire types. Hand-written to mirror the API's snake_case JSON 1:1 (the API's
766
- * contract test asserts they stay assignable to and from its zod schemas).
767
- */
768
- /**
769
- * `pending` while the DNS records are being checked, `verified` once they are,
770
- * `temporary_failure` after a transient DNS problem, and `failed` when verification gave up
771
- * (72 hours) — call `verify` to start over. `deleting` is a removal in progress.
772
- */
773
- type DomainStatus = "pending" | "verified" | "temporary_failure" | "failed" | "deleting";
774
- /** Verification state of the `send.` bounce subdomain. */
775
- type MailFromStatus = "pending" | "success" | "temporary_failure" | "failed";
776
- /**
777
- * What a record is for: `dkim` signs messages, `mail_from_mx` and `mail_from_spf` set up the
778
- * bounce subdomain, and `dmarc` is recommended but not required.
779
- */
780
- type DomainRecordPurpose = "dkim" | "mail_from_mx" | "mail_from_spf" | "dmarc";
781
- /** What the last DNS check saw. `not_checked` means DNS has not been consulted yet. */
782
- type DomainRecordStatus = "verified" | "missing" | "mismatch" | "not_checked";
783
- /** One DNS record a domain needs (or, when `required` is `false`, should have). */
784
- interface DomainRecord {
785
- purpose: DomainRecordPurpose;
786
- type: "CNAME" | "MX" | "TXT";
787
- /** The fully qualified record name to create. */
788
- name: string;
789
- value: string;
790
- /** `MX` records only. */
791
- priority: number | null;
792
- /** `false` for records that are only recommended. */
793
- required: boolean;
794
- status: DomainRecordStatus;
795
- /** What DNS returned when it did not match. */
796
- found: string[];
797
- }
798
- /**
799
- * `pending` until the CNAME points at COSS and its certificate is issued, `active` once tracking
800
- * links of emails sent from the domain use it, `temporary_failure` when an active hostname stopped
801
- * working (emails fall back to the default tracking host meanwhile), and `failed` when setup gave
802
- * up (72 hours) — call `domains.verify` to start over. `deleting` is a removal in progress.
803
- */
804
- type TrackingDomainStatus = "pending" | "active" | "temporary_failure" | "failed" | "deleting";
805
- /** The CNAME a tracking domain needs, with the result of the last check. */
806
- interface TrackingDomainRecord {
807
- type: "CNAME";
808
- /** The fully qualified record name to create. */
809
- name: string;
810
- /** The host the record must point at. */
811
- value: string;
812
- status: DomainRecordStatus;
813
- /** What DNS returned when it did not match. */
814
- found: string[];
815
- }
816
- /** A domain's custom tracking domain: open pixels and click redirects use it while `active`. */
817
- interface TrackingDomain {
818
- /** The tracking hostname, a subdomain of the domain (e.g. `links.acme.com`). */
819
- hostname: string;
820
- status: TrackingDomainStatus;
821
- record: TrackingDomainRecord;
822
- /** What is holding the hostname up, when the certificate provider said. */
823
- message: string | null;
824
- /** ISO 8601 timestamp. */
825
- created_at: string;
826
- last_checked_at: string | null;
827
- activated_at: string | null;
828
- failed_at: string | null;
829
- }
830
- /** The MX record a receiving domain needs, with the result of the last check. */
831
- interface ReceivingDomainRecord {
832
- type: "MX";
833
- /** The fully qualified record name to create. */
834
- name: string;
835
- /** The mail exchange the record must point at. */
836
- value: string;
837
- priority: number;
838
- /** `verified` once the most preferred MX records point at COSS. */
839
- status: DomainRecordStatus;
840
- /** What DNS returned when it did not match. */
841
- found: string[];
842
- }
843
- /** A domain's receiving hostname: email to any address at it is received by `environment_id`. */
844
- interface ReceivingDomain {
845
- /** The domain itself or a subdomain of it (e.g. `inbound.acme.com`). */
846
- hostname: string;
847
- environment_id: string;
848
- record: ReceivingDomainRecord;
849
- /** ISO 8601 timestamp. */
850
- created_at: string;
851
- last_checked_at: string | null;
852
- }
853
- /** A sending domain of the organization. */
854
- interface Domain {
855
- object: "domain";
856
- id: string;
857
- /** The domain, lower-cased. */
858
- name: string;
859
- status: DomainStatus;
860
- /** Whether live keys may send from this domain right now. */
861
- can_send: boolean;
862
- region: string | null;
863
- /** The envelope sender subdomain bounces come back to. */
864
- mail_from_domain: string;
865
- mail_from_status: MailFromStatus;
866
- /** The DNS records to publish, with the result of the last check. */
867
- records: DomainRecord[];
868
- /** ISO 8601 timestamp. */
869
- created_at: string;
870
- last_checked_at: string | null;
871
- verified_at: string | null;
872
- failed_at: string | null;
873
- /** The custom tracking domain, or `null` when none is set up. */
874
- tracking: TrackingDomain | null;
875
- /** The receiving hostname, or `null` when the domain doesn't receive email. */
876
- receiving: ReceivingDomain | null;
877
- }
878
- /** Body of `POST /v1/domains`. */
879
- interface CreateDomainParams {
880
- /**
881
- * The domain to send from, without a scheme or path (`"acme.com"`, `"mail.acme.com"`).
882
- * Internationalized domains must be punycode-encoded.
883
- */
884
- name: string;
885
- }
886
- /** Returned by `domains.delete`. */
887
- interface DeletedDomain {
888
- object: "domain";
889
- id: string;
890
- deleted: true;
891
- }
892
- /** Body of `POST /v1/domains/{id}/tracking`. */
893
- interface CreateTrackingDomainParams {
894
- /** A subdomain of the domain to serve tracking links from (`"links.acme.com"`). */
895
- hostname: string;
896
- }
897
- /** Body of `POST /v1/domains/{id}/receiving`. */
898
- interface CreateReceivingDomainParams {
899
- /** The domain itself or a subdomain of it (`"inbound.acme.com"`). */
900
- hostname: string;
901
- }
902
- //#endregion
903
- //#region src/resources/receiving-domains.d.ts
904
- type DeleteOptions$1 = Pick<RequestOptions, "signal">;
905
- /**
906
- * `coss.domains.receiving`: a domain's receiving hostname (the domain itself or a subdomain, e.g.
907
- * `inbound.acme.com`). Email sent to any address at it is received by the API key's environment.
908
- */
909
- declare class ReceivingDomainsResource {
910
- #private;
911
- /** @internal Use `new Coss().domains.receiving`. */
912
- constructor(http: HttpClient);
913
- /**
914
- * Starts receiving at a hostname of the domain, for the API key's environment, and returns the
915
- * domain with the MX record to publish in `data.receiving.record`.
916
- */
917
- create(domainId: string, params: CreateReceivingDomainParams, options?: RequestOptions): Promise<CossResult<Domain>>;
918
- /** Stops receiving at the domain's hostname. Emails already received are kept. */
919
- delete(domainId: string, options?: DeleteOptions$1): Promise<CossResult<Domain>>;
920
- }
921
- //#endregion
922
- //#region src/resources/tracking-domains.d.ts
923
- type DeleteOptions = Pick<RequestOptions, "signal">;
924
- /**
925
- * `coss.domains.tracking`: a domain's custom tracking domain (e.g. `links.acme.com`). Open pixels
926
- * and click redirects of emails sent from the domain use it while it is `active`.
927
- */
928
- declare class TrackingDomainsResource {
929
- #private;
930
- /** @internal Use `new Coss().domains.tracking`. */
931
- constructor(http: HttpClient);
932
- /**
933
- * Sets up a subdomain of the domain as its tracking domain and returns the domain, with the
934
- * CNAME to publish in `data.tracking.record`. Setup gives up after 72 hours.
935
- */
936
- create(domainId: string, params: CreateTrackingDomainParams, options?: RequestOptions): Promise<CossResult<Domain>>;
937
- /**
938
- * Removes the domain's tracking domain. Later emails use the default tracking host; links in
939
- * emails already sent through it stop working.
940
- */
941
- delete(domainId: string, options?: DeleteOptions): Promise<CossResult<Domain>>;
942
- }
943
- //#endregion
944
- //#region src/resources/domains.d.ts
945
- type ReadOptions$10 = Pick<RequestOptions, "signal">;
946
- /**
947
- * `coss.domains`: the domains live (`coss_live_…`) keys may send from. Domains belong to the
948
- * organization, so every API key of the organization sees the same ones.
949
- */
950
- declare class DomainsResource {
951
- #private;
952
- /** Each domain's custom tracking domain: add and remove it. */
953
- readonly tracking: TrackingDomainsResource;
954
- /** Each domain's receiving hostname: start and stop receiving email at it. */
955
- readonly receiving: ReceivingDomainsResource;
956
- /** @internal Use `new Coss().domains`. */
957
- constructor(http: HttpClient);
958
- /**
959
- * Adds a domain and returns the DNS records to publish (`data.records`). The records are
960
- * checked in the background; verification gives up after 72 hours.
961
- */
962
- create(params: CreateDomainParams, options?: RequestOptions): Promise<CossResult<Domain>>;
963
- /** Lists the organization's domains, ordered by name. */
964
- list(options?: ReadOptions$10): Promise<CossResult<List<Domain>>>;
965
- /** Retrieves a domain with the result of the last DNS check. */
966
- get(id: string, options?: ReadOptions$10): Promise<CossResult<Domain>>;
967
- /**
968
- * Checks the domain's records now instead of waiting for the next background check. A `failed`
969
- * domain starts verification over with fresh DKIM records, which have to be published again.
970
- * Its tracking domain, if any, is checked too.
971
- */
972
- verify(id: string, options?: RequestOptions): Promise<CossResult<Domain>>;
973
- /** 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>>;
975
- }
976
- //#endregion
977
- //#region src/types/received-email.d.ts
978
- /**
979
- * Received (inbound) email wire types. Hand-written to mirror the API's snake_case JSON 1:1 (the
980
- * API's contract test asserts they stay assignable to and from its zod schemas).
981
- */
982
- /** `received`, or `blocked` when the message carried a virus (only its envelope is kept). */
983
- type ReceivedEmailStatus = "received" | "blocked";
984
- /** What the receiving server concluded; `null` when the check did not run. */
985
- type VerdictStatus = "pass" | "fail" | "gray" | "processing_failed";
986
- interface ReceivedEmailVerdicts {
987
- spam: VerdictStatus | null;
988
- virus: VerdictStatus | null;
989
- spf: VerdictStatus | null;
990
- dkim: VerdictStatus | null;
991
- dmarc: VerdictStatus | null;
992
- /** The sender domain's DMARC policy (`none`, `quarantine`, `reject`) when DMARC failed. */
993
- dmarc_policy: string | null;
994
- }
995
- /** Metadata of an attachment; download it with `email.received.getAttachment`. */
996
- interface ReceivedEmailAttachment {
997
- id: string;
998
- /** `null` when the part named none. */
999
- filename: string | null;
1000
- content_type: string;
1001
- /** Set for parts the HTML references (`cid:` URLs). */
1002
- content_id: string | null;
1003
- disposition: "attachment" | "inline";
1004
- /** Size in bytes. */
1005
- size: number;
1006
- }
1007
- /** A received email as lists return it: without bodies and headers. */
1008
- interface ReceivedEmailSummary {
1009
- object: "received_email";
1010
- id: string;
1011
- status: ReceivedEmailStatus;
1012
- blocked_reason: "virus" | null;
1013
- /** The envelope sender (`MAIL FROM`); empty for bounces. */
1014
- mail_from: string;
1015
- /** The envelope recipients this environment received it for (Bcc'd addresses included). */
1016
- recipients: string[];
1017
- /** The `From` header. */
1018
- from: string | null;
1019
- to: string[];
1020
- cc: string[];
1021
- subject: string | null;
1022
- /** The `Message-ID` header. */
1023
- message_id: string | null;
1024
- attachments: ReceivedEmailAttachment[];
1025
- /** Size of the raw message in bytes. */
1026
- size: number;
1027
- /** Whether the spam verdict is `fail`. */
1028
- spam: boolean;
1029
- verdicts: ReceivedEmailVerdicts;
1030
- /** Whether a sandbox environment received it. */
1031
- sandbox: boolean;
1032
- /** ISO 8601 timestamp. */
1033
- received_at: string;
1034
- }
1035
- /** A received email with its headers and bodies. HTML is the sender's: sanitize it to show it. */
1036
- interface ReceivedEmail extends ReceivedEmailSummary {
1037
- reply_to: string[];
1038
- in_reply_to: string | null;
1039
- /** Message ids of the `References` header. */
1040
- references: string[];
1041
- /** The `Date` header, when valid (ISO 8601). */
1042
- sent_at: string | null;
1043
- /** Every header in message order, duplicates included. */
1044
- headers: {
1045
- name: string;
1046
- value: string;
1047
- }[];
1048
- text: string | null;
1049
- html: string | null;
1050
- /** Whether `text`, `html` or `headers` were shortened; `getRaw` always has everything. */
1051
- truncated: boolean;
1052
- }
1053
- /** Query of `email.received.list`. */
1054
- interface ListReceivedEmailsParams {
1055
- /** 1-100, default 20. */
1056
- limit?: number;
1057
- /** The `id` of the last email of the previous page. */
1058
- after?: string;
1059
- }
1060
- /** Returned by `email.received.delete`. */
1061
- interface DeletedReceivedEmail {
1062
- object: "received_email";
1063
- id: string;
1064
- deleted: true;
1065
- }
1066
- /** The environment's own domain under COSS's inbound domain: any address at it is received. */
1067
- interface InboundAddress {
1068
- object: "inbound_address";
1069
- environment_id: string;
1070
- domain: string;
1071
- }
1072
- //#endregion
1073
- //#region src/resources/received-emails.d.ts
1074
- type ReadOptions$9 = Pick<RequestOptions, "signal">;
1075
- /**
1076
- * `coss.email.received`: emails received by the API key's environment, at its inbound address
1077
- * (`address()`) or at a receiving domain (`coss.domains.receiving`). An `email.received` webhook
1078
- * announces each one.
1079
- */
1080
- declare class ReceivedEmailsResource {
1081
- #private;
1082
- /** @internal Use `new Coss().email.received`. */
1083
- constructor(http: HttpClient);
1084
- /** 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>>>;
1086
- /** Retrieves a received email with its headers and bodies. */
1087
- get(id: string, options?: ReadOptions$9): Promise<CossResult<ReceivedEmail>>;
1088
- /** The whole message as received (`message/rfc822` bytes). */
1089
- getRaw(id: string, options?: ReadOptions$9): Promise<CossResult<Uint8Array>>;
1090
- /** 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>>;
1092
- /**
1093
- * The environment's inbound domain: email to any address at it (`support@<domain>`) is
1094
- * received, with no DNS setup.
1095
- */
1096
- address(options?: ReadOptions$9): Promise<CossResult<InboundAddress>>;
1097
- /** Deletes a received email with its raw message and attachments right away. */
1098
- delete(id: string, options?: ReadOptions$9): Promise<CossResult<DeletedReceivedEmail>>;
1099
- }
1100
- //#endregion
1101
- //#region src/resources/suppressions.d.ts
1102
- type ReadOptions$8 = Pick<RequestOptions, "signal">;
1103
- /**
1104
- * `coss.email.suppressions`: the suppression list of the API key's environment. Sends skip
1105
- * suppressed recipients; permanent bounces and complaints are added automatically.
1106
- */
1107
- declare class SuppressionResource {
1108
- #private;
1109
- /** @internal Use `new Coss().email.suppressions`. */
1110
- constructor(http: HttpClient);
1111
- /**
1112
- * Suppresses an address for every email (`scope: "*"`, the default) or for one category, e.g.
1113
- * when a recipient unsubscribes. Returns the existing entry if there already is one.
1114
- */
1115
- add(params: CreateSuppressionParams, options?: RequestOptions): Promise<CossResult<Suppression>>;
1116
- /**
1117
- * Adds many entries at once (reason `import`), 1,000 per request. Invalid entries are skipped
1118
- * and reported in `invalid`; entries already on the list count as `existing`. If a request
1119
- * fails, the earlier batches stay imported: importing everything again is safe.
1120
- */
1121
- import(params: ImportSuppressionsParams, options?: ReadOptions$8): Promise<CossResult<SuppressionImport>>;
1122
- /**
1123
- * The whole list as CSV (`address,scope,reason,created_at,email_id,id`, oldest first), which
1124
- * `import` (or the dashboard) accepts again.
1125
- */
1126
- export(params?: ExportSuppressionsParams, options?: ReadOptions$8): Promise<CossResult<string>>;
1127
- /** 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>>>;
1129
- /** Whether a send to `address` (with `category`, if given) would skip it. */
1130
- check(params: CheckSuppressionParams, options?: ReadOptions$8): Promise<CossResult<SuppressionCheck>>;
1131
- /** Retrieves one entry. */
1132
- get(id: string, options?: ReadOptions$8): Promise<CossResult<Suppression>>;
1133
- /** 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>>;
1135
- }
1136
- //#endregion
1137
- //#region src/types/tracking.d.ts
1138
- /** Tracking settings wire types (hand-written mirrors of the API's schemas). */
1139
- /** An environment's tracking default (`category: null`) or the rule for one category. */
1140
- interface TrackingRule {
1141
- object: "tracking_rule";
1142
- id: string;
1143
- /** The category the rule applies to; `null` for the environment default. */
1144
- category: string | null;
1145
- /** Whether opens are tracked. */
1146
- opens: boolean;
1147
- /** Whether clicks are tracked. */
1148
- clicks: boolean;
1149
- /** ISO 8601 timestamp. */
1150
- created_at: string;
1151
- /** ISO 8601 timestamp. */
1152
- updated_at: string;
1153
- }
1154
- /**
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.
1157
- */
1158
- interface TrackingSettings {
1159
- object: "tracking_settings";
1160
- /** The environment default; `null` when none is set. */
1161
- default: TrackingRule | null;
1162
- /** Category rules, by category name. */
1163
- categories: TrackingRule[];
1164
- }
1165
- /**
1166
- * 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.
1168
- */
1169
- interface UpdateTrackingRuleParams {
1170
- opens?: boolean;
1171
- clicks?: boolean;
1172
- }
1173
- /** Returned when a rule is removed. */
1174
- interface DeletedTrackingRule {
1175
- object: "tracking_rule";
1176
- id: string;
1177
- category: string | null;
1178
- deleted: true;
1179
- }
1180
- //#endregion
1181
- //#region src/resources/tracking.d.ts
1182
- type ReadOptions$7 = Pick<RequestOptions, "signal">;
1183
- /**
1184
- * `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.
1187
- */
1188
- declare class TrackingResource {
1189
- #private;
1190
- /** @internal Use `new Coss().email.tracking`. */
1191
- constructor(http: HttpClient);
1192
- /** The environment default and the category rules. */
1193
- get(options?: ReadOptions$7): Promise<CossResult<TrackingSettings>>;
1194
- /**
1195
- * Sets the environment default, which applies to emails without a rule for their category.
1196
- * Fields left out keep their value; a new default starts with both off.
1197
- */
1198
- updateDefault(params: UpdateTrackingRuleParams, options?: ReadOptions$7): Promise<CossResult<TrackingRule>>;
1199
- /** Removes the environment default: emails without a category rule are then not tracked. */
1200
- removeDefault(options?: ReadOptions$7): Promise<CossResult<DeletedTrackingRule>>;
1201
- /**
1202
- * Sets the rule for emails sent with `category`, which wins over the default. Fields left out
1203
- * keep their value; a new rule starts with both off.
1204
- */
1205
- updateCategory(category: string, params: UpdateTrackingRuleParams, options?: ReadOptions$7): Promise<CossResult<TrackingRule>>;
1206
- /** Removes a category's rule: its emails follow the environment default again. */
1207
- removeCategory(category: string, options?: ReadOptions$7): Promise<CossResult<DeletedTrackingRule>>;
1208
- }
1209
- //#endregion
1210
- //#region src/resources/email.d.ts
1211
- /** `coss.email`: transactional email. */
1212
- declare class EmailResource {
1213
- #private;
1214
- /** The environment's suppression list. */
1215
- readonly suppressions: SuppressionResource;
1216
- /** The environment's open and click tracking settings. */
1217
- readonly tracking: TrackingResource;
1218
- /** Emails the environment received. */
1219
- readonly received: ReceivedEmailsResource;
1220
- /** @internal Use `new Coss().email`. */
1221
- constructor(http: HttpClient);
1222
- /**
1223
- * Sends an email. It is returned `queued` and handed to the delivery provider moments later:
1224
- * `get` it or listen for the `email.sent` / `email.failed` webhooks for the outcome. Safe to
1225
- * 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.
1227
- */
1228
- send(params: SendEmailParams, options?: RequestOptions): Promise<CossResult<Email>>;
1229
- /**
1230
- * Sends up to 100 emails in one request, each as `send` would. The batch is all or nothing: if
1231
- * any email is invalid (the error's `issues` name it, e.g. `emails.3.to`), none is sent. Its
1232
- * recipients count against the send quota together. Safe to retry: one `Idempotency-Key` covers
1233
- * the whole batch. Larger lists need several calls, each with its own key.
1234
- */
1235
- sendBatch(emails: SendEmailParams[], options?: RequestOptions): Promise<CossResult<EmailBatch>>;
1236
- /** Retrieves an email sent from the same environment as the API key. */
1237
- get(id: string, options?: Pick<RequestOptions, "signal">): Promise<CossResult<Email>>;
1238
- /**
1239
- * Lists emails sent from the same environment as the API key, newest first and without their
1240
- * content (`get` one for `html`, `text`, `headers` and `attachments`). Pass the last `id` as
1241
- * `after` while `has_more` is true.
1242
- */
1243
- list(params?: ListEmailsParams, options?: Pick<RequestOptions, "signal">): Promise<CossResult<List<EmailSummary>>>;
1244
- /**
1245
- * Cancels a scheduled email. Canceling an already canceled email returns it; any other email
1246
- * fails with `email_not_cancelable`.
1247
- */
1248
- cancel(id: string, options?: Pick<RequestOptions, "signal">): Promise<CossResult<Email>>;
1249
- /**
1250
- * Moves a scheduled email to a new time and records an `email.rescheduled` event. The time it
1251
- * already has returns it unchanged; an email that is no longer scheduled fails with
1252
- * `email_not_reschedulable`.
1253
- */
1254
- reschedule(id: string, params: RescheduleEmailParams, options?: Pick<RequestOptions, "signal">): Promise<CossResult<Email>>;
1255
- /** Lists an email's delivery events, oldest first. */
1256
- listEvents(id: string, options?: Pick<RequestOptions, "signal">): Promise<CossResult<List<EmailEvent>>>;
1257
- /** Lists the links tracked for clicks in an email, in document order, with click counts. */
1258
- listLinks(id: string, options?: Pick<RequestOptions, "signal">): Promise<CossResult<List<EmailLink>>>;
1259
- }
1260
- //#endregion
1261
- //#region src/types/hooks.d.ts
1262
- /**
1263
- * 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.
1265
- */
1266
- /** One of your customers (or users), with their own endpoints and portal. */
1267
- interface HookApplication {
1268
- object: "hook_application";
1269
- id: string;
1270
- /** Your own id for it, unique in the environment; every method that takes an application accepts it. */
1271
- uid: string | null;
1272
- name: string;
1273
- metadata: Record<string, string>;
1274
- /** ISO 8601 timestamp. */
1275
- created_at: string;
1276
- updated_at: string;
1277
- }
1278
- /** Body of `POST /v1/hooks/applications`. */
1279
- interface CreateHookApplicationParams {
1280
- /** Shown to the application's users in the portal. */
1281
- name: string;
1282
- /** Your own id for it (1-256 letters, digits and `. _ : @ | -`). */
1283
- uid?: string;
1284
- /** Up to 16 keys (up to 40 characters) with string values (up to 500). */
1285
- metadata?: Record<string, string>;
1286
- }
1287
- /** Body of `PATCH /v1/hooks/applications/{application}`. Omitted fields keep their value. */
1288
- interface UpdateHookApplicationParams {
1289
- name?: string;
1290
- /** `null` removes it. */
1291
- uid?: string | null;
1292
- /** Replaces the metadata. */
1293
- metadata?: Record<string, string>;
1294
- }
1295
- /** Query of `GET /v1/hooks/applications`. */
1296
- interface ListHookApplicationsParams {
1297
- /** 1-100, default 50. */
1298
- limit?: number;
1299
- /** Cursor: the `id` of the last application of the previous page. */
1300
- after?: string;
1301
- }
1302
- /** Returned by `hooks.applications.delete`. */
1303
- interface DeletedHookApplication {
1304
- object: "hook_application";
1305
- id: string;
1306
- deleted: true;
1307
- }
1308
- /** A type of message you send (e.g. `invoice.paid`): the catalog your users subscribe from. */
1309
- interface HookEventType {
1310
- object: "hook_event_type";
1311
- name: string;
1312
- description: string | null;
1313
- /** A JSON Schema of the payload, shown to your users (not enforced). */
1314
- schema: Record<string, unknown> | null;
1315
- /** Example payloads; the first is what a test send delivers. */
1316
- examples: Record<string, unknown>[];
1317
- /** Hidden from the portal and new subscriptions; already subscribed endpoints still receive it. */
1318
- archived: boolean;
1319
- created_at: string;
1320
- updated_at: string;
1321
- }
1322
- /** Body of `POST /v1/hooks/event_types`. */
1323
- interface CreateHookEventTypeParams {
1324
- /** 1-64 letters, digits and `. _ -`. */
1325
- name: string;
1326
- description?: string;
1327
- schema?: Record<string, unknown>;
1328
- /** Up to 5. */
1329
- examples?: Record<string, unknown>[];
1330
- }
1331
- /** Body of `PATCH /v1/hooks/event_types/{name}`. */
1332
- interface UpdateHookEventTypeParams {
1333
- description?: string | null;
1334
- schema?: Record<string, unknown> | null;
1335
- examples?: Record<string, unknown>[];
1336
- /** `false` restores an archived type. */
1337
- archived?: boolean;
1338
- }
1339
- /** Query of `GET /v1/hooks/event_types`. */
1340
- interface ListHookEventTypesParams {
1341
- /** Also list archived types. */
1342
- include_archived?: boolean;
1343
- /** 1-100, default 50. */
1344
- limit?: number;
1345
- /** Cursor: the `name` of the last type of the previous page. */
1346
- after?: string;
1347
- }
1348
- /** Why an endpoint is disabled. */
1349
- type HookEndpointDisabledReason = "manual" | "failing";
1350
- /** A URL of an application's user that receives its messages, signed with its own secret. */
1351
- interface HookEndpoint {
1352
- object: "hook_endpoint";
1353
- id: string;
1354
- application_id: string;
1355
- url: string;
1356
- description: string | null;
1357
- /** Event types delivered; empty means every type. */
1358
- filter_types: string[];
1359
- rate_limit_per_second: number | null;
1360
- enabled: boolean;
1361
- /** `manual`, or `failing` (its deliveries failed every attempt for five days); `null` while enabled. */
1362
- disabled_reason: HookEndpointDisabledReason | null;
1363
- disabled_at: string | null;
1364
- /** When its current run of failed deliveries began; `null` while healthy. */
1365
- failing_since: string | null;
1366
- /** After a secret roll, requests are also signed with the previous secret until then. */
1367
- previous_secret_expires_at: string | null;
1368
- metadata: Record<string, string>;
1369
- created_at: string;
1370
- updated_at: string;
1371
- }
1372
- /** A created endpoint, or one whose secret was just rolled. */
1373
- interface HookEndpointWithSecret extends HookEndpoint {
1374
- /** The `whsec_…` signing secret (Standard Webhooks). */
1375
- secret: string;
1376
- }
1377
- /** Body of `POST /v1/hooks/applications/{application}/endpoints`. */
1378
- interface CreateHookEndpointParams {
1379
- /** An `https://` URL. */
1380
- url: string;
1381
- description?: string;
1382
- /** Existing, unarchived event types; omitted or empty means every type. */
1383
- filter_types?: string[];
1384
- /** A `whsec_` + base64 secret of 24-64 bytes (e.g. migrated from another provider). */
1385
- secret?: string;
1386
- /** 1-1000. */
1387
- rate_limit_per_second?: number;
1388
- metadata?: Record<string, string>;
1389
- enabled?: boolean;
1390
- }
1391
- /** Body of `PATCH /v1/hooks/applications/{application}/endpoints/{id}`. */
1392
- interface UpdateHookEndpointParams {
1393
- url?: string;
1394
- description?: string | null;
1395
- filter_types?: string[];
1396
- rate_limit_per_second?: number | null;
1397
- metadata?: Record<string, string>;
1398
- enabled?: boolean;
1399
- }
1400
- /** Returned by `hooks.endpoints.delete`. */
1401
- interface DeletedHookEndpoint {
1402
- object: "hook_endpoint";
1403
- id: string;
1404
- deleted: true;
1405
- }
1406
- /** Returned by `hooks.endpoints.getSecret`. */
1407
- interface HookEndpointSecret {
1408
- object: "hook_endpoint_secret";
1409
- secret: string;
1410
- }
1411
- /** Body of `POST …/endpoints/{id}/roll_secret`. */
1412
- interface RollHookEndpointSecretParams {
1413
- /** Seconds the current secret keeps signing next to the new one: default 86400, at most 604800, `0` stops it now. */
1414
- previous_secret_expires_in?: number;
1415
- }
1416
- /** Body of `POST …/endpoints/{id}/recover`. */
1417
- interface RecoverHookEndpointParams {
1418
- /** Requeue failed deliveries of messages sent since then (ISO 8601 string or `Date`). */
1419
- since: string | Date;
1420
- }
1421
- /** A recovery: COSS requeues the matching failed deliveries in the background. */
1422
- interface HookEndpointRecovery {
1423
- object: "hook_endpoint_recovery";
1424
- id: string;
1425
- endpoint_id: string;
1426
- since: string;
1427
- until: string;
1428
- status: "pending" | "completed";
1429
- requeued: number;
1430
- created_at: string;
1431
- completed_at: string | null;
1432
- }
1433
- /** Body of `POST …/endpoints/{id}/test`. */
1434
- interface SendHookTestParams {
1435
- event_type: string;
1436
- /** Defaults to the event type's first example. */
1437
- payload?: Record<string, unknown>;
1438
- }
1439
- /** A message sent to an application. */
1440
- interface HookMessage {
1441
- object: "hook_message";
1442
- /** Also the `webhook-id` header of every request delivering it. */
1443
- id: string;
1444
- application_id: string;
1445
- event_type: string;
1446
- /** The JSON body delivered to each endpoint. */
1447
- payload: Record<string, unknown>;
1448
- created_at: string;
1449
- }
1450
- /** Params of `hooks.messages.send`: the application, then the body of `POST …/messages`. */
1451
- interface SendHookMessageParams {
1452
- /** The application's id or uid. */
1453
- application: string;
1454
- /** e.g. `invoice.paid`; endpoints filtering by type only get the types they chose. */
1455
- event_type: string;
1456
- /** At most 256 KB serialized; send integers beyond 2^53 as strings. */
1457
- payload: Record<string, unknown>;
1458
- }
1459
- /** Query of `GET …/messages`. */
1460
- interface ListHookMessagesParams {
1461
- /** Only messages of this type. */
1462
- event_type?: string;
1463
- /** 1-100, default 50. */
1464
- limit?: number;
1465
- /** Cursor: the `id` of the last message of the previous page. */
1466
- after?: string;
1467
- }
1468
- /**
1469
- * `pending`: waiting for its next attempt. `succeeded`: the endpoint answered 2xx. `failed`: every
1470
- * attempt failed, or the endpoint was disabled or deleted.
1471
- */
1472
- type HookDeliveryStatus = "pending" | "succeeded" | "failed";
1473
- /** One message's delivery to one endpoint. */
1474
- interface HookDelivery {
1475
- object: "hook_delivery";
1476
- id: string;
1477
- application_id: string;
1478
- message_id: string;
1479
- endpoint_id: string;
1480
- status: HookDeliveryStatus;
1481
- attempt_count: number;
1482
- next_attempt_at: string | null;
1483
- last_status_code: number | null;
1484
- last_error: string | null;
1485
- created_at: string;
1486
- finished_at: string | null;
1487
- }
1488
- /** Query of `GET …/endpoints/{id}/deliveries`. */
1489
- interface ListHookDeliveriesParams {
1490
- status?: HookDeliveryStatus;
1491
- /** 1-100, default 50. */
1492
- limit?: number;
1493
- /** Cursor: the `id` of the last delivery of the previous page. */
1494
- after?: string;
1495
- }
1496
- /** One HTTP request of a delivery. */
1497
- interface HookAttempt {
1498
- object: "hook_attempt";
1499
- id: string;
1500
- delivery_id: string;
1501
- endpoint_id: string;
1502
- attempted_at: string;
1503
- /** `null` when no response arrived. */
1504
- status_code: number | null;
1505
- duration_ms: number;
1506
- error: string | null;
1507
- /** At most 1 KB of the response body. */
1508
- response_excerpt: string | null;
1509
- }
1510
- /** Params of `hooks.portal.createSession`. */
1511
- interface CreateHookPortalSessionParams {
1512
- /** The application's id or uid. */
1513
- application: string;
1514
- /** Seconds until it expires: default 3600, 60-86400. */
1515
- expires_in?: number;
1516
- /** The user can look but not change anything. */
1517
- read_only?: boolean;
1518
- }
1519
- /** A portal sign-in for one application's user. */
1520
- interface HookPortalSession {
1521
- object: "hook_portal_session";
1522
- id: string;
1523
- application_id: string;
1524
- /** Open it or embed it (from an allowed origin); the token is in its fragment. */
1525
- url: string;
1526
- /** The secret part of `url`. */
1527
- token: string;
1528
- read_only: boolean;
1529
- expires_at: string;
1530
- }
1531
- //#endregion
1532
- //#region src/resources/hooks.d.ts
1533
- type ReadOptions$6 = Pick<RequestOptions, "signal">;
1534
- /** `coss.hooks.applications`: your customers, each with their own endpoints and portal. */
1535
- declare class HookApplicationsResource {
1536
- #private;
1537
- /** @internal Use `new Coss().hooks.applications`. */
1538
- constructor(http: HttpClient);
1539
- /** Creates an application. Never automatically retried (the API does not deduplicate it). */
1540
- create(params: CreateHookApplicationParams, options?: RequestOptions): Promise<CossResult<HookApplication>>;
1541
- /** Lists the environment's applications, newest first. */
1542
- list(params?: ListHookApplicationsParams, options?: ReadOptions$6): Promise<CossResult<List<HookApplication>>>;
1543
- /** 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>>;
1546
- /** Deletes the application with its endpoints and portal sessions. */
1547
- delete(application: string, options?: ReadOptions$6): Promise<CossResult<DeletedHookApplication>>;
1548
- }
1549
- /** `coss.hooks.eventTypes`: the catalog of messages you send, which your users subscribe from. */
1550
- declare class HookEventTypesResource {
1551
- #private;
1552
- /** @internal Use `new Coss().hooks.eventTypes`. */
1553
- constructor(http: HttpClient);
1554
- /** Creates an event type. Never automatically retried (a retry would find it existing). */
1555
- create(params: CreateHookEventTypeParams, options?: RequestOptions): Promise<CossResult<HookEventType>>;
1556
- /** 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>>;
1559
- /** Changes its description, schema or examples, or archives or restores it. */
1560
- update(name: string, params: UpdateHookEventTypeParams, options?: ReadOptions$6): Promise<CossResult<HookEventType>>;
1561
- /** Archives it: hidden from the portal and new subscriptions. */
1562
- archive(name: string, options?: ReadOptions$6): Promise<CossResult<HookEventType>>;
1563
- }
1564
- /** `coss.hooks.endpoints`: an application's endpoints (usually added by its users in the portal). */
1565
- declare class HookEndpointsResource {
1566
- #private;
1567
- /** @internal Use `new Coss().hooks.endpoints`. */
1568
- constructor(http: HttpClient);
1569
- /** Creates an endpoint; the result carries its secret. Never automatically retried. */
1570
- 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>>;
1575
- /** The endpoint's current signing secret. */
1576
- getSecret(application: string, id: string, options?: ReadOptions$6): Promise<CossResult<HookEndpointSecret>>;
1577
- /** Replaces the signing secret. Never automatically retried (a second roll would stop the first). */
1578
- rollSecret(application: string, id: string, params?: RollHookEndpointSecretParams, options?: RequestOptions): Promise<CossResult<HookEndpointWithSecret>>;
1579
- /** Requeues the endpoint's failed deliveries of messages sent since `since` (in the background). */
1580
- 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>>;
1582
- /** Sends a message to this endpoint only. Never automatically retried. */
1583
- sendTest(application: string, id: string, params: SendHookTestParams, options?: RequestOptions): Promise<CossResult<HookMessage>>;
1584
- /** The endpoint's deliveries, newest first. */
1585
- listDeliveries(application: string, id: string, params?: ListHookDeliveriesParams, options?: ReadOptions$6): Promise<CossResult<List<HookDelivery>>>;
1586
- }
1587
- /** `coss.hooks.messages`: send a message once; COSS delivers it to every subscribed endpoint. */
1588
- declare class HookMessagesResource {
1589
- #private;
1590
- /** @internal Use `new Coss().hooks.messages`. */
1591
- constructor(http: HttpClient);
1592
- /**
1593
- * Sends a message to an application. Safe to retry: every attempt carries the same
1594
- * `Idempotency-Key`, so a retried send is delivered once.
1595
- */
1596
- send(params: SendHookMessageParams, options?: RequestOptions): Promise<CossResult<HookMessage>>;
1597
- /** 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>>;
1600
- /** One delivery per endpoint the message went to. */
1601
- listDeliveries(application: string, id: string, options?: ReadOptions$6): Promise<CossResult<List<HookDelivery>>>;
1602
- }
1603
- /** `coss.hooks.deliveries`: one message's delivery to one endpoint. */
1604
- declare class HookDeliveriesResource {
1605
- #private;
1606
- /** @internal Use `new Coss().hooks.deliveries`. */
1607
- constructor(http: HttpClient);
1608
- get(application: string, id: string, options?: ReadOptions$6): Promise<CossResult<HookDelivery>>;
1609
- /** Every HTTP request of the delivery, oldest first. */
1610
- listAttempts(application: string, id: string, options?: ReadOptions$6): Promise<CossResult<List<HookAttempt>>>;
1611
- /** Queues a finished delivery for one more attempt. Never automatically retried. */
1612
- retry(application: string, id: string, options?: RequestOptions): Promise<CossResult<HookDelivery>>;
1613
- }
1614
- /** `coss.hooks.portal`: a ready-made page for an application's user to manage their endpoints. */
1615
- declare class HookPortalResource {
1616
- #private;
1617
- /** @internal Use `new Coss().hooks.portal`. */
1618
- constructor(http: HttpClient);
1619
- /**
1620
- * Signs the application's user in to the portal: open or embed the returned `url`. Call it from
1621
- * your backend each time the user opens the portal.
1622
- */
1623
- createSession(params: CreateHookPortalSessionParams, options?: RequestOptions): Promise<CossResult<HookPortalSession>>;
1624
- }
1625
- /**
1626
- * `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
1628
- * (Standard Webhooks), with retries, and gives them a portal to manage it all.
1629
- */
1630
- declare class HooksResource {
1631
- readonly applications: HookApplicationsResource;
1632
- readonly eventTypes: HookEventTypesResource;
1633
- readonly endpoints: HookEndpointsResource;
1634
- readonly messages: HookMessagesResource;
1635
- readonly deliveries: HookDeliveriesResource;
1636
- readonly portal: HookPortalResource;
1637
- /** @internal Use `new Coss().hooks`. */
1638
- constructor(http: HttpClient);
1639
- }
1640
- //#endregion
1641
- //#region src/types/log.d.ts
1642
- /** Log wire types (hand-written mirrors of the API's schemas). */
1643
- /**
1644
- * `api`: a request to the API. `email`: an email event. `webhook`: a webhook delivery attempt.
1645
- * `risk`: a risk assessment or its feedback.
1646
- */
1647
- type LogSource = "api" | "email" | "webhook" | "risk";
1648
- /**
1649
- * `error`: 5xx responses, bounces, complaints, failures. `warning`: 4xx responses, delays,
1650
- * suppressions, failed webhook attempts that will be retried. `info`: everything else.
1651
- */
1652
- type LogLevel = "info" | "warning" | "error";
1653
- /** One line of the API key's environment's log. */
1654
- interface Log {
1655
- object: "log";
1656
- id: string;
1657
- /** ISO 8601 timestamp. */
1658
- occurred_at: string;
1659
- source: LogSource;
1660
- level: LogLevel;
1661
- /** `api.request`, `webhook.attempt`, or an email event type such as `email.delivered`. */
1662
- type: string;
1663
- /** A one-line summary. */
1664
- message: string;
1665
- /** The `X-Request-Id` of the API request this line belongs to. */
1666
- request_id: string | null;
1667
- api_key_id: string | null;
1668
- method: string | null;
1669
- path: string | null;
1670
- /** The matched route, e.g. `/v1/emails/:id`. */
1671
- route: string | null;
1672
- /** The API response status, or the webhook endpoint's response status. */
1673
- status_code: number | null;
1674
- duration_ms: number | null;
1675
- client_ip: string | null;
1676
- user_agent: string | null;
1677
- error_code: string | null;
1678
- /** What the line is about: `email`, `domain`, `webhook_endpoint`… */
1679
- resource_type: string | null;
1680
- resource_id: string | null;
1681
- recipient: string | null;
1682
- /**
1683
- * Details: redacted request and response bodies for API requests, event data for emails and
1684
- * webhooks.
1685
- */
1686
- attributes: Record<string, unknown>;
1687
- }
1688
- type OneOrMany<T> = T | readonly T[];
1689
- /** Query of `GET /v1/logs`. Lists may be given as arrays or comma-separated strings. */
1690
- interface ListLogsParams {
1691
- /** Start of the range (inclusive). Defaults to an hour before `to`. */
1692
- from?: string | Date;
1693
- /** End of the range (exclusive). Defaults to now. At most 31 days after `from`. */
1694
- to?: string | Date;
1695
- source?: OneOrMany<LogSource>;
1696
- level?: OneOrMany<LogLevel>;
1697
- /** e.g. `"email.bounced"`. */
1698
- type?: OneOrMany<string>;
1699
- /** Status codes or classes, e.g. `["4xx", "503"]`. */
1700
- status?: OneOrMany<string | number>;
1701
- method?: OneOrMany<string>;
1702
- /** Routes such as `/v1/emails/:id`. */
1703
- route?: OneOrMany<string>;
1704
- api_key_id?: OneOrMany<string>;
1705
- request_id?: string;
1706
- /** Only lines about this resource, e.g. an `email_…` id. */
1707
- resource_id?: string;
1708
- /** Free text, matched against the message, path, ids and recipient. */
1709
- q?: string;
1710
- /** 1-100, default 50. */
1711
- limit?: number;
1712
- /** The `id` of the last line of the previous page. */
1713
- after?: string;
1714
- }
1715
- //#endregion
1716
- //#region src/types/log-drain.d.ts
1717
- /**
1718
- * What a drain forwards: `api` (requests made with the environment's API keys), `email` (email
1719
- * events), `webhook` (webhook delivery attempts) and `audit` (changes to the environment, from
1720
- * the organization's audit log).
1721
- */
1722
- type LogDrainSource = LogSource | "audit";
1723
- /** An HTTPS endpoint the environment's log is streamed to, in signed NDJSON batches. */
1724
- interface LogDrain {
1725
- object: "log_drain";
1726
- id: string;
1727
- url: string;
1728
- description: string | null;
1729
- /** Empty means every source, including ones added later. */
1730
- sources: LogDrainSource[];
1731
- /** A disabled drain receives nothing, and lines logged meanwhile are not kept for it. */
1732
- enabled: boolean;
1733
- /** `manual`, or `failing`: a batch failed every attempt, so COSS disabled it. */
1734
- disabled_reason: "manual" | "failing" | null;
1735
- /** ISO 8601 timestamp; `null` while enabled. */
1736
- disabled_at: string | null;
1737
- created_at: string;
1738
- updated_at: string;
1739
- }
1740
- /** A drain with its `whsec_…` signing secret, returned only when it is created. */
1741
- interface LogDrainWithSecret extends LogDrain {
1742
- secret: string;
1743
- }
1744
- interface DeletedLogDrain {
1745
- object: "log_drain";
1746
- id: string;
1747
- deleted: true;
1748
- }
1749
- interface CreateLogDrainParams {
1750
- /** An `https://` URL COSS posts batches to. */
1751
- url: string;
1752
- description?: string | null;
1753
- /** Defaults to every source. */
1754
- sources?: LogDrainSource[];
1755
- }
1756
- interface UpdateLogDrainParams {
1757
- url?: string;
1758
- /** `null` clears it. */
1759
- description?: string | null;
1760
- sources?: LogDrainSource[];
1761
- /** Disabling drops the lines still waiting for the drain. */
1762
- enabled?: boolean;
1763
- }
1764
- type LogDrainBatchStatus = "pending" | "succeeded" | "failed";
1765
- /** One HTTP attempt of a batch. */
1766
- interface LogDrainAttempt {
1767
- object: "log_drain_attempt";
1768
- id: string;
1769
- attempted_at: string;
1770
- /** `null` when no response arrived. */
1771
- status_code: number | null;
1772
- duration_ms: number;
1773
- error: string | null;
1774
- /** At most 1 KB of the response body, as text. */
1775
- response_excerpt: string | null;
1776
- }
1777
- /** One NDJSON request; its `id` is the `webhook-id` header, the same on every attempt. */
1778
- interface LogDrainBatch {
1779
- object: "log_drain_batch";
1780
- id: string;
1781
- drain_id: string;
1782
- status: LogDrainBatchStatus;
1783
- line_count: number;
1784
- byte_size: number;
1785
- attempt_count: number;
1786
- next_attempt_at: string | null;
1787
- last_status_code: number | null;
1788
- last_error: string | null;
1789
- /** Oldest first. */
1790
- attempts: LogDrainAttempt[];
1791
- created_at: string;
1792
- updated_at: string;
1793
- }
1794
- interface ListLogDrainBatchesParams {
1795
- status?: LogDrainBatchStatus;
1796
- /** 1-100, default 50. */
1797
- limit?: number;
1798
- /** The `id` of the last batch of the previous page. */
1799
- after?: string;
1800
- }
1801
- /**
1802
- * One line of a log drain batch: a log line (as `coss.logs.list()` returns it) or an audit event
1803
- * of the environment (as `coss.auditEvents.list()` returns it).
1804
- */
1805
- type LogDrainLine = Log | AuditEvent;
1806
- //#endregion
1807
- //#region src/resources/log-drains.d.ts
1808
- type ReadOptions$5 = Pick<RequestOptions, "signal">;
1809
- /** `coss.logDrains.batches`: a drain's delivery log, each batch with every HTTP attempt. */
1810
- declare class LogDrainBatchesResource {
1811
- #private;
1812
- /** @internal Use `new Coss().logDrains.batches`. */
1813
- constructor(http: HttpClient);
1814
- /** 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>>>;
1816
- /** Retrieves one batch of the drain. */
1817
- get(drainId: string, id: string, options?: ReadOptions$5): Promise<CossResult<LogDrainBatch>>;
1818
- }
1819
- /**
1820
- * `coss.logDrains`: HTTPS endpoints the environment's log is streamed to (API requests, email
1821
- * events, webhook attempts and audit events), in signed NDJSON batches. Drains belong to the API
1822
- * key's own environment, so a `coss_test_…` key only ever manages sandbox drains.
1823
- */
1824
- declare class LogDrainsResource {
1825
- #private;
1826
- /** Each drain's delivery log. */
1827
- readonly batches: LogDrainBatchesResource;
1828
- /** @internal Use `new Coss().logDrains`. */
1829
- constructor(http: HttpClient);
1830
- /**
1831
- * Creates a drain. The result carries its `secret` (returned only here) — store it and pass it
1832
- * to `verifyLogDrainBatch` for every request. Creation is never automatically retried: the API
1833
- * does not deduplicate it. After a lost response, list drains and remove the one with the
1834
- * unknown secret before creating a replacement.
1835
- */
1836
- create(params: CreateLogDrainParams, options?: RequestOptions): Promise<CossResult<LogDrainWithSecret>>;
1837
- /** Lists the environment's drains, oldest first. Secrets are never included. */
1838
- list(options?: ReadOptions$5): Promise<CossResult<List<LogDrain>>>;
1839
- /** Retrieves a drain of the API key's environment. */
1840
- get(id: string, options?: ReadOptions$5): Promise<CossResult<LogDrain>>;
1841
- /**
1842
- * 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
1844
- * disabled it for failing) sends lines logged from then on.
1845
- */
1846
- update(id: string, params: UpdateLogDrainParams, options?: ReadOptions$5): Promise<CossResult<LogDrain>>;
1847
- /** 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>>;
1849
- }
1850
- //#endregion
1851
- //#region src/resources/logs.d.ts
1852
- type ReadOptions$4 = Pick<RequestOptions, "signal">;
1853
- /**
1854
- * `coss.logs`: the API key's environment log, newest first: API requests made with its keys,
1855
- * email events and webhook delivery attempts.
1856
- */
1857
- declare class LogsResource {
1858
- #private;
1859
- /** @internal Use `new Coss().logs`. */
1860
- constructor(http: HttpClient);
1861
- /**
1862
- * Lists log lines, newest first (the last hour unless `from`/`to` say otherwise). Pass the last
1863
- * `id` as `after` while `has_more` is true.
1864
- */
1865
- list(params?: ListLogsParams, options?: ReadOptions$4): Promise<CossResult<List<Log>>>;
1866
- /** Retrieves one log line. */
1867
- get(id: string, options?: ReadOptions$4): Promise<CossResult<Log>>;
1868
- }
1869
- //#endregion
1870
- //#region src/types/reputation.d.ts
1871
- /** Reputation wire types (hand-written mirrors of the API's `Reputation` schema). */
1872
- type ReputationStatus = "good" | "warning" | "suspended";
1873
- type ReputationCheckSeverity = "ok" | "warning" | "suspend";
1874
- /** One signal the reputation guard measured, e.g. the bounce rate. */
1875
- interface ReputationCheck {
1876
- /** What was measured, e.g. `bounce_rate` or `complaint_rate`. */
1877
- trigger: string;
1878
- severity: ReputationCheckSeverity;
1879
- message: string;
1880
- /** `count / volume`; `null` with no volume. */
1881
- rate: number | null;
1882
- count: number;
1883
- /** Recipients sent to (live environments) in the window. */
1884
- volume: number;
1885
- warning_threshold: number | null;
1886
- suspend_threshold: number | null;
1887
- /** Below this volume the rate is reported but never acted on. */
1888
- minimum_volume: number | null;
1889
- }
1890
- /** `GET /v1/reputation`: the organization's standing with the reputation guard. */
1891
- interface Reputation {
1892
- object: "reputation";
1893
- /**
1894
- * `suspended` means live sending is refused (`account_suspended`) until COSS support
1895
- * reinstates the organization; sandbox keys keep working.
1896
- */
1897
- status: ReputationStatus;
1898
- /** The trigger behind a `warning` or `suspended` status. */
1899
- reason: string | null;
1900
- /** ISO 8601 timestamp. */
1901
- status_changed_at: string | null;
1902
- /** When `checks` were computed; `null` before the first evaluation. */
1903
- evaluated_at: string | null;
1904
- /** The period `checks` cover. */
1905
- window: {
1906
- start: string;
1907
- end: string;
1908
- } | null;
1909
- checks: ReputationCheck[];
1910
- }
1911
- //#endregion
1912
- //#region src/resources/reputation.d.ts
1913
- type ReadOptions$3 = Pick<RequestOptions, "signal">;
1914
- /**
1915
- * `coss.reputation`: the organization's standing with the COSS reputation guard, which suspends
1916
- * live sending automatically when bounce or complaint rates cross its thresholds.
1917
- */
1918
- declare class ReputationResource {
1919
- #private;
1920
- /** @internal Use `new Coss().reputation`. */
1921
- constructor(http: HttpClient);
1922
- /** The current status and the latest rates measured over live environments. */
1923
- get(options?: ReadOptions$3): Promise<CossResult<Reputation>>;
1924
- }
1925
- //#endregion
1926
- //#region src/types/risk.d.ts
1927
- /** Risk wire types (hand-written mirrors of the API's schemas). */
1928
- /** What is being assessed. Velocity is counted per event (`custom` events per `event_name`). */
1929
- type RiskEvent = "signup" | "login" | "message" | "checkout" | "custom";
1930
- /** `allow`: go ahead. `review`: suspicious; limit or hold it for a person. `block`: refuse it. */
1931
- type RiskDecision = "allow" | "review" | "block";
1932
- /** What really happened: `legitimate`, `fraud`, or `abuse` (spam, free-tier abuse…). */
1933
- type RiskOutcome = "legitimate" | "fraud" | "abuse";
1934
- type RiskList = "allow" | "block";
1935
- /**
1936
- * `email` (matched by mailbox, dots and `+tags` folded), `domain` (subdomains included), `ip` (an
1937
- * address or CIDR range), `asn`, `country` (ISO 3166-1 alpha-2), `user` (your user id).
1938
- */
1939
- type RiskListEntryType = "email" | "domain" | "ip" | "asn" | "country" | "user";
1940
- /** Signal groups an assessment was made without (a lookup failed or timed out). */
1941
- type RiskDegradedSignal = "email_dns" | "domain_age" | "ip_data" | "velocity" | "captcha" | "content" | "ip_privacy";
1942
- /** What content classification scores. */
1943
- type RiskContentCategory = "spam" | "phishing" | "malware" | "fraud";
1944
- /**
1945
- * Per category, the model's probability (0-1) that the content belongs to it. Not calibrated:
1946
- * pick thresholds by looking at your own traffic.
1947
- */
1948
- type RiskContentScores = Record<RiskContentCategory, number>;
1949
- /** Every reason an assessment can give (see the reason catalog in the docs). */
1950
- type RiskReasonCode = "email.invalid" | "email.disposable" | "email.undeliverable" | "email.role_account" | "email.typo" | "email.domain_new" | "ip.tor" | "ip.vpn_network" | "ip.hosting_provider" | "ip.vpn" | "ip.proxy" | "ip.relay" | "ip.private" | "velocity.signups_per_ip_1h" | "velocity.signups_per_ip_24h" | "velocity.signups_per_subnet_1h" | "velocity.signups_per_email_domain_1h" | "velocity.signups_per_mailbox_24h" | "velocity.signups_per_device_24h" | "velocity.checkouts_per_ip_1h" | "velocity.checkouts_per_user_1h" | "velocity.checkouts_per_card_24h" | "velocity.logins_per_ip_1h" | "velocity.logins_per_user_1h" | "velocity.events_per_ip_1h" | "velocity.events_per_user_1h" | "duplicate.canonical_mailbox" | "duplicate.device" | "history.fraud_mailbox" | "history.fraud_user" | "history.fraud_ip" | "history.fraud_subnet" | "history.fraud_card" | "history.fraud_device" | "checkout.card_country_mismatch" | "checkout.billing_country_mismatch" | "checkout.prepaid_card" | "device.automation" | "device.invalid" | "login.new_country" | "login.new_network" | "captcha.failed" | "captcha.missing" | "content.spam" | "content.phishing" | "content.malware" | "content.fraud" | "rule.matched" | "list.blocked" | "list.allowed";
1951
- /** Why an assessment decided what it did. Never show reasons to the person being assessed. */
1952
- interface RiskReason {
1953
- code: RiskReasonCode;
1954
- /** For developers (dashboards, logs). */
1955
- message: string;
1956
- /** The count behind a `velocity.*` reason. */
1957
- value?: number;
1958
- /** The count a `velocity.*` reason fires at. */
1959
- threshold?: number;
1960
- window?: "1h" | "24h";
1961
- /** `email.typo`: the likely domain, which you may show the user ("Did you mean …?"). */
1962
- suggestion?: string;
1963
- /** `ip.hosting_provider`, `ip.vpn_network`: the network's operator; `ip.vpn`: the VPN service. */
1964
- provider?: string;
1965
- /** `duplicate.*`: your id of the user who has the mailbox or device, if known. */
1966
- previous_user?: string | null;
1967
- /** `duplicate.*`: the assessment that first saw the mailbox or device. */
1968
- previous_assessment?: string;
1969
- /** `list.*`: the matching list entry. */
1970
- entry?: string;
1971
- /** `list.*`: what matched. */
1972
- type?: RiskListEntryType;
1973
- /** `rule.matched`: the rule's id. */
1974
- rule?: string;
1975
- /** `rule.matched`: the rule's name. */
1976
- name?: string;
1977
- }
1978
- interface RiskEmailSignals {
1979
- /** `null` once the address is removed (90 days after the assessment). */
1980
- domain: string | null;
1981
- valid: boolean;
1982
- disposable: boolean;
1983
- /** From DNS (MX, A, AAAA). `unknown` when the lookup failed or timed out. */
1984
- deliverability: "deliverable" | "undeliverable" | "unknown";
1985
- role_account: boolean;
1986
- free_provider: boolean;
1987
- suggestion: string | null;
1988
- /**
1989
- * Days since the domain was registered (RDAP); `null` when unknown or not looked up (free
1990
- * providers, disposable domains).
1991
- */
1992
- domain_age_days: number | null;
1993
- }
1994
- interface RiskCaptchaSignals {
1995
- provided: boolean;
1996
- /** `null` when it couldn't be checked (no captcha configured, or the provider was unreachable). */
1997
- passed: boolean | null;
1998
- }
1999
- /** Logins of a user with history: whether the country or network is new for them. */
2000
- interface RiskLoginSignals {
2001
- new_country: boolean;
2002
- new_network: boolean;
2003
- }
2004
- interface RiskIpSignals {
2005
- version: 4 | 6;
2006
- private: boolean;
2007
- tor: boolean;
2008
- hosting: boolean;
2009
- hosting_provider: string | null;
2010
- hosting_kind: "cloud" | "hosting" | "vpn" | null;
2011
- asn: number | null;
2012
- as_name: string | null;
2013
- /** ISO 3166-1 alpha-2. */
2014
- country: string | null;
2015
- /**
2016
- * From COSS's IP privacy data provider; `null` when it isn't available or was not asked
2017
- * (private addresses).
2018
- */
2019
- privacy: RiskIpPrivacy | null;
2020
- }
2021
- /** Whether an address is a VPN exit, a proxy or a privacy relay (iCloud Private Relay…). */
2022
- interface RiskIpPrivacy {
2023
- vpn: boolean;
2024
- proxy: boolean;
2025
- relay: boolean;
2026
- /** The VPN or proxy service. */
2027
- service: string | null;
2028
- }
2029
- /** How a card is funded, as your payment processor reports it. */
2030
- type RiskCardFunding = "credit" | "debit" | "prepaid" | "unknown";
2031
- /** What you sent in `checkout` (never the card). */
2032
- interface RiskCheckoutSignals {
2033
- amount: number;
2034
- currency: string;
2035
- card_country: string | null;
2036
- card_funding: RiskCardFunding | null;
2037
- billing_country: string | null;
2038
- shipping_country: string | null;
2039
- }
2040
- /** What the browser reported through `coss/device` (its device id is only kept as a keyed hash). */
2041
- interface RiskDeviceSignals {
2042
- /** `false`: the token was malformed or too old. */
2043
- valid: boolean;
2044
- /** WebDriver control or a headless browser. */
2045
- automation: boolean;
2046
- /** IANA time zone (`Europe/London`). */
2047
- timezone: string | null;
2048
- /** The browser's first language. */
2049
- language: string | null;
2050
- platform: string | null;
2051
- /** `<width>x<height>` in CSS pixels. */
2052
- screen: string | null;
2053
- touch: boolean | null;
2054
- }
2055
- /** An assessment of one event. */
2056
- interface RiskAssessment {
2057
- object: "risk_assessment";
2058
- id: string;
2059
- event: RiskEvent;
2060
- event_name: string | null;
2061
- decision: RiskDecision;
2062
- /** 0-1: how risky the signals are together. Lists can decide regardless of the score. */
2063
- score: number;
2064
- /** Why, most significant first. */
2065
- reasons: RiskReason[];
2066
- signals: {
2067
- email: RiskEmailSignals | null;
2068
- ip: RiskIpSignals | null;
2069
- /**
2070
- * Events of the same kind in this environment, this one included, keyed
2071
- * `<dimension>_<window>` (e.g. `ip_1h`, `mailbox_24h`); `null` when unavailable.
2072
- */
2073
- velocity: Record<string, number> | null;
2074
- captcha: RiskCaptchaSignals | null;
2075
- login: RiskLoginSignals | null;
2076
- /** `null` when no content was given or it couldn't be classified. */
2077
- content: RiskContentScores | null;
2078
- checkout: RiskCheckoutSignals | null;
2079
- device: RiskDeviceSignals | null;
2080
- };
2081
- user: {
2082
- id: string | null;
2083
- email: string | null;
2084
- };
2085
- /** `null` once removed (90 days after the assessment). */
2086
- ip: string | null;
2087
- degraded: RiskDegradedSignal[];
2088
- /** The latest outcome you reported with `coss.risk.feedback`. */
2089
- outcome: RiskOutcome | null;
2090
- /** `open` for `review` decisions until you send feedback, then `resolved`. */
2091
- review_status: "open" | "resolved" | null;
2092
- /** ISO 8601 timestamp. */
2093
- created_at: string;
2094
- }
2095
- /** Body of `POST /v1/risk/assessments`. */
2096
- interface AssessRiskParams {
2097
- event: RiskEvent;
2098
- /** Required for `custom` events (e.g. `invite_sent`), not allowed otherwise. */
2099
- event_name?: string;
2100
- user?: {
2101
- /** Your id for the user, when it exists (logins always; sign-ups once the account exists). */
2102
- id?: string;
2103
- /** The email address the user gave. */
2104
- email?: string;
2105
- };
2106
- /** The client's IP address (not your server's or proxy's). */
2107
- ip?: string;
2108
- /** The client's user agent. */
2109
- user_agent?: string;
2110
- /**
2111
- * The token your captcha widget (Turnstile or hCaptcha, set in the risk settings) gave the
2112
- * browser. Verified once: don't reuse it.
2113
- */
2114
- captcha?: {
2115
- token: string;
2116
- };
2117
- /**
2118
- * Text the user wrote (a bio, a message, a listing), classified with the event and never
2119
- * stored: its scores go in `signals.content`, and `content.*` reasons fire only at thresholds
2120
- * you set.
2121
- */
2122
- content?: {
2123
- text: string;
2124
- };
2125
- /** Only with `checkout` events: what is being paid for, and with which card. */
2126
- checkout?: {
2127
- /** In the currency's minor unit (cents for USD: 1999 is $19.99). */
2128
- amount: number;
2129
- /** ISO 4217, upper-case (`USD`). */
2130
- currency: string;
2131
- /** What your payment processor tells you about the card. */
2132
- card?: {
2133
- /**
2134
- * Your processor's fingerprint of the card number (Stripe: `card.fingerprint`), kept as a
2135
- * keyed hash only. Never send the card number.
2136
- */
2137
- fingerprint?: string;
2138
- /** Where the card was issued (ISO 3166-1 alpha-2, upper-case). */
2139
- country?: string;
2140
- funding?: RiskCardFunding;
2141
- };
2142
- billing_country?: string;
2143
- shipping_country?: string;
2144
- };
2145
- /** What `collectDevice()` from `coss/device` returned in the user's browser. */
2146
- device?: {
2147
- token: string;
2148
- };
2149
- }
2150
- /** Query of `GET /v1/risk/assessments`. */
2151
- interface ListRiskAssessmentsParams {
2152
- event?: RiskEvent;
2153
- decision?: RiskDecision;
2154
- user_id?: string;
2155
- /** `open`: the review queue. */
2156
- review_status?: "open" | "resolved";
2157
- /** 1-100, default 50. */
2158
- limit?: number;
2159
- /** The `id` of the last assessment of the previous page. */
2160
- after?: string;
2161
- }
2162
- /** Body of `POST /v1/risk/assessments/{id}/feedback`. */
2163
- interface RiskFeedbackParams {
2164
- outcome: RiskOutcome;
2165
- /** For your team; never shared. */
2166
- note?: string;
2167
- }
2168
- /** An entry of the environment's allow or block list. */
2169
- interface RiskListEntry {
2170
- object: "risk_list_entry";
2171
- id: string;
2172
- list: RiskList;
2173
- type: RiskListEntryType;
2174
- /** Normalized: emails as their mailbox, CIDR ranges canonical, ASNs as numbers. */
2175
- value: string;
2176
- note: string | null;
2177
- /** ISO 8601 timestamp: the entry stops matching then. */
2178
- expires_at: string | null;
2179
- /** ISO 8601 timestamp. */
2180
- created_at: string;
2181
- }
2182
- /** Body of `POST /v1/risk/list_entries` (`coss.risk.lists.add` builds it). */
2183
- interface CreateRiskListEntryParams {
2184
- list: RiskList;
2185
- type: RiskListEntryType;
2186
- value: string;
2187
- note?: string;
2188
- /** ISO 8601 timestamp with an offset. */
2189
- expires_at?: string;
2190
- }
2191
- /** What `coss.risk.lists.add` matches on: exactly one of these. */
2192
- type RiskListEntryValue = {
2193
- email: string;
2194
- } | {
2195
- domain: string;
2196
- } | {
2197
- ip: string;
2198
- } | {
2199
- asn: string | number;
2200
- } | {
2201
- country: string;
2202
- } | {
2203
- user: string;
2204
- };
2205
- /** Query of `GET /v1/risk/list_entries`. */
2206
- interface ListRiskListEntriesParams {
2207
- list?: RiskList;
2208
- type?: RiskListEntryType;
2209
- /** 1-100, default 50. */
2210
- limit?: number;
2211
- after?: string;
2212
- }
2213
- /** Response of `DELETE /v1/risk/list_entries/{id}`. */
2214
- interface DeletedRiskListEntry {
2215
- object: "risk_list_entry";
2216
- id: string;
2217
- deleted: true;
2218
- }
2219
- /** Response of `DELETE /v1/risk/users/{user_id}`. */
2220
- interface ForgottenRiskUser {
2221
- object: "risk_user";
2222
- /** Your user id. */
2223
- id: string;
2224
- deleted: true;
2225
- }
2226
- type RiskCaptchaProvider = "turnstile" | "hcaptcha";
2227
- /** The environment's risk settings. */
2228
- interface RiskSettings {
2229
- object: "risk_settings";
2230
- /** Scores at or above it are `review`. */
2231
- review_threshold: number;
2232
- /** Scores at or above it are `block`. */
2233
- block_threshold: number;
2234
- /** Reasons that never fire in this environment. */
2235
- disabled_reasons: RiskReasonCode[];
2236
- /** The captcha provider assessments verify tokens with (never the secret). */
2237
- captcha: {
2238
- provider: RiskCaptchaProvider;
2239
- required: boolean;
2240
- } | null;
2241
- /** Per content category, the score at which `content.<category>` fires; `null`: never. */
2242
- content_thresholds: Record<RiskContentCategory, number | null>;
2243
- /** Reasons whose weight this environment changed; the rest weigh what the catalog says. */
2244
- reason_weights: Partial<Record<RiskReasonCode, number>>;
2245
- /** ISO 8601 timestamp; `null` while on the defaults. */
2246
- updated_at: string | null;
2247
- }
2248
- /** Body of `PATCH /v1/risk/settings`: only the fields given change. */
2249
- interface UpdateRiskSettingsParams {
2250
- review_threshold?: number;
2251
- block_threshold?: number;
2252
- disabled_reasons?: RiskReasonCode[];
2253
- /** `null` turns captcha verification off and deletes the secret. */
2254
- captcha?: {
2255
- provider: RiskCaptchaProvider;
2256
- /** Required when setting a provider for the first time or changing it. */
2257
- secret?: string;
2258
- /** Assessments without a token get `captcha.missing`. */
2259
- required?: boolean;
2260
- } | null;
2261
- /** Changes the categories given: a score in (0, 1] sets the threshold, `null` removes it. */
2262
- content_thresholds?: Partial<Record<RiskContentCategory, number | null>>;
2263
- /**
2264
- * Changes the reasons given: a weight in [0, 0.99] replaces the default (for example
2265
- * calibration's `suggested_weight`), `null` restores it. Not `list.*` or `rule.matched`.
2266
- */
2267
- reason_weights?: Partial<Record<RiskReasonCode, number | null>>;
2268
- }
2269
- /** Feedback counted against one reason or rule (`fraud` includes `abuse`). */
2270
- interface RiskCalibrationCounts {
2271
- fraud: number;
2272
- legitimate: number;
2273
- /** `fraud / (fraud + legitimate)`; `null` without feedback. */
2274
- precision: number | null;
2275
- }
2276
- /** How often each reason and rule was right over the last 90 days, by your feedback. */
2277
- interface RiskCalibration {
2278
- object: "risk_calibration";
2279
- window_days: number;
2280
- /** Assessments in the window. */
2281
- assessments: number;
2282
- /** Of those, with feedback. */
2283
- labeled: number;
2284
- reasons: (RiskCalibrationCounts & {
2285
- code: RiskReasonCode;
2286
- /** Assessments it fired in. */
2287
- fired: number;
2288
- default_weight: number;
2289
- /** Its weight in this environment now. */
2290
- weight: number;
2291
- /** What feedback supports; `null` with fewer than 20 assessments with feedback. */
2292
- suggested_weight: number | null;
2293
- })[];
2294
- rules: (RiskCalibrationCounts & {
2295
- rule: string;
2296
- name: string;
2297
- /** Assessments it decided. */
2298
- matched: number;
2299
- })[];
2300
- }
2301
- /** A field a rule condition can test (see the rules guide). */
2302
- type RiskRuleField = "email.valid" | "email.disposable" | "email.undeliverable" | "email.role_account" | "email.free_provider" | "email.typo" | "email.domain_new" | "email.domain" | "email.domain_age_days" | "ip.tor" | "ip.hosting" | "ip.vpn" | "ip.proxy" | "ip.relay" | "ip.private" | "ip.country" | "ip.asn" | "ip.hosting_provider" | "captcha.passed" | "duplicate.canonical_mailbox" | "duplicate.device" | "history.fraud" | "login.new_country" | "login.new_network" | "content.spam" | "content.phishing" | "content.malware" | "content.fraud" | "checkout.amount" | "checkout.currency" | "checkout.card_country" | "checkout.card_funding" | "checkout.billing_country" | "checkout.shipping_country" | "device.automation" | "device.timezone" | "device.language" | "score" | "velocity.ip_1h" | "velocity.ip_24h" | "velocity.subnet_1h" | "velocity.subnet_24h" | "velocity.email_domain_1h" | "velocity.email_domain_24h" | "velocity.mailbox_1h" | "velocity.mailbox_24h" | "velocity.user_1h" | "velocity.user_24h" | "velocity.card_1h" | "velocity.card_24h" | "velocity.device_1h" | "velocity.device_24h";
2303
- /** A test of one field. A field without a value (no IP, no email…) never matches. */
2304
- interface RiskRuleCondition {
2305
- field: RiskRuleField;
2306
- /** `is` (booleans); `eq`, `neq`, `gt`, `gte`, `lt`, `lte` (numbers); `eq`, `neq`, `in`, `not_in` (strings). */
2307
- operator: "is" | "eq" | "neq" | "gt" | "gte" | "lt" | "lte" | "in" | "not_in";
2308
- value: boolean | number | string | string[];
2309
- }
2310
- /** A rule: the first enabled one whose conditions match decides (after the lists). */
2311
- interface RiskRule {
2312
- object: "risk_rule";
2313
- id: string;
2314
- name: string;
2315
- enabled: boolean;
2316
- /** Rules are tried in ascending order. */
2317
- position: number;
2318
- /** Events it applies to; empty: every event. */
2319
- events: RiskEvent[];
2320
- /** `all`: every condition must hold. `any`: one is enough. */
2321
- match: "all" | "any";
2322
- conditions: RiskRuleCondition[];
2323
- action: RiskDecision;
2324
- /** ISO 8601 timestamp. */
2325
- created_at: string;
2326
- /** ISO 8601 timestamp. */
2327
- updated_at: string;
2328
- }
2329
- /** Body of `POST /v1/risk/rules`. */
2330
- interface CreateRiskRuleParams {
2331
- name: string;
2332
- enabled?: boolean;
2333
- /** Default 0. */
2334
- position?: number;
2335
- events?: RiskEvent[];
2336
- /** Default `all`. */
2337
- match?: "all" | "any";
2338
- conditions: RiskRuleCondition[];
2339
- action: RiskDecision;
2340
- }
2341
- /** Body of `PATCH /v1/risk/rules/{id}`: only the fields given change. */
2342
- type UpdateRiskRuleParams = Partial<CreateRiskRuleParams>;
2343
- /** Response of `DELETE /v1/risk/rules/{id}`. */
2344
- interface DeletedRiskRule {
2345
- object: "risk_rule";
2346
- id: string;
2347
- deleted: true;
2348
- }
2349
- /** Result of `coss.risk.checkEmail()`: what COSS knows about an address. Nothing is stored. */
2350
- interface RiskEmailCheck {
2351
- object: "risk_email_check";
2352
- email: string;
2353
- valid: boolean;
2354
- domain: string | null;
2355
- /** The mailbox with the provider's aliasing folded (dots and `+tags` at Gmail…). */
2356
- canonical: string | null;
2357
- disposable: boolean;
2358
- /** From DNS (MX, A, AAAA). `unknown` when the lookup failed or timed out. */
2359
- deliverability: "deliverable" | "undeliverable" | "unknown";
2360
- role_account: boolean;
2361
- free_provider: boolean;
2362
- /** The likely intended domain when this one looks like a typo of a popular one. */
2363
- suggestion: string | null;
2364
- /** Days since the domain was registered (RDAP); `null` when unknown or not looked up. */
2365
- domain_age_days: number | null;
2366
- /** Lookups that failed or timed out. */
2367
- degraded: ("email_dns" | "domain_age")[];
2368
- }
2369
- /** Result of `coss.risk.checkIp()`. Nothing is stored. */
2370
- interface RiskIpCheck extends RiskIpSignals {
2371
- object: "risk_ip_check";
2372
- ip: string;
2373
- /**
2374
- * `ip_data` when some IP data is unavailable at the moment; `ip_privacy` when the privacy data
2375
- * provider failed or timed out.
2376
- */
2377
- degraded: ("ip_data" | "ip_privacy")[];
2378
- }
2379
- /** Result of `coss.risk.classify()`: scores only, neither stored nor logged. */
2380
- interface RiskContentClassification {
2381
- object: "risk_content_classification";
2382
- scores: RiskContentScores;
2383
- /** The text was longer than the model reads (8,000 characters): only its beginning counted. */
2384
- truncated: boolean;
2385
- }
2386
- /** What `on_failure` answers while COSS can't count. */
2387
- type RiskLimitFailureMode = "allow" | "deny";
2388
- /** One of your rate limit buckets: each key gets `burst` tokens, refilling `limit` per period. */
2389
- interface RiskLimitBucket {
2390
- object: "risk_limit_bucket";
2391
- id: string;
2392
- /** What `coss.risk.limit({ bucket })` names it by. */
2393
- name: string;
2394
- /** Tokens added per `period_seconds`. */
2395
- limit: number;
2396
- period_seconds: number;
2397
- /** How many requests a key can make at once. */
2398
- burst: number;
2399
- on_failure: RiskLimitFailureMode;
2400
- /** ISO 8601 timestamp. */
2401
- created_at: string;
2402
- /** ISO 8601 timestamp. */
2403
- updated_at: string;
2404
- }
2405
- /** Body of `POST /v1/risk/limit_buckets`. */
2406
- interface CreateRiskLimitBucketParams {
2407
- /** 1-64 lower-case letters, digits, `.`, `_` or `-`; unique in the environment. */
2408
- name: string;
2409
- limit: number;
2410
- /** 1 second to 1 day. */
2411
- period_seconds: number;
2412
- /** Defaults to `limit`. */
2413
- burst?: number;
2414
- /** Defaults to `allow`. */
2415
- on_failure?: RiskLimitFailureMode;
2416
- }
2417
- /** Body of `PATCH /v1/risk/limit_buckets/{id}` (the name can't change). */
2418
- type UpdateRiskLimitBucketParams = Partial<Omit<CreateRiskLimitBucketParams, "name">>;
2419
- interface DeletedRiskLimitBucket {
2420
- object: "risk_limit_bucket";
2421
- id: string;
2422
- deleted: true;
2423
- }
2424
- /** Body of `POST /v1/risk/limits`. */
2425
- interface CheckRiskLimitParams {
2426
- /** The bucket's name. */
2427
- bucket: string;
2428
- /** Who or what is limited (a user id, an email or IP address…); COSS keeps only a hash. */
2429
- key: string;
2430
- /** Tokens this request takes. Default 1. */
2431
- cost?: number;
2432
- }
2433
- /** Result of `coss.risk.limit()`. */
2434
- interface RiskLimit {
2435
- object: "risk_limit";
2436
- bucket: string;
2437
- /** Whether to let the request through. Denied requests take no tokens. */
2438
- allowed: boolean;
2439
- /** The bucket's size (`burst`). */
2440
- limit: number;
2441
- /** Tokens left for this key. */
2442
- remaining: number;
2443
- /** Milliseconds until the key's bucket is full again. */
2444
- reset_ms: number;
2445
- /** When denied: milliseconds until the same request would fit; `null` if it never would. */
2446
- retry_after_ms: number | null;
2447
- /** COSS couldn't count: `allowed` is the bucket's `on_failure`. */
2448
- degraded: boolean;
2449
- }
2450
- //#endregion
2451
- //#region src/resources/risk.d.ts
2452
- type ReadOptions$2 = Pick<RequestOptions, "signal">;
2453
- /** `coss.risk.assessments`: reading past assessments (`assess` lives on `coss.risk`). */
2454
- declare class RiskAssessmentsResource {
2455
- #private;
2456
- /** @internal Use `new Coss().risk.assessments`. */
2457
- constructor(http: HttpClient);
2458
- /** Retrieves one assessment. */
2459
- get(id: string, options?: ReadOptions$2): Promise<CossResult<RiskAssessment>>;
2460
- /**
2461
- * Lists assessments, newest first (`review_status: "open"` is the review queue). Pass the last
2462
- * `id` as `after` while `has_more` is true.
2463
- */
2464
- list(params?: ListRiskAssessmentsParams, options?: ReadOptions$2): Promise<CossResult<List<RiskAssessment>>>;
2465
- }
2466
- /** `coss.risk.lists`: the environment's allow and block lists. */
2467
- declare class RiskListsResource {
2468
- #private;
2469
- /** @internal Use `new Coss().risk.lists`. */
2470
- constructor(http: HttpClient);
2471
- /**
2472
- * Adds an entry: `coss.risk.lists.add("block", { domain: "evil.example" })`. An allow-list match
2473
- * makes decisions `allow`, a block-list match `block`. Returns the existing entry if there is one.
2474
- */
2475
- add(list: RiskList, entry: RiskListEntryValue & {
2476
- note?: string;
2477
- expires_at?: string | Date;
2478
- }, options?: RequestOptions): Promise<CossResult<RiskListEntry>>;
2479
- /** 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>>>;
2481
- /** Retrieves one entry. */
2482
- get(id: string, options?: ReadOptions$2): Promise<CossResult<RiskListEntry>>;
2483
- /** Removes an entry. */
2484
- remove(id: string, options?: ReadOptions$2): Promise<CossResult<DeletedRiskListEntry>>;
2485
- }
2486
- /** `coss.risk.settings`: the environment's thresholds, disabled reasons and captcha provider. */
2487
- declare class RiskSettingsResource {
2488
- #private;
2489
- /** @internal Use `new Coss().risk.settings`. */
2490
- constructor(http: HttpClient);
2491
- get(options?: ReadOptions$2): Promise<CossResult<RiskSettings>>;
2492
- /** Changes the fields given. The captcha secret is write-only. */
2493
- update(params: UpdateRiskSettingsParams, options?: ReadOptions$2): Promise<CossResult<RiskSettings>>;
2494
- }
2495
- /**
2496
- * `coss.risk.rules`: the environment's rules. After the lists, the first enabled rule whose
2497
- * conditions match an event decides it.
2498
- */
2499
- declare class RiskRulesResource {
2500
- #private;
2501
- /** @internal Use `new Coss().risk.rules`. */
2502
- constructor(http: HttpClient);
2503
- /** Creates a rule. Not retried automatically: a retry could create it twice. */
2504
- create(params: CreateRiskRuleParams, options?: ReadOptions$2): Promise<CossResult<RiskRule>>;
2505
- /** Every rule, in evaluation order. */
2506
- list(options?: ReadOptions$2): Promise<CossResult<List<RiskRule>>>;
2507
- get(id: string, options?: ReadOptions$2): Promise<CossResult<RiskRule>>;
2508
- /** 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>>;
2511
- }
2512
- /**
2513
- * `coss.risk.limitBuckets`: your rate limit buckets, which `coss.risk.limit()` charges per key.
2514
- */
2515
- declare class RiskLimitBucketsResource {
2516
- #private;
2517
- /** @internal Use `new Coss().risk.limitBuckets`. */
2518
- constructor(http: HttpClient);
2519
- /** Creates a bucket. Not retried automatically: a retry would find its name taken. */
2520
- create(params: CreateRiskLimitBucketParams, options?: ReadOptions$2): Promise<CossResult<RiskLimitBucket>>;
2521
- /** Every bucket, by name. */
2522
- list(options?: ReadOptions$2): Promise<CossResult<List<RiskLimitBucket>>>;
2523
- get(id: string, options?: ReadOptions$2): Promise<CossResult<RiskLimitBucket>>;
2524
- /** 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>>;
2527
- }
2528
- /** `coss.risk.users`: what COSS remembers about your users. */
2529
- declare class RiskUsersResource {
2530
- #private;
2531
- /** @internal Use `new Coss().risk.users`. */
2532
- constructor(http: HttpClient);
2533
- /**
2534
- * Call when you delete a user: COSS deletes what identifies them (their mailbox, fraud reports,
2535
- * and the user id, email, IP and user agent on their assessments). Safe to repeat.
2536
- */
2537
- forget(userId: string, options?: ReadOptions$2): Promise<CossResult<ForgottenRiskUser>>;
2538
- }
2539
- /**
2540
- * `coss.risk`: assess sign-ups, logins and other events. Call it from your server and treat an
2541
- * error as `allow` (fail open), so an outage never locks your users out.
2542
- *
2543
- * ```ts
2544
- * const { data } = await coss.risk.assess({ event: "signup", user: { email }, ip, user_agent });
2545
- * if (data?.decision === "block") return refuse();
2546
- * ```
2547
- */
2548
- declare class RiskResource {
2549
- #private;
2550
- /** Past assessments (`get`, `list`). */
2551
- readonly assessments: RiskAssessmentsResource;
2552
- /** Allow and block lists (`add`, `list`, `get`, `remove`). */
2553
- readonly lists: RiskListsResource;
2554
- /** Forgetting deleted users. */
2555
- readonly users: RiskUsersResource;
2556
- /** Thresholds, disabled reasons and the captcha provider (`get`, `update`). */
2557
- readonly settings: RiskSettingsResource;
2558
- /** Rules (`create`, `list`, `get`, `update`, `delete`). */
2559
- readonly rules: RiskRulesResource;
2560
- /** Your rate limit buckets (`create`, `list`, `get`, `update`, `delete`). */
2561
- readonly limitBuckets: RiskLimitBucketsResource;
2562
- /** @internal Use `new Coss().risk`. */
2563
- constructor(http: HttpClient);
2564
- /**
2565
- * Assesses an event and returns the decision with its score and reasons. Retries reuse one
2566
- * `Idempotency-Key`, so an event is never counted twice.
2567
- */
2568
- assess(params: AssessRiskParams, options?: RequestOptions): Promise<CossResult<RiskAssessment>>;
2569
- /**
2570
- * Reports what an assessed user turned out to be: `fraud` and `abuse` teach later assessments to
2571
- * flag the same mailbox, user, card, device, IP and subnet; `legitimate` takes that back.
2572
- * Resolves a review, and counts in `calibration()`.
2573
- */
2574
- feedback(id: string, params: RiskFeedbackParams, options?: RequestOptions): Promise<CossResult<RiskAssessment>>;
2575
- /**
2576
- * How often each reason and rule was right over the last 90 days, by your feedback, and the
2577
- * reason weights that supports. Apply them with `settings.update({ reason_weights })`.
2578
- */
2579
- calibration(options?: ReadOptions$2): Promise<CossResult<RiskCalibration>>;
2580
- /**
2581
- * Checks an email address on its own: syntax, disposable domains, deliverability, role
2582
- * accounts, free providers, the canonical mailbox, typos and domain age. Nothing is stored.
2583
- */
2584
- checkEmail(email: string, options?: ReadOptions$2): Promise<CossResult<RiskEmailCheck>>;
2585
- /**
2586
- * 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.
2588
- */
2589
- checkIp(ip: string, options?: ReadOptions$2): Promise<CossResult<RiskIpCheck>>;
2590
- /**
2591
- * Scores text for spam, phishing, malware and fraud. Scores only, never a verdict: you choose
2592
- * the thresholds. The text is neither stored nor logged.
2593
- */
2594
- classify(params: {
2595
- text: string;
2596
- }, options?: ReadOptions$2): Promise<CossResult<RiskContentClassification>>;
2597
- /**
2598
- * Takes `cost` tokens (default 1) from `key`'s share of one of your buckets
2599
- * (`coss.risk.limitBuckets`). Retries reuse one `Idempotency-Key`, so they are charged once.
2600
- *
2601
- * ```ts
2602
- * const { data } = await coss.risk.limit({ bucket: "password_reset", key: email });
2603
- * if (data && !data.allowed) return tooManyRequests(data.retry_after_ms);
2604
- * ```
2605
- */
2606
- limit(params: CheckRiskLimitParams, options?: RequestOptions): Promise<CossResult<RiskLimit>>;
2607
- }
2608
- //#endregion
2609
- //#region src/types/webhook.d.ts
2610
- /** What a webhook says about the email; never its content, cc or bcc. */
2611
- interface EmailWebhookEventData extends EmailEventData {
2612
- email_id: string;
2613
- from: string;
2614
- to: string[];
2615
- subject: string;
2616
- tags: EmailTag[];
2617
- category: string | null;
2618
- /** `true` for emails sent with a sandbox (`coss_test_…`) key. */
2619
- sandbox: boolean;
2620
- /** The recipient this event is about; `null` for the whole email. */
2621
- recipient: string | null;
2622
- /** ISO 8601 timestamp of the event itself (deliveries can arrive later, and out of order). */
2623
- occurred_at: string;
2624
- }
2625
- /** An email event. `id` equals the `webhook-id` header and `EmailEvent.id`. */
2626
- interface EmailWebhookEvent {
2627
- id: string;
2628
- object: "event";
2629
- type: EmailEventType;
2630
- /** The API version this event is rendered in: the receiving endpoint's `api_version`. */
2631
- api_version: string;
2632
- /** ISO 8601 timestamp. */
2633
- created_at: string;
2634
- data: EmailWebhookEventData;
2635
- }
2636
- /** Events about received (inbound) emails. */
2637
- type ReceivedEmailEventType = "email.received";
2638
- /** What a webhook says about a received email; never its content, headers or cc. */
2639
- interface ReceivedEmailWebhookEventData {
2640
- /** Retrieve the email (bodies, headers, attachments) with `coss.email.received.get`. */
2641
- received_email_id: string;
2642
- /** The `From` header. */
2643
- from: string | null;
2644
- /** The `To` header's addresses. */
2645
- to: string[];
2646
- /** The envelope recipients this environment received it for. */
2647
- recipients: string[];
2648
- subject: string | null;
2649
- message_id: string | null;
2650
- attachment_count: number;
2651
- size: number;
2652
- /** Whether the spam verdict is `fail`. */
2653
- spam: boolean;
2654
- verdicts: ReceivedEmailVerdicts;
2655
- sandbox: boolean;
2656
- /** ISO 8601 timestamp. */
2657
- received_at: string;
2658
- }
2659
- /** An email arrived. `id` equals the `webhook-id` header. */
2660
- interface ReceivedEmailWebhookEvent {
2661
- id: string;
2662
- object: "event";
2663
- type: ReceivedEmailEventType;
2664
- /** The API version this event is rendered in: the receiving endpoint's `api_version`. */
2665
- api_version: string;
2666
- /** ISO 8601 timestamp. */
2667
- created_at: string;
2668
- data: ReceivedEmailWebhookEventData;
2669
- }
2670
- /** Changes of the organization's reputation standing (sent to live environments only). */
2671
- type AccountEventType = "account.reputation_warning" | "account.reputation_recovered" | "account.suspended" | "account.reinstated";
2672
- interface AccountWebhookEventData {
2673
- organization_id: string;
2674
- status: ReputationStatus;
2675
- previous_status: ReputationStatus;
2676
- /** The trigger behind a `warning` or `suspended` status, e.g. `complaint_rate`. */
2677
- reason: string | null;
2678
- /** ISO 8601 timestamp. */
2679
- occurred_at: string;
2680
- /** The measurements behind the change (see `coss.reputation.get()`). */
2681
- checks: ReputationCheck[];
2682
- }
2683
- /** A reputation change. `id` equals the `webhook-id` header. */
2684
- interface AccountWebhookEvent {
2685
- id: string;
2686
- object: "event";
2687
- type: AccountEventType;
2688
- /** The API version this event is rendered in: the receiving endpoint's `api_version`. */
2689
- api_version: string;
2690
- /** ISO 8601 timestamp. */
2691
- created_at: string;
2692
- data: AccountWebhookEventData;
2693
- }
2694
- /** Billing events (organization-wide; sent to live environments only). */
2695
- type BillingEventType = "billing.invoice_finalized" | "billing.invoice_paid" | "billing.invoice_payment_failed" | "billing.invoice_voided" | "billing.plan_changed" | "billing.usage_threshold_reached" | "billing.hold_placed" | "billing.hold_lifted" | "billing.credit_granted";
2696
- interface BillingEventFields {
2697
- /** Equals the `webhook-id` header. */
2698
- id: string;
2699
- object: "event";
2700
- /** The API version this event is rendered in: the receiving endpoint's `api_version`. */
2701
- api_version: string;
2702
- /** ISO 8601 timestamp. */
2703
- created_at: string;
2704
- }
2705
- /** Every billing event's `data` has these. */
2706
- interface BillingEventData {
2707
- organization_id: string;
2708
- /** When it happened (ISO 8601): sort events by it. */
2709
- occurred_at: string;
2710
- }
2711
- /** A billing event; narrow on `type` for its `data`. */
2712
- type BillingWebhookEvent = (BillingEventFields & {
2713
- type: "billing.invoice_finalized" | "billing.invoice_paid" | "billing.invoice_voided";
2714
- data: BillingEventData & {
2715
- invoice: InvoiceSummary;
2716
- };
2717
- }) | (BillingEventFields & {
2718
- type: "billing.invoice_payment_failed";
2719
- data: BillingEventData & {
2720
- invoice: InvoiceSummary;
2721
- failure: {
2722
- message: string;
2723
- };
2724
- };
2725
- }) | (BillingEventFields & {
2726
- type: "billing.plan_changed";
2727
- data: BillingEventData & {
2728
- /**
2729
- * `upgrade` (in effect now), `downgrade`/`cancellation` (scheduled), `reverted` (a
2730
- * scheduled change was undone), `contract` (a contract changed).
2731
- */
2732
- change: "upgrade" | "downgrade" | "cancellation" | "reverted" | "contract";
2733
- /** The plan from `effective_at`. */
2734
- plan: PlanKey;
2735
- previous_plan: PlanKey;
2736
- effective_at: string;
2737
- };
2738
- }) | (BillingEventFields & {
2739
- type: "billing.usage_threshold_reached";
2740
- data: BillingEventData & {
2741
- /** The threshold crossed, e.g. 80. */
2742
- percent: number;
2743
- /** `credit`: the month's usage credit; `allowance`: a capped plan's included units. */
2744
- of: "credit" | "allowance";
2745
- meter: Meter | null;
2746
- period: {
2747
- start: string;
2748
- end: string;
2749
- };
2750
- };
2751
- }) | (BillingEventFields & {
2752
- type: "billing.hold_placed" | "billing.hold_lifted";
2753
- data: BillingEventData & {
2754
- reason: BillingHoldReason;
2755
- };
2756
- }) | (BillingEventFields & {
2757
- type: "billing.credit_granted";
2758
- data: BillingEventData & {
2759
- credit: Credit;
2760
- };
2761
- });
2762
- /** Risk events: `review` decisions, and their resolution, for a queue you work through. */
2763
- type RiskEventType = "risk.assessment.review" | "risk.assessment.reviewed";
2764
- interface RiskWebhookEventData {
2765
- assessment_id: string;
2766
- event: RiskEvent;
2767
- event_name: string | null;
2768
- decision: RiskDecision;
2769
- score: number;
2770
- reasons: RiskReason[];
2771
- /** Your user id, if the assessment had one. Never the email or IP address. */
2772
- user_id: string | null;
2773
- /** `risk.assessment.reviewed`: the outcome that resolved the review. */
2774
- outcome: RiskOutcome | null;
2775
- /** ISO 8601 timestamp. */
2776
- occurred_at: string;
2777
- }
2778
- /** A risk review opened or resolved. `id` equals the `webhook-id` header. */
2779
- interface RiskWebhookEvent {
2780
- id: string;
2781
- object: "event";
2782
- type: RiskEventType;
2783
- /** The API version this event is rendered in: the receiving endpoint's `api_version`. */
2784
- api_version: string;
2785
- /** ISO 8601 timestamp. */
2786
- created_at: string;
2787
- data: RiskWebhookEventData;
2788
- }
2789
- /** Events about Hooks: an endpoint of one of your applications was disabled for failing. */
2790
- type HookOperationalEventType = "hook_endpoint.disabled";
2791
- interface HookEndpointWebhookEventData {
2792
- application_id: string;
2793
- /** Your uid for the application, when it has one. */
2794
- application_uid: string | null;
2795
- endpoint_id: string;
2796
- url: string;
2797
- /** ISO 8601 timestamp: when its deliveries started failing every attempt. */
2798
- failing_since: string;
2799
- /** ISO 8601 timestamp. */
2800
- occurred_at: string;
2801
- }
2802
- /** A Hooks endpoint of one of your applications was disabled. `id` equals the `webhook-id` header. */
2803
- interface HookEndpointWebhookEvent {
2804
- id: string;
2805
- object: "event";
2806
- type: HookOperationalEventType;
2807
- /** The API version this event is rendered in: the receiving endpoint's `api_version`. */
2808
- api_version: string;
2809
- /** ISO 8601 timestamp. */
2810
- created_at: string;
2811
- data: HookEndpointWebhookEventData;
2812
- }
2813
- /** The JSON body of a webhook request; narrow on `type`. */
2814
- type WebhookEvent = EmailWebhookEvent | ReceivedEmailWebhookEvent | AccountWebhookEvent | BillingWebhookEvent | RiskWebhookEvent | HookEndpointWebhookEvent;
2815
- //#endregion
2816
- //#region src/types/webhook-endpoint.d.ts
2817
- /** Every event type an endpoint can subscribe to. */
2818
- type WebhookEventType = EmailEventType | ReceivedEmailEventType | AccountEventType | BillingEventType | RiskEventType | HookOperationalEventType;
2819
- /** Why an endpoint is disabled. */
2820
- type WebhookEndpointDisabledReason = "manual" | "failing";
2821
- /** A URL of the API key's environment that receives signed event notifications. */
2822
- interface WebhookEndpoint {
2823
- object: "webhook_endpoint";
2824
- id: string;
2825
- url: string;
2826
- description: string | null;
2827
- /**
2828
- * Event types delivered to this endpoint. An empty array means every event type, including
2829
- * ones added later.
2830
- */
2831
- event_types: string[];
2832
- /** The API version events are rendered in for this endpoint (each event's `api_version`). */
2833
- api_version: string;
2834
- /** A disabled endpoint receives nothing until it is enabled again. */
2835
- enabled: boolean;
2836
- /**
2837
- * `manual`: someone disabled it. `failing`: its deliveries failed every attempt for five days,
2838
- * so COSS disabled it. `null` while enabled.
2839
- */
2840
- disabled_reason: WebhookEndpointDisabledReason | null;
2841
- /** When it was disabled (ISO 8601); `null` while enabled. */
2842
- disabled_at: string | null;
2843
- /**
2844
- * When the endpoint's current run of failed deliveries began (ISO 8601); cleared by the next
2845
- * successful delivery. An endpoint failing for five days is disabled. `null` while healthy.
2846
- */
2847
- failing_since: string | null;
2848
- /**
2849
- * After a secret roll, deliveries are also signed with the previous secret until this time
2850
- * (ISO 8601). `null` when only the current secret signs.
2851
- */
2852
- previous_secret_expires_at: string | null;
2853
- /** ISO 8601 timestamp. */
2854
- created_at: string;
2855
- updated_at: string;
2856
- }
2857
- /** A freshly created endpoint, or one whose secret was just rolled: the only responses with the signing secret. */
2858
- interface WebhookEndpointWithSecret extends WebhookEndpoint {
2859
- /**
2860
- * The endpoint's `whsec_…` signing secret, for `verifyWebhook`. Returned only on creation and
2861
- * on a roll — store it now; it cannot be read back through the API.
2862
- */
2863
- secret: string;
2864
- }
2865
- /** Body of `POST /v1/webhook_endpoints`. */
2866
- interface CreateWebhookEndpointParams {
2867
- /** An `https://` URL COSS posts events to. */
2868
- url: string;
2869
- /** A note for your own reference. */
2870
- description?: string | null;
2871
- /** Defaults to every event type, including ones added later. */
2872
- event_types?: WebhookEventType[];
2873
- /**
2874
- * The API version events are rendered in. Defaults to the client's `apiVersion`, so events match
2875
- * this SDK's `WebhookEvent` types.
2876
- */
2877
- api_version?: ApiVersion;
2878
- }
2879
- /** Body of `PATCH /v1/webhook_endpoints/{id}`. Omitted fields keep their current value. */
2880
- interface UpdateWebhookEndpointParams {
2881
- url?: string;
2882
- /** `null` clears the description. */
2883
- description?: string | null;
2884
- event_types?: WebhookEventType[];
2885
- api_version?: ApiVersion;
2886
- enabled?: boolean;
2887
- }
2888
- /** Body of `POST /v1/webhook_endpoints/{id}/roll_secret`. */
2889
- interface RollWebhookEndpointSecretParams {
2890
- /**
2891
- * Seconds the current secret keeps signing deliveries next to the new one, so receivers can
2892
- * switch without rejecting anything. Default 86400 (a day), at most 604800 (a week). `0` stops
2893
- * it immediately, e.g. after a leak.
2894
- */
2895
- previous_secret_expires_in?: number;
2896
- }
2897
- /** Body of `POST /v1/webhook_endpoints/{id}/recover`. */
2898
- interface RecoverWebhookEndpointParams {
2899
- /**
2900
- * Requeue the deliveries that failed and were created at or after this time (ISO 8601 string or
2901
- * `Date`). Deliveries are kept for 30 days.
2902
- */
2903
- since: string | Date;
2904
- }
2905
- /** Returned by `webhookEndpoints.recover`. */
2906
- interface WebhookEndpointRecovery {
2907
- object: "webhook_endpoint_recovery";
2908
- endpoint_id: string;
2909
- /** How many failed deliveries were queued for one more attempt (spread over the next minute). */
2910
- requeued: number;
2911
- /** At most 1,000 are requeued per call; `true` means call again with the same `since`. */
2912
- has_more: boolean;
2913
- }
2914
- /** Returned by `webhookEndpoints.delete`. */
2915
- interface DeletedWebhookEndpoint {
2916
- object: "webhook_endpoint";
2917
- id: string;
2918
- deleted: true;
2919
- }
2920
- /**
2921
- * `pending`: waiting for its next attempt. `succeeded`: the endpoint answered with a 2xx status.
2922
- * `failed`: every attempt failed, or the endpoint was disabled.
2923
- */
2924
- type WebhookDeliveryStatus = "pending" | "succeeded" | "failed";
2925
- /** One HTTP request of a delivery. */
2926
- interface WebhookAttempt {
2927
- object: "webhook_attempt";
2928
- id: string;
2929
- /** ISO 8601 timestamp. */
2930
- attempted_at: string;
2931
- /** The endpoint's HTTP status; `null` when no response arrived. */
2932
- status_code: number | null;
2933
- duration_ms: number;
2934
- /** Why the attempt failed (e.g. `HTTP 500`, a timeout); `null` on success. */
2935
- error: string | null;
2936
- /** At most 1 KB of the response body, as text. */
2937
- response_excerpt: string | null;
2938
- }
2939
- /** One event sent to one endpoint, retried with backoff until it succeeds or gives up. */
2940
- interface WebhookDelivery {
2941
- object: "webhook_delivery";
2942
- id: string;
2943
- endpoint_id: string;
2944
- /** The event's id: the `id` of the payload and the `webhook-id` header. */
2945
- event_id: string;
2946
- event_type: string;
2947
- status: WebhookDeliveryStatus;
2948
- attempt_count: number;
2949
- /** When the next attempt is due; `null` once the delivery is finished. */
2950
- next_attempt_at: string | null;
2951
- last_status_code: number | null;
2952
- last_error: string | null;
2953
- /** The event body, exactly as posted to the endpoint (a `WebhookEvent`). */
2954
- payload: Record<string, unknown>;
2955
- /** Every HTTP attempt of this delivery, oldest first. */
2956
- attempts: WebhookAttempt[];
2957
- created_at: string;
2958
- updated_at: string;
2959
- }
2960
- /** Query of `GET /v1/webhook_endpoints/{id}/deliveries`. */
2961
- interface ListWebhookDeliveriesParams {
2962
- /** Only deliveries with this status. */
2963
- status?: WebhookDeliveryStatus;
2964
- /** Only the delivery of this event. */
2965
- event_id?: string;
2966
- /** 1-100, default 50. */
2967
- limit?: number;
2968
- /** Cursor: the `id` of the last delivery of the previous page. */
2969
- after?: string;
2970
- }
2971
- //#endregion
2972
- //#region src/resources/webhook-deliveries.d.ts
2973
- type ReadOptions$1 = Pick<RequestOptions, "signal">;
2974
- /**
2975
- * `coss.webhookEndpoints.deliveries`: an endpoint's delivery log. Each delivery carries every
2976
- * HTTP attempt and the payload as sent.
2977
- */
2978
- declare class WebhookDeliveriesResource {
2979
- #private;
2980
- /** @internal Use `new Coss().webhookEndpoints.deliveries`. */
2981
- constructor(http: HttpClient);
2982
- /** 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>>>;
2984
- /** Retrieves one delivery of the endpoint. */
2985
- get(endpointId: string, id: string, options?: ReadOptions$1): Promise<CossResult<WebhookDelivery>>;
2986
- /**
2987
- * Queues a finished delivery for one more attempt, made within seconds. A delivery that is
2988
- * still `pending` is returned unchanged (it is already scheduled for `next_attempt_at`).
2989
- * Never automatically retried: the API does not deduplicate replay requests, even with an
2990
- * idempotency key.
2991
- */
2992
- retry(endpointId: string, id: string, options?: RequestOptions): Promise<CossResult<WebhookDelivery>>;
2993
- }
2994
- //#endregion
2995
- //#region src/resources/webhook-endpoints.d.ts
2996
- type ReadOptions = Pick<RequestOptions, "signal">;
2997
- /**
2998
- * `coss.webhookEndpoints`: the URLs that receive signed event notifications. Endpoints belong to
2999
- * the API key's own environment, so a `coss_test_…` key only ever manages sandbox endpoints.
3000
- */
3001
- declare class WebhookEndpointsResource {
3002
- #private;
3003
- /** Each endpoint's delivery log: list, retrieve and retry deliveries. */
3004
- readonly deliveries: WebhookDeliveriesResource;
3005
- /** @internal Use `new Coss().webhookEndpoints`. */
3006
- constructor(http: HttpClient);
3007
- /**
3008
- * Creates an endpoint. The result carries its `secret` (returned again only by `rollSecret`) —
3009
- * store it and pass it to `verifyWebhook` for every delivery. Creation is never automatically retried:
3010
- * the API does not deduplicate it, even with an idempotency key. After a lost response,
3011
- * list endpoints and remove the endpoint with the unknown secret before creating a replacement.
3012
- */
3013
- create(params: CreateWebhookEndpointParams, options?: RequestOptions): Promise<CossResult<WebhookEndpointWithSecret>>;
3014
- /** Lists the environment's endpoints, oldest first. Secrets are never included. */
3015
- list(options?: ReadOptions): Promise<CossResult<List<WebhookEndpoint>>>;
3016
- /** Retrieves an endpoint of the API key's environment. */
3017
- get(id: string, options?: ReadOptions): Promise<CossResult<WebhookEndpoint>>;
3018
- /**
3019
- * Changes the URL, description, subscribed event types or `enabled` flag. The signing secret
3020
- * stays the same (see `rollSecret`), so receivers keep verifying deliveries.
3021
- */
3022
- update(id: string, params: UpdateWebhookEndpointParams, options?: ReadOptions): Promise<CossResult<WebhookEndpoint>>;
3023
- /**
3024
- * Replaces the endpoint's signing secret; the result carries the new `secret`. Until
3025
- * `previous_secret_expires_at` (a day by default), deliveries are signed with both secrets, so
3026
- * `verifyWebhook` accepts them with either: deploy the new one, then let the old one expire.
3027
- * Never automatically retried (a second roll would stop the original secret at once): after a
3028
- * lost response, roll again and deploy that secret.
3029
- */
3030
- rollSecret(id: string, params?: RollWebhookEndpointSecretParams, options?: RequestOptions): Promise<CossResult<WebhookEndpointWithSecret>>;
3031
- /**
3032
- * Queues the endpoint's deliveries that failed since `since` for one more attempt each (at most
3033
- * 1,000 per call; while `has_more` is true, call again with the same `since`), e.g. after fixing a
3034
- * receiver that was down. The endpoint must be enabled.
3035
- */
3036
- recover(id: string, params: RecoverWebhookEndpointParams, options?: RequestOptions): Promise<CossResult<WebhookEndpointRecovery>>;
3037
- /** Deletes the endpoint and its delivery log. To pause it instead, update `enabled` to false. */
3038
- delete(id: string, options?: ReadOptions): Promise<CossResult<DeletedWebhookEndpoint>>;
3039
- }
3040
- //#endregion
3041
- //#region src/client.d.ts
3042
- interface CossOptions {
3043
- /** Secret API key (`coss_live_…` or `coss_test_…`). Defaults to the `COSS_API_KEY` env variable. */
3044
- apiKey?: string;
3045
- /** Defaults to the `COSS_BASE_URL` env variable, then `https://api.coss.com`. */
3046
- baseUrl?: string;
3047
- /** Custom `fetch` implementation. Defaults to the global `fetch`. */
3048
- fetch?: FetchLike;
3049
- /** Per-attempt timeout in milliseconds. Default `30000`. */
3050
- timeout?: number;
3051
- /** Retries for connection errors, timeouts, 409, 429 and 5xx. Default `2`; excludes webhook creation. */
3052
- maxRetries?: number;
3053
- /**
3054
- * The API version (`Coss-Version`) to request. Defaults to `API_VERSION`, the version this SDK's
3055
- * types describe; requests never fall back to your organization's pinned version.
3056
- */
3057
- apiVersion?: ApiVersion;
3058
- /**
3059
- * Allow use where a `document` global exists. Off by default because shipping a secret API key
3060
- * to a browser exposes it to anyone who opens the page.
3061
- */
3062
- dangerouslyAllowBrowser?: boolean;
3063
- }
3064
- /**
3065
- * The COSS client. One API key covers every product.
3066
- *
3067
- * ```ts
3068
- * const coss = new Coss({ apiKey: "coss_test_…" });
3069
- * const { data, error } = await coss.email.send({ from, to, subject, html });
3070
- * ```
3071
- */
3072
- export declare class Coss {
3073
- readonly email: EmailResource;
3074
- /** Sending domains of the organization (`coss.domains.create`, `.verify`, …). */
3075
- readonly domains: DomainsResource;
3076
- /** Webhook endpoints of the API key's environment. */
3077
- readonly webhookEndpoints: WebhookEndpointsResource;
3078
- /** The organization's sending reputation (`coss.reputation.get()`). */
3079
- readonly reputation: ReputationResource;
3080
- /** The environment's log: API requests, email events, webhook attempts (`coss.logs.list()`). */
3081
- readonly logs: LogsResource;
3082
- /** HTTPS endpoints the environment's log is streamed to (`coss.logDrains.create()`). */
3083
- readonly logDrains: LogDrainsResource;
3084
- /** The organization's audit log: changes by members, API keys and COSS support (`coss.auditEvents.list()`). */
3085
- readonly auditEvents: AuditEventsResource;
3086
- /** Hooks, webhooks as a service: `coss.hooks.messages.send()` delivers to your users' endpoints. */
3087
- readonly hooks: HooksResource;
3088
- /** Risk assessments of sign-ups, logins and other events (`coss.risk.assess()`). */
3089
- readonly risk: RiskResource;
3090
- /** The organization's plan, usage, invoices and credits (`coss.billing.get()`). */
3091
- readonly billing: BillingResource;
3092
- /**
3093
- * Throws only for programmer errors: no API key, or running in a browser without
3094
- * `dangerouslyAllowBrowser`. Request failures are returned as `{ data: null, error }`.
3095
- */
3096
- constructor(options?: CossOptions);
3097
- }
3098
- //#endregion
1
+ import { $ as RiskUsersResource, $i as ListSuppressionsParams, $n as EnvironmentResource, $r as MailFromStatus, $t as LogsResource, A as BillingEventType, Aa as CossError, Ai as EmailFailure, An as HookApplication, Ar as DmarcNextStepKind, At as RiskLimit, B as ReceivedEmailEventType, Bi as ReactEmailElement, Bn as HookMessage, Br as ListDmarcReportsParams, Bt as RiskReasonCode, C as WebhookEndpointDisabledReason, Ca as ListAuditEventsParams, Ci as Email, Cn as HooksResource, Cr as TrackingDomainsResource, Ct as RiskEmailCheck, D as AccountEventType, Da as NamedResource, Di as EmailEvent, Dn as CreateHookPortalSessionParams, Dr as DmarcCheck, Dt as RiskIpCheck, E as WebhookEventType, Ea as Environment, Ei as EmailBatch, En as CreateHookEventTypeParams, Er as DmarcResource, Et as RiskFeedbackParams, F as EmailWebhookEvent, Fa as API_VERSIONS, Fi as EmailSummary, Fn as HookEndpointDisabledReason, Fr as DmarcReportRecord, Ft as RiskListEntryType, G as RiskWebhookEventData, Gi as SendEmailTemplateParams, Gn as ListHookMessagesParams, Gr as CreateTrackingDomainParams, Gt as UpdateRiskLimitBucketParams, H as ReceivedEmailWebhookEventData, Hi as SendEmailBaseParams, Hn as ListHookApplicationsParams, Hr as BimiStatus, Ht as RiskRuleCondition, I as EmailWebhookEventData, Ia as ApiVersion, Ii as EmailTag, In as HookEndpointRecovery, Ir as DmarcReportSummary, It as RiskListEntryValue, J as RiskLimitBucketsResource, Ji as CreateSuppressionParams, Jn as SendHookMessageParams, Jr as DomainBimi, Jt as ReputationResource, K as WebhookEvent, Ki as TrackingOptions, Kn as RecoverHookEndpointParams, Kr as DeletedDomain, Kt as UpdateRiskRuleParams, L as HookEndpointWebhookEvent, Li as EmailTracking, Ln as HookEndpointSecret, Lr as DmarcSource, Lt as RiskLoginSignals, M as DomainEventType, Ma as CossErrorType, Mi as EmailRecipient, Mn as HookDelivery, Mr as DmarcPolicyPublished, Mt as RiskLimitFailureMode, N as DomainWebhookEvent, Na as CossResult, Ni as EmailRecipientStatus, Nn as HookDeliveryStatus, Nr as DmarcPublishedRecord, Nt as RiskList, O as AccountWebhookEvent, Oa as FetchLike, Oi as EmailEventData, On as DeletedHookApplication, Or as DmarcCheckId, Ot as RiskIpPrivacy, P as DomainWebhookEventData, Pa as API_VERSION, Pi as EmailStatus, Pn as HookEndpoint, Pr as DmarcReport, Pt as RiskListEntry, Q as RiskSettingsResource, Qi as ImportSuppressionsParams, Qn as UpdateHookEventTypeParams, Qr as DomainStatus, Qt as ReputationStatus, R as HookEndpointWebhookEventData, Ri as List, Rn as HookEndpointWithSecret, Rr as DmarcStage, Rt as RiskOutcome, S as WebhookEndpoint, Sa as AuditEvent, Si as AuditEventsResource, Sn as HookPortalResource, Sr as DomainsResource, St as RiskDeviceSignals, T as WebhookEndpointWithSecret, Ta as DeletedApiKey, Ti as EmailAttachmentParams, Tn as CreateHookEndpointParams, Tr as DmarcReportsResource, Tt as RiskEvent, U as RiskEventType, Ui as SendEmailContentParams, Un as ListHookDeliveriesParams, Ur as CreateDomainParams, Ut as RiskRuleField, V as ReceivedEmailWebhookEvent, Vi as RescheduleEmailParams, Vn as HookPortalSession, Vr as BimiIssueCode, Vt as RiskRule, W as RiskWebhookEvent, Wi as SendEmailParams, Wn as ListHookEventTypesParams, Wr as CreateReceivingDomainParams, Wt as RiskSettings, X as RiskResource, Xi as ExportSuppressionsParams, Xn as UpdateHookApplicationParams, Xr as DomainRecordPurpose, Xt as ReputationCheck, Y as RiskListsResource, Yi as DeletedSuppression, Yn as SendHookTestParams, Yr as DomainRecord, Yt as Reputation, Z as RiskRulesResource, Zi as ImportSuppressionEntry, Zn as UpdateHookEndpointParams, Zr as DomainRecordStatus, Zt as ReputationCheckSeverity, _ as RollWebhookEndpointSecretParams, _a as TemplateVariableParams, _i as ListInvoicesParams, _n as HookApplicationsResource, _r as EmailTemplateVersionsResource, _t as RiskContentCategory, a as DeletedWebhookListener, aa as DeletedEmailTemplate, ai as BillingCreditsResource, an as LogDrain, ar as UpdateTrackingRuleParams, at as DeletedRiskLimitBucket, b as WebhookDelivery, ba as UpdateEmailTemplateParams, bi as PlanKey, bn as HookEventTypesResource, br as DedicatedIpPool, bt as RiskDecision, c as WebhookListenerAck, ca as EmailTemplateVersion, ci as Billing, cn as LogDrainBatchStatus, cr as DeletedReceivedEmail, ct as ForgottenRiskUser, d as WebhookEndpointsResource, da as PublishEmailTemplateParams, di as Invoice, dn as LogDrainWithSecret, dr as ReceivedEmail, dt as RiskAssessment, ea as Suppression, ei as ReceivingDomain, en as LogDrainBatchesResource, er as EmailResource, et as AssessRiskParams, f as WebhookDeliveriesResource, fa as TemplateContent, fi as InvoiceLine, fn as UpdateLogDrainParams, fr as ReceivedEmailAttachment, ft as RiskCalibration, g as RecoverWebhookEndpointParams, ga as TemplateVariable, gi as ListCreditsParams, gn as LogSource, gr as VerdictStatus, gt as RiskCheckoutSignals, h as ListWebhookDeliveriesParams, ha as TemplateScalarType, hi as InvoiceSummary, hn as LogLevel, hr as ReceivedEmailVerdicts, ht as RiskCardFunding, i as CreateWebhookListenerParams, ia as CreateEmailTemplateParams, ii as TrackingDomainStatus, in as ListLogDrainBatchesParams, ir as TrackingSettings, it as CreateRiskRuleParams, j as BillingWebhookEvent, ja as CossErrorIssue, ji as EmailLink, jn as HookAttempt, jr as DmarcPolicy, jt as RiskLimitBucket, k as AccountWebhookEventData, ka as RequestOptions, ki as EmailEventType, kn as DeletedHookEndpoint, kr as DmarcNextStep, kt as RiskIpSignals, l as WebhookListenerDelivery, la as ListEmailTemplateVersionsParams, li as BillingHoldReason, ln as LogDrainLine, lr as InboundAddress, lt as ListRiskAssessmentsParams, m as DeletedWebhookEndpoint, ma as TemplateProblem, mi as InvoiceStatus, mn as Log, mr as ReceivedEmailSummary, mt as RiskCaptchaSignals, n as CossOptions, na as SuppressionImport, ni as TrackingDomain, nn as CreateLogDrainParams, nr as DeletedTrackingRule, nt as CreateRiskLimitBucketParams, o as PollWebhookListenerParams, oa as EmailTemplate, oi as BillingInvoicesResource, on as LogDrainAttempt, or as SuppressionResource, ot as DeletedRiskListEntry, p as CreateWebhookEndpointParams, pa as TemplateContentParams, pi as InvoiceLineKind, pn as ListLogsParams, pr as ReceivedEmailStatus, pt as RiskCaptchaProvider, q as RiskAssessmentsResource, qi as CheckSuppressionParams, qn as RollHookEndpointSecretParams, qr as Domain, qt as UpdateRiskSettingsParams, r as WebhookListenersResource, ra as SuppressionReason, ri as TrackingDomainRecord, rn as DeletedLogDrain, rr as TrackingRule, rt as CreateRiskListEntryParams, s as WebhookListener, sa as EmailTemplateReference, si as BillingResource, sn as LogDrainBatch, sr as ReceivedEmailsResource, st as DeletedRiskRule, t as Coss, ta as SuppressionCheck, ti as ReceivingDomainRecord, tn as LogDrainsResource, tr as TrackingResource, tt as CheckRiskLimitParams, u as WebhookListenerPoll, ua as ListEmailTemplatesParams, ui as Credit, un as LogDrainSource, ur as ListReceivedEmailsParams, ut as ListRiskListEntriesParams, v as UpdateWebhookEndpointParams, va as TemplateVariableType, vi as ListUsageParams, vn as HookDeliveriesResource, vr as EmailTemplatesResource, vt as RiskContentClassification, w as WebhookEndpointRecovery, wa as ApiKeyResource, wi as EmailAttachment, wn as CreateHookApplicationParams, wr as ReceivingDomainsResource, wt as RiskEmailSignals, x as WebhookDeliveryStatus, xa as AuditActorType, xi as Usage, xn as HookMessagesResource, xr as DedicatedIpPoolStatus, xt as RiskDegradedSignal, y as WebhookAttempt, ya as UpdateEmailTemplateDraftParams, yi as Meter, yn as HookEndpointsResource, yr as DedicatedIpsResource, yt as RiskContentScores, z as HookOperationalEventType, zi as ListEmailsParams, zn as HookEventType, zr as DomainDmarc, zt as RiskReason } from "./client-avnHVMry.js";
3099
2
  //#region src/version.d.ts
3100
3
  /** 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";
4
+ export declare const VERSION = "0.5.0";
3102
5
  //#endregion
3103
6
  //#region src/webhooks.d.ts
3104
7
  /** A webhook request failed verification: reject it (e.g. respond 400). */
@@ -3122,7 +25,7 @@ interface VerifyWebhookOptions {
3122
25
  * const event = await verifyWebhook(await request.text(), request.headers, process.env.COSS_WEBHOOK_SECRET);
3123
26
  * ```
3124
27
  *
3125
- * The same check verifies messages your own users receive from COSS Hooks (`coss.hooks`): pass
28
+ * The same check verifies messages your own users receive from coss.com Hooks (`coss.hooks`): pass
3126
29
  * the endpoint's secret and name your payload type, e.g. `verifyWebhook<InvoicePaid>(…)`.
3127
30
  */
3128
31
  export declare function verifyWebhook<T = WebhookEvent>(payload: string, headers: WebhookHeaders, secret: string, options?: VerifyWebhookOptions): Promise<T>;
@@ -3139,4 +42,4 @@ export declare function verifyWebhook<T = WebhookEvent>(payload: string, headers
3139
42
  */
3140
43
  export declare function verifyLogDrainBatch(payload: string, headers: WebhookHeaders, secret: string, options?: VerifyWebhookOptions): Promise<LogDrainLine[]>;
3141
44
  //#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 };
45
+ export { API_VERSION, API_VERSIONS, type AccountEventType, type AccountWebhookEvent, type AccountWebhookEventData, type ApiKeyResource, type ApiVersion, type AssessRiskParams, type AuditActorType, type AuditEvent, type AuditEventsResource, type Billing, type BillingCreditsResource, type BillingEventType, type BillingHoldReason, type BillingInvoicesResource, type BillingResource, type BillingWebhookEvent, type BimiIssueCode, type BimiStatus, type CheckRiskLimitParams, type CheckSuppressionParams, Coss, type CossError, type CossErrorIssue, type CossErrorType, type CossOptions, type CossResult, type CreateDomainParams, type CreateEmailTemplateParams, type CreateHookApplicationParams, type CreateHookEndpointParams, type CreateHookEventTypeParams, type CreateHookPortalSessionParams, type CreateLogDrainParams, type CreateReceivingDomainParams, type CreateRiskLimitBucketParams, type CreateRiskListEntryParams, type CreateRiskRuleParams, type CreateSuppressionParams, type CreateTrackingDomainParams, type CreateWebhookEndpointParams, type CreateWebhookListenerParams, type Credit, type DedicatedIpPool, type DedicatedIpPoolStatus, type DedicatedIpsResource, type DeletedApiKey, type DeletedDomain, type DeletedEmailTemplate, type DeletedHookApplication, type DeletedHookEndpoint, type DeletedLogDrain, type DeletedReceivedEmail, type DeletedRiskLimitBucket, type DeletedRiskListEntry, type DeletedRiskRule, type DeletedSuppression, type DeletedTrackingRule, type DeletedWebhookEndpoint, type DeletedWebhookListener, type DmarcCheck, type DmarcCheckId, type DmarcNextStep, type DmarcNextStepKind, type DmarcPolicy, type DmarcPolicyPublished, type DmarcPublishedRecord, type DmarcReport, type DmarcReportRecord, type DmarcReportSummary, type DmarcReportsResource, type DmarcResource, type DmarcSource, type DmarcStage, type Domain, type DomainBimi, type DomainDmarc, type DomainEventType, type DomainRecord, type DomainRecordPurpose, type DomainRecordStatus, type DomainStatus, type DomainWebhookEvent, type DomainWebhookEventData, type DomainsResource, type Email, type EmailAttachment, type EmailAttachmentParams, type EmailBatch, type EmailEvent, type EmailEventData, type EmailEventType, type EmailFailure, type EmailLink, type EmailRecipient, type EmailRecipientStatus, type EmailResource, type EmailStatus, type EmailSummary, type EmailTag, type EmailTemplate, type EmailTemplateReference, type EmailTemplateVersion, type EmailTemplateVersionsResource, type EmailTemplatesResource, type EmailTracking, type EmailWebhookEvent, type EmailWebhookEventData, type Environment, type EnvironmentResource, type ExportSuppressionsParams, type FetchLike, type ForgottenRiskUser, type HookApplication, type HookApplicationsResource, type HookAttempt, type HookDeliveriesResource, type HookDelivery, type HookDeliveryStatus, type HookEndpoint, type HookEndpointDisabledReason, type HookEndpointRecovery, type HookEndpointSecret, type HookEndpointWebhookEvent, type HookEndpointWebhookEventData, type HookEndpointWithSecret, type HookEndpointsResource, type HookEventType, type HookEventTypesResource, type HookMessage, type HookMessagesResource, type HookOperationalEventType, type HookPortalResource, type HookPortalSession, type HooksResource, type ImportSuppressionEntry, type ImportSuppressionsParams, type InboundAddress, type Invoice, type InvoiceLine, type InvoiceLineKind, type InvoiceStatus, type InvoiceSummary, type List, type ListAuditEventsParams, type ListCreditsParams, type ListDmarcReportsParams, type ListEmailTemplateVersionsParams, type ListEmailTemplatesParams, type ListEmailsParams, type ListHookApplicationsParams, type ListHookDeliveriesParams, type ListHookEventTypesParams, type ListHookMessagesParams, type ListInvoicesParams, type ListLogDrainBatchesParams, type ListLogsParams, type ListReceivedEmailsParams, type ListRiskAssessmentsParams, type ListRiskListEntriesParams, type ListSuppressionsParams, type ListUsageParams, type ListWebhookDeliveriesParams, type Log, type LogDrain, type LogDrainAttempt, type LogDrainBatch, type LogDrainBatchStatus, type LogDrainBatchesResource, type LogDrainLine, type LogDrainSource, type LogDrainWithSecret, type LogDrainsResource, type LogLevel, type LogSource, type LogsResource, type MailFromStatus, type Meter, type NamedResource, type PlanKey, type PollWebhookListenerParams, type PublishEmailTemplateParams, type ReactEmailElement, type ReceivedEmail, type ReceivedEmailAttachment, type ReceivedEmailEventType, type ReceivedEmailStatus, type ReceivedEmailSummary, type ReceivedEmailVerdicts, type ReceivedEmailWebhookEvent, type ReceivedEmailWebhookEventData, type ReceivedEmailsResource, type ReceivingDomain, type ReceivingDomainRecord, type ReceivingDomainsResource, type RecoverHookEndpointParams, type RecoverWebhookEndpointParams, type Reputation, type ReputationCheck, type ReputationCheckSeverity, type ReputationResource, type ReputationStatus, type RequestOptions, type RescheduleEmailParams, type RiskAssessment, type RiskAssessmentsResource, type RiskCalibration, type RiskCaptchaProvider, type RiskCaptchaSignals, type RiskCardFunding, type RiskCheckoutSignals, type RiskContentCategory, type RiskContentClassification, type RiskContentScores, type RiskDecision, type RiskDegradedSignal, type RiskDeviceSignals, type RiskEmailCheck, type RiskEmailSignals, type RiskEvent, type RiskEventType, type RiskFeedbackParams, type RiskIpCheck, type RiskIpPrivacy, type RiskIpSignals, type RiskLimit, type RiskLimitBucket, type RiskLimitBucketsResource, type RiskLimitFailureMode, type RiskList, type RiskListEntry, type RiskListEntryType, type RiskListEntryValue, type RiskListsResource, type RiskLoginSignals, type RiskOutcome, type RiskReason, type RiskReasonCode, type RiskResource, type RiskRule, type RiskRuleCondition, type RiskRuleField, type RiskRulesResource, type RiskSettings, type RiskSettingsResource, type RiskUsersResource, type RiskWebhookEvent, type RiskWebhookEventData, type RollHookEndpointSecretParams, type RollWebhookEndpointSecretParams, type SendEmailBaseParams, type SendEmailContentParams, type SendEmailParams, type SendEmailTemplateParams, type SendHookMessageParams, type SendHookTestParams, type Suppression, type SuppressionCheck, type SuppressionImport, type SuppressionReason, type SuppressionResource, type TemplateContent, type TemplateContentParams, type TemplateProblem, type TemplateScalarType, type TemplateVariable, type TemplateVariableParams, type TemplateVariableType, type TrackingDomain, type TrackingDomainRecord, type TrackingDomainStatus, type TrackingDomainsResource, type TrackingOptions, type TrackingResource, type TrackingRule, type TrackingSettings, type UpdateEmailTemplateDraftParams, type UpdateEmailTemplateParams, type UpdateHookApplicationParams, type UpdateHookEndpointParams, type UpdateHookEventTypeParams, type UpdateLogDrainParams, type UpdateRiskLimitBucketParams, type UpdateRiskRuleParams, type UpdateRiskSettingsParams, type UpdateTrackingRuleParams, type UpdateWebhookEndpointParams, type Usage, type VerdictStatus, type VerifyWebhookOptions, type WebhookAttempt, type WebhookDeliveriesResource, type WebhookDelivery, type WebhookDeliveryStatus, type WebhookEndpoint, type WebhookEndpointDisabledReason, type WebhookEndpointRecovery, type WebhookEndpointWithSecret, type WebhookEndpointsResource, type WebhookEvent, type WebhookEventType, type WebhookHeaders, type WebhookListener, type WebhookListenerAck, type WebhookListenerDelivery, type WebhookListenerPoll, type WebhookListenersResource };