coss 0.4.0 → 0.5.0

package/dist/integration-p3vtLNgq.d.ts

@@ -0,0 +1,35 @@
+import { Aa as CossError, Oa as FetchLike, t as Coss } from "./client-avnHVMry.js";
+//#region src/core/integration.d.ts
+/** How an integration reaches coss.com: a client of your own, or the options to create one. */
+interface IntegrationClientOptions {
+  /**
+   * A client to send with. When set, `apiKey`, `baseUrl` and `fetch` are ignored. Otherwise the
+   * integration creates its own client on first send, so a missing key fails the first send rather
+   * than your app's startup (or its build).
+   */
+  client?: Coss;
+  /** Defaults to the `COSS_API_KEY` env variable. */
+  apiKey?: string;
+  /** Defaults to the `COSS_BASE_URL` env variable, then `https://api.coss.com`. */
+  baseUrl?: string;
+  fetch?: FetchLike;
+}
+/**
+ * Thrown by the integrations when coss.com refuses or can't take an email. Integrations throw (unlike
+ * `coss.email.send`, which returns `{ data, error }`) because the libraries they plug into report
+ * failures that way. The API's error is on `error`.
+ */
+declare class CossSendError extends Error {
+  override readonly name = "CossSendError";
+  /** The `CossError` the API (or the client) returned. */
+  readonly error: CossError;
+  /** `error.code`, e.g. `domain_not_verified`. */
+  readonly code: string;
+  /** HTTP status, `null` for connection errors and timeouts. */
+  readonly status: number | null;
+  /** The API request id (`req_…`) to quote to support. */
+  readonly requestId: string | null;
+  constructor(error: CossError);
+}
+//#endregion
+export { IntegrationClientOptions as n, CossSendError as t };

package/dist/mime-C8bhhjvD.js

