@stage-labs/metro 0.1.0-beta.26 → 0.1.0-beta.261

package/runtime/node_modules/@metro-labs/gmail/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@metro-labs/gmail",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "exports": {
+    ".": "./src/station.ts",
+    "./train": "./src/index.ts",
+    "./login": "./src/login.ts"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "tsc --noEmit && bun test test/"
+  },
+  "dependencies": {
+    "@metro-labs/core": "workspace:*"
+  },
+  "devDependencies": {
+    "@stage-labs/config": "0.1.0-beta.3",
+    "eslint": "^10.3.0",
+    "knip": "^6.15.0",
+    "madge": "^8.0.0",
+    "typescript": "^5"
+  }
+}

package/runtime/node_modules/@metro-labs/gmail/src/accounts.ts

@@ -0,0 +1,81 @@
+import { makeAccountStore, resolveAccountId, type Die } from '@metro-labs/core/stations/account-store';
+import { threadOfLine } from '@metro-labs/core/stations/mail';
+import { TokenKeeper, type FetchLike } from '@metro-labs/core/stations/oauth';
+import { TrainError } from '@metro-labs/core/train-error';
+import { refreshTokens } from './auth.js';
+import { loadState, saveState, type AccountState } from './state.js';
+
+export interface AccountConfig {
+  id: string;
+  accountEmail: string;
+  clientId: string;
+  clientSecret: string;
+  refreshToken: string;
+  accessToken?: string;
+  expiresAt?: number;
+  includeAutomated?: boolean;
+}
+
+const filled = (v: unknown): boolean => typeof v === 'string' && v !== '';
+
+function checkAccount(a: AccountConfig, die: Die): void {
+  if (!filled(a.accountEmail) || !a.accountEmail.includes('@')) die(`account '${a.id}' has no mailbox address`);
+  if (!filled(a.clientId) || !filled(a.clientSecret)) die(`account '${a.id}' has no OAuth client`);
+  if (!filled(a.refreshToken)) die(`account '${a.id}' has no refresh token`);
+}
+
+export const { loadAccounts } = makeAccountStore<AccountConfig>({
+  prefix: 'gmail',
+  validate(raw, die) {
+    for (const a of raw) checkAccount(a, die);
+  },
+});
+
+const signedOut = (err: unknown): never => {
+  throw new TrainError('gmail_signed_out', err instanceof Error ? err.message : String(err), { retryable: false });
+};
+
+export class Account {
+  readonly email: string;
+  readonly state: AccountState;
+  private readonly keeper: TokenKeeper;
+
+  constructor(
+    readonly cfg: AccountConfig,
+    private readonly fetchImpl: FetchLike = (input, init) => fetch(input, init),
+  ) {
+    this.email = cfg.accountEmail.toLowerCase();
+    this.state = loadState(cfg.id, { refreshToken: cfg.refreshToken, accessToken: cfg.accessToken ?? '', expiresAt: cfg.expiresAt ?? 0 });
+    const client = { clientId: cfg.clientId, clientSecret: cfg.clientSecret };
+    this.keeper = new TokenKeeper(this.state, (refreshToken) => refreshTokens(client, refreshToken, this.fetchImpl).catch(signedOut), () => {
+      this.save();
+    });
+  }
+
+  get id(): string {
+    return this.cfg.id;
+  }
+
+  save(): void {
+    saveState(this.cfg.id, this.state);
+  }
+
+  token(force = false): Promise<string> {
+    return this.keeper.token(force);
+  }
+
+  fetch(input: string, init?: RequestInit): Promise<Response> {
+    return this.fetchImpl(input, init);
+  }
+}
+
+export const accounts = new Map<string, Account>();
+
+export function accountOf(args: { account?: unknown; line?: unknown }): Account {
+  const line = typeof args.line === 'string' && args.line !== '' ? args.line : undefined;
+  const account = typeof args.account === 'string' && args.account !== '' ? args.account : undefined;
+  const id = resolveAccountId(accounts, { account, line }, (l) => threadOfLine('gmail', l)?.accountId);
+  const acct = accounts.get(id);
+  if (acct === undefined) throw new Error(`unknown account '${id}'`);
+  return acct;
+}

