@house-rules/email 0.0.0-stage → 0.1.1

package/AGENTS.md

@@ -0,0 +1,37 @@
+# @house-rules/email: notes for agents
+
+## What it does
+
+Email sends messages through the `EmailSender` port. It owns no data, migrations, tables or event kinds. It does not depend on event-log or look up actors. Callers supply recipient, content and an idempotency key.
+
+## How an app mounts it
+
+Mount `EmailMount` with `Email.layer` in composition/modules.ts. Provide exactly one adapter to the facade layer:
+
+```ts
+Email.layer.pipe(
+  Layer.provide(consoleEmail({ defaultFrom: "noreply@example.test" })),
+)
+// Tests may use memoryEmail({ defaultFrom: "noreply@example.test" }) instead.
+```
+
+The main door exports `Email`, `bindEmail`, `EmailMount`, `EmailSender` and adapters. The browser-safe `./contract` door exports message/result schemas, errors, `EmailPermissions.send` (`email:send`) and `EmailOperations.send` (`Email.send`). It exports no services, bindings or adapters.
+
+`Email.send` takes `{ message, idempotencyKey }` and returns `{ providerId? }`. Only system callers may send. A person is refused with `EmailCallerDenied` (`forbidden`), even with `email:send`. Email has no not-found concept. The operation is not transactional and opens no unit. A delivery feature must pass the same idempotency key on retries; a surrounding database rollback cannot undo a sent email.
+
+The facade captures `EmailSender` once. Its `send(message, idempotencyKey)` delegates to `EmailSender.send`, which accepts a flat `EmailDelivery`: `to`, optional `from`, `subject`, `text`, optional `html`, `idempotencyKey` and optional headers. A missing `from` uses the required `defaultFrom`. An explicit blank `from`, blank required text or blank default sender fails with `EmailRejected` (`invalid`). CR/LF is rejected in recipients, sender addresses, subject, and header names and values. Message bodies may contain line breaks.
+
+Adapter or provider availability failures use `EmailSendFailed` (`unavailable`) with fixed public text "Email sending is unavailable." Its optional internal `cause` keeps provider diagnostics out of the public message. Never copy those diagnostics into public wording.
+
+The console adapter logs only a summary. It never logs addresses, subject, headers, or message bodies. This also prevents disclosure of mandatory security mail bodies. The memory adapter is for tests and exposes `MemoryEmailOutboxTesting`; it keeps the first message for each `idempotencyKey`.
+
+A future SMTP or API-provider adapter implements `EmailSender` and is chosen by the app owner. No provider or dependency is selected here. The adapter must pass `idempotencyKey` through when the provider supports it. Plain SMTP has no standard idempotency support, so a retry can duplicate a message.
+
+No `migrations.json` entry is needed. The pull-out test removes the email mount, its adapter layer and the app's email delivery edge without changing other modules.
+
+## Fixed rules
+
+- Keep app-specific content and provider dependencies out of this package's domain boundary.
+- Never log full email bodies or sensitive message metadata.
+- Keep public unavailable messages fixed and provider diagnostics private.
+- No database, migrations, event-log dependency or actor lookup belongs here.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jakub Szwajka
+
+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,22 @@
-# Temporary Holding Version
+# @house-rules/email
 
-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.
+A provider-neutral email sender port with development console and test memory adapters. It owns no data.
+
+Mount `EmailMount` in composition and provide one adapter to the facade:
+
+```ts
+import { consoleEmail, Email } from "@house-rules/email";
+import { Layer } from "effect";
+
+const emailLayer = Email.layer.pipe(
+  Layer.provide(consoleEmail({ defaultFrom: "noreply@example.test" })),
+);
+```
+
+The browser-safe `@house-rules/email/contract` exports `EmailOperations.send` (`Email.send`) and `EmailPermissions.send` (`email:send`). A feature calls it with `{ message, idempotencyKey }` and receives `{ providerId? }`. The operation accepts system callers only; people receive `EmailCallerDenied`, even if they hold the permission. It writes no unit or data. Retry with the same key because a sent email cannot roll back with a database transaction.
+
+`EmailSender.send` takes a flat `EmailDelivery`: recipient, optional sender, subject, text body, optional HTML body, optional headers, and a required idempotency key. `EmailRejected` represents invalid input, including explicit blank senders and CR/LF in addresses, subject or headers. `EmailSendFailed` is an unavailable failure with fixed public wording and an optional internal `cause` for provider diagnostics.
+
+Console output contains only a redacted summary. The memory adapter exposes an inspectable test outbox and deduplicates by idempotency key. There is no SMTP or API provider adapter yet. A provider choice and dependency require owner approval. Provider adapters should forward idempotency keys when supported.
+
+See [AGENTS.md](./AGENTS.md) for mounting rules and adapter constraints.

