coss 0.4.0 → 0.5.0

package/README.md

@@ -391,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 };

package/dist/better-auth.js

@@ -0,0 +1,269 @@
+import { c as CossSendError, l as lazyClient, o as sha256Hex, r as escapeHtml } from "./mime-C8bhhjvD.js";
+//#region src/better-auth.ts
+/**
+* `coss/better-auth`: Better Auth's email callbacks, sent through coss.com.
+*
+* ```ts
+* import { betterAuth } from "better-auth";
+* import { cossEmail } from "coss/better-auth";
+*
+* const email = cossEmail({ from: "Acme <auth@acme.com>", appName: "Acme" });
+*
+* export const auth = betterAuth({
+*   emailVerification: { sendVerificationEmail: email.sendVerificationEmail },
+*   emailAndPassword: { enabled: true, sendResetPassword: email.sendResetPassword },
+* });
+* ```
+*
+* The types here describe only what the callbacks read, so the SDK has no dependency on Better
+* Auth; `test/integration-types.ts` checks them against Better Auth's own.
+*/
+/**
+* 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.
+*/
+function cossEmail(options) {
+	const client = lazyClient("better-auth", options);
+	const templates = {
+		...DEFAULT_TEMPLATES,
+		...options.templates
+	};
+	const appName = options.appName?.trim() || void 0;
+	async function send(params, sendOptions) {
+		const result = await client().email.send({
+			category: options.category ?? "account",
+			tracking: {
+				opens: false,
+				clicks: false
+			},
+			...params,
+			from: params.from ?? options.from
+		}, sendOptions);
+		if (result.error) throw new CossSendError(result.error);
+		return result.data;
+	}
+	/**
+	* Sends one auth email. A link's token makes a stable idempotency key, so the same callback
+	* run twice sends once; the token itself is hashed, never sent as the key.
+	*/
+	async function sendAuthEmail(to, content, token) {
+		const idempotencyKey = token ? `better-auth_${await sha256Hex(token)}` : void 0;
+		await send({
+			to,
+			...content
+		}, { idempotencyKey });
+	}
+	return {
+		sendVerificationEmail: (data) => sendAuthEmail(data.user.email, templates.verifyEmail({
+			...data,
+			appName
+		}), data.token),
+		sendResetPassword: (data) => sendAuthEmail(data.user.email, templates.resetPassword({
+			...data,
+			appName
+		}), data.token),
+		sendChangeEmailConfirmation: (data) => sendAuthEmail(data.user.email, templates.changeEmailConfirmation({
+			...data,
+			appName
+		}), data.token),
+		sendDeleteAccountVerification: (data) => sendAuthEmail(data.user.email, templates.deleteAccount({
+			...data,
+			appName
+		}), data.token),
+		sendMagicLink: (data) => sendAuthEmail(data.email, templates.magicLink({
+			...data,
+			appName
+		}), data.token),
+		sendVerificationOTP: (data) => sendAuthEmail(data.email, templates.verificationOtp({
+			...data,
+			appName
+		})),
+		sendInvitationEmail: async (data) => {
+			if (!options.invitationUrl) throw new Error("coss/better-auth: sendInvitationEmail needs the `invitationUrl` option (Better Auth passes no URL for invitations).");
+			const url = options.invitationUrl(data);
+			await sendAuthEmail(data.email, templates.invitation({
+				...data,
+				url,
+				appName
+			}));
+		},
+		send
+	};
+}
+/** A plain, unbranded email: a heading, a paragraph, a button, and a closing line. */
+function layout(parts) {
+	const action = parts.action ? `<p style="margin:24px 0"><a href="${escapeHtml(parts.action.url)}" style="display:inline-block;padding:10px 18px;border-radius:6px;background:#111;color:#fff;text-decoration:none;font-weight:600">${escapeHtml(parts.action.label)}</a></p>
+<p style="color:#666;font-size:13px">Or paste this link into your browser:<br><a href="${escapeHtml(parts.action.url)}" style="color:#666;word-break:break-all">${escapeHtml(parts.action.url)}</a></p>` : "";
+	const code = parts.code ? `<p style="margin:24px 0;font-size:28px;letter-spacing:6px;font-weight:600;font-family:ui-monospace,Menlo,monospace">${escapeHtml(parts.code)}</p>` : "";
+	return `<!doctype html>
+<html><body style="margin:0;padding:24px;background:#fff;color:#111;font-family:-apple-system,BlinkMacSystemFont,'Segoe UI',Helvetica,Arial,sans-serif;font-size:15px;line-height:1.5">
+<div style="max-width:480px;margin:0 auto">
+<h1 style="font-size:20px;margin:0 0 16px">${escapeHtml(parts.heading)}</h1>
+<p>${escapeHtml(parts.intro)}</p>
+${action}${code}
+<p style="color:#666;font-size:13px">${escapeHtml(parts.outro)}</p>
+</div>
+</body></html>`;
+}
+function text(lines) {
+	return `${lines.filter((line) => line !== void 0).join("\n\n")}\n`;
+}
+const IGNORE = "If you didn't ask for this, you can ignore this email.";
+function on(appName) {
+	return appName ? ` on ${appName}` : "";
+}
+const OTP_SUBJECTS = {
+	"sign-in": "Your sign-in code",
+	"email-verification": "Your verification code",
+	"forget-password": "Your password reset code",
+	"change-email": "Your code to change your email address"
+};
+/** The default templates: plain, unbranded, with a text version of each. */
+const DEFAULT_TEMPLATES = {
+	verifyEmail: ({ url, appName }) => {
+		const intro = `Confirm this is your email address to finish setting up your account${on(appName)}.`;
+		return {
+			subject: "Verify your email address",
+			html: layout({
+				heading: "Verify your email address",
+				intro,
+				action: {
+					label: "Verify email",
+					url
+				},
+				outro: IGNORE
+			}),
+			text: text([
+				intro,
+				url,
+				IGNORE
+			])
+		};
+	},
+	resetPassword: ({ url, appName }) => {
+		const intro = `Someone asked to reset the password of your account${on(appName)}. Choose a new one with this link.`;
+		return {
+			subject: "Reset your password",
+			html: layout({
+				heading: "Reset your password",
+				intro,
+				action: {
+					label: "Reset password",
+					url
+				},
+				outro: `${IGNORE} Your password won't change.`
+			}),
+			text: text([
+				intro,
+				url,
+				`${IGNORE} Your password won't change.`
+			])
+		};
+	},
+	changeEmailConfirmation: ({ newEmail, url, appName }) => {
+		const intro = `Someone asked to change the email address of your account${on(appName)} to ${newEmail}. Confirm the change with this link.`;
+		return {
+			subject: "Confirm your new email address",
+			html: layout({
+				heading: "Confirm your new email address",
+				intro,
+				action: {
+					label: "Confirm change",
+					url
+				},
+				outro: IGNORE
+			}),
+			text: text([
+				intro,
+				url,
+				IGNORE
+			])
+		};
+	},
+	deleteAccount: ({ url, appName }) => {
+		const intro = `Someone asked to delete your account${on(appName)}. This can't be undone. Confirm with this link.`;
+		return {
+			subject: "Confirm account deletion",
+			html: layout({
+				heading: "Confirm account deletion",
+				intro,
+				action: {
+					label: "Delete my account",
+					url
+				},
+				outro: `${IGNORE} Your account stays as it is.`
+			}),
+			text: text([
+				intro,
+				url,
+				`${IGNORE} Your account stays as it is.`
+			])
+		};
+	},
+	magicLink: ({ url, appName }) => {
+		const heading = appName ? `Sign in to ${appName}` : "Sign in";
+		const intro = "Use this link to sign in. It works once and expires soon.";
+		return {
+			subject: heading,
+			html: layout({
+				heading,
+				intro,
+				action: {
+					label: "Sign in",
+					url
+				},
+				outro: IGNORE
+			}),
+			text: text([
+				intro,
+				url,
+				IGNORE
+			])
+		};
+	},
+	verificationOtp: ({ otp, type, appName }) => {
+		const subject = OTP_SUBJECTS[type] ?? "Your verification code";
+		const intro = `Enter this code${on(appName)}. It expires in a few minutes.`;
+		return {
+			subject,
+			html: layout({
+				heading: subject,
+				intro,
+				code: otp,
+				outro: IGNORE
+			}),
+			text: text([
+				intro,
+				otp,
+				IGNORE
+			])
+		};
+	},
+	invitation: ({ organization, inviter, url, appName }) => {
+		const who = inviter.user.name?.trim() || inviter.user.email;
+		const subject = `Join ${organization.name}${on(appName)}`;
+		const intro = `${who} invited you to join ${organization.name}${on(appName)}.`;
+		return {
+			subject,
+			html: layout({
+				heading: subject,
+				intro,
+				action: {
+					label: "Accept invitation",
+					url
+				},
+				outro: "If you weren't expecting this invitation, you can ignore this email."
+			}),
+			text: text([
+				intro,
+				url,
+				"If you weren't expecting this invitation, you can ignore this email."
+			])
+		};
+	}
+};
+//#endregion
+export { CossSendError, DEFAULT_TEMPLATES, cossEmail };