package/runtime/node_modules/@metro-labs/gmail/src/actions.ts

@@ -0,0 +1,14 @@
+import { makeStation, respond } from '@metro-labs/core/stations/station-runtime';
+import { accounts } from './accounts.js';
+import { MAILBOX_URL } from './config.js';
+import { reply, send } from './outbound.js';
+import { read } from './query.js';
+
+function listAccounts(id: string): void {
+  const list = [...accounts.values()].map((a) => ({ id: a.id, handle: a.email, url: `${MAILBOX_URL}mail/u/${a.email}/`, email: a.email }));
+  respond(id, { result: { accounts: list } });
+}
+
+export const handleCall = makeStation({
+  handlers: { accounts: listAccounts, send, reply, read },
+});

package/runtime/node_modules/@metro-labs/gmail/src/api.ts

@@ -0,0 +1,31 @@
+import { refusalOf, type MailService } from '@metro-labs/core/stations/mail';
+import type { Account } from './accounts.js';
+import { googleMessage } from './auth.js';
+import { apiBase } from './config.js';
+
+const GMAIL: MailService = { station: 'gmail', company: 'Google', product: 'Gmail', api: 'The Gmail API', apiCode: 'api_error' };
+
+export const USER = '/gmail/v1/users/me';
+
+export class HistoryGone extends Error {}
+
+async function call(acct: Account, path: string, init: RequestInit, force: boolean): Promise<Response> {
+  const headers = new Headers(init.headers);
+  headers.set('authorization', `Bearer ${await acct.token(force)}`);
+  headers.set('accept', 'application/json');
+  return acct.fetch(`${apiBase()}${path}`, { ...init, headers });
+}
+
+export async function gmail(acct: Account, path: string, init: RequestInit = {}): Promise<Response> {
+  let res = await call(acct, path, init, false);
+  if (res.status === 401) res = await call(acct, path, init, true);
+  if (res.ok) return res;
+  const detail = await googleMessage(res);
+  throw res.status === 404 && path.startsWith(`${USER}/history`) ? new HistoryGone(detail) : refusalOf(GMAIL, res.status, detail);
+}
+
+export async function gmailJson<T>(acct: Account, path: string, init: RequestInit = {}): Promise<T> {
+  return (await (await gmail(acct, path, init)).json()) as T;
+}
+
+export const queryOf = (params: [string, string][]): string => new URLSearchParams(params).toString();

package/runtime/node_modules/@metro-labs/gmail/src/attachments.ts

@@ -0,0 +1,35 @@
+import { stat } from 'node:fs/promises';
+import { assertAttachmentSize, saveBufferToCache, type SavedAttachment } from '@metro-labs/core/stations/attachments';
+import type { OutgoingFile } from '@metro-labs/core/stations/mail';
+import { TrainError } from '@metro-labs/core/train-error';
+import type { Account } from './accounts.js';
+import { gmailJson, USER } from './api.js';
+import { unloadedBodies, type GmailMessage, type MailFile } from './message.js';
+
+export const MAX_FILES_BYTES = 25 * 1024 * 1024;
+
+const attachmentData = async (acct: Account, messageId: string, attachmentId: string): Promise<string | null> =>
+  (await gmailJson<{ data?: string }>(acct, `${USER}/messages/${encodeURIComponent(messageId)}/attachments/${encodeURIComponent(attachmentId)}`)).data ?? null;
+
+export async function withBodies(acct: Account, m: GmailMessage): Promise<GmailMessage> {
+  for (const part of unloadedBodies(m)) part.body = { ...part.body, data: (await attachmentData(acct, m.id, part.body?.attachmentId ?? '')) ?? '' };
+  return m;
+}
+
+export async function saveFile(acct: Account, messageId: string, file: MailFile, index: number): Promise<SavedAttachment> {
+  if (file.size !== undefined) assertAttachmentSize(file.size);
+  const data = file.data ?? (file.attachmentId === null ? null : await attachmentData(acct, messageId, file.attachmentId));
+  if (data === null) throw new TrainError('gmail_file_missing', `Gmail gave no content for ${file.name}`, { retryable: false });
+  return saveBufferToCache(new Uint8Array(Buffer.from(data, 'base64url')), messageId, index, { mime: file.mime, name: file.name });
+}
+
+export async function assertSendable(files: OutgoingFile[]): Promise<void> {
+  let total = 0;
+  for (const file of files) total += (await stat(file.path)).size;
+  if (total > MAX_FILES_BYTES)
+    throw new TrainError(
+      'gmail_files_too_big',
+      `Gmail takes up to 25 MB of files in one email; these are ${(total / 1024 / 1024).toFixed(1)} MB, so share a link instead`,
+      { retryable: false },
+    );
+}

