coss 0.3.0 → 0.5.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`)                 |
 
@@ -361,6 +391,29 @@ To make a send safe across process restarts too, pass your own key, derived from
 cancel a call. Aborting stops the request in flight and any pending retry, and returns
 `{ type: "connection_error", code: "aborted" }`.
 
+## Integrations
+
+To send from libraries you already use, import the matching entry. They need no other package
+than the library itself, and they throw a `CossSendError` when coss.com refuses an email.
+
+```ts
+// Nodemailer
+import nodemailer from "nodemailer";
+import { cossTransport } from "coss/nodemailer";
+const transporter = nodemailer.createTransport(cossTransport());
+
+// Better Auth: verification, password reset, magic link, one-time code and invitation emails
+import { cossEmail } from "coss/better-auth";
+const email = cossEmail({ from: "Acme <auth@acme.com>", appName: "Acme" });
+// betterAuth({ emailVerification: { sendVerificationEmail: email.sendVerificationEmail }, … })
+
+// Auth.js (NextAuth.js v5): the email provider
+import Coss from "coss/authjs";
+// NextAuth({ adapter, providers: [Coss({ from: "Acme <auth@acme.com>" })] })
+```
+
+Guides: [coss.com/docs/integrations](https://coss.com/docs/integrations).
+
 ## Runtime support
 
 The SDK works on Node.js ≥ 22, Bun, Deno and Cloudflare Workers. It only needs the standard `fetch`,

package/dist/authjs.d.ts

@@ -0,0 +1,64 @@
+import { n as IntegrationClientOptions, t as CossSendError } from "./integration-p3vtLNgq.js";
+//#region src/authjs.d.ts
+/** What Auth.js passes to `sendVerificationRequest` (the fields the provider reads). */
+export interface CossVerificationRequestParams {
+  /** The address to send the link to. */
+  identifier: string;
+  url: string;
+  token: string;
+  expires: Date;
+  provider: {
+    apiKey?: string;
+    from?: string;
+  };
+  theme: {
+    brandColor?: string;
+    buttonText?: string;
+  };
+}
+/** An email's content, as `render` returns it. */
+export interface CossVerificationEmail {
+  subject: string;
+  html: string;
+  text: string;
+}
+export interface CossProviderConfig extends IntegrationClientOptions {
+  /** The sender, e.g. `"Acme <auth@acme.com>"`, on a domain verified in coss.com (live keys). */
+  from?: string;
+  /** How long a link is valid, in seconds. Default 24 hours. */
+  maxAge?: number;
+  /** Replace the default email (Auth.js's layout). */
+  render?: (params: CossVerificationRequestParams & {
+    host: string;
+  }) => CossVerificationEmail;
+  /** Defaults to `"account"`. */
+  category?: string;
+  /** Provider id, default `"coss"` (also names the env variable: `AUTH_COSS_KEY`). */
+  id?: string;
+  /** Shown on Auth.js's sign-in page. Default `"Email"`. */
+  name?: string;
+}
+/** The provider object Auth.js reads. */
+export interface CossEmailProvider {
+  id: string;
+  type: "email";
+  name: string;
+  from?: string;
+  maxAge: number;
+  apiKey?: string;
+  sendVerificationRequest: (params: CossVerificationRequestParams) => Promise<void>;
+  /** What Auth.js merges over the provider (a type literal: Auth.js wants a `Record`). */
+  options: {
+    id?: string;
+    name?: string;
+    from?: string;
+    maxAge?: number;
+  };
+}
+/**
+ * An Auth.js email provider. Links go out with `category: "account"` and open and click tracking
+ * off: click tracking would route the secret link through coss.com's redirect.
+ */
+export declare function CossProvider(config?: CossProviderConfig): CossEmailProvider;
+//#endregion
+export { CossProvider as default, CossSendError };

package/dist/authjs.js

@@ -0,0 +1,97 @@
+import { c as CossSendError, l as lazyClient, o as sha256Hex, r as escapeHtml } from "./mime-C8bhhjvD.js";
+//#region src/authjs.ts
+/**
+* An Auth.js email provider. Links go out with `category: "account"` and open and click tracking
+* off: click tracking would route the secret link through coss.com's redirect.
+*/
+function CossProvider(config = {}) {
+	const clients = /* @__PURE__ */ new Map();
+	const clientFor = (apiKey) => {
+		const key = apiKey ?? config.apiKey ?? "";
+		let client = clients.get(key);
+		if (!client) {
+			client = lazyClient("authjs", config, () => apiKey ?? config.apiKey);
+			clients.set(key, client);
+		}
+		return client();
+	};
+	return {
+		id: config.id ?? "coss",
+		type: "email",
+		name: config.name ?? "Email",
+		from: config.from,
+		maxAge: config.maxAge ?? 86400,
+		apiKey: config.apiKey,
+		async sendVerificationRequest(params) {
+			const from = params.provider.from ?? config.from;
+			if (!from) throw new Error("coss/authjs: set `from`, e.g. Coss({ from: \"Acme <auth@acme.com>\" }).");
+			const host = new URL(params.url).host;
+			const email = (config.render ?? defaultEmail)({
+				...params,
+				host
+			});
+			const result = await clientFor(params.provider.apiKey).email.send({
+				from,
+				to: params.identifier,
+				subject: email.subject,
+				html: email.html,
+				text: email.text,
+				category: config.category ?? "account",
+				tracking: {
+					opens: false,
+					clicks: false
+				}
+			}, { idempotencyKey: `authjs_${await sha256Hex(params.token)}` });
+			if (result.error) throw new CossSendError(result.error);
+		},
+		options: {
+			id: config.id,
+			name: config.name,
+			from: config.from,
+			maxAge: config.maxAge
+		}
+	};
+}
+/** Auth.js's own sign-in email, with the host's dots broken so clients don't link them. */
+function defaultEmail({ url, host, theme }) {
+	const escapedHost = escapeHtml(host).replace(/\./g, "&#8203;.");
+	const brandColor = escapeHtml(theme.brandColor || "#346df1");
+	const buttonText = escapeHtml(theme.buttonText || "#fff");
+	const html = `<body style="background: #f9f9f9;">
+  <table width="100%" border="0" cellspacing="20" cellpadding="0"
+    style="background: #fff; max-width: 600px; margin: auto; border-radius: 10px;">
+    <tr>
+      <td align="center"
+        style="padding: 10px 0px; font-size: 22px; font-family: Helvetica, Arial, sans-serif; color: #444;">
+        Sign in to <strong>${escapedHost}</strong>
+      </td>
+    </tr>
+    <tr>
+      <td align="center" style="padding: 20px 0;">
+        <table border="0" cellspacing="0" cellpadding="0">
+          <tr>
+            <td align="center" style="border-radius: 5px;" bgcolor="${brandColor}"><a href="${escapeHtml(url)}"
+                target="_blank"
+                style="font-size: 18px; font-family: Helvetica, Arial, sans-serif; color: ${buttonText}; text-decoration: none; border-radius: 5px; padding: 10px 20px; border: 1px solid ${brandColor}; display: inline-block; font-weight: bold;">Sign
+                in</a></td>
+          </tr>
+        </table>
+      </td>
+    </tr>
+    <tr>
+      <td align="center"
+        style="padding: 0px 0px 10px 0px; font-size: 16px; line-height: 22px; font-family: Helvetica, Arial, sans-serif; color: #444;">
+        If you did not request this email you can safely ignore it.
+      </td>
+    </tr>
+  </table>
+</body>
+`;
+	return {
+		subject: `Sign in to ${host}`,
+		html,
+		text: `Sign in to ${host}\n${url}\n\n`
+	};
+}
+//#endregion
+export { CossProvider, CossProvider as default, CossSendError };

package/dist/better-auth.d.ts

@@ -0,0 +1,128 @@
+import { Ci as Email, Wi as SendEmailParams } from "./client-avnHVMry.js";
+import { n as IntegrationClientOptions, t as CossSendError } from "./integration-p3vtLNgq.js";
+//#region src/better-auth.d.ts
+/** An email's content: what a template returns. */
+export interface EmailContent {
+  subject: string;
+  html: string;
+  text: string;
+}
+/** The user Better Auth passes to its callbacks (only the fields the templates read). */
+export interface BetterAuthUser {
+  email: string;
+  name?: string | null;
+}
+export interface VerificationEmailData {
+  user: BetterAuthUser;
+  url: string;
+  token: string;
+}
+export interface ResetPasswordData {
+  user: BetterAuthUser;
+  url: string;
+  token: string;
+}
+export interface ChangeEmailConfirmationData {
+  user: BetterAuthUser;
+  newEmail: string;
+  url: string;
+  token: string;
+}
+export interface DeleteAccountVerificationData {
+  user: BetterAuthUser;
+  url: string;
+  token: string;
+}
+export interface MagicLinkData {
+  email: string;
+  url: string;
+  token: string;
+}
+export interface VerificationOtpData {
+  email: string;
+  otp: string;
+  type: "sign-in" | "email-verification" | "forget-password" | "change-email";
+}
+export interface InvitationData {
+  id: string;
+  email: string;
+  role: string;
+  organization: {
+    name: string;
+  };
+  inviter: {
+    user: BetterAuthUser;
+  };
+}
+/** Template data: what Better Auth passed, plus your `appName`. */
+type WithApp<T> = T & {
+  appName: string | undefined;
+};
+/** One template per email; each returns the subject and both bodies. */
+export interface CossEmailTemplates {
+  verifyEmail: (data: WithApp<VerificationEmailData>) => EmailContent;
+  resetPassword: (data: WithApp<ResetPasswordData>) => EmailContent;
+  changeEmailConfirmation: (data: WithApp<ChangeEmailConfirmationData>) => EmailContent;
+  deleteAccount: (data: WithApp<DeleteAccountVerificationData>) => EmailContent;
+  magicLink: (data: WithApp<MagicLinkData>) => EmailContent;
+  verificationOtp: (data: WithApp<VerificationOtpData>) => EmailContent;
+  invitation: (data: WithApp<InvitationData & {
+    url: string;
+  }>) => EmailContent;
+}
+export interface CossEmailOptions extends IntegrationClientOptions {
+  /** The sender, e.g. `"Acme <auth@acme.com>"`, on a domain verified in coss.com (live keys). */
+  from: string;
+  /** Your product's name, used by the default templates ("Sign in to Acme"). */
+  appName?: string;
+  /** Replace any of the default templates. */
+  templates?: Partial<CossEmailTemplates>;
+  /**
+   * The page where an invitee accepts an organization invitation, e.g.
+   * `({ id }) => \`https://acme.com/accept-invitation/${id}\``. Better Auth passes no URL to
+   * `sendInvitationEmail`, so it needs this.
+   */
+  invitationUrl?: (data: InvitationData) => string;
+  /** Defaults to `"account"`, so suppressions scoped to other categories never block sign-in mail. */
+  category?: string;
+}
+/**
+ * Parameters of `send`: `from`, `category` and tracking default to the `cossEmail` options. Like
+ * `coss.email.send`, a send has its own content or names a template.
+ */
+export type CossEmailSendParams = SendEmailParams extends (infer Params) ? Params extends SendEmailParams ? Omit<Params, "from"> & {
+  from?: string;
+} : never : never;
+/** The callbacks `cossEmail` returns; pass each to the matching Better Auth option. */
+export interface CossEmail {
+  /** `emailVerification.sendVerificationEmail` */
+  sendVerificationEmail: (data: VerificationEmailData, request?: unknown) => Promise<void>;
+  /** `emailAndPassword.sendResetPassword` */
+  sendResetPassword: (data: ResetPasswordData, request?: unknown) => Promise<void>;
+  /** `user.changeEmail.sendChangeEmailConfirmation` (sent to the current address) */
+  sendChangeEmailConfirmation: (data: ChangeEmailConfirmationData, request?: unknown) => Promise<void>;
+  /** `user.deleteUser.sendDeleteAccountVerification` */
+  sendDeleteAccountVerification: (data: DeleteAccountVerificationData, request?: unknown) => Promise<void>;
+  /** `magicLink({ sendMagicLink })` */
+  sendMagicLink: (data: MagicLinkData, ctx?: unknown) => Promise<void>;
+  /** `emailOTP({ sendVerificationOTP })` */
+  sendVerificationOTP: (data: VerificationOtpData, ctx?: unknown) => Promise<void>;
+  /** `organization({ sendInvitationEmail })`; needs the `invitationUrl` option. */
+  sendInvitationEmail: (data: InvitationData, request?: unknown) => Promise<void>;
+  /** Sends any other email with the same defaults. Throws `CossSendError` on failure. */
+  send: (params: CossEmailSendParams, options?: {
+    idempotencyKey?: string;
+  }) => Promise<Email>;
+}
+/**
+ * Better Auth email callbacks that send through coss.com. Each throws `CossSendError` when coss.com
+ * refuses the email.
+ *
+ * Auth emails go out with `category: "account"` and open and click tracking off: click tracking
+ * would route the secret links through coss.com's redirect.
+ */
+export declare function cossEmail(options: CossEmailOptions): CossEmail;
+/** The default templates: plain, unbranded, with a text version of each. */
+export declare const DEFAULT_TEMPLATES: CossEmailTemplates;
+//#endregion
+export { CossSendError };