chore: add changeset

.changeset/famous-dragons-build.md

@@ -0,0 +1,7 @@
+---
+"@logto/connector-http-email": minor
+---
+
+add HTTP email connector
+
+The HTTP email connector allows you to send emails via HTTP call. To use the HTTP email connector, you'll need to have your own email service that expose an HTTP API for sending emails. Logto will call this API when it needs to send an email. For example, when a user registers, Logto will call the HTTP API to send a verification email.

packages/connectors/connector-http-email/README.md

@@ -0,0 +1,27 @@
+# HTTP email connector
+
+The official Logto connector for HTTP email.
+
+## Get started
+
+The HTTP email connector allows you to send emails via HTTP call. To use the HTTP email connector, you'll need to have your own email service that expose an HTTP API for sending emails. Logto will call this API when it needs to send an email. For example, when a user registers, Logto will call the HTTP API to send a verification email.
+
+## Set up HTTP email connector
+
+To use the HTTP email connector, you need to set up an HTTP endpoint that Logto can call. And an optional authorization token for the endpoint.
+
+## Payload
+
+The HTTP email connector will send the following payload to the endpoint when it needs to send an email:
+
+```json
+{
+ "to": "foo@logto.io",
+ "type": "SignIn",
+ "payload": {
+ "code": "123456"
+ }
+}
+```
+
+You can find the type definition of `SendMessageData` in [connector-kit](../../toolkit/connector-kit/src/types/passwordless.ts).

packages/connectors/connector-http-email/package.json

@@ -0,0 +1,68 @@
+{
+ "name": "@logto/connector-http-email",
+ "version": "0.1.0",
+ "description": "Email connector to send email via HTTP call.",
+ "author": "Silverhand Inc. <contact@silverhand.io>",
+ "dependencies": {
+ "@logto/connector-kit": "workspace:^4.0.0",
+ "@silverhand/essentials": "^2.9.1",
+ "got": "^14.0.0",
+ "zod": "^3.23.8"
+ },
+ "main": "./lib/index.js",
+ "module": "./lib/index.js",
+ "exports": "./lib/index.js",
+ "license": "MPL-2.0",
+ "type": "module",
+ "files": [
+ "lib",
+ "docs",
+ "logo.svg",
+ "logo-dark.svg"
+ ],
+ "scripts": {
+ "precommit": "lint-staged",
+ "check": "tsc --noEmit",
+ "build": "tsup",
+ "dev": "tsup --watch",
+ "lint": "eslint --ext .ts src",
+ "lint:report": "pnpm lint --format json --output-file report.json",
+ "test": "vitest src",
+ "test:ci": "pnpm run test --silent --coverage",
+ "prepublishOnly": "pnpm build"
+ },
+ "engines": {
+ "node": "^20.9.0"
+ },
+ "eslintConfig": {
+ "extends": "@silverhand",
+ "settings": {
+ "import/core-modules": [
+ "@silverhand/essentials",
+ "got",
+ "nock",
+ "snakecase-keys",
+ "zod"
+ ]
+ }
+ },
+ "prettier": "@silverhand/eslint-config/.prettierrc",
+ "publishConfig": {
+ "access": "public"
+ },
+ "devDependencies": {
+ "@silverhand/eslint-config": "6.0.1",
+ "@silverhand/ts-config": "6.0.0",
+ "@types/node": "^20.11.20",
+ "@types/supertest": "^6.0.2",
+ "@vitest/coverage-v8": "^2.0.0",
+ "eslint": "^8.56.0",
+ "lint-staged": "^15.0.2",
+ "nock": "^13.3.1",
+ "prettier": "^3.0.0",
+ "supertest": "^7.0.0",
+ "tsup": "^8.1.0",
+ "typescript": "^5.5.3",
+ "vitest": "^2.0.0"
+ }
+}

packages/connectors/connector-http-email/src/constant.ts

@@ -0,0 +1,33 @@
+import type { ConnectorMetadata } from '@logto/connector-kit';
+import { ConnectorConfigFormItemType } from '@logto/connector-kit';
+
+export const defaultMetadata: ConnectorMetadata = {
+ id: 'http-email-service',
+ target: 'http-mail',
+ platform: null,
+ name: {
+ en: 'HTTP Email',
+ },
+ logo: './logo.svg',
+ logoDark: null,
+ description: {
+ en: 'Send email via HTTP call.',
+ },
+ readme: './README.md',
+ formItems: [
+ {
+ key: 'endpoint',
+ label: 'Endpoint',
+ type: ConnectorConfigFormItemType.Text,
+ required: true,
+ placeholder: '<https://example.com/your-http-endpoint>',
+ },
+ {
+ key: 'authorization',
+ label: 'Authorization Header',
+ type: ConnectorConfigFormItemType.Text,
+ required: false,
+ placeholder: '<Bearer your-token>',
+ },
+ ],
+};

