coss 0.2.0 → 0.3.0

package/dist/device.d.ts

@@ -0,0 +1,11 @@
+//#region src/device.d.ts
+export interface CollectDeviceOptions {
+  /**
+   * Where the device id is kept: `local` (default) remembers it in `localStorage`; `memory`
+   * keeps it only for this page (for example until the user consents to storage).
+   */
+  storage?: "local" | "memory";
+}
+/** Returns a token for `device.token` in `coss.risk.assess()`. Make a new one per submission. */
+export declare function collectDevice(options?: CollectDeviceOptions): string;
+//#endregion

package/dist/device.js

@@ -0,0 +1,71 @@
+//#region src/device.ts
+/**
+* `coss/device`: recognizes the browser behind risk events. Call `collectDevice()` in the browser
+* when the user submits a form, send the token to your server with it, and pass it to
+* `coss.risk.assess({ device: { token } })`.
+*
+* The token carries a random id this browser keeps in `localStorage` (`coss_device_id`, no
+* cookies) and coarse facts: time zone, languages, platform, screen size, touch support, and
+* whether the browser is automated (WebDriver, headless). No canvas, WebGL, font or audio
+* fingerprinting: a browser whose storage is cleared looks like a new one. COSS keeps only a keyed
+* hash of the id.
+*
+* Collects nothing until called, and never throws: outside a browser the token simply carries
+* fewer facts.
+*/
+/** The token format version, checked by the API. */
+const TOKEN_PREFIX = "cd1.";
+const STORAGE_KEY = "coss_device_id";
+const HEADLESS = /HeadlessChrome|PhantomJS|SlimerJS/;
+let memoryId;
+function randomId() {
+	const bytes = /* @__PURE__ */ new Uint8Array(16);
+	globalThis.crypto.getRandomValues(bytes);
+	return base64Url(bytes);
+}
+function base64Url(bytes) {
+	let binary = "";
+	for (const byte of bytes) binary += String.fromCharCode(byte);
+	return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+function deviceId(storage) {
+	if (storage === "local") try {
+		const store = globalThis.localStorage;
+		if (store) {
+			const stored = store.getItem(STORAGE_KEY);
+			if (stored && /^[A-Za-z0-9_-]{16,64}$/.test(stored)) return stored;
+			const id = randomId();
+			store.setItem(STORAGE_KEY, id);
+			return id;
+		}
+	} catch {}
+	memoryId ??= randomId();
+	return memoryId;
+}
+function safely(read, fallback) {
+	try {
+		return read() ?? fallback;
+	} catch {
+		return fallback;
+	}
+}
+/** Returns a token for `device.token` in `coss.risk.assess()`. Make a new one per submission. */
+function collectDevice(options = {}) {
+	const nav = globalThis.navigator;
+	const screen = globalThis.screen;
+	const userAgent = safely(() => nav?.userAgent ?? "", "");
+	const payload = {
+		id: deviceId(options.storage ?? "local"),
+		t: Date.now(),
+		tz: safely(() => Intl.DateTimeFormat().resolvedOptions().timeZone.slice(0, 64) || null, null),
+		l: safely(() => [...nav?.languages ?? []].slice(0, 10).map((l) => l.slice(0, 35)), []),
+		p: safely(() => (nav?.userAgentData?.platform || nav?.platform || "").slice(0, 64) || null, null),
+		s: safely(() => screen ? [Math.round(screen.width), Math.round(screen.height)] : null, null),
+		tp: safely(() => typeof nav?.maxTouchPoints === "number" ? Math.round(nav.maxTouchPoints) : null, null),
+		wd: safely(() => nav?.webdriver === true, false),
+		hl: HEADLESS.test(userAgent)
+	};
+	return `${TOKEN_PREFIX}${base64Url(new TextEncoder().encode(JSON.stringify(payload)))}`;
+}
+//#endregion
+export { collectDevice };

package/dist/index.d.ts

@@ -437,6 +437,15 @@ interface EmailLink {
   first_clicked_at: string | null;
   last_clicked_at: string | null;
 }
+/** Why an email failed as a whole. */
+interface EmailFailure {
+  /**
+   * E.g. `all_recipients_suppressed`, `domain_not_verified`, `content_rejected`,
+   * `attachments_unavailable`, `dispatch_failed` or `provider_error`.
+   */
+  code: string;
+  message: string;
+}
 /** An email as returned by the API. Recipient fields are always arrays. */
 interface Email {
   object: "email";
@@ -454,6 +463,8 @@ interface Email {
   tags: EmailTag[];
   category: string | null;
   status: EmailStatus;
+  /** Why the email failed; `null` unless `status` is `"failed"`. */
+  failure: EmailFailure | null;
   /** Every distinct recipient across `to`, `cc` and `bcc`, with its delivery status. */
   recipients: EmailRecipient[];
   /** Attachment metadata; the content is discarded once the email is sent. */
@@ -470,6 +481,31 @@ interface Email {
   /** The batch that sent the email (`coss.email.sendBatch`), or `null` if it was sent alone. */
   batch_id: string | null;
 }
+/** An email in a list (`coss.email.list`): everything but its content. */
+type EmailSummary = Omit<Email, "html" | "text" | "headers" | "attachments">;
+/** Filters of `coss.email.list`. Emails are returned newest first. */
+interface ListEmailsParams {
+  /** Only emails with this recipient (in `to`, `cc` or `bcc`; the bare address, any case). */
+  to?: string;
+  /** Only emails with a recipient in one of these statuses (with `to`, that recipient's). */
+  recipient_status?: EmailRecipientStatus[];
+  /** Only emails in these statuses. */
+  status?: EmailStatus[];
+  /** Free text, matched against the subject and the `to` addresses. */
+  q?: string;
+  /** Only emails of this category. */
+  category?: string;
+  /** Only the emails of this batch. */
+  batch_id?: string;
+  /** Only emails created at or after this time. */
+  created_after?: Date | string;
+  /** Only emails created before this time. */
+  created_before?: Date | string;
+  /** 1-100, default 20. */
+  limit?: number;
+  /** Cursor: the `id` of the last email of the previous page. */
+  after?: string;
+}
 /** Emails sent together by `coss.email.sendBatch`. */
 interface EmailBatch {
   object: "email_batch";
@@ -1199,6 +1235,12 @@ declare class EmailResource {
   sendBatch(emails: SendEmailParams[], options?: RequestOptions): Promise<CossResult<EmailBatch>>;
   /** Retrieves an email sent from the same environment as the API key. */
   get(id: string, options?: Pick<RequestOptions, "signal">): Promise<CossResult<Email>>;
+  /**
+   * Lists emails sent from the same environment as the API key, newest first and without their
+   * content (`get` one for `html`, `text`, `headers` and `attachments`). Pass the last `id` as
+   * `after` while `has_more` is true.
+   */
+  list(params?: ListEmailsParams, options?: Pick<RequestOptions, "signal">): Promise<CossResult<List<EmailSummary>>>;
   /**
    * Cancels a scheduled email. Canceling an already canceled email returns it; any other email
    * fails with `email_not_cancelable`.
@@ -1896,9 +1938,16 @@ type RiskList = "allow" | "block";
  */
 type RiskListEntryType = "email" | "domain" | "ip" | "asn" | "country" | "user";
 /** Signal groups an assessment was made without (a lookup failed or timed out). */
-type RiskDegradedSignal = "email_dns" | "domain_age" | "ip_data" | "velocity" | "captcha";
+type RiskDegradedSignal = "email_dns" | "domain_age" | "ip_data" | "velocity" | "captcha" | "content" | "ip_privacy";
+/** What content classification scores. */
+type RiskContentCategory = "spam" | "phishing" | "malware" | "fraud";
+/**
+ * Per category, the model's probability (0-1) that the content belongs to it. Not calibrated:
+ * pick thresholds by looking at your own traffic.
+ */
+type RiskContentScores = Record<RiskContentCategory, number>;
 /** Every reason an assessment can give (see the reason catalog in the docs). */
-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.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.logins_per_ip_1h" | "velocity.logins_per_user_1h" | "velocity.events_per_ip_1h" | "velocity.events_per_user_1h" | "duplicate.canonical_mailbox" | "history.fraud_mailbox" | "history.fraud_user" | "history.fraud_ip" | "history.fraud_subnet" | "login.new_country" | "login.new_network" | "captcha.failed" | "captcha.missing" | "rule.matched" | "list.blocked" | "list.allowed";
+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";
 /** Why an assessment decided what it did. Never show reasons to the person being assessed. */
 interface RiskReason {
   code: RiskReasonCode;
@@ -1911,11 +1960,11 @@ interface RiskReason {
   window?: "1h" | "24h";
   /** `email.typo`: the likely domain, which you may show the user ("Did you mean …?"). */
   suggestion?: string;
-  /** `ip.hosting_provider`, `ip.vpn_network`: the network's operator. */
+  /** `ip.hosting_provider`, `ip.vpn_network`: the network's operator; `ip.vpn`: the VPN service. */
   provider?: string;
-  /** `duplicate.canonical_mailbox`: your id of the user who has the mailbox, if known. */
+  /** `duplicate.*`: your id of the user who has the mailbox or device, if known. */
   previous_user?: string | null;
-  /** `duplicate.canonical_mailbox`: the assessment that first saw the mailbox. */
+  /** `duplicate.*`: the assessment that first saw the mailbox or device. */
   previous_assessment?: string;
   /** `list.*`: the matching list entry. */
   entry?: string;
@@ -1963,6 +2012,45 @@ interface RiskIpSignals {
   as_name: string | null;
   /** ISO 3166-1 alpha-2. */
   country: string | null;
+  /**
+   * From COSS's IP privacy data provider; `null` when it isn't available or was not asked
+   * (private addresses).
+   */
+  privacy: RiskIpPrivacy | null;
+}
+/** Whether an address is a VPN exit, a proxy or a privacy relay (iCloud Private Relay…). */
+interface RiskIpPrivacy {
+  vpn: boolean;
+  proxy: boolean;
+  relay: boolean;
+  /** The VPN or proxy service. */
+  service: string | null;
+}
+/** How a card is funded, as your payment processor reports it. */
+type RiskCardFunding = "credit" | "debit" | "prepaid" | "unknown";
+/** What you sent in `checkout` (never the card). */
+interface RiskCheckoutSignals {
+  amount: number;
+  currency: string;
+  card_country: string | null;
+  card_funding: RiskCardFunding | null;
+  billing_country: string | null;
+  shipping_country: string | null;
+}
+/** What the browser reported through `coss/device` (its device id is only kept as a keyed hash). */
+interface RiskDeviceSignals {
+  /** `false`: the token was malformed or too old. */
+  valid: boolean;
+  /** WebDriver control or a headless browser. */
+  automation: boolean;
+  /** IANA time zone (`Europe/London`). */
+  timezone: string | null;
+  /** The browser's first language. */
+  language: string | null;
+  platform: string | null;
+  /** `<width>x<height>` in CSS pixels. */
+  screen: string | null;
+  touch: boolean | null;
 }
 /** An assessment of one event. */
 interface RiskAssessment {
@@ -1985,6 +2073,10 @@ interface RiskAssessment {
     velocity: Record<string, number> | null;
     captcha: RiskCaptchaSignals | null;
     login: RiskLoginSignals | null;
+    /** `null` when no content was given or it couldn't be classified. */
+    content: RiskContentScores | null;
+    checkout: RiskCheckoutSignals | null;
+    device: RiskDeviceSignals | null;
   };
   user: {
     id: string | null;
@@ -2022,6 +2114,38 @@ interface AssessRiskParams {
   captcha?: {
     token: string;
   };
+  /**
+   * Text the user wrote (a bio, a message, a listing), classified with the event and never
+   * stored: its scores go in `signals.content`, and `content.*` reasons fire only at thresholds
+   * you set.
+   */
+  content?: {
+    text: string;
+  };
+  /** Only with `checkout` events: what is being paid for, and with which card. */
+  checkout?: {
+    /** In the currency's minor unit (cents for USD: 1999 is $19.99). */
+    amount: number;
+    /** ISO 4217, upper-case (`USD`). */
+    currency: string;
+    /** What your payment processor tells you about the card. */
+    card?: {
+      /**
+       * Your processor's fingerprint of the card number (Stripe: `card.fingerprint`), kept as a
+       * keyed hash only. Never send the card number.
+       */
+      fingerprint?: string;
+      /** Where the card was issued (ISO 3166-1 alpha-2, upper-case). */
+      country?: string;
+      funding?: RiskCardFunding;
+    };
+    billing_country?: string;
+    shipping_country?: string;
+  };
+  /** What `collectDevice()` from `coss/device` returned in the user's browser. */
+  device?: {
+    token: string;
+  };
 }
 /** Query of `GET /v1/risk/assessments`. */
 interface ListRiskAssessmentsParams {
@@ -2114,6 +2238,10 @@ interface RiskSettings {
     provider: RiskCaptchaProvider;
     required: boolean;
   } | null;
+  /** Per content category, the score at which `content.<category>` fires; `null`: never. */
+  content_thresholds: Record<RiskContentCategory, number | null>;
+  /** Reasons whose weight this environment changed; the rest weigh what the catalog says. */
+  reason_weights: Partial<Record<RiskReasonCode, number>>;
   /** ISO 8601 timestamp; `null` while on the defaults. */
   updated_at: string | null;
 }
@@ -2130,9 +2258,48 @@ interface UpdateRiskSettingsParams {
     /** Assessments without a token get `captcha.missing`. */
     required?: boolean;
   } | null;
+  /** Changes the categories given: a score in (0, 1] sets the threshold, `null` removes it. */
+  content_thresholds?: Partial<Record<RiskContentCategory, number | null>>;
+  /**
+   * Changes the reasons given: a weight in [0, 0.99] replaces the default (for example
+   * calibration's `suggested_weight`), `null` restores it. Not `list.*` or `rule.matched`.
+   */
+  reason_weights?: Partial<Record<RiskReasonCode, number | null>>;
+}
+/** Feedback counted against one reason or rule (`fraud` includes `abuse`). */
+interface RiskCalibrationCounts {
+  fraud: number;
+  legitimate: number;
+  /** `fraud / (fraud + legitimate)`; `null` without feedback. */
+  precision: number | null;
+}
+/** How often each reason and rule was right over the last 90 days, by your feedback. */
+interface RiskCalibration {
+  object: "risk_calibration";
+  window_days: number;
+  /** Assessments in the window. */
+  assessments: number;
+  /** Of those, with feedback. */
+  labeled: number;
+  reasons: (RiskCalibrationCounts & {
+    code: RiskReasonCode;
+    /** Assessments it fired in. */
+    fired: number;
+    default_weight: number;
+    /** Its weight in this environment now. */
+    weight: number;
+    /** What feedback supports; `null` with fewer than 20 assessments with feedback. */
+    suggested_weight: number | null;
+  })[];
+  rules: (RiskCalibrationCounts & {
+    rule: string;
+    name: string;
+    /** Assessments it decided. */
+    matched: number;
+  })[];
 }
 /** A field a rule condition can test (see the rules guide). */
-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.private" | "ip.country" | "ip.asn" | "ip.hosting_provider" | "captcha.passed" | "duplicate.canonical_mailbox" | "history.fraud" | "login.new_country" | "login.new_network" | "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";
+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";
 /** A test of one field. A field without a value (no IP, no email…) never matches. */
 interface RiskRuleCondition {
   field: RiskRuleField;
@@ -2179,6 +2346,107 @@ interface DeletedRiskRule {
   id: string;
   deleted: true;
 }
+/** Result of `coss.risk.checkEmail()`: what COSS knows about an address. Nothing is stored. */
+interface RiskEmailCheck {
+  object: "risk_email_check";
+  email: string;
+  valid: boolean;
+  domain: string | null;
+  /** The mailbox with the provider's aliasing folded (dots and `+tags` at Gmail…). */
+  canonical: string | null;
+  disposable: boolean;
+  /** From DNS (MX, A, AAAA). `unknown` when the lookup failed or timed out. */
+  deliverability: "deliverable" | "undeliverable" | "unknown";
+  role_account: boolean;
+  free_provider: boolean;
+  /** The likely intended domain when this one looks like a typo of a popular one. */
+  suggestion: string | null;
+  /** Days since the domain was registered (RDAP); `null` when unknown or not looked up. */
+  domain_age_days: number | null;
+  /** Lookups that failed or timed out. */
+  degraded: ("email_dns" | "domain_age")[];
+}
+/** Result of `coss.risk.checkIp()`. Nothing is stored. */
+interface RiskIpCheck extends RiskIpSignals {
+  object: "risk_ip_check";
+  ip: string;
+  /**
+   * `ip_data` when some IP data is unavailable at the moment; `ip_privacy` when the privacy data
+   * provider failed or timed out.
+   */
+  degraded: ("ip_data" | "ip_privacy")[];
+}
+/** Result of `coss.risk.classify()`: scores only, neither stored nor logged. */
+interface RiskContentClassification {
+  object: "risk_content_classification";
+  scores: RiskContentScores;
+  /** The text was longer than the model reads (8,000 characters): only its beginning counted. */
+  truncated: boolean;
+}
+/** What `on_failure` answers while COSS can't count. */
+type RiskLimitFailureMode = "allow" | "deny";
+/** One of your rate limit buckets: each key gets `burst` tokens, refilling `limit` per period. */
+interface RiskLimitBucket {
+  object: "risk_limit_bucket";
+  id: string;
+  /** What `coss.risk.limit({ bucket })` names it by. */
+  name: string;
+  /** Tokens added per `period_seconds`. */
+  limit: number;
+  period_seconds: number;
+  /** How many requests a key can make at once. */
+  burst: number;
+  on_failure: RiskLimitFailureMode;
+  /** ISO 8601 timestamp. */
+  created_at: string;
+  /** ISO 8601 timestamp. */
+  updated_at: string;
+}
+/** Body of `POST /v1/risk/limit_buckets`. */
+interface CreateRiskLimitBucketParams {
+  /** 1-64 lower-case letters, digits, `.`, `_` or `-`; unique in the environment. */
+  name: string;
+  limit: number;
+  /** 1 second to 1 day. */
+  period_seconds: number;
+  /** Defaults to `limit`. */
+  burst?: number;
+  /** Defaults to `allow`. */
+  on_failure?: RiskLimitFailureMode;
+}
+/** Body of `PATCH /v1/risk/limit_buckets/{id}` (the name can't change). */
+type UpdateRiskLimitBucketParams = Partial<Omit<CreateRiskLimitBucketParams, "name">>;
+interface DeletedRiskLimitBucket {
+  object: "risk_limit_bucket";
+  id: string;
+  deleted: true;
+}
+/** Body of `POST /v1/risk/limits`. */
+interface CheckRiskLimitParams {
+  /** The bucket's name. */
+  bucket: string;
+  /** Who or what is limited (a user id, an email or IP address…); COSS keeps only a hash. */
+  key: string;
+  /** Tokens this request takes. Default 1. */
+  cost?: number;
+}
+/** Result of `coss.risk.limit()`. */
+interface RiskLimit {
+  object: "risk_limit";
+  bucket: string;
+  /** Whether to let the request through. Denied requests take no tokens. */
+  allowed: boolean;
+  /** The bucket's size (`burst`). */
+  limit: number;
+  /** Tokens left for this key. */
+  remaining: number;
+  /** Milliseconds until the key's bucket is full again. */
+  reset_ms: number;
+  /** When denied: milliseconds until the same request would fit; `null` if it never would. */
+  retry_after_ms: number | null;
+  /** COSS couldn't count: `allowed` is the bucket's `on_failure`. */
+  degraded: boolean;
+}
 //#endregion
 //#region src/resources/risk.d.ts
 type ReadOptions$2 = Pick<RequestOptions, "signal">;
@@ -2241,6 +2509,22 @@ declare class RiskRulesResource {
   update(id: string, params: UpdateRiskRuleParams, options?: ReadOptions$2): Promise<CossResult<RiskRule>>;
   delete(id: string, options?: ReadOptions$2): Promise<CossResult<DeletedRiskRule>>;
 }
+/**
+ * `coss.risk.limitBuckets`: your rate limit buckets, which `coss.risk.limit()` charges per key.
+ */
+declare class RiskLimitBucketsResource {
+  #private;
+  /** @internal Use `new Coss().risk.limitBuckets`. */
+  constructor(http: HttpClient);
+  /** Creates a bucket. Not retried automatically: a retry would find its name taken. */
+  create(params: CreateRiskLimitBucketParams, options?: ReadOptions$2): Promise<CossResult<RiskLimitBucket>>;
+  /** Every bucket, by name. */
+  list(options?: ReadOptions$2): Promise<CossResult<List<RiskLimitBucket>>>;
+  get(id: string, options?: ReadOptions$2): Promise<CossResult<RiskLimitBucket>>;
+  /** Changes the fields given; the next check uses them. */
+  update(id: string, params: UpdateRiskLimitBucketParams, options?: ReadOptions$2): Promise<CossResult<RiskLimitBucket>>;
+  delete(id: string, options?: ReadOptions$2): Promise<CossResult<DeletedRiskLimitBucket>>;
+}
 /** `coss.risk.users`: what COSS remembers about your users. */
 declare class RiskUsersResource {
   #private;
@@ -2273,6 +2557,8 @@ declare class RiskResource {
   readonly settings: RiskSettingsResource;
   /** Rules (`create`, `list`, `get`, `update`, `delete`). */
   readonly rules: RiskRulesResource;
+  /** Your rate limit buckets (`create`, `list`, `get`, `update`, `delete`). */
+  readonly limitBuckets: RiskLimitBucketsResource;
   /** @internal Use `new Coss().risk`. */
   constructor(http: HttpClient);
   /**
@@ -2282,9 +2568,42 @@ declare class RiskResource {
   assess(params: AssessRiskParams, options?: RequestOptions): Promise<CossResult<RiskAssessment>>;
   /**
    * Reports what an assessed user turned out to be: `fraud` and `abuse` teach later assessments to
-   * flag the same mailbox, user, IP and subnet; `legitimate` takes that back. Resolves a review.
+   * flag the same mailbox, user, card, device, IP and subnet; `legitimate` takes that back.
+   * Resolves a review, and counts in `calibration()`.
    */
   feedback(id: string, params: RiskFeedbackParams, options?: RequestOptions): Promise<CossResult<RiskAssessment>>;
+  /**
+   * How often each reason and rule was right over the last 90 days, by your feedback, and the
+   * reason weights that supports. Apply them with `settings.update({ reason_weights })`.
+   */
+  calibration(options?: ReadOptions$2): Promise<CossResult<RiskCalibration>>;
+  /**
+   * Checks an email address on its own: syntax, disposable domains, deliverability, role
+   * accounts, free providers, the canonical mailbox, typos and domain age. Nothing is stored.
+   */
+  checkEmail(email: string, options?: ReadOptions$2): Promise<CossResult<RiskEmailCheck>>;
+  /**
+   * Checks an IP address on its own: Tor, cloud, hosting and VPN networks, ASN and country, and
+   * VPN, proxy and relay exits when COSS's privacy data is available.
+   */
+  checkIp(ip: string, options?: ReadOptions$2): Promise<CossResult<RiskIpCheck>>;
+  /**
+   * Scores text for spam, phishing, malware and fraud. Scores only, never a verdict: you choose
+   * the thresholds. The text is neither stored nor logged.
+   */
+  classify(params: {
+    text: string;
+  }, options?: ReadOptions$2): Promise<CossResult<RiskContentClassification>>;
+  /**
+   * Takes `cost` tokens (default 1) from `key`'s share of one of your buckets
+   * (`coss.risk.limitBuckets`). Retries reuse one `Idempotency-Key`, so they are charged once.
+   *
+   * ```ts
+   * const { data } = await coss.risk.limit({ bucket: "password_reset", key: email });
+   * if (data && !data.allowed) return tooManyRequests(data.retry_after_ms);
+   * ```
+   */
+  limit(params: CheckRiskLimitParams, options?: RequestOptions): Promise<CossResult<RiskLimit>>;
 }
 //#endregion
 //#region src/types/webhook.d.ts
@@ -2779,7 +3098,7 @@ export declare class Coss {
 //#endregion
 //#region src/version.d.ts
 /** SDK version, sent in the User-Agent. A test keeps it equal to package.json's `version`. */
-export declare const VERSION = "0.2.0";
+export declare const VERSION = "0.3.0";
 //#endregion
 //#region src/webhooks.d.ts
 /** A webhook request failed verification: reject it (e.g. respond 400). */
@@ -2820,4 +3139,4 @@ export declare function verifyWebhook<T = WebhookEvent>(payload: string, headers
  */
 export declare function verifyLogDrainBatch(payload: string, headers: WebhookHeaders, secret: string, options?: VerifyWebhookOptions): Promise<LogDrainLine[]>;
 //#endregion
-export type { AccountEventType, AccountWebhookEvent, AccountWebhookEventData, ApiVersion, AssessRiskParams, AuditActorType, AuditEvent, AuditEventsResource, Billing, BillingCreditsResource, BillingEventType, BillingHoldReason, BillingInvoicesResource, BillingResource, BillingWebhookEvent, CheckSuppressionParams, CossError, CossErrorIssue, CossErrorType, CossOptions, CossResult, CreateDomainParams, CreateHookApplicationParams, CreateHookEndpointParams, CreateHookEventTypeParams, CreateHookPortalSessionParams, CreateLogDrainParams, CreateReceivingDomainParams, CreateRiskListEntryParams, CreateRiskRuleParams, CreateSuppressionParams, CreateTrackingDomainParams, CreateWebhookEndpointParams, Credit, DeletedDomain, DeletedHookApplication, DeletedHookEndpoint, DeletedLogDrain, DeletedReceivedEmail, DeletedRiskListEntry, DeletedRiskRule, DeletedSuppression, DeletedTrackingRule, DeletedWebhookEndpoint, Domain, DomainRecord, DomainRecordPurpose, DomainRecordStatus, DomainStatus, DomainsResource, Email, EmailAttachment, EmailAttachmentParams, EmailBatch, EmailEvent, EmailEventData, EmailEventType, EmailLink, EmailRecipient, EmailRecipientStatus, EmailResource, EmailStatus, 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, 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, RiskCaptchaProvider, RiskCaptchaSignals, RiskDecision, RiskDegradedSignal, RiskEmailSignals, RiskEvent, RiskEventType, RiskFeedbackParams, RiskIpSignals, 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, UpdateRiskRuleParams, UpdateRiskSettingsParams, UpdateTrackingRuleParams, UpdateWebhookEndpointParams, Usage, VerdictStatus, VerifyWebhookOptions, WebhookAttempt, WebhookDeliveriesResource, WebhookDelivery, WebhookDeliveryStatus, WebhookEndpoint, WebhookEndpointDisabledReason, WebhookEndpointRecovery, WebhookEndpointWithSecret, WebhookEndpointsResource, WebhookEvent, WebhookEventType, WebhookHeaders };
+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 };

package/dist/index.js

@@ -9,7 +9,7 @@ const API_VERSION = "2026-10-10";
 //#endregion
 //#region src/version.ts
 /** SDK version, sent in the User-Agent. A test keeps it equal to package.json's `version`. */
-const VERSION = "0.2.0";
+const VERSION = "0.3.0";
 //#endregion
 //#region src/core/errors.ts
 const API_ERROR_TYPES = /* @__PURE__ */ new Set([
@@ -826,6 +826,19 @@ var EmailResource = class {
 		});
 	}
 	/**
+	* Lists emails sent from the same environment as the API key, newest first and without their
+	* content (`get` one for `html`, `text`, `headers` and `attachments`). Pass the last `id` as
+	* `after` while `has_more` is true.
+	*/
+	list(params = {}, options) {
+		return this.#http.request({
+			method: "GET",
+			path: "/v1/emails",
+			query: listQuery(params),
+			signal: options?.signal
+		});
+	}
+	/**
 	* Cancels a scheduled email. Canceling an already canceled email returns it; any other email
 	* fails with `email_not_cancelable`.
 	*/
@@ -1521,6 +1534,57 @@ var RiskRulesResource = class {
 		});
 	}
 };
+/**
+* `coss.risk.limitBuckets`: your rate limit buckets, which `coss.risk.limit()` charges per key.
+*/
+var RiskLimitBucketsResource = class {
+	#http;
+	/** @internal Use `new Coss().risk.limitBuckets`. */
+	constructor(http) {
+		this.#http = http;
+	}
+	/** Creates a bucket. Not retried automatically: a retry would find its name taken. */
+	create(params, options) {
+		return this.#http.request({
+			method: "POST",
+			path: "/v1/risk/limit_buckets",
+			body: params,
+			retry: false,
+			signal: options?.signal
+		});
+	}
+	/** Every bucket, by name. */
+	list(options) {
+		return this.#http.request({
+			method: "GET",
+			path: "/v1/risk/limit_buckets",
+			signal: options?.signal
+		});
+	}
+	get(id, options) {
+		return this.#http.request({
+			method: "GET",
+			path: `/v1/risk/limit_buckets/${encodeURIComponent(id)}`,
+			signal: options?.signal
+		});
+	}
+	/** Changes the fields given; the next check uses them. */
+	update(id, params, options) {
+		return this.#http.request({
+			method: "PATCH",
+			path: `/v1/risk/limit_buckets/${encodeURIComponent(id)}`,
+			body: params,
+			signal: options?.signal
+		});
+	}
+	delete(id, options) {
+		return this.#http.request({
+			method: "DELETE",
+			path: `/v1/risk/limit_buckets/${encodeURIComponent(id)}`,
+			signal: options?.signal
+		});
+	}
+};
 /** `coss.risk.users`: what COSS remembers about your users. */
 var RiskUsersResource = class {
 	#http;
@@ -1560,6 +1624,8 @@ var RiskResource = class {
 	settings;
 	/** Rules (`create`, `list`, `get`, `update`, `delete`). */
 	rules;
+	/** Your rate limit buckets (`create`, `list`, `get`, `update`, `delete`). */
+	limitBuckets;
 	#http;
 	/** @internal Use `new Coss().risk`. */
 	constructor(http) {
@@ -1569,6 +1635,7 @@ var RiskResource = class {
 		this.users = new RiskUsersResource(http);
 		this.settings = new RiskSettingsResource(http);
 		this.rules = new RiskRulesResource(http);
+		this.limitBuckets = new RiskLimitBucketsResource(http);
 	}
 	/**
 	* Assesses an event and returns the decision with its score and reasons. Retries reuse one
@@ -1585,7 +1652,8 @@ var RiskResource = class {
 	}
 	/**
 	* Reports what an assessed user turned out to be: `fraud` and `abuse` teach later assessments to
-	* flag the same mailbox, user, IP and subnet; `legitimate` takes that back. Resolves a review.
+	* flag the same mailbox, user, card, device, IP and subnet; `legitimate` takes that back.
+	* Resolves a review, and counts in `calibration()`.
 	*/
 	feedback(id, params, options) {
 		return this.#http.request({
@@ -1596,6 +1664,71 @@ var RiskResource = class {
 			signal: options?.signal
 		});
 	}
+	/**
+	* How often each reason and rule was right over the last 90 days, by your feedback, and the
+	* reason weights that supports. Apply them with `settings.update({ reason_weights })`.
+	*/
+	calibration(options) {
+		return this.#http.request({
+			method: "GET",
+			path: "/v1/risk/calibration",
+			signal: options?.signal
+		});
+	}
+	/**
+	* Checks an email address on its own: syntax, disposable domains, deliverability, role
+	* accounts, free providers, the canonical mailbox, typos and domain age. Nothing is stored.
+	*/
+	checkEmail(email, options) {
+		return this.#http.request({
+			method: "POST",
+			path: "/v1/risk/email/check",
+			body: { email },
+			signal: options?.signal
+		});
+	}
+	/**
+	* Checks an IP address on its own: Tor, cloud, hosting and VPN networks, ASN and country, and
+	* VPN, proxy and relay exits when COSS's privacy data is available.
+	*/
+	checkIp(ip, options) {
+		return this.#http.request({
+			method: "POST",
+			path: "/v1/risk/ip/check",
+			body: { ip },
+			signal: options?.signal
+		});
+	}
+	/**
+	* Scores text for spam, phishing, malware and fraud. Scores only, never a verdict: you choose
+	* the thresholds. The text is neither stored nor logged.
+	*/
+	classify(params, options) {
+		return this.#http.request({
+			method: "POST",
+			path: "/v1/risk/content/classify",
+			body: params,
+			signal: options?.signal
+		});
+	}
+	/**
+	* Takes `cost` tokens (default 1) from `key`'s share of one of your buckets
+	* (`coss.risk.limitBuckets`). Retries reuse one `Idempotency-Key`, so they are charged once.
+	*
+	* ```ts
+	* const { data } = await coss.risk.limit({ bucket: "password_reset", key: email });
+	* if (data && !data.allowed) return tooManyRequests(data.retry_after_ms);
+	* ```
+	*/
+	limit(params, options) {
+		return this.#http.request({
+			method: "POST",
+			path: "/v1/risk/limits",
+			body: params,
+			idempotencyKey: options?.idempotencyKey,
+			signal: options?.signal
+		});
+	}
 };
 //#endregion
 //#region src/resources/webhook-deliveries.ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "coss",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "The official TypeScript SDK for COSS: email, SMS, video, scheduling and more behind one API key.",
   "license": "MIT",
   "homepage": "https://coss.com/docs",
@@ -23,6 +23,7 @@
   "types": "./dist/index.d.ts",
   "exports": {
     ".": "./dist/index.js",
+    "./device": "./dist/device.js",
     "./package.json": "./package.json"
   },
   "scripts": {