coss 0.2.0 → 0.4.0

package/README.md

@@ -1,6 +1,6 @@
 # coss
 
-The official TypeScript SDK for COSS: one API key for email, and soon SMS, video, scheduling and more.
+The official TypeScript SDK for coss.com: one API key for email, and soon SMS, video, scheduling and more.
 
 ```sh
 npm install coss
@@ -10,7 +10,7 @@ Published from [cosscom/coss](https://github.com/cosscom/coss) by CI, with
 [provenance](https://docs.npmjs.com/generating-provenance-statements). Versions 0.0.1–0.0.5 of the npm package
 are an earlier, unrelated package by a previous owner (deprecated).
 
-- Zero dependencies, ESM-only, fully typed.
+- Zero dependencies (React Email support is an optional peer), ESM-only, fully typed.
 - `coss.email`, `coss.domains`, `coss.webhookEndpoints` and `coss.reputation` behind one API key.
 - Every method returns `{ data, error }`. API and network failures are returned, never thrown.
 - Retries transient failures automatically, and sends are idempotent.
@@ -25,7 +25,7 @@ const coss = new Coss({ apiKey: process.env.COSS_API_KEY });
 const { data, error } = await coss.email.send({
   from: "Acme <onboarding@example.com>",
   to: "delivered@example.com",
-  subject: "Hello from COSS",
+  subject: "Hello from coss.com",
   html: "<p>It works!</p>",
 });
 
@@ -73,7 +73,7 @@ The constructor throws in only two cases, both programmer errors:
 - It runs where a `document` global exists (a browser, or a jsdom or happy-dom test environment)
   without `dangerouslyAllowBrowser: true`.
 
-API keys are secrets, so call COSS from your server.
+API keys are secrets, so call coss.com from your server.
 
 Each method also takes per-request options:
 
@@ -99,6 +99,35 @@ import { API_VERSION } from "coss";
 await coss.webhookEndpoints.update("whep_01k…", { api_version: API_VERSION });
 ```
 
+## React Email
+
+Pass a [React Email](https://react.email) component as `react` instead of `html`. The SDK renders it
+with `@react-email/render`, an optional peer dependency you install yourself (with `react` and
+`react-dom`, which your components need anyway):
+
+```sh
+npm install @react-email/render
+```
+
+```tsx
+import { WelcomeEmail } from "./emails/welcome";
+
+await coss.email.send({
+  from: "Acme <hello@acme.com>",
+  to: "ada@example.com",
+  subject: "Welcome to Acme",
+  react: <WelcomeEmail name="Ada" />,
+});
+```
+
+The component becomes `html`, and `text` too unless you pass your own. Rendering happens once, before
+the first attempt, so retries resend the same body. `sendBatch` renders each email's `react` the same way.
+Nothing throws: `react` together with `html` returns `validation_error`, a missing
+`@react-email/render` returns `react_renderer_missing`, and a component that throws returns
+`react_render_failed`, all `invalid_request_error`s with `param` naming the email (`react`,
+`emails.3.react`) and no request made. The SDK itself still has no dependencies: the renderer is imported
+only by a send that has `react`.
+
 ## Attachments
 
 Attach up to 20 files (25 MB combined) as base64. The content type defaults from the extension.
@@ -120,7 +149,7 @@ await coss.email.send({
 ```
 
 Emails only return attachment metadata (`id`, `filename`, `content_type`, `content_id`, `size`).
-COSS discards the content once the email is sent. Executables and other file types the delivery
+coss.com discards the content once the email is sent. Executables and other file types the delivery
 provider refuses (`.exe`, `.js`, `.bat`, …) are rejected with a `validation_error`.
 
 ## Domains
@@ -148,7 +177,8 @@ await coss.domains.delete(domain!.id);
 rate limited: a second call within a few seconds answers `429` (the SDK waits out `Retry-After` and
 retries). Verification gives up after 72 hours and the domain becomes `failed`; calling `verify`
 again then starts over with fresh DKIM records, which have to be published too. The `dmarc` record
-is recommended rather than required (`required: false`).
+is recommended rather than required (`required: false`). `bimi` reports whether mailbox providers can show
+your brand logo (your own BIMI record and VMC or CMC certificate, with DMARC at enforcement).
 
 ## Webhook endpoints
 
@@ -241,7 +271,7 @@ Imported entries have the reason `import`. The dashboard imports and exports the
 ### Open and click tracking
 
 Tracking is off unless the environment turns it on in the dashboard (a default, plus rules per
-category) or a send asks for it. COSS then adds an invisible image to the HTML body and sends its
+category) or a send asks for it. coss.com then adds an invisible image to the HTML body and sends its
 links through a redirect. Links with a `data-coss-no-track` attribute are left as they are.
 
 ```ts
@@ -264,9 +294,9 @@ one. Mail clients that preload images and link scanners can inflate the numbers.
 
 ## Reputation
 
-COSS watches your live bounce and complaint rates. When one gets too high your organization is
+coss.com watches your live bounce and complaint rates. When one gets too high your organization is
 warned, and past the suspension threshold live sending is suspended automatically (sends fail with
-`permission_error` / `account_suspended`; sandbox keys keep working) until COSS support reinstates it.
+`permission_error` / `account_suspended`; sandbox keys keep working) until coss.com support reinstates it.
 
 ```ts
 const { data } = await coss.reputation.get();
@@ -325,7 +355,7 @@ interface CossError {
 | `not_found_error`       | 404               | No such resource in the key's environment                         |
 | `idempotency_error`     | 409 / 422         | `request_in_progress` (retried automatically), or `idempotency_key_reused` with a different body |
 | `rate_limit_error`      | 429               | Too many requests with the key (`rate_limited`), the send quota is used up (`quota_exceeded`), or a domain was checked moments ago (`domain_recently_checked`) |
-| `api_error`             | 5xx, other        | Server error. Also used for responses that are not a COSS error envelope (`unexpected_response`) |
+| `api_error`             | 5xx, other        | Server error. Also used for responses that are not a coss.com error envelope (`unexpected_response`) |
 | `connection_error`      | —                 | Network failure (`network_error`), or you aborted (`aborted`)      |
 | `timeout_error`         | —                 | An attempt exceeded `timeout` (`request_timeout`)                 |
 

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.com 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 };