package/runtime/node_modules/@metro-labs/gmail/src/auth.ts

@@ -0,0 +1,105 @@
+import { postForm, SignInError, tokensOf, type FetchLike, type OAuthBody, type Tokens } from '@metro-labs/core/stations/oauth';
+import { apiBase, authorizeBase, redirectUri, SCOPES, tokenUrl } from './config.js';
+
+export interface GmailClient {
+  clientId: string;
+  clientSecret: string;
+}
+
+const CLIENT_ID_RE = /^[\w.-]+\.apps\.googleusercontent\.com$/;
+
+const text = (v: unknown): string => (typeof v === 'string' ? v.trim() : '');
+
+export function clientOf(rawId: unknown, rawSecret: unknown): GmailClient {
+  const clientId = text(rawId);
+  const clientSecret = text(rawSecret);
+  if (!CLIENT_ID_RE.test(clientId))
+    throw new SignInError('Paste the client ID of your Google OAuth client. It ends with .apps.googleusercontent.com.');
+  if (clientSecret === '' || /\s/.test(clientSecret)) throw new SignInError('Paste the client secret of your Google OAuth client.');
+  return { clientId, clientSecret };
+}
+
+export function failureOf(body: OAuthBody): string {
+  const error = text(body.error);
+  if (error === 'access_denied') return 'The sign-in was declined, so nothing was connected.';
+  if (error === 'invalid_client' || error === 'unauthorized_client')
+    return 'Google does not accept this client ID and secret. Check both on the Clients page of your Google Cloud project.';
+  if (error === 'redirect_uri_mismatch') return `Your Google OAuth client must list ${redirectUri()} as an authorized redirect URI.`;
+  if (error === 'admin_policy_enforced') return 'Your Google Workspace administrator blocks this app. Trust it in the Admin console under API controls, then start again.';
+  const detail = text(body.error_description);
+  return detail === '' ? `Google refused the sign-in (${error === '' ? 'no reason given' : error}).` : `Google refused the sign-in: ${detail}`;
+}
+
+export function authorizeUrl(client: GmailClient, challenge: string, state: string, loginHint: string | null): string {
+  const query = new URLSearchParams({
+    ...(loginHint === null ? {} : { login_hint: loginHint }),
+    client_id: client.clientId,
+    redirect_uri: redirectUri(),
+    response_type: 'code',
+    scope: SCOPES,
+    state,
+    code_challenge: challenge,
+    code_challenge_method: 'S256',
+    access_type: 'offline',
+    prompt: 'select_account consent',
+  });
+  return `${authorizeBase()}?${query.toString()}`;
+}
+
+const post = (fields: Record<string, string>, fetchImpl: FetchLike): Promise<{ status: number; body: OAuthBody }> =>
+  postForm(tokenUrl(), fields, fetchImpl, 'Google');
+
+export async function redeemCode(client: GmailClient, code: string, verifier: string, fetchImpl: FetchLike, now = Date.now()): Promise<Tokens> {
+  const { status, body } = await post(
+    {
+      grant_type: 'authorization_code',
+      code,
+      code_verifier: verifier,
+      redirect_uri: redirectUri(),
+      client_id: client.clientId,
+      client_secret: client.clientSecret,
+    },
+    fetchImpl,
+  );
+  if (status !== 200) throw new SignInError(failureOf(body));
+  return tokensOf(body, now, 'Google');
+}
+
+export async function refreshTokens(client: GmailClient, refreshToken: string, fetchImpl: FetchLike, now = Date.now()): Promise<Tokens> {
+  const { status, body } = await post(
+    { grant_type: 'refresh_token', refresh_token: refreshToken, client_id: client.clientId, client_secret: client.clientSecret },
+    fetchImpl,
+  );
+  if (status !== 200) throw new SignInError(`Google refused to renew this mailbox's sign-in, so connect Gmail again. ${failureOf(body)}`);
+  return tokensOf(body, now, 'Google', refreshToken);
+}
+
+export async function googleMessage(res: Response): Promise<string> {
+  const body = (await res.json().catch(() => ({}))) as { error?: { message?: unknown; status?: unknown } };
+  const status = typeof body.error?.status === 'string' ? body.error.status : '';
+  const message = typeof body.error?.message === 'string' ? body.error.message : '';
+  return [status, message].filter((s) => s !== '').join(': ') || `HTTP ${String(res.status)}`;
+}
+
+const wrongMailbox = (actual: string, wanted: string): string =>
+  `You signed in as ${actual}, not ${wanted}. Nothing was connected. Start again and pick ${wanted} on Google's page.`;
+
+export async function verifyMailbox(accessToken: string, fetchImpl: FetchLike, wanted: string | null): Promise<string> {
+  let res: Response;
+  try {
+    res = await fetchImpl(`${apiBase()}/gmail/v1/users/me/profile`, {
+      headers: { authorization: `Bearer ${accessToken}`, accept: 'application/json' },
+    });
+  } catch (err) {
+    throw new SignInError(`Metro could not reach Gmail: ${err instanceof Error ? err.message : String(err)}`);
+  }
+  if (!res.ok) {
+    const hint = res.status === 403 ? ' Check that the Gmail API is enabled in your Google Cloud project.' : '';
+    throw new SignInError(`Gmail refused the new sign-in (${await googleMessage(res)}), so nothing was connected.${hint}`);
+  }
+  const body = (await res.json().catch(() => ({}))) as Record<string, unknown>;
+  const email = text(body.emailAddress).toLowerCase();
+  if (email === '') throw new SignInError('Gmail did not say which mailbox this is, so nothing was connected.');
+  if (wanted !== null && wanted !== email) throw new SignInError(wrongMailbox(email, wanted));
+  return email;
+}

