Native forward: supportsForward SDK flag + Gmail message forwarding

.changeset/forward-a-note.md

@@ -0,0 +1,5 @@
+---
+"@plotday/twister": minor
+---
+
+Added: `LinkTypeConfig.supportsForward` and `CreateLinkDraft.forward` so connectors can perform native forwards of existing items (e.g. email forwards carrying the original message and attachments) when a user forwards a note.

connectors/gmail/src/channels.ts

@@ -44,6 +44,10 @@ export const GMAIL_LINK_TYPES: LinkTypeConfig[] = [
  compose: {
  targets: "addresses" as const,
  },
+ // onCreateLink reconstructs a real Gmail forward (original message +
+ // attachments) when `CreateLinkDraft.forward` is set, so the runtime
+ // should route native forwards here instead of the blockquote fallback.
+ supportsForward: true,
  },
 ];
 

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

@@ -1,6 +1,7 @@
 import { afterEach, describe, expect, it, vi } from "vitest";
 import {
  GmailApi,
+ buildForwardMessage,
  buildNewEmailMessage,
  buildReplyMessage,
  stripQuotedReply,
@@ -319,3 +320,78 @@ describe("outbound MIME bodies (multipart/alternative HTML + plain)", () => {
  expect(decodeMimePart(raw, "text/plain")).not.toContain("**");
  });
 });
+
+describe("buildForwardMessage", () => {
+ it("uses a Fwd: subject and includes the quoted original + forwarder message", () => {
+ const raw = decodeRawMessage(
+ buildForwardMessage({
+ to: ["bob@example.com"],
+ cc: [],
+ from: "me@example.com",
+ subject: "Q3 budget",
+ body: "See below.",
+ originalHeader: "From: Alice <alice@example.com>\nSubject: Q3 budget",
+ originalBody: "Let's meet Thursday.",
+ })
+ );
+ expect(raw).toContain("Subject: Fwd: Q3 budget");
+ expect(raw).not.toContain("In-Reply-To:");
+
+ // Body content lives base64-encoded inside the multipart/alternative
+ // plain-text part, so decode that part rather than scanning the raw
+ // (still-encoded) message for the literal text.
+ const text = decodeMimePart(raw, "text/plain");
+ expect(text).toContain("See below.");
+ expect(text).toContain("Let's meet Thursday.");
+ });
+
+ it("keeps an existing Fwd: prefix instead of doubling it", () => {
+ const raw = decodeRawMessage(
+ buildForwardMessage({
+ to: ["b@x.com"],
+ cc: [],
+ from: "m@x.com",
+ subject: "Fwd: hi",
+ body: "",
+ originalHeader: "From: a@x.com",
+ originalBody: "hi",
+ })
+ );
+ expect(raw).toContain("Subject: Fwd: hi");
+ expect(raw).not.toContain("Fwd: Fwd:");
+ });
+
+ it("emits a Bcc header without exposing bcc addresses in To/Cc", () => {
+ const raw = decodeRawMessage(
+ buildForwardMessage({
+ to: ["bob@example.com"],
+ cc: ["carol@example.com"],
+ bcc: ["dave@example.com"],
+ from: "me@example.com",
+ subject: "Q3 budget",
+ body: "",
+ originalHeader: "From: Alice <alice@example.com>",
+ originalBody: "hi",
+ })
+ );
+ expect(raw).toContain("Bcc: dave@example.com");
+ expect(raw).toContain("To: bob@example.com");
+ expect(raw).not.toContain("To: bob@example.com, dave@example.com");
+ expect(raw).not.toContain("Cc: carol@example.com, dave@example.com");
+ });
+
+ it("omits the Bcc header entirely when there are no bcc recipients", () => {
+ const raw = decodeRawMessage(
+ buildForwardMessage({
+ to: ["bob@example.com"],
+ cc: [],
+ from: "me@example.com",
+ subject: "Q3 budget",
+ body: "",
+ originalHeader: "From: Alice <alice@example.com>",
+ originalBody: "hi",
+ })
+ );
+ expect(raw).not.toContain("Bcc:");
+ });
+});

connectors/gmail/src/gmail-api.ts

@@ -283,6 +283,21 @@ export class GmailApi {
  return data as GmailThread;
  }
 