@@ -0,0 +1,152 @@
+import { n as INTEGRATION, t as Coss } from "./client-CCVBtkpV.js";
+//#region src/core/integration.ts
+/** Returns a getter for the client, created (and validated) the first time it is needed. */
+function lazyClient(integration, options, apiKey) {
+	let client = options.client;
+	return () => {
+		client ??= new Coss({
+			apiKey: apiKey?.() ?? options.apiKey,
+			baseUrl: options.baseUrl,
+			fetch: options.fetch,
+			[INTEGRATION]: integration
+		});
+		return client;
+	};
+}
+/**
+* Thrown by the integrations when coss.com refuses or can't take an email. Integrations throw (unlike
+* `coss.email.send`, which returns `{ data, error }`) because the libraries they plug into report
+* failures that way. The API's error is on `error`.
+*/
+var CossSendError = class extends Error {
+	name = "CossSendError";
+	/** The `CossError` the API (or the client) returned. */
+	error;
+	/** `error.code`, e.g. `domain_not_verified`. */
+	code;
+	/** HTTP status, `null` for connection errors and timeouts. */
+	status;
+	/** The API request id (`req_…`) to quote to support. */
+	requestId;
+	constructor(error) {
+		const issues = error.issues?.map((issue) => `${issue.path}: ${issue.message}`).join("; ");
+		super(`coss.com could not send the email: ${error.message} (${error.code})${issues ? ` ${issues}` : ""}`);
+		this.error = error;
+		this.code = error.code;
+		this.status = error.status;
+		this.requestId = error.request_id;
+	}
+};
+//#endregion
+//#region src/core/mime.ts
+/**
+* Helpers the integrations (`coss/nodemailer`, `coss/better-auth`, `coss/authjs`) share to turn a
+* framework's message into a `SendEmailParams`. No `node:*`: like the rest of the SDK this runs on
+* Node, Bun, Deno and Workers.
+*/
+/**
+* Headers the API refuses because coss.com or the provider sets them (`RESERVED_HEADERS` in
+* `packages/email/src/schemas.ts`, mirrored by hand; `apps/api/test/integrations-contract.test.ts`
+* sends every one). Mailers set several of these on every message, so they are dropped, not sent.
+*/
+const RESERVED_HEADERS = /* @__PURE__ */ new Set([
+	"from",
+	"to",
+	"cc",
+	"bcc",
+	"reply-to",
+	"subject",
+	"sender",
+	"return-path",
+	"date",
+	"message-id",
+	"mime-version",
+	"content-type",
+	"content-transfer-encoding",
+	"content-disposition",
+	"dkim-signature",
+	"received"
+]);
+/** Whether the API would refuse a custom header with this name. */
+function isReservedHeader(name) {
+	const lower = name.toLowerCase();
+	return RESERVED_HEADERS.has(lower) || lower.startsWith("x-ses-");
+}
+const NAME_SPECIALS = /["<>,;:@()[\]\\]/;
+/** `addr`, or `Name <addr>` with the name quoted when it needs to be. */
+function formatAddress(address, name) {
+	const trimmedName = name?.trim();
+	if (!trimmedName) return address;
+	return `${NAME_SPECIALS.test(trimmedName) ? `"${trimmedName.replace(/["\\]/g, "\\$&")}"` : trimmedName} <${address}>`;
+}
+const PRINTABLE_ASCII = /^[ -~]*$/;
+const ENCODED_WORD_BYTES = 45;
+/**
+* A header value as the API takes it: one line of printable ASCII. Folded lines are unfolded, and
+* anything non-ASCII becomes RFC 2047 encoded-words (`=?UTF-8?B?…?=`), which mail clients decode.
+*/
+function encodeHeaderValue(value) {
+	const unfolded = value.replace(/\r?\n[ \t]*/g, " ").replace(/\p{Cc}/gu, " ").trim();
+	if (PRINTABLE_ASCII.test(unfolded)) return unfolded;
+	const encoder = new TextEncoder();
+	const words = [];
+	let chunk = [];
+	for (const character of unfolded) {
+		const bytes = encoder.encode(character);
+		if (chunk.length + bytes.length > ENCODED_WORD_BYTES) {
+			words.push(`=?UTF-8?B?${toBase64(Uint8Array.from(chunk))}?=`);
+			chunk = [];
+		}
+		chunk.push(...bytes);
+	}
+	if (chunk.length > 0) words.push(`=?UTF-8?B?${toBase64(Uint8Array.from(chunk))}?=`);
+	return words.join(" ");
+}
+/**
+* Custom headers for the API: reserved ones dropped, values encoded, empty ones left out (the API
+* needs at least one character). Names are kept as given; the API treats them case-insensitively.
+* `undefined` when none is left.
+*/
+function customHeaders(entries) {
+	const headers = {};
+	let any = false;
+	for (const [name, value] of entries) {
+		const trimmedName = name.trim();
+		if (!trimmedName || isReservedHeader(trimmedName)) continue;
+		const encoded = encodeHeaderValue(value);
+		if (!encoded) continue;
+		headers[trimmedName] = encoded;
+		any = true;
+	}
+	return any ? headers : void 0;
+}
+const BASE64_CHUNK = 32768;
+/** Standard, padded base64 of `bytes`. */
+function toBase64(bytes) {
+	let binary = "";
+	for (let i = 0; i < bytes.length; i += BASE64_CHUNK) binary += String.fromCharCode(...bytes.subarray(i, i + BASE64_CHUNK));
+	return btoa(binary);
+}
+/** Base64 of a string's UTF-8 bytes. */
+function utf8ToBase64(value) {
+	return toBase64(new TextEncoder().encode(value));
+}
+/** `type/subtype` without parameters (`text/plain; charset=utf-8` → `text/plain`). */
+function mediaType(contentType) {
+	return contentType?.split(";")[0]?.trim().toLowerCase() || void 0;
+}
+/** A Content-ID without its angle brackets (`<logo@acme>` → `logo@acme`). */
+function bareContentId(cid) {
+	return cid?.trim().replace(/^<|>$/g, "") || void 0;
+}
+/** Hex SHA-256 of `value` (Web Crypto). */
+async function sha256Hex(value) {
+	const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(value));
+	return Array.from(new Uint8Array(digest), (byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+/** Escapes text for HTML element content and quoted attribute values. */
+function escapeHtml(value) {
+	return value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#39;");
+}
+//#endregion
+export { mediaType as a, CossSendError as c, formatAddress as i, lazyClient as l, customHeaders as n, sha256Hex as o, escapeHtml as r, utf8ToBase64 as s, bareContentId as t };

package/dist/nodemailer.d.ts

@@ -0,0 +1,75 @@
+import { Ci as Email, Ii as EmailTag, Ki as TrackingOptions } from "./client-avnHVMry.js";
+import { n as IntegrationClientOptions, t as CossSendError } from "./integration-p3vtLNgq.js";
+//#region src/nodemailer.d.ts
+/** coss.com settings for one message, passed as `coss` next to Nodemailer's own fields (see `withCoss`). */
+export interface CossMessageOptions {
+  /** What kind of email this is, e.g. `"marketing"`. Recipients suppressed for it are skipped. */
+  category?: string;
+  /** Merged with the transport's `tags`; a message tag replaces a transport tag of the same name. */
+  tags?: EmailTag[];
+  /** Send later: a `Date`, or an ISO 8601 date-time with an offset, at most 30 days ahead. */
+  scheduledAt?: Date | string;
+  tracking?: TrackingOptions;
+  /**
+   * Sent as `Idempotency-Key`: a retry with the same key never sends twice. Defaults to a random
+   * key per `sendMail` call (still reused by the client's own retries).
+   */
+  idempotencyKey?: string;
+}
+/** Options of `cossTransport`. The coss.com fields apply to every message unless the message sets them. */
+export interface CossTransportOptions extends IntegrationClientOptions {
+  category?: string;
+  tags?: EmailTag[];
+  tracking?: TrackingOptions;
+}
+/** What `sendMail` resolves with. */
+export interface CossSentMessageInfo {
+  /** The coss.com email id (`email_…`): look it up with `coss.email.get(id)` or in the dashboard. */
+  messageId: string;
+  envelope: {
+    from: string | false;
+    to: string[];
+  };
+  /** Every envelope recipient: coss.com took the email for all of them (or none, as an error). */
+  accepted: string[];
+  rejected: string[];
+  pending: string[];
+  /** e.g. `202 queued`. */
+  response: string;
+  /** The email as the API returned it. */
+  email: Email;
+}
+/** The parts of Nodemailer's `MailMessage` the transport reads. */
+export interface NodemailerMailMessage {
+  data: object;
+  message: {
+    getEnvelope(): {
+      from: string | false;
+      to: string[];
+    };
+  };
+  normalize(callback: (err: Error | null, data?: object) => void): void;
+}
+/** A Nodemailer transport (`nodemailer.createTransport(cossTransport())`). */
+export interface CossTransport {
+  name: string;
+  version: string;
+  send(mail: NodemailerMailMessage, callback: (err: Error | null, info?: CossSentMessageInfo) => void): void;
+  /** Checks the configuration (an API key is set) without sending anything. */
+  verify(callback?: (err: Error | null, success?: true) => void): Promise<true> | undefined;
+}
+/**
+ * Adds coss.com settings to a message. Use this rather than an inline `coss` field: Nodemailer's
+ * `SendMailOptions` type has no `coss` property, so an object literal with one doesn't typecheck.
+ *
+ * ```ts
+ * await transporter.sendMail(withCoss({ from, to, subject, html }, { category: "receipts" }));
+ * ```
+ */
+export declare function withCoss<T extends object>(mail: T, options: CossMessageOptions): T & {
+  coss: CossMessageOptions;
+};
+/** A Nodemailer transport that sends every message with `coss.email.send`. */
+export declare function cossTransport(options?: CossTransportOptions): CossTransport;
+//#endregion
+export { CossSendError };

package/dist/nodemailer.js

@@ -0,0 +1,193 @@
+import { r as VERSION } from "./client-CCVBtkpV.js";
+import { a as mediaType, c as CossSendError, i as formatAddress, l as lazyClient, n as customHeaders, s as utf8ToBase64, t as bareContentId } from "./mime-C8bhhjvD.js";
+//#region src/nodemailer.ts
+/**
+* Adds coss.com settings to a message. Use this rather than an inline `coss` field: Nodemailer's
+* `SendMailOptions` type has no `coss` property, so an object literal with one doesn't typecheck.
+*
+* ```ts
+* await transporter.sendMail(withCoss({ from, to, subject, html }, { category: "receipts" }));
+* ```
+*/
+function withCoss(mail, options) {
+	return {
+		...mail,
+		coss: options
+	};
+}
+/** A Nodemailer transport that sends every message with `coss.email.send`. */
+function cossTransport(options = {}) {
+	const client = lazyClient("nodemailer", options);
+	return {
+		name: "coss.com",
+		version: VERSION,
+		send(mail, callback) {
+			send(mail).then((info) => callback(null, info), (error) => callback(error instanceof Error ? error : new Error(String(error))));
+		},
+		verify(callback) {
+			const check = async () => {
+				client();
+				return true;
+			};
+			if (!callback) return check();
+			check().then((success) => callback(null, success), (error) => callback(error instanceof Error ? error : new Error(String(error))));
+		}
+	};
+	async function send(mail) {
+		const raw = mail.data;
+		unsupported(raw.raw, "`raw` messages", "build the message from its fields instead");
+		unsupported(raw.envelope, "a custom `envelope`", "coss.com sends to the message's recipients");
+		unsupported(raw.sender, "`sender`", "coss.com sets the Sender header itself");
+		unsupported(raw.amp, "AMP (`amp`) bodies", "send `html` and `text`");
+		unsupported(raw.watchHtml, "`watchHtml`", "send `html` and `text`");
+		if (Array.isArray(raw.alternatives) && raw.alternatives.length > 0) unsupported(true, "`alternatives`", "send `html`, `text` and attachments");
+		if (Array.isArray(raw.attachments) && raw.attachments.some(hasRawMime)) unsupported(true, "attachments with `raw` MIME", "give `content`, `path` or `href`");
+		const ownHeaders = messageHeaders(raw.headers);
+		const envelope = mail.message.getEnvelope();
+		const data = await new Promise((resolve, reject) => {
+			mail.normalize((err, normalized) => err ? reject(err) : resolve(normalized ?? {}));
+		});
+		const coss = data.coss ?? {};
+		const params = {
+			from: required(data.from ? addresses([data.from])[0] : void 0, "from"),
+			to: addresses(data.to),
+			subject: data.subject ?? ""
+		};
+		const cc = addresses(data.cc);
+		if (cc.length > 0) params.cc = cc;
+		const bcc = addresses(data.bcc);
+		if (bcc.length > 0) params.bcc = bcc;
+		const replyTo = addresses(data.replyTo);
+		if (replyTo.length > 0) params.reply_to = replyTo;
+		if (typeof data.html === "string" && data.html) params.html = data.html;
+		if (typeof data.text === "string" && data.text) params.text = data.text;
+		const attachments = (data.attachments ?? []).map(attachment);
+		if (data.icalEvent) attachments.push(icalAttachment(data.icalEvent));
+		if (attachments.length > 0) params.attachments = attachments;
+		const derived = Object.entries(data.normalizedHeaders ?? {}).filter(([name]) => !ownHeaders.names.has(name));
+		const headers = customHeaders([
+			...ownHeaders.entries,
+			...derived,
+			...priorityHeaders(data.priority),
+			...typeof data.xMailer === "string" ? [["X-Mailer", data.xMailer]] : []
+		]);
+		if (headers) params.headers = headers;
+		const category = coss.category ?? options.category;
+		if (category) params.category = category;
+		const tags = mergeTags(options.tags, coss.tags);
+		if (tags) params.tags = tags;
+		const tracking = coss.tracking ?? options.tracking;
+		if (tracking) params.tracking = tracking;
+		if (coss.scheduledAt) params.scheduled_at = coss.scheduledAt instanceof Date ? coss.scheduledAt.toISOString() : coss.scheduledAt;
+		const result = await client().email.send(params, { idempotencyKey: coss.idempotencyKey });
+		if (result.error) throw new CossSendError(result.error);
+		return {
+			messageId: result.data.id,
+			envelope: {
+				from: envelope.from,
+				to: envelope.to
+			},
+			accepted: [...envelope.to],
+			rejected: [],
+			pending: [],
+			response: `202 ${result.data.status}`,
+			email: result.data
+		};
+	}
+}
+function unsupported(value, what, instead) {
+	if (value === void 0 || value === null || value === false || value === "") return;
+	throw new Error(`coss/nodemailer: ${what} can't be sent through coss.com; ${instead}.`);
+}
+function hasRawMime(attachment) {
+	if (!attachment || typeof attachment !== "object" || !("raw" in attachment)) return false;
+	return attachment.raw !== void 0 && attachment.raw !== null && attachment.raw !== false;
+}
+function required(value, field) {
+	if (value === void 0) throw new Error(`coss/nodemailer: the message has no \`${field}\`.`);
+	return value;
+}
+/**
+* A message's `headers` (an object, or Nodemailer's `[{ key, value }]` array form) as name/value
+* pairs, plus the keys normalize() files them under. coss.com sends each header once, so one
+* given several values is refused rather than sent with only the first.
+*/
+function messageHeaders(headers) {
+	const entries = [];
+	const names = /* @__PURE__ */ new Set();
+	if (!headers || typeof headers !== "object") return {
+		entries,
+		names
+	};
+	const pairs = Array.isArray(headers) ? headers.map((entry) => [typeof entry?.key === "string" ? entry.key : "", entry?.value]) : Object.entries(headers);
+	for (const key of Object.keys(headers)) names.add(key);
+	const seen = /* @__PURE__ */ new Set();
+	for (const [name, given] of pairs) {
+		const values = (Array.isArray(given) ? given : [given]).map((value) => value && typeof value === "object" && "value" in value ? value.value : value).filter((value) => value !== void 0 && value !== null && value !== false && value !== "");
+		if (!name || values.length === 0) continue;
+		const lower = name.trim().toLowerCase();
+		if (values.length > 1 || seen.has(lower)) throw new Error(`coss/nodemailer: the \`${name}\` header is given more than once; coss.com sends each header once.`);
+		seen.add(lower);
+		entries.push([name, String(values[0])]);
+	}
+	return {
+		entries,
+		names
+	};
+}
+/** Parsed addresses (groups flattened) as `Name <addr>` strings. */
+function addresses(list) {
+	const out = [];
+	for (const entry of list ?? []) if (entry.group) out.push(...addresses(entry.group));
+	else if (entry.address) out.push(formatAddress(entry.address, entry.name));
+	return out;
+}
+function attachment(file, index) {
+	const params = {
+		filename: typeof file.filename === "string" ? file.filename : `attachment-${index + 1}`,
+		content: base64Content(file)
+	};
+	const contentType = mediaType(file.contentType);
+	if (contentType) params.content_type = contentType;
+	const contentId = bareContentId(file.cid);
+	if (contentId) params.content_id = contentId;
+	return params;
+}
+function icalAttachment(event) {
+	return {
+		filename: typeof event.filename === "string" ? event.filename : "invite.ics",
+		content: base64Content(event),
+		content_type: "text/calendar"
+	};
+}
+/** After normalize(), content is base64 (it was binary) or a UTF-8 string. */
+function base64Content(file) {
+	const content = file.content;
+	if (content === void 0 || content === null) return "";
+	if (typeof content !== "string") throw new Error("coss/nodemailer: an attachment's content could not be read.");
+	return file.encoding?.toLowerCase() === "base64" ? content.replace(/\s+/g, "") : utf8ToBase64(content);
+}
+/** The headers Nodemailer adds for `priority` (it adds them to the MIME tree, not `normalizedHeaders`). */
+function priorityHeaders(priority) {
+	switch (priority?.toLowerCase()) {
+		case "high": return [
+			["X-Priority", "1 (Highest)"],
+			["X-MSMail-Priority", "High"],
+			["Importance", "High"]
+		];
+		case "low": return [
+			["X-Priority", "5 (Lowest)"],
+			["X-MSMail-Priority", "Low"],
+			["Importance", "Low"]
+		];
+		default: return [];
+	}
+}
+function mergeTags(defaults, message) {
+	if (!defaults?.length && !message?.length) return void 0;
+	const byName = /* @__PURE__ */ new Map();
+	for (const tag of [...defaults ?? [], ...message ?? []]) byName.set(tag.name, tag);
+	return [...byName.values()];
+}
+//#endregion
+export { CossSendError, cossTransport, withCoss };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "coss",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "The official TypeScript SDK for coss.com: email, SMS, video, scheduling and more behind one API key.",
   "license": "MIT",
   "homepage": "https://coss.com/docs",
@@ -23,7 +23,10 @@
   "types": "./dist/index.d.ts",
   "exports": {
     ".": "./dist/index.js",
+    "./authjs": "./dist/authjs.js",
+    "./better-auth": "./dist/better-auth.js",
     "./device": "./dist/device.js",
+    "./nodemailer": "./dist/nodemailer.js",
     "./package.json": "./package.json"
   },
   "scripts": {
@@ -32,18 +35,33 @@
     "test": "bun test"
   },
   "peerDependencies": {
-    "@react-email/render": "^1.0.0 || ^2.0.0"
+    "@auth/core": ">=0.37.0",
+    "@react-email/render": "^1.0.0 || ^2.0.0",
+    "better-auth": ">=1.0.0",
+    "nodemailer": ">=6.9.0"
   },
   "peerDependenciesMeta": {
+    "@auth/core": {
+      "optional": true
+    },
     "@react-email/render": {
       "optional": true
+    },
+    "better-auth": {
+      "optional": true
+    },
+    "nodemailer": {
+      "optional": true
     }
   },
   "devDependencies": {
     "@arethetypeswrong/core": "0.18.5",
+    "@auth/core": "0.41.3",
     "@react-email/render": "2.1.0",
     "@types/bun": "1.4.2",
     "@types/react": "19.3.0",
+    "better-auth": "1.7.7",
+    "nodemailer": "10.0.13",
     "publint": "0.3.25",
     "react": "19.3.0",
     "react-dom": "19.3.0",