package/dist/adapters/console.d.ts

@@ -0,0 +1,3 @@
+import { Layer } from "effect";
+import { EmailSender, type EmailSenderOptions } from "../sender/email-sender.ts";
+export declare const console: (options: EmailSenderOptions) => Layer.Layer<EmailSender, never, never>;

package/dist/adapters/console.js

@@ -0,0 +1,14 @@
+import { Effect, Layer } from "effect";
+import { EmailSender, validateEmail } from "../sender/email-sender.js";
+export const console = (options) => Layer.effect(EmailSender, Effect.succeed(EmailSender.of({
+    send: (email) => {
+        const invalid = validateEmail(email, options.defaultFrom);
+        if (invalid)
+            return Effect.fail(invalid);
+        return Effect.logInfo("Email queued", {
+            fromConfigured: Boolean(email.from ?? options.defaultFrom),
+            recipientCount: 1,
+            hasHtml: Boolean(email.html),
+        }).pipe(Effect.as({}));
+    },
+})));

package/dist/adapters/memory.d.ts

@@ -0,0 +1,10 @@
+import { Context, Effect, Layer } from "effect";
+import { EmailSender, type EmailDelivery, type EmailSenderOptions } from "../sender/email-sender.ts";
+declare const MemoryEmailOutboxTesting_base: Context.ServiceClass<MemoryEmailOutboxTesting, "@house-rules/email/MemoryEmailOutboxTesting", {
+    messages: Effect.Effect<ReadonlyArray<EmailDelivery>>;
+    add: (email: EmailDelivery) => Effect.Effect<void>;
+}>;
+export declare class MemoryEmailOutboxTesting extends MemoryEmailOutboxTesting_base {
+}
+export declare const memory: (options: EmailSenderOptions) => Layer.Layer<EmailSender | MemoryEmailOutboxTesting, never, never>;
+export {};

package/dist/adapters/memory.js

@@ -0,0 +1,29 @@
+import { Context, Effect, Layer, Ref } from "effect";
+import { EmailSender, validateEmail, } from "../sender/email-sender.js";
+export class MemoryEmailOutboxTesting extends Context.Service()("@house-rules/email/MemoryEmailOutboxTesting") {
+}
+export const memory = (options) => {
+    const outbox = Layer.effect(MemoryEmailOutboxTesting, Effect.gen(function* () {
+        const sent = yield* Ref.make(new Map());
+        return MemoryEmailOutboxTesting.of({
+            messages: Ref.get(sent).pipe(Effect.map((items) => [...items.values()])),
+            add: (email) => Ref.update(sent, (items) => {
+                if (items.has(email.idempotencyKey))
+                    return items;
+                const message = Object.freeze({ ...email, from: email.from ?? options.defaultFrom });
+                return new Map(items).set(email.idempotencyKey, message);
+            }),
+        });
+    }));
+    return Layer.effect(EmailSender, Effect.gen(function* () {
+        const outbox = yield* MemoryEmailOutboxTesting;
+        return EmailSender.of({
+            send: (email) => {
+                const invalid = validateEmail(email, options.defaultFrom);
+                if (invalid)
+                    return Effect.fail(invalid);
+                return outbox.add(email).pipe(Effect.as({}));
+            },
+        });
+    })).pipe(Layer.provideMerge(outbox));
+};

package/dist/contract.d.ts

@@ -0,0 +1,3 @@
+export { EmailMessage, EmailRejected, EmailSendFailed, EmailCallerDenied, EmailSendResult, } from "./sender/message.ts";
+export { EmailOperations } from "./sender/operations.ts";
+export { type EmailPermission, EmailPermissions } from "./sender/permissions.ts";

package/dist/contract.js

@@ -0,0 +1,3 @@
+export { EmailMessage, EmailRejected, EmailSendFailed, EmailCallerDenied, EmailSendResult, } from "./sender/message.js";
+export { EmailOperations } from "./sender/operations.js";
+export { EmailPermissions } from "./sender/permissions.js";

package/dist/facade.d.ts

