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

package/runtime/sdk-runner/node_modules/@metro-labs/core/src/stations/attachments.ts

@@ -0,0 +1,195 @@
+export const attachDir = (): string =>
+  process.env.METRO_XMTP_ATTACH_DIR ??
+  `${process.env.HOME}/.cache/metro/messenger-uploads`;
+
+const CACHE_NAME_RE = /^msg_[A-Za-z0-9]{1,16}_\d+\.[A-Za-z0-9]{1,5}$/;
+
+export const resolveCachedAttachment = (name: string): string | null =>
+  CACHE_NAME_RE.test(name) ? `${attachDir()}/${name}` : null;
+
+const MIME_EXT: Record<string, string> = {
+  'image/jpeg': 'jpg',
+  'image/jpg': 'jpg',
+  'image/png': 'png',
+  'image/gif': 'gif',
+  'image/webp': 'webp',
+  'image/heic': 'heic',
+  'audio/mp4': 'm4a',
+  'audio/mpeg': 'mp3',
+  'audio/ogg': 'ogg',
+  'audio/wav': 'wav',
+  'video/mp4': 'mp4',
+  'video/quicktime': 'mov',
+  'video/webm': 'webm',
+  'application/pdf': 'pdf',
+};
+
+const extFromName = (filename: string | undefined): string | undefined => {
+  const ext = filename
+    ?.split('?')[0]
+    ?.split('#')[0]
+    ?.split('.')
+    .pop()
+    ?.toLowerCase();
+  return ext !== undefined && ext.length >= 1 && ext.length <= 5
+    ? ext
+    : undefined;
+};
+
+export const extFromMime = (mime: string | undefined): string | undefined => {
+  if (mime === undefined) return undefined;
+  const mapped = MIME_EXT[mime];
+  if (mapped) return mapped;
+  if (mime.startsWith('image/')) return mime.slice(6).replace('jpeg', 'jpg');
+  return undefined;
+};
+
+const extFor = (
+  filename: string | undefined,
+  mime: string | undefined,
+): string => extFromName(filename) ?? extFromMime(mime) ?? 'bin';
+
+const cacheFileName = (
+  messageId: string,
+  index: number,
+  filename: string | undefined,
+  mime: string | undefined,
+): string => {
+  const safeId =
+    messageId.replace(/[^a-zA-Z0-9]/g, '').slice(0, 16) || 'unknown';
+  return `msg_${safeId}_${index}.${extFor(filename, mime)}`;
+};
+
+export interface SavedAttachment {
+  path: string;
+  mime?: string;
+  name?: string;
+  bytes: number;
+}
+
+export const MAX_ATTACHMENT_BYTES = Number(
+  process.env.METRO_ATTACH_MAX_BYTES ?? 100 * 1024 * 1024,
+);
+
+export function assertAttachmentSize(bytes: number): void {
+  if (bytes > MAX_ATTACHMENT_BYTES)
+    throw new Error(
+      `attachment size ${bytes} exceeds limit of ${MAX_ATTACHMENT_BYTES} bytes`,
+    );
+}
+
+export function assertContentLength(header: string | null | undefined): void {
+  if (header == null) return;
+  const n = Number(header);
+  if (Number.isFinite(n)) assertAttachmentSize(n);
+}
+
+const cachePathFor = async (
+  messageId: string,
+  index: number,
+  meta: { mime?: string; name?: string },
+): Promise<string> => {
+  const { mkdir } = await import('node:fs/promises');
+  const nodePath = await import('node:path');
+  const dir = attachDir();
+  await mkdir(dir, { recursive: true });
+  return nodePath.join(
+    dir,
+    cacheFileName(messageId, index, meta.name, meta.mime),
+  );
+};
+
+export const saveBufferToCache = async (
+  data: Uint8Array,
+  messageId: string,
+  index: number,
+  meta: { mime?: string; name?: string },
+): Promise<SavedAttachment> => {
+  assertAttachmentSize(data.length);
+  const { writeFile } = await import('node:fs/promises');
+  const path = await cachePathFor(messageId, index, meta);
+  await writeFile(path, data);
+  return { path, mime: meta.mime, name: meta.name, bytes: data.length };
+};
+
+export const saveStreamToCache = async (
+  chunks: AsyncIterable<Uint8Array>,
+  messageId: string,
+  index: number,
+  meta: { mime?: string; name?: string },
+): Promise<SavedAttachment> => {
+  const { open, rename, rm } = await import('node:fs/promises');
+  const path = await cachePathFor(messageId, index, meta);
+  const part = `${path}.part`;
+  const handle = await open(part, 'w');
+  let bytes = 0;
+  try {
+    for await (const chunk of chunks) {
+      bytes += chunk.length;
+      assertAttachmentSize(bytes);
+      await handle.write(chunk);
+    }
+  } catch (err) {
+    await handle.close();
+    await rm(part, { force: true });
+    throw err;
+  }
+  await handle.close();
+  await rename(part, path);
+  return { path, mime: meta.mime, name: meta.name, bytes };
+};
+
+export const guessMime = (path: string): string => {
+  const ext = (path.split('.').pop() ?? '').toLowerCase();
+  const map: Record<string, string> = {
+    png: 'image/png',
+    jpg: 'image/jpeg',
+    jpeg: 'image/jpeg',
+    gif: 'image/gif',
+    webp: 'image/webp',
+    heic: 'image/heic',
+    mp4: 'video/mp4',
+    mov: 'video/quicktime',
+    webm: 'video/webm',
+    m4v: 'video/x-m4v',
+    m4a: 'audio/mp4',
+    mp3: 'audio/mpeg',
+    ogg: 'audio/ogg',
+    wav: 'audio/wav',
+    pdf: 'application/pdf',
+  };
+  return map[ext] ?? 'application/octet-stream';
+};
+
+export const isImageMime = (mime: string): boolean =>
+  mime.toLowerCase().startsWith('image/');
+export const isImageExt = (path: string): boolean =>
+  /\.(png|jpe?g|gif|webp|heic|bmp|svg)$/i.test(path);
+
+export const appendFile = async (
+  form: FormData,
+  field: string,
+  path: string,
+  name: string,
+): Promise<void> => {
+  const data = await Bun.file(path).arrayBuffer();
+  form.append(field, new Blob([data]), name);
+};
+
+export const kindOf = (mime: string, path: string): string => {
+  if (isImageMime(mime) || isImageExt(path)) return 'image';
+  if (mime.startsWith('video/')) return 'video';
+  if (mime.startsWith('audio/')) return 'audio';
+  return 'file';
+};
+
+export const toCanonical = (a: {
+  path: string;
+  mime: string;
+  name: string;
+}): Record<string, unknown> => ({
+  kind: kindOf(a.mime, a.path),
+  path: a.path,
+  name: a.name,
+  mime: a.mime,
+});

