coss 0.3.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.js

@@ -7,7 +7,7 @@
 * 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
+* 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