@@ -0,0 +1,16 @@
+import { Effect } from "effect";
+import { EmailSender } from "./sender/email-sender.ts";
+import type { EmailMessage, EmailRejected, EmailSendFailed, EmailSendResult } from "./sender/message.ts";
+declare const Email_base: import("effect/Context").ServiceClass<Email, "email", {
+    readonly send: (message: EmailMessage, idempotencyKey: string) => Effect.Effect<EmailSendResult, EmailSendFailed | EmailRejected>;
+}> & {
+    readonly id: "email";
+} & {
+    readonly make: Effect.Effect<{
+        readonly send: (message: EmailMessage, idempotencyKey: string) => Effect.Effect<EmailSendResult, EmailSendFailed | EmailRejected>;
+    }, never, EmailSender>;
+    readonly layer: import("@house-rules/domain").ModuleLayer<Email, never, EmailSender>;
+};
+export declare class Email extends Email_base {
+}
+export {};

package/dist/facade.js

@@ -0,0 +1,12 @@
+import { defineModule } from "@house-rules/domain";
+import { Effect } from "effect";
+import { EmailSender } from "./sender/email-sender.js";
+export class Email extends defineModule()("email", {
+    make: Effect.gen(function* () {
+        const sender = yield* EmailSender;
+        return {
+            send: (message, idempotencyKey) => sender.send({ ...message, idempotencyKey }),
+        };
+    }),
+}) {
+}

package/dist/index.d.ts

@@ -0,0 +1,31 @@
+import { Email } from "./facade.ts";
+import { bindEmail } from "./sender/bind-email.ts";
+export declare const EmailMount: {
+    map: {
+        name: string;
+        kind: "package";
+        package: string;
+    };
+    service: typeof Email;
+    operations: import("@house-rules/domain/contract").Operation<"Email.send", import("effect/Schema").Struct<{
+        readonly message: import("effect/Schema").Struct<{
+            readonly to: import("effect/Schema").String;
+            readonly from: import("effect/Schema").optionalKey<import("effect/Schema").String>;
+            readonly subject: import("effect/Schema").String;
+            readonly text: import("effect/Schema").String;
+            readonly html: import("effect/Schema").optionalKey<import("effect/Schema").String>;
+            readonly headers: import("effect/Schema").optionalKey<import("effect/Schema").$Record<import("effect/Schema").String, import("effect/Schema").String>>;
+        }>;
+        readonly idempotencyKey: import("effect/Schema").String;
+    }>, import("effect/Schema").Struct<{
+        readonly providerId: import("effect/Schema").optionalKey<import("effect/Schema").String>;
+    }>, import("effect/Schema").Union<readonly [typeof import("./contract.ts").EmailSendFailed, typeof import("./contract.ts").EmailRejected, typeof import("./contract.ts").EmailCallerDenied]>, NoInfer<readonly []>, false, false, false, false>[];
+    bind: typeof bindEmail;
+};
+export { Email } from "./facade.ts";
+export { bindEmail } from "./sender/bind-email.ts";
+export { EmailSender } from "./sender/email-sender.ts";
+export type { EmailDelivery, EmailSenderOptions } from "./sender/email-sender.ts";
+export { EmailMessage, EmailOperations, type EmailPermission, EmailPermissions, EmailRejected, EmailSendFailed, EmailCallerDenied, EmailSendResult, } from "./contract.ts";
+export { console as consoleEmail } from "./adapters/console.ts";
+export { memory as memoryEmail, MemoryEmailOutboxTesting } from "./adapters/memory.ts";

package/dist/index.js

@@ -0,0 +1,15 @@
+import { Email } from "./facade.js";
+import { bindEmail } from "./sender/bind-email.js";
+import { EmailOperations } from "./sender/operations.js";
+export const EmailMount = {
+    map: { name: "email", kind: "package", package: "@house-rules/email" },
+    service: Email,
+    operations: Object.values(EmailOperations),
+    bind: bindEmail,
+};
+export { Email } from "./facade.js";
+export { bindEmail } from "./sender/bind-email.js";
+export { EmailSender } from "./sender/email-sender.js";
+export { EmailMessage, EmailOperations, EmailPermissions, EmailRejected, EmailSendFailed, EmailCallerDenied, EmailSendResult, } from "./contract.js";
+export { console as consoleEmail } from "./adapters/console.js";
+export { memory as memoryEmail, MemoryEmailOutboxTesting } from "./adapters/memory.js";

package/dist/sender/bind-email.d.ts

@@ -0,0 +1,8 @@
+import { type Binding } from "@house-rules/application";
+import { Effect } from "effect";
+import { type EmailMessage, type EmailRejected, type EmailSendFailed, type EmailSendResult } from "./message.ts";
+type Service = {
+    readonly send: (message: EmailMessage, idempotencyKey: string) => Effect.Effect<EmailSendResult, EmailSendFailed | EmailRejected>;
+};
+export declare const bindEmail: (service: Service) => readonly Binding[];
+export {};

package/dist/sender/bind-email.js

