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

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

@@ -0,0 +1,23 @@
+import { envUrl, envValue } from '@metro-labs/core/stations/oauth';
+
+export const OUTLOOK_CLIENT_ID = 'a2fbd978-97ee-4cc9-92bb-9d9567a7bf40';
+
+export const SCOPES = [
+  'https://graph.microsoft.com/Mail.ReadWrite',
+  'https://graph.microsoft.com/Mail.Send',
+  'https://graph.microsoft.com/User.Read',
+  'offline_access',
+  'openid',
+].join(' ');
+
+export const NOT_SET_UP = 'Outlook is not set up on this Metro yet.';
+
+export const MAILBOX_URL = 'https://outlook.office.com/mail/';
+
+export const clientId = (): string => envValue('METRO_OUTLOOK_CLIENT_ID', OUTLOOK_CLIENT_ID);
+
+export const loginBase = (): string => envUrl('METRO_OUTLOOK_LOGIN_URL', 'https://login.microsoftonline.com/common');
+
+export const redirectUri = (): string => envValue('METRO_OUTLOOK_REDIRECT', 'https://metro.box/');
+
+export const graphBase = (): string => envUrl('METRO_OUTLOOK_GRAPH_URL', 'https://graph.microsoft.com/v1.0');

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

@@ -0,0 +1,59 @@
+import { bodyText } from '@metro-labs/core/stations/mail-text';
+import type { MailItem } from '@metro-labs/core/stations/mail';
+
+export interface Address {
+  emailAddress?: { name?: string; address?: string };
+}
+
+export interface GraphMessage {
+  id: string;
+  conversationId?: string;
+  subject?: string | null;
+  from?: Address | null;
+  toRecipients?: Address[];
+  ccRecipients?: Address[];
+  receivedDateTime?: string;
+  bodyPreview?: string;
+  body?: { contentType?: string; content?: string };
+  hasAttachments?: boolean;
+  isRead?: boolean;
+  internetMessageId?: string;
+  '@removed'?: unknown;
+}
+
+export const MESSAGE_FIELDS = [
+  'id',
+  'conversationId',
+  'subject',
+  'from',
+  'toRecipients',
+  'ccRecipients',
+  'receivedDateTime',
+  'bodyPreview',
+  'body',
+  'hasAttachments',
+  'isRead',
+  'internetMessageId',
+].join(',');
+
+export const LIST_FIELDS = MESSAGE_FIELDS.replace(',body,', ',');
+
+export const addressOf = (a: Address | null | undefined): string => (a?.emailAddress?.address ?? '').toLowerCase();
+
+const addresses = (list: Address[] | undefined): string[] => (list ?? []).map(addressOf).filter((s) => s !== '');
+
+export const itemOf = (m: GraphMessage): MailItem => ({
+  id: m.id,
+  threadId: m.conversationId ?? m.id,
+  subject: (m.subject ?? '').trim(),
+  from: addressOf(m.from),
+  fromName: m.from?.emailAddress?.name ?? '',
+  to: addresses(m.toRecipients),
+  cc: addresses(m.ccRecipients),
+  date: m.receivedDateTime ?? null,
+  preview: (m.bodyPreview ?? '').trim(),
+  text: bodyText(m.body),
+  hasAttachments: m.hasAttachments === true,
+  isRead: m.isRead === true,
+  internetMessageId: m.internetMessageId ?? null,
+});

package/runtime/node_modules/@metro-labs/outlook/src/graph.ts

