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

package/runtime/node_modules/@metro-labs/discord-bot/src/format.ts

@@ -1,56 +1,9 @@
 import { MessageFlags, type Message, type MessageReaction, type User } from 'discord.js';
+import { reportAttachment, selfUri } from '@metro-labs/core/stations/train-events';
 import { accounts, lineOf } from './accounts.js';
-import { emit, mintId, SELF_URI } from './wire.js';
+import { emit, mintId } from '@metro-labs/core/stations/station-runtime';
 import { saveDiscordAttachment } from './attachments.js';
 
-export function emitInbound(
-  accountId: string,
-  e: Record<string, unknown>,
-): void {
-  const owner = accounts.get(accountId)?.cfg.owner;
-  const payload = {
-    ...(e.payload as Record<string, unknown> | undefined),
-    account: accountId,
-  };
-  emit({ ...e, ...(owner ? { to: owner } : {}), account: accountId, payload });
-}
-
-function emitAttachmentSaved(
-  accountId: string,
-  line: string,
-  sourceMsgId: string,
-  index: number,
-  ref: { url: string; name?: string | null; contentType?: string | null },
-  messageId: string,
-): void {
-  void saveDiscordAttachment(ref, messageId, index)
-    .then((saved) => {
-      emitInbound(accountId, {
-        kind: 'inbound',
-        id: mintId(),
-        ts: new Date().toISOString(),
-        station: 'discord-bot',
-        line,
-        from: SELF_URI,
-        text: `📎 saved: ${saved.path}`,
-        payload: {
-          contentType: 'attachmentSaved',
-          attachmentFor: sourceMsgId,
-          index,
-          attachmentPath: saved.path,
-          localPath: saved.path,
-          mime: saved.mime,
-          name: saved.name,
-        },
-      });
-    })
-    .catch((err: unknown) =>
-      process.stderr.write(
-        `discord-bot attachment save failed: ${err instanceof Error ? err.message : String(err)}\n`,
-      ),
-    );
-}
-
 const AV_TAG: Record<string, string> = { audio: 'audio', video: 'video' };
 
 function tagFor(att: {
@@ -65,6 +18,20 @@ function tagFor(att: {
   return `[${kind}: ${att.name ?? kind}]`;
 }
 
+function addressing(accountId: string, m: Message): { mentions_self: boolean; reply_to_self: boolean } {
+  const me = accounts.get(accountId)?.client.user ?? null;
+  if (me === null) return { mentions_self: false, reply_to_self: false };
+  return {
+    mentions_self: m.mentions.has(me, { ignoreRepliedUser: true, ignoreEveryone: true }),
+    reply_to_self: m.mentions.repliedUser?.id === me.id,
+  };
+}
+
+const senderOf = (m: Message): Record<string, string | undefined> => ({
+  from_name: m.author.username,
+  from_display_name: m.member?.displayName ?? m.author.globalName ?? undefined,
+});
+
 export function messageEnvelope(
   accountId: string,
   m: Message,
@@ -89,29 +56,25 @@ export function messageEnvelope(
     size: a.size,
   }));
   attachments.forEach((a, i) => {
-    emitAttachmentSaved(
-      accountId,
-      line,
-      envId,
-      i,
-      { url: a.url, name: a.name, contentType: a.contentType },
-      m.id,
+    reportAttachment(
+      saveDiscordAttachment({ url: a.url, name: a.name, contentType: a.contentType }, m.id, i),
+      { station: 'discord-bot', account: accountId, line, forId: envId, index: i },
+      { failed: { name: a.name, mime: a.contentType ?? undefined } },
     );
   });
   return {
-    kind: 'inbound',
     id: envId,
     ts: new Date(m.createdTimestamp).toISOString(),
     station: 'discord-bot',
     line,
     line_name: 'name' in m.channel ? m.channel.name : undefined,
     from: `metro://discord-bot/${accountId}/user/${m.author.id}`,
-    from_name: m.author.username,
-    from_display_name: m.author.globalName ?? undefined,
+    ...senderOf(m),
     message_id: m.id,
     text,
     is_private: m.guildId == null,
     reply_to: m.reference?.messageId ?? undefined,
+    ...addressing(accountId, m),
     ...(m.reference?.messageId
       ? { event: { type: 'reply', replyTo: m.reference.messageId } }
       : {}),
@@ -126,7 +89,6 @@ export function reactionEnvelope(
 ): Record<string, unknown> | null {
   if (u.bot) return null;
   return {
-    kind: 'react',
     id: mintId(),
     ts: new Date().toISOString(),
     station: 'discord-bot',
@@ -152,23 +114,20 @@ export function reactionEnvelope(
 }
 
 function outbound(
-  kind: string,
   accountId: string,
   line: string,
   messageId: string,
   extra: object,
 ): void {
   emit({
-    kind,
     id: mintId(),
     ts: new Date().toISOString(),
     station: 'discord-bot',
     line,
-    from: SELF_URI,
+    from: selfUri(),
     to: line,
     message_id: messageId,
     ...extra,
-    account: accountId,
     payload: { account: accountId },
   });
 }
@@ -180,7 +139,7 @@ export function emitOutbound(
   text: string,
   replyTo?: string,
 ): void {
-  outbound('outbound', accountId, line, messageId, {
+  outbound(accountId, line, messageId, {
     text,
     reply_to: replyTo,
     ...(replyTo ? { event: { type: 'reply', replyTo } } : {}),
@@ -192,7 +151,7 @@ export function emitOutboundReact(
   messageId: string,
   emoji: string,
 ): void {
-  outbound('react', accountId, line, messageId, {
+  outbound(accountId, line, messageId, {
     emoji,
     event: { type: 'react', emoji, targetId: messageId },
   });
@@ -203,7 +162,7 @@ export function emitOutboundEdit(
   messageId: string,
   text: string,
 ): void {
-  outbound('edit', accountId, line, messageId, {
+  outbound(accountId, line, messageId, {
     text,
     event: { type: 'edit', targetId: messageId },
   });

package/runtime/node_modules/@metro-labs/discord-bot/src/group-actions.ts

@@ -1,5 +1,5 @@
 import { routeOf, rest } from './accounts.js';
-import { respond } from './wire.js';
+import { respond } from '@metro-labs/core/stations/station-runtime';
 import {
   groupAddMembers,
   groupCreate,

package/runtime/node_modules/@metro-labs/discord-bot/src/group.ts

@@ -1,8 +1,8 @@
-import { errMsg } from '@metro-labs/mcp/log';
+import { errMsg } from '@metro-labs/core/log';
 import type {
   GroupResult,
   MemberOutcome,
-} from '@metro-labs/mcp/stations/types';
+} from '@metro-labs/core/stations/types';
 import { lineOf } from './accounts.js';
 
 export type RestFn = <T = unknown>(

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

@@ -1,4 +1,4 @@
-import { errMsg } from '@metro-labs/mcp/log';
+import { errMsg } from '@metro-labs/core/log';
 import {
   Client,
   Events,
@@ -14,9 +14,11 @@ import {
   lineOf,
   type AccountConfig,
 } from './accounts.js';
-import { emitInbound, messageEnvelope, reactionEnvelope } from './format.js';
-import { mintId } from './wire.js';
-import { readCalls } from '@metro-labs/mcp/trains/protocol';
+import { emitInbound } from '@metro-labs/core/stations/train-events';
+import { messageEnvelope, reactionEnvelope } from './format.js';
+import { mintId } from '@metro-labs/core/stations/station-runtime';
+import { readCalls } from '@metro-labs/core/trains/protocol';
+import { announceAccounts } from '@metro-labs/core/stations/train-boot';
 import { handleCall } from './actions.js';
 
 readCalls('discord-bot', handleCall);
@@ -30,7 +32,6 @@ function makeClient(): Client {
       GatewayIntentBits.GuildMessageReactions,
       GatewayIntentBits.DirectMessages,
       GatewayIntentBits.DirectMessageReactions,
-      GatewayIntentBits.GuildVoiceStates,
     ],
     partials: [
       Partials.Channel,
@@ -44,7 +45,6 @@ function makeClient(): Client {
 function onEdit(accountId: string, m: Message): void {
   if (m.author.bot) return;
   emitInbound(accountId, {
-    kind: 'edit',
     id: mintId(),
     ts: new Date(m.editedTimestamp ?? Date.now()).toISOString(),
     station: 'discord-bot',
@@ -104,7 +104,7 @@ async function bootAccount(cfg: AccountConfig): Promise<void> {
   accounts.set(accountId, { cfg, client });
   await client.login(cfg.token);
   process.stderr.write(
-    `discord-bot[${accountId}] ready — ${client.user?.tag ?? '?'} (owner=${cfg.owner ?? '(broadcast)'})\n`,
+    `discord-bot[${accountId}] ready — ${client.user?.tag ?? '?'}\n`,
   );
 }
 
@@ -118,10 +118,4 @@ for (const cfg of cfgs) {
     );
   }
 }
-if (accounts.size === 0) {
-  process.stderr.write('discord-bot: no accounts booted, exiting\n');
-  process.exit(2);
-}
-process.stderr.write(
-  `discord-bot train ready — ${accounts.size} account(s): ${[...accounts.keys()].join(', ')}\n`,
-);
+announceAccounts('discord-bot', accounts.keys());

package/runtime/node_modules/@metro-labs/discord-bot/src/members.ts

@@ -1,5 +1,5 @@
-import { errMsg } from '@metro-labs/mcp/log';
-import type { MemberList, MetroMember } from '@metro-labs/mcp/stations/types';
+import { errMsg } from '@metro-labs/core/log';
+import type { MemberList, MetroMember } from '@metro-labs/core/stations/types';
 import { rest } from './accounts.js';
 
 export interface DiscordRole {

package/runtime/node_modules/@metro-labs/discord-bot/src/profile.ts

@@ -0,0 +1,68 @@
+import { readFile } from 'node:fs/promises';
+import type { Client } from 'discord.js';
+import { TrainError } from '@metro-labs/core/train-error';
+import {
+  assertImage,
+  fieldsOf,
+  parseProfileChange,
+  type ProfileApplied,
+  type ProfileChange,
+} from '@metro-labs/core/stations/profile';
+import type { SenderProfile } from '@metro-labs/core/stations/sender-profile';
+import { accountFor, accounts } from './accounts.js';
+import { respond } from '@metro-labs/core/stations/station-runtime';
+
+export async function applyProfile(
+  client: Client,
+  change: ProfileChange,
+): Promise<void> {
+  const user = client.user;
+  if (!user) throw new TrainError('discord_not_ready', 'the gateway is not ready yet');
+  if (change.avatar !== undefined) assertImage(change.avatar);
+  const avatar = change.avatar === undefined ? undefined : await readFile(change.avatar.path);
+  if (change.name !== undefined || avatar !== undefined)
+    await user.edit({
+      ...(change.name === undefined ? {} : { username: change.name }),
+      ...(avatar === undefined ? {} : { avatar }),
+    });
+  if (change.bio !== undefined) {
+    const app = client.application;
+    if (!app) throw new TrainError('discord_not_ready', 'the application is not loaded yet');
+    await app.edit({ description: change.bio });
+  }
+}
+
+export async function setProfile(
+  id: string,
+  args: Record<string, unknown>,
+): Promise<void> {
+  const accountId = accountFor({ account: args.account as string | undefined });
+  const acct = accounts.get(accountId);
+  if (!acct) {
+    respond(id, { error: `unknown account '${accountId}'` });
+    return;
+  }
+  const change = parseProfileChange(args);
+  await applyProfile(acct.client, change);
+  const result: ProfileApplied = { account: accountId, applied: fieldsOf(change) };
+  respond(id, { result });
+}
+
+export async function readProfile(id: string, args: Record<string, unknown>): Promise<void> {
+  const accountId = accountFor({ account: args.account as string | undefined });
+  const acct = accounts.get(accountId);
+  if (!acct) {
+    respond(id, { error: `unknown account '${accountId}'` });
+    return;
+  }
+  const user = typeof args.user === 'string' ? args.user.trim() : '';
+  if (!/^\d+$/.test(user)) throw new TrainError('discord_user_required', 'profile needs the Discord id of the person', { retryable: false });
+  const found = await acct.client.users.fetch(user);
+  const result: SenderProfile = {
+    id: user,
+    name: found.username,
+    ...(found.globalName === null ? {} : { display_name: found.globalName }),
+    avatar: found.displayAvatarURL({ size: 256 }),
+  };
+  respond(id, { result });
+}

package/runtime/node_modules/@metro-labs/discord-bot/src/send-files.ts

@@ -1,4 +1,5 @@
-import { appendFile } from '@metro-labs/mcp/stations/attachments';
+import { appendFile } from '@metro-labs/core/stations/attachments';
+import type { CanonicalAttachment } from '@metro-labs/core/stations/types';
 
 export interface OutgoingFile {
   path: string;
@@ -6,25 +7,23 @@ export interface OutgoingFile {
   kind: string;
 }
 
+type WireAttachment = CanonicalAttachment & { kind?: string };
+
 const basenameOf = (path: string, index: number): string =>
   path.split('/').pop() ?? `file-${index}`;
 
-export function outgoingFiles(
-  paths: string[],
-  names: string[] | undefined,
-  kinds: string[] | undefined,
-): OutgoingFile[] {
+export function outgoingFiles(attachments: unknown): OutgoingFile[] {
+  if (!Array.isArray(attachments)) return [];
   const out: OutgoingFile[] = [];
-  for (let i = 0; i < paths.length; i++) {
-    const path = paths[i];
-    if (path === undefined || path === '') continue;
-    const given = names?.[i];
+  (attachments as WireAttachment[]).forEach((a, i) => {
+    const path = a.path;
+    if (path === undefined || path === '') return;
     out.push({
       path,
-      name: given !== undefined && given !== '' ? given : basenameOf(path, i),
-      kind: kinds?.[i] ?? 'file',
+      name: a.name !== undefined && a.name !== '' ? a.name : basenameOf(path, i),
+      kind: a.kind ?? 'file',
     });
-  }
+  });
   return out;
 }
 

package/runtime/node_modules/@metro-labs/discord-bot/src/station.ts

@@ -1,4 +1,5 @@
-import type { GroupOp, Station, Verb } from '@metro-labs/mcp/stations/types';
+import type { GroupOp, Station, Verb } from '@metro-labs/core/stations/types';
+import { PROFILE_FIELDS, type ProfileField } from '@metro-labs/core/stations/profile';
 
 export const discordBotStation: Station = {
   name: 'discord-bot',
@@ -12,8 +13,12 @@ export const discordBotStation: Station = {
     'edit',
     'delete',
     'read',
+    'typing',
   ]),
   groupOps: new Set<GroupOp>(['create_group', 'add_members', 'remove_members']),
   attachmentMode: 'canonical',
+  profileFields: new Set<ProfileField>(PROFILE_FIELDS),
+  readsProfiles: true,
+  discoversChannels: true,
   tools: [],
 };

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

@@ -0,0 +1,27 @@
+{
+  "name": "@metro-labs/gmail",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "exports": {
+    ".": "./src/station.ts",
+    "./train": "./src/index.ts",
+    "./login": "./src/login.ts",
+    "./managed": "./src/managed.ts",
+    "./managed-binding": "./src/managed-binding.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,133 @@
+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 { renewManaged, revokeManaged } from './managed.js';
+import { checkManagedBinding, type ManagedBinding } from './managed-binding.js';
+import { loadState, saveState, type AccountState } from './state.js';
+
+export interface AccountConfig extends ManagedBinding {
+  id: string;
+  accountEmail: string;
+  clientId?: string;
+  clientSecret?: string;
+  refreshGrant?: string;
+  authorizationId?: string;
+  sendEnabled?: boolean;
+  refreshToken: string;
+  accessToken?: string;
+  expiresAt?: number;
+  includeAutomated?: boolean;
+}
+
+const filled = (v: unknown): boolean => typeof v === 'string' && v !== '';
+
+function checkClient(a: AccountConfig, die: Die): void {
+  if (a.managed === true) {
+    if (!filled(a.refreshGrant) || !filled(a.managedHost) || !filled(a.managedOrganization) || !filled(a.authorizationId) || typeof a.sendEnabled !== 'boolean') die(`account '${a.id}' has an incomplete managed sign-in`);
+  } else if (!filled(a.clientId) || !filled(a.clientSecret)) die(`account '${a.id}' has no OAuth client`);
+}
+
+function checkAccount(a: AccountConfig, die: Die): void {
+  if (!filled(a.accountEmail) || !a.accountEmail.includes('@')) die(`account '${a.id}' has no mailbox address`);
+  checkClient(a, die);
+  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;
+  private readonly pendingTokens = new Set<Promise<string>>();
+  private closing = false;
+  private revoked = false;
+
+  constructor(
+    readonly cfg: AccountConfig,
+    private readonly fetchImpl: FetchLike = (input, init) => fetch(input, init),
+  ) {
+    this.email = cfg.accountEmail.toLowerCase();
+    this.state = loadState(cfg.id, cfg);
+    const client = { clientId: cfg.clientId ?? '', clientSecret: cfg.clientSecret ?? '' };
+    this.keeper = new TokenKeeper(this.state, async (refreshToken) => {
+      checkManagedBinding(cfg);
+      const tokens = await (cfg.managed === true
+        ? renewManaged(refreshToken, this.state.refreshGrant ?? '', cfg.managedHost ?? '', this.fetchImpl)
+        : refreshTokens(client, refreshToken, this.fetchImpl, Date.now(), cfg.sendEnabled)).catch(signedOut);
+      return tokens;
+    }, () => {
+      this.save();
+    });
+  }
+
+  get id(): string {
+    return this.cfg.id;
+  }
+
+  save(): void {
+    saveState(this.cfg.id, this.state);
+  }
+
+  check(): void {
+    if (this.closing) throw new TrainError('gmail_disconnecting', 'This Gmail connection is disconnecting.', { retryable: false });
+    checkManagedBinding(this.cfg);
+  }
+
+  async token(force = false): Promise<string> {
+    this.check();
+    const pending = this.keeper.token(force);
+    this.pendingTokens.add(pending);
+    try {
+      const token = await pending;
+      this.check();
+      return token;
+    } finally {
+      this.pendingTokens.delete(pending);
+    }
+  }
+
+  async disconnect(authorizationId: unknown): Promise<void> {
+    if (this.cfg.managed !== true || !authorizationId || authorizationId !== this.cfg.authorizationId) throw new TrainError('gmail_connection_changed', 'This Gmail connection changed. Try deleting again.', { retryable: false });
+    if (this.revoked) return;
+    if (this.closing) throw new TrainError('gmail_disconnecting', 'This Gmail connection is disconnecting.', { retryable: false });
+    this.closing = true;
+    try {
+      await Promise.allSettled([...this.pendingTokens]);
+      await revokeManaged(this.state.refreshToken, this.state.refreshGrant ?? '', this.cfg.managedHost ?? '', this.fetchImpl);
+      this.revoked = true;
+    } catch (err) {
+      this.closing = false;
+      throw err;
+    }
+  }
+
+  async fetch(input: string, init?: RequestInit): Promise<Response> {
+    this.check();
+    const result = await this.fetchImpl(input, init);
+    this.check();
+    return result;
+  }
+}
+
+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,20 @@
+import { makeStation, respond } from '@metro-labs/core/stations/station-runtime';
+import { accountOf, accounts } from './accounts.js';
+import { listChannels } from './channels.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, managed: a.cfg.managed === true, ...(a.cfg.sendEnabled === undefined ? {} : { sendEnabled: a.cfg.sendEnabled }) }));
+  respond(id, { result: { accounts: list } });
+}
+
+async function disconnect(id: string, args: Record<string, unknown>): Promise<void> {
+  await accountOf(args).disconnect(args.authorizationId);
+  respond(id, { result: { revoked: true } });
+}
+
+export const handleCall = makeStation({
+  handlers: { accounts: listAccounts, listChannels, send, reply, read, disconnect },
+});

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

@@ -0,0 +1,34 @@
+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);
+  acct.check();
+  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> {
+  const body = (await (await gmail(acct, path, init)).json()) as T;
+  acct.check();
+  return body;
+}
+
+export const queryOf = (params: [string, string][]): string => new URLSearchParams(params).toString();

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

@@ -0,0 +1,38 @@
+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 });
+  acct.check();
+  const saved = await saveBufferToCache(new Uint8Array(Buffer.from(data, 'base64url')), messageId, index, { mime: file.mime, name: file.name });
+  acct.check();
+  return saved;
+}
+
+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 },
+    );
+}