package/runtime/sdk-runner/node_modules/@metro-labs/core/src/stations/mail-text.ts

@@ -0,0 +1,72 @@
+export const MAX_TEXT_CHARS = 20_000;
+
+const ENTITIES: Record<string, string> = {
+  amp: '&',
+  lt: '<',
+  gt: '>',
+  quot: '"',
+  apos: "'",
+  nbsp: ' ',
+  ndash: '-',
+  mdash: '-',
+  hellip: '...',
+  rsquo: "'",
+  lsquo: "'",
+  rdquo: '"',
+  ldquo: '"',
+};
+
+function codePoint(n: number): string {
+  return Number.isInteger(n) && n > 0 && n <= 0x10ffff ? String.fromCodePoint(n) : '';
+}
+
+export function decodeEntities(text: string): string {
+  return text.replace(/&(#x[0-9a-f]+|#\d+|[a-z]+);/gi, (whole, name: string) => {
+    if (name.startsWith('#x') || name.startsWith('#X')) return codePoint(parseInt(name.slice(2), 16));
+    if (name.startsWith('#')) return codePoint(Number(name.slice(1)));
+    return ENTITIES[name.toLowerCase()] ?? whole;
+  });
+}
+
+export function htmlToText(html: string): string {
+  const text = html
+    .replace(/<!--[\s\S]*?-->/g, '')
+    .replace(/<(head|style|script|title)\b[\s\S]*?<\/\1\s*>/gi, '')
+    .replace(/<br\s*\/?>/gi, '\n')
+    .replace(/<li\b[^>]*>/gi, '\n- ')
+    .replace(/<\/(p|div|tr|h[1-6]|blockquote|table|ul|ol)\s*>/gi, '\n')
+    .replace(/<(p|div|tr|h[1-6]|blockquote|table)\b[^>]*>/gi, '\n')
+    .replace(/<\/t[dh]\s*>/gi, ' ')
+    .replace(/<[^>]*>/g, '');
+  return tidy(decodeEntities(text));
+}
+
+export function tidy(text: string): string {
+  return text
+    .replace(/\r\n?/g, '\n')
+    .replace(/[ \t ]+/g, ' ')
+    .split('\n')
+    .map((l) => l.trim())
+    .join('\n')
+    .replace(/\n{3,}/g, '\n\n')
+    .trim();
+}
+
+export function capText(text: string, max = MAX_TEXT_CHARS): string {
+  if (text.length <= max) return text;
+  return `${text.slice(0, max)}\n[... ${String(text.length - max)} more characters]`;
+}
+
+export function bodyText(body: { contentType?: unknown; content?: unknown } | undefined): string {
+  const content = typeof body?.content === 'string' ? body.content : '';
+  return String(body?.contentType).toLowerCase() === 'html' ? htmlToText(content) : tidy(content);
+}
+
+export function escapeHtml(text: string): string {
+  return text
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/\r?\n/g, '<br>');
+}

