@groundmail/groundhog 0.0.0-stage → 0.1.1

package/dist/extract.js

@@ -0,0 +1,116 @@
+/**
+ * Pull the one-time code and the links out of an email, so a test (or an agent)
+ * can finish a sign-in without reading the email itself.
+ */
+const ENTITIES = { amp: '&', lt: '<', gt: '>', quot: '"', apos: "'", nbsp: ' ', '#39': "'" };
+export function decodeEntities(value) {
+    return value.replace(/&(#x[0-9a-f]+|#\d+|[a-z]+\d*);/gi, (match, entity) => {
+        const lower = entity.toLowerCase();
+        if (lower.startsWith('#x'))
+            return String.fromCodePoint(parseInt(lower.slice(2), 16));
+        if (lower.startsWith('#'))
+            return String.fromCodePoint(parseInt(lower.slice(1), 10));
+        return ENTITIES[lower] ?? match;
+    });
+}
+/** A rough plain-text rendering of HTML, good enough for finding codes. */
+export function htmlToText(html) {
+    return decodeEntities(html
+        .replace(/<(script|style|head)[\s\S]*?<\/\1>/gi, ' ')
+        .replace(/<br\s*\/?>/gi, '\n')
+        .replace(/<\/(p|div|tr|h[1-6]|li|table)>/gi, '\n')
+        .replace(/<[^>]+>/g, ' '))
+        .replace(/[ \t\f\v]+/g, ' ')
+        .replace(/\n\s*\n+/g, '\n')
+        .trim();
+}
+function toParts(input) {
+    if (typeof input === 'string') {
+        const looksHtml = /<[a-z][\s\S]*>/i.test(input);
+        return { html: looksHtml ? input : '', text: looksHtml ? htmlToText(input) : input, subject: '' };
+    }
+    const html = input.html ?? '';
+    const text = input.text?.trim() ? input.text : html ? htmlToText(html) : '';
+    return { html, text, subject: input.subject ?? '' };
+}
+const URL_IN_TEXT = /https?:\/\/[^\s<>"'`)\]]+/gi;
+function cleanUrl(url) {
+    return decodeEntities(url.trim()).replace(/[.,;:!?]+$/, '');
+}
+/** Every http(s) link in the email, in the order it appears, without duplicates. */
+export function extractLinks(input) {
+    const { html, text } = toParts(input);
+    const seen = new Set();
+    const out = [];
+    const add = (url) => {
+        const clean = cleanUrl(url);
+        if (!/^https?:\/\//i.test(clean) || seen.has(clean))
+            return;
+        seen.add(clean);
+        out.push(clean);
+    };
+    if (html) {
+        for (const match of html.matchAll(/<a\b[^>]*?\bhref\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s>]+))/gi)) {
+            add(match[1] ?? match[2] ?? match[3] ?? '');
+        }
+    }
+    for (const match of (text || '').matchAll(URL_IN_TEXT))
+        add(match[0]);
+    return out;
+}
+const CODE_WORDS = /(code|otp|one[- ]time|passcode|pin|verification|verify|confirm|token|sign[- ]?in|log[- ]?in|2fa|mfa)/i;
+/**
+ * The one-time code in the email: digits (4–8, also "123 456" / "123-456"), or a short
+ * letters-and-digits code next to a word like "code". `null` when nothing looks like one.
+ */
+export function extractCode(input) {
+    const { text, subject } = toParts(input);
+    const haystacks = [subject, text].filter(Boolean);
+    let best = null;
+    let order = 0;
+    for (const source of haystacks) {
+        const scrubbed = source.replace(URL_IN_TEXT, ' ').replace(/#[0-9a-f]{3,8}\b/gi, ' ');
+        const candidates = [];
+        for (const match of scrubbed.matchAll(/(?<![\w.$€£-])(\d{3}[ -]\d{3}|\d{4,8})(?![\w%-]|[.,]\d)/g)) {
+            candidates.push({ value: match[1], index: match.index ?? 0, alnum: false });
+        }
+        for (const match of scrubbed.matchAll(/(?<![\w-])([A-Z0-9]{5,8})(?![\w-])/g)) {
+            const value = match[1];
+            if (/\d/.test(value) && /[A-Z]/.test(value))
+                candidates.push({ value, index: match.index ?? 0, alnum: true });
+        }
+        for (const candidate of candidates) {
+            const value = candidate.value.replace(/[ -]/g, '');
+            const before = scrubbed.slice(Math.max(0, candidate.index - 60), candidate.index);
+            const near = CODE_WORDS.test(before);
+            let score = near ? 10 : 0;
+            if (candidate.alnum && !near)
+                continue;
+            if (!candidate.alnum) {
+                if (value.length === 6)
+                    score += 4;
+                else if (value.length === 4 || value.length === 8)
+                    score += 1;
+                if (value.length === 4 && /^(19|20)\d\d$/.test(value))
+                    score -= 8;
+                if (/^0+$/.test(value))
+                    score -= 8;
+            }
+            if (/[$€£]\s*$/.test(before) || /(#|no\.?|number|order|invoice|receipt)\s*$/i.test(before))
+                score -= 6;
+            order += 1;
+            if (score <= 0)
+                continue;
+            if (!best || score > best.score)
+                best = { value, score, order };
+        }
+    }
+    return best && best.score > 0 ? best.value : null;
+}
+/** The first link whose URL contains `contains` (or the first link that isn't an unsubscribe/asset link). */
+export function pickLink(links, contains) {
+    if (contains)
+        return links.find((link) => link.includes(contains)) ?? null;
+    const useful = links.filter((link) => !/unsubscribe|\.(png|jpe?g|gif|svg|css)(\?|$)|list-manage|privacy|terms/i.test(link));
+    return useful[0] ?? links[0] ?? null;
+}

package/dist/faults.d.ts

@@ -0,0 +1,24 @@
+import { EventEmitter } from 'node:events';
+import { type FaultKind } from './types.js';
+export type FaultState = {
+    kind: FaultKind | null;
+    /** Sends left that will fail. 0 when failure mode is off. */
+    remaining: number;
+    /** How long a `timeout` fault holds the connection before dropping it. */
+    timeoutMs: number;
+};
+export declare const FAULT_LABELS: Record<FaultKind, {
+    short: string;
+    label: string;
+}>;
+/** `429`, `rate_limit`, `5xx`, `503`, `timeout`… → a fault kind. */
+export declare function parseFaultKind(value: unknown): FaultKind | null;
+export declare class Faults extends EventEmitter {
+    private state;
+    constructor(timeoutMs?: number);
+    get(): FaultState;
+    set(kind: FaultKind, next?: number, timeoutMs?: number): FaultState;
+    clear(): FaultState;
+    /** Take one fault for this send, if failure mode is on. */
+    take(): FaultKind | null;
+}

package/dist/faults.js

@@ -0,0 +1,64 @@
+import { EventEmitter } from 'node:events';
+import { FAULT_KINDS } from './types.js';
+export const FAULT_LABELS = {
+    rate_limit: { short: '429', label: 'Rate limited' },
+    invalid_recipient: { short: '422', label: 'Invalid recipient' },
+    unauthorized: { short: '401', label: 'Bad API key' },
+    outage: { short: '5xx', label: 'Provider outage' },
+    timeout: { short: 'T/O', label: 'Timeout' },
+};
+/** `429`, `rate_limit`, `5xx`, `503`, `timeout`… → a fault kind. */
+export function parseFaultKind(value) {
+    const v = String(value ?? '').trim().toLowerCase();
+    if (!v)
+        return null;
+    if (FAULT_KINDS.includes(v))
+        return v;
+    if (v === '429' || v === 'rate-limit' || v === 'ratelimit' || v === 'rate_limited')
+        return 'rate_limit';
+    if (v === '422' || v === '400' || v === 'invalid-recipient' || v === 'bad_recipient')
+        return 'invalid_recipient';
+    if (v === '401' || v === '403' || v === 'bad_key' || v === 'auth')
+        return 'unauthorized';
+    if (v === '5xx' || /^5\d\d$/.test(v) || v === 'down')
+        return 'outage';
+    if (v === 't/o' || v === 'timeout' || v === 'timed_out')
+        return 'timeout';
+    return null;
+}
+export class Faults extends EventEmitter {
+    state;
+    constructor(timeoutMs = 30_000) {
+        super();
+        this.state = { kind: null, remaining: 0, timeoutMs };
+    }
+    get() {
+        return { ...this.state };
+    }
+    set(kind, next = 1, timeoutMs) {
+        this.state = {
+            kind: next > 0 ? kind : null,
+            remaining: Math.max(0, Math.floor(next)),
+            timeoutMs: timeoutMs ?? this.state.timeoutMs,
+        };
+        this.emit('change', this.get());
+        return this.get();
+    }
+    clear() {
+        this.state = { ...this.state, kind: null, remaining: 0 };
+        this.emit('change', this.get());
+        return this.get();
+    }
+    /** Take one fault for this send, if failure mode is on. */
+    take() {
+        if (!this.state.kind || this.state.remaining <= 0)
+            return null;
+        const kind = this.state.kind;
+        this.state.remaining -= 1;
+        if (this.state.remaining <= 0)
+            this.state.kind = null;
+        this.emit('change', this.get());
+        this.emit('fault', kind);
+        return kind;
+    }
+}

package/dist/groundmail-account.d.ts

@@ -0,0 +1,50 @@
+/**
+ * "Send to my real inbox": a one-time Groundmail sign-in (OAuth device flow, like
+ * `groundmail login`), then copies of caught emails go out through Groundmail's
+ * sandbox sender, which only delivers to the account's own address.
+ */
+import { EventEmitter } from 'node:events';
+import type { StoredEmail } from './types.js';
+export declare const OAUTH_CLIENT_ID = "groundhog";
+export declare function withUtm(url: string, campaign: string): string;
+export type AccountStatus = {
+    connected: boolean;
+    email: string | null;
+    workspace: string | null;
+    pending: {
+        userCode: string;
+        url: string;
+        expiresAt: string;
+    } | null;
+    error: string | null;
+};
+export declare function configDir(env?: NodeJS.ProcessEnv): string;
+export declare class GroundmailAccount extends EventEmitter {
+    private readonly options;
+    private pending;
+    private lastError;
+    private polling;
+    constructor(options?: {
+        apiUrl?: string;
+        from?: string;
+        env?: NodeJS.ProcessEnv;
+        openBrowser?: (url: string) => void;
+    });
+    get apiUrl(): string;
+    get from(): string;
+    private get file();
+    private load;
+    private save;
+    status(): AccountStatus;
+    /** Start the browser sign-in. Resolves with the link and code; finishes in the background. */
+    connect(): Promise<AccountStatus>;
+    private poll;
+    private storeTokens;
+    private accessToken;
+    disconnect(): Promise<AccountStatus>;
+    /** Send a copy of a caught email through Groundmail. */
+    sendCopy(email: StoredEmail, to?: string): Promise<{
+        id: string;
+        to: string;
+    }>;
+}

package/dist/groundmail-account.js

@@ -0,0 +1,233 @@
+/**
+ * "Send to my real inbox": a one-time Groundmail sign-in (OAuth device flow, like
+ * `groundmail login`), then copies of caught emails go out through Groundmail's
+ * sandbox sender, which only delivers to the account's own address.
+ */
+import { EventEmitter } from 'node:events';
+import { chmodSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { homedir, hostname } from 'node:os';
+import { join } from 'node:path';
+export const OAUTH_CLIENT_ID = 'groundhog';
+const DEVICE_GRANT = 'urn:ietf:params:oauth:grant-type:device_code';
+const UTM = 'utm_source=groundhog&utm_medium=app';
+export function withUtm(url, campaign) {
+    return `${url}${url.includes('?') ? '&' : '?'}${UTM}&utm_campaign=${campaign}`;
+}
+export function configDir(env = process.env) {
+    if (env.GROUNDHOG_CONFIG_DIR)
+        return env.GROUNDHOG_CONFIG_DIR;
+    const base = env.XDG_CONFIG_HOME || join(homedir(), '.config');
+    return join(base, 'groundhog');
+}
+async function post(url, body, token) {
+    const response = await fetch(url, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json', Accept: 'application/json', 'User-Agent': 'groundhog', ...(token ? { Authorization: `Bearer ${token}` } : {}) },
+        body: JSON.stringify(body),
+        signal: AbortSignal.timeout(20_000),
+    });
+    const json = (await response.json().catch(() => ({})));
+    return { status: response.status, body: json };
+}
+function apiError(body, fallback) {
+    const error = body.error;
+    if (error && typeof error === 'object') {
+        const e = error;
+        return [e.message, e.hint].filter(Boolean).join(' ') || fallback;
+    }
+    if (typeof body.error_description === 'string')
+        return body.error_description;
+    if (typeof error === 'string')
+        return [error, body.hint].filter(Boolean).join(' ');
+    return fallback;
+}
+export class GroundmailAccount extends EventEmitter {
+    options;
+    pending = null;
+    lastError = null;
+    polling = false;
+    constructor(options = {}) {
+        super();
+        this.options = options;
+    }
+    get apiUrl() {
+        return (this.options.apiUrl || this.options.env?.GROUNDMAIL_API_URL || 'https://api.groundmail.dev').replace(/\/+$/, '');
+    }
+    get from() {
+        return this.options.from || 'Groundhog <noreply@mail.groundmail.dev>';
+    }
+    get file() {
+        return join(configDir(this.options.env), 'groundmail.json');
+    }
+    load() {
+        try {
+            if (!existsSync(this.file))
+                return null;
+            const saved = JSON.parse(readFileSync(this.file, 'utf8'));
+            return saved.apiUrl === this.apiUrl ? saved : null;
+        }
+        catch {
+            return null;
+        }
+    }
+    save(saved) {
+        mkdirSync(configDir(this.options.env), { recursive: true });
+        writeFileSync(this.file, JSON.stringify(saved, null, 2), { mode: 0o600 });
+        try {
+            chmodSync(this.file, 0o600);
+        }
+        catch {
+            // Best effort on filesystems without modes.
+        }
+    }
+    status() {
+        const saved = this.load();
+        return {
+            connected: Boolean(saved),
+            email: saved?.email ?? null,
+            workspace: saved?.workspace ?? null,
+            pending: this.pending ? { userCode: this.pending.userCode, url: this.pending.url, expiresAt: new Date(this.pending.expiresAt).toISOString() } : null,
+            error: this.lastError,
+        };
+    }
+    /** Start the browser sign-in. Resolves with the link and code; finishes in the background. */
+    async connect() {
+        if (this.load())
+            return this.status();
+        if (this.pending && this.pending.expiresAt > Date.now() + 5000)
+            return this.status();
+        this.lastError = null;
+        const start = await post(`${this.apiUrl}/oauth/device_authorization`, {
+            client_id: OAUTH_CLIENT_ID,
+            scope: 'emails:send account:read',
+            device_name: `Groundhog on ${hostname().slice(0, 60) || 'this computer'}`,
+        });
+        const body = start.body;
+        const url = typeof body.verification_uri_complete === 'string' ? body.verification_uri_complete : body.verification_uri;
+        if (start.status >= 400 || typeof body.device_code !== 'string' || typeof url !== 'string') {
+            this.lastError = apiError(body, 'Could not start the Groundmail sign-in.');
+            throw new Error(this.lastError);
+        }
+        this.pending = {
+            deviceCode: body.device_code,
+            userCode: String(body.user_code ?? ''),
+            url: withUtm(url, 'real_inbox'),
+            interval: Math.max(1, Number(body.interval) || 5),
+            expiresAt: Date.now() + (Number(body.expires_in) || 600) * 1000,
+        };
+        this.options.openBrowser?.(this.pending.url);
+        void this.poll();
+        this.emit('change', this.status());
+        return this.status();
+    }
+    async poll() {
+        if (this.polling)
+            return;
+        this.polling = true;
+        try {
+            while (this.pending && this.pending.expiresAt > Date.now()) {
+                await new Promise((resolve) => setTimeout(resolve, this.pending.interval * 1000).unref?.());
+                const pending = this.pending;
+                if (!pending)
+                    break;
+                let result;
+                try {
+                    result = await post(`${this.apiUrl}/oauth/token`, { grant_type: DEVICE_GRANT, device_code: pending.deviceCode, client_id: OAUTH_CLIENT_ID });
+                }
+                catch {
+                    continue;
+                }
+                if (result.status < 300 && typeof result.body.access_token === 'string') {
+                    this.storeTokens(result.body);
+                    this.pending = null;
+                    this.emit('change', this.status());
+                    return;
+                }
+                const code = String(result.body.error ?? '');
+                if (code === 'authorization_pending')
+                    continue;
+                if (code === 'slow_down') {
+                    pending.interval += 5;
+                    continue;
+                }
+                this.lastError = code === 'access_denied' ? 'The sign-in was canceled.' : apiError(result.body, 'The sign-in expired. Try again.');
+                this.pending = null;
+                this.emit('change', this.status());
+                return;
+            }
+            if (this.pending) {
+                this.pending = null;
+                this.lastError = 'The sign-in expired. Try again.';
+                this.emit('change', this.status());
+            }
+        }
+        finally {
+            this.polling = false;
+        }
+    }
+    storeTokens(body, previous) {
+        const user = (body.user ?? {});
+        const workspace = (body.workspace ?? {});
+        const saved = {
+            apiUrl: this.apiUrl,
+            accessToken: String(body.access_token),
+            accessTokenExpiresAt: Date.now() + (Number(body.expires_in) || 3600) * 1000,
+            refreshToken: typeof body.refresh_token === 'string' ? body.refresh_token : (previous?.refreshToken ?? ''),
+            email: user.email ?? previous?.email ?? null,
+            workspace: workspace.name ?? previous?.workspace ?? null,
+            savedAt: new Date().toISOString(),
+        };
+        this.save(saved);
+        return saved;
+    }
+    async accessToken() {
+        const saved = this.load();
+        if (!saved)
+            throw new Error('Connect Groundmail first.');
+        if (saved.accessTokenExpiresAt > Date.now() + 60_000)
+            return saved.accessToken;
+        const result = await post(`${this.apiUrl}/oauth/token`, { grant_type: 'refresh_token', refresh_token: saved.refreshToken, client_id: OAUTH_CLIENT_ID });
+        if (result.status >= 300 || typeof result.body.access_token !== 'string') {
+            if (result.status === 400 || result.status === 401)
+                rmSync(this.file, { force: true });
+            throw new Error(apiError(result.body, 'The Groundmail sign-in expired. Connect again.'));
+        }
+        return this.storeTokens(result.body, saved).accessToken;
+    }
+    async disconnect() {
+        const saved = this.load();
+        this.pending = null;
+        if (saved?.refreshToken) {
+            await post(`${this.apiUrl}/oauth/revoke`, { token: saved.refreshToken, token_type_hint: 'refresh_token', client_id: OAUTH_CLIENT_ID }).catch(() => null);
+        }
+        rmSync(this.file, { force: true });
+        this.emit('change', this.status());
+        return this.status();
+    }
+    /** Send a copy of a caught email through Groundmail. */
+    async sendCopy(email, to) {
+        const saved = this.load();
+        const recipient = (to || saved?.email || '').trim();
+        if (!recipient)
+            throw new Error('Which address should get the copy?');
+        const token = await this.accessToken();
+        const attachments = email.attachments.map((attachment) => ({
+            filename: attachment.filename,
+            content: email.attachmentContent.get(attachment.id)?.toString('base64') ?? '',
+            content_type: attachment.contentType,
+        }));
+        const result = await post(`${this.apiUrl}/emails`, {
+            from: this.from,
+            to: [recipient],
+            subject: email.subject || '(no subject)',
+            ...(email.html ? { html: email.html } : {}),
+            ...(email.text ? { text: email.text } : {}),
+            ...(!email.html && !email.text ? { text: '(This email had no body.)' } : {}),
+            ...(attachments.length ? { attachments } : {}),
+            headers: { 'X-Groundhog-Copy-Of': email.id },
+        }, token);
+        if (result.status >= 300)
+            throw new Error(apiError(result.body, `Groundmail answered ${result.status}.`));
+        return { id: String(result.body.id ?? ''), to: recipient };
+    }
+}

package/dist/http.d.ts

@@ -0,0 +1,58 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+export declare const MAX_BODY_BYTES: number;
+export declare class HttpError extends Error {
+    readonly status: number;
+    constructor(status: number, message: string);
+}
+export type HttpResult = {
+    status: number;
+    headers?: Record<string, string>;
+    body?: unknown;
+};
+export type MultipartFile = {
+    field: string;
+    filename: string;
+    contentType: string;
+    content: Buffer;
+};
+export type MultipartForm = {
+    fields: Array<[string, string]>;
+    files: MultipartFile[];
+};
+export declare class RequestContext {
+    readonly req: IncomingMessage;
+    readonly res: ServerResponse;
+    readonly url: URL;
+    params: Record<string, string>;
+    private bodyPromise;
+    constructor(req: IncomingMessage, res: ServerResponse);
+    get method(): string;
+    header(name: string): string;
+    query(name: string): string | undefined;
+    body(): Promise<Buffer>;
+    json<T = Record<string, unknown>>(): Promise<T>;
+    /** application/x-www-form-urlencoded, as ordered pairs (keys repeat). */
+    formPairs(): Promise<Array<[string, string]>>;
+    multipart(): Promise<MultipartForm>;
+    send(result: HttpResult): void;
+}
+export type Handler = (ctx: RequestContext) => Promise<HttpResult | void> | HttpResult | void;
+export type Route = {
+    method: string;
+    /** Path with `:params`, e.g. `/emails/:id`. A trailing `*` matches the rest. */
+    path: string;
+    handler: Handler;
+};
+export declare function compileRoute(path: string): RegExp;
+export declare class Router {
+    private routes;
+    add(method: string, path: string, handler: Handler): this;
+    get(path: string, handler: Handler): this;
+    post(path: string, handler: Handler): this;
+    put(path: string, handler: Handler): this;
+    delete(path: string, handler: Handler): this;
+    match(method: string, pathname: string): {
+        route: Route;
+        params: Record<string, string>;
+    } | 'method' | null;
+}