package/runtime/node_modules/@metro-labs/gmail/src/config.ts

@@ -0,0 +1,13 @@
+import { envUrl, envValue } from '@metro-labs/core/stations/oauth';
+
+export const SCOPES = ['https://www.googleapis.com/auth/gmail.readonly', 'https://www.googleapis.com/auth/gmail.send'].join(' ');
+
+export const MAILBOX_URL = 'https://mail.google.com/';
+
+export const authorizeBase = (): string => envUrl('METRO_GMAIL_AUTH_URL', 'https://accounts.google.com/o/oauth2/v2/auth');
+
+export const tokenUrl = (): string => envUrl('METRO_GMAIL_TOKEN_URL', 'https://oauth2.googleapis.com/token');
+
+export const apiBase = (): string => envUrl('METRO_GMAIL_API_URL', 'https://gmail.googleapis.com');
+
+export const redirectUri = (): string => envValue('METRO_GMAIL_REDIRECT', 'https://metro.box/');

package/runtime/node_modules/@metro-labs/gmail/src/inbound.ts

@@ -0,0 +1,96 @@
+import { log } from '@metro-labs/core/log';
+import { mailEnvelope, noteSeen, pollForever } from '@metro-labs/core/stations/mail';
+import { emitInbound, reportAttachment } from '@metro-labs/core/stations/train-events';
+import { TrainError } from '@metro-labs/core/train-error';
+import type { Account } from './accounts.js';
+import { gmailJson, HistoryGone, queryOf, USER } from './api.js';
+import { saveFile, withBodies } from './attachments.js';
+import { headersOf, itemOf, mailFilesOf, metaOf, type GmailMessage } from './message.js';
+import { screen } from './trust.js';
+
+const POLL_MS = Number(process.env.METRO_GMAIL_POLL_MS) || 30_000;
+
+interface HistoryPage {
+  history?: { messagesAdded?: { message?: { id?: string; labelIds?: string[] } }[] }[];
+  nextPageToken?: string;
+  historyId?: string;
+}
+
+const addedTo = (page: HistoryPage): string[] =>
+  (page.history ?? []).flatMap((h) =>
+    (h.messagesAdded ?? []).flatMap(({ message }) => {
+      const labels = message?.labelIds;
+      const inbox = labels === undefined || (labels.includes('INBOX') && !labels.includes('DRAFT'));
+      return message?.id !== undefined && inbox ? [message.id] : [];
+    }),
+  );
+
+async function fetched(acct: Account, messageId: string): Promise<GmailMessage | null> {
+  try {
+    return await withBodies(acct, await gmailJson<GmailMessage>(acct, `${USER}/messages/${encodeURIComponent(messageId)}?format=full`));
+  } catch (err) {
+    if (err instanceof TrainError && err.code === 'gmail_not_found') return null;
+    throw err;
+  }
+}
+
+async function deliver(acct: Account, messageId: string): Promise<boolean> {
+  const m = await fetched(acct, messageId);
+  if (m === null) return false;
+  const item = itemOf(m);
+  if (item.from === acct.email) return false;
+  const verdict = screen(headersOf(m), item.from, acct.cfg.includeAutomated === true);
+  if ('skip' in verdict) {
+    log.debug({ account: acct.id, reason: verdict.skip }, 'gmail: skipped an automated mail');
+    return false;
+  }
+  const files = mailFilesOf(m);
+  const env = mailEnvelope('gmail', acct.id, acct.email, item, files.map(metaOf), verdict.verified);
+  emitInbound(acct.id, env);
+  const at = { station: 'gmail', account: acct.id, line: String(env.line), forId: String(env.id) };
+  for (const [index, file] of files.entries())
+    reportAttachment(saveFile(acct, m.id, file, index), { ...at, index }, { saved: { kind: file.kind, size: file.size }, failed: { kind: file.kind } });
+  return true;
+}
+
+async function walk(acct: Account, start: string): Promise<{ count: number; latest: string }> {
+  let count = 0;
+  let latest = start;
+  let pageToken: string | undefined;
+  do {
+    const params: [string, string][] = [['startHistoryId', start], ['historyTypes', 'messageAdded'], ['labelId', 'INBOX'], ...(pageToken === undefined ? [] : [['pageToken', pageToken] as [string, string]])];
+    const page = await gmailJson<HistoryPage>(acct, `${USER}/history?${queryOf(params)}`);
+    for (const id of addedTo(page)) {
+      if (acct.state.seen.includes(id)) continue;
+      if (await deliver(acct, id)) count += 1;
+      noteSeen(acct.state.seen, id);
+    }
+    latest = page.historyId ?? latest;
+    pageToken = page.nextPageToken;
+  } while (pageToken !== undefined);
+  return { count, latest };
+}
+
+export async function syncOnce(acct: Account): Promise<number> {
+  const state = acct.state;
+  if (state.historyId === null) {
+    state.historyId = (await gmailJson<{ historyId?: string }>(acct, `${USER}/profile`)).historyId ?? null;
+    acct.save();
+    return 0;
+  }
+  let count = 0;
+  try {
+    const walked = await walk(acct, state.historyId);
+    count = walked.count;
+    state.historyId = walked.latest;
+  } catch (err) {
+    if (!(err instanceof HistoryGone)) throw err;
+    state.historyId = null;
+  }
+  acct.save();
+  return count;
+}
+
+export function startPolling(acct: Account): void {
+  pollForever(`gmail[${acct.id}]`, () => syncOnce(acct), POLL_MS);
+}

