carlyemail 0.6.5 → 0.7.0

package/README.md

@@ -170,12 +170,23 @@ import { createEmailHandler } from "carlyemail/webhooks";
 
 const handleEmail = createEmailHandler({
   secret: env.CARLYEMAIL_WEBHOOK_SECRET,
+  inbox: "frontdesk@carlyemail.com",
+  allowFrom: ["sam@gmail.com"],
   async onEmail(event) {
     console.log(event.message);
   },
 });
+
+export default {
+  fetch: (request, env, ctx) => handleEmail(request, env, ctx),
+};
 ```
 
+Only `message.received` reaches `onEmail`: spam, blocked and unauthenticated
+mail does not, nor does mail from the inbox itself, a sender outside
+`allowFrom`, or a redelivery. The handler answers 202 and runs `onEmail` after,
+through `ctx.waitUntil` when it is given one. A bad signature gets 401.
+
 ## Licence
 
 MIT — see `LICENSE`. That covers **this CLI only**. The CarlyEmail service it

package/carlyemail.js

@@ -18,7 +18,7 @@ import { basename, extname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { randomBytes } from "node:crypto";
 
-export const VERSION = "0.6.5";
+export const VERSION = "0.7.0";
 
 const DEFAULT_API = "https://api.carlyemail.com";
 const CONFIG_DIR = join(homedir(), ".carlyemail");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "carlyemail",
-  "version": "0.6.5",
+  "version": "0.7.0",
   "description": "Real email inboxes your agent can send, receive and reply from. SDK and CLI.",
   "keywords": [
     "email",

package/sdk.d.ts

@@ -1,5 +1,13 @@
 // Generated by scripts/build_sdk.py from the OpenAPI spec. Do not edit.
 
+export interface Actor {
+  type: string;
+  member_id?: string | null;
+  api_key_id?: string | null;
+  name?: string | null;
+  email?: string | null;
+}
+
 export interface AgentSigninRequest {
   human_email: string;
 }
@@ -164,6 +172,10 @@ export interface CreateListEntryRequest {
   reason?: string | null;
 }
 
+export interface CreateNoteRequest {
+  text: string;
+}
+
 export interface CreatePodRequest {
   name?: string | null;
   client_id?: string | null;
@@ -191,6 +203,14 @@ export interface DomainOut {
   created_at: string;
 }
 
+export interface DraftInProgress {
+  draft_id: string;
+  created_by?: Actor | null;
+  updated_by?: Actor | null;
+  send_at?: string | null;
+  updated_at: string;
+}
+
 export interface DraftOut {
   inbox_id: string;
   draft_id: string;
@@ -210,6 +230,8 @@ export interface DraftOut {
   references?: Array<string>;
   send_status?: string | null;
   send_at?: string | null;
+  created_by?: Actor | null;
+  updated_by?: Actor | null;
   updated_at: string;
   created_at: string;
 }
@@ -270,6 +292,7 @@ export interface InboxEventOut {
   event_type: "label.added" | "label.removed";
   message_id?: string | null;
   label?: string | null;
+  actor?: Actor | null;
   event_at: string;
   created_at: string;
 }
@@ -365,6 +388,11 @@ export interface ListMessagesResponse {
   messages: Array<MessageItem>;
 }
 
+export interface ListNotesResponse {
+  count: number;
+  notes: Array<NoteOut>;
+}
+
 export interface ListPodsResponse {
   count: number;
   limit?: number | null;
@@ -418,6 +446,7 @@ export interface MessageItem {
   preview?: string | null;
   attachments?: Array<AttachmentOut>;
   size?: number;
+  sent_by?: Actor | null;
   updated_at: string;
   created_at: string;
 }
@@ -437,6 +466,7 @@ export interface MessageOut {
   preview?: string | null;
   attachments?: Array<AttachmentOut>;
   size?: number;
+  sent_by?: Actor | null;
   updated_at: string;
   created_at: string;
   text?: string | null;
@@ -449,6 +479,15 @@ export interface MessageOut {
   authentication?: Record<string, string>;
 }
 
+export interface NoteOut {
+  note_id: string;
+  thread_id: string;
+  inbox_id: string;
+  text: string;
+  author?: Actor | null;
+  created_at: string;
+}
+
 export interface OrganizationChoice {
   organization_id: string;
   name?: string | null;
@@ -575,6 +614,7 @@ export interface ThreadItem {
   last_message_id?: string | null;
   message_count?: number;
   size?: number;
+  assignee?: Actor | null;
   updated_at: string;
   created_at: string;
 }
@@ -594,9 +634,12 @@ export interface ThreadOut {
   last_message_id?: string | null;
   message_count?: number;
   size?: number;
+  assignee?: Actor | null;
   updated_at: string;
   created_at: string;
   messages?: Array<MessageOut>;
+  notes?: Array<NoteOut>;
+  drafts?: Array<DraftInProgress>;
 }
 
 export interface UpdateDomainRequest {
@@ -648,11 +691,13 @@ export interface UpdateMessageResponse {
 export interface UpdateThreadRequest {
   add_labels?: Array<string> | null;
   remove_labels?: Array<string> | null;
+  assignee_id?: string | null;
 }
 
 export interface UpdateThreadResponse {
   thread_id: string;
   labels: Array<string>;
+  assignee?: Actor | null;
 }
 
 export interface UpdateWebhookHeadersRequest {
@@ -779,13 +824,16 @@ export declare class Messages {
 }
 
 export declare class Threads {
-  list(inboxId: string, query?: { limit?: number | null; pageToken?: string | null; labels?: Array<string> | null; before?: string | null; after?: string | null; ascending?: boolean; senders?: Array<string> | null; recipients?: Array<string> | null; subject?: string | null }): Promise<ListThreadsResponse>;
+  list(inboxId: string, query?: { limit?: number | null; pageToken?: string | null; labels?: Array<string> | null; before?: string | null; after?: string | null; ascending?: boolean; senders?: Array<string> | null; recipients?: Array<string> | null; subject?: string | null; assignee?: string | null }): Promise<ListThreadsResponse>;
   search(inboxId: string, query?: { q?: string; limit?: number | null; pageToken?: string | null; before?: string | null; after?: string | null }): Promise<ListThreadsResponse>;
   getAttachment(inboxId: string, threadId: string, attachmentId: string): Promise<AttachmentResponse>;
   get(inboxId: string, threadId: string): Promise<ThreadOut>;
   update(inboxId: string, threadId: string, body: UpdateThreadRequest): Promise<UpdateThreadResponse>;
   delete(inboxId: string, threadId: string): Promise<void>;
-  listOrg(query?: { limit?: number | null; pageToken?: string | null; labels?: Array<string> | null; before?: string | null; after?: string | null; ascending?: boolean; includeSpam?: boolean; includeBlocked?: boolean; includeUnauthenticated?: boolean; includeTrash?: boolean; senders?: Array<string> | null; recipients?: Array<string> | null; subject?: string | null }): Promise<ListThreadsResponse>;
+  listNotes(inboxId: string, threadId: string): Promise<ListNotesResponse>;
+  addNote(inboxId: string, threadId: string, body: CreateNoteRequest): Promise<NoteOut>;
+  deleteNote(inboxId: string, threadId: string, noteId: string): Promise<void>;
+  listOrg(query?: { limit?: number | null; pageToken?: string | null; labels?: Array<string> | null; before?: string | null; after?: string | null; ascending?: boolean; includeSpam?: boolean; includeBlocked?: boolean; includeUnauthenticated?: boolean; includeTrash?: boolean; senders?: Array<string> | null; recipients?: Array<string> | null; subject?: string | null; assignee?: string | null }): Promise<ListThreadsResponse>;
   searchOrg(query?: { q?: string; limit?: number | null; pageToken?: string | null; before?: string | null; after?: string | null }): Promise<ListThreadsResponse>;
   getOrg(threadId: string): Promise<ThreadOut>;
   updateOrg(threadId: string, body: UpdateThreadRequest): Promise<UpdateThreadResponse>;
@@ -865,7 +913,7 @@ export declare class Pods {
   getInbox(inboxId: string, podId: string): Promise<InboxOut>;
   updateInbox(inboxId: string, podId: string, body: UpdateInboxRequest): Promise<InboxOut>;
   deleteInbox(inboxId: string, podId: string, query?: { force?: boolean }): Promise<void>;
-  listThreads(podId: string, query?: { limit?: number | null; pageToken?: string | null; labels?: Array<string> | null; before?: string | null; after?: string | null; ascending?: boolean; includeSpam?: boolean; includeBlocked?: boolean; includeUnauthenticated?: boolean; includeTrash?: boolean; senders?: Array<string> | null; recipients?: Array<string> | null; subject?: string | null }): Promise<ListThreadsResponse>;
+  listThreads(podId: string, query?: { limit?: number | null; pageToken?: string | null; labels?: Array<string> | null; before?: string | null; after?: string | null; ascending?: boolean; includeSpam?: boolean; includeBlocked?: boolean; includeUnauthenticated?: boolean; includeTrash?: boolean; senders?: Array<string> | null; recipients?: Array<string> | null; subject?: string | null; assignee?: string | null }): Promise<ListThreadsResponse>;
   searchThreads(podId: string, query?: { q?: string; limit?: number | null; pageToken?: string | null; before?: string | null; after?: string | null }): Promise<ListThreadsResponse>;
   getThread(threadId: string, podId: string): Promise<ThreadOut>;
   updateThread(threadId: string, podId: string, body: UpdateThreadRequest): Promise<UpdateThreadResponse>;

package/sdk.js

@@ -251,7 +251,7 @@ class Threads {
 
   /** List Threads */
   list(inboxId, query = {}) {
-    return this.$.request("GET", `/v0/inboxes/${encode(inboxId)}/threads`, { query: { "limit": query.limit, "page_token": query.pageToken, "labels": query.labels, "before": query.before, "after": query.after, "ascending": query.ascending, "senders": query.senders, "recipients": query.recipients, "subject": query.subject } });
+    return this.$.request("GET", `/v0/inboxes/${encode(inboxId)}/threads`, { query: { "limit": query.limit, "page_token": query.pageToken, "labels": query.labels, "before": query.before, "after": query.after, "ascending": query.ascending, "senders": query.senders, "recipients": query.recipients, "subject": query.subject, "assignee": query.assignee } });
   }
 
   /** Search Threads */
@@ -279,9 +279,24 @@ class Threads {
     return this.$.request("DELETE", `/v0/inboxes/${encode(inboxId)}/threads/${encode(threadId)}`);
   }
 
+  /** List Notes */
+  listNotes(inboxId, threadId) {
+    return this.$.request("GET", `/v0/inboxes/${encode(inboxId)}/threads/${encode(threadId)}/notes`);
+  }
+
+  /** Add Note */
+  addNote(inboxId, threadId, body) {
+    return this.$.request("POST", `/v0/inboxes/${encode(inboxId)}/threads/${encode(threadId)}/notes`, { body });
+  }
+
+  /** Delete Note */
+  deleteNote(inboxId, threadId, noteId) {
+    return this.$.request("DELETE", `/v0/inboxes/${encode(inboxId)}/threads/${encode(threadId)}/notes/${encode(noteId)}`);
+  }
+
   /** List Threads */
   listOrg(query = {}) {
-    return this.$.request("GET", `/v0/threads`, { query: { "limit": query.limit, "page_token": query.pageToken, "labels": query.labels, "before": query.before, "after": query.after, "ascending": query.ascending, "include_spam": query.includeSpam, "include_blocked": query.includeBlocked, "include_unauthenticated": query.includeUnauthenticated, "include_trash": query.includeTrash, "senders": query.senders, "recipients": query.recipients, "subject": query.subject } });
+    return this.$.request("GET", `/v0/threads`, { query: { "limit": query.limit, "page_token": query.pageToken, "labels": query.labels, "before": query.before, "after": query.after, "ascending": query.ascending, "include_spam": query.includeSpam, "include_blocked": query.includeBlocked, "include_unauthenticated": query.includeUnauthenticated, "include_trash": query.includeTrash, "senders": query.senders, "recipients": query.recipients, "subject": query.subject, "assignee": query.assignee } });
   }
 
   /** Search Threads */
@@ -609,7 +624,7 @@ class Pods {
 
   /** List Threads */
   listThreads(podId, query = {}) {
-    return this.$.request("GET", `/v0/pods/${encode(podId)}/threads`, { query: { "limit": query.limit, "page_token": query.pageToken, "labels": query.labels, "before": query.before, "after": query.after, "ascending": query.ascending, "include_spam": query.includeSpam, "include_blocked": query.includeBlocked, "include_unauthenticated": query.includeUnauthenticated, "include_trash": query.includeTrash, "senders": query.senders, "recipients": query.recipients, "subject": query.subject } });
+    return this.$.request("GET", `/v0/pods/${encode(podId)}/threads`, { query: { "limit": query.limit, "page_token": query.pageToken, "labels": query.labels, "before": query.before, "after": query.after, "ascending": query.ascending, "include_spam": query.includeSpam, "include_blocked": query.includeBlocked, "include_unauthenticated": query.includeUnauthenticated, "include_trash": query.includeTrash, "senders": query.senders, "recipients": query.recipients, "subject": query.subject, "assignee": query.assignee } });
   }
 
   /** Search Threads */

package/webhooks.d.ts

@@ -28,8 +28,31 @@ export declare function verifyWebhook(
   options?: VerifyWebhookOptions,
 ): Promise<CarlyEmailEvent>;
 
-export declare function createEmailHandler(options: {
+export declare const RECEIVED: "message.received";
+export declare const SPAM: "message.received.spam";
+export declare const BLOCKED: "message.received.blocked";
+export declare const UNAUTHENTICATED: "message.received.unauthenticated";
+
+export interface CreateEmailHandlerOptions {
   secret: string;
   onEmail: (event: CarlyEmailEvent, request: Request) => unknown | Promise<unknown>;
+  /** The address being answered, so mail it sent itself is dropped. */
+  inbox?: string;
+  /** Who may write: `emma@example.com` or `@example.com`. Empty means anyone. */
+  allowFrom?: string[] | string;
+  /** Event types that reach `onEmail`, matched exactly. Defaults to `message.received`. */
+  eventTypes?: string[];
   toleranceSeconds?: number;
-}): (request: Request) => Promise<Response>;
+  /** Event ids held in memory to ignore redeliveries. Defaults to 2048. */
+  remember?: number;
+  /**
+   * `true` (the default) answers 202 and runs `onEmail` afterwards, handing it
+   * to a `waitUntil` found among the handler's later arguments. `false` runs it
+   * first and lets an exception become a 5xx so the delivery retries.
+   */
+  background?: boolean;
+}
+
+export declare function createEmailHandler(
+  options: CreateEmailHandlerOptions,
+): (request: Request, ...context: unknown[]) => Promise<Response>;

package/webhooks.js

@@ -81,30 +81,108 @@ export async function verifyWebhook(secret, body, headers, options = {}) {
   throw new WebhookVerificationError("webhook signature does not match");
 }
 
+// The four ways a message arrives. They are separate event types rather than a
+// flag on one type, so a subscription to RECEIVED alone never sees the other
+// three. Match them exactly: `startsWith("message.received")` is true of all
+// four, and hands spam and forged senders straight to the model.
+export const RECEIVED = "message.received";
+export const SPAM = "message.received.spam";
+export const BLOCKED = "message.received.blocked";
+export const UNAUTHENTICATED = "message.received.unauthenticated";
+
+function addressOf(from) {
+  const value = String(from ?? "").trim();
+  const angled = value.match(/<([^<>]*)>\s*$/);
+  return (angled ? angled[1] : value).trim().toLowerCase();
+}
+
 /**
  * Build a fetch-compatible handler with a Cloudflare-style `onEmail(event)`
- * callback. Handler errors are allowed through so the delivery gets a 5xx and
- * retries; only verification errors are turned into terminal 400 responses.
+ * callback, making the same decisions as the Python `create_email_router`:
+ * verify the raw body, admit only the event types asked for (exactly), drop
+ * the inbox's own mail, check the sender, ignore a redelivery, and answer the
+ * delivery before the agent runs.
+ *
+ * A model turn can outlast the delivery timeout, and a timed-out delivery is
+ * retried, so by default the handler answers 202 and runs `onEmail` after. Pass
+ * the runtime's context as a later argument (`handle(request, env, ctx)` in a
+ * Worker) and the run goes to its `waitUntil`. `background: false` runs
+ * `onEmail` first and lets an exception become a 5xx so the delivery retries.
  */
-export function createEmailHandler({ secret, onEmail, toleranceSeconds = 300 }) {
+export function createEmailHandler({
+  secret,
+  onEmail,
+  inbox = "",
+  allowFrom = [],
+  eventTypes = [RECEIVED],
+  toleranceSeconds = 300,
+  remember = 2048,
+  background = true,
+}) {
   if (!secret) throw new Error("createEmailHandler requires a webhook secret");
   if (typeof onEmail !== "function") throw new TypeError("createEmailHandler requires onEmail");
 
-  return async function handle(request) {
+  const ownAddress = inbox.toLowerCase();
+  const allowed = new Set(
+    (typeof allowFrom === "string" ? allowFrom.split(",") : allowFrom)
+      .map((entry) => entry.trim().toLowerCase())
+      .filter(Boolean),
+  );
+  const admitted = new Set(eventTypes);
+  // Bounded and in memory, so it resets with the isolate. Redeliveries cluster
+  // in the minutes after a failure, which this covers; record `event_id`
+  // somewhere durable if acting twice on one email is costly.
+  const seen = new Set();
+
+  function allows(from) {
+    if (!allowed.size) return true;
+    // Compared whole, never as a substring: `emma@example.com.attacker.net`
+    // is a domain anyone can register and sign mail from.
+    const address = addressOf(from);
+    if (!address.includes("@")) return false;
+    return allowed.has(address) || allowed.has(`@${address.split("@").pop()}`);
+  }
+
+  function firstSighting(eventId) {
+    if (seen.has(eventId)) return false;
+    seen.add(eventId);
+    if (seen.size > remember) seen.delete(seen.values().next().value);
+    return true;
+  }
+
+  return async function handle(request, ...context) {
     const body = new Uint8Array(await request.arrayBuffer());
     let event;
     try {
       event = await verifyWebhook(secret, body, request.headers, { toleranceSeconds });
     } catch (error) {
+      // 401 and nothing else: an unverified caller learns the URL exists.
       if (error instanceof WebhookVerificationError) {
-        return new Response(error.message, { status: 400 });
+        return new Response(error.message, { status: 401 });
       }
       throw error;
     }
 
-    if (event.event_type?.startsWith("message.received")) {
+    const message = event?.message;
+    if (
+      !admitted.has(event?.event_type) ||
+      typeof message !== "object" ||
+      message === null ||
+      (ownAddress && addressOf(message.from) === ownAddress) ||
+      !allows(message.from) ||
+      (event.event_id && !firstSighting(event.event_id))
+    ) {
+      return new Response(null, { status: 204 });
+    }
+
+    if (!background) {
       await onEmail(event, request);
+      return new Response(null, { status: 204 });
     }
-    return new Response(null, { status: 204 });
+    const run = Promise.resolve()
+      .then(() => onEmail(event, request))
+      .catch((error) => console.error("carlyemail: onEmail failed", error));
+    context.find((item) => typeof item?.waitUntil === "function")?.waitUntil(run);
+    return new Response(null, { status: 202 });
   };
 }