@mailslot/core 0.0.2 → 0.2.1

package/README.md

@@ -1,9 +1,14 @@
 # @mailslot/core
 
-The Mailslot worker: self-hosted email inbox for AI agents on your own
-Cloudflare account. One Durable Object per address, MCP + HTTP + webhook
-surfaces, read-once OTP extraction.
+The Mailslot worker as a library: a self-hosted email inbox for AI agents on
+your own Cloudflare account. One Durable Object per address, MCP plus HTTP plus
+webhook surfaces, read-once OTP extraction.
 
-This package is deployed from source with wrangler — see the
-[setup guide](https://github.com/mailslot/mailslot#quick-start). For the
-guided deploy (coming soon): `npx create-mailslot`.
+Deploy it with the wizard, `npx create-mailslot`, which scaffolds a thin project
+importing this package and walks the whole setup. Or deploy from source with
+wrangler: see the [setup guide](https://github.com/mailslot/mailslot#quick-start).
+
+To customize a deployment, subclass `Inbox` and override the protected
+`onStored(email, message)` hook. It runs after the message is stored, while the
+email proxy is still valid, so it is the place for per-deployment logic like
+auto-replies or custom notifications, without forking core.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mailslot/core",
-  "version": "0.0.2",
+  "version": "0.2.1",
   "description": "Self-hosted email inbox for AI agents, on your own Cloudflare account",
   "license": "MIT",
   "type": "module",
@@ -30,7 +30,6 @@
   },
   "scripts": {
     "dev": "wrangler dev",
-    "deploy": "wrangler deploy",
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
     "cf-typegen": "wrangler types"

package/src/env.ts

@@ -18,12 +18,6 @@ declare global {
       WEBHOOK_URL?: string;
       /** If set, webhook payloads are HMAC-SHA256 signed (X-Mailslot-Signature). */
       WEBHOOK_SECRET?: string;
-      /**
-       * Comma-separated addresses that auto-reply with a "return receipt"
-       * showing what the worker parsed (proof-of-handling). Replies are
-       * suppressed for auto-generated, bulk, and bounce mail.
-       */
-      RECEIPT_ADDRESSES?: string;
     }
   }
 }

package/src/inbox.ts

@@ -76,13 +76,6 @@ export class Inbox extends Agent<Env> {
     return this.name;
   }
 
-  private isReceiptAddress(): boolean {
-    return (this.env.RECEIPT_ADDRESSES ?? "")
-      .split(",")
-      .map((a) => a.trim().toLowerCase())
-      .includes(this.address);
-  }
-
   async onEmail(email: AgentEmail) {
     const raw = await email.getRaw();
     const parsed = await PostalMime.parse(raw);
@@ -111,18 +104,9 @@ export class Inbox extends Agent<Env> {
       }
     }
 
-    // Return receipt: visible proof the worker handled the mail.
-    // Reply goes back through Email Routing (no ESP). Guarded against loops.
-    if (this.isReceiptAddress() && shouldAutoReply(email)) {
-      try {
-        await this.replyToEmail(email, {
-          fromName: "Mailslot",
-          body: receiptBody(this.address, { id, subject, snippet, receivedAt })
-        });
-      } catch (e) {
-        console.error("receipt reply failed:", e);
-      }
-    }
+    // Extension point: subclasses may add custom handling (e.g. an auto-reply)
+    // here, while the email proxy is still valid and before webhook delivery.
+    await this.onStored(email, { id, from: email.from, subject, snippet, receivedAt, consumed: false });
 
     if (this.env.WEBHOOK_URL) {
       await this.deliverWebhook({
@@ -140,6 +124,14 @@ export class Inbox extends Agent<Env> {
     }
   }
 
+  /**
+   * Extension point, called once per inbound message after it is stored and
+   * any forward, before webhook delivery — while the email proxy is still
+   * valid. Default: no-op. Override in a subclass to add custom handling such
+   * as an auto-reply. Core stays free of outbound/business logic.
+   */
+  protected async onStored(_email: AgentEmail, _message: MessageSummary): Promise<void> {}
+
   list(opts: ListOptions = {}): MessageSummary[] {
     const limit = Math.min(Math.max(opts.limit ?? 20, 1), 100);
     // Small per-address volumes: fetch recent window, filter in JS.
@@ -263,46 +255,6 @@ export class Inbox extends Agent<Env> {
   }
 }
 
-/**
- * Loop prevention for auto-replies. Never answer bounces, auto-generated,
- * or bulk/list mail — replying to a robot is how mail loops are born.
- */
-function shouldAutoReply(email: AgentEmail): boolean {
-  const from = (email.from ?? "").toLowerCase();
-  if (!from || from.startsWith("mailer-daemon") || from.startsWith("postmaster")) return false;
-
-  const h = email.headers;
-  const autoSubmitted = h.get("auto-submitted");
-  if (autoSubmitted && autoSubmitted.toLowerCase() !== "no") return false;
-  if (h.get("x-auto-response-suppress")) return false;
-  if (h.get("list-id") || h.get("list-unsubscribe")) return false;
-  const precedence = (h.get("precedence") ?? "").toLowerCase();
-  if (precedence === "bulk" || precedence === "junk" || precedence === "list") return false;
-  return true;
-}
-
-function receiptBody(
-  address: string,
-  msg: { id: string; subject: string; snippet: string; receivedAt: number }
-): string {
-  return [
-    "Return receipt — your mail was handled by a Mailslot worker.",
-    "",
-    `  inbox:    ${address}`,
-    `  subject:  ${msg.subject || "(none)"}`,
-    `  parsed:   ${msg.snippet || "(empty body)"}`,
-    `  id:       ${msg.id}`,
-    `  received: ${new Date(msg.receivedAt).toISOString()}`,
-    "",
-    "This reply was sent by the same Cloudflare Worker that received,",
-    "parsed, and stored your message — self-hosted, no email provider",
-    "involved. An AI agent can now read it over MCP.",
-    "",
-    "Mailslot — your agent's email shouldn't come with a landlord.",
-    "https://mailslot.dev · https://github.com/mailslot/mailslot"
-  ].join("\n");
-}
-
 function toSummary(row: MessageRow): MessageSummary {
   return {
     id: row.id,

package/src/index.ts

@@ -6,6 +6,8 @@ import { handleApi } from "./api";
 import { checkBearerToken } from "./auth";
 
 export { Inbox, MailslotMcp };
+export type { MessageSummary, MessageDetail } from "./inbox";
+export type { AgentEmail } from "agents";
 
 const mcpHandler = MailslotMcp.serve("/mcp", { binding: "MailslotMcp" });