@stage-labs/metro 0.1.0-beta.31 → 0.1.0-beta.310

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

@@ -0,0 +1,115 @@
+import { postForm, SignInError, tokensOf, type FetchLike, type OAuthBody, type Tokens } from '@metro-labs/core/stations/oauth';
+import { apiBase, authorizeBase, redirectUri, scopesFor, tokenUrl } from './config.js';
+
+export function checkScopes(scope: unknown, sendEnabled: boolean): void {
+  const granted = typeof scope === 'string' ? scope.split(/\s+/).filter(Boolean) : [];
+  const wanted = scopesFor(sendEnabled).split(' ');
+  if (wanted.some((s) => !granted.includes(s)) || granted.some((s) => !wanted.includes(s)))
+    throw new SignInError('Google did not grant exactly the requested Gmail access. Review this app in your Google Account, then connect again.');
+}
+
+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, sendEnabled = false): string {
+  const query = new URLSearchParams({
+    ...(loginHint === null ? {} : { login_hint: loginHint }),
+    client_id: client.clientId,
+    redirect_uri: redirectUri(),
+    response_type: 'code',
+    scope: scopesFor(sendEnabled),
+    ...(sendEnabled ? { include_granted_scopes: 'true' } : {}),
+    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(), sendEnabled = false): 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));
+  checkScopes(body.scope, sendEnabled);
+  return tokensOf(body, now, 'Google');
+}
+
+export async function refreshTokens(client: GmailClient, refreshToken: string, fetchImpl: FetchLike, now = Date.now(), sendEnabled?: boolean): 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)}`);
+  if (sendEnabled !== undefined) checkScopes(body.scope, sendEnabled);
+  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/channels.ts

@@ -0,0 +1,66 @@
+import type { ChannelEntry } from '@metro-labs/core/stations/channel-directory';
+import { ChannelPages, type ChannelPage } from '@metro-labs/core/stations/channel-pages';
+import { mailLine } from '@metro-labs/core/stations/mail';
+import { firstHeader, type MailHeader } from '@metro-labs/core/stations/mail-trust';
+import { respond } from '@metro-labs/core/stations/station-runtime';
+import { TrainError } from '@metro-labs/core/train-error';
+import { accountOf, type Account } from './accounts.js';
+import { gmailJson, queryOf, USER } from './api.js';
+
+const BATCH = 10;
+const SCOPE = 'Matches thread ids, lines and subjects in Gmail mailbox order, excluding Spam and Trash.';
+const directories = new WeakMap<Account, ChannelPages>();
+
+interface ThreadPage {
+  threads?: { id?: string }[];
+  nextPageToken?: string;
+}
+
+interface ThreadSubject {
+  messages?: { payload?: { headers?: MailHeader[] } }[];
+}
+
+async function threadEntry(acct: Account, id: string, signal: AbortSignal): Promise<ChannelEntry> {
+  const params: [string, string][] = [
+    ['format', 'metadata'],
+    ['metadataHeaders', 'Subject'],
+    ['fields', 'messages(payload(headers(name,value)))'],
+  ];
+  const thread = await gmailJson<ThreadSubject>(acct, `${USER}/threads/${encodeURIComponent(id)}?${queryOf(params)}`, { redirect: 'error', signal });
+  const subject = firstHeader(thread.messages?.[0]?.payload?.headers ?? [], 'subject') ?? '';
+  return { id, line: mailLine('gmail', acct.id, id), kind: 'thread', ...(subject ? { name: subject } : {}) };
+}
+
+async function loadPage(account: Account, token: string | undefined, limit: number, seen: ReadonlySet<string>): Promise<ChannelPage> {
+  const signal = AbortSignal.timeout(45_000);
+  const params: [string, string][] = [
+    ['maxResults', String(limit)],
+    ['fields', 'threads(id),nextPageToken'],
+    ...(token ? [['pageToken', token] as [string, string]] : []),
+  ];
+  const page = await gmailJson<ThreadPage>(account, `${USER}/threads?${queryOf(params)}`, { redirect: 'error', signal });
+  const rows = page.threads ?? [];
+  if (rows.length > limit) throw new TrainError('gmail_channel_page', 'Gmail returned more thread metadata than requested.');
+  const ids = new Set<string>();
+  for (const row of rows) {
+    if (!row.id || row.id.length > 1024) throw new TrainError('gmail_channel_page', 'Gmail returned invalid thread metadata.');
+    if (!seen.has(row.id)) ids.add(row.id);
+  }
+  const channels: ChannelEntry[] = [];
+  const unique = [...ids];
+  for (let i = 0; i < unique.length; i += BATCH) {
+    channels.push(...await Promise.all(unique.slice(i, i + BATCH).map((id) => threadEntry(account, id, signal))));
+  }
+  return { channels, scanned: rows.length, ...(page.nextPageToken ? { next: page.nextPageToken } : {}) };
+}
+
+export async function listChannels(id: string, args: Record<string, unknown>): Promise<void> {
+  if (typeof args.account !== 'string' || !args.account.trim()) throw new TrainError('bad_request', 'account is required to list channels.');
+  const account = accountOf({ account: args.account });
+  account.check();
+  const directory = directories.get(account) ?? new ChannelPages();
+  directories.set(account, directory);
+  const result = await directory.list(account.id, args, (token, limit, seen) => loadPage(account, token, limit, seen), SCOPE);
+  account.check();
+  respond(id, { result });
+}

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

@@ -0,0 +1,15 @@
+import { envUrl, envValue } from '@metro-labs/core/stations/oauth';
+
+export const READ_SCOPE = 'https://www.googleapis.com/auth/gmail.readonly';
+export const SEND_SCOPE = 'https://www.googleapis.com/auth/gmail.send';
+export const scopesFor = (sendEnabled = false): string => [READ_SCOPE, ...(sendEnabled ? [SEND_SCOPE] : [])].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,97 @@
+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);
+  acct.check();
+  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,39 @@
+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;
+  sendEnabled?: boolean;
+  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;
+    const sendEnabled = deps.sendEnabled === true;
+    super({
+      authorize: (challenge, state) => authorizeUrl(client, challenge, state, mailbox, sendEnabled),
+      redeem: async (code, verifier) => {
+        const tokens = await redeemCode(client, code, verifier, fetchImpl, now(), sendEnabled);
+        const email = await verifyMailbox(tokens.accessToken, fetchImpl, mailbox);
+        return {
+          config: { accountEmail: email, ...client, ...tokens, sendEnabled, createdAt: new Date(now()).toISOString() },
+          identity: { email },
+        };
+      },
+    });
+  }
+}

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

@@ -0,0 +1,33 @@
+import { readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { ensureSecureDir, writeSecure } from '@metro-labs/core/secure-fs';
+import { TrainError } from '@metro-labs/core/train-error';
+
+export interface ManagedBinding {
+  managed?: boolean;
+  managedOrganization?: string;
+  managedHost?: string;
+}
+
+const bindingDir = (): string => process.env.METRO_AGENTS_DIR ?? join(homedir(), '.metro', 'agents');
+
+export function setManagedHost(url: string | null): void {
+  const dir = bindingDir();
+  ensureSecureDir(dir);
+  writeSecure(join(dir, '.gmail-host'), url === null ? '' : new URL(url).host);
+}
+
+export function checkManagedBinding(config: ManagedBinding): void {
+  if (config.managed !== true) return;
+  let owner = '';
+  let host = '';
+  try {
+    owner = readFileSync(join(bindingDir(), '.owner'), 'utf8').trim();
+    host = readFileSync(join(bindingDir(), '.gmail-host'), 'utf8').trim();
+  } catch {
+    throw new TrainError('gmail_binding_changed', 'Reconnect managed Gmail on this box before using it.', { retryable: false });
+  }
+  if (!owner || owner !== config.managedOrganization || !host || host !== config.managedHost)
+    throw new TrainError('gmail_binding_changed', 'This box changed owner or address. Reconnect managed Gmail before using it.', { retryable: false });
+}

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

@@ -0,0 +1,45 @@
+import { SignInError, type FetchLike, type Tokens } from '@metro-labs/core/stations/oauth';
+
+const BASE = 'https://api.metro.box/api/gmail';
+const reach: FetchLike = (input, init) => fetch(input, init);
+
+export interface ManagedTokens extends Tokens {
+  refreshGrant: string;
+}
+
+export async function managedRequest(path: 'start' | 'exchange' | 'cancel' | 'refresh' | 'revoke', body: Record<string, unknown>, bearer?: string, fetchImpl = reach): Promise<Record<string, unknown>> {
+  let response: Response;
+  try {
+    response = await fetchImpl(`${BASE}/${path}`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json', ...(bearer === undefined ? {} : { authorization: bearer }) },
+      body: JSON.stringify(body),
+      redirect: 'error',
+      signal: AbortSignal.timeout(25_000),
+    });
+  } catch {
+    throw new SignInError('Metro could not reach managed Gmail sign-in. Try again.');
+  }
+  if (!response.ok) {
+    const retry = response.status >= 500 ? 'Try again later.' : 'Start Gmail sign-in again. Your Google Workspace administrator may need to allow the app.';
+    throw new SignInError(`Metro could not complete managed Gmail sign-in. ${retry}`);
+  }
+  const value: unknown = await response.json().catch(() => null);
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) throw new SignInError('Metro returned an invalid Gmail answer.');
+  return value as Record<string, unknown>;
+}
+
+export function managedTokens(value: Record<string, unknown>): ManagedTokens {
+  if (typeof value.accessToken !== 'string' || !value.accessToken || typeof value.refreshToken !== 'string' || !value.refreshToken || typeof value.refreshGrant !== 'string' || !value.refreshGrant || typeof value.expiresAt !== 'number' || !Number.isFinite(value.expiresAt))
+    throw new SignInError('Metro returned an incomplete Gmail sign-in.');
+  return { accessToken: value.accessToken, refreshToken: value.refreshToken, refreshGrant: value.refreshGrant, expiresAt: value.expiresAt };
+}
+
+export async function renewManaged(refreshToken: string, refreshGrant: string, host: string, fetchImpl = reach): Promise<ManagedTokens> {
+  return managedTokens(await managedRequest('refresh', { refreshToken, refreshGrant, host }, undefined, fetchImpl));
+}
+
+export async function revokeManaged(refreshToken: string, refreshGrant: string, host: string, fetchImpl = reach): Promise<void> {
+  const result = await managedRequest('revoke', { refreshToken, refreshGrant, host }, undefined, fetchImpl);
+  if (result.revoked !== true) throw new SignInError('Metro did not confirm Google revocation. Try again.');
+}

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 };
+}