+ /**
+ * Fetches a single message by id. Used to source a native forward (see
+ * `buildForwardMessage`), where the caller has a message id — the note
+ * `key` a Gmail-backed note carries — rather than a thread id.
+ */
+ public async getMessage(
+ messageId: string,
+ format: "full" | "minimal" | "metadata" | "raw" = "full"
+ ): Promise<GmailMessage> {
+ const data = await this.call(`/messages/${messageId}`, {
+ params: { format },
+ });
+ return data as GmailMessage;
+ }
+
  public async setupWatch(
  topicName: string,
  labelId?: string
@@ -584,7 +599,7 @@ export function isFromAddressRewritten(
  * Extracts the body from a Gmail message (handles multipart messages).
  * Returns raw content with its type so HTML can be converted server-side.
  */
-function extractBody(part: GmailMessagePart): { content: string; contentType: "text" | "html" } {
+export function extractBody(part: GmailMessagePart): { content: string; contentType: "text" | "html" } {
  // Prefer HTML over plain text — server-side conversion produces cleaner output.
  // Search the WHOLE MIME tree, not just immediate children: forwarded messages
  // nest the real body inside a `message/rfc822` part (or a deeper multipart),
@@ -1457,3 +1472,116 @@ export function buildReplyMessage(options: {
 
  return base64UrlEncodeMessage(rawMessage);
 }
+
+/**
+ * Builds an RFC 2822 forward of an existing Gmail message. Gmail has no
+ * native "forward" endpoint — a forward is just a new message sent via
+ * `messages.send`. Unlike a reply, a forward starts a NEW thread (no
+ * `In-Reply-To` / `References`). The body is the forwarder's own message
+ * followed by a standard quoted-original attribution block; the original
+ * message's attachments are re-attached.
+ * Returns the base64url-encoded raw message string for the Gmail API.
+ */
+export function buildForwardMessage(options: {
+ to: string[];
+ cc: string[];
+ /**
+ * Optional — a forward's recipients come from the same role-tagged picker
+ * as a compose, so a bcc-role recipient can appear here. Defaults to none.
+ * Gmail's send API delivers to Bcc recipients and strips the Bcc header
+ * from the copy other recipients receive (same as `buildNewEmailMessage`),
+ * so listing them here does not expose them.
+ */
+ bcc?: string[];
+ from: string;
+ subject: string;
+ body: string;
+ originalHeader: string; // e.g. "From: … \n Date: … \n Subject: … \n To: …"
+ originalBody: string; // the original message's text/markdown body
+ attachments?: AttachmentData[];
+}): string {
+ const {
+ to,
+ cc,
+ bcc = [],
+ from,
+ subject,
+ body,
+ originalHeader,
+ originalBody,
+ attachments,
+ } = options;
+
+ // Sanitize every value interpolated into a header to prevent CRLF header
+ // injection (RFC 5322) via attacker-controlled subjects or addresses.
+ const fromHeader = sanitizeHeaderValue(from);
+ const toHeader = to.map(sanitizeHeaderValue).join(", ");
+ const ccHeader = cc.map(sanitizeHeaderValue).join(", ");
+ const bccHeader = bcc.map(sanitizeHeaderValue).join(", ");
+
+ // Ensure subject has a "Fwd:" prefix, without doubling an existing one.
+ const fwdSubject = sanitizeHeaderValue(
+ subject.startsWith("Fwd:") ? subject : `Fwd: ${subject}`
+ );
+
+ // A forward starts a new thread, so — unlike buildReplyMessage — there is
+ // no In-Reply-To / References header here.
+ const headerLines: string[] = [`From: ${fromHeader}`, `To: ${toHeader}`];
+ if (cc.length > 0) headerLines.push(`Cc: ${ccHeader}`);
+ if (bcc.length > 0) headerLines.push(`Bcc: ${bccHeader}`);
+ headerLines.push(`Subject: ${fwdSubject}`);
+ headerLines.push(`MIME-Version: 1.0`);
+
+ // Compose the visible body: the forwarder's own message (if any) on top of
+ // a standard quoted-original attribution block.
+ const quotedOriginal = [
+ "---------- Forwarded message ----------",
+ originalHeader,
+ "",
+ originalBody,
+ ].join("\n");
+ const composed = body.length > 0 ? `${body}\n\n${quotedOriginal}` : quotedOriginal;
+
+ // The body is always a multipart/alternative (plain text + rendered HTML) so
+ // recipients get clean formatting and MTAs don't hard-wrap raw Markdown.
+ const altBoundary = mimeBoundary("alt");
+ const altBlock = buildAlternativeBlock(altBoundary, composed);
+
+ let rawMessage: string;
+
+ if (attachments && attachments.length > 0) {
+ // Wrap the alternative body and the re-attached attachments in a
+ // multipart/mixed.
+ const mixBoundary = mimeBoundary("mix");
+
+ const attachmentParts: string[] = [];
+ for (const att of attachments) {
+ const b64Lines = uint8ArrayToBase64Lines(att.data);
+ // Encode filename for Content-Disposition
+ const safeFileName = att.fileName.replace(/[\r\n"]/g, "_");
+ attachmentParts.push(
+ `--${mixBoundary}`,
+ `Content-Type: ${att.mimeType}; name="${safeFileName}"`,
+ `Content-Transfer-Encoding: base64`,
+ `Content-Disposition: attachment; filename="${safeFileName}"`,
+ "",
+ b64Lines,
+ );
+ }
+
+ rawMessage = [
+ ...headerLines,
+ `Content-Type: multipart/mixed; boundary="${mixBoundary}"`,
+ "", // end of message headers
+ `--${mixBoundary}`,
+ ...altBlock,
+ ...attachmentParts,
+ `--${mixBoundary}--`,
+ ].join("\r\n");
+ } else {
+ // Top-level body is the multipart/alternative entity itself.
+ rawMessage = [...headerLines, ...altBlock].join("\r\n");
+ }
+
+ return base64UrlEncodeMessage(rawMessage);
+}

.changeset/forward-a-note.md

@@ -0,0 +1,5 @@
+---
+"@plotday/twister": minor
+---
+
+Added: `LinkTypeConfig.supportsForward` and `CreateLinkDraft.forward` so connectors can perform native forwards of existing items (e.g. email forwards carrying the original message and attachments) when a user forwards a note.

connectors/gmail/src/channels.ts

@@ -44,6 +44,10 @@ export const GMAIL_LINK_TYPES: LinkTypeConfig[] = [
  compose: {
  targets: "addresses" as const,
  },
+ // onCreateLink reconstructs a real Gmail forward (original message +
+ // attachments) when `CreateLinkDraft.forward` is set, so the runtime
+ // should route native forwards here instead of the blockquote fallback.
+ supportsForward: true,
  },
 ];
 

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

@@ -1,6 +1,7 @@
 import { afterEach, describe, expect, it, vi } from "vitest";
 import {
  GmailApi,
+ buildForwardMessage,
  buildNewEmailMessage,
  buildReplyMessage,
  stripQuotedReply,
@@ -319,3 +320,78 @@ describe("outbound MIME bodies (multipart/alternative HTML + plain)", () => {
  expect(decodeMimePart(raw, "text/plain")).not.toContain("**");
  });
 });
+
+describe("buildForwardMessage", () => {
+ it("uses a Fwd: subject and includes the quoted original + forwarder message", () => {
+ const raw = decodeRawMessage(
+ buildForwardMessage({
+ to: ["bob@example.com"],
+ cc: [],
+ from: "me@example.com",
+ subject: "Q3 budget",
+ body: "See below.",
+ originalHeader: "From: Alice <alice@example.com>\nSubject: Q3 budget",
+ originalBody: "Let's meet Thursday.",
+ })
+ );
+ expect(raw).toContain("Subject: Fwd: Q3 budget");
+ expect(raw).not.toContain("In-Reply-To:");
+
+ // Body content lives base64-encoded inside the multipart/alternative
+ // plain-text part, so decode that part rather than scanning the raw
+ // (still-encoded) message for the literal text.
+ const text = decodeMimePart(raw, "text/plain");
+ expect(text).toContain("See below.");
+ expect(text).toContain("Let's meet Thursday.");
+ });
+
+ it("keeps an existing Fwd: prefix instead of doubling it", () => {
+ const raw = decodeRawMessage(
+ buildForwardMessage({
+ to: ["b@x.com"],
+ cc: [],
+ from: "m@x.com",
+ subject: "Fwd: hi",
+ body: "",
+ originalHeader: "From: a@x.com",
+ originalBody: "hi",
+ })
+ );
+ expect(raw).toContain("Subject: Fwd: hi");
+ expect(raw).not.toContain("Fwd: Fwd:");
+ });
+
+ it("emits a Bcc header without exposing bcc addresses in To/Cc", () => {
+ const raw = decodeRawMessage(
+ buildForwardMessage({
+ to: ["bob@example.com"],
+ cc: ["carol@example.com"],
+ bcc: ["dave@example.com"],
+ from: "me@example.com",
+ subject: "Q3 budget",
+ body: "",
+ originalHeader: "From: Alice <alice@example.com>",
+ originalBody: "hi",
+ })
+ );
+ expect(raw).toContain("Bcc: dave@example.com");
+ expect(raw).toContain("To: bob@example.com");
+ expect(raw).not.toContain("To: bob@example.com, dave@example.com");
+ expect(raw).not.toContain("Cc: carol@example.com, dave@example.com");
+ });
+
+ it("omits the Bcc header entirely when there are no bcc recipients", () => {
+ const raw = decodeRawMessage(
+ buildForwardMessage({
+ to: ["bob@example.com"],
+ cc: [],
+ from: "me@example.com",
+ subject: "Q3 budget",
+ body: "",
+ originalHeader: "From: Alice <alice@example.com>",
+ originalBody: "hi",
+ })
+ );
+ expect(raw).not.toContain("Bcc:");
+ });
+});

connectors/gmail/src/gmail-api.ts

@@ -283,6 +283,21 @@ export class GmailApi {
  return data as GmailThread;
  }
 
+ /**
+ * Fetches a single message by id. Used to source a native forward (see
+ * `buildForwardMessage`), where the caller has a message id — the note
+ * `key` a Gmail-backed note carries — rather than a thread id.
+ */
+ public async getMessage(
+ messageId: string,
+ format: "full" | "minimal" | "metadata" | "raw" = "full"
+ ): Promise<GmailMessage> {
+ const data = await this.call(`/messages/${messageId}`, {
+ params: { format },
+ });
+ return data as GmailMessage;
+ }
+
  public async setupWatch(
  topicName: string,
  labelId?: string
@@ -584,7 +599,7 @@ export function isFromAddressRewritten(
  * Extracts the body from a Gmail message (handles multipart messages).
  * Returns raw content with its type so HTML can be converted server-side.
  */
-function extractBody(part: GmailMessagePart): { content: string; contentType: "text" | "html" } {
+export function extractBody(part: GmailMessagePart): { content: string; contentType: "text" | "html" } {
  // Prefer HTML over plain text — server-side conversion produces cleaner output.
  // Search the WHOLE MIME tree, not just immediate children: forwarded messages
  // nest the real body inside a `message/rfc822` part (or a deeper multipart),
@@ -1457,3 +1472,116 @@ export function buildReplyMessage(options: {
 
  return base64UrlEncodeMessage(rawMessage);
 }
+
+/**
+ * Builds an RFC 2822 forward of an existing Gmail message. Gmail has no
+ * native "forward" endpoint — a forward is just a new message sent via
+ * `messages.send`. Unlike a reply, a forward starts a NEW thread (no
+ * `In-Reply-To` / `References`). The body is the forwarder's own message
+ * followed by a standard quoted-original attribution block; the original
+ * message's attachments are re-attached.
+ * Returns the base64url-encoded raw message string for the Gmail API.
+ */
+export function buildForwardMessage(options: {
+ to: string[];
+ cc: string[];
+ /**
+ * Optional — a forward's recipients come from the same role-tagged picker
+ * as a compose, so a bcc-role recipient can appear here. Defaults to none.
+ * Gmail's send API delivers to Bcc recipients and strips the Bcc header
+ * from the copy other recipients receive (same as `buildNewEmailMessage`),
+ * so listing them here does not expose them.
+ */
+ bcc?: string[];
+ from: string;
+ subject: string;
+ body: string;
+ originalHeader: string; // e.g. "From: … \n Date: … \n Subject: … \n To: …"
+ originalBody: string; // the original message's text/markdown body
+ attachments?: AttachmentData[];
+}): string {
+ const {
+ to,
+ cc,
+ bcc = [],
+ from,
+ subject,
+ body,
+ originalHeader,
+ originalBody,
+ attachments,
+ } = options;
+
+ // Sanitize every value interpolated into a header to prevent CRLF header
+ // injection (RFC 5322) via attacker-controlled subjects or addresses.
+ const fromHeader = sanitizeHeaderValue(from);
+ const toHeader = to.map(sanitizeHeaderValue).join(", ");
+ const ccHeader = cc.map(sanitizeHeaderValue).join(", ");
+ const bccHeader = bcc.map(sanitizeHeaderValue).join(", ");
+
+ // Ensure subject has a "Fwd:" prefix, without doubling an existing one.
+ const fwdSubject = sanitizeHeaderValue(
+ subject.startsWith("Fwd:") ? subject : `Fwd: ${subject}`
+ );
+
+ // A forward starts a new thread, so — unlike buildReplyMessage — there is
+ // no In-Reply-To / References header here.
+ const headerLines: string[] = [`From: ${fromHeader}`, `To: ${toHeader}`];
+ if (cc.length > 0) headerLines.push(`Cc: ${ccHeader}`);
+ if (bcc.length > 0) headerLines.push(`Bcc: ${bccHeader}`);
+ headerLines.push(`Subject: ${fwdSubject}`);
+ headerLines.push(`MIME-Version: 1.0`);
+
+ // Compose the visible body: the forwarder's own message (if any) on top of
+ // a standard quoted-original attribution block.
+ const quotedOriginal = [
+ "---------- Forwarded message ----------",
+ originalHeader,
+ "",
+ originalBody,
+ ].join("\n");
+ const composed = body.length > 0 ? `${body}\n\n${quotedOriginal}` : quotedOriginal;
+
+ // The body is always a multipart/alternative (plain text + rendered HTML) so
+ // recipients get clean formatting and MTAs don't hard-wrap raw Markdown.
+ const altBoundary = mimeBoundary("alt");
+ const altBlock = buildAlternativeBlock(altBoundary, composed);
+
+ let rawMessage: string;
+
+ if (attachments && attachments.length > 0) {
+ // Wrap the alternative body and the re-attached attachments in a
+ // multipart/mixed.
+ const mixBoundary = mimeBoundary("mix");
+
+ const attachmentParts: string[] = [];
+ for (const att of attachments) {
+ const b64Lines = uint8ArrayToBase64Lines(att.data);
+ // Encode filename for Content-Disposition
+ const safeFileName = att.fileName.replace(/[\r\n"]/g, "_");
+ attachmentParts.push(
+ `--${mixBoundary}`,
+ `Content-Type: ${att.mimeType}; name="${safeFileName}"`,
+ `Content-Transfer-Encoding: base64`,
+ `Content-Disposition: attachment; filename="${safeFileName}"`,
+ "",
+ b64Lines,
+ );
+ }
+
+ rawMessage = [
+ ...headerLines,
+ `Content-Type: multipart/mixed; boundary="${mixBoundary}"`,
+ "", // end of message headers
+ `--${mixBoundary}`,
+ ...altBlock,
+ ...attachmentParts,
+ `--${mixBoundary}--`,
+ ].join("\r\n");
+ } else {
+ // Top-level body is the multipart/alternative entity itself.
+ rawMessage = [...headerLines, ...altBlock].join("\r\n");
+ }
+
+ return base64UrlEncodeMessage(rawMessage);
+}

.changeset/forward-a-note.md

@@ -0,0 +1,5 @@
+---
+"@plotday/twister": minor
+---
+
+Added: `LinkTypeConfig.supportsForward` and `CreateLinkDraft.forward` so connectors can perform native forwards of existing items (e.g. email forwards carrying the original message and attachments) when a user forwards a note.

connectors/gmail/src/channels.ts

@@ -44,6 +44,10 @@ export const GMAIL_LINK_TYPES: LinkTypeConfig[] = [
  compose: {
  targets: "addresses" as const,
  },
+ // onCreateLink reconstructs a real Gmail forward (original message +
+ // attachments) when `CreateLinkDraft.forward` is set, so the runtime
+ // should route native forwards here instead of the blockquote fallback.
+ supportsForward: true,
  },
 ];
 

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

@@ -1,6 +1,7 @@
 import { afterEach, describe, expect, it, vi } from "vitest";
 import {
  GmailApi,
+ buildForwardMessage,
  buildNewEmailMessage,
  buildReplyMessage,
  stripQuotedReply,
@@ -319,3 +320,78 @@ describe("outbound MIME bodies (multipart/alternative HTML + plain)", () => {
  expect(decodeMimePart(raw, "text/plain")).not.toContain("**");
  });
 });
+
+describe("buildForwardMessage", () => {
+ it("uses a Fwd: subject and includes the quoted original + forwarder message", () => {
+ const raw = decodeRawMessage(
+ buildForwardMessage({
+ to: ["bob@example.com"],
+ cc: [],
+ from: "me@example.com",
+ subject: "Q3 budget",
+ body: "See below.",
+ originalHeader: "From: Alice <alice@example.com>\nSubject: Q3 budget",
+ originalBody: "Let's meet Thursday.",
+ })
+ );
+ expect(raw).toContain("Subject: Fwd: Q3 budget");
+ expect(raw).not.toContain("In-Reply-To:");
+
+ // Body content lives base64-encoded inside the multipart/alternative
+ // plain-text part, so decode that part rather than scanning the raw
+ // (still-encoded) message for the literal text.
+ const text = decodeMimePart(raw, "text/plain");
+ expect(text).toContain("See below.");
+ expect(text).toContain("Let's meet Thursday.");
+ });
+
+ it("keeps an existing Fwd: prefix instead of doubling it", () => {
+ const raw = decodeRawMessage(
+ buildForwardMessage({
+ to: ["b@x.com"],
+ cc: [],
+ from: "m@x.com",
+ subject: "Fwd: hi",
+ body: "",
+ originalHeader: "From: a@x.com",
+ originalBody: "hi",
+ })
+ );
+ expect(raw).toContain("Subject: Fwd: hi");
+ expect(raw).not.toContain("Fwd: Fwd:");
+ });
+
+ it("emits a Bcc header without exposing bcc addresses in To/Cc", () => {
+ const raw = decodeRawMessage(
+ buildForwardMessage({
+ to: ["bob@example.com"],
+ cc: ["carol@example.com"],
+ bcc: ["dave@example.com"],
+ from: "me@example.com",
+ subject: "Q3 budget",
+ body: "",
+ originalHeader: "From: Alice <alice@example.com>",
+ originalBody: "hi",
+ })
+ );
+ expect(raw).toContain("Bcc: dave@example.com");
+ expect(raw).toContain("To: bob@example.com");
+ expect(raw).not.toContain("To: bob@example.com, dave@example.com");
+ expect(raw).not.toContain("Cc: carol@example.com, dave@example.com");
+ });
+
+ it("omits the Bcc header entirely when there are no bcc recipients", () => {
+ const raw = decodeRawMessage(
+ buildForwardMessage({
+ to: ["bob@example.com"],
+ cc: [],
+ from: "me@example.com",
+ subject: "Q3 budget",
+ body: "",
+ originalHeader: "From: Alice <alice@example.com>",
+ originalBody: "hi",
+ })
+ );
+ expect(raw).not.toContain("Bcc:");
+ });
+});

connectors/gmail/src/gmail-api.ts

@@ -283,6 +283,21 @@ export class GmailApi {
  return data as GmailThread;
  }
 
+ /**
+ * Fetches a single message by id. Used to source a native forward (see
+ * `buildForwardMessage`), where the caller has a message id — the note
+ * `key` a Gmail-backed note carries — rather than a thread id.
+ */
+ public async getMessage(
+ messageId: string,
+ format: "full" | "minimal" | "metadata" | "raw" = "full"
+ ): Promise<GmailMessage> {
+ const data = await this.call(`/messages/${messageId}`, {
+ params: { format },
+ });
+ return data as GmailMessage;
+ }
+
  public async setupWatch(
  topicName: string,
  labelId?: string
@@ -584,7 +599,7 @@ export function isFromAddressRewritten(
  * Extracts the body from a Gmail message (handles multipart messages).
  * Returns raw content with its type so HTML can be converted server-side.
  */
-function extractBody(part: GmailMessagePart): { content: string; contentType: "text" | "html" } {
+export function extractBody(part: GmailMessagePart): { content: string; contentType: "text" | "html" } {
  // Prefer HTML over plain text — server-side conversion produces cleaner output.
  // Search the WHOLE MIME tree, not just immediate children: forwarded messages
  // nest the real body inside a `message/rfc822` part (or a deeper multipart),
@@ -1457,3 +1472,116 @@ export function buildReplyMessage(options: {
 
  return base64UrlEncodeMessage(rawMessage);
 }
+
+/**
+ * Builds an RFC 2822 forward of an existing Gmail message. Gmail has no
+ * native "forward" endpoint — a forward is just a new message sent via
+ * `messages.send`. Unlike a reply, a forward starts a NEW thread (no
+ * `In-Reply-To` / `References`). The body is the forwarder's own message
+ * followed by a standard quoted-original attribution block; the original
+ * message's attachments are re-attached.
+ * Returns the base64url-encoded raw message string for the Gmail API.
+ */
+export function buildForwardMessage(options: {
+ to: string[];
+ cc: string[];
+ /**
+ * Optional — a forward's recipients come from the same role-tagged picker
+ * as a compose, so a bcc-role recipient can appear here. Defaults to none.
+ * Gmail's send API delivers to Bcc recipients and strips the Bcc header
+ * from the copy other recipients receive (same as `buildNewEmailMessage`),
+ * so listing them here does not expose them.
+ */
+ bcc?: string[];
+ from: string;
+ subject: string;
+ body: string;
+ originalHeader: string; // e.g. "From: … \n Date: … \n Subject: … \n To: …"
+ originalBody: string; // the original message's text/markdown body
+ attachments?: AttachmentData[];
+}): string {
+ const {
+ to,
+ cc,
+ bcc = [],
+ from,
+ subject,
+ body,
+ originalHeader,
+ originalBody,
+ attachments,
+ } = options;
+
+ // Sanitize every value interpolated into a header to prevent CRLF header
+ // injection (RFC 5322) via attacker-controlled subjects or addresses.
+ const fromHeader = sanitizeHeaderValue(from);
+ const toHeader = to.map(sanitizeHeaderValue).join(", ");
+ const ccHeader = cc.map(sanitizeHeaderValue).join(", ");
+ const bccHeader = bcc.map(sanitizeHeaderValue).join(", ");
+
+ // Ensure subject has a "Fwd:" prefix, without doubling an existing one.
+ const fwdSubject = sanitizeHeaderValue(
+ subject.startsWith("Fwd:") ? subject : `Fwd: ${subject}`
+ );
+
+ // A forward starts a new thread, so — unlike buildReplyMessage — there is
+ // no In-Reply-To / References header here.
+ const headerLines: string[] = [`From: ${fromHeader}`, `To: ${toHeader}`];
+ if (cc.length > 0) headerLines.push(`Cc: ${ccHeader}`);
+ if (bcc.length > 0) headerLines.push(`Bcc: ${bccHeader}`);
+ headerLines.push(`Subject: ${fwdSubject}`);
+ headerLines.push(`MIME-Version: 1.0`);
+
+ // Compose the visible body: the forwarder's own message (if any) on top of
+ // a standard quoted-original attribution block.
+ const quotedOriginal = [
+ "---------- Forwarded message ----------",
+ originalHeader,
+ "",
+ originalBody,
+ ].join("\n");
+ const composed = body.length > 0 ? `${body}\n\n${quotedOriginal}` : quotedOriginal;
+
+ // The body is always a multipart/alternative (plain text + rendered HTML) so
+ // recipients get clean formatting and MTAs don't hard-wrap raw Markdown.
+ const altBoundary = mimeBoundary("alt");
+ const altBlock = buildAlternativeBlock(altBoundary, composed);
+
+ let rawMessage: string;
+
+ if (attachments && attachments.length > 0) {
+ // Wrap the alternative body and the re-attached attachments in a
+ // multipart/mixed.
+ const mixBoundary = mimeBoundary("mix");
+
+ const attachmentParts: string[] = [];
+ for (const att of attachments) {
+ const b64Lines = uint8ArrayToBase64Lines(att.data);
+ // Encode filename for Content-Disposition
+ const safeFileName = att.fileName.replace(/[\r\n"]/g, "_");
+ attachmentParts.push(
+ `--${mixBoundary}`,
+ `Content-Type: ${att.mimeType}; name="${safeFileName}"`,
+ `Content-Transfer-Encoding: base64`,
+ `Content-Disposition: attachment; filename="${safeFileName}"`,
+ "",
+ b64Lines,
+ );
+ }
+
+ rawMessage = [
+ ...headerLines,
+ `Content-Type: multipart/mixed; boundary="${mixBoundary}"`,
+ "", // end of message headers
+ `--${mixBoundary}`,
+ ...altBlock,
+ ...attachmentParts,
+ `--${mixBoundary}--`,
+ ].join("\r\n");
+ } else {
+ // Top-level body is the multipart/alternative entity itself.
+ rawMessage = [...headerLines, ...altBlock].join("\r\n");
+ }
+
+ return base64UrlEncodeMessage(rawMessage);
+}

.changeset/forward-a-note.md

@@ -0,0 +1,5 @@
+---
+"@plotday/twister": minor
+---
+
+Added: `LinkTypeConfig.supportsForward` and `CreateLinkDraft.forward` so connectors can perform native forwards of existing items (e.g. email forwards carrying the original message and attachments) when a user forwards a note.

connectors/gmail/src/channels.ts

@@ -44,6 +44,10 @@ export const GMAIL_LINK_TYPES: LinkTypeConfig[] = [
  compose: {
  targets: "addresses" as const,
  },
+ // onCreateLink reconstructs a real Gmail forward (original message +
+ // attachments) when `CreateLinkDraft.forward` is set, so the runtime
+ // should route native forwards here instead of the blockquote fallback.
+ supportsForward: true,
  },
 ];
 

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

@@ -1,6 +1,7 @@
 import { afterEach, describe, expect, it, vi } from "vitest";
 import {
  GmailApi,
+ buildForwardMessage,
  buildNewEmailMessage,
  buildReplyMessage,
  stripQuotedReply,
@@ -319,3 +320,78 @@ describe("outbound MIME bodies (multipart/alternative HTML + plain)", () => {
  expect(decodeMimePart(raw, "text/plain")).not.toContain("**");
  });
 });
+
+describe("buildForwardMessage", () => {
+ it("uses a Fwd: subject and includes the quoted original + forwarder message", () => {
+ const raw = decodeRawMessage(
+ buildForwardMessage({
+ to: ["bob@example.com"],
+ cc: [],
+ from: "me@example.com",
+ subject: "Q3 budget",
+ body: "See below.",
+ originalHeader: "From: Alice <alice@example.com>\nSubject: Q3 budget",
+ originalBody: "Let's meet Thursday.",
+ })
+ );
+ expect(raw).toContain("Subject: Fwd: Q3 budget");
+ expect(raw).not.toContain("In-Reply-To:");
+
+ // Body content lives base64-encoded inside the multipart/alternative
+ // plain-text part, so decode that part rather than scanning the raw
+ // (still-encoded) message for the literal text.
+ const text = decodeMimePart(raw, "text/plain");
+ expect(text).toContain("See below.");
+ expect(text).toContain("Let's meet Thursday.");
+ });
+
+ it("keeps an existing Fwd: prefix instead of doubling it", () => {
+ const raw = decodeRawMessage(
+ buildForwardMessage({
+ to: ["b@x.com"],
+ cc: [],
+ from: "m@x.com",
+ subject: "Fwd: hi",
+ body: "",
+ originalHeader: "From: a@x.com",
+ originalBody: "hi",
+ })
+ );
+ expect(raw).toContain("Subject: Fwd: hi");
+ expect(raw).not.toContain("Fwd: Fwd:");
+ });
+
+ it("emits a Bcc header without exposing bcc addresses in To/Cc", () => {
+ const raw = decodeRawMessage(
+ buildForwardMessage({
+ to: ["bob@example.com"],
+ cc: ["carol@example.com"],
+ bcc: ["dave@example.com"],
+ from: "me@example.com",
+ subject: "Q3 budget",
+ body: "",
+ originalHeader: "From: Alice <alice@example.com>",
+ originalBody: "hi",
+ })
+ );
+ expect(raw).toContain("Bcc: dave@example.com");
+ expect(raw).toContain("To: bob@example.com");
+ expect(raw).not.toContain("To: bob@example.com, dave@example.com");
+ expect(raw).not.toContain("Cc: carol@example.com, dave@example.com");
+ });
+
+ it("omits the Bcc header entirely when there are no bcc recipients", () => {
+ const raw = decodeRawMessage(
+ buildForwardMessage({
+ to: ["bob@example.com"],
+ cc: [],
+ from: "me@example.com",
+ subject: "Q3 budget",
+ body: "",
+ originalHeader: "From: Alice <alice@example.com>",
+ originalBody: "hi",
+ })
+ );
+ expect(raw).not.toContain("Bcc:");
+ });
+});

connectors/gmail/src/gmail-api.ts

@@ -283,6 +283,21 @@ export class GmailApi {
  return data as GmailThread;
  }
 
+ /**
+ * Fetches a single message by id. Used to source a native forward (see
+ * `buildForwardMessage`), where the caller has a message id — the note
+ * `key` a Gmail-backed note carries — rather than a thread id.
+ */
+ public async getMessage(
+ messageId: string,
+ format: "full" | "minimal" | "metadata" | "raw" = "full"
+ ): Promise<GmailMessage> {
+ const data = await this.call(`/messages/${messageId}`, {
+ params: { format },
+ });
+ return data as GmailMessage;
+ }
+
  public async setupWatch(
  topicName: string,
  labelId?: string
@@ -584,7 +599,7 @@ export function isFromAddressRewritten(
  * Extracts the body from a Gmail message (handles multipart messages).
  * Returns raw content with its type so HTML can be converted server-side.
  */
-function extractBody(part: GmailMessagePart): { content: string; contentType: "text" | "html" } {
+export function extractBody(part: GmailMessagePart): { content: string; contentType: "text" | "html" } {
  // Prefer HTML over plain text — server-side conversion produces cleaner output.
  // Search the WHOLE MIME tree, not just immediate children: forwarded messages
  // nest the real body inside a `message/rfc822` part (or a deeper multipart),
@@ -1457,3 +1472,116 @@ export function buildReplyMessage(options: {
 
  return base64UrlEncodeMessage(rawMessage);
 }
+
+/**
+ * Builds an RFC 2822 forward of an existing Gmail message. Gmail has no
+ * native "forward" endpoint — a forward is just a new message sent via
+ * `messages.send`. Unlike a reply, a forward starts a NEW thread (no
+ * `In-Reply-To` / `References`). The body is the forwarder's own message
+ * followed by a standard quoted-original attribution block; the original
+ * message's attachments are re-attached.
+ * Returns the base64url-encoded raw message string for the Gmail API.
+ */
+export function buildForwardMessage(options: {
+ to: string[];
+ cc: string[];
+ /**
+ * Optional — a forward's recipients come from the same role-tagged picker
+ * as a compose, so a bcc-role recipient can appear here. Defaults to none.
+ * Gmail's send API delivers to Bcc recipients and strips the Bcc header
+ * from the copy other recipients receive (same as `buildNewEmailMessage`),
+ * so listing them here does not expose them.
+ */
+ bcc?: string[];
+ from: string;
+ subject: string;
+ body: string;
+ originalHeader: string; // e.g. "From: … \n Date: … \n Subject: … \n To: …"
+ originalBody: string; // the original message's text/markdown body
+ attachments?: AttachmentData[];
+}): string {
+ const {
+ to,
+ cc,
+ bcc = [],
+ from,
+ subject,
+ body,
+ originalHeader,
+ originalBody,
+ attachments,
+ } = options;
+
+ // Sanitize every value interpolated into a header to prevent CRLF header
+ // injection (RFC 5322) via attacker-controlled subjects or addresses.
+ const fromHeader = sanitizeHeaderValue(from);
+ const toHeader = to.map(sanitizeHeaderValue).join(", ");
+ const ccHeader = cc.map(sanitizeHeaderValue).join(", ");
+ const bccHeader = bcc.map(sanitizeHeaderValue).join(", ");
+
+ // Ensure subject has a "Fwd:" prefix, without doubling an existing one.
+ const fwdSubject = sanitizeHeaderValue(
+ subject.startsWith("Fwd:") ? subject : `Fwd: ${subject}`
+ );
+
+ // A forward starts a new thread, so — unlike buildReplyMessage — there is
+ // no In-Reply-To / References header here.
+ const headerLines: string[] = [`From: ${fromHeader}`, `To: ${toHeader}`];
+ if (cc.length > 0) headerLines.push(`Cc: ${ccHeader}`);
+ if (bcc.length > 0) headerLines.push(`Bcc: ${bccHeader}`);
+ headerLines.push(`Subject: ${fwdSubject}`);
+ headerLines.push(`MIME-Version: 1.0`);
+
+ // Compose the visible body: the forwarder's own message (if any) on top of
+ // a standard quoted-original attribution block.
+ const quotedOriginal = [
+ "---------- Forwarded message ----------",
+ originalHeader,
+ "",
+ originalBody,
+ ].join("\n");
+ const composed = body.length > 0 ? `${body}\n\n${quotedOriginal}` : quotedOriginal;
+
+ // The body is always a multipart/alternative (plain text + rendered HTML) so
+ // recipients get clean formatting and MTAs don't hard-wrap raw Markdown.
+ const altBoundary = mimeBoundary("alt");
+ const altBlock = buildAlternativeBlock(altBoundary, composed);
+
+ let rawMessage: string;
+
+ if (attachments && attachments.length > 0) {
+ // Wrap the alternative body and the re-attached attachments in a
+ // multipart/mixed.
+ const mixBoundary = mimeBoundary("mix");
+
+ const attachmentParts: string[] = [];
+ for (const att of attachments) {
+ const b64Lines = uint8ArrayToBase64Lines(att.data);
+ // Encode filename for Content-Disposition
+ const safeFileName = att.fileName.replace(/[\r\n"]/g, "_");
+ attachmentParts.push(
+ `--${mixBoundary}`,
+ `Content-Type: ${att.mimeType}; name="${safeFileName}"`,
+ `Content-Transfer-Encoding: base64`,
+ `Content-Disposition: attachment; filename="${safeFileName}"`,
+ "",
+ b64Lines,
+ );
+ }
+
+ rawMessage = [
+ ...headerLines,
+ `Content-Type: multipart/mixed; boundary="${mixBoundary}"`,
+ "", // end of message headers
+ `--${mixBoundary}`,
+ ...altBlock,
+ ...attachmentParts,
+ `--${mixBoundary}--`,
+ ].join("\r\n");
+ } else {
+ // Top-level body is the multipart/alternative entity itself.
+ rawMessage = [...headerLines, ...altBlock].join("\r\n");
+ }
+
+ return base64UrlEncodeMessage(rawMessage);
+}

.changeset/forward-a-note.md

@@ -0,0 +1,5 @@
+---
+"@plotday/twister": minor
+---
+
+Added: `LinkTypeConfig.supportsForward` and `CreateLinkDraft.forward` so connectors can perform native forwards of existing items (e.g. email forwards carrying the original message and attachments) when a user forwards a note.

connectors/gmail/src/channels.ts

@@ -44,6 +44,10 @@ export const GMAIL_LINK_TYPES: LinkTypeConfig[] = [
  compose: {
  targets: "addresses" as const,
  },
+ // onCreateLink reconstructs a real Gmail forward (original message +
+ // attachments) when `CreateLinkDraft.forward` is set, so the runtime
+ // should route native forwards here instead of the blockquote fallback.
+ supportsForward: true,
  },
 ];
 

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

@@ -1,6 +1,7 @@
 import { afterEach, describe, expect, it, vi } from "vitest";
 import {
  GmailApi,
+ buildForwardMessage,
  buildNewEmailMessage,
  buildReplyMessage,
  stripQuotedReply,
@@ -319,3 +320,78 @@ describe("outbound MIME bodies (multipart/alternative HTML + plain)", () => {
  expect(decodeMimePart(raw, "text/plain")).not.toContain("**");
  });
 });
+
+describe("buildForwardMessage", () => {
+ it("uses a Fwd: subject and includes the quoted original + forwarder message", () => {
+ const raw = decodeRawMessage(
+ buildForwardMessage({
+ to: ["bob@example.com"],
+ cc: [],
+ from: "me@example.com",
+ subject: "Q3 budget",
+ body: "See below.",
+ originalHeader: "From: Alice <alice@example.com>\nSubject: Q3 budget",
+ originalBody: "Let's meet Thursday.",
+ })
+ );
+ expect(raw).toContain("Subject: Fwd: Q3 budget");
+ expect(raw).not.toContain("In-Reply-To:");
+
+ // Body content lives base64-encoded inside the multipart/alternative
+ // plain-text part, so decode that part rather than scanning the raw
+ // (still-encoded) message for the literal text.
+ const text = decodeMimePart(raw, "text/plain");
+ expect(text).toContain("See below.");
+ expect(text).toContain("Let's meet Thursday.");
+ });
+
+ it("keeps an existing Fwd: prefix instead of doubling it", () => {
+ const raw = decodeRawMessage(
+ buildForwardMessage({
+ to: ["b@x.com"],
+ cc: [],
+ from: "m@x.com",
+ subject: "Fwd: hi",
+ body: "",
+ originalHeader: "From: a@x.com",
+ originalBody: "hi",
+ })
+ );
+ expect(raw).toContain("Subject: Fwd: hi");
+ expect(raw).not.toContain("Fwd: Fwd:");
+ });
+
+ it("emits a Bcc header without exposing bcc addresses in To/Cc", () => {
+ const raw = decodeRawMessage(
+ buildForwardMessage({
+ to: ["bob@example.com"],
+ cc: ["carol@example.com"],
+ bcc: ["dave@example.com"],
+ from: "me@example.com",
+ subject: "Q3 budget",
+ body: "",
+ originalHeader: "From: Alice <alice@example.com>",
+ originalBody: "hi",
+ })
+ );
+ expect(raw).toContain("Bcc: dave@example.com");
+ expect(raw).toContain("To: bob@example.com");
+ expect(raw).not.toContain("To: bob@example.com, dave@example.com");
+ expect(raw).not.toContain("Cc: carol@example.com, dave@example.com");
+ });
+
+ it("omits the Bcc header entirely when there are no bcc recipients", () => {
+ const raw = decodeRawMessage(
+ buildForwardMessage({
+ to: ["bob@example.com"],
+ cc: [],
+ from: "me@example.com",
+ subject: "Q3 budget",
+ body: "",
+ originalHeader: "From: Alice <alice@example.com>",
+ originalBody: "hi",
+ })
+ );
+ expect(raw).not.toContain("Bcc:");
+ });
+});

connectors/gmail/src/gmail-api.ts

@@ -283,6 +283,21 @@ export class GmailApi {
  return data as GmailThread;
  }
 
+ /**
+ * Fetches a single message by id. Used to source a native forward (see
+ * `buildForwardMessage`), where the caller has a message id — the note
+ * `key` a Gmail-backed note carries — rather than a thread id.
+ */
+ public async getMessage(
+ messageId: string,
+ format: "full" | "minimal" | "metadata" | "raw" = "full"
+ ): Promise<GmailMessage> {
+ const data = await this.call(`/messages/${messageId}`, {
+ params: { format },
+ });
+ return data as GmailMessage;
+ }
+
  public async setupWatch(
  topicName: string,
  labelId?: string
@@ -584,7 +599,7 @@ export function isFromAddressRewritten(
  * Extracts the body from a Gmail message (handles multipart messages).
  * Returns raw content with its type so HTML can be converted server-side.
  */
-function extractBody(part: GmailMessagePart): { content: string; contentType: "text" | "html" } {
+export function extractBody(part: GmailMessagePart): { content: string; contentType: "text" | "html" } {
  // Prefer HTML over plain text — server-side conversion produces cleaner output.
  // Search the WHOLE MIME tree, not just immediate children: forwarded messages
  // nest the real body inside a `message/rfc822` part (or a deeper multipart),
@@ -1457,3 +1472,116 @@ export function buildReplyMessage(options: {
 
  return base64UrlEncodeMessage(rawMessage);
 }
+
+/**
+ * Builds an RFC 2822 forward of an existing Gmail message. Gmail has no
+ * native "forward" endpoint — a forward is just a new message sent via
+ * `messages.send`. Unlike a reply, a forward starts a NEW thread (no
+ * `In-Reply-To` / `References`). The body is the forwarder's own message
+ * followed by a standard quoted-original attribution block; the original
+ * message's attachments are re-attached.
+ * Returns the base64url-encoded raw message string for the Gmail API.
+ */
+export function buildForwardMessage(options: {
+ to: string[];
+ cc: string[];
+ /**
+ * Optional — a forward's recipients come from the same role-tagged picker
+ * as a compose, so a bcc-role recipient can appear here. Defaults to none.
+ * Gmail's send API delivers to Bcc recipients and strips the Bcc header
+ * from the copy other recipients receive (same as `buildNewEmailMessage`),
+ * so listing them here does not expose them.
+ */
+ bcc?: string[];
+ from: string;
+ subject: string;
+ body: string;
+ originalHeader: string; // e.g. "From: … \n Date: … \n Subject: … \n To: …"
+ originalBody: string; // the original message's text/markdown body
+ attachments?: AttachmentData[];
+}): string {
+ const {
+ to,
+ cc,
+ bcc = [],
+ from,
+ subject,
+ body,
+ originalHeader,
+ originalBody,
+ attachments,
+ } = options;
+
+ // Sanitize every value interpolated into a header to prevent CRLF header
+ // injection (RFC 5322) via attacker-controlled subjects or addresses.
+ const fromHeader = sanitizeHeaderValue(from);
+ const toHeader = to.map(sanitizeHeaderValue).join(", ");
+ const ccHeader = cc.map(sanitizeHeaderValue).join(", ");
+ const bccHeader = bcc.map(sanitizeHeaderValue).join(", ");
+
+ // Ensure subject has a "Fwd:" prefix, without doubling an existing one.
+ const fwdSubject = sanitizeHeaderValue(
+ subject.startsWith("Fwd:") ? subject : `Fwd: ${subject}`
+ );
+
+ // A forward starts a new thread, so — unlike buildReplyMessage — there is
+ // no In-Reply-To / References header here.
+ const headerLines: string[] = [`From: ${fromHeader}`, `To: ${toHeader}`];
+ if (cc.length > 0) headerLines.push(`Cc: ${ccHeader}`);
+ if (bcc.length > 0) headerLines.push(`Bcc: ${bccHeader}`);
+ headerLines.push(`Subject: ${fwdSubject}`);
+ headerLines.push(`MIME-Version: 1.0`);
+
+ // Compose the visible body: the forwarder's own message (if any) on top of
+ // a standard quoted-original attribution block.
+ const quotedOriginal = [
+ "---------- Forwarded message ----------",
+ originalHeader,
+ "",
+ originalBody,
+ ].join("\n");
+ const composed = body.length > 0 ? `${body}\n\n${quotedOriginal}` : quotedOriginal;
+
+ // The body is always a multipart/alternative (plain text + rendered HTML) so
+ // recipients get clean formatting and MTAs don't hard-wrap raw Markdown.
+ const altBoundary = mimeBoundary("alt");
+ const altBlock = buildAlternativeBlock(altBoundary, composed);
+
+ let rawMessage: string;
+
+ if (attachments && attachments.length > 0) {
+ // Wrap the alternative body and the re-attached attachments in a
+ // multipart/mixed.
+ const mixBoundary = mimeBoundary("mix");
+
+ const attachmentParts: string[] = [];
+ for (const att of attachments) {
+ const b64Lines = uint8ArrayToBase64Lines(att.data);
+ // Encode filename for Content-Disposition
+ const safeFileName = att.fileName.replace(/[\r\n"]/g, "_");
+ attachmentParts.push(
+ `--${mixBoundary}`,
+ `Content-Type: ${att.mimeType}; name="${safeFileName}"`,
+ `Content-Transfer-Encoding: base64`,
+ `Content-Disposition: attachment; filename="${safeFileName}"`,
+ "",
+ b64Lines,
+ );
+ }
+
+ rawMessage = [
+ ...headerLines,
+ `Content-Type: multipart/mixed; boundary="${mixBoundary}"`,
+ "", // end of message headers
+ `--${mixBoundary}`,
+ ...altBlock,
+ ...attachmentParts,
+ `--${mixBoundary}--`,
+ ].join("\r\n");
+ } else {
+ // Top-level body is the multipart/alternative entity itself.
+ rawMessage = [...headerLines, ...altBlock].join("\r\n");
+ }
+
+ return base64UrlEncodeMessage(rawMessage);
+}

.changeset/forward-a-note.md

@@ -0,0 +1,5 @@
+---
+"@plotday/twister": minor
+---
+
+Added: `LinkTypeConfig.supportsForward` and `CreateLinkDraft.forward` so connectors can perform native forwards of existing items (e.g. email forwards carrying the original message and attachments) when a user forwards a note.

connectors/gmail/src/channels.ts

@@ -44,6 +44,10 @@ export const GMAIL_LINK_TYPES: LinkTypeConfig[] = [
  compose: {
  targets: "addresses" as const,
  },
+ // onCreateLink reconstructs a real Gmail forward (original message +
+ // attachments) when `CreateLinkDraft.forward` is set, so the runtime
+ // should route native forwards here instead of the blockquote fallback.
+ supportsForward: true,
  },
 ];
 

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

@@ -1,6 +1,7 @@
 import { afterEach, describe, expect, it, vi } from "vitest";
 import {
  GmailApi,
+ buildForwardMessage,
  buildNewEmailMessage,
  buildReplyMessage,
  stripQuotedReply,
@@ -319,3 +320,78 @@ describe("outbound MIME bodies (multipart/alternative HTML + plain)", () => {
  expect(decodeMimePart(raw, "text/plain")).not.toContain("**");
  });
 });
+
+describe("buildForwardMessage", () => {
+ it("uses a Fwd: subject and includes the quoted original + forwarder message", () => {
+ const raw = decodeRawMessage(
+ buildForwardMessage({
+ to: ["bob@example.com"],
+ cc: [],
+ from: "me@example.com",
+ subject: "Q3 budget",
+ body: "See below.",
+ originalHeader: "From: Alice <alice@example.com>\nSubject: Q3 budget",
+ originalBody: "Let's meet Thursday.",
+ })
+ );
+ expect(raw).toContain("Subject: Fwd: Q3 budget");
+ expect(raw).not.toContain("In-Reply-To:");
+
+ // Body content lives base64-encoded inside the multipart/alternative
+ // plain-text part, so decode that part rather than scanning the raw
+ // (still-encoded) message for the literal text.
+ const text = decodeMimePart(raw, "text/plain");
+ expect(text).toContain("See below.");
+ expect(text).toContain("Let's meet Thursday.");
+ });
+
+ it("keeps an existing Fwd: prefix instead of doubling it", () => {
+ const raw = decodeRawMessage(
+ buildForwardMessage({
+ to: ["b@x.com"],
+ cc: [],
+ from: "m@x.com",
+ subject: "Fwd: hi",
+ body: "",
+ originalHeader: "From: a@x.com",
+ originalBody: "hi",
+ })
+ );
+ expect(raw).toContain("Subject: Fwd: hi");
+ expect(raw).not.toContain("Fwd: Fwd:");
+ });
+
+ it("emits a Bcc header without exposing bcc addresses in To/Cc", () => {
+ const raw = decodeRawMessage(
+ buildForwardMessage({
+ to: ["bob@example.com"],
+ cc: ["carol@example.com"],
+ bcc: ["dave@example.com"],
+ from: "me@example.com",
+ subject: "Q3 budget",
+ body: "",
+ originalHeader: "From: Alice <alice@example.com>",
+ originalBody: "hi",
+ })
+ );
+ expect(raw).toContain("Bcc: dave@example.com");
+ expect(raw).toContain("To: bob@example.com");
+ expect(raw).not.toContain("To: bob@example.com, dave@example.com");
+ expect(raw).not.toContain("Cc: carol@example.com, dave@example.com");
+ });
+
+ it("omits the Bcc header entirely when there are no bcc recipients", () => {
+ const raw = decodeRawMessage(
+ buildForwardMessage({
+ to: ["bob@example.com"],
+ cc: [],
+ from: "me@example.com",
+ subject: "Q3 budget",
+ body: "",
+ originalHeader: "From: Alice <alice@example.com>",
+ originalBody: "hi",
+ })
+ );
+ expect(raw).not.toContain("Bcc:");
+ });
+});

connectors/gmail/src/gmail-api.ts

@@ -283,6 +283,21 @@ export class GmailApi {
  return data as GmailThread;
  }
 
+ /**
+ * Fetches a single message by id. Used to source a native forward (see
+ * `buildForwardMessage`), where the caller has a message id — the note
+ * `key` a Gmail-backed note carries — rather than a thread id.
+ */
+ public async getMessage(
+ messageId: string,
+ format: "full" | "minimal" | "metadata" | "raw" = "full"
+ ): Promise<GmailMessage> {
+ const data = await this.call(`/messages/${messageId}`, {
+ params: { format },
+ });
+ return data as GmailMessage;
+ }
+
  public async setupWatch(
  topicName: string,
  labelId?: string
@@ -584,7 +599,7 @@ export function isFromAddressRewritten(
  * Extracts the body from a Gmail message (handles multipart messages).
  * Returns raw content with its type so HTML can be converted server-side.
  */
-function extractBody(part: GmailMessagePart): { content: string; contentType: "text" | "html" } {
+export function extractBody(part: GmailMessagePart): { content: string; contentType: "text" | "html" } {
  // Prefer HTML over plain text — server-side conversion produces cleaner output.
  // Search the WHOLE MIME tree, not just immediate children: forwarded messages
  // nest the real body inside a `message/rfc822` part (or a deeper multipart),
@@ -1457,3 +1472,116 @@ export function buildReplyMessage(options: {
 
  return base64UrlEncodeMessage(rawMessage);
 }
+
+/**
+ * Builds an RFC 2822 forward of an existing Gmail message. Gmail has no
+ * native "forward" endpoint — a forward is just a new message sent via
+ * `messages.send`. Unlike a reply, a forward starts a NEW thread (no
+ * `In-Reply-To` / `References`). The body is the forwarder's own message
+ * followed by a standard quoted-original attribution block; the original
+ * message's attachments are re-attached.
+ * Returns the base64url-encoded raw message string for the Gmail API.
+ */
+export function buildForwardMessage(options: {
+ to: string[];
+ cc: string[];
+ /**
+ * Optional — a forward's recipients come from the same role-tagged picker
+ * as a compose, so a bcc-role recipient can appear here. Defaults to none.
+ * Gmail's send API delivers to Bcc recipients and strips the Bcc header
+ * from the copy other recipients receive (same as `buildNewEmailMessage`),
+ * so listing them here does not expose them.
+ */
+ bcc?: string[];
+ from: string;
+ subject: string;
+ body: string;
+ originalHeader: string; // e.g. "From: … \n Date: … \n Subject: … \n To: …"
+ originalBody: string; // the original message's text/markdown body
+ attachments?: AttachmentData[];
+}): string {
+ const {
+ to,
+ cc,
+ bcc = [],
+ from,
+ subject,
+ body,
+ originalHeader,
+ originalBody,
+ attachments,
+ } = options;
+
+ // Sanitize every value interpolated into a header to prevent CRLF header
+ // injection (RFC 5322) via attacker-controlled subjects or addresses.
+ const fromHeader = sanitizeHeaderValue(from);
+ const toHeader = to.map(sanitizeHeaderValue).join(", ");
+ const ccHeader = cc.map(sanitizeHeaderValue).join(", ");
+ const bccHeader = bcc.map(sanitizeHeaderValue).join(", ");
+
+ // Ensure subject has a "Fwd:" prefix, without doubling an existing one.
+ const fwdSubject = sanitizeHeaderValue(
+ subject.startsWith("Fwd:") ? subject : `Fwd: ${subject}`
+ );
+
+ // A forward starts a new thread, so — unlike buildReplyMessage — there is
+ // no In-Reply-To / References header here.
+ const headerLines: string[] = [`From: ${fromHeader}`, `To: ${toHeader}`];
+ if (cc.length > 0) headerLines.push(`Cc: ${ccHeader}`);
+ if (bcc.length > 0) headerLines.push(`Bcc: ${bccHeader}`);
+ headerLines.push(`Subject: ${fwdSubject}`);
+ headerLines.push(`MIME-Version: 1.0`);
+
+ // Compose the visible body: the forwarder's own message (if any) on top of
+ // a standard quoted-original attribution block.
+ const quotedOriginal = [
+ "---------- Forwarded message ----------",
+ originalHeader,
+ "",
+ originalBody,
+ ].join("\n");
+ const composed = body.length > 0 ? `${body}\n\n${quotedOriginal}` : quotedOriginal;
+
+ // The body is always a multipart/alternative (plain text + rendered HTML) so
+ // recipients get clean formatting and MTAs don't hard-wrap raw Markdown.
+ const altBoundary = mimeBoundary("alt");
+ const altBlock = buildAlternativeBlock(altBoundary, composed);
+
+ let rawMessage: string;
+
+ if (attachments && attachments.length > 0) {
+ // Wrap the alternative body and the re-attached attachments in a
+ // multipart/mixed.
+ const mixBoundary = mimeBoundary("mix");
+
+ const attachmentParts: string[] = [];
+ for (const att of attachments) {
+ const b64Lines = uint8ArrayToBase64Lines(att.data);
+ // Encode filename for Content-Disposition
+ const safeFileName = att.fileName.replace(/[\r\n"]/g, "_");
+ attachmentParts.push(
+ `--${mixBoundary}`,
+ `Content-Type: ${att.mimeType}; name="${safeFileName}"`,
+ `Content-Transfer-Encoding: base64`,
+ `Content-Disposition: attachment; filename="${safeFileName}"`,
+ "",
+ b64Lines,
+ );
+ }
+
+ rawMessage = [
+ ...headerLines,
+ `Content-Type: multipart/mixed; boundary="${mixBoundary}"`,
+ "", // end of message headers
+ `--${mixBoundary}`,
+ ...altBlock,
+ ...attachmentParts,
+ `--${mixBoundary}--`,
+ ].join("\r\n");
+ } else {
+ // Top-level body is the multipart/alternative entity itself.
+ rawMessage = [...headerLines, ...altBlock].join("\r\n");
+ }
+
+ return base64UrlEncodeMessage(rawMessage);
+}

.changeset/forward-a-note.md

@@ -0,0 +1,5 @@
+---
+"@plotday/twister": minor
+---
+
+Added: `LinkTypeConfig.supportsForward` and `CreateLinkDraft.forward` so connectors can perform native forwards of existing items (e.g. email forwards carrying the original message and attachments) when a user forwards a note.

connectors/gmail/src/channels.ts

@@ -44,6 +44,10 @@ export const GMAIL_LINK_TYPES: LinkTypeConfig[] = [
  compose: {
  targets: "addresses" as const,
  },
+ // onCreateLink reconstructs a real Gmail forward (original message +
+ // attachments) when `CreateLinkDraft.forward` is set, so the runtime
+ // should route native forwards here instead of the blockquote fallback.
+ supportsForward: true,
  },
 ];
 

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

@@ -1,6 +1,7 @@
 import { afterEach, describe, expect, it, vi } from "vitest";
 import {
  GmailApi,
+ buildForwardMessage,
  buildNewEmailMessage,
  buildReplyMessage,
  stripQuotedReply,
@@ -319,3 +320,78 @@ describe("outbound MIME bodies (multipart/alternative HTML + plain)", () => {
  expect(decodeMimePart(raw, "text/plain")).not.toContain("**");
  });
 });
+
+describe("buildForwardMessage", () => {
+ it("uses a Fwd: subject and includes the quoted original + forwarder message", () => {
+ const raw = decodeRawMessage(
+ buildForwardMessage({
+ to: ["bob@example.com"],
+ cc: [],
+ from: "me@example.com",
+ subject: "Q3 budget",
+ body: "See below.",
+ originalHeader: "From: Alice <alice@example.com>\nSubject: Q3 budget",
+ originalBody: "Let's meet Thursday.",
+ })
+ );
+ expect(raw).toContain("Subject: Fwd: Q3 budget");
+ expect(raw).not.toContain("In-Reply-To:");
+
+ // Body content lives base64-encoded inside the multipart/alternative
+ // plain-text part, so decode that part rather than scanning the raw
+ // (still-encoded) message for the literal text.
+ const text = decodeMimePart(raw, "text/plain");
+ expect(text).toContain("See below.");
+ expect(text).toContain("Let's meet Thursday.");
+ });
+
+ it("keeps an existing Fwd: prefix instead of doubling it", () => {
+ const raw = decodeRawMessage(
+ buildForwardMessage({
+ to: ["b@x.com"],
+ cc: [],
+ from: "m@x.com",
+ subject: "Fwd: hi",
+ body: "",
+ originalHeader: "From: a@x.com",
+ originalBody: "hi",
+ })
+ );
+ expect(raw).toContain("Subject: Fwd: hi");
+ expect(raw).not.toContain("Fwd: Fwd:");
+ });
+
+ it("emits a Bcc header without exposing bcc addresses in To/Cc", () => {
+ const raw = decodeRawMessage(
+ buildForwardMessage({
+ to: ["bob@example.com"],
+ cc: ["carol@example.com"],
+ bcc: ["dave@example.com"],
+ from: "me@example.com",
+ subject: "Q3 budget",
+ body: "",
+ originalHeader: "From: Alice <alice@example.com>",
+ originalBody: "hi",
+ })
+ );
+ expect(raw).toContain("Bcc: dave@example.com");
+ expect(raw).toContain("To: bob@example.com");
+ expect(raw).not.toContain("To: bob@example.com, dave@example.com");
+ expect(raw).not.toContain("Cc: carol@example.com, dave@example.com");
+ });
+
+ it("omits the Bcc header entirely when there are no bcc recipients", () => {
+ const raw = decodeRawMessage(
+ buildForwardMessage({
+ to: ["bob@example.com"],
+ cc: [],
+ from: "me@example.com",
+ subject: "Q3 budget",
+ body: "",
+ originalHeader: "From: Alice <alice@example.com>",
+ originalBody: "hi",
+ })
+ );
+ expect(raw).not.toContain("Bcc:");
+ });
+});

connectors/gmail/src/gmail-api.ts

@@ -283,6 +283,21 @@ export class GmailApi {
  return data as GmailThread;
  }
 
+ /**
+ * Fetches a single message by id. Used to source a native forward (see
+ * `buildForwardMessage`), where the caller has a message id — the note
+ * `key` a Gmail-backed note carries — rather than a thread id.
+ */
+ public async getMessage(
+ messageId: string,
+ format: "full" | "minimal" | "metadata" | "raw" = "full"
+ ): Promise<GmailMessage> {
+ const data = await this.call(`/messages/${messageId}`, {
+ params: { format },
+ });
+ return data as GmailMessage;
+ }
+
  public async setupWatch(
  topicName: string,
  labelId?: string
@@ -584,7 +599,7 @@ export function isFromAddressRewritten(
  * Extracts the body from a Gmail message (handles multipart messages).
  * Returns raw content with its type so HTML can be converted server-side.
  */
-function extractBody(part: GmailMessagePart): { content: string; contentType: "text" | "html" } {
+export function extractBody(part: GmailMessagePart): { content: string; contentType: "text" | "html" } {
  // Prefer HTML over plain text — server-side conversion produces cleaner output.
  // Search the WHOLE MIME tree, not just immediate children: forwarded messages
  // nest the real body inside a `message/rfc822` part (or a deeper multipart),
@@ -1457,3 +1472,116 @@ export function buildReplyMessage(options: {
 
  return base64UrlEncodeMessage(rawMessage);
 }
+
+/**
+ * Builds an RFC 2822 forward of an existing Gmail message. Gmail has no
+ * native "forward" endpoint — a forward is just a new message sent via
+ * `messages.send`. Unlike a reply, a forward starts a NEW thread (no
+ * `In-Reply-To` / `References`). The body is the forwarder's own message
+ * followed by a standard quoted-original attribution block; the original
+ * message's attachments are re-attached.
+ * Returns the base64url-encoded raw message string for the Gmail API.
+ */
+export function buildForwardMessage(options: {
+ to: string[];
+ cc: string[];
+ /**
+ * Optional — a forward's recipients come from the same role-tagged picker
+ * as a compose, so a bcc-role recipient can appear here. Defaults to none.
+ * Gmail's send API delivers to Bcc recipients and strips the Bcc header
+ * from the copy other recipients receive (same as `buildNewEmailMessage`),
+ * so listing them here does not expose them.
+ */
+ bcc?: string[];
+ from: string;
+ subject: string;
+ body: string;
+ originalHeader: string; // e.g. "From: … \n Date: … \n Subject: … \n To: …"
+ originalBody: string; // the original message's text/markdown body
+ attachments?: AttachmentData[];
+}): string {
+ const {
+ to,
+ cc,
+ bcc = [],
+ from,
+ subject,
+ body,
+ originalHeader,
+ originalBody,
+ attachments,
+ } = options;
+
+ // Sanitize every value interpolated into a header to prevent CRLF header
+ // injection (RFC 5322) via attacker-controlled subjects or addresses.
+ const fromHeader = sanitizeHeaderValue(from);
+ const toHeader = to.map(sanitizeHeaderValue).join(", ");
+ const ccHeader = cc.map(sanitizeHeaderValue).join(", ");
+ const bccHeader = bcc.map(sanitizeHeaderValue).join(", ");
+
+ // Ensure subject has a "Fwd:" prefix, without doubling an existing one.
+ const fwdSubject = sanitizeHeaderValue(
+ subject.startsWith("Fwd:") ? subject : `Fwd: ${subject}`
+ );
+
+ // A forward starts a new thread, so — unlike buildReplyMessage — there is
+ // no In-Reply-To / References header here.
+ const headerLines: string[] = [`From: ${fromHeader}`, `To: ${toHeader}`];
+ if (cc.length > 0) headerLines.push(`Cc: ${ccHeader}`);
+ if (bcc.length > 0) headerLines.push(`Bcc: ${bccHeader}`);
+ headerLines.push(`Subject: ${fwdSubject}`);
+ headerLines.push(`MIME-Version: 1.0`);
+
+ // Compose the visible body: the forwarder's own message (if any) on top of
+ // a standard quoted-original attribution block.
+ const quotedOriginal = [
+ "---------- Forwarded message ----------",
+ originalHeader,
+ "",
+ originalBody,
+ ].join("\n");
+ const composed = body.length > 0 ? `${body}\n\n${quotedOriginal}` : quotedOriginal;
+
+ // The body is always a multipart/alternative (plain text + rendered HTML) so
+ // recipients get clean formatting and MTAs don't hard-wrap raw Markdown.
+ const altBoundary = mimeBoundary("alt");
+ const altBlock = buildAlternativeBlock(altBoundary, composed);
+
+ let rawMessage: string;
+
+ if (attachments && attachments.length > 0) {
+ // Wrap the alternative body and the re-attached attachments in a
+ // multipart/mixed.
+ const mixBoundary = mimeBoundary("mix");
+
+ const attachmentParts: string[] = [];
+ for (const att of attachments) {
+ const b64Lines = uint8ArrayToBase64Lines(att.data);
+ // Encode filename for Content-Disposition
+ const safeFileName = att.fileName.replace(/[\r\n"]/g, "_");
+ attachmentParts.push(
+ `--${mixBoundary}`,
+ `Content-Type: ${att.mimeType}; name="${safeFileName}"`,
+ `Content-Transfer-Encoding: base64`,
+ `Content-Disposition: attachment; filename="${safeFileName}"`,
+ "",
+ b64Lines,
+ );
+ }
+
+ rawMessage = [
+ ...headerLines,
+ `Content-Type: multipart/mixed; boundary="${mixBoundary}"`,
+ "", // end of message headers
+ `--${mixBoundary}`,
+ ...altBlock,
+ ...attachmentParts,
+ `--${mixBoundary}--`,
+ ].join("\r\n");
+ } else {
+ // Top-level body is the multipart/alternative entity itself.
+ rawMessage = [...headerLines, ...altBlock].join("\r\n");
+ }
+
+ return base64UrlEncodeMessage(rawMessage);
+}

.changeset/forward-a-note.md

@@ -0,0 +1,5 @@
+---
+"@plotday/twister": minor
+---
+
+Added: `LinkTypeConfig.supportsForward` and `CreateLinkDraft.forward` so connectors can perform native forwards of existing items (e.g. email forwards carrying the original message and attachments) when a user forwards a note.

connectors/gmail/src/channels.ts

@@ -44,6 +44,10 @@ export const GMAIL_LINK_TYPES: LinkTypeConfig[] = [
  compose: {
  targets: "addresses" as const,
  },
+ // onCreateLink reconstructs a real Gmail forward (original message +
+ // attachments) when `CreateLinkDraft.forward` is set, so the runtime
+ // should route native forwards here instead of the blockquote fallback.
+ supportsForward: true,
  },
 ];
 

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

@@ -1,6 +1,7 @@
 import { afterEach, describe, expect, it, vi } from "vitest";
 import {
  GmailApi,
+ buildForwardMessage,
  buildNewEmailMessage,
  buildReplyMessage,
  stripQuotedReply,
@@ -319,3 +320,78 @@ describe("outbound MIME bodies (multipart/alternative HTML + plain)", () => {
  expect(decodeMimePart(raw, "text/plain")).not.toContain("**");
  });
 });
+
+describe("buildForwardMessage", () => {
+ it("uses a Fwd: subject and includes the quoted original + forwarder message", () => {
+ const raw = decodeRawMessage(
+ buildForwardMessage({
+ to: ["bob@example.com"],
+ cc: [],
+ from: "me@example.com",
+ subject: "Q3 budget",
+ body: "See below.",
+ originalHeader: "From: Alice <alice@example.com>\nSubject: Q3 budget",
+ originalBody: "Let's meet Thursday.",
+ })
+ );
+ expect(raw).toContain("Subject: Fwd: Q3 budget");
+ expect(raw).not.toContain("In-Reply-To:");
+
+ // Body content lives base64-encoded inside the multipart/alternative
+ // plain-text part, so decode that part rather than scanning the raw
+ // (still-encoded) message for the literal text.
+ const text = decodeMimePart(raw, "text/plain");
+ expect(text).toContain("See below.");
+ expect(text).toContain("Let's meet Thursday.");
+ });
+
+ it("keeps an existing Fwd: prefix instead of doubling it", () => {
+ const raw = decodeRawMessage(
+ buildForwardMessage({
+ to: ["b@x.com"],
+ cc: [],
+ from: "m@x.com",
+ subject: "Fwd: hi",
+ body: "",
+ originalHeader: "From: a@x.com",
+ originalBody: "hi",
+ })
+ );
+ expect(raw).toContain("Subject: Fwd: hi");
+ expect(raw).not.toContain("Fwd: Fwd:");
+ });
+
+ it("emits a Bcc header without exposing bcc addresses in To/Cc", () => {
+ const raw = decodeRawMessage(
+ buildForwardMessage({
+ to: ["bob@example.com"],
+ cc: ["carol@example.com"],
+ bcc: ["dave@example.com"],
+ from: "me@example.com",
+ subject: "Q3 budget",
+ body: "",
+ originalHeader: "From: Alice <alice@example.com>",
+ originalBody: "hi",
+ })
+ );
+ expect(raw).toContain("Bcc: dave@example.com");
+ expect(raw).toContain("To: bob@example.com");
+ expect(raw).not.toContain("To: bob@example.com, dave@example.com");
+ expect(raw).not.toContain("Cc: carol@example.com, dave@example.com");
+ });
+
+ it("omits the Bcc header entirely when there are no bcc recipients", () => {
+ const raw = decodeRawMessage(
+ buildForwardMessage({
+ to: ["bob@example.com"],
+ cc: [],
+ from: "me@example.com",
+ subject: "Q3 budget",
+ body: "",
+ originalHeader: "From: Alice <alice@example.com>",
+ originalBody: "hi",
+ })
+ );
+ expect(raw).not.toContain("Bcc:");
+ });
+});

connectors/gmail/src/gmail-api.ts

@@ -283,6 +283,21 @@ export class GmailApi {
  return data as GmailThread;
  }
 
+ /**
+ * Fetches a single message by id. Used to source a native forward (see
+ * `buildForwardMessage`), where the caller has a message id — the note
+ * `key` a Gmail-backed note carries — rather than a thread id.
+ */
+ public async getMessage(
+ messageId: string,
+ format: "full" | "minimal" | "metadata" | "raw" = "full"
+ ): Promise<GmailMessage> {
+ const data = await this.call(`/messages/${messageId}`, {
+ params: { format },
+ });
+ return data as GmailMessage;
+ }
+
  public async setupWatch(
  topicName: string,
  labelId?: string
@@ -584,7 +599,7 @@ export function isFromAddressRewritten(
  * Extracts the body from a Gmail message (handles multipart messages).
  * Returns raw content with its type so HTML can be converted server-side.
  */
-function extractBody(part: GmailMessagePart): { content: string; contentType: "text" | "html" } {
+export function extractBody(part: GmailMessagePart): { content: string; contentType: "text" | "html" } {
  // Prefer HTML over plain text — server-side conversion produces cleaner output.
  // Search the WHOLE MIME tree, not just immediate children: forwarded messages
  // nest the real body inside a `message/rfc822` part (or a deeper multipart),
@@ -1457,3 +1472,116 @@ export function buildReplyMessage(options: {
 
  return base64UrlEncodeMessage(rawMessage);
 }
+
+/**
+ * Builds an RFC 2822 forward of an existing Gmail message. Gmail has no
+ * native "forward" endpoint — a forward is just a new message sent via
+ * `messages.send`. Unlike a reply, a forward starts a NEW thread (no
+ * `In-Reply-To` / `References`). The body is the forwarder's own message
+ * followed by a standard quoted-original attribution block; the original
+ * message's attachments are re-attached.
+ * Returns the base64url-encoded raw message string for the Gmail API.
+ */
+export function buildForwardMessage(options: {
+ to: string[];
+ cc: string[];
+ /**
+ * Optional — a forward's recipients come from the same role-tagged picker
+ * as a compose, so a bcc-role recipient can appear here. Defaults to none.
+ * Gmail's send API delivers to Bcc recipients and strips the Bcc header
+ * from the copy other recipients receive (same as `buildNewEmailMessage`),
+ * so listing them here does not expose them.
+ */
+ bcc?: string[];
+ from: string;
+ subject: string;
+ body: string;
+ originalHeader: string; // e.g. "From: … \n Date: … \n Subject: … \n To: …"
+ originalBody: string; // the original message's text/markdown body
+ attachments?: AttachmentData[];
+}): string {
+ const {
+ to,
+ cc,
+ bcc = [],
+ from,
+ subject,
+ body,
+ originalHeader,
+ originalBody,
+ attachments,
+ } = options;
+
+ // Sanitize every value interpolated into a header to prevent CRLF header
+ // injection (RFC 5322) via attacker-controlled subjects or addresses.
+ const fromHeader = sanitizeHeaderValue(from);
+ const toHeader = to.map(sanitizeHeaderValue).join(", ");
+ const ccHeader = cc.map(sanitizeHeaderValue).join(", ");
+ const bccHeader = bcc.map(sanitizeHeaderValue).join(", ");
+
+ // Ensure subject has a "Fwd:" prefix, without doubling an existing one.
+ const fwdSubject = sanitizeHeaderValue(
+ subject.startsWith("Fwd:") ? subject : `Fwd: ${subject}`
+ );
+
+ // A forward starts a new thread, so — unlike buildReplyMessage — there is
+ // no In-Reply-To / References header here.
+ const headerLines: string[] = [`From: ${fromHeader}`, `To: ${toHeader}`];
+ if (cc.length > 0) headerLines.push(`Cc: ${ccHeader}`);
+ if (bcc.length > 0) headerLines.push(`Bcc: ${bccHeader}`);
+ headerLines.push(`Subject: ${fwdSubject}`);
+ headerLines.push(`MIME-Version: 1.0`);
+
+ // Compose the visible body: the forwarder's own message (if any) on top of
+ // a standard quoted-original attribution block.
+ const quotedOriginal = [
+ "---------- Forwarded message ----------",
+ originalHeader,
+ "",
+ originalBody,
+ ].join("\n");
+ const composed = body.length > 0 ? `${body}\n\n${quotedOriginal}` : quotedOriginal;
+
+ // The body is always a multipart/alternative (plain text + rendered HTML) so
+ // recipients get clean formatting and MTAs don't hard-wrap raw Markdown.
+ const altBoundary = mimeBoundary("alt");
+ const altBlock = buildAlternativeBlock(altBoundary, composed);
+
+ let rawMessage: string;
+
+ if (attachments && attachments.length > 0) {
+ // Wrap the alternative body and the re-attached attachments in a
+ // multipart/mixed.
+ const mixBoundary = mimeBoundary("mix");
+
+ const attachmentParts: string[] = [];
+ for (const att of attachments) {
+ const b64Lines = uint8ArrayToBase64Lines(att.data);
+ // Encode filename for Content-Disposition
+ const safeFileName = att.fileName.replace(/[\r\n"]/g, "_");
+ attachmentParts.push(
+ `--${mixBoundary}`,
+ `Content-Type: ${att.mimeType}; name="${safeFileName}"`,
+ `Content-Transfer-Encoding: base64`,
+ `Content-Disposition: attachment; filename="${safeFileName}"`,
+ "",
+ b64Lines,
+ );
+ }
+
+ rawMessage = [
+ ...headerLines,
+ `Content-Type: multipart/mixed; boundary="${mixBoundary}"`,
+ "", // end of message headers
+ `--${mixBoundary}`,
+ ...altBlock,
+ ...attachmentParts,
+ `--${mixBoundary}--`,
+ ].join("\r\n");
+ } else {
+ // Top-level body is the multipart/alternative entity itself.
+ rawMessage = [...headerLines, ...altBlock].join("\r\n");
+ }
+
+ return base64UrlEncodeMessage(rawMessage);
+}