feat: thread facets — SDK vocabulary + @plotday/email-classifier + gmail/slack emission

.changeset/facets-sdk.md

@@ -0,0 +1,5 @@
+---
+"@plotday/twister": minor
+---
+
+Added: `@plotday/twister/facets` exporting `Format`, `Automation`, `Reach`, and `ThreadFacets` for connector-emitted thread facets, and `NewLink.facets` to carry them.

connectors/gmail/package.json

@@ -30,6 +30,7 @@
  },
  "dependencies": {
  "@plotday/connector-google-contacts": "workspace:^",
+ "@plotday/email-classifier": "workspace:^",
  "@plotday/twister": "workspace:^"
  },
  "devDependencies": {

connectors/gmail/src/gmail-facets.test.ts

@@ -0,0 +1,60 @@
+import { describe, expect, it } from "vitest";
+import { gmailFacets } from "./gmail-facets";
+import type { GmailMessage } from "./gmail-api";
+
+function msg(opts: {
+ headers: Array<[string, string]>;
+ labelIds?: string[];
+}): GmailMessage {
+ return {
+ id: "m1",
+ threadId: "t1",
+ labelIds: opts.labelIds ?? [],
+ snippet: "",
+ historyId: "1",
+ internalDate: "1700000000000",
+ sizeEstimate: 0,
+ payload: {
+ mimeType: "text/plain",
+ headers: opts.headers.map(([name, value]) => ({ name, value })),
+ },
+ };
+}
+
+describe("gmailFacets", () => {
+ it("classifies a newsletter as reading/automated/list", () => {
+ const f = gmailFacets(
+ msg({
+ headers: [
+ ["From", "news@substack.com"],
+ ["To", "me@x.com"],
+ ["Subject", "The Weekly Digest"],
+ ["List-Id", "<news.substack.com>"],
+ ["List-Unsubscribe", "<mailto:u@substack.com>"],
+ ],
+ }),
+ "a".repeat(4000)
+ );
+ expect(f).toEqual({ format: "reading", automation: "automated", reach: "list" });
+ });
+
+ it("classifies a personal 1:1 email as message/human/direct", () => {
+ const f = gmailFacets(
+ msg({ headers: [["From", "jane@friends.com"], ["To", "me@x.com"], ["Subject", "Lunch?"]] }),
+ "a".repeat(500)
+ );
+ expect(f).toEqual({ format: "message", automation: "human", reach: "direct" });
+ });
+
+ it("classifies a GitHub notification", () => {
+ const f = gmailFacets(
+ msg({
+ headers: [["From", "notifications@github.com"], ["To", "me@x.com"], ["Subject", "[repo] PR merged"]],
+ labelIds: ["CATEGORY_UPDATES"],
+ }),
+ "short"
+ );
+ expect(f.format).toBe("notification");
+ expect(f.automation).toBe("automated");
+ });
+});

connectors/gmail/src/gmail-facets.ts

@@ -0,0 +1,35 @@
+import { classifyEmail, type EmailSignals } from "@plotday/email-classifier";
+import type { ThreadFacets } from "@plotday/twister/facets";
+import { getHeader, parseEmailAddress, parseEmailAddresses, type GmailMessage } from "./gmail-api";
+
+const GMAIL_CATEGORY_LABELS = new Set([
+ "CATEGORY_PROMOTIONS",
+ "CATEGORY_UPDATES",
+ "CATEGORY_SOCIAL",
+ "CATEGORY_FORUMS",
+ "CATEGORY_PERSONAL",
+]);
+
+/**
+ * Compute facets for a Gmail message. `bodyText` is the extracted body used
+ * for the length heuristic (pass the same string the note will carry).
+ */
+export function gmailFacets(message: GmailMessage, bodyText: string): ThreadFacets {
+ const signals: EmailSignals = {
+ listId: getHeader(message, "List-Id"),
+ listUnsubscribe: getHeader(message, "List-Unsubscribe"),
+ precedence: getHeader(message, "Precedence"),
+ autoSubmitted: getHeader(message, "Auto-Submitted"),
+ returnPath: getHeader(message, "Return-Path"),
+ importance: getHeader(message, "Importance") ?? getHeader(message, "X-Priority"),
+ fromAddress: parseEmailAddress(getHeader(message, "From") ?? "")?.email.toLowerCase() ?? null,
+ recipientCount:
+ parseEmailAddresses(getHeader(message, "To")).length +
+ parseEmailAddresses(getHeader(message, "Cc")).length,
+ isReply: getHeader(message, "In-Reply-To") !== null || getHeader(message, "References") !== null,
+ subject: getHeader(message, "Subject"),
+ bodyLength: bodyText.length,
+ gmailCategories: (message.labelIds ?? []).filter((l) => GMAIL_CATEGORY_LABELS.has(l)),
+ };
+ return classifyEmail(signals);
+}

connectors/gmail/src/gmail.ts

@@ -35,6 +35,7 @@ import {
  syncGmailMailboxIncremental,
  transformGmailThread,
 } from "./gmail-api";
+import { gmailFacets } from "./gmail-facets";
 
 /**
  * Persisted mailbox-wide watch state. Gmail allows one watch per (mailbox,
@@ -1350,6 +1351,18 @@ export class Gmail extends Connector<Gmail> {
  syncableId: channelId,
  };
 
+ // Compute classifier facets from the parent message's headers + body.
+ const facetParent = thread.messages.find((m) => !m.labelIds?.includes("DRAFT"));
+ if (facetParent) {
+ // Use the parent message's full note body (not the short preview snippet)
+ // so the classifier's reading-vs-notification length split can fire.
+ const facetNote = plotThread.notes?.find(
+ (n) => "key" in n && (n as { key: string }).key === facetParent.id
+ );
+ const facetBody = facetNote?.content ?? plotThread.preview ?? "";
+ plotThread.facets = gmailFacets(facetParent, facetBody);
+ }
+
  // Star ↔ todo sync: detect star changes and sync to Plot todo status.
  // Statuses have been removed; every thread (including archived) is saved
  // with no status and treated like any other thread.

connectors/slack/src/slack-facets.test.ts

@@ -0,0 +1,32 @@
+import { describe, expect, it } from "vitest";
+import { slackFacets } from "./slack-facets";
+import type { SlackMessage } from "./slack-api";
+
+function m(overrides: Partial<SlackMessage> = {}): SlackMessage {
+ return { type: "message", ts: "1.0", text: "hi", ...overrides };
+}
+
+describe("slackFacets", () => {
+ it("treats a DM human message as chat/human/direct", () => {
+ expect(slackFacets(m({ user: "U1", text: "hey there" }), "D123")).toEqual({
+ format: "chat",
+ automation: "human",
+ reach: "direct",
+ });
+ });
+ it("treats a channel post as reach=list", () => {
+ expect(slackFacets(m({ user: "U1" }), "C123").reach).toBe("list");
+ });
+ it("flags a bot message automated", () => {
+ expect(slackFacets(m({ bot_id: "B1", subtype: "bot_message" }), "C123").automation).toBe("automated");
+ });
+ it("a long post becomes a message, not chat", () => {
+ expect(slackFacets(m({ user: "U1", text: "x".repeat(1500) }), "C123").format).toBe("message");
+ });
+ it("treats a group DM (G-prefix) as reach=direct", () => {
+ expect(slackFacets(m({ user: "U1" }), "G123").reach).toBe("direct");
+ });
+ it("treats a message with no user as automated", () => {
+ expect(slackFacets(m({ user: undefined }), "C123").automation).toBe("automated");
+ });
+});

connectors/slack/src/slack-facets.ts

@@ -0,0 +1,30 @@
+import type { ThreadFacets } from "@plotday/twister/facets";
+import type { SlackMessage } from "./slack-api";
+
+// Reach is inferred from the channelId prefix (the channel object isn't in
+// scope at save time):
+// C = public or modern private channel → list (broadcast context)
+// G = group/MPIM OR legacy (pre-2020) private → treated as direct (best-effort;
+// an old private channel is misread as direct, acceptable under fail-open)
+// D = IM (DM) → direct
+function reachForChannel(channelId: string): "direct" | "list" {
+ return channelId.startsWith("C") ? "list" : "direct";
+}
+
+// A long Slack post reads as a "message" rather than a quick "chat".
+const CHAT_MAX_LENGTH = 1000;
+
+/**
+ * Compute facets for a Slack thread's parent message. Channel kind is inferred
+ * from the channelId prefix (the full channel object is not in scope at save
+ * time); this is best-effort per the facet design's fail-open principle.
+ */
+export function slackFacets(parent: SlackMessage, channelId: string): ThreadFacets {
+ const isBot = Boolean(parent.bot_id) || parent.subtype === "bot_message" || !parent.user;
+ const text = parent.text ?? "";
+ return {
+ format: text.length > CHAT_MAX_LENGTH ? "message" : "chat",
+ automation: isBot ? "automated" : "human",
+ reach: reachForChannel(channelId),
+ };
+}

connectors/slack/src/slack.ts

@@ -41,6 +41,7 @@ import {
  transformSlackThread,
 } from "./slack-api";
 import { unicodeToSlackName } from "./slack-emoji";
+import { slackFacets } from "./slack-facets";
 
 /**
  * Slack integration source.
@@ -503,6 +504,7 @@ export class Slack extends Connector<Slack> {
  syncProvider: "slack",
  syncableId: channelId,
  };
+ if (thread[0]) activityThread.facets = slackFacets(thread[0], channelId);
 
  // Save link directly via integrations
  await this.tools.integrations.saveLink(activityThread);
@@ -686,6 +688,7 @@ export class Slack extends Connector<Slack> {
  syncProvider: "slack",
  syncableId: channelId,
  };
+ if (messages[0]) link.facets = slackFacets(messages[0], channelId);
  await this.tools.integrations.saveLink(link);
  }
 
@@ -913,6 +916,7 @@ export class Slack extends Connector<Slack> {
  syncProvider: "slack",
  syncableId: channelId,
  };
+ if (messages[0]) link.facets = slackFacets(messages[0], channelId);
 
  // Suppress the onThreadToDo echo Plot will fire from this write;
  // handleStarEvent / backfillStars is already the source of truth.

libs/email-classifier/package.json

@@ -0,0 +1,30 @@
+{
+ "name": "@plotday/email-classifier",
+ "private": true,
+ "version": "0.1.0",
+ "type": "module",
+ "main": "./dist/index.js",
+ "types": "./dist/index.d.ts",
+ "exports": {
+ ".": {
+ "@plotday/connector": "./src/index.ts",
+ "types": "./dist/index.d.ts",
+ "default": "./dist/index.js"
+ }
+ },
+ "files": ["dist", "README.md"],
+ "scripts": {
+ "build": "tsc",
+ "clean": "rm -rf dist",
+ "lint": "tsc --noEmit",
+ "test": "vitest run",
+ "test:watch": "vitest"
+ },
+ "dependencies": {
+ "@plotday/twister": "workspace:^"
+ },
+ "devDependencies": {
+ "typescript": "^5.9.3",
+ "vitest": "^2.1.8"
+ }
+}

libs/email-classifier/src/classify-email.test.ts

@@ -0,0 +1,88 @@
+import { describe, expect, it } from "vitest";
+import { classifyEmail, type EmailSignals } from "./classify-email";
+
+function signals(overrides: Partial<EmailSignals> = {}): EmailSignals {
+ return {
+ listId: null,
+ listUnsubscribe: null,
+ precedence: null,
+ autoSubmitted: null,
+ returnPath: null,
+ importance: null,
+ fromAddress: "jane@example.com",
+ recipientCount: 1,
+ isReply: false,
+ subject: "Hello",
+ bodyLength: 300,
+ gmailCategories: [],
+ ...overrides,
+ };
+}
+
+describe("classifyEmail — automation", () => {
+ it("flags no-reply senders automated", () => {
+ expect(classifyEmail(signals({ fromAddress: "no-reply@acme.com" })).automation).toBe("automated");
+ });
+ it("flags Precedence: bulk automated", () => {
+ expect(classifyEmail(signals({ precedence: "bulk" })).automation).toBe("automated");
+ });
+ it("flags Auto-Submitted automated", () => {
+ expect(classifyEmail(signals({ autoSubmitted: "auto-generated" })).automation).toBe("automated");
+ });
+ it("flags mailing-list mail automated", () => {
+ expect(classifyEmail(signals({ listId: "<news.acme.com>" })).automation).toBe("automated");
+ });
+ it("treats a plain person email as human", () => {
+ expect(classifyEmail(signals()).automation).toBe("human");
+ });
+});
+
+describe("classifyEmail — reach", () => {
+ it("flags List-Id as list", () => {
+ expect(classifyEmail(signals({ listId: "<news.acme.com>" })).reach).toBe("list");
+ });
+ it("flags List-Unsubscribe as list", () => {
+ expect(classifyEmail(signals({ listUnsubscribe: "<mailto:u@acme.com>" })).reach).toBe("list");
+ });
+ it("flags high recipient count as list", () => {
+ expect(classifyEmail(signals({ recipientCount: 12 })).reach).toBe("list");
+ });
+ it("treats a 1:1 email as direct", () => {
+ expect(classifyEmail(signals()).reach).toBe("direct");
+ });
+});
+
+describe("classifyEmail — format", () => {
+ it("invoice from subject keywords", () => {
+ expect(classifyEmail(signals({ subject: "Your invoice is due", fromAddress: "billing@acme.com" })).format).toBe("invoice");
+ });
+ it("receipt from subject keywords", () => {
+ expect(classifyEmail(signals({ subject: "Your order confirmation #1234", fromAddress: "orders@shop.com" })).format).toBe("receipt");
+ });
+ it("promotion from Gmail category", () => {
+ expect(classifyEmail(signals({ gmailCategories: ["CATEGORY_PROMOTIONS"], listUnsubscribe: "<x>" })).format).toBe("promotion");
+ });
+ it("reading from a long list email", () => {
+ expect(
+ classifyEmail(signals({ listId: "<news>", listUnsubscribe: "<x>", bodyLength: 4000, subject: "Weekly digest" })).format
+ ).toBe("reading");
+ });
+ it("notification from a short automated update", () => {
+ expect(
+ classifyEmail(signals({ fromAddress: "notifications@github.com", bodyLength: 200, gmailCategories: ["CATEGORY_UPDATES"] })).format
+ ).toBe("notification");
+ });
+ it("message for a normal human email", () => {
+ expect(classifyEmail(signals({ bodyLength: 800 })).format).toBe("message");
+ });
+ it("classifies a short automated email as a notification", () => {
+ expect(classifyEmail(signals({ fromAddress: "no-reply@x.com", bodyLength: 0, subject: null })).format).toBe("notification");
+ });
+ it("leaves format null when no heuristic is confident", () => {
+ // automated (auto_reply) but long body, direct, no categories, neutral subject →
+ // none of the format branches fire → null.
+ expect(
+ classifyEmail(signals({ precedence: "auto_reply", bodyLength: 900, subject: "Re: status" })).format
+ ).toBeNull();
+ });
+});

.changeset/facets-sdk.md

@@ -0,0 +1,5 @@
+---
+"@plotday/twister": minor
+---
+
+Added: `@plotday/twister/facets` exporting `Format`, `Automation`, `Reach`, and `ThreadFacets` for connector-emitted thread facets, and `NewLink.facets` to carry them.

connectors/gmail/package.json

@@ -30,6 +30,7 @@
  },
  "dependencies": {
  "@plotday/connector-google-contacts": "workspace:^",
+ "@plotday/email-classifier": "workspace:^",
  "@plotday/twister": "workspace:^"
  },
  "devDependencies": {

connectors/gmail/src/gmail-facets.test.ts

@@ -0,0 +1,60 @@
+import { describe, expect, it } from "vitest";
+import { gmailFacets } from "./gmail-facets";
+import type { GmailMessage } from "./gmail-api";
+
+function msg(opts: {
+ headers: Array<[string, string]>;
+ labelIds?: string[];
+}): GmailMessage {
+ return {
+ id: "m1",
+ threadId: "t1",
+ labelIds: opts.labelIds ?? [],
+ snippet: "",
+ historyId: "1",
+ internalDate: "1700000000000",
+ sizeEstimate: 0,
+ payload: {
+ mimeType: "text/plain",
+ headers: opts.headers.map(([name, value]) => ({ name, value })),
+ },
+ };
+}
+
+describe("gmailFacets", () => {
+ it("classifies a newsletter as reading/automated/list", () => {
+ const f = gmailFacets(
+ msg({
+ headers: [
+ ["From", "news@substack.com"],
+ ["To", "me@x.com"],
+ ["Subject", "The Weekly Digest"],
+ ["List-Id", "<news.substack.com>"],
+ ["List-Unsubscribe", "<mailto:u@substack.com>"],
+ ],
+ }),
+ "a".repeat(4000)
+ );
+ expect(f).toEqual({ format: "reading", automation: "automated", reach: "list" });
+ });
+
+ it("classifies a personal 1:1 email as message/human/direct", () => {
+ const f = gmailFacets(
+ msg({ headers: [["From", "jane@friends.com"], ["To", "me@x.com"], ["Subject", "Lunch?"]] }),
+ "a".repeat(500)
+ );
+ expect(f).toEqual({ format: "message", automation: "human", reach: "direct" });
+ });
+
+ it("classifies a GitHub notification", () => {
+ const f = gmailFacets(
+ msg({
+ headers: [["From", "notifications@github.com"], ["To", "me@x.com"], ["Subject", "[repo] PR merged"]],
+ labelIds: ["CATEGORY_UPDATES"],
+ }),
+ "short"
+ );
+ expect(f.format).toBe("notification");
+ expect(f.automation).toBe("automated");
+ });
+});

connectors/gmail/src/gmail-facets.ts

@@ -0,0 +1,35 @@
+import { classifyEmail, type EmailSignals } from "@plotday/email-classifier";
+import type { ThreadFacets } from "@plotday/twister/facets";
+import { getHeader, parseEmailAddress, parseEmailAddresses, type GmailMessage } from "./gmail-api";
+
+const GMAIL_CATEGORY_LABELS = new Set([
+ "CATEGORY_PROMOTIONS",
+ "CATEGORY_UPDATES",
+ "CATEGORY_SOCIAL",
+ "CATEGORY_FORUMS",
+ "CATEGORY_PERSONAL",
+]);
+
+/**
+ * Compute facets for a Gmail message. `bodyText` is the extracted body used
+ * for the length heuristic (pass the same string the note will carry).
+ */
+export function gmailFacets(message: GmailMessage, bodyText: string): ThreadFacets {
+ const signals: EmailSignals = {
+ listId: getHeader(message, "List-Id"),
+ listUnsubscribe: getHeader(message, "List-Unsubscribe"),
+ precedence: getHeader(message, "Precedence"),
+ autoSubmitted: getHeader(message, "Auto-Submitted"),
+ returnPath: getHeader(message, "Return-Path"),
+ importance: getHeader(message, "Importance") ?? getHeader(message, "X-Priority"),
+ fromAddress: parseEmailAddress(getHeader(message, "From") ?? "")?.email.toLowerCase() ?? null,
+ recipientCount:
+ parseEmailAddresses(getHeader(message, "To")).length +
+ parseEmailAddresses(getHeader(message, "Cc")).length,
+ isReply: getHeader(message, "In-Reply-To") !== null || getHeader(message, "References") !== null,
+ subject: getHeader(message, "Subject"),
+ bodyLength: bodyText.length,
+ gmailCategories: (message.labelIds ?? []).filter((l) => GMAIL_CATEGORY_LABELS.has(l)),
+ };
+ return classifyEmail(signals);
+}

connectors/gmail/src/gmail.ts

@@ -35,6 +35,7 @@ import {
  syncGmailMailboxIncremental,
  transformGmailThread,
 } from "./gmail-api";
+import { gmailFacets } from "./gmail-facets";
 
 /**
  * Persisted mailbox-wide watch state. Gmail allows one watch per (mailbox,
@@ -1350,6 +1351,18 @@ export class Gmail extends Connector<Gmail> {
  syncableId: channelId,
  };
 
+ // Compute classifier facets from the parent message's headers + body.
+ const facetParent = thread.messages.find((m) => !m.labelIds?.includes("DRAFT"));
+ if (facetParent) {
+ // Use the parent message's full note body (not the short preview snippet)
+ // so the classifier's reading-vs-notification length split can fire.
+ const facetNote = plotThread.notes?.find(
+ (n) => "key" in n && (n as { key: string }).key === facetParent.id
+ );
+ const facetBody = facetNote?.content ?? plotThread.preview ?? "";
+ plotThread.facets = gmailFacets(facetParent, facetBody);
+ }
+
  // Star ↔ todo sync: detect star changes and sync to Plot todo status.
  // Statuses have been removed; every thread (including archived) is saved
  // with no status and treated like any other thread.

connectors/slack/src/slack-facets.test.ts

@@ -0,0 +1,32 @@
+import { describe, expect, it } from "vitest";
+import { slackFacets } from "./slack-facets";
+import type { SlackMessage } from "./slack-api";
+
+function m(overrides: Partial<SlackMessage> = {}): SlackMessage {
+ return { type: "message", ts: "1.0", text: "hi", ...overrides };
+}
+
+describe("slackFacets", () => {
+ it("treats a DM human message as chat/human/direct", () => {
+ expect(slackFacets(m({ user: "U1", text: "hey there" }), "D123")).toEqual({
+ format: "chat",
+ automation: "human",
+ reach: "direct",
+ });
+ });
+ it("treats a channel post as reach=list", () => {
+ expect(slackFacets(m({ user: "U1" }), "C123").reach).toBe("list");
+ });
+ it("flags a bot message automated", () => {
+ expect(slackFacets(m({ bot_id: "B1", subtype: "bot_message" }), "C123").automation).toBe("automated");
+ });
+ it("a long post becomes a message, not chat", () => {
+ expect(slackFacets(m({ user: "U1", text: "x".repeat(1500) }), "C123").format).toBe("message");
+ });
+ it("treats a group DM (G-prefix) as reach=direct", () => {
+ expect(slackFacets(m({ user: "U1" }), "G123").reach).toBe("direct");
+ });
+ it("treats a message with no user as automated", () => {
+ expect(slackFacets(m({ user: undefined }), "C123").automation).toBe("automated");
+ });
+});

connectors/slack/src/slack-facets.ts

@@ -0,0 +1,30 @@
+import type { ThreadFacets } from "@plotday/twister/facets";
+import type { SlackMessage } from "./slack-api";
+
+// Reach is inferred from the channelId prefix (the channel object isn't in
+// scope at save time):
+// C = public or modern private channel → list (broadcast context)
+// G = group/MPIM OR legacy (pre-2020) private → treated as direct (best-effort;
+// an old private channel is misread as direct, acceptable under fail-open)
+// D = IM (DM) → direct
+function reachForChannel(channelId: string): "direct" | "list" {
+ return channelId.startsWith("C") ? "list" : "direct";
+}
+
+// A long Slack post reads as a "message" rather than a quick "chat".
+const CHAT_MAX_LENGTH = 1000;
+
+/**
+ * Compute facets for a Slack thread's parent message. Channel kind is inferred
+ * from the channelId prefix (the full channel object is not in scope at save
+ * time); this is best-effort per the facet design's fail-open principle.
+ */
+export function slackFacets(parent: SlackMessage, channelId: string): ThreadFacets {
+ const isBot = Boolean(parent.bot_id) || parent.subtype === "bot_message" || !parent.user;
+ const text = parent.text ?? "";
+ return {
+ format: text.length > CHAT_MAX_LENGTH ? "message" : "chat",
+ automation: isBot ? "automated" : "human",
+ reach: reachForChannel(channelId),
+ };
+}

connectors/slack/src/slack.ts

@@ -41,6 +41,7 @@ import {
  transformSlackThread,
 } from "./slack-api";
 import { unicodeToSlackName } from "./slack-emoji";
+import { slackFacets } from "./slack-facets";
 
 /**
  * Slack integration source.
@@ -503,6 +504,7 @@ export class Slack extends Connector<Slack> {
  syncProvider: "slack",
  syncableId: channelId,
  };
+ if (thread[0]) activityThread.facets = slackFacets(thread[0], channelId);
 
  // Save link directly via integrations
  await this.tools.integrations.saveLink(activityThread);
@@ -686,6 +688,7 @@ export class Slack extends Connector<Slack> {
  syncProvider: "slack",
  syncableId: channelId,
  };
+ if (messages[0]) link.facets = slackFacets(messages[0], channelId);
  await this.tools.integrations.saveLink(link);
  }
 
@@ -913,6 +916,7 @@ export class Slack extends Connector<Slack> {
  syncProvider: "slack",
  syncableId: channelId,
  };
+ if (messages[0]) link.facets = slackFacets(messages[0], channelId);
 
  // Suppress the onThreadToDo echo Plot will fire from this write;
  // handleStarEvent / backfillStars is already the source of truth.

libs/email-classifier/package.json

@@ -0,0 +1,30 @@
+{
+ "name": "@plotday/email-classifier",
+ "private": true,
+ "version": "0.1.0",
+ "type": "module",
+ "main": "./dist/index.js",
+ "types": "./dist/index.d.ts",
+ "exports": {
+ ".": {
+ "@plotday/connector": "./src/index.ts",
+ "types": "./dist/index.d.ts",
+ "default": "./dist/index.js"
+ }
+ },
+ "files": ["dist", "README.md"],
+ "scripts": {
+ "build": "tsc",
+ "clean": "rm -rf dist",
+ "lint": "tsc --noEmit",
+ "test": "vitest run",
+ "test:watch": "vitest"
+ },
+ "dependencies": {
+ "@plotday/twister": "workspace:^"
+ },
+ "devDependencies": {
+ "typescript": "^5.9.3",
+ "vitest": "^2.1.8"
+ }
+}

libs/email-classifier/src/classify-email.test.ts

@@ -0,0 +1,88 @@
+import { describe, expect, it } from "vitest";
+import { classifyEmail, type EmailSignals } from "./classify-email";
+
+function signals(overrides: Partial<EmailSignals> = {}): EmailSignals {
+ return {
+ listId: null,
+ listUnsubscribe: null,
+ precedence: null,
+ autoSubmitted: null,
+ returnPath: null,
+ importance: null,
+ fromAddress: "jane@example.com",
+ recipientCount: 1,
+ isReply: false,
+ subject: "Hello",
+ bodyLength: 300,
+ gmailCategories: [],
+ ...overrides,
+ };
+}
+
+describe("classifyEmail — automation", () => {
+ it("flags no-reply senders automated", () => {
+ expect(classifyEmail(signals({ fromAddress: "no-reply@acme.com" })).automation).toBe("automated");
+ });
+ it("flags Precedence: bulk automated", () => {
+ expect(classifyEmail(signals({ precedence: "bulk" })).automation).toBe("automated");
+ });
+ it("flags Auto-Submitted automated", () => {
+ expect(classifyEmail(signals({ autoSubmitted: "auto-generated" })).automation).toBe("automated");
+ });
+ it("flags mailing-list mail automated", () => {
+ expect(classifyEmail(signals({ listId: "<news.acme.com>" })).automation).toBe("automated");
+ });
+ it("treats a plain person email as human", () => {
+ expect(classifyEmail(signals()).automation).toBe("human");
+ });
+});
+
+describe("classifyEmail — reach", () => {
+ it("flags List-Id as list", () => {
+ expect(classifyEmail(signals({ listId: "<news.acme.com>" })).reach).toBe("list");
+ });
+ it("flags List-Unsubscribe as list", () => {
+ expect(classifyEmail(signals({ listUnsubscribe: "<mailto:u@acme.com>" })).reach).toBe("list");
+ });
+ it("flags high recipient count as list", () => {
+ expect(classifyEmail(signals({ recipientCount: 12 })).reach).toBe("list");
+ });
+ it("treats a 1:1 email as direct", () => {
+ expect(classifyEmail(signals()).reach).toBe("direct");
+ });
+});
+
+describe("classifyEmail — format", () => {
+ it("invoice from subject keywords", () => {
+ expect(classifyEmail(signals({ subject: "Your invoice is due", fromAddress: "billing@acme.com" })).format).toBe("invoice");
+ });
+ it("receipt from subject keywords", () => {
+ expect(classifyEmail(signals({ subject: "Your order confirmation #1234", fromAddress: "orders@shop.com" })).format).toBe("receipt");
+ });
+ it("promotion from Gmail category", () => {
+ expect(classifyEmail(signals({ gmailCategories: ["CATEGORY_PROMOTIONS"], listUnsubscribe: "<x>" })).format).toBe("promotion");
+ });
+ it("reading from a long list email", () => {
+ expect(
+ classifyEmail(signals({ listId: "<news>", listUnsubscribe: "<x>", bodyLength: 4000, subject: "Weekly digest" })).format
+ ).toBe("reading");
+ });
+ it("notification from a short automated update", () => {
+ expect(
+ classifyEmail(signals({ fromAddress: "notifications@github.com", bodyLength: 200, gmailCategories: ["CATEGORY_UPDATES"] })).format
+ ).toBe("notification");
+ });
+ it("message for a normal human email", () => {
+ expect(classifyEmail(signals({ bodyLength: 800 })).format).toBe("message");
+ });
+ it("classifies a short automated email as a notification", () => {
+ expect(classifyEmail(signals({ fromAddress: "no-reply@x.com", bodyLength: 0, subject: null })).format).toBe("notification");
+ });
+ it("leaves format null when no heuristic is confident", () => {
+ // automated (auto_reply) but long body, direct, no categories, neutral subject →
+ // none of the format branches fire → null.
+ expect(
+ classifyEmail(signals({ precedence: "auto_reply", bodyLength: 900, subject: "Re: status" })).format
+ ).toBeNull();
+ });
+});

.changeset/facets-sdk.md

@@ -0,0 +1,5 @@
+---
+"@plotday/twister": minor
+---
+
+Added: `@plotday/twister/facets` exporting `Format`, `Automation`, `Reach`, and `ThreadFacets` for connector-emitted thread facets, and `NewLink.facets` to carry them.

connectors/gmail/package.json

@@ -30,6 +30,7 @@
  },
  "dependencies": {
  "@plotday/connector-google-contacts": "workspace:^",
+ "@plotday/email-classifier": "workspace:^",
  "@plotday/twister": "workspace:^"
  },
  "devDependencies": {

connectors/gmail/src/gmail-facets.test.ts

@@ -0,0 +1,60 @@
+import { describe, expect, it } from "vitest";
+import { gmailFacets } from "./gmail-facets";
+import type { GmailMessage } from "./gmail-api";
+
+function msg(opts: {
+ headers: Array<[string, string]>;
+ labelIds?: string[];
+}): GmailMessage {
+ return {
+ id: "m1",
+ threadId: "t1",
+ labelIds: opts.labelIds ?? [],
+ snippet: "",
+ historyId: "1",
+ internalDate: "1700000000000",
+ sizeEstimate: 0,
+ payload: {
+ mimeType: "text/plain",
+ headers: opts.headers.map(([name, value]) => ({ name, value })),
+ },
+ };
+}
+
+describe("gmailFacets", () => {
+ it("classifies a newsletter as reading/automated/list", () => {
+ const f = gmailFacets(
+ msg({
+ headers: [
+ ["From", "news@substack.com"],
+ ["To", "me@x.com"],
+ ["Subject", "The Weekly Digest"],
+ ["List-Id", "<news.substack.com>"],
+ ["List-Unsubscribe", "<mailto:u@substack.com>"],
+ ],
+ }),
+ "a".repeat(4000)
+ );
+ expect(f).toEqual({ format: "reading", automation: "automated", reach: "list" });
+ });
+
+ it("classifies a personal 1:1 email as message/human/direct", () => {
+ const f = gmailFacets(
+ msg({ headers: [["From", "jane@friends.com"], ["To", "me@x.com"], ["Subject", "Lunch?"]] }),
+ "a".repeat(500)
+ );
+ expect(f).toEqual({ format: "message", automation: "human", reach: "direct" });
+ });
+
+ it("classifies a GitHub notification", () => {
+ const f = gmailFacets(
+ msg({
+ headers: [["From", "notifications@github.com"], ["To", "me@x.com"], ["Subject", "[repo] PR merged"]],
+ labelIds: ["CATEGORY_UPDATES"],
+ }),
+ "short"
+ );
+ expect(f.format).toBe("notification");
+ expect(f.automation).toBe("automated");
+ });
+});

connectors/gmail/src/gmail-facets.ts

@@ -0,0 +1,35 @@
+import { classifyEmail, type EmailSignals } from "@plotday/email-classifier";
+import type { ThreadFacets } from "@plotday/twister/facets";
+import { getHeader, parseEmailAddress, parseEmailAddresses, type GmailMessage } from "./gmail-api";
+
+const GMAIL_CATEGORY_LABELS = new Set([
+ "CATEGORY_PROMOTIONS",
+ "CATEGORY_UPDATES",
+ "CATEGORY_SOCIAL",
+ "CATEGORY_FORUMS",
+ "CATEGORY_PERSONAL",
+]);
+
+/**
+ * Compute facets for a Gmail message. `bodyText` is the extracted body used
+ * for the length heuristic (pass the same string the note will carry).
+ */
+export function gmailFacets(message: GmailMessage, bodyText: string): ThreadFacets {
+ const signals: EmailSignals = {
+ listId: getHeader(message, "List-Id"),
+ listUnsubscribe: getHeader(message, "List-Unsubscribe"),
+ precedence: getHeader(message, "Precedence"),
+ autoSubmitted: getHeader(message, "Auto-Submitted"),
+ returnPath: getHeader(message, "Return-Path"),
+ importance: getHeader(message, "Importance") ?? getHeader(message, "X-Priority"),
+ fromAddress: parseEmailAddress(getHeader(message, "From") ?? "")?.email.toLowerCase() ?? null,
+ recipientCount:
+ parseEmailAddresses(getHeader(message, "To")).length +
+ parseEmailAddresses(getHeader(message, "Cc")).length,
+ isReply: getHeader(message, "In-Reply-To") !== null || getHeader(message, "References") !== null,
+ subject: getHeader(message, "Subject"),
+ bodyLength: bodyText.length,
+ gmailCategories: (message.labelIds ?? []).filter((l) => GMAIL_CATEGORY_LABELS.has(l)),
+ };
+ return classifyEmail(signals);
+}

connectors/gmail/src/gmail.ts

@@ -35,6 +35,7 @@ import {
  syncGmailMailboxIncremental,
  transformGmailThread,
 } from "./gmail-api";
+import { gmailFacets } from "./gmail-facets";
 
 /**
  * Persisted mailbox-wide watch state. Gmail allows one watch per (mailbox,
@@ -1350,6 +1351,18 @@ export class Gmail extends Connector<Gmail> {
  syncableId: channelId,
  };
 
+ // Compute classifier facets from the parent message's headers + body.
+ const facetParent = thread.messages.find((m) => !m.labelIds?.includes("DRAFT"));
+ if (facetParent) {
+ // Use the parent message's full note body (not the short preview snippet)
+ // so the classifier's reading-vs-notification length split can fire.
+ const facetNote = plotThread.notes?.find(
+ (n) => "key" in n && (n as { key: string }).key === facetParent.id
+ );
+ const facetBody = facetNote?.content ?? plotThread.preview ?? "";
+ plotThread.facets = gmailFacets(facetParent, facetBody);
+ }
+
  // Star ↔ todo sync: detect star changes and sync to Plot todo status.
  // Statuses have been removed; every thread (including archived) is saved
  // with no status and treated like any other thread.

connectors/slack/src/slack-facets.test.ts

@@ -0,0 +1,32 @@
+import { describe, expect, it } from "vitest";
+import { slackFacets } from "./slack-facets";
+import type { SlackMessage } from "./slack-api";
+
+function m(overrides: Partial<SlackMessage> = {}): SlackMessage {
+ return { type: "message", ts: "1.0", text: "hi", ...overrides };
+}
+
+describe("slackFacets", () => {
+ it("treats a DM human message as chat/human/direct", () => {
+ expect(slackFacets(m({ user: "U1", text: "hey there" }), "D123")).toEqual({
+ format: "chat",
+ automation: "human",
+ reach: "direct",
+ });
+ });
+ it("treats a channel post as reach=list", () => {
+ expect(slackFacets(m({ user: "U1" }), "C123").reach).toBe("list");
+ });
+ it("flags a bot message automated", () => {
+ expect(slackFacets(m({ bot_id: "B1", subtype: "bot_message" }), "C123").automation).toBe("automated");
+ });
+ it("a long post becomes a message, not chat", () => {
+ expect(slackFacets(m({ user: "U1", text: "x".repeat(1500) }), "C123").format).toBe("message");
+ });
+ it("treats a group DM (G-prefix) as reach=direct", () => {
+ expect(slackFacets(m({ user: "U1" }), "G123").reach).toBe("direct");
+ });
+ it("treats a message with no user as automated", () => {
+ expect(slackFacets(m({ user: undefined }), "C123").automation).toBe("automated");
+ });
+});

connectors/slack/src/slack-facets.ts

@@ -0,0 +1,30 @@
+import type { ThreadFacets } from "@plotday/twister/facets";
+import type { SlackMessage } from "./slack-api";
+
+// Reach is inferred from the channelId prefix (the channel object isn't in
+// scope at save time):
+// C = public or modern private channel → list (broadcast context)
+// G = group/MPIM OR legacy (pre-2020) private → treated as direct (best-effort;
+// an old private channel is misread as direct, acceptable under fail-open)
+// D = IM (DM) → direct
+function reachForChannel(channelId: string): "direct" | "list" {
+ return channelId.startsWith("C") ? "list" : "direct";
+}
+
+// A long Slack post reads as a "message" rather than a quick "chat".
+const CHAT_MAX_LENGTH = 1000;
+
+/**
+ * Compute facets for a Slack thread's parent message. Channel kind is inferred
+ * from the channelId prefix (the full channel object is not in scope at save
+ * time); this is best-effort per the facet design's fail-open principle.
+ */
+export function slackFacets(parent: SlackMessage, channelId: string): ThreadFacets {
+ const isBot = Boolean(parent.bot_id) || parent.subtype === "bot_message" || !parent.user;
+ const text = parent.text ?? "";
+ return {
+ format: text.length > CHAT_MAX_LENGTH ? "message" : "chat",
+ automation: isBot ? "automated" : "human",
+ reach: reachForChannel(channelId),
+ };
+}

connectors/slack/src/slack.ts

@@ -41,6 +41,7 @@ import {
  transformSlackThread,
 } from "./slack-api";
 import { unicodeToSlackName } from "./slack-emoji";
+import { slackFacets } from "./slack-facets";
 
 /**
  * Slack integration source.
@@ -503,6 +504,7 @@ export class Slack extends Connector<Slack> {
  syncProvider: "slack",
  syncableId: channelId,
  };
+ if (thread[0]) activityThread.facets = slackFacets(thread[0], channelId);
 
  // Save link directly via integrations
  await this.tools.integrations.saveLink(activityThread);
@@ -686,6 +688,7 @@ export class Slack extends Connector<Slack> {
  syncProvider: "slack",
  syncableId: channelId,
  };
+ if (messages[0]) link.facets = slackFacets(messages[0], channelId);
  await this.tools.integrations.saveLink(link);
  }
 
@@ -913,6 +916,7 @@ export class Slack extends Connector<Slack> {
  syncProvider: "slack",
  syncableId: channelId,
  };
+ if (messages[0]) link.facets = slackFacets(messages[0], channelId);
 
  // Suppress the onThreadToDo echo Plot will fire from this write;
  // handleStarEvent / backfillStars is already the source of truth.

libs/email-classifier/package.json

@@ -0,0 +1,30 @@
+{
+ "name": "@plotday/email-classifier",
+ "private": true,
+ "version": "0.1.0",
+ "type": "module",
+ "main": "./dist/index.js",
+ "types": "./dist/index.d.ts",
+ "exports": {
+ ".": {
+ "@plotday/connector": "./src/index.ts",
+ "types": "./dist/index.d.ts",
+ "default": "./dist/index.js"
+ }
+ },
+ "files": ["dist", "README.md"],
+ "scripts": {
+ "build": "tsc",
+ "clean": "rm -rf dist",
+ "lint": "tsc --noEmit",
+ "test": "vitest run",
+ "test:watch": "vitest"
+ },
+ "dependencies": {
+ "@plotday/twister": "workspace:^"
+ },
+ "devDependencies": {
+ "typescript": "^5.9.3",
+ "vitest": "^2.1.8"
+ }
+}

libs/email-classifier/src/classify-email.test.ts

@@ -0,0 +1,88 @@
+import { describe, expect, it } from "vitest";
+import { classifyEmail, type EmailSignals } from "./classify-email";
+
+function signals(overrides: Partial<EmailSignals> = {}): EmailSignals {
+ return {
+ listId: null,
+ listUnsubscribe: null,
+ precedence: null,
+ autoSubmitted: null,
+ returnPath: null,
+ importance: null,
+ fromAddress: "jane@example.com",
+ recipientCount: 1,
+ isReply: false,
+ subject: "Hello",
+ bodyLength: 300,
+ gmailCategories: [],
+ ...overrides,
+ };
+}
+
+describe("classifyEmail — automation", () => {
+ it("flags no-reply senders automated", () => {
+ expect(classifyEmail(signals({ fromAddress: "no-reply@acme.com" })).automation).toBe("automated");
+ });
+ it("flags Precedence: bulk automated", () => {
+ expect(classifyEmail(signals({ precedence: "bulk" })).automation).toBe("automated");
+ });
+ it("flags Auto-Submitted automated", () => {
+ expect(classifyEmail(signals({ autoSubmitted: "auto-generated" })).automation).toBe("automated");
+ });
+ it("flags mailing-list mail automated", () => {
+ expect(classifyEmail(signals({ listId: "<news.acme.com>" })).automation).toBe("automated");
+ });
+ it("treats a plain person email as human", () => {
+ expect(classifyEmail(signals()).automation).toBe("human");
+ });
+});
+
+describe("classifyEmail — reach", () => {
+ it("flags List-Id as list", () => {
+ expect(classifyEmail(signals({ listId: "<news.acme.com>" })).reach).toBe("list");
+ });
+ it("flags List-Unsubscribe as list", () => {
+ expect(classifyEmail(signals({ listUnsubscribe: "<mailto:u@acme.com>" })).reach).toBe("list");
+ });
+ it("flags high recipient count as list", () => {
+ expect(classifyEmail(signals({ recipientCount: 12 })).reach).toBe("list");
+ });
+ it("treats a 1:1 email as direct", () => {
+ expect(classifyEmail(signals()).reach).toBe("direct");
+ });
+});
+
+describe("classifyEmail — format", () => {
+ it("invoice from subject keywords", () => {
+ expect(classifyEmail(signals({ subject: "Your invoice is due", fromAddress: "billing@acme.com" })).format).toBe("invoice");
+ });
+ it("receipt from subject keywords", () => {
+ expect(classifyEmail(signals({ subject: "Your order confirmation #1234", fromAddress: "orders@shop.com" })).format).toBe("receipt");
+ });
+ it("promotion from Gmail category", () => {
+ expect(classifyEmail(signals({ gmailCategories: ["CATEGORY_PROMOTIONS"], listUnsubscribe: "<x>" })).format).toBe("promotion");
+ });
+ it("reading from a long list email", () => {
+ expect(
+ classifyEmail(signals({ listId: "<news>", listUnsubscribe: "<x>", bodyLength: 4000, subject: "Weekly digest" })).format
+ ).toBe("reading");
+ });
+ it("notification from a short automated update", () => {
+ expect(
+ classifyEmail(signals({ fromAddress: "notifications@github.com", bodyLength: 200, gmailCategories: ["CATEGORY_UPDATES"] })).format
+ ).toBe("notification");
+ });
+ it("message for a normal human email", () => {
+ expect(classifyEmail(signals({ bodyLength: 800 })).format).toBe("message");
+ });
+ it("classifies a short automated email as a notification", () => {
+ expect(classifyEmail(signals({ fromAddress: "no-reply@x.com", bodyLength: 0, subject: null })).format).toBe("notification");
+ });
+ it("leaves format null when no heuristic is confident", () => {
+ // automated (auto_reply) but long body, direct, no categories, neutral subject →
+ // none of the format branches fire → null.
+ expect(
+ classifyEmail(signals({ precedence: "auto_reply", bodyLength: 900, subject: "Re: status" })).format
+ ).toBeNull();
+ });
+});

.changeset/facets-sdk.md

@@ -0,0 +1,5 @@
+---
+"@plotday/twister": minor
+---
+
+Added: `@plotday/twister/facets` exporting `Format`, `Automation`, `Reach`, and `ThreadFacets` for connector-emitted thread facets, and `NewLink.facets` to carry them.

connectors/gmail/package.json

@@ -30,6 +30,7 @@
  },
  "dependencies": {
  "@plotday/connector-google-contacts": "workspace:^",
+ "@plotday/email-classifier": "workspace:^",
  "@plotday/twister": "workspace:^"
  },
  "devDependencies": {

connectors/gmail/src/gmail-facets.test.ts

@@ -0,0 +1,60 @@
+import { describe, expect, it } from "vitest";
+import { gmailFacets } from "./gmail-facets";
+import type { GmailMessage } from "./gmail-api";
+
+function msg(opts: {
+ headers: Array<[string, string]>;
+ labelIds?: string[];
+}): GmailMessage {
+ return {
+ id: "m1",
+ threadId: "t1",
+ labelIds: opts.labelIds ?? [],
+ snippet: "",
+ historyId: "1",
+ internalDate: "1700000000000",
+ sizeEstimate: 0,
+ payload: {
+ mimeType: "text/plain",
+ headers: opts.headers.map(([name, value]) => ({ name, value })),
+ },
+ };
+}
+
+describe("gmailFacets", () => {
+ it("classifies a newsletter as reading/automated/list", () => {
+ const f = gmailFacets(
+ msg({
+ headers: [
+ ["From", "news@substack.com"],
+ ["To", "me@x.com"],
+ ["Subject", "The Weekly Digest"],
+ ["List-Id", "<news.substack.com>"],
+ ["List-Unsubscribe", "<mailto:u@substack.com>"],
+ ],
+ }),
+ "a".repeat(4000)
+ );
+ expect(f).toEqual({ format: "reading", automation: "automated", reach: "list" });
+ });
+
+ it("classifies a personal 1:1 email as message/human/direct", () => {
+ const f = gmailFacets(
+ msg({ headers: [["From", "jane@friends.com"], ["To", "me@x.com"], ["Subject", "Lunch?"]] }),
+ "a".repeat(500)
+ );
+ expect(f).toEqual({ format: "message", automation: "human", reach: "direct" });
+ });
+
+ it("classifies a GitHub notification", () => {
+ const f = gmailFacets(
+ msg({
+ headers: [["From", "notifications@github.com"], ["To", "me@x.com"], ["Subject", "[repo] PR merged"]],
+ labelIds: ["CATEGORY_UPDATES"],
+ }),
+ "short"
+ );
+ expect(f.format).toBe("notification");
+ expect(f.automation).toBe("automated");
+ });
+});

connectors/gmail/src/gmail-facets.ts

@@ -0,0 +1,35 @@
+import { classifyEmail, type EmailSignals } from "@plotday/email-classifier";
+import type { ThreadFacets } from "@plotday/twister/facets";
+import { getHeader, parseEmailAddress, parseEmailAddresses, type GmailMessage } from "./gmail-api";
+
+const GMAIL_CATEGORY_LABELS = new Set([
+ "CATEGORY_PROMOTIONS",
+ "CATEGORY_UPDATES",
+ "CATEGORY_SOCIAL",
+ "CATEGORY_FORUMS",
+ "CATEGORY_PERSONAL",
+]);
+
+/**
+ * Compute facets for a Gmail message. `bodyText` is the extracted body used
+ * for the length heuristic (pass the same string the note will carry).
+ */
+export function gmailFacets(message: GmailMessage, bodyText: string): ThreadFacets {
+ const signals: EmailSignals = {
+ listId: getHeader(message, "List-Id"),
+ listUnsubscribe: getHeader(message, "List-Unsubscribe"),
+ precedence: getHeader(message, "Precedence"),
+ autoSubmitted: getHeader(message, "Auto-Submitted"),
+ returnPath: getHeader(message, "Return-Path"),
+ importance: getHeader(message, "Importance") ?? getHeader(message, "X-Priority"),
+ fromAddress: parseEmailAddress(getHeader(message, "From") ?? "")?.email.toLowerCase() ?? null,
+ recipientCount:
+ parseEmailAddresses(getHeader(message, "To")).length +
+ parseEmailAddresses(getHeader(message, "Cc")).length,
+ isReply: getHeader(message, "In-Reply-To") !== null || getHeader(message, "References") !== null,
+ subject: getHeader(message, "Subject"),
+ bodyLength: bodyText.length,
+ gmailCategories: (message.labelIds ?? []).filter((l) => GMAIL_CATEGORY_LABELS.has(l)),
+ };
+ return classifyEmail(signals);
+}

connectors/gmail/src/gmail.ts

@@ -35,6 +35,7 @@ import {
  syncGmailMailboxIncremental,
  transformGmailThread,
 } from "./gmail-api";
+import { gmailFacets } from "./gmail-facets";
 
 /**
  * Persisted mailbox-wide watch state. Gmail allows one watch per (mailbox,
@@ -1350,6 +1351,18 @@ export class Gmail extends Connector<Gmail> {
  syncableId: channelId,
  };
 
+ // Compute classifier facets from the parent message's headers + body.
+ const facetParent = thread.messages.find((m) => !m.labelIds?.includes("DRAFT"));
+ if (facetParent) {
+ // Use the parent message's full note body (not the short preview snippet)
+ // so the classifier's reading-vs-notification length split can fire.
+ const facetNote = plotThread.notes?.find(
+ (n) => "key" in n && (n as { key: string }).key === facetParent.id
+ );
+ const facetBody = facetNote?.content ?? plotThread.preview ?? "";
+ plotThread.facets = gmailFacets(facetParent, facetBody);
+ }
+
  // Star ↔ todo sync: detect star changes and sync to Plot todo status.
  // Statuses have been removed; every thread (including archived) is saved
  // with no status and treated like any other thread.

connectors/slack/src/slack-facets.test.ts

@@ -0,0 +1,32 @@
+import { describe, expect, it } from "vitest";
+import { slackFacets } from "./slack-facets";
+import type { SlackMessage } from "./slack-api";
+
+function m(overrides: Partial<SlackMessage> = {}): SlackMessage {
+ return { type: "message", ts: "1.0", text: "hi", ...overrides };
+}
+
+describe("slackFacets", () => {
+ it("treats a DM human message as chat/human/direct", () => {
+ expect(slackFacets(m({ user: "U1", text: "hey there" }), "D123")).toEqual({
+ format: "chat",
+ automation: "human",
+ reach: "direct",
+ });
+ });
+ it("treats a channel post as reach=list", () => {
+ expect(slackFacets(m({ user: "U1" }), "C123").reach).toBe("list");
+ });
+ it("flags a bot message automated", () => {
+ expect(slackFacets(m({ bot_id: "B1", subtype: "bot_message" }), "C123").automation).toBe("automated");
+ });
+ it("a long post becomes a message, not chat", () => {
+ expect(slackFacets(m({ user: "U1", text: "x".repeat(1500) }), "C123").format).toBe("message");
+ });
+ it("treats a group DM (G-prefix) as reach=direct", () => {
+ expect(slackFacets(m({ user: "U1" }), "G123").reach).toBe("direct");
+ });
+ it("treats a message with no user as automated", () => {
+ expect(slackFacets(m({ user: undefined }), "C123").automation).toBe("automated");
+ });
+});

connectors/slack/src/slack-facets.ts

@@ -0,0 +1,30 @@
+import type { ThreadFacets } from "@plotday/twister/facets";
+import type { SlackMessage } from "./slack-api";
+
+// Reach is inferred from the channelId prefix (the channel object isn't in
+// scope at save time):
+// C = public or modern private channel → list (broadcast context)
+// G = group/MPIM OR legacy (pre-2020) private → treated as direct (best-effort;
+// an old private channel is misread as direct, acceptable under fail-open)
+// D = IM (DM) → direct
+function reachForChannel(channelId: string): "direct" | "list" {
+ return channelId.startsWith("C") ? "list" : "direct";
+}
+
+// A long Slack post reads as a "message" rather than a quick "chat".
+const CHAT_MAX_LENGTH = 1000;
+
+/**
+ * Compute facets for a Slack thread's parent message. Channel kind is inferred
+ * from the channelId prefix (the full channel object is not in scope at save
+ * time); this is best-effort per the facet design's fail-open principle.
+ */
+export function slackFacets(parent: SlackMessage, channelId: string): ThreadFacets {
+ const isBot = Boolean(parent.bot_id) || parent.subtype === "bot_message" || !parent.user;
+ const text = parent.text ?? "";
+ return {
+ format: text.length > CHAT_MAX_LENGTH ? "message" : "chat",
+ automation: isBot ? "automated" : "human",
+ reach: reachForChannel(channelId),
+ };
+}

connectors/slack/src/slack.ts

@@ -41,6 +41,7 @@ import {
  transformSlackThread,
 } from "./slack-api";
 import { unicodeToSlackName } from "./slack-emoji";
+import { slackFacets } from "./slack-facets";
 
 /**
  * Slack integration source.
@@ -503,6 +504,7 @@ export class Slack extends Connector<Slack> {
  syncProvider: "slack",
  syncableId: channelId,
  };
+ if (thread[0]) activityThread.facets = slackFacets(thread[0], channelId);
 
  // Save link directly via integrations
  await this.tools.integrations.saveLink(activityThread);
@@ -686,6 +688,7 @@ export class Slack extends Connector<Slack> {
  syncProvider: "slack",
  syncableId: channelId,
  };
+ if (messages[0]) link.facets = slackFacets(messages[0], channelId);
  await this.tools.integrations.saveLink(link);
  }
 
@@ -913,6 +916,7 @@ export class Slack extends Connector<Slack> {
  syncProvider: "slack",
  syncableId: channelId,
  };
+ if (messages[0]) link.facets = slackFacets(messages[0], channelId);
 
  // Suppress the onThreadToDo echo Plot will fire from this write;
  // handleStarEvent / backfillStars is already the source of truth.

libs/email-classifier/package.json

@@ -0,0 +1,30 @@
+{
+ "name": "@plotday/email-classifier",
+ "private": true,
+ "version": "0.1.0",
+ "type": "module",
+ "main": "./dist/index.js",
+ "types": "./dist/index.d.ts",
+ "exports": {
+ ".": {
+ "@plotday/connector": "./src/index.ts",
+ "types": "./dist/index.d.ts",
+ "default": "./dist/index.js"
+ }
+ },
+ "files": ["dist", "README.md"],
+ "scripts": {
+ "build": "tsc",
+ "clean": "rm -rf dist",
+ "lint": "tsc --noEmit",
+ "test": "vitest run",
+ "test:watch": "vitest"
+ },
+ "dependencies": {
+ "@plotday/twister": "workspace:^"
+ },
+ "devDependencies": {
+ "typescript": "^5.9.3",
+ "vitest": "^2.1.8"
+ }
+}

libs/email-classifier/src/classify-email.test.ts

@@ -0,0 +1,88 @@
+import { describe, expect, it } from "vitest";
+import { classifyEmail, type EmailSignals } from "./classify-email";
+
+function signals(overrides: Partial<EmailSignals> = {}): EmailSignals {
+ return {
+ listId: null,
+ listUnsubscribe: null,
+ precedence: null,
+ autoSubmitted: null,
+ returnPath: null,
+ importance: null,
+ fromAddress: "jane@example.com",
+ recipientCount: 1,
+ isReply: false,
+ subject: "Hello",
+ bodyLength: 300,
+ gmailCategories: [],
+ ...overrides,
+ };
+}
+
+describe("classifyEmail — automation", () => {
+ it("flags no-reply senders automated", () => {
+ expect(classifyEmail(signals({ fromAddress: "no-reply@acme.com" })).automation).toBe("automated");
+ });
+ it("flags Precedence: bulk automated", () => {
+ expect(classifyEmail(signals({ precedence: "bulk" })).automation).toBe("automated");
+ });
+ it("flags Auto-Submitted automated", () => {
+ expect(classifyEmail(signals({ autoSubmitted: "auto-generated" })).automation).toBe("automated");
+ });
+ it("flags mailing-list mail automated", () => {
+ expect(classifyEmail(signals({ listId: "<news.acme.com>" })).automation).toBe("automated");
+ });
+ it("treats a plain person email as human", () => {
+ expect(classifyEmail(signals()).automation).toBe("human");
+ });
+});
+
+describe("classifyEmail — reach", () => {
+ it("flags List-Id as list", () => {
+ expect(classifyEmail(signals({ listId: "<news.acme.com>" })).reach).toBe("list");
+ });
+ it("flags List-Unsubscribe as list", () => {
+ expect(classifyEmail(signals({ listUnsubscribe: "<mailto:u@acme.com>" })).reach).toBe("list");
+ });
+ it("flags high recipient count as list", () => {
+ expect(classifyEmail(signals({ recipientCount: 12 })).reach).toBe("list");
+ });
+ it("treats a 1:1 email as direct", () => {
+ expect(classifyEmail(signals()).reach).toBe("direct");
+ });
+});
+
+describe("classifyEmail — format", () => {
+ it("invoice from subject keywords", () => {
+ expect(classifyEmail(signals({ subject: "Your invoice is due", fromAddress: "billing@acme.com" })).format).toBe("invoice");
+ });
+ it("receipt from subject keywords", () => {
+ expect(classifyEmail(signals({ subject: "Your order confirmation #1234", fromAddress: "orders@shop.com" })).format).toBe("receipt");
+ });
+ it("promotion from Gmail category", () => {
+ expect(classifyEmail(signals({ gmailCategories: ["CATEGORY_PROMOTIONS"], listUnsubscribe: "<x>" })).format).toBe("promotion");
+ });
+ it("reading from a long list email", () => {
+ expect(
+ classifyEmail(signals({ listId: "<news>", listUnsubscribe: "<x>", bodyLength: 4000, subject: "Weekly digest" })).format
+ ).toBe("reading");
+ });
+ it("notification from a short automated update", () => {
+ expect(
+ classifyEmail(signals({ fromAddress: "notifications@github.com", bodyLength: 200, gmailCategories: ["CATEGORY_UPDATES"] })).format
+ ).toBe("notification");
+ });
+ it("message for a normal human email", () => {
+ expect(classifyEmail(signals({ bodyLength: 800 })).format).toBe("message");
+ });
+ it("classifies a short automated email as a notification", () => {
+ expect(classifyEmail(signals({ fromAddress: "no-reply@x.com", bodyLength: 0, subject: null })).format).toBe("notification");
+ });
+ it("leaves format null when no heuristic is confident", () => {
+ // automated (auto_reply) but long body, direct, no categories, neutral subject →
+ // none of the format branches fire → null.
+ expect(
+ classifyEmail(signals({ precedence: "auto_reply", bodyLength: 900, subject: "Re: status" })).format
+ ).toBeNull();
+ });
+});

.changeset/facets-sdk.md

@@ -0,0 +1,5 @@
+---
+"@plotday/twister": minor
+---
+
+Added: `@plotday/twister/facets` exporting `Format`, `Automation`, `Reach`, and `ThreadFacets` for connector-emitted thread facets, and `NewLink.facets` to carry them.

connectors/gmail/package.json

@@ -30,6 +30,7 @@
  },
  "dependencies": {
  "@plotday/connector-google-contacts": "workspace:^",
+ "@plotday/email-classifier": "workspace:^",
  "@plotday/twister": "workspace:^"
  },
  "devDependencies": {

connectors/gmail/src/gmail-facets.test.ts

@@ -0,0 +1,60 @@
+import { describe, expect, it } from "vitest";
+import { gmailFacets } from "./gmail-facets";
+import type { GmailMessage } from "./gmail-api";
+
+function msg(opts: {
+ headers: Array<[string, string]>;
+ labelIds?: string[];
+}): GmailMessage {
+ return {
+ id: "m1",
+ threadId: "t1",
+ labelIds: opts.labelIds ?? [],
+ snippet: "",
+ historyId: "1",
+ internalDate: "1700000000000",
+ sizeEstimate: 0,
+ payload: {
+ mimeType: "text/plain",
+ headers: opts.headers.map(([name, value]) => ({ name, value })),
+ },
+ };
+}
+
+describe("gmailFacets", () => {
+ it("classifies a newsletter as reading/automated/list", () => {
+ const f = gmailFacets(
+ msg({
+ headers: [
+ ["From", "news@substack.com"],
+ ["To", "me@x.com"],
+ ["Subject", "The Weekly Digest"],
+ ["List-Id", "<news.substack.com>"],
+ ["List-Unsubscribe", "<mailto:u@substack.com>"],
+ ],
+ }),
+ "a".repeat(4000)
+ );
+ expect(f).toEqual({ format: "reading", automation: "automated", reach: "list" });
+ });
+
+ it("classifies a personal 1:1 email as message/human/direct", () => {
+ const f = gmailFacets(
+ msg({ headers: [["From", "jane@friends.com"], ["To", "me@x.com"], ["Subject", "Lunch?"]] }),
+ "a".repeat(500)
+ );
+ expect(f).toEqual({ format: "message", automation: "human", reach: "direct" });
+ });
+
+ it("classifies a GitHub notification", () => {
+ const f = gmailFacets(
+ msg({
+ headers: [["From", "notifications@github.com"], ["To", "me@x.com"], ["Subject", "[repo] PR merged"]],
+ labelIds: ["CATEGORY_UPDATES"],
+ }),
+ "short"
+ );
+ expect(f.format).toBe("notification");
+ expect(f.automation).toBe("automated");
+ });
+});

connectors/gmail/src/gmail-facets.ts

@@ -0,0 +1,35 @@
+import { classifyEmail, type EmailSignals } from "@plotday/email-classifier";
+import type { ThreadFacets } from "@plotday/twister/facets";
+import { getHeader, parseEmailAddress, parseEmailAddresses, type GmailMessage } from "./gmail-api";
+
+const GMAIL_CATEGORY_LABELS = new Set([
+ "CATEGORY_PROMOTIONS",
+ "CATEGORY_UPDATES",
+ "CATEGORY_SOCIAL",
+ "CATEGORY_FORUMS",
+ "CATEGORY_PERSONAL",
+]);
+
+/**
+ * Compute facets for a Gmail message. `bodyText` is the extracted body used
+ * for the length heuristic (pass the same string the note will carry).
+ */
+export function gmailFacets(message: GmailMessage, bodyText: string): ThreadFacets {
+ const signals: EmailSignals = {
+ listId: getHeader(message, "List-Id"),
+ listUnsubscribe: getHeader(message, "List-Unsubscribe"),
+ precedence: getHeader(message, "Precedence"),
+ autoSubmitted: getHeader(message, "Auto-Submitted"),
+ returnPath: getHeader(message, "Return-Path"),
+ importance: getHeader(message, "Importance") ?? getHeader(message, "X-Priority"),
+ fromAddress: parseEmailAddress(getHeader(message, "From") ?? "")?.email.toLowerCase() ?? null,
+ recipientCount:
+ parseEmailAddresses(getHeader(message, "To")).length +
+ parseEmailAddresses(getHeader(message, "Cc")).length,
+ isReply: getHeader(message, "In-Reply-To") !== null || getHeader(message, "References") !== null,
+ subject: getHeader(message, "Subject"),
+ bodyLength: bodyText.length,
+ gmailCategories: (message.labelIds ?? []).filter((l) => GMAIL_CATEGORY_LABELS.has(l)),
+ };
+ return classifyEmail(signals);
+}

connectors/gmail/src/gmail.ts

@@ -35,6 +35,7 @@ import {
  syncGmailMailboxIncremental,
  transformGmailThread,
 } from "./gmail-api";
+import { gmailFacets } from "./gmail-facets";
 
 /**
  * Persisted mailbox-wide watch state. Gmail allows one watch per (mailbox,
@@ -1350,6 +1351,18 @@ export class Gmail extends Connector<Gmail> {
  syncableId: channelId,
  };
 
+ // Compute classifier facets from the parent message's headers + body.
+ const facetParent = thread.messages.find((m) => !m.labelIds?.includes("DRAFT"));
+ if (facetParent) {
+ // Use the parent message's full note body (not the short preview snippet)
+ // so the classifier's reading-vs-notification length split can fire.
+ const facetNote = plotThread.notes?.find(
+ (n) => "key" in n && (n as { key: string }).key === facetParent.id
+ );
+ const facetBody = facetNote?.content ?? plotThread.preview ?? "";
+ plotThread.facets = gmailFacets(facetParent, facetBody);
+ }
+
  // Star ↔ todo sync: detect star changes and sync to Plot todo status.
  // Statuses have been removed; every thread (including archived) is saved
  // with no status and treated like any other thread.

connectors/slack/src/slack-facets.test.ts

@@ -0,0 +1,32 @@
+import { describe, expect, it } from "vitest";
+import { slackFacets } from "./slack-facets";
+import type { SlackMessage } from "./slack-api";
+
+function m(overrides: Partial<SlackMessage> = {}): SlackMessage {
+ return { type: "message", ts: "1.0", text: "hi", ...overrides };
+}
+
+describe("slackFacets", () => {
+ it("treats a DM human message as chat/human/direct", () => {
+ expect(slackFacets(m({ user: "U1", text: "hey there" }), "D123")).toEqual({
+ format: "chat",
+ automation: "human",
+ reach: "direct",
+ });
+ });
+ it("treats a channel post as reach=list", () => {
+ expect(slackFacets(m({ user: "U1" }), "C123").reach).toBe("list");
+ });
+ it("flags a bot message automated", () => {
+ expect(slackFacets(m({ bot_id: "B1", subtype: "bot_message" }), "C123").automation).toBe("automated");
+ });
+ it("a long post becomes a message, not chat", () => {
+ expect(slackFacets(m({ user: "U1", text: "x".repeat(1500) }), "C123").format).toBe("message");
+ });
+ it("treats a group DM (G-prefix) as reach=direct", () => {
+ expect(slackFacets(m({ user: "U1" }), "G123").reach).toBe("direct");
+ });
+ it("treats a message with no user as automated", () => {
+ expect(slackFacets(m({ user: undefined }), "C123").automation).toBe("automated");
+ });
+});

connectors/slack/src/slack-facets.ts

@@ -0,0 +1,30 @@
+import type { ThreadFacets } from "@plotday/twister/facets";
+import type { SlackMessage } from "./slack-api";
+
+// Reach is inferred from the channelId prefix (the channel object isn't in
+// scope at save time):
+// C = public or modern private channel → list (broadcast context)
+// G = group/MPIM OR legacy (pre-2020) private → treated as direct (best-effort;
+// an old private channel is misread as direct, acceptable under fail-open)
+// D = IM (DM) → direct
+function reachForChannel(channelId: string): "direct" | "list" {
+ return channelId.startsWith("C") ? "list" : "direct";
+}
+
+// A long Slack post reads as a "message" rather than a quick "chat".
+const CHAT_MAX_LENGTH = 1000;
+
+/**
+ * Compute facets for a Slack thread's parent message. Channel kind is inferred
+ * from the channelId prefix (the full channel object is not in scope at save
+ * time); this is best-effort per the facet design's fail-open principle.
+ */
+export function slackFacets(parent: SlackMessage, channelId: string): ThreadFacets {
+ const isBot = Boolean(parent.bot_id) || parent.subtype === "bot_message" || !parent.user;
+ const text = parent.text ?? "";
+ return {
+ format: text.length > CHAT_MAX_LENGTH ? "message" : "chat",
+ automation: isBot ? "automated" : "human",
+ reach: reachForChannel(channelId),
+ };
+}

connectors/slack/src/slack.ts

@@ -41,6 +41,7 @@ import {
  transformSlackThread,
 } from "./slack-api";
 import { unicodeToSlackName } from "./slack-emoji";
+import { slackFacets } from "./slack-facets";
 
 /**
  * Slack integration source.
@@ -503,6 +504,7 @@ export class Slack extends Connector<Slack> {
  syncProvider: "slack",
  syncableId: channelId,
  };
+ if (thread[0]) activityThread.facets = slackFacets(thread[0], channelId);
 
  // Save link directly via integrations
  await this.tools.integrations.saveLink(activityThread);
@@ -686,6 +688,7 @@ export class Slack extends Connector<Slack> {
  syncProvider: "slack",
  syncableId: channelId,
  };
+ if (messages[0]) link.facets = slackFacets(messages[0], channelId);
  await this.tools.integrations.saveLink(link);
  }
 
@@ -913,6 +916,7 @@ export class Slack extends Connector<Slack> {
  syncProvider: "slack",
  syncableId: channelId,
  };
+ if (messages[0]) link.facets = slackFacets(messages[0], channelId);
 
  // Suppress the onThreadToDo echo Plot will fire from this write;
  // handleStarEvent / backfillStars is already the source of truth.

libs/email-classifier/package.json

@@ -0,0 +1,30 @@
+{
+ "name": "@plotday/email-classifier",
+ "private": true,
+ "version": "0.1.0",
+ "type": "module",
+ "main": "./dist/index.js",
+ "types": "./dist/index.d.ts",
+ "exports": {
+ ".": {
+ "@plotday/connector": "./src/index.ts",
+ "types": "./dist/index.d.ts",
+ "default": "./dist/index.js"
+ }
+ },
+ "files": ["dist", "README.md"],
+ "scripts": {
+ "build": "tsc",
+ "clean": "rm -rf dist",
+ "lint": "tsc --noEmit",
+ "test": "vitest run",
+ "test:watch": "vitest"
+ },
+ "dependencies": {
+ "@plotday/twister": "workspace:^"
+ },
+ "devDependencies": {
+ "typescript": "^5.9.3",
+ "vitest": "^2.1.8"
+ }
+}

libs/email-classifier/src/classify-email.test.ts

@@ -0,0 +1,88 @@
+import { describe, expect, it } from "vitest";
+import { classifyEmail, type EmailSignals } from "./classify-email";
+
+function signals(overrides: Partial<EmailSignals> = {}): EmailSignals {
+ return {
+ listId: null,
+ listUnsubscribe: null,
+ precedence: null,
+ autoSubmitted: null,
+ returnPath: null,
+ importance: null,
+ fromAddress: "jane@example.com",
+ recipientCount: 1,
+ isReply: false,
+ subject: "Hello",
+ bodyLength: 300,
+ gmailCategories: [],
+ ...overrides,
+ };
+}
+
+describe("classifyEmail — automation", () => {
+ it("flags no-reply senders automated", () => {
+ expect(classifyEmail(signals({ fromAddress: "no-reply@acme.com" })).automation).toBe("automated");
+ });
+ it("flags Precedence: bulk automated", () => {
+ expect(classifyEmail(signals({ precedence: "bulk" })).automation).toBe("automated");
+ });
+ it("flags Auto-Submitted automated", () => {
+ expect(classifyEmail(signals({ autoSubmitted: "auto-generated" })).automation).toBe("automated");
+ });
+ it("flags mailing-list mail automated", () => {
+ expect(classifyEmail(signals({ listId: "<news.acme.com>" })).automation).toBe("automated");
+ });
+ it("treats a plain person email as human", () => {
+ expect(classifyEmail(signals()).automation).toBe("human");
+ });
+});
+
+describe("classifyEmail — reach", () => {
+ it("flags List-Id as list", () => {
+ expect(classifyEmail(signals({ listId: "<news.acme.com>" })).reach).toBe("list");
+ });
+ it("flags List-Unsubscribe as list", () => {
+ expect(classifyEmail(signals({ listUnsubscribe: "<mailto:u@acme.com>" })).reach).toBe("list");
+ });
+ it("flags high recipient count as list", () => {
+ expect(classifyEmail(signals({ recipientCount: 12 })).reach).toBe("list");
+ });
+ it("treats a 1:1 email as direct", () => {
+ expect(classifyEmail(signals()).reach).toBe("direct");
+ });
+});
+
+describe("classifyEmail — format", () => {
+ it("invoice from subject keywords", () => {
+ expect(classifyEmail(signals({ subject: "Your invoice is due", fromAddress: "billing@acme.com" })).format).toBe("invoice");
+ });
+ it("receipt from subject keywords", () => {
+ expect(classifyEmail(signals({ subject: "Your order confirmation #1234", fromAddress: "orders@shop.com" })).format).toBe("receipt");
+ });
+ it("promotion from Gmail category", () => {
+ expect(classifyEmail(signals({ gmailCategories: ["CATEGORY_PROMOTIONS"], listUnsubscribe: "<x>" })).format).toBe("promotion");
+ });
+ it("reading from a long list email", () => {
+ expect(
+ classifyEmail(signals({ listId: "<news>", listUnsubscribe: "<x>", bodyLength: 4000, subject: "Weekly digest" })).format
+ ).toBe("reading");
+ });
+ it("notification from a short automated update", () => {
+ expect(
+ classifyEmail(signals({ fromAddress: "notifications@github.com", bodyLength: 200, gmailCategories: ["CATEGORY_UPDATES"] })).format
+ ).toBe("notification");
+ });
+ it("message for a normal human email", () => {
+ expect(classifyEmail(signals({ bodyLength: 800 })).format).toBe("message");
+ });
+ it("classifies a short automated email as a notification", () => {
+ expect(classifyEmail(signals({ fromAddress: "no-reply@x.com", bodyLength: 0, subject: null })).format).toBe("notification");
+ });
+ it("leaves format null when no heuristic is confident", () => {
+ // automated (auto_reply) but long body, direct, no categories, neutral subject →
+ // none of the format branches fire → null.
+ expect(
+ classifyEmail(signals({ precedence: "auto_reply", bodyLength: 900, subject: "Re: status" })).format
+ ).toBeNull();
+ });
+});

.changeset/facets-sdk.md

@@ -0,0 +1,5 @@
+---
+"@plotday/twister": minor
+---
+
+Added: `@plotday/twister/facets` exporting `Format`, `Automation`, `Reach`, and `ThreadFacets` for connector-emitted thread facets, and `NewLink.facets` to carry them.

connectors/gmail/package.json

@@ -30,6 +30,7 @@
  },
  "dependencies": {
  "@plotday/connector-google-contacts": "workspace:^",
+ "@plotday/email-classifier": "workspace:^",
  "@plotday/twister": "workspace:^"
  },
  "devDependencies": {

connectors/gmail/src/gmail-facets.test.ts

@@ -0,0 +1,60 @@
+import { describe, expect, it } from "vitest";
+import { gmailFacets } from "./gmail-facets";
+import type { GmailMessage } from "./gmail-api";
+
+function msg(opts: {
+ headers: Array<[string, string]>;
+ labelIds?: string[];
+}): GmailMessage {
+ return {
+ id: "m1",
+ threadId: "t1",
+ labelIds: opts.labelIds ?? [],
+ snippet: "",
+ historyId: "1",
+ internalDate: "1700000000000",
+ sizeEstimate: 0,
+ payload: {
+ mimeType: "text/plain",
+ headers: opts.headers.map(([name, value]) => ({ name, value })),
+ },
+ };
+}
+
+describe("gmailFacets", () => {
+ it("classifies a newsletter as reading/automated/list", () => {
+ const f = gmailFacets(
+ msg({
+ headers: [
+ ["From", "news@substack.com"],
+ ["To", "me@x.com"],
+ ["Subject", "The Weekly Digest"],
+ ["List-Id", "<news.substack.com>"],
+ ["List-Unsubscribe", "<mailto:u@substack.com>"],
+ ],
+ }),
+ "a".repeat(4000)
+ );
+ expect(f).toEqual({ format: "reading", automation: "automated", reach: "list" });
+ });
+
+ it("classifies a personal 1:1 email as message/human/direct", () => {
+ const f = gmailFacets(
+ msg({ headers: [["From", "jane@friends.com"], ["To", "me@x.com"], ["Subject", "Lunch?"]] }),
+ "a".repeat(500)
+ );
+ expect(f).toEqual({ format: "message", automation: "human", reach: "direct" });
+ });
+
+ it("classifies a GitHub notification", () => {
+ const f = gmailFacets(
+ msg({
+ headers: [["From", "notifications@github.com"], ["To", "me@x.com"], ["Subject", "[repo] PR merged"]],
+ labelIds: ["CATEGORY_UPDATES"],
+ }),
+ "short"
+ );
+ expect(f.format).toBe("notification");
+ expect(f.automation).toBe("automated");
+ });
+});

connectors/gmail/src/gmail-facets.ts

@@ -0,0 +1,35 @@
+import { classifyEmail, type EmailSignals } from "@plotday/email-classifier";
+import type { ThreadFacets } from "@plotday/twister/facets";
+import { getHeader, parseEmailAddress, parseEmailAddresses, type GmailMessage } from "./gmail-api";
+
+const GMAIL_CATEGORY_LABELS = new Set([
+ "CATEGORY_PROMOTIONS",
+ "CATEGORY_UPDATES",
+ "CATEGORY_SOCIAL",
+ "CATEGORY_FORUMS",
+ "CATEGORY_PERSONAL",
+]);
+
+/**
+ * Compute facets for a Gmail message. `bodyText` is the extracted body used
+ * for the length heuristic (pass the same string the note will carry).
+ */
+export function gmailFacets(message: GmailMessage, bodyText: string): ThreadFacets {
+ const signals: EmailSignals = {
+ listId: getHeader(message, "List-Id"),
+ listUnsubscribe: getHeader(message, "List-Unsubscribe"),
+ precedence: getHeader(message, "Precedence"),
+ autoSubmitted: getHeader(message, "Auto-Submitted"),
+ returnPath: getHeader(message, "Return-Path"),
+ importance: getHeader(message, "Importance") ?? getHeader(message, "X-Priority"),
+ fromAddress: parseEmailAddress(getHeader(message, "From") ?? "")?.email.toLowerCase() ?? null,
+ recipientCount:
+ parseEmailAddresses(getHeader(message, "To")).length +
+ parseEmailAddresses(getHeader(message, "Cc")).length,
+ isReply: getHeader(message, "In-Reply-To") !== null || getHeader(message, "References") !== null,
+ subject: getHeader(message, "Subject"),
+ bodyLength: bodyText.length,
+ gmailCategories: (message.labelIds ?? []).filter((l) => GMAIL_CATEGORY_LABELS.has(l)),
+ };
+ return classifyEmail(signals);
+}

connectors/gmail/src/gmail.ts

@@ -35,6 +35,7 @@ import {
  syncGmailMailboxIncremental,
  transformGmailThread,
 } from "./gmail-api";
+import { gmailFacets } from "./gmail-facets";
 
 /**
  * Persisted mailbox-wide watch state. Gmail allows one watch per (mailbox,
@@ -1350,6 +1351,18 @@ export class Gmail extends Connector<Gmail> {
  syncableId: channelId,
  };
 
+ // Compute classifier facets from the parent message's headers + body.
+ const facetParent = thread.messages.find((m) => !m.labelIds?.includes("DRAFT"));
+ if (facetParent) {
+ // Use the parent message's full note body (not the short preview snippet)
+ // so the classifier's reading-vs-notification length split can fire.
+ const facetNote = plotThread.notes?.find(
+ (n) => "key" in n && (n as { key: string }).key === facetParent.id
+ );
+ const facetBody = facetNote?.content ?? plotThread.preview ?? "";
+ plotThread.facets = gmailFacets(facetParent, facetBody);
+ }
+
  // Star ↔ todo sync: detect star changes and sync to Plot todo status.
  // Statuses have been removed; every thread (including archived) is saved
  // with no status and treated like any other thread.

connectors/slack/src/slack-facets.test.ts

@@ -0,0 +1,32 @@
+import { describe, expect, it } from "vitest";
+import { slackFacets } from "./slack-facets";
+import type { SlackMessage } from "./slack-api";
+
+function m(overrides: Partial<SlackMessage> = {}): SlackMessage {
+ return { type: "message", ts: "1.0", text: "hi", ...overrides };
+}
+
+describe("slackFacets", () => {
+ it("treats a DM human message as chat/human/direct", () => {
+ expect(slackFacets(m({ user: "U1", text: "hey there" }), "D123")).toEqual({
+ format: "chat",
+ automation: "human",
+ reach: "direct",
+ });
+ });
+ it("treats a channel post as reach=list", () => {
+ expect(slackFacets(m({ user: "U1" }), "C123").reach).toBe("list");
+ });
+ it("flags a bot message automated", () => {
+ expect(slackFacets(m({ bot_id: "B1", subtype: "bot_message" }), "C123").automation).toBe("automated");
+ });
+ it("a long post becomes a message, not chat", () => {
+ expect(slackFacets(m({ user: "U1", text: "x".repeat(1500) }), "C123").format).toBe("message");
+ });
+ it("treats a group DM (G-prefix) as reach=direct", () => {
+ expect(slackFacets(m({ user: "U1" }), "G123").reach).toBe("direct");
+ });
+ it("treats a message with no user as automated", () => {
+ expect(slackFacets(m({ user: undefined }), "C123").automation).toBe("automated");
+ });
+});

connectors/slack/src/slack-facets.ts

@@ -0,0 +1,30 @@
+import type { ThreadFacets } from "@plotday/twister/facets";
+import type { SlackMessage } from "./slack-api";
+
+// Reach is inferred from the channelId prefix (the channel object isn't in
+// scope at save time):
+// C = public or modern private channel → list (broadcast context)
+// G = group/MPIM OR legacy (pre-2020) private → treated as direct (best-effort;
+// an old private channel is misread as direct, acceptable under fail-open)
+// D = IM (DM) → direct
+function reachForChannel(channelId: string): "direct" | "list" {
+ return channelId.startsWith("C") ? "list" : "direct";
+}
+
+// A long Slack post reads as a "message" rather than a quick "chat".
+const CHAT_MAX_LENGTH = 1000;
+
+/**
+ * Compute facets for a Slack thread's parent message. Channel kind is inferred
+ * from the channelId prefix (the full channel object is not in scope at save
+ * time); this is best-effort per the facet design's fail-open principle.
+ */
+export function slackFacets(parent: SlackMessage, channelId: string): ThreadFacets {
+ const isBot = Boolean(parent.bot_id) || parent.subtype === "bot_message" || !parent.user;
+ const text = parent.text ?? "";
+ return {
+ format: text.length > CHAT_MAX_LENGTH ? "message" : "chat",
+ automation: isBot ? "automated" : "human",
+ reach: reachForChannel(channelId),
+ };
+}

connectors/slack/src/slack.ts

@@ -41,6 +41,7 @@ import {
  transformSlackThread,
 } from "./slack-api";
 import { unicodeToSlackName } from "./slack-emoji";
+import { slackFacets } from "./slack-facets";
 
 /**
  * Slack integration source.
@@ -503,6 +504,7 @@ export class Slack extends Connector<Slack> {
  syncProvider: "slack",
  syncableId: channelId,
  };
+ if (thread[0]) activityThread.facets = slackFacets(thread[0], channelId);
 
  // Save link directly via integrations
  await this.tools.integrations.saveLink(activityThread);
@@ -686,6 +688,7 @@ export class Slack extends Connector<Slack> {
  syncProvider: "slack",
  syncableId: channelId,
  };
+ if (messages[0]) link.facets = slackFacets(messages[0], channelId);
  await this.tools.integrations.saveLink(link);
  }
 
@@ -913,6 +916,7 @@ export class Slack extends Connector<Slack> {
  syncProvider: "slack",
  syncableId: channelId,
  };
+ if (messages[0]) link.facets = slackFacets(messages[0], channelId);
 
  // Suppress the onThreadToDo echo Plot will fire from this write;
  // handleStarEvent / backfillStars is already the source of truth.

libs/email-classifier/package.json

@@ -0,0 +1,30 @@
+{
+ "name": "@plotday/email-classifier",
+ "private": true,
+ "version": "0.1.0",
+ "type": "module",
+ "main": "./dist/index.js",
+ "types": "./dist/index.d.ts",
+ "exports": {
+ ".": {
+ "@plotday/connector": "./src/index.ts",
+ "types": "./dist/index.d.ts",
+ "default": "./dist/index.js"
+ }
+ },
+ "files": ["dist", "README.md"],
+ "scripts": {
+ "build": "tsc",
+ "clean": "rm -rf dist",
+ "lint": "tsc --noEmit",
+ "test": "vitest run",
+ "test:watch": "vitest"
+ },
+ "dependencies": {
+ "@plotday/twister": "workspace:^"
+ },
+ "devDependencies": {
+ "typescript": "^5.9.3",
+ "vitest": "^2.1.8"
+ }
+}

libs/email-classifier/src/classify-email.test.ts

@@ -0,0 +1,88 @@
+import { describe, expect, it } from "vitest";
+import { classifyEmail, type EmailSignals } from "./classify-email";
+
+function signals(overrides: Partial<EmailSignals> = {}): EmailSignals {
+ return {
+ listId: null,
+ listUnsubscribe: null,
+ precedence: null,
+ autoSubmitted: null,
+ returnPath: null,
+ importance: null,
+ fromAddress: "jane@example.com",
+ recipientCount: 1,
+ isReply: false,
+ subject: "Hello",
+ bodyLength: 300,
+ gmailCategories: [],
+ ...overrides,
+ };
+}
+
+describe("classifyEmail — automation", () => {
+ it("flags no-reply senders automated", () => {
+ expect(classifyEmail(signals({ fromAddress: "no-reply@acme.com" })).automation).toBe("automated");
+ });
+ it("flags Precedence: bulk automated", () => {
+ expect(classifyEmail(signals({ precedence: "bulk" })).automation).toBe("automated");
+ });
+ it("flags Auto-Submitted automated", () => {
+ expect(classifyEmail(signals({ autoSubmitted: "auto-generated" })).automation).toBe("automated");
+ });
+ it("flags mailing-list mail automated", () => {
+ expect(classifyEmail(signals({ listId: "<news.acme.com>" })).automation).toBe("automated");
+ });
+ it("treats a plain person email as human", () => {
+ expect(classifyEmail(signals()).automation).toBe("human");
+ });
+});
+
+describe("classifyEmail — reach", () => {
+ it("flags List-Id as list", () => {
+ expect(classifyEmail(signals({ listId: "<news.acme.com>" })).reach).toBe("list");
+ });
+ it("flags List-Unsubscribe as list", () => {
+ expect(classifyEmail(signals({ listUnsubscribe: "<mailto:u@acme.com>" })).reach).toBe("list");
+ });
+ it("flags high recipient count as list", () => {
+ expect(classifyEmail(signals({ recipientCount: 12 })).reach).toBe("list");
+ });
+ it("treats a 1:1 email as direct", () => {
+ expect(classifyEmail(signals()).reach).toBe("direct");
+ });
+});
+
+describe("classifyEmail — format", () => {
+ it("invoice from subject keywords", () => {
+ expect(classifyEmail(signals({ subject: "Your invoice is due", fromAddress: "billing@acme.com" })).format).toBe("invoice");
+ });
+ it("receipt from subject keywords", () => {
+ expect(classifyEmail(signals({ subject: "Your order confirmation #1234", fromAddress: "orders@shop.com" })).format).toBe("receipt");
+ });
+ it("promotion from Gmail category", () => {
+ expect(classifyEmail(signals({ gmailCategories: ["CATEGORY_PROMOTIONS"], listUnsubscribe: "<x>" })).format).toBe("promotion");
+ });
+ it("reading from a long list email", () => {
+ expect(
+ classifyEmail(signals({ listId: "<news>", listUnsubscribe: "<x>", bodyLength: 4000, subject: "Weekly digest" })).format
+ ).toBe("reading");
+ });
+ it("notification from a short automated update", () => {
+ expect(
+ classifyEmail(signals({ fromAddress: "notifications@github.com", bodyLength: 200, gmailCategories: ["CATEGORY_UPDATES"] })).format
+ ).toBe("notification");
+ });
+ it("message for a normal human email", () => {
+ expect(classifyEmail(signals({ bodyLength: 800 })).format).toBe("message");
+ });
+ it("classifies a short automated email as a notification", () => {
+ expect(classifyEmail(signals({ fromAddress: "no-reply@x.com", bodyLength: 0, subject: null })).format).toBe("notification");
+ });
+ it("leaves format null when no heuristic is confident", () => {
+ // automated (auto_reply) but long body, direct, no categories, neutral subject →
+ // none of the format branches fire → null.
+ expect(
+ classifyEmail(signals({ precedence: "auto_reply", bodyLength: 900, subject: "Re: status" })).format
+ ).toBeNull();
+ });
+});

.changeset/facets-sdk.md

@@ -0,0 +1,5 @@
+---
+"@plotday/twister": minor
+---
+
+Added: `@plotday/twister/facets` exporting `Format`, `Automation`, `Reach`, and `ThreadFacets` for connector-emitted thread facets, and `NewLink.facets` to carry them.

connectors/gmail/package.json

@@ -30,6 +30,7 @@
  },
  "dependencies": {
  "@plotday/connector-google-contacts": "workspace:^",
+ "@plotday/email-classifier": "workspace:^",
  "@plotday/twister": "workspace:^"
  },
  "devDependencies": {

connectors/gmail/src/gmail-facets.test.ts

@@ -0,0 +1,60 @@
+import { describe, expect, it } from "vitest";
+import { gmailFacets } from "./gmail-facets";
+import type { GmailMessage } from "./gmail-api";
+
+function msg(opts: {
+ headers: Array<[string, string]>;
+ labelIds?: string[];
+}): GmailMessage {
+ return {
+ id: "m1",
+ threadId: "t1",
+ labelIds: opts.labelIds ?? [],
+ snippet: "",
+ historyId: "1",
+ internalDate: "1700000000000",
+ sizeEstimate: 0,
+ payload: {
+ mimeType: "text/plain",
+ headers: opts.headers.map(([name, value]) => ({ name, value })),
+ },
+ };
+}
+
+describe("gmailFacets", () => {
+ it("classifies a newsletter as reading/automated/list", () => {
+ const f = gmailFacets(
+ msg({
+ headers: [
+ ["From", "news@substack.com"],
+ ["To", "me@x.com"],
+ ["Subject", "The Weekly Digest"],
+ ["List-Id", "<news.substack.com>"],
+ ["List-Unsubscribe", "<mailto:u@substack.com>"],
+ ],
+ }),
+ "a".repeat(4000)
+ );
+ expect(f).toEqual({ format: "reading", automation: "automated", reach: "list" });
+ });
+
+ it("classifies a personal 1:1 email as message/human/direct", () => {
+ const f = gmailFacets(
+ msg({ headers: [["From", "jane@friends.com"], ["To", "me@x.com"], ["Subject", "Lunch?"]] }),
+ "a".repeat(500)
+ );
+ expect(f).toEqual({ format: "message", automation: "human", reach: "direct" });
+ });
+
+ it("classifies a GitHub notification", () => {
+ const f = gmailFacets(
+ msg({
+ headers: [["From", "notifications@github.com"], ["To", "me@x.com"], ["Subject", "[repo] PR merged"]],
+ labelIds: ["CATEGORY_UPDATES"],
+ }),
+ "short"
+ );
+ expect(f.format).toBe("notification");
+ expect(f.automation).toBe("automated");
+ });
+});

connectors/gmail/src/gmail-facets.ts

@@ -0,0 +1,35 @@
+import { classifyEmail, type EmailSignals } from "@plotday/email-classifier";
+import type { ThreadFacets } from "@plotday/twister/facets";
+import { getHeader, parseEmailAddress, parseEmailAddresses, type GmailMessage } from "./gmail-api";
+
+const GMAIL_CATEGORY_LABELS = new Set([
+ "CATEGORY_PROMOTIONS",
+ "CATEGORY_UPDATES",
+ "CATEGORY_SOCIAL",
+ "CATEGORY_FORUMS",
+ "CATEGORY_PERSONAL",
+]);
+
+/**
+ * Compute facets for a Gmail message. `bodyText` is the extracted body used
+ * for the length heuristic (pass the same string the note will carry).
+ */
+export function gmailFacets(message: GmailMessage, bodyText: string): ThreadFacets {
+ const signals: EmailSignals = {
+ listId: getHeader(message, "List-Id"),
+ listUnsubscribe: getHeader(message, "List-Unsubscribe"),
+ precedence: getHeader(message, "Precedence"),
+ autoSubmitted: getHeader(message, "Auto-Submitted"),
+ returnPath: getHeader(message, "Return-Path"),
+ importance: getHeader(message, "Importance") ?? getHeader(message, "X-Priority"),
+ fromAddress: parseEmailAddress(getHeader(message, "From") ?? "")?.email.toLowerCase() ?? null,
+ recipientCount:
+ parseEmailAddresses(getHeader(message, "To")).length +
+ parseEmailAddresses(getHeader(message, "Cc")).length,
+ isReply: getHeader(message, "In-Reply-To") !== null || getHeader(message, "References") !== null,
+ subject: getHeader(message, "Subject"),
+ bodyLength: bodyText.length,
+ gmailCategories: (message.labelIds ?? []).filter((l) => GMAIL_CATEGORY_LABELS.has(l)),
+ };
+ return classifyEmail(signals);
+}

connectors/gmail/src/gmail.ts

@@ -35,6 +35,7 @@ import {
  syncGmailMailboxIncremental,
  transformGmailThread,
 } from "./gmail-api";
+import { gmailFacets } from "./gmail-facets";
 
 /**
  * Persisted mailbox-wide watch state. Gmail allows one watch per (mailbox,
@@ -1350,6 +1351,18 @@ export class Gmail extends Connector<Gmail> {
  syncableId: channelId,
  };
 
+ // Compute classifier facets from the parent message's headers + body.
+ const facetParent = thread.messages.find((m) => !m.labelIds?.includes("DRAFT"));
+ if (facetParent) {
+ // Use the parent message's full note body (not the short preview snippet)
+ // so the classifier's reading-vs-notification length split can fire.
+ const facetNote = plotThread.notes?.find(
+ (n) => "key" in n && (n as { key: string }).key === facetParent.id
+ );
+ const facetBody = facetNote?.content ?? plotThread.preview ?? "";
+ plotThread.facets = gmailFacets(facetParent, facetBody);
+ }
+
  // Star ↔ todo sync: detect star changes and sync to Plot todo status.
  // Statuses have been removed; every thread (including archived) is saved
  // with no status and treated like any other thread.

connectors/slack/src/slack-facets.test.ts

@@ -0,0 +1,32 @@
+import { describe, expect, it } from "vitest";
+import { slackFacets } from "./slack-facets";
+import type { SlackMessage } from "./slack-api";
+
+function m(overrides: Partial<SlackMessage> = {}): SlackMessage {
+ return { type: "message", ts: "1.0", text: "hi", ...overrides };
+}
+
+describe("slackFacets", () => {
+ it("treats a DM human message as chat/human/direct", () => {
+ expect(slackFacets(m({ user: "U1", text: "hey there" }), "D123")).toEqual({
+ format: "chat",
+ automation: "human",
+ reach: "direct",
+ });
+ });
+ it("treats a channel post as reach=list", () => {
+ expect(slackFacets(m({ user: "U1" }), "C123").reach).toBe("list");
+ });
+ it("flags a bot message automated", () => {
+ expect(slackFacets(m({ bot_id: "B1", subtype: "bot_message" }), "C123").automation).toBe("automated");
+ });
+ it("a long post becomes a message, not chat", () => {
+ expect(slackFacets(m({ user: "U1", text: "x".repeat(1500) }), "C123").format).toBe("message");
+ });
+ it("treats a group DM (G-prefix) as reach=direct", () => {
+ expect(slackFacets(m({ user: "U1" }), "G123").reach).toBe("direct");
+ });
+ it("treats a message with no user as automated", () => {
+ expect(slackFacets(m({ user: undefined }), "C123").automation).toBe("automated");
+ });
+});

connectors/slack/src/slack-facets.ts

@@ -0,0 +1,30 @@
+import type { ThreadFacets } from "@plotday/twister/facets";
+import type { SlackMessage } from "./slack-api";
+
+// Reach is inferred from the channelId prefix (the channel object isn't in
+// scope at save time):
+// C = public or modern private channel → list (broadcast context)
+// G = group/MPIM OR legacy (pre-2020) private → treated as direct (best-effort;
+// an old private channel is misread as direct, acceptable under fail-open)
+// D = IM (DM) → direct
+function reachForChannel(channelId: string): "direct" | "list" {
+ return channelId.startsWith("C") ? "list" : "direct";
+}
+
+// A long Slack post reads as a "message" rather than a quick "chat".
+const CHAT_MAX_LENGTH = 1000;
+
+/**
+ * Compute facets for a Slack thread's parent message. Channel kind is inferred
+ * from the channelId prefix (the full channel object is not in scope at save
+ * time); this is best-effort per the facet design's fail-open principle.
+ */
+export function slackFacets(parent: SlackMessage, channelId: string): ThreadFacets {
+ const isBot = Boolean(parent.bot_id) || parent.subtype === "bot_message" || !parent.user;
+ const text = parent.text ?? "";
+ return {
+ format: text.length > CHAT_MAX_LENGTH ? "message" : "chat",
+ automation: isBot ? "automated" : "human",
+ reach: reachForChannel(channelId),
+ };
+}

connectors/slack/src/slack.ts

@@ -41,6 +41,7 @@ import {
  transformSlackThread,
 } from "./slack-api";
 import { unicodeToSlackName } from "./slack-emoji";
+import { slackFacets } from "./slack-facets";
 
 /**
  * Slack integration source.
@@ -503,6 +504,7 @@ export class Slack extends Connector<Slack> {
  syncProvider: "slack",
  syncableId: channelId,
  };
+ if (thread[0]) activityThread.facets = slackFacets(thread[0], channelId);
 
  // Save link directly via integrations
  await this.tools.integrations.saveLink(activityThread);
@@ -686,6 +688,7 @@ export class Slack extends Connector<Slack> {
  syncProvider: "slack",
  syncableId: channelId,
  };
+ if (messages[0]) link.facets = slackFacets(messages[0], channelId);
  await this.tools.integrations.saveLink(link);
  }
 
@@ -913,6 +916,7 @@ export class Slack extends Connector<Slack> {
  syncProvider: "slack",
  syncableId: channelId,
  };
+ if (messages[0]) link.facets = slackFacets(messages[0], channelId);
 
  // Suppress the onThreadToDo echo Plot will fire from this write;
  // handleStarEvent / backfillStars is already the source of truth.

libs/email-classifier/package.json

@@ -0,0 +1,30 @@
+{
+ "name": "@plotday/email-classifier",
+ "private": true,
+ "version": "0.1.0",
+ "type": "module",
+ "main": "./dist/index.js",
+ "types": "./dist/index.d.ts",
+ "exports": {
+ ".": {
+ "@plotday/connector": "./src/index.ts",
+ "types": "./dist/index.d.ts",
+ "default": "./dist/index.js"
+ }
+ },
+ "files": ["dist", "README.md"],
+ "scripts": {
+ "build": "tsc",
+ "clean": "rm -rf dist",
+ "lint": "tsc --noEmit",
+ "test": "vitest run",
+ "test:watch": "vitest"
+ },
+ "dependencies": {
+ "@plotday/twister": "workspace:^"
+ },
+ "devDependencies": {
+ "typescript": "^5.9.3",
+ "vitest": "^2.1.8"
+ }
+}

libs/email-classifier/src/classify-email.test.ts

@@ -0,0 +1,88 @@
+import { describe, expect, it } from "vitest";
+import { classifyEmail, type EmailSignals } from "./classify-email";
+
+function signals(overrides: Partial<EmailSignals> = {}): EmailSignals {
+ return {
+ listId: null,
+ listUnsubscribe: null,
+ precedence: null,
+ autoSubmitted: null,
+ returnPath: null,
+ importance: null,
+ fromAddress: "jane@example.com",
+ recipientCount: 1,
+ isReply: false,
+ subject: "Hello",
+ bodyLength: 300,
+ gmailCategories: [],
+ ...overrides,
+ };
+}
+
+describe("classifyEmail — automation", () => {
+ it("flags no-reply senders automated", () => {
+ expect(classifyEmail(signals({ fromAddress: "no-reply@acme.com" })).automation).toBe("automated");
+ });
+ it("flags Precedence: bulk automated", () => {
+ expect(classifyEmail(signals({ precedence: "bulk" })).automation).toBe("automated");
+ });
+ it("flags Auto-Submitted automated", () => {
+ expect(classifyEmail(signals({ autoSubmitted: "auto-generated" })).automation).toBe("automated");
+ });
+ it("flags mailing-list mail automated", () => {
+ expect(classifyEmail(signals({ listId: "<news.acme.com>" })).automation).toBe("automated");
+ });
+ it("treats a plain person email as human", () => {
+ expect(classifyEmail(signals()).automation).toBe("human");
+ });
+});
+
+describe("classifyEmail — reach", () => {
+ it("flags List-Id as list", () => {
+ expect(classifyEmail(signals({ listId: "<news.acme.com>" })).reach).toBe("list");
+ });
+ it("flags List-Unsubscribe as list", () => {
+ expect(classifyEmail(signals({ listUnsubscribe: "<mailto:u@acme.com>" })).reach).toBe("list");
+ });
+ it("flags high recipient count as list", () => {
+ expect(classifyEmail(signals({ recipientCount: 12 })).reach).toBe("list");
+ });
+ it("treats a 1:1 email as direct", () => {
+ expect(classifyEmail(signals()).reach).toBe("direct");
+ });
+});
+
+describe("classifyEmail — format", () => {
+ it("invoice from subject keywords", () => {
+ expect(classifyEmail(signals({ subject: "Your invoice is due", fromAddress: "billing@acme.com" })).format).toBe("invoice");
+ });
+ it("receipt from subject keywords", () => {
+ expect(classifyEmail(signals({ subject: "Your order confirmation #1234", fromAddress: "orders@shop.com" })).format).toBe("receipt");
+ });
+ it("promotion from Gmail category", () => {
+ expect(classifyEmail(signals({ gmailCategories: ["CATEGORY_PROMOTIONS"], listUnsubscribe: "<x>" })).format).toBe("promotion");
+ });
+ it("reading from a long list email", () => {
+ expect(
+ classifyEmail(signals({ listId: "<news>", listUnsubscribe: "<x>", bodyLength: 4000, subject: "Weekly digest" })).format
+ ).toBe("reading");
+ });
+ it("notification from a short automated update", () => {
+ expect(
+ classifyEmail(signals({ fromAddress: "notifications@github.com", bodyLength: 200, gmailCategories: ["CATEGORY_UPDATES"] })).format
+ ).toBe("notification");
+ });
+ it("message for a normal human email", () => {
+ expect(classifyEmail(signals({ bodyLength: 800 })).format).toBe("message");
+ });
+ it("classifies a short automated email as a notification", () => {
+ expect(classifyEmail(signals({ fromAddress: "no-reply@x.com", bodyLength: 0, subject: null })).format).toBe("notification");
+ });
+ it("leaves format null when no heuristic is confident", () => {
+ // automated (auto_reply) but long body, direct, no categories, neutral subject →
+ // none of the format branches fire → null.
+ expect(
+ classifyEmail(signals({ precedence: "auto_reply", bodyLength: 900, subject: "Re: status" })).format
+ ).toBeNull();
+ });
+});

.changeset/facets-sdk.md

@@ -0,0 +1,5 @@
+---
+"@plotday/twister": minor
+---
+
+Added: `@plotday/twister/facets` exporting `Format`, `Automation`, `Reach`, and `ThreadFacets` for connector-emitted thread facets, and `NewLink.facets` to carry them.

connectors/gmail/package.json

@@ -30,6 +30,7 @@
  },
  "dependencies": {
  "@plotday/connector-google-contacts": "workspace:^",
+ "@plotday/email-classifier": "workspace:^",
  "@plotday/twister": "workspace:^"
  },
  "devDependencies": {

connectors/gmail/src/gmail-facets.test.ts

@@ -0,0 +1,60 @@
+import { describe, expect, it } from "vitest";
+import { gmailFacets } from "./gmail-facets";
+import type { GmailMessage } from "./gmail-api";
+
+function msg(opts: {
+ headers: Array<[string, string]>;
+ labelIds?: string[];
+}): GmailMessage {
+ return {
+ id: "m1",
+ threadId: "t1",
+ labelIds: opts.labelIds ?? [],
+ snippet: "",
+ historyId: "1",
+ internalDate: "1700000000000",
+ sizeEstimate: 0,
+ payload: {
+ mimeType: "text/plain",
+ headers: opts.headers.map(([name, value]) => ({ name, value })),
+ },
+ };
+}
+
+describe("gmailFacets", () => {
+ it("classifies a newsletter as reading/automated/list", () => {
+ const f = gmailFacets(
+ msg({
+ headers: [
+ ["From", "news@substack.com"],
+ ["To", "me@x.com"],
+ ["Subject", "The Weekly Digest"],
+ ["List-Id", "<news.substack.com>"],
+ ["List-Unsubscribe", "<mailto:u@substack.com>"],
+ ],
+ }),
+ "a".repeat(4000)
+ );
+ expect(f).toEqual({ format: "reading", automation: "automated", reach: "list" });
+ });
+
+ it("classifies a personal 1:1 email as message/human/direct", () => {
+ const f = gmailFacets(
+ msg({ headers: [["From", "jane@friends.com"], ["To", "me@x.com"], ["Subject", "Lunch?"]] }),
+ "a".repeat(500)
+ );
+ expect(f).toEqual({ format: "message", automation: "human", reach: "direct" });
+ });
+
+ it("classifies a GitHub notification", () => {
+ const f = gmailFacets(
+ msg({
+ headers: [["From", "notifications@github.com"], ["To", "me@x.com"], ["Subject", "[repo] PR merged"]],
+ labelIds: ["CATEGORY_UPDATES"],
+ }),
+ "short"
+ );
+ expect(f.format).toBe("notification");
+ expect(f.automation).toBe("automated");
+ });
+});

connectors/gmail/src/gmail-facets.ts

@@ -0,0 +1,35 @@
+import { classifyEmail, type EmailSignals } from "@plotday/email-classifier";
+import type { ThreadFacets } from "@plotday/twister/facets";
+import { getHeader, parseEmailAddress, parseEmailAddresses, type GmailMessage } from "./gmail-api";
+
+const GMAIL_CATEGORY_LABELS = new Set([
+ "CATEGORY_PROMOTIONS",
+ "CATEGORY_UPDATES",
+ "CATEGORY_SOCIAL",
+ "CATEGORY_FORUMS",
+ "CATEGORY_PERSONAL",
+]);
+
+/**
+ * Compute facets for a Gmail message. `bodyText` is the extracted body used
+ * for the length heuristic (pass the same string the note will carry).
+ */
+export function gmailFacets(message: GmailMessage, bodyText: string): ThreadFacets {
+ const signals: EmailSignals = {
+ listId: getHeader(message, "List-Id"),
+ listUnsubscribe: getHeader(message, "List-Unsubscribe"),
+ precedence: getHeader(message, "Precedence"),
+ autoSubmitted: getHeader(message, "Auto-Submitted"),
+ returnPath: getHeader(message, "Return-Path"),
+ importance: getHeader(message, "Importance") ?? getHeader(message, "X-Priority"),
+ fromAddress: parseEmailAddress(getHeader(message, "From") ?? "")?.email.toLowerCase() ?? null,
+ recipientCount:
+ parseEmailAddresses(getHeader(message, "To")).length +
+ parseEmailAddresses(getHeader(message, "Cc")).length,
+ isReply: getHeader(message, "In-Reply-To") !== null || getHeader(message, "References") !== null,
+ subject: getHeader(message, "Subject"),
+ bodyLength: bodyText.length,
+ gmailCategories: (message.labelIds ?? []).filter((l) => GMAIL_CATEGORY_LABELS.has(l)),
+ };
+ return classifyEmail(signals);
+}

connectors/gmail/src/gmail.ts

@@ -35,6 +35,7 @@ import {
  syncGmailMailboxIncremental,
  transformGmailThread,
 } from "./gmail-api";
+import { gmailFacets } from "./gmail-facets";
 
 /**
  * Persisted mailbox-wide watch state. Gmail allows one watch per (mailbox,
@@ -1350,6 +1351,18 @@ export class Gmail extends Connector<Gmail> {
  syncableId: channelId,
  };
 
+ // Compute classifier facets from the parent message's headers + body.
+ const facetParent = thread.messages.find((m) => !m.labelIds?.includes("DRAFT"));
+ if (facetParent) {
+ // Use the parent message's full note body (not the short preview snippet)
+ // so the classifier's reading-vs-notification length split can fire.
+ const facetNote = plotThread.notes?.find(
+ (n) => "key" in n && (n as { key: string }).key === facetParent.id
+ );
+ const facetBody = facetNote?.content ?? plotThread.preview ?? "";
+ plotThread.facets = gmailFacets(facetParent, facetBody);
+ }
+
  // Star ↔ todo sync: detect star changes and sync to Plot todo status.
  // Statuses have been removed; every thread (including archived) is saved
  // with no status and treated like any other thread.

connectors/slack/src/slack-facets.test.ts

@@ -0,0 +1,32 @@
+import { describe, expect, it } from "vitest";
+import { slackFacets } from "./slack-facets";
+import type { SlackMessage } from "./slack-api";
+
+function m(overrides: Partial<SlackMessage> = {}): SlackMessage {
+ return { type: "message", ts: "1.0", text: "hi", ...overrides };
+}
+
+describe("slackFacets", () => {
+ it("treats a DM human message as chat/human/direct", () => {
+ expect(slackFacets(m({ user: "U1", text: "hey there" }), "D123")).toEqual({
+ format: "chat",
+ automation: "human",
+ reach: "direct",
+ });
+ });
+ it("treats a channel post as reach=list", () => {
+ expect(slackFacets(m({ user: "U1" }), "C123").reach).toBe("list");
+ });
+ it("flags a bot message automated", () => {
+ expect(slackFacets(m({ bot_id: "B1", subtype: "bot_message" }), "C123").automation).toBe("automated");
+ });
+ it("a long post becomes a message, not chat", () => {
+ expect(slackFacets(m({ user: "U1", text: "x".repeat(1500) }), "C123").format).toBe("message");
+ });
+ it("treats a group DM (G-prefix) as reach=direct", () => {
+ expect(slackFacets(m({ user: "U1" }), "G123").reach).toBe("direct");
+ });
+ it("treats a message with no user as automated", () => {
+ expect(slackFacets(m({ user: undefined }), "C123").automation).toBe("automated");
+ });
+});

connectors/slack/src/slack-facets.ts

@@ -0,0 +1,30 @@
+import type { ThreadFacets } from "@plotday/twister/facets";
+import type { SlackMessage } from "./slack-api";
+
+// Reach is inferred from the channelId prefix (the channel object isn't in
+// scope at save time):
+// C = public or modern private channel → list (broadcast context)
+// G = group/MPIM OR legacy (pre-2020) private → treated as direct (best-effort;
+// an old private channel is misread as direct, acceptable under fail-open)
+// D = IM (DM) → direct
+function reachForChannel(channelId: string): "direct" | "list" {
+ return channelId.startsWith("C") ? "list" : "direct";
+}
+
+// A long Slack post reads as a "message" rather than a quick "chat".
+const CHAT_MAX_LENGTH = 1000;
+
+/**
+ * Compute facets for a Slack thread's parent message. Channel kind is inferred
+ * from the channelId prefix (the full channel object is not in scope at save
+ * time); this is best-effort per the facet design's fail-open principle.
+ */
+export function slackFacets(parent: SlackMessage, channelId: string): ThreadFacets {
+ const isBot = Boolean(parent.bot_id) || parent.subtype === "bot_message" || !parent.user;
+ const text = parent.text ?? "";
+ return {
+ format: text.length > CHAT_MAX_LENGTH ? "message" : "chat",
+ automation: isBot ? "automated" : "human",
+ reach: reachForChannel(channelId),
+ };
+}

connectors/slack/src/slack.ts

@@ -41,6 +41,7 @@ import {
  transformSlackThread,
 } from "./slack-api";
 import { unicodeToSlackName } from "./slack-emoji";
+import { slackFacets } from "./slack-facets";
 
 /**
  * Slack integration source.
@@ -503,6 +504,7 @@ export class Slack extends Connector<Slack> {
  syncProvider: "slack",
  syncableId: channelId,
  };
+ if (thread[0]) activityThread.facets = slackFacets(thread[0], channelId);
 
  // Save link directly via integrations
  await this.tools.integrations.saveLink(activityThread);
@@ -686,6 +688,7 @@ export class Slack extends Connector<Slack> {
  syncProvider: "slack",
  syncableId: channelId,
  };
+ if (messages[0]) link.facets = slackFacets(messages[0], channelId);
  await this.tools.integrations.saveLink(link);
  }
 
@@ -913,6 +916,7 @@ export class Slack extends Connector<Slack> {
  syncProvider: "slack",
  syncableId: channelId,
  };
+ if (messages[0]) link.facets = slackFacets(messages[0], channelId);
 
  // Suppress the onThreadToDo echo Plot will fire from this write;
  // handleStarEvent / backfillStars is already the source of truth.

libs/email-classifier/package.json

@@ -0,0 +1,30 @@
+{
+ "name": "@plotday/email-classifier",
+ "private": true,
+ "version": "0.1.0",
+ "type": "module",
+ "main": "./dist/index.js",
+ "types": "./dist/index.d.ts",
+ "exports": {
+ ".": {
+ "@plotday/connector": "./src/index.ts",
+ "types": "./dist/index.d.ts",
+ "default": "./dist/index.js"
+ }
+ },
+ "files": ["dist", "README.md"],
+ "scripts": {
+ "build": "tsc",
+ "clean": "rm -rf dist",
+ "lint": "tsc --noEmit",
+ "test": "vitest run",
+ "test:watch": "vitest"
+ },
+ "dependencies": {
+ "@plotday/twister": "workspace:^"
+ },
+ "devDependencies": {
+ "typescript": "^5.9.3",
+ "vitest": "^2.1.8"
+ }
+}

libs/email-classifier/src/classify-email.test.ts

@@ -0,0 +1,88 @@
+import { describe, expect, it } from "vitest";
+import { classifyEmail, type EmailSignals } from "./classify-email";
+
+function signals(overrides: Partial<EmailSignals> = {}): EmailSignals {
+ return {
+ listId: null,
+ listUnsubscribe: null,
+ precedence: null,
+ autoSubmitted: null,
+ returnPath: null,
+ importance: null,
+ fromAddress: "jane@example.com",
+ recipientCount: 1,
+ isReply: false,
+ subject: "Hello",
+ bodyLength: 300,
+ gmailCategories: [],
+ ...overrides,
+ };
+}
+
+describe("classifyEmail — automation", () => {
+ it("flags no-reply senders automated", () => {
+ expect(classifyEmail(signals({ fromAddress: "no-reply@acme.com" })).automation).toBe("automated");
+ });
+ it("flags Precedence: bulk automated", () => {
+ expect(classifyEmail(signals({ precedence: "bulk" })).automation).toBe("automated");
+ });
+ it("flags Auto-Submitted automated", () => {
+ expect(classifyEmail(signals({ autoSubmitted: "auto-generated" })).automation).toBe("automated");
+ });
+ it("flags mailing-list mail automated", () => {
+ expect(classifyEmail(signals({ listId: "<news.acme.com>" })).automation).toBe("automated");
+ });
+ it("treats a plain person email as human", () => {
+ expect(classifyEmail(signals()).automation).toBe("human");
+ });
+});
+
+describe("classifyEmail — reach", () => {
+ it("flags List-Id as list", () => {
+ expect(classifyEmail(signals({ listId: "<news.acme.com>" })).reach).toBe("list");
+ });
+ it("flags List-Unsubscribe as list", () => {
+ expect(classifyEmail(signals({ listUnsubscribe: "<mailto:u@acme.com>" })).reach).toBe("list");
+ });
+ it("flags high recipient count as list", () => {
+ expect(classifyEmail(signals({ recipientCount: 12 })).reach).toBe("list");
+ });
+ it("treats a 1:1 email as direct", () => {
+ expect(classifyEmail(signals()).reach).toBe("direct");
+ });
+});
+
+describe("classifyEmail — format", () => {
+ it("invoice from subject keywords", () => {
+ expect(classifyEmail(signals({ subject: "Your invoice is due", fromAddress: "billing@acme.com" })).format).toBe("invoice");
+ });
+ it("receipt from subject keywords", () => {
+ expect(classifyEmail(signals({ subject: "Your order confirmation #1234", fromAddress: "orders@shop.com" })).format).toBe("receipt");
+ });
+ it("promotion from Gmail category", () => {
+ expect(classifyEmail(signals({ gmailCategories: ["CATEGORY_PROMOTIONS"], listUnsubscribe: "<x>" })).format).toBe("promotion");
+ });
+ it("reading from a long list email", () => {
+ expect(
+ classifyEmail(signals({ listId: "<news>", listUnsubscribe: "<x>", bodyLength: 4000, subject: "Weekly digest" })).format
+ ).toBe("reading");
+ });
+ it("notification from a short automated update", () => {
+ expect(
+ classifyEmail(signals({ fromAddress: "notifications@github.com", bodyLength: 200, gmailCategories: ["CATEGORY_UPDATES"] })).format
+ ).toBe("notification");
+ });
+ it("message for a normal human email", () => {
+ expect(classifyEmail(signals({ bodyLength: 800 })).format).toBe("message");
+ });
+ it("classifies a short automated email as a notification", () => {
+ expect(classifyEmail(signals({ fromAddress: "no-reply@x.com", bodyLength: 0, subject: null })).format).toBe("notification");
+ });
+ it("leaves format null when no heuristic is confident", () => {
+ // automated (auto_reply) but long body, direct, no categories, neutral subject →
+ // none of the format branches fire → null.
+ expect(
+ classifyEmail(signals({ precedence: "auto_reply", bodyLength: 900, subject: "Re: status" })).format
+ ).toBeNull();
+ });
+});