package/runtime/node_modules/@metro-labs/gmail/src/index.ts

@@ -0,0 +1,12 @@
+import { readCalls } from '@metro-labs/core/trains/protocol';
+import { announceAccounts } from '@metro-labs/core/stations/train-boot';
+import { Account, accounts, loadAccounts } from './accounts.js';
+import { handleCall } from './actions.js';
+import { startPolling } from './inbound.js';
+
+readCalls('gmail', handleCall);
+
+for (const cfg of loadAccounts()) accounts.set(cfg.id, new Account(cfg));
+announceAccounts('gmail', accounts.keys());
+
+for (const acct of accounts.values()) startPolling(acct);

package/runtime/node_modules/@metro-labs/gmail/src/login.ts

@@ -0,0 +1,37 @@
+import { BrowserSignIn, parseMailbox, type FetchLike } from '@metro-labs/core/stations/oauth';
+import { authorizeUrl, clientOf, redeemCode, verifyMailbox } from './auth.js';
+
+export { failureOf } from './auth.js';
+
+export interface GmailLoginResult {
+  config: Record<string, unknown>;
+  identity: Record<string, string>;
+}
+
+export interface GmailLoginDeps {
+  clientId?: unknown;
+  clientSecret?: unknown;
+  mailbox?: unknown;
+  fetch?: FetchLike;
+  now?: () => number;
+}
+
+export class GmailBrowserLogin extends BrowserSignIn<GmailLoginResult> {
+  constructor(deps: GmailLoginDeps) {
+    const client = clientOf(deps.clientId, deps.clientSecret);
+    const mailbox = parseMailbox(deps.mailbox);
+    const fetchImpl: FetchLike = deps.fetch ?? ((input, init) => fetch(input, init));
+    const now = deps.now ?? Date.now;
+    super({
+      authorize: (challenge, state) => authorizeUrl(client, challenge, state, mailbox),
+      redeem: async (code, verifier) => {
+        const tokens = await redeemCode(client, code, verifier, fetchImpl, now());
+        const email = await verifyMailbox(tokens.accessToken, fetchImpl, mailbox);
+        return {
+          config: { accountEmail: email, ...client, ...tokens, createdAt: new Date(now()).toISOString() },
+          identity: { email },
+        };
+      },
+    });
+  }
+}