@@ -0,0 +1,55 @@
+import { refusalOf, type MailService } from '@metro-labs/core/stations/mail';
+import type { Account } from './accounts.js';
+import { graphBase } from './config.js';
+
+type Json = Record<string, unknown>;
+
+const urlOf = (path: string): string => (/^https?:\/\//.test(path) ? path : `${graphBase()}${path}`);
+
+async function graphMessage(res: Response): Promise<string> {
+  const body = (await res.json().catch(() => ({}))) as { error?: { code?: unknown; message?: unknown } };
+  const message = typeof body.error?.message === 'string' ? body.error.message : '';
+  const code = typeof body.error?.code === 'string' ? body.error.code : '';
+  return [code, message].filter((s) => s !== '').join(': ') || `HTTP ${String(res.status)}`;
+}
+
+export class GraphGone extends Error {}
+
+const OUTLOOK: MailService = { station: 'outlook', company: 'Microsoft', product: 'Outlook', api: 'Microsoft Graph', apiCode: 'graph_error' };
+
+async function refusal(res: Response): Promise<Error> {
+  const detail = await graphMessage(res);
+  return res.status === 410 ? new GraphGone(detail) : refusalOf(OUTLOOK, res.status, detail);
+}
+
+async function send(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(urlOf(path), { ...init, headers });
+}
+
+export async function graph(acct: Account, path: string, init: RequestInit = {}): Promise<Response> {
+  let res = await send(acct, path, init, false);
+  if (res.status === 401) res = await send(acct, path, init, true);
+  if (!res.ok) throw await refusal(res);
+  return res;
+}
+
+export async function graphJson<T = Json>(acct: Account, path: string, init: RequestInit = {}): Promise<T> {
+  const res = await graph(acct, path, init);
+  return (await res.json()) as T;
+}
+
+export function jsonInit(method: string, body: unknown): RequestInit {
+  return { method, headers: { 'content-type': 'application/json' }, body: JSON.stringify(body) };
+}
+
+export const odataQuote = (value: string): string => `'${value.replace(/'/g, "''")}'`;
+
+export const queryOf = (params: Record<string, string>): string =>
+  Object.entries(params)
+    .map(([key, value]) => `${key}=${encodeURIComponent(value)}`)
+    .join('&');
+
+export const messagePath = (messageId: string): string => `/me/messages/${encodeURIComponent(messageId)}`;

package/runtime/node_modules/@metro-labs/outlook/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 type { Screened } from '@metro-labs/core/stations/mail-trust';
+import { emitInbound, reportAttachment } from '@metro-labs/core/stations/train-events';
+import type { Account } from './accounts.js';
+import { listFiles, metaOf, saveFile, type MailFile } from './attachments.js';
+import { addressOf, itemOf, MESSAGE_FIELDS, type GraphMessage } from './format.js';
+import { graphJson, GraphGone } from './graph.js';
+import { screen } from './trust.js';
+
+export const POLL_MS = Number(process.env.METRO_OUTLOOK_POLL_MS) || 30_000;
+
+const FIRST_PAGE = `/me/mailFolders/inbox/messages/delta?$select=${MESSAGE_FIELDS}`;
+const PAGE_SIZE = { prefer: 'odata.maxpagesize=50' };
+
+interface DeltaPage {
+  value?: GraphMessage[];
+  '@odata.nextLink'?: string;
+  '@odata.deltaLink'?: string;
+}
+
+function fresh(acct: Account, m: GraphMessage, since: string): boolean {
+  if (m['@removed'] !== undefined) return false;
+  if (acct.state.seen.includes(m.id)) return false;
+  if (addressOf(m.from) === acct.email) return false;
+  return Date.parse(m.receivedDateTime ?? '') >= Date.parse(since);
+}
+
+const reasonOf = (err: unknown): string => (err instanceof Error ? err.message : String(err));
+
+async function screened(acct: Account, m: GraphMessage): Promise<Screened> {
+  return screen(acct, m).catch((err: unknown) => {
+    process.stderr.write(`outlook[${acct.id}] could not read the headers of a message, so it counts as unverified: ${reasonOf(err)}\n`);
+    return { verified: false };
+  });
+}
+
+async function deliver(acct: Account, m: GraphMessage): Promise<boolean> {
+  const verdict = await screened(acct, m);
+  if ('skip' in verdict) {
+    log.debug({ account: acct.id, reason: verdict.skip }, 'outlook: skipped an automated mail');
+    return false;
+  }
+  const files: MailFile[] =
+    m.hasAttachments === true
+      ? await listFiles(acct, m.id).catch((err: unknown) => {
+          process.stderr.write(`outlook[${acct.id}] could not list the files of a message: ${reasonOf(err)}\n`);
+          return [];
+        })
+      : [];
+  const env = mailEnvelope('outlook', acct.id, acct.email, itemOf(m), files.map(metaOf), verdict.verified);
+  emitInbound(acct.id, env);
+  const at = { station: 'outlook', 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, onMessage: (m: GraphMessage) => Promise<void>): Promise<string | null> {
+  let next: string | undefined = start;
+  while (next !== undefined) {
+    const page: DeltaPage = await graphJson<DeltaPage>(acct, next, { headers: PAGE_SIZE });
+    for (const m of page.value ?? []) await onMessage(m);
+    if (page['@odata.deltaLink'] !== undefined) return page['@odata.deltaLink'];
+    next = page['@odata.nextLink'];
+  }
+  return null;
+}
+
+export async function syncOnce(acct: Account): Promise<number> {
+  const state = acct.state;
+  const since = state.syncedAt;
+  if (state.deltaLink === null || since === null) {
+    state.syncedAt = since ?? new Date().toISOString();
+    state.deltaLink = await walk(acct, FIRST_PAGE, () => Promise.resolve());
+    acct.save();
+    return 0;
+  }
+  let count = 0;
+  try {
+    state.deltaLink = await walk(acct, state.deltaLink, async (m) => {
+      if (!fresh(acct, m, since)) return;
+      if (await deliver(acct, m)) count += 1;
+      noteSeen(state.seen, m.id);
+    });
+  } catch (err) {
+    if (!(err instanceof GraphGone)) throw err;
+    state.deltaLink = null;
+  }
+  acct.save();
+  return count;
+}
+
+export function startPolling(acct: Account): void {
+  pollForever(`outlook[${acct.id}]`, () => syncOnce(acct), POLL_MS);
+}

package/runtime/node_modules/@metro-labs/outlook/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('outlook', handleCall);
+
+for (const cfg of loadAccounts()) accounts.set(cfg.id, new Account(cfg));
+announceAccounts('outlook', accounts.keys());
+
+for (const acct of accounts.values()) startPolling(acct);

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

@@ -0,0 +1,129 @@
+import { BrowserSignIn, SignInError, type FetchLike, type Tokens } from '@metro-labs/core/stations/oauth';
+import { pollDeviceCode, requestDeviceCode, type DeviceCode, type Poll } from './auth.js';
+import { authorizeUrl, redeemCode } from './browser.js';
+import { verifyMailbox, type Mailbox } from './me.js';
+
+export { NOT_SET_UP } from './config.js';
+export { failureOf } from './auth.js';
+
+export interface OutlookLoginResult {
+  config: Record<string, unknown>;
+  identity: Record<string, string>;
+}
+
+export interface OutlookLoginEvents {
+  onDone: (result: OutlookLoginResult) => void;
+  onFailed: (message: string) => void;
+}
+
+export interface OutlookLoginDeps {
+  fetch?: FetchLike;
+  now?: () => number;
+  mailbox?: string | null;
+}
+
+const SLOW_DOWN_MS = 5_000;
+
+function resultOf(tokens: Tokens, tenantId: string | null, mailbox: Mailbox, now: number): OutlookLoginResult {
+  return {
+    config: {
+      accountEmail: mailbox.email,
+      refreshToken: tokens.refreshToken,
+      accessToken: tokens.accessToken,
+      expiresAt: tokens.expiresAt,
+      tenantId,
+      createdAt: new Date(now).toISOString(),
+    },
+    identity: { email: mailbox.email, ...(mailbox.name === '' ? {} : { name: mailbox.name }) },
+  };
+}
+
+export class OutlookBrowserLogin extends BrowserSignIn<OutlookLoginResult> {
+  constructor(deps: OutlookLoginDeps = {}) {
+    const fetchImpl: FetchLike = deps.fetch ?? ((input, init) => fetch(input, init));
+    const now = deps.now ?? Date.now;
+    const mailbox = deps.mailbox ?? null;
+    super({
+      authorize: (challenge, state) => authorizeUrl(challenge, state, mailbox),
+      redeem: async (code, verifier) => {
+        const { tokens, tenantId } = await redeemCode(code, verifier, fetchImpl, now());
+        return resultOf(tokens, tenantId, await verifyMailbox(tokens.accessToken, fetchImpl, mailbox), now());
+      },
+    });
+  }
+}
+
+export class OutlookLogin {
+  private code: DeviceCode | null = null;
+  private timer: ReturnType<typeof setTimeout> | null = null;
+  private stopped = false;
+  private readonly fetchImpl: FetchLike;
+  private readonly now: () => number;
+  private readonly mailbox: string | null;
+
+  constructor(private readonly events: OutlookLoginEvents, deps: OutlookLoginDeps = {}) {
+    this.fetchImpl = deps.fetch ?? ((input, init) => fetch(input, init));
+    this.now = deps.now ?? Date.now;
+    this.mailbox = deps.mailbox ?? null;
+  }
+
+  async start(): Promise<DeviceCode> {
+    const code = await requestDeviceCode(this.fetchImpl, this.now());
+    this.code = code;
+    this.schedule(code.intervalMs);
+    return code;
+  }
+
+  cancel(): Promise<void> {
+    this.stopped = true;
+    if (this.timer !== null) clearTimeout(this.timer);
+    this.timer = null;
+    return Promise.resolve();
+  }
+
+  private schedule(delayMs: number): void {
+    if (this.stopped) return;
+    this.timer = setTimeout(() => {
+      this.tick().catch((err: unknown) => {
+        this.fail(err instanceof SignInError ? err.message : 'Metro could not finish the Microsoft sign-in.');
+      });
+    }, delayMs);
+    this.timer.unref();
+  }
+
+  private fail(message: string): void {
+    if (this.stopped) return;
+    this.stopped = true;
+    this.events.onFailed(message);
+  }
+
+  private async tick(): Promise<void> {
+    const code = this.code;
+    if (code === null || this.stopped) return;
+    if (this.now() >= code.expiresAt) {
+      this.fail('The sign-in code expired before it was used. Start again.');
+      return;
+    }
+    await this.settle(code, await pollDeviceCode(code, this.fetchImpl, this.now()));
+  }
+
+  private async settle(code: DeviceCode, poll: Poll): Promise<void> {
+    if (poll.kind === 'pending') {
+      this.schedule(code.intervalMs);
+      return;
+    }
+    if (poll.kind === 'slow_down') {
+      code.intervalMs += SLOW_DOWN_MS;
+      this.schedule(code.intervalMs);
+      return;
+    }
+    if (poll.kind === 'failed') {
+      this.fail(poll.message);
+      return;
+    }
+    const mailbox = await verifyMailbox(poll.tokens.accessToken, this.fetchImpl, this.mailbox);
+    if (this.stopped) return;
+    this.stopped = true;
+    this.events.onDone(resultOf(poll.tokens, poll.tenantId, mailbox, this.now()));
+  }
+}

package/runtime/node_modules/@metro-labs/outlook/src/me.ts

@@ -0,0 +1,31 @@
+import { SignInError, type FetchLike } from '@metro-labs/core/stations/oauth';
+import { graphBase } from './config.js';
+
+export interface Mailbox {
+  email: string;
+  name: string;
+}
+
+const text = (v: unknown): string => (typeof v === 'string' ? v.trim() : '');
+
+const wrongMailbox = (actual: string, wanted: string): string =>
+  `You signed in as ${actual}, not ${wanted}. Nothing was connected. Start again and pick ${wanted} on Microsoft's page, or use "Use another account".`;
+
+export async function verifyMailbox(accessToken: string, fetchImpl: FetchLike, wanted: string | null = null): Promise<Mailbox> {
+  let res: Response;
+  try {
+    res = await fetchImpl(`${graphBase()}/me?$select=mail,userPrincipalName,displayName`, {
+      headers: { authorization: `Bearer ${accessToken}`, accept: 'application/json' },
+    });
+  } catch (err) {
+    throw new SignInError(`Metro could not reach Microsoft Graph: ${err instanceof Error ? err.message : String(err)}`);
+  }
+  if (!res.ok) throw new SignInError(`Microsoft Graph refused the new sign-in (${String(res.status)}), so nothing was connected.`);
+  const body = (await res.json().catch(() => ({}))) as Record<string, unknown>;
+  const mail = text(body.mail).toLowerCase();
+  const principal = text(body.userPrincipalName).toLowerCase();
+  const email = mail || principal;
+  if (email === '') throw new SignInError('Microsoft Graph did not say which mailbox this is, so nothing was connected.');
+  if (wanted !== null && wanted !== mail && wanted !== principal) throw new SignInError(wrongMailbox(email, wanted));
+  return { email, name: text(body.displayName) };
+}

package/runtime/node_modules/@metro-labs/outlook/src/outbound.ts

@@ -0,0 +1,103 @@
+import { checkAddress, filesOf, isAddress, mailLine, str, subjectOf, threadOfLine, type OutgoingFile } from '@metro-labs/core/stations/mail';
+import { escapeHtml } from '@metro-labs/core/stations/mail-text';
+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 { assertSendable, attachFile } from './attachments.js';
+import { graph, graphJson, jsonInit, messagePath, odataQuote, queryOf } from './graph.js';
+
+type Args = Record<string, unknown>;
+
+export const EPOCH = '1900-01-01T00:00:00Z';
+
+export async function latestInConversation(acct: Account, conversationId: string): Promise<string> {
+  const filter = `receivedDateTime ge ${EPOCH} and conversationId eq ${odataQuote(conversationId)}`;
+  const params = queryOf({ $filter: filter, $orderby: 'receivedDateTime desc', $top: '1', $select: 'id' });
+  const body = await graphJson<{ value?: { id: string }[] }>(acct, `/me/messages?${params}`);
+  const id = body.value?.[0]?.id;
+  if (id === undefined)
+    throw new TrainError('outlook_empty_conversation', 'Outlook has no message in this conversation to answer', { retryable: false });
+  return id;
+}
+
+async function discard(acct: Account, draftId: string): Promise<void> {
+  await graph(acct, messagePath(draftId), { method: 'DELETE' }).catch((err: unknown) => {
+    process.stderr.write(`outlook[${acct.id}] could not remove an unsent draft: ${err instanceof Error ? err.message : String(err)}\n`);
+  });
+}
+
+async function withFiles(acct: Account, target: string, verb: 'reply' | 'replyAll', comment: string, files: OutgoingFile[]): Promise<string[]> {
+  const draft = await graphJson<{ id?: string }>(acct, `${messagePath(target)}/${verb === 'reply' ? 'createReply' : 'createReplyAll'}`, jsonInit('POST', { comment }));
+  const draftId = draft.id;
+  if (draftId === undefined) throw new TrainError('outlook_graph_error', 'Outlook did not open a reply draft', { retryable: true });
+  const labels: string[] = [];
+  try {
+    for (const file of files) labels.push(await attachFile(acct, draftId, file));
+    await graph(acct, `${messagePath(draftId)}/send`, { method: 'POST' });
+  } catch (err) {
+    await discard(acct, draftId);
+    throw err;
+  }
+  return labels;
+}
+
+async function compose(id: string, acct: Account, to: string, args: Args, text: string, files: OutgoingFile[]): Promise<void> {
+  checkAddress('outlook', to);
+  const draft = await graphJson<{ id?: string; conversationId?: string }>(acct, '/me/messages', jsonInit('POST', {
+    subject: subjectOf('outlook', str(args.subject), text),
+    body: { contentType: 'Text', content: text },
+    toRecipients: [{ emailAddress: { address: to } }],
+  }));
+  if (draft.id === undefined) throw new TrainError('outlook_graph_error', 'Outlook did not open a draft', { retryable: true });
+  const labels: string[] = [];
+  try {
+    for (const file of files) labels.push(await attachFile(acct, draft.id, file));
+    await graph(acct, `${messagePath(draft.id)}/send`, { method: 'POST' });
+  } catch (err) {
+    await discard(acct, draft.id);
+    throw err;
+  }
+  const line = draft.conversationId === undefined ? undefined : mailLine('outlook', acct.id, draft.conversationId);
+  respond(id, { result: { account: acct.id, messageId: draft.id, ...(line === undefined ? {} : { line }), ...(labels.length > 0 ? { attachments: labels } : {}) } });
+}
+
+interface Outgoing {
+  target: string;
+  acct: Account;
+  files: OutgoingFile[];
+  text: string;
+  replyTo: string;
+}
+
+async function outgoing(args: Args): Promise<Outgoing> {
+  const line = str(args.line);
+  const parsed = threadOfLine('outlook', line);
+  if (parsed === null) throw new TrainError('outlook_bad_line', `not an outlook line: ${line}`, { retryable: false });
+  const acct = accountOf(args);
+  const files = filesOf(args.attachments);
+  const text = typeof args.text === 'string' ? args.text : '';
+  if (text.trim() === '' && files.length === 0)
+    throw new TrainError('outlook_text_required', 'give some text or a file to send', { retryable: false });
+  await assertSendable(files);
+  return { target: parsed.threadId, acct, files, text, replyTo: str(args.replyTo) };
+}
+
+async function answer(id: string, args: Args, verb: 'reply' | 'replyAll'): Promise<void> {
+  const { target: conversation, acct, files, text, replyTo } = await outgoing(args);
+  if (isAddress(conversation)) {
+    if (verb === 'reply' || replyTo !== '')
+      throw new TrainError('outlook_reply_needs_thread', 'reply on the thread\'s own line; an address line starts a new email', { retryable: false });
+    await compose(id, acct, conversation.toLowerCase(), args, text, files);
+    return;
+  }
+  const target = replyTo === '' ? await latestInConversation(acct, conversation) : replyTo;
+  const comment = escapeHtml(text);
+  let labels: string[] = [];
+  if (files.length === 0) await graph(acct, `${messagePath(target)}/${verb}`, jsonInit('POST', { comment }));
+  else labels = await withFiles(acct, target, verb, comment, files);
+  respond(id, { result: { account: acct.id, repliedTo: target, ...(labels.length > 0 ? { attachments: labels } : {}) } });
+}
+
+export const reply = (id: string, args: Args): Promise<void> => answer(id, args, 'reply');
+
+export const send = (id: string, args: Args): Promise<void> => answer(id, args, str(args.replyTo) === '' ? 'replyAll' : 'reply');

package/runtime/node_modules/@metro-labs/outlook/src/query.ts

@@ -0,0 +1,84 @@
+import { mailFull, mailSummary, MAX_LIMIT, readQueryOf, str, type ReadQuery } from '@metro-labs/core/stations/mail';
+import { respond } from '@metro-labs/core/stations/station-runtime';
+import { accountOf, type Account } from './accounts.js';
+import { listFiles, saveFile } from './attachments.js';
+import { itemOf, LIST_FIELDS, MESSAGE_FIELDS, type GraphMessage } from './format.js';
+import { graph, graphJson, jsonInit, messagePath, odataQuote, queryOf } from './graph.js';
+import { EPOCH } from './outbound.js';
+
+type Args = Record<string, unknown>;
+
+function outlookQuery(args: Args): ReadQuery {
+  const q = readQueryOf('outlook', args);
+  return { ...q, query: q.query.replace(/"/g, '') };
+}
+
+export function filterOf(q: ReadQuery, beforeAt: string): string {
+  const parts = [`receivedDateTime ge ${q.since === '' ? EPOCH : q.since}`];
+  const until = [q.until, beforeAt].filter((s) => s !== '').sort()[0];
+  if (until !== undefined) parts.push(`receivedDateTime lt ${until}`);
+  if (q.threadId !== null) parts.push(`conversationId eq ${odataQuote(q.threadId)}`);
+  if (q.from !== '') parts.push(`from/emailAddress/address eq ${odataQuote(q.from)}`);
+  if (q.unreadOnly) parts.push('isRead eq false');
+  return parts.join(' and ');
+}
+
+function inWindow(at: number, q: ReadQuery, beforeAt: string): boolean {
+  if (q.since !== '' && at < Date.parse(q.since)) return false;
+  if (q.until !== '' && at >= Date.parse(q.until)) return false;
+  return beforeAt === '' || at < Date.parse(beforeAt);
+}
+
+function matches(q: ReadQuery, m: GraphMessage, beforeAt: string): boolean {
+  if (q.threadId !== null && m.conversationId !== q.threadId) return false;
+  if (q.unreadOnly && m.isRead === true) return false;
+  return inWindow(Date.parse(m.receivedDateTime ?? ''), q, beforeAt);
+}
+
+async function receivedAt(acct: Account, messageId: string): Promise<string> {
+  if (messageId === '') return '';
+  const m = await graphJson<GraphMessage>(acct, `${messagePath(messageId)}?$select=receivedDateTime`);
+  return m.receivedDateTime ?? '';
+}
+
+export function searchParams(q: ReadQuery, beforeAt: string): string {
+  if (q.query === '')
+    return queryOf({ $filter: filterOf(q, beforeAt), $orderby: 'receivedDateTime desc', $top: String(q.limit), $select: LIST_FIELDS });
+  const terms = q.from === '' ? q.query : `from:${q.from} ${q.query}`;
+  return queryOf({ $search: `"${terms}"`, $top: String(MAX_LIMIT), $select: LIST_FIELDS });
+}
+
+async function list(id: string, acct: Account, q: ReadQuery): Promise<void> {
+  const beforeAt = await receivedAt(acct, q.before);
+  const body = await graphJson<{ value?: GraphMessage[] }>(acct, `/me/messages?${searchParams(q, beforeAt)}`);
+  const found = (body.value ?? []).filter((m) => q.query === '' || matches(q, m, beforeAt)).slice(0, q.limit);
+  respond(id, {
+    result: {
+      account: acct.id,
+      mode: q.query === '' ? 'filter' : 'search',
+      messages: found.map((m) => mailSummary('outlook', acct.id, itemOf(m))),
+    },
+  });
+}
+
+async function one(id: string, acct: Account, messageId: string): Promise<void> {
+  const m = await graphJson<GraphMessage>(acct, `${messagePath(messageId)}?$select=${MESSAGE_FIELDS}`);
+  const files = m.hasAttachments === true ? await listFiles(acct, m.id) : [];
+  const attachments = [];
+  for (const [index, file] of files.entries()) {
+    const saved = await saveFile(acct, m.id, file, index);
+    attachments.push({ name: file.name, mime: file.mime, kind: file.kind, size: saved.bytes, local_path: saved.path });
+  }
+  if (m.isRead !== true) await graph(acct, messagePath(m.id), jsonInit('PATCH', { isRead: true }));
+  respond(id, { result: { account: acct.id, message: { ...mailFull('outlook', acct.id, itemOf(m)), is_read: true, attachments } } });
+}
+
+export async function read(id: string, args: Args): Promise<void> {
+  const acct = accountOf(args);
+  const messageId = str(args.messageId);
+  if (messageId !== '') {
+    await one(id, acct, messageId);
+    return;
+  }
+  await list(id, acct, outlookQuery(args));
+}

package/runtime/node_modules/@metro-labs/outlook/src/state.ts

@@ -0,0 +1,28 @@
+import { readJson, writeSecure } from '@metro-labs/core/secure-fs';
+import { accountFiles } from '@metro-labs/core/stations/account-files';
+import { seenOf } from '@metro-labs/core/stations/mail';
+import { tokenStateOf, type Tokens } from '@metro-labs/core/stations/oauth';
+
+export interface AccountState extends Tokens {
+  deltaLink: string | null;
+  syncedAt: string | null;
+  seen: string[];
+}
+
+export const stateFiles = accountFiles('OUTLOOK_STATE_DIR', 'outlook-state-');
+
+const nullable = (v: unknown): string | null => (typeof v === 'string' && v !== '' ? v : null);
+
+export function loadState(accountId: string, seed: Partial<Tokens>): AccountState {
+  const saved = readJson<Record<string, unknown>>(stateFiles.path(accountId), {});
+  return {
+    ...tokenStateOf(saved, seed),
+    deltaLink: nullable(saved.deltaLink),
+    syncedAt: nullable(saved.syncedAt),
+    seen: seenOf(saved.seen),
+  };
+}
+
+export function saveState(accountId: string, state: AccountState): void {
+  writeSecure(stateFiles.path(accountId), JSON.stringify(state));
+}

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

@@ -0,0 +1,16 @@
+import type { ReadFilter, Station, Verb } from '@metro-labs/core/stations/types';
+import { stateFiles } from './state.js';
+
+export const outlookStation: Station = {
+  name: 'outlook',
+  hasAccounts: true,
+  hasTrain: true,
+  discoversChannels: true,
+  messageVerbs: new Set<Verb>(['send', 'reply', 'read']),
+  readFilters: new Set<ReadFilter>(['account', 'query', 'from', 'until', 'unread_only', 'message_id']),
+  approvals: false,
+  attachmentMode: 'canonical',
+  forget: stateFiles.forget,
+  forgetExcept: stateFiles.forgetExcept,
+  tools: [],
+};