@@ -0,0 +1,9 @@
+import { bindOperation } from "@house-rules/application";
+import { Effect } from "effect";
+import { EmailCallerDenied, } from "./message.js";
+import { EmailOperations } from "./operations.js";
+export const bindEmail = (service) => [
+    bindOperation(EmailOperations.send, ({ message, idempotencyKey }, { caller }) => caller.kind === "system"
+        ? service.send(message, idempotencyKey)
+        : Effect.fail(new EmailCallerDenied())),
+];

package/dist/sender/email-sender.d.ts

@@ -0,0 +1,15 @@
+import { Context, type Effect } from "effect";
+import { type EmailMessage, EmailRejected, type EmailSendFailed, type EmailSendResult } from "./message.ts";
+export type EmailDelivery = EmailMessage & Readonly<{
+    idempotencyKey: string;
+}>;
+export declare const validateEmail: (email: EmailDelivery, defaultFrom: string) => EmailRejected | undefined;
+declare const EmailSender_base: Context.ServiceClass<EmailSender, "@house-rules/email/EmailSender", {
+    send(email: EmailDelivery): Effect.Effect<EmailSendResult, EmailSendFailed | EmailRejected>;
+}>;
+export declare class EmailSender extends EmailSender_base {
+}
+export type EmailSenderOptions = Readonly<{
+    defaultFrom: string;
+}>;
+export {};

package/dist/sender/email-sender.js

@@ -0,0 +1,25 @@
+import { Context } from "effect";
+import { EmailRejected, } from "./message.js";
+export const validateEmail = (email, defaultFrom) => {
+    const headerValues = Object.entries(email.headers ?? {}).flat();
+    const headersInvalid = headerValues.some((value) => /[\r\n]/.test(value));
+    const addressOrSubjectInvalid = [
+        email.to,
+        email.from ?? defaultFrom,
+        defaultFrom,
+        email.subject,
+    ].some((value) => /[\r\n]/.test(value));
+    if (!defaultFrom.trim() ||
+        !(email.from ?? defaultFrom).trim() ||
+        !email.to.trim() ||
+        !email.subject.trim() ||
+        !email.text.trim() ||
+        !email.idempotencyKey.trim() ||
+        headersInvalid ||
+        addressOrSubjectInvalid) {
+        return new EmailRejected({ message: "Email is invalid." });
+    }
+    return undefined;
+};
+export class EmailSender extends Context.Service()("@house-rules/email/EmailSender") {
+}

package/dist/sender/message.d.ts