package/runtime/node_modules/@metro-labs/gmail/src/message.ts

@@ -0,0 +1,125 @@
+import { kindOf } from '@metro-labs/core/stations/attachments';
+import type { AttachmentMeta, MailItem } from '@metro-labs/core/stations/mail';
+import { decodeEntities, htmlToText, tidy } from '@metro-labs/core/stations/mail-text';
+import { firstHeader, type MailHeader } from '@metro-labs/core/stations/mail-trust';
+
+export interface GmailPart {
+  mimeType?: string;
+  filename?: string;
+  headers?: MailHeader[];
+  body?: { attachmentId?: string; size?: number; data?: string };
+  parts?: GmailPart[];
+}
+
+export interface GmailMessage {
+  id: string;
+  threadId?: string;
+  labelIds?: string[];
+  snippet?: string;
+  internalDate?: string;
+  payload?: GmailPart;
+}
+
+export interface MailFile extends AttachmentMeta {
+  attachmentId: string | null;
+  data: string | null;
+}
+
+export interface Person {
+  address: string;
+  name: string;
+}
+
+export const LIST_HEADERS = ['From', 'To', 'Cc', 'Subject', 'Message-ID'];
+
+export const headersOf = (m: GmailMessage): MailHeader[] => m.payload?.headers ?? [];
+
+export const headerOf = (m: GmailMessage, name: string): string => firstHeader(headersOf(m), name.toLowerCase()) ?? '';
+
+const splitList = (value: string): string[] =>
+  (value.match(/(?:"(?:[^"\\]|\\.)*"|<[^>]*>|[^,"<])+/g) ?? []).map((s) => s.trim()).filter((s) => s !== '');
+
+export function personOf(raw: string): Person {
+  const angle = /<([^<>]*)>\s*$/.exec(raw);
+  if (angle === null) return { address: raw.replace(/\([^()]*\)/g, '').trim().toLowerCase(), name: '' };
+  const name = raw.slice(0, angle.index).trim().replace(/^"(.*)"$/, '$1').replace(/\\(.)/g, '$1');
+  return { address: (angle[1] ?? '').trim().toLowerCase(), name };
+}
+
+export const peopleOf = (value: string): Person[] => splitList(value).map(personOf).filter((p) => p.address.includes('@'));
+
+const addressesOf = (value: string): string[] => peopleOf(value).map((p) => p.address);
+
+function flatten(part: GmailPart | undefined): GmailPart[] {
+  return part === undefined ? [] : [part, ...(part.parts ?? []).flatMap(flatten)];
+}
+
+const isFile = (p: GmailPart): boolean => (p.filename ?? '') !== '';
+
+function charsetOf(part: GmailPart): string {
+  const type = firstHeader(part.headers ?? [], 'content-type') ?? '';
+  return /charset="?([^";\s]+)/i.exec(type)?.[1] ?? 'utf-8';
+}
+
+function decoded(part: GmailPart): string {
+  const bytes = Buffer.from(part.body?.data ?? '', 'base64url');
+  try {
+    return new TextDecoder(charsetOf(part)).decode(bytes);
+  } catch {
+    return bytes.toString('utf8');
+  }
+}
+
+export const unloadedBodies = (m: GmailMessage): GmailPart[] =>
+  flatten(m.payload).filter((p) => !isFile(p) && (p.mimeType ?? '').startsWith('text/') && (p.body?.data ?? '') === '' && (p.body?.attachmentId ?? '') !== '');
+
+export function textOf(m: GmailMessage): string {
+  const parts = flatten(m.payload).filter((p) => !isFile(p) && (p.body?.data ?? '') !== '');
+  const plain = parts.find((p) => p.mimeType === 'text/plain');
+  if (plain !== undefined) return tidy(decoded(plain));
+  const html = parts.find((p) => p.mimeType === 'text/html');
+  return html === undefined ? '' : htmlToText(decoded(html));
+}
+
+export const mailFilesOf = (m: GmailMessage): MailFile[] =>
+  flatten(m.payload)
+    .filter(isFile)
+    .map((p) => {
+      const name = p.filename ?? 'attachment';
+      const mime = p.mimeType ?? 'application/octet-stream';
+      return {
+        attachmentId: p.body?.attachmentId ?? null,
+        data: p.body?.data ?? null,
+        name,
+        mime,
+        kind: kindOf(mime, name),
+        ...(typeof p.body?.size === 'number' ? { size: p.body.size } : {}),
+      };
+    });
+
+export const metaOf = (f: MailFile): AttachmentMeta => ({
+  kind: f.kind,
+  name: f.name,
+  mime: f.mime,
+  ...(f.size === undefined ? {} : { size: f.size }),
+});
+
+export function itemOf(m: GmailMessage): MailItem {
+  const from = personOf(headerOf(m, 'From'));
+  const at = Number(m.internalDate);
+  return {
+    id: m.id,
+    threadId: m.threadId ?? m.id,
+    subject: headerOf(m, 'Subject').trim(),
+    from: from.address,
+    fromName: from.name,
+    to: addressesOf(headerOf(m, 'To')),
+    cc: addressesOf(headerOf(m, 'Cc')),
+    date: Number.isFinite(at) && at > 0 ? new Date(at).toISOString() : null,
+    preview: decodeEntities(m.snippet ?? '').trim(),
+    text: textOf(m),
+    hasAttachments: mailFilesOf(m).length > 0 || m.payload?.mimeType === 'multipart/mixed',
+    isRead: !(m.labelIds ?? []).includes('UNREAD'),
+    internetMessageId: headerOf(m, 'Message-ID') || null,
+  };
+}

package/runtime/node_modules/@metro-labs/gmail/src/mime.ts

@@ -0,0 +1,70 @@
+import { randomBytes } from 'node:crypto';
+import { readFile } from 'node:fs/promises';
+import { kindOf } from '@metro-labs/core/stations/attachments';
+import type { OutgoingFile } from '@metro-labs/core/stations/mail';
+
+export interface Draft {
+  from: string;
+  to: string[];
+  cc: string[];
+  subject: string;
+  text: string;
+  inReplyTo: string;
+  references: string;
+  files: OutgoingFile[];
+}
+
+const CRLF = '\r\n';
+
+const oneLine = (v: string): string => v.replace(/[\r\n]+/g, ' ').trim();
+const isAscii = (v: string): boolean => /^[\x20-\x7e]*$/.test(v);
+const WORD_BYTES = 45;
+const FOLD = `${CRLF} `;
+
+function utf8Chunks(v: string): string[] {
+  const chunks = [''];
+  for (const ch of v) {
+    const last = chunks.length - 1;
+    if (Buffer.byteLength((chunks[last] ?? '') + ch) > WORD_BYTES) chunks.push(ch);
+    else chunks[last] = (chunks[last] ?? '') + ch;
+  }
+  return chunks;
+}
+
+const encodedWord = (v: string): string =>
+  isAscii(v) ? v : utf8Chunks(v).map((c) => `=?UTF-8?B?${Buffer.from(c, 'utf8').toString('base64')}?=`).join(FOLD);
+const quoted = (v: string): string => `"${v.replace(/["\\]/g, '\\$&')}"`;
+const base64Lines = (data: Buffer): string => data.toString('base64').replace(/.{1,76}/g, `$&${CRLF}`);
+export const boundaryOf = (): string => `metro_${randomBytes(12).toString('hex')}`;
+
+function fileHeaders(file: OutgoingFile): string[] {
+  const name = oneLine(file.name);
+  const typeName = isAscii(name) ? quoted(name) : quoted(encodedWord(name));
+  const disposition = isAscii(name) ? `filename=${quoted(name)}` : `filename*=UTF-8''${encodeURIComponent(name)}`;
+  return [`Content-Type: ${oneLine(file.mime)}; name=${typeName}`, `Content-Disposition: attachment; ${disposition}`, 'Content-Transfer-Encoding: base64'];
+}
+
+const part = (headers: string[], body: Buffer): string => [...headers, '', base64Lines(body)].join(CRLF);
+
+export async function buildMime(d: Draft): Promise<{ mime: string; labels: string[] }> {
+  const head = [
+    `From: ${d.from}`,
+    `To: ${d.to.join(`,${FOLD}`)}`,
+    ...(d.cc.length > 0 ? [`Cc: ${d.cc.join(`,${FOLD}`)}`] : []),
+    `Subject: ${encodedWord(oneLine(d.subject))}`,
+    ...(d.inReplyTo === '' ? [] : [`In-Reply-To: ${oneLine(d.inReplyTo)}`]),
+    ...(d.references === '' ? [] : [`References: ${oneLine(d.references).split(/\s+/).join(FOLD)}`]),
+    'MIME-Version: 1.0',
+  ];
+  const text = part(['Content-Type: text/plain; charset="UTF-8"', 'Content-Transfer-Encoding: base64'], Buffer.from(d.text, 'utf8'));
+  if (d.files.length === 0) return { mime: [...head, text].join(CRLF), labels: [] };
+  const boundary = boundaryOf();
+  const parts = [text];
+  const labels: string[] = [];
+  for (const file of d.files) {
+    parts.push(part(fileHeaders(file), await readFile(file.path)));
+    labels.push(kindOf(file.mime, file.path));
+  }
+  const body = [...parts.map((p) => `--${boundary}${CRLF}${p}`), `--${boundary}--`, ''];
+  return { mime: [...head, `Content-Type: multipart/mixed; boundary="${boundary}"`, '', ...body].join(CRLF), labels };
+}