@ryusenkei/mail 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 RYUSENKEI
+
+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

@@ -1,3 +1,36 @@
-# Temporary Holding Version
+# @ryusenkei/mail
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The port for sending email: the `Mailer` interface, its error codes, an in-memory implementation, and a contract test. No runtime dependencies besides `@ryusenkei/core`. Implementations for a provider live in the `adapter-*` packages.
+
+## Install
+
+```sh
+pnpm add @ryusenkei/mail
+```
+
+## Interface
+
+`send({ from, to, replyTo?, subject, text, html? })` returns the provider message ID.
+
+- Business failures come back as `Result` with these codes: `invalid_input` (malformed address, or a line break in a header field, which blocks header injection), `rejected`
+- Infrastructure failures are thrown as `TransientError` (may succeed on retry) or `ConfigError` (a missing setting), from `@ryusenkei/core`
+
+`validateMail(mail)` is the shared input check. Every implementation runs it before sending.
+
+```ts
+const sent = await services.mailer.send({ from, to: [owner], subject, text });
+if (!sent.ok) log('warn', 'mail_rejected', { error: sent.error });
+```
+
+## Testing
+
+| Entry | Contents |
+| --- | --- |
+| `@ryusenkei/mail/testing` | `memoryMailer()`: keeps sent mail in `outbox`. For tests and local development; keep it out of production code |
+| `@ryusenkei/mail/contract` | `mailerContract(name, make, mail)`: the behavior every implementation must have, as Vitest tests. Run it against each adapter |
+
+The contract imports `vitest`, so it is a separate entry from the in-memory implementation, which local development can use without Vitest.
+
+## License
+
+MIT

package/dist/contract.d.ts

@@ -0,0 +1,6 @@
+import type { Mail, Mailer } from './index.ts';
+/**
+ * 実装が守る契約の試験（Vitest）
+ * @param mail 実装が送れる正しいメール（送信元は実装で使える値）
+ */
+export declare function mailerContract(name: string, make: () => Mailer, mail: Mail): void;

package/dist/contract.js

@@ -0,0 +1,22 @@
+import { describe, expect, it } from 'vitest';
+/**
+ * 実装が守る契約の試験（Vitest）
+ * @param mail 実装が送れる正しいメール（送信元は実装で使える値）
+ */
+export function mailerContract(name, make, mail) {
+    describe(`${name}: Mailer の契約`, () => {
+        it('正しいメールを送る', async () => {
+            expect((await make().send(mail)).ok).toBe(true);
+        });
+        it('ヘッダーに改行を含むメールは送らずに invalid_input', async () => {
+            const mailer = make();
+            expect(await mailer.send({ ...mail, subject: 'a\r\nBcc: x@example.com' })).toEqual({ ok: false, error: 'invalid_input' });
+            expect(await mailer.send({ ...mail, to: [{ email: 'x@example.com', name: 'a\nb' }] })).toEqual({ ok: false, error: 'invalid_input' });
+        });
+        it('宛先の形式の誤り・宛先なしは invalid_input', async () => {
+            const mailer = make();
+            expect(await mailer.send({ ...mail, to: [{ email: 'not-an-address' }] })).toEqual({ ok: false, error: 'invalid_input' });
+            expect(await mailer.send({ ...mail, to: [] })).toEqual({ ok: false, error: 'invalid_input' });
+        });
+    });
+}

package/dist/index.d.ts

@@ -0,0 +1,26 @@
+import { type Result } from '@ryusenkei/core';
+export type MailAddress = {
+    email: string;
+    name?: string;
+};
+export type Mail = {
+    from: MailAddress;
+    to: MailAddress[];
+    replyTo?: MailAddress;
+    subject: string;
+    text: string;
+    html?: string;
+};
+/**
+ * メール送信の業務の失敗
+ * - 基盤の失敗（送信の API の障害）は `TransientError`、送信元の未認証・binding の不足は `ConfigError` を投げる
+ */
+export type MailError = 'invalid_input' | 'rejected';
+/** メールの送信 */
+export interface Mailer {
+    send(mail: Mail): Promise<Result<{
+        id: string | undefined;
+    }, MailError>>;
+}
+/** 送信の前の入力の検査（実装は送る前にこれを通す） */
+export declare function validateMail(mail: Mail): Result<void, 'invalid_input'>;

package/dist/index.js

@@ -0,0 +1,15 @@
+import { err, ok } from '@ryusenkei/core';
+// `RFC 5322` の厳密な検査ではなく、明らかな誤りと改行・空白の混入だけを弾く
+const EMAIL = /^[^\s@<>()",;:]+@[^\s@<>()",;:]+\.[^\s@<>()",;:]+$/;
+const HEADER_BREAK = /[\r\n\u0000]/;
+/** 送信の前の入力の検査（実装は送る前にこれを通す） */
+export function validateMail(mail) {
+    const addresses = [mail.from, ...mail.to, ...(mail.replyTo ? [mail.replyTo] : [])];
+    if (!mail.to.length)
+        return err('invalid_input');
+    if (addresses.some((a) => !EMAIL.test(a.email) || (a.name !== undefined && HEADER_BREAK.test(a.name))))
+        return err('invalid_input');
+    if (HEADER_BREAK.test(mail.subject))
+        return err('invalid_input');
+    return ok();
+}

package/dist/testing.d.ts

@@ -0,0 +1,5 @@
+import { type Mail, type Mailer } from './index.ts';
+/** 送ったメールを `outbox` に溜めるメモリの実装（テストと dev 用） */
+export declare function memoryMailer(): Mailer & {
+    outbox: Mail[];
+};

package/dist/testing.js

@@ -0,0 +1,16 @@
+import { ok } from '@ryusenkei/core';
+import { validateMail } from "./index.js";
+/** 送ったメールを `outbox` に溜めるメモリの実装（テストと dev 用） */
+export function memoryMailer() {
+    const outbox = [];
+    return {
+        outbox,
+        async send(mail) {
+            const valid = validateMail(mail);
+            if (!valid.ok)
+                return valid;
+            outbox.push(mail);
+            return ok({ id: `memory-${outbox.length}` });
+        },
+    };
+}

package/package.json

@@ -1,6 +1,54 @@
 {
   "name": "@ryusenkei/mail",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "メール送信の差し込み口（型、エラーコード、入力の検査、メモリの実装、契約テスト）",
+  "license": "MIT",
+  "author": "RYUSENKEI",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ryusenkei-inc/toolkit.git",
+    "directory": "packages/runtime/mail"
+  },
+  "homepage": "https://github.com/ryusenkei-inc/toolkit/tree/main/packages/runtime/mail",
+  "type": "module",
+  "sideEffects": false,
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./testing": {
+      "types": "./dist/testing.d.ts",
+      "default": "./dist/testing.js"
+    },
+    "./contract": {
+      "types": "./dist/contract.d.ts",
+      "default": "./dist/contract.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@ryusenkei/core": "^0.1.0"
+  },
+  "peerDependencies": {
+    "vitest": ">=3"
+  },
+  "peerDependenciesMeta": {
+    "vitest": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "typescript": "^5.9.3"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit"
+  }
 }