@@ -0,0 +1,34 @@
+import { Schema } from "effect";
+export declare const EmailMessage: Schema.Struct<{
+    readonly to: Schema.String;
+    readonly from: Schema.optionalKey<Schema.String>;
+    readonly subject: Schema.String;
+    readonly text: Schema.String;
+    readonly html: Schema.optionalKey<Schema.String>;
+    readonly headers: Schema.optionalKey<Schema.$Record<Schema.String, Schema.String>>;
+}>;
+export type EmailMessage = typeof EmailMessage.Type;
+export declare const EmailSendResult: Schema.Struct<{
+    readonly providerId: Schema.optionalKey<Schema.String>;
+}>;
+export type EmailSendResult = typeof EmailSendResult.Type;
+declare const EmailSendFailed_base: Schema.Class<EmailSendFailed, Schema.TaggedStruct<"EmailSendFailed", {
+    readonly kind: Schema.tag<"unavailable">;
+    readonly message: Schema.Literal<"Email sending is unavailable.">;
+    readonly cause: Schema.optional<Schema.Defect>;
+}>, import("effect/Cause").YieldableError>;
+export declare class EmailSendFailed extends EmailSendFailed_base {
+}
+declare const EmailRejected_base: Schema.Class<EmailRejected, Schema.TaggedStruct<"EmailRejected", {
+    readonly kind: Schema.tag<"invalid">;
+    readonly message: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+export declare class EmailRejected extends EmailRejected_base {
+}
+declare const EmailCallerDenied_base: Schema.Class<EmailCallerDenied, Schema.TaggedStruct<"EmailCallerDenied", {
+    readonly kind: Schema.tag<"forbidden">;
+    readonly message: Schema.tag<"Email sending requires a system caller.">;
+}>, import("effect/Cause").YieldableError>;
+export declare class EmailCallerDenied extends EmailCallerDenied_base {
+}
+export {};

package/dist/sender/message.js

@@ -0,0 +1,27 @@
+import { errorKind } from "@house-rules/domain/contract";
+import { Schema } from "effect";
+export const EmailMessage = Schema.Struct({
+    to: Schema.String,
+    from: Schema.optionalKey(Schema.String),
+    subject: Schema.String,
+    text: Schema.String,
+    html: Schema.optionalKey(Schema.String),
+    headers: Schema.optionalKey(Schema.Record(Schema.String, Schema.String)),
+});
+export const EmailSendResult = Schema.Struct({ providerId: Schema.optionalKey(Schema.String) });
+export class EmailSendFailed extends Schema.TaggedError()("EmailSendFailed", {
+    kind: errorKind("unavailable"),
+    message: Schema.Literal("Email sending is unavailable."),
+    cause: Schema.optional(Schema.Defect()),
+}) {
+}
+export class EmailRejected extends Schema.TaggedError()("EmailRejected", {
+    kind: errorKind("invalid"),
+    message: Schema.String,
+}) {
+}
+export class EmailCallerDenied extends Schema.TaggedError()("EmailCallerDenied", {
+    kind: errorKind("forbidden"),
+    message: Schema.tag("Email sending requires a system caller."),
+}) {
+}

package/dist/sender/operations.d.ts

@@ -0,0 +1,17 @@
+import { Schema } from "effect";
+import { EmailRejected, EmailSendFailed, EmailCallerDenied } from "./message.ts";
+export declare const EmailOperations: {
+    readonly send: import("@house-rules/domain/contract").Operation<"Email.send", Schema.Struct<{
+        readonly message: Schema.Struct<{
+            readonly to: Schema.String;
+            readonly from: Schema.optionalKey<Schema.String>;
+            readonly subject: Schema.String;
+            readonly text: Schema.String;
+            readonly html: Schema.optionalKey<Schema.String>;
+            readonly headers: Schema.optionalKey<Schema.$Record<Schema.String, Schema.String>>;
+        }>;
+        readonly idempotencyKey: Schema.String;
+    }>, Schema.Struct<{
+        readonly providerId: Schema.optionalKey<Schema.String>;
+    }>, Schema.Union<readonly [typeof EmailSendFailed, typeof EmailRejected, typeof EmailCallerDenied]>, NoInfer<readonly []>, false, false, false, false>;
+};

package/dist/sender/operations.js

@@ -0,0 +1,14 @@
+import { defineOperation } from "@house-rules/domain/contract";
+import { Schema } from "effect";
+import { EmailMessage, EmailRejected, EmailSendFailed, EmailCallerDenied, EmailSendResult, } from "./message.js";
+import { EmailPermissions } from "./permissions.js";
+const send = defineOperation("Email.send", {
+    description: "Send an email as the system with a delivery idempotency key.",
+    input: Schema.Struct({ message: EmailMessage, idempotencyKey: Schema.String }),
+    output: EmailSendResult,
+    failure: Schema.Union([EmailSendFailed, EmailRejected, EmailCallerDenied]),
+    permission: EmailPermissions.send,
+    edges: [],
+    transactional: false,
+});
+export const EmailOperations = { send };

package/dist/sender/permissions.d.ts

@@ -0,0 +1,4 @@
+export declare const EmailPermissions: {
+    readonly send: "email:send";
+};
+export type EmailPermission = (typeof EmailPermissions)[keyof typeof EmailPermissions];

package/dist/sender/permissions.js

@@ -0,0 +1 @@
+export const EmailPermissions = { send: "email:send" };

package/package.json

@@ -1,6 +1,52 @@
 {
   "name": "@house-rules/email",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.1",
+  "description": "A provider-neutral email sending port with console and memory adapters.",
+  "license": "MIT",
+  "type": "module",
+  "files": [
+    "dist",
+    "AGENTS.md",
+    "README.md"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./contract": {
+      "types": "./dist/contract.d.ts",
+      "default": "./dist/contract.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/JakubSzwajka/house-rules.git",
+    "directory": "packages/email"
+  },
+  "bugs": {
+    "url": "https://github.com/JakubSzwajka/house-rules/issues"
+  },
+  "homepage": "https://github.com/JakubSzwajka/house-rules",
+  "peerDependencies": {
+    "@house-rules/application": "0.3.0",
+    "@house-rules/domain": "0.2.1",
+    "effect": "4.0.3"
+  },
+  "devDependencies": {
+    "@effect/vitest": "4.0.3",
+    "@house-rules/application": "0.3.0",
+    "@house-rules/domain": "0.2.1",
+    "effect": "4.0.3",
+    "typescript": "7.0.2",
+    "vitest": "5.0.1"
+  },
+  "scripts": {
+    "build": "tsc --project tsconfig.build.json",
+    "typecheck": "tsc --project tsconfig.json",
+    "test": "varlock run --path ../../ -- vitest run"
+  }
 }