@betternotify/selligent 1.0.0-beta.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Better-Notify contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,104 @@
+# @betternotify/selligent
+
+[Selligent (Marigold Engage)](https://www.marigold.com/products/marigold-engage) transactional email transport for [Better-Notify](https://github.com/better-notify/better-notify). Delivers rendered emails through the Selligent Delivery Cloud (SDC) `POST /email/v1/messages/send` API.
+
+<p>
+  <a href="https://better-notify.com">Website</a> ·
+  <a href="https://better-notify.com/docs">Docs</a> ·
+  <a href="https://github.com/better-notify/better-notify">GitHub</a> ·
+  <a href="https://x.com/better_notify">X</a>
+</p>
+
+## Install
+
+```sh
+npm install @betternotify/selligent @betternotify/core @betternotify/email
+```
+
+## Usage
+
+```ts
+import { createNotify, createClient } from '@betternotify/core';
+import { emailChannel } from '@betternotify/email';
+import { selligentTransport } from '@betternotify/selligent';
+
+const email = emailChannel({
+  defaults: { from: { name: 'My App', email: 'noreply@example.com' } },
+});
+
+const rpc = createNotify({ channels: { email } });
+const catalog = rpc.catalog({
+  /* routes */
+});
+
+const mail = createClient({
+  catalog,
+  channels: { email },
+  transportsByChannel: {
+    email: selligentTransport({
+      clientId: Number(process.env.SELLIGENT_CLIENT_ID!),
+      clientSecret: process.env.SELLIGENT_CLIENT_SECRET!,
+      accountId: process.env.SELLIGENT_ACCOUNT_ID!,
+    }),
+  },
+});
+```
+
+Alternatively, if you already manage OAuth tokens externally:
+
+```ts
+selligentTransport({
+  getAccessToken: () => myTokenManager.getToken(),
+});
+```
+
+## Options
+
+| Field          | Type       | Description                                                                          |
+| -------------- | ---------- | ------------------------------------------------------------------------------------ |
+| `clientId`     | `number`   | Selligent OAuth client ID. Required (unless using `getAccessToken`).                 |
+| `clientSecret` | `string`   | Selligent OAuth client secret. Required (unless using `getAccessToken`).             |
+| `accountId`    | `string`   | Selligent account ID. Required (unless using `getAccessToken`).                      |
+| `getAccessToken` | `() => Promise<string>` | Provide your own token. Mutually exclusive with OAuth credentials.   |
+| `baseUrl`      | `string`   | Override the SDC API base URL. Defaults to `https://sdc.slgnt.eu`.                   |
+| `authUrl`      | `string`   | Override the OAuth token endpoint. Defaults to `https://auth.slgnt.eu/oauth/token`.  |
+| `audience`     | `string`   | Override the OAuth audience. Defaults to `https://sdc.slgnt.eu`.                     |
+| `logger`       | `object`   | Optional `LoggerLike`. Defaults to `consoleLogger()`.                                |
+| `http`         | `object`   | HTTP behavior options (retry, timeout, hooks).                                       |
+
+## Authentication
+
+Unlike API-key-based transports, Selligent uses **OAuth 2.0 client credentials**. The transport handles token management automatically — it fetches a token before the first send, caches it, and refreshes it when it's about to expire (within 60 seconds of expiry).
+
+The `verify()` method tests credentials by attempting a token fetch without sending any email.
+
+## Per-send overrides
+
+Pass Selligent-specific fields per-send via the `transport` key in `.send()`:
+
+```ts
+await mail.welcome.send({
+  to: 'user@example.com',
+  input: { name: 'Jane' },
+  transport: {
+    selligent: {
+      profile: 'crm-id-123',
+      tags: ['campaign-spring'],
+      metadata: '{"ref": 123}',
+      list_unsubscribe: '<https://example.com/unsub>',
+      custom_send_time: '2025-09-02T12:00:00',
+      time_to_live: 'P2D',
+    },
+  },
+});
+```
+
+## Caveats
+
+SDC sends message content without any modifications — it does not inject tracking pixels or rewrite links. Open/click tracking must be implemented by the sender.
+
+The following `RenderedMessage` fields are not part of SDC's send schema and are silently dropped: `cc`, `bcc`, custom `headers`, `tags`, `priority`, and `inlineAssets`.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,84 @@
+import { LoggerLike } from "@betternotify/core";
+import { HttpClientBehaviorOptions } from "@betternotify/core/transports";
+import * as _betternotify_email0 from "@betternotify/email";
+
+//#region src/types.d.ts
+type SelligentOAuthCredentials = {
+  clientId: number;
+  clientSecret: string;
+  accountId: string;
+};
+type SelligentTransportOptions = {
+  baseUrl?: string;
+  authUrl?: string;
+  audience?: string;
+  logger?: LoggerLike;
+  http?: HttpClientBehaviorOptions;
+} & (SelligentOAuthCredentials | {
+  getAccessToken: () => Promise<string>;
+});
+type SelligentAddress = {
+  alias: string;
+  address: string;
+};
+type SelligentAttachment = {
+  file_name: string;
+  data: string;
+  mime_type: string;
+};
+type SelligentMessageContext = {
+  profile: string;
+  tags?: string[];
+  metadata?: string;
+};
+type SelligentMessageItem = {
+  reference: string;
+  content: {
+    html: string;
+    text?: string;
+    attachments?: SelligentAttachment[];
+  };
+  headers: {
+    subject: string;
+    to: SelligentAddress;
+    from: SelligentAddress;
+    reply?: SelligentAddress;
+    list_unsubscribe?: string;
+  };
+  context: SelligentMessageContext;
+  custom_send_time?: string;
+  time_to_live?: string;
+};
+type SelligentTokenResponse = {
+  access_token: string;
+  token_type: string;
+  refresh_token: string;
+  scope: string;
+  expires_in: number;
+};
+type SelligentErrorResponse = {
+  error_message?: string;
+};
+type SelligentPerSendData = {
+  profile?: string;
+  tags?: string[];
+  metadata?: string;
+  reference?: string;
+  list_unsubscribe?: string;
+  custom_send_time?: string;
+  time_to_live?: string;
+};
+//#endregion
+//#region src/is-retriable.d.ts
+declare const isSelligentRetriable: (err: unknown) => boolean;
+//#endregion
+//#region src/index.d.ts
+declare module '@betternotify/core' {
+  interface TransportDataMap {
+    selligent: SelligentPerSendData;
+  }
+}
+/** @experimental Selligent (Marigold Engage) transport using the SDC transactional email API. */
+declare const selligentTransport: (opts: SelligentTransportOptions) => _betternotify_email0.Transport;
+//#endregion
+export { type SelligentAddress, type SelligentAttachment, type SelligentErrorResponse, type SelligentMessageContext, type SelligentMessageItem, type SelligentOAuthCredentials, type SelligentPerSendData, type SelligentTokenResponse, type SelligentTransportOptions, isSelligentRetriable, selligentTransport };

package/dist/index.js

@@ -0,0 +1,205 @@
+import { createTransport, normalizeAddress } from "@betternotify/email/transports";
+import { NotifyRpcError, NotifyRpcProviderError, consoleLogger, handlePromise } from "@betternotify/core";
+import { createHttpClient, mapHttpStatus } from "@betternotify/core/transports";
+//#region src/is-retriable.ts
+const isSelligentRetriable = (err) => {
+	if (err instanceof NotifyRpcProviderError) return err.retriable;
+	return true;
+};
+//#endregion
+//#region src/index.ts
+const DEFAULT_BASE_URL = "https://sdc.slgnt.eu";
+const DEFAULT_AUTH_URL = "https://auth.slgnt.eu/oauth/token";
+const DEFAULT_AUDIENCE = "https://sdc.slgnt.eu";
+const DEFAULT_TIMEOUT_MS = 3e4;
+const TOKEN_REFRESH_BUFFER_MS = 6e4;
+const toBase64 = (content) => {
+	if (Buffer.isBuffer(content)) return content.toString("base64");
+	return Buffer.from(content).toString("base64");
+};
+const toSelligentAddress = (addr) => {
+	if (typeof addr === "string") return {
+		alias: "",
+		address: addr
+	};
+	return {
+		alias: addr.name ?? "",
+		address: addr.email
+	};
+};
+const toAttachments = (attachments) => attachments.map((att) => ({
+	file_name: att.filename,
+	data: toBase64(att.content),
+	mime_type: att.contentType ?? "application/octet-stream"
+}));
+const hasOAuthCredentials = (opts) => "clientId" in opts;
+const createTokenManager = (opts) => {
+	if (!hasOAuthCredentials(opts)) return { getToken: opts.getAccessToken };
+	const authUrl = opts.authUrl ?? DEFAULT_AUTH_URL;
+	const audience = opts.audience ?? DEFAULT_AUDIENCE;
+	let cachedToken;
+	let expiresAt = 0;
+	const getToken = async () => {
+		if (cachedToken && Date.now() < expiresAt - TOKEN_REFRESH_BUFFER_MS) return cachedToken;
+		const res = await fetch(authUrl, {
+			method: "POST",
+			headers: { "Content-Type": "application/json" },
+			body: JSON.stringify({
+				client_id: opts.clientId,
+				client_secret: opts.clientSecret,
+				account_id: opts.accountId,
+				grant_type: "client_credentials",
+				audience
+			})
+		});
+		if (!res.ok) {
+			const [, body] = await handlePromise(res.text());
+			throw new NotifyRpcProviderError({
+				message: `Selligent transport: OAuth token request failed [${res.status}]${body ? `: ${body}` : ""}`,
+				code: "CONFIG",
+				provider: "selligent",
+				httpStatus: res.status,
+				retriable: res.status >= 500
+			});
+		}
+		const data = await res.json();
+		cachedToken = data.access_token;
+		expiresAt = Date.now() + data.expires_in * 1e3;
+		return cachedToken;
+	};
+	return { getToken };
+};
+const buildMessageItems = (message, from, ctx, perSend) => message.to.map((to, i) => {
+	const item = {
+		reference: perSend?.reference ?? `${ctx.messageId}-${i}`,
+		content: { html: message.html },
+		headers: {
+			subject: message.subject,
+			to: toSelligentAddress(to),
+			from: toSelligentAddress(from)
+		},
+		context: { profile: perSend?.profile ?? normalizeAddress(to) }
+	};
+	if (message.text) item.content.text = message.text;
+	if (message.attachments?.length) item.content.attachments = toAttachments(message.attachments);
+	if (message.replyTo) item.headers.reply = toSelligentAddress(message.replyTo);
+	if (perSend?.list_unsubscribe) item.headers.list_unsubscribe = perSend.list_unsubscribe;
+	if (perSend?.tags) item.context.tags = perSend.tags;
+	if (perSend?.metadata) item.context.metadata = perSend.metadata;
+	if (perSend?.custom_send_time) item.custom_send_time = perSend.custom_send_time;
+	if (perSend?.time_to_live) item.time_to_live = perSend.time_to_live;
+	return item;
+});
+/** @experimental Selligent (Marigold Engage) transport using the SDC transactional email API. */
+const selligentTransport = (opts) => {
+	const url = `${(opts.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "")}/email/v1/messages/send`;
+	const log = (opts.logger ?? consoleLogger()).child({ component: "selligent" });
+	const http = createHttpClient({
+		...opts.http,
+		timeoutMs: opts.http?.timeoutMs ?? DEFAULT_TIMEOUT_MS
+	});
+	const tokenManager = createTokenManager(opts);
+	return createTransport({
+		name: "selligent",
+		async verify() {
+			const [err, token] = await handlePromise(tokenManager.getToken());
+			if (err) return {
+				ok: false,
+				details: err.message
+			};
+			return {
+				ok: true,
+				details: { tokenLength: token.length }
+			};
+		},
+		async send(message, ctx) {
+			if (!message.from) throw new NotifyRpcError({
+				message: "Selligent transport: no \"from\" address. Set it on the channel default, route `.from()` resolver, or per-call args.",
+				code: "CONFIG",
+				route: ctx.route,
+				messageId: ctx.messageId
+			});
+			const [tokenErr, token] = await handlePromise(tokenManager.getToken());
+			if (tokenErr) {
+				if (tokenErr instanceof NotifyRpcProviderError) return {
+					ok: false,
+					error: tokenErr
+				};
+				return {
+					ok: false,
+					error: new NotifyRpcProviderError({
+						message: `Selligent transport: failed to obtain access token: ${tokenErr.message}`,
+						code: "CONFIG",
+						provider: "selligent",
+						retriable: true,
+						route: ctx.route,
+						messageId: ctx.messageId,
+						cause: tokenErr
+					})
+				};
+			}
+			const perSend = ctx.transport?.selligent;
+			const items = buildMessageItems(message, message.from, ctx, perSend);
+			const result = await http.request(url, {
+				method: "POST",
+				headers: {
+					Authorization: `Bearer ${token}`,
+					"Content-Type": "application/json"
+				},
+				body: JSON.stringify(items)
+			});
+			if (!result.ok) {
+				if (result.kind === "network") {
+					log.error("Selligent fetch failed", {
+						err: result.cause,
+						route: ctx.route
+					});
+					return {
+						ok: false,
+						error: new NotifyRpcProviderError({
+							message: `Selligent transport: ${result.timedOut ? "request timed out" : `network error: ${result.cause.message}`}`,
+							code: result.timedOut ? "TIMEOUT" : "PROVIDER",
+							provider: "selligent",
+							retriable: true,
+							route: ctx.route,
+							messageId: ctx.messageId,
+							cause: result.cause
+						})
+					};
+				}
+				const errData = result.body ?? {};
+				const { code, retriable } = mapHttpStatus(result.status);
+				const errorMessage = `Selligent transport: [${result.status}] ${errData.error_message ?? "request failed"}`;
+				log.error(errorMessage, {
+					err: {
+						status: result.status,
+						body: errData
+					},
+					route: ctx.route
+				});
+				return {
+					ok: false,
+					error: new NotifyRpcProviderError({
+						message: errorMessage,
+						code,
+						provider: "selligent",
+						httpStatus: result.status,
+						retriable,
+						route: ctx.route,
+						messageId: ctx.messageId
+					})
+				};
+			}
+			return {
+				ok: true,
+				data: {
+					accepted: message.to.map(normalizeAddress),
+					rejected: [],
+					raw: items
+				}
+			};
+		}
+	});
+};
+//#endregion
+export { isSelligentRetriable, selligentTransport };

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@betternotify/selligent",
+  "version": "1.0.0-beta.1",
+  "description": "Selligent (Marigold Engage) transactional email transport for Better-Notify.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/better-notify/better-notify",
+    "directory": "packages/selligent"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "@betternotify/core": "1.0.0-beta.4",
+    "@betternotify/email": "1.0.0-beta.2"
+  },
+  "devDependencies": {
+    "rolldown": "1.0.0",
+    "typescript": "6.0.3",
+    "vitest": "2.1.9",
+    "@internal/rolldown-config": "0.0.0",
+    "@internal/tsconfig": "0.0.0"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "build": "NODE_OPTIONS='--import tsx/esm' rolldown -c",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  }
+}