packages/connectors/connector-http-email/src/index.test.ts

@@ -0,0 +1,47 @@
+import nock from 'nock';
+
+import { TemplateType } from '@logto/connector-kit';
+
+import createConnector from './index.js';
+import { mockedConfig } from './mock.js';
+
+const getConfig = vi.fn().mockResolvedValue(mockedConfig);
+
+describe('HTTP email connector', () => {
+ afterEach(() => {
+ nock.cleanAll();
+ });
+
+ it('should init without throwing errors', async () => {
+ await expect(createConnector({ getConfig })).resolves.not.toThrow();
+ });
+
+ it('should call endpoint with correct parameters', async () => {
+ const url = new URL(mockedConfig.endpoint);
+ const mockPost = nock(url.origin)
+ .post(url.pathname, (body) => {
+ expect(body).toMatchObject({
+ to: 'foo@logto.io',
+ type: TemplateType.SignIn,
+ payload: {
+ code: '123456',
+ },
+ });
+ return true;
+ })
+ .reply(200, {
+ message: 'Email sent successfully',
+ });
+
+ const connector = await createConnector({ getConfig });
+ await connector.sendMessage({
+ to: 'foo@logto.io',
+ type: TemplateType.SignIn,
+ payload: {
+ code: '123456',
+ },
+ });
+
+ expect(mockPost.isDone()).toBe(true);
+ });
+});

packages/connectors/connector-http-email/src/index.ts

@@ -0,0 +1,70 @@
+import { assert } from '@silverhand/essentials';
+import { got, HTTPError } from 'got';
+
+import type {
+ GetConnectorConfig,
+ SendMessageFunction,
+ CreateConnector,
+ EmailConnector,
+} from '@logto/connector-kit';
+import {
+ ConnectorError,
+ ConnectorErrorCodes,
+ validateConfig,
+ ConnectorType,
+} from '@logto/connector-kit';
+
+import { defaultMetadata } from './constant.js';
+import { httpMailConfigGuard } from './types.js';
+
+const sendMessage =
+ (getConfig: GetConnectorConfig): SendMessageFunction =>
+ async (data, inputConfig) => {
+ const { to, type, payload } = data;
+ const config = inputConfig ?? (await getConfig(defaultMetadata.id));
+ validateConfig(config, httpMailConfigGuard);
+ const { endpoint, authorization } = config;
+
+ try {
+ return await got.post(endpoint, {
+ headers: {
+ Authorization: authorization,
+ 'Content-Type': 'application/json',
+ },
+ json: {
+ to,
+ type,
+ payload,
+ },
+ });
+ } catch (error: unknown) {
+ if (error instanceof HTTPError) {
+ const {
+ response: { body: rawBody },
+ } = error;
+
+ assert(
+ typeof rawBody === 'string',
+ new ConnectorError(
+ ConnectorErrorCodes.InvalidResponse,
+ `Invalid response raw body type: ${typeof rawBody}`
+ )
+ );
+
+ throw new ConnectorError(ConnectorErrorCodes.General, rawBody);
+ }
+
+ throw new ConnectorError(ConnectorErrorCodes.General, error);
+ }
+ };
+
+const createHttpMailConnector: CreateConnector<EmailConnector> = async ({ getConfig }) => {
+ return {
+ metadata: defaultMetadata,
+ type: ConnectorType.Email,
+ configGuard: httpMailConfigGuard,
+ sendMessage: sendMessage(getConfig),
+ };
+};
+
+export default createHttpMailConnector;

packages/connectors/connector-http-email/src/mock.ts

@@ -0,0 +1,6 @@
+import type { HttpMailConfig } from './types.js';
+
+export const mockedConfig: HttpMailConfig = {
+ endpoint: 'https://example.com/your-http-endpoint',
+ authorization: 'SampleToken',
+};

packages/connectors/connector-http-email/src/types.ts

@@ -0,0 +1,8 @@
+import { z } from 'zod';
+
+export const httpMailConfigGuard = z.object({
+ endpoint: z.string(),
+ authorization: z.string().optional(),
+});
+
+export type HttpMailConfig = z.infer<typeof httpMailConfigGuard>;