package/runtime/sdk-runner/node_modules/@metro-labs/core/src/stations/mail-trust.ts

@@ -0,0 +1,29 @@
+export interface MailHeader {
+  name?: string;
+  value?: string;
+}
+
+export type Screened = { skip: string } | { verified: boolean };
+
+const AUTOMATED_LOCAL = /^(no-?reply|do-?not-?reply|donotreply|mailer-daemon|notifications?)([+._-].*)?$/i;
+const BULK = new Set(['bulk', 'list', 'junk']);
+
+export const headerValues = (headers: MailHeader[], name: string): string[] =>
+  headers.filter((h) => (h.name ?? '').toLowerCase() === name).map((h) => (h.value ?? '').trim());
+
+export const firstHeader = (headers: MailHeader[], name: string): string | undefined => headerValues(headers, name)[0];
+
+export function automatedBySender(address: string): string | null {
+  const local = address.split('@')[0] ?? '';
+  return AUTOMATED_LOCAL.test(local) ? `sender ${address}` : null;
+}
+
+export function automatedByHeaders(headers: MailHeader[]): string | null {
+  if (firstHeader(headers, 'list-unsubscribe') !== undefined) return 'List-Unsubscribe';
+  const auto = firstHeader(headers, 'auto-submitted');
+  if (auto !== undefined && auto.toLowerCase() !== 'no') return `Auto-Submitted: ${auto}`;
+  const precedence = (firstHeader(headers, 'precedence') ?? '').toLowerCase();
+  return BULK.has(precedence) ? `Precedence: ${precedence}` : null;
+}
+
+export const domainOf = (address: string): string => (address.split('@')[1] ?? '').toLowerCase();

package/runtime/sdk-runner/node_modules/@metro-labs/core/src/stations/mail.ts

@@ -0,0 +1,212 @@
+import { mintId } from '../ids.js';
+import { Line } from '../lines.js';
+import { TrainError } from '../train-error.js';
+import { capText } from './mail-text.js';
+
+export type MailStation = 'outlook' | 'gmail';
+
+type Args = Record<string, unknown>;
+
+export interface MailItem {
+  id: string;
+  threadId: string;
+  subject: string;
+  from: string;
+  fromName: string;
+  to: string[];
+  cc: string[];
+  date: string | null;
+  preview: string;
+  text: string;
+  hasAttachments: boolean;
+  isRead: boolean;
+  internetMessageId: string | null;
+}
+
+export interface AttachmentMeta {
+  kind: string;
+  name: string;
+  mime: string;
+  size?: number;
+}
+
+export interface OutgoingFile {
+  path: string;
+  mime: string;
+  name: string;
+}
+
+export interface ReadQuery {
+  threadId: string | null;
+  query: string;
+  from: string;
+  since: string;
+  until: string;
+  before: string;
+  unreadOnly: boolean;
+  limit: number;
+}
+
+export const DEFAULT_LIMIT = 20;
+export const MAX_LIMIT = 50;
+const SEEN_MAX = 500;
+const SUBJECT_MAX = 255;
+const ADDRESS_RE = /^[^@\s/]+@[^@\s/]+\.[^@\s/]+$/;
+
+export interface MailService {
+  station: MailStation;
+  company: string;
+  product: string;
+  api: string;
+  apiCode: string;
+}
+
+export function refusalOf(s: MailService, status: number, detail: string): TrainError {
+  const refuse = (code: string, text: string, retryable = false): TrainError => new TrainError(`${s.station}_${code}`, text, { retryable });
+  if (status === 401) return refuse('signed_out', `${s.company} refused this mailbox's sign-in (${detail}); connect ${s.product} again from the page`);
+  if (status === 403) return refuse('forbidden', `${s.company} does not let Metro do that on this mailbox (${detail})`);
+  if (status === 404) return refuse('not_found', `${s.product} has no such message or conversation (${detail})`);
+  if (status === 413) return refuse('too_large', `${s.product} refused the size of that request (${detail})`);
+  if (status === 429) return refuse('throttled', `${s.company} asked Metro to slow down (${detail}); try again in a minute`, true);
+  return refuse(s.apiCode, `${s.api} answered ${String(status)} (${detail})`, status >= 500);
+}
+
+export const str = (v: unknown): string => (typeof v === 'string' ? v.trim() : '');
+
+const encodeResource = (id: string): string => id.replace(/%/g, '%25').replace(/\//g, '%2F').replace(/\+/g, '%2B');
+
+export const mailLine = (station: MailStation, accountId: string, threadId: string): string =>
+  `metro://${station}/${accountId}/${encodeResource(threadId)}`;
+
+const mailUser = (station: MailStation, accountId: string, address: string): string =>
+  `metro://${station}/${accountId}/user/${address.toLowerCase()}`;
+
+export function threadOfLine(station: MailStation, line: string): { accountId: string; threadId: string } | null {
+  const parsed = Line.parseMail(line, station);
+  if (parsed === null) return null;
+  try {
+    return { accountId: parsed.accountId, threadId: decodeURIComponent(parsed.resource) };
+  } catch {
+    return null;
+  }
+}
+
+const isPrivateTo = (m: MailItem, self: string): boolean => m.to.length === 1 && m.to[0] === self && m.cc.length === 0;
+
+export function mailEnvelope(station: MailStation, accountId: string, self: string, m: MailItem, attachments: AttachmentMeta[], verified: boolean): Record<string, unknown> {
+  const body = capText(m.text);
+  return {
+    id: mintId(),
+    ts: m.date ?? new Date().toISOString(),
+    station,
+    line: mailLine(station, accountId, m.threadId),
+    line_name: m.subject === '' ? '(no subject)' : m.subject,
+    from: mailUser(station, accountId, m.from === '' ? 'unknown' : m.from),
+    from_name: m.fromName || m.from,
+    from_display_name: m.fromName || undefined,
+    message_id: m.id,
+    text: m.subject === '' ? body : `Subject: ${m.subject}\n\n${body}`,
+    is_private: isPrivateTo(m, self),
+    sender_verified: verified,
+    payload: {
+      from: m.from,
+      to: m.to,
+      cc: m.cc,
+      subject: m.subject,
+      internetMessageId: m.internetMessageId,
+      ...(attachments.length === 0 ? {} : { attachments }),
+    },
+  };
+}
+
+const heading = (station: MailStation, accountId: string, m: MailItem): Record<string, unknown> => ({
+  message_id: m.id,
+  line: mailLine(station, accountId, m.threadId),
+  from: m.from,
+  from_name: m.fromName,
+  date: m.date,
+  title: m.subject,
+});
+
+export const mailSummary = (station: MailStation, accountId: string, m: MailItem): Record<string, unknown> => ({
+  ...heading(station, accountId, m),
+  text_preview: m.preview,
+  has_attachments: m.hasAttachments,
+  is_read: m.isRead,
+});
+
+export const mailFull = (station: MailStation, accountId: string, m: MailItem): Record<string, unknown> => ({
+  ...heading(station, accountId, m),
+  has_attachments: m.hasAttachments,
+  is_read: m.isRead,
+  to: m.to,
+  cc: m.cc,
+  text: capText(m.text),
+});
+
+export const isAddress = (target: string): boolean => target.includes('@');
+
+export const isEmailAddress = (value: string): boolean => ADDRESS_RE.test(value);
+
+export function checkAddress(station: MailStation, to: string): void {
+  if (!isEmailAddress(to)) throw new TrainError(`${station}_bad_address`, `not an email address: ${to}`, { retryable: false });
+}
+
+export function subjectOf(station: MailStation, subject: string, text: string): string {
+  const chosen = subject !== '' ? subject : (text.split('\n').find((l) => l.trim() !== '') ?? '').trim();
+  if (chosen === '') throw new TrainError(`${station}_subject_required`, 'a new email needs a subject or some text', { retryable: false });
+  return chosen.length > SUBJECT_MAX ? `${chosen.slice(0, SUBJECT_MAX - 3)}...` : chosen;
+}
+
+export const filesOf = (raw: unknown): OutgoingFile[] =>
+  (Array.isArray(raw) ? raw : [])
+    .map((a) => (a ?? {}) as Record<string, unknown>)
+    .filter((a) => typeof a.path === 'string' && a.path !== '')
+    .map((a) => ({
+      path: String(a.path),
+      mime: typeof a.mime === 'string' && a.mime !== '' ? a.mime : 'application/octet-stream',
+      name: typeof a.name === 'string' && a.name !== '' ? a.name : 'file',
+    }));
+
+function isoOf(station: MailStation, raw: string, field: string): string {
+  if (raw === '') return '';
+  const at = Date.parse(raw);
+  if (Number.isNaN(at)) throw new TrainError(`${station}_bad_date`, `${field} must be a date, for example 2026-09-24 or 2026-09-24T10:00:00Z`, { retryable: false });
+  return new Date(at).toISOString();
+}
+
+export function readQueryOf(station: MailStation, args: Args): ReadQuery {
+  const line = str(args.line);
+  const thread = line === '' ? null : threadOfLine(station, line);
+  if (line !== '' && thread === null) throw new TrainError(`${station}_bad_line`, `not a valid ${station} line: ${line}`, { retryable: false });
+  return {
+    threadId: thread?.threadId ?? null,
+    query: str(args.query),
+    from: str(args.from).toLowerCase(),
+    since: isoOf(station, str(args.since), 'since'),
+    until: isoOf(station, str(args.until), 'until'),
+    before: str(args.before),
+    unreadOnly: args.unreadOnly === true,
+    limit: typeof args.limit === 'number' && args.limit > 0 ? Math.min(Math.floor(args.limit), MAX_LIMIT) : DEFAULT_LIMIT,
+  };
+}
+
+export const seenOf = (raw: unknown): string[] => (Array.isArray(raw) ? raw.filter((s): s is string => typeof s === 'string') : []);
+
+export function noteSeen(seen: string[], messageId: string): void {
+  seen.push(messageId);
+  if (seen.length > SEEN_MAX) seen.splice(0, seen.length - SEEN_MAX);
+}
+
+export function pollForever(tag: string, once: () => Promise<unknown>, intervalMs: number): void {
+  const tick = (): void => {
+    once()
+      .catch((err: unknown) => {
+        process.stderr.write(`${tag} mail check failed: ${err instanceof Error ? err.message : String(err)}\n`);
+      })
+      .finally(() => {
+        setTimeout(tick, intervalMs);
+      });
+  };
+  tick();
+}

package/runtime/sdk-runner/node_modules/@metro-labs/core/src/stations/messaging-normalize.ts

@@ -0,0 +1,16 @@
+type Args = Record<string, unknown>;
+
+export interface Normalized {
+  action: string;
+  args: Args;
+}
+
+export type Normalize = (action: string, args: Args) => Normalized;
+
+export const messagingAliases =
+  (removal: Args = { emoji: '' }): Normalize =>
+  (action, args) => {
+    if (action === 'reply') return { action: 'send', args };
+    if (action === 'unreact') return { action: 'react', args: { ...args, ...removal } };
+    return { action, args };
+  };

package/runtime/sdk-runner/node_modules/@metro-labs/core/src/stations/oauth.ts

@@ -0,0 +1,126 @@
+import { createHash, randomBytes } from 'node:crypto';
+
+export class SignInError extends Error {}
+
+export type FetchLike = (input: string, init?: RequestInit) => Promise<Response>;
+
+export type OAuthBody = Record<string, unknown>;
+
+export interface Tokens {
+  accessToken: string;
+  refreshToken: string;
+  expiresAt: number;
+}
+
+export interface Pkce {
+  verifier: string;
+  challenge: string;
+}
+
+const RENEW_BEFORE_MS = 5 * 60_000;
+const MAILBOX_RE = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+
+const text = (v: unknown): string => (typeof v === 'string' ? v : '');
+
+export const seconds = (v: unknown, fallback: number): number =>
+  typeof v === 'number' && Number.isFinite(v) && v >= 0 ? v : fallback;
+
+export function envValue(name: string, fallback: string): string {
+  const value = (process.env[name] ?? '').trim();
+  return value === '' ? fallback : value;
+}
+
+export const envUrl = (name: string, fallback: string): string => envValue(name, fallback).replace(/\/+$/, '');
+
+export function pkcePair(verifier = randomBytes(32).toString('base64url')): Pkce {
+  return { verifier, challenge: createHash('sha256').update(verifier).digest('base64url') };
+}
+
+export const newState = (): string => randomBytes(24).toString('base64url');
+
+export function parseMailbox(value: unknown): string | null {
+  const mailbox = (typeof value === 'string' ? value.trim() : '').toLowerCase();
+  if (mailbox === '') return null;
+  if (!MAILBOX_RE.test(mailbox))
+    throw new SignInError('Type the whole address of the mailbox, like andy@company.com, or leave it blank.');
+  return mailbox;
+}
+
+export async function postForm(url: string, fields: Record<string, string>, fetchImpl: FetchLike, provider: string): Promise<{ status: number; body: OAuthBody }> {
+  let res: Response;
+  try {
+    res = await fetchImpl(url, {
+      method: 'POST',
+      headers: { 'content-type': 'application/x-www-form-urlencoded', accept: 'application/json' },
+      body: new URLSearchParams(fields).toString(),
+    });
+  } catch (err) {
+    throw new SignInError(`Metro could not reach ${provider}: ${err instanceof Error ? err.message : String(err)}`);
+  }
+  const raw: unknown = await res.json().catch(() => ({}));
+  return { status: res.status, body: typeof raw === 'object' && raw !== null ? (raw as OAuthBody) : {} };
+}
+
+export function tokensOf(body: OAuthBody, now: number, provider: string, previous?: string): Tokens {
+  const accessToken = text(body.access_token);
+  const refreshToken = text(body.refresh_token) || (previous ?? '');
+  if (accessToken === '' || refreshToken === '') throw new SignInError(`${provider} answered without the tokens Metro needs.`);
+  return { accessToken, refreshToken, expiresAt: now + seconds(body.expires_in, 3600) * 1000 };
+}
+
+export function tokenStateOf(saved: OAuthBody, seed: Partial<Tokens>): Tokens {
+  const fromFile = text(saved.refreshToken) !== '';
+  return {
+    refreshToken: fromFile ? text(saved.refreshToken) : text(seed.refreshToken),
+    accessToken: fromFile ? text(saved.accessToken) : text(seed.accessToken),
+    expiresAt: fromFile ? Number(saved.expiresAt) || 0 : Number(seed.expiresAt) || 0,
+  };
+}
+
+export class TokenKeeper {
+  private refreshing: Promise<string> | null = null;
+
+  constructor(
+    private readonly state: Tokens,
+    private readonly renewWith: (refreshToken: string) => Promise<Tokens>,
+    private readonly renewed: () => void,
+  ) {}
+
+  token(force = false): Promise<string> {
+    const fresh = this.state.accessToken !== '' && this.state.expiresAt - RENEW_BEFORE_MS > Date.now();
+    if (fresh && !force) return Promise.resolve(this.state.accessToken);
+    this.refreshing ??= this.renew().finally(() => {
+      this.refreshing = null;
+    });
+    return this.refreshing;
+  }
+
+  private async renew(): Promise<string> {
+    Object.assign(this.state, await this.renewWith(this.state.refreshToken));
+    this.renewed();
+    return this.state.accessToken;
+  }
+}
+
+export interface BrowserFlow<R> {
+  authorize: (challenge: string, state: string) => string;
+  redeem: (code: string, verifier: string) => Promise<R>;
+}
+
+export class BrowserSignIn<R> {
+  readonly state = newState();
+  readonly authorizeUrl: string;
+  private readonly pkce = pkcePair();
+  private used = false;
+
+  constructor(private readonly flow: BrowserFlow<R>) {
+    this.authorizeUrl = flow.authorize(this.pkce.challenge, this.state);
+  }
+
+  async finish(code: string, state: string): Promise<R> {
+    if (state !== this.state) throw new SignInError('This sign-in link belongs to another attempt. Start again from the Channels page.');
+    if (this.used) throw new SignInError('This sign-in was already used. Start again from the Channels page.');
+    this.used = true;
+    return this.flow.redeem(code, this.pkce.verifier);
+  }
+}