@avgvstvs96/pigeon 0.0.0-stage → 0.1.0

package/src/config.ts

@@ -0,0 +1,70 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+import { defineSource } from "./define.ts";
+import { pigeon, type Pigeon } from "./pigeon.ts";
+import { redact } from "./redact.ts";
+import { imessage } from "./sources/imessage/index.ts";
+import type { Config } from "./types.ts";
+
+export const configApi = { defineSource, imessage, redact };
+
+export type ConfigApi = typeof configApi;
+export type ConfigFactory = (api: ConfigApi) => Config | Promise<Config>;
+
+export function configDir(): string {
+  const base = process.env.XDG_CONFIG_HOME?.trim() || join(homedir(), ".config");
+  return join(base, "pigeon");
+}
+
+/** The config file pigeon will load, if there is one. */
+export async function findConfig(): Promise<string | undefined> {
+  const explicit = process.env.PIGEON_CONFIG?.trim();
+  if (explicit) return explicit;
+  for (const name of ["config.ts", "config.js"]) {
+    const path = join(configDir(), name);
+    if (await Bun.file(path).exists()) return path;
+  }
+}
+
+function validate(raw: unknown, path: string): Config {
+  if (!raw || typeof raw !== "object") throw new Error(`${path} must export a config object or a function returning one`);
+  const unknown = Object.keys(raw).filter((key) => key !== "sources" && key !== "filters");
+  if (unknown.length > 0) throw new Error(`${path}: unknown config keys: ${unknown.join(", ")} (expected sources, filters)`);
+  const { sources, filters } = raw as Config;
+  if (filters !== undefined && !(Array.isArray(filters) && filters.every((f) => typeof f === "function"))) {
+    throw new Error(`${path}: filters must be an array of functions`);
+  }
+  if (
+    sources !== undefined &&
+    !(Array.isArray(sources) && sources.every((s) => s && typeof s.id === "string" && typeof s.messages === "function"))
+  ) {
+    throw new Error(`${path}: sources must be an array of sources, each with an id and messages()`);
+  }
+  return { sources, filters };
+}
+
+/**
+ * Reads `~/.config/pigeon/config.ts`. Unlike most tools, a config that fails
+ * to load is fatal: it may hold the filters that hide messages, and running
+ * without them would hand those messages out.
+ */
+export async function loadConfig(): Promise<Config> {
+  const path = await findConfig();
+  if (!path) return {};
+  if (!(await Bun.file(path).exists())) throw new Error(`config not found: ${path}`);
+  let raw: unknown;
+  try {
+    const mod = await import(pathToFileURL(path).href);
+    if (mod.default === undefined) throw new Error("it has no default export");
+    raw = await (typeof mod.default === "function" ? (mod.default as ConfigFactory)(configApi) : mod.default);
+  } catch (err) {
+    throw new Error(`couldn't load ${path}: ${err instanceof Error ? err.message : err}`);
+  }
+  return validate(raw, path);
+}
+
+/** pigeon with your config applied: the same messages, and the same hidden ones, as the CLI. */
+export async function open(): Promise<Pigeon> {
+  return pigeon(await loadConfig());
+}

package/src/define.ts

@@ -0,0 +1,6 @@
+import type { Source } from "./types.ts";
+
+/** Types a source. The built-in iMessage source is declared with this too. */
+export function defineSource<S extends Source>(source: S): S {
+  return source;
+}

package/src/handles.ts

@@ -0,0 +1,22 @@
+const PHONE = /^\+?[\d\s().-]{7,}$/;
+
+function digits(value: string): string {
+  return value.replace(/\D/g, "");
+}
+
+export function isPhone(value: string): boolean {
+  return PHONE.test(value.trim()) && digits(value).length >= 7;
+}
+
+/**
+ * One key per person, however the handle was written: phone numbers compare on
+ * their last 10 digits, so "+1 (516) 555-0100" and "5165550100" are the same.
+ */
+export function handleKey(value: string): string {
+  const trimmed = value.trim();
+  return isPhone(trimmed) ? digits(trimmed).slice(-10) : trimmed.toLowerCase();
+}
+
+export function sameHandle(a: string, b: string): boolean {
+  return handleKey(a) === handleKey(b);
+}

package/src/index.ts

@@ -0,0 +1,11 @@
+export type { Attachment, Chat, Config, Filter, Message, Outgoing, Person, Query, Source } from "./types.ts";
+export type { ConfigApi, ConfigFactory } from "./config.ts";
+export type { MessageQuery, Pigeon } from "./pigeon.ts";
+export type { RedactRule } from "./redact.ts";
+export type { IMessageOptions } from "./sources/imessage/index.ts";
+
+export { configDir, findConfig, loadConfig, open } from "./config.ts";
+export { defineSource } from "./define.ts";
+export { pigeon } from "./pigeon.ts";
+export { REDACTED, redact } from "./redact.ts";
+export { imessage } from "./sources/imessage/index.ts";

package/src/pigeon.ts

@@ -0,0 +1,187 @@
+import { isPhone, sameHandle } from "./handles.ts";
+import { imessage } from "./sources/imessage/index.ts";
+import type { Chat, Config, Filter, Message, Outgoing, Source } from "./types.ts";
+
+export interface MessageQuery {
+  /** A chat id or name, from any source. */
+  chat?: string;
+  since?: Date;
+  until?: Date;
+  /** Words that must all appear, matched after filters run so hidden text is never searched. */
+  text?: string;
+  limit?: number;
+}
+
+export interface Pigeon {
+  sources: Source[];
+  /** Every chat, most recent first. */
+  chats(): Promise<Chat[]>;
+  /** Chats matching an id, a name, or part of a name. */
+  findChats(ref: string): Promise<Chat[]>;
+  /** Exactly one chat, or an error naming the candidates. */
+  chat(ref: string): Promise<Chat>;
+  /** Filtered messages, newest first. */
+  messages(query?: MessageQuery): AsyncGenerator<Message>;
+  /** Filtered messages as they arrive. */
+  watch(query?: Omit<MessageQuery, "since" | "until" | "limit">): AsyncGenerator<Message>;
+  send(ref: string, message: Outgoing): Promise<void>;
+}
+
+type Stream<T> = AsyncIterable<T> | Iterable<T>;
+
+function iterate<T>(stream: Stream<T>): AsyncIterator<T> | Iterator<T> {
+  return Symbol.asyncIterator in stream ? stream[Symbol.asyncIterator]() : stream[Symbol.iterator]();
+}
+
+/** Merges streams that are each newest first into one that is newest first. */
+async function* newestFirst(streams: Stream<Message>[]): AsyncGenerator<Message> {
+  const iterators = streams.map(iterate);
+  try {
+    const heads = await Promise.all(iterators.map((it) => it.next()));
+    while (true) {
+      let next = -1;
+      heads.forEach((head, i) => {
+        if (!head.done && (next < 0 || head.value.date > heads[next]!.value.date)) next = i;
+      });
+      if (next < 0) return;
+      yield heads[next]!.value;
+      heads[next] = await iterators[next]!.next();
+    }
+  } finally {
+    await Promise.all(iterators.map((it) => it.return?.()));
+  }
+}
+
+/** Merges live streams in arrival order. */
+async function* arrivals(streams: AsyncIterable<Message>[]): AsyncGenerator<Message> {
+  const iterators = streams.map((s) => s[Symbol.asyncIterator]());
+  const pull = (i: number) => iterators[i]!.next().then((result) => ({ i, result }));
+  const pending = new Map(iterators.map((_, i) => [i, pull(i)]));
+  try {
+    while (pending.size > 0) {
+      const { i, result } = await Promise.race(pending.values());
+      if (result.done) {
+        pending.delete(i);
+        continue;
+      }
+      pending.set(i, pull(i));
+      yield result.value;
+    }
+  } finally {
+    await Promise.all(iterators.map((it) => it.return?.()));
+  }
+}
+
+function matcher(text: string | undefined): (message: Message) => boolean {
+  const terms = text?.toLowerCase().split(/\s+/).filter(Boolean) ?? [];
+  return (m) => {
+    const haystack = m.text.toLowerCase();
+    return terms.every((term) => haystack.includes(term));
+  };
+}
+
+function isMessage(value: unknown): value is Message {
+  const m = value as Message | null;
+  return !!m && typeof m === "object" && typeof m.text === "string" && m.date instanceof Date && Array.isArray(m.attachments);
+}
+
+/**
+ * Runs every filter in order. A filter that throws or returns anything but
+ * `true` or a message drops the message: when in doubt, nothing leaks.
+ */
+function screener(filters: Filter[]): (message: Message) => Message | undefined {
+  const warned = new Set<number>();
+  return (message) => {
+    let current = message;
+    for (const [i, filter] of filters.entries()) {
+      let result: unknown;
+      try {
+        result = filter(current);
+      } catch (err) {
+        if (!warned.has(i)) console.error(`pigeon: filter ${i + 1} threw, dropping what it fails on\n  ${err}`);
+        warned.add(i);
+        return undefined;
+      }
+      if (result === true) continue;
+      if (!isMessage(result)) return undefined;
+      current = result;
+    }
+    return current;
+  };
+}
+
+function only(found: Chat[], ref: string): Chat {
+  if (found.length === 1) return found[0]!;
+  const names = found.slice(0, 8).map((c) => `  ${c.name} (${c.id})`);
+  throw new Error(`"${ref}" matches ${found.length} chats, use an id:\n${names.join("\n")}`);
+}
+
+export function pigeon({ sources = [imessage()], filters = [] }: Config = {}): Pigeon {
+  const screen = screener(filters);
+  const sourceOf = (chat: Chat) => sources.find((s) => s.id === chat.source);
+
+  async function chats(): Promise<Chat[]> {
+    const lists = await Promise.all(sources.map((s) => s.chats()));
+    return lists.flat().sort((a, b) => (b.date?.getTime() ?? 0) - (a.date?.getTime() ?? 0));
+  }
+
+  /** By id, then exact name, then (unless `exact`) part of a name. */
+  async function lookup(ref: string, exact: boolean): Promise<Chat[]> {
+    const all = await chats();
+    const needle = ref.trim().toLowerCase();
+    const byId = all.filter((c) => sameHandle(c.id, ref));
+    if (byId.length > 0) return byId;
+    const byName = all.filter((c) => c.name.toLowerCase() === needle);
+    if (byName.length > 0 || exact) return byName;
+    return all.filter((c) => c.name.toLowerCase().includes(needle));
+  }
+
+  const findChats = (ref: string) => lookup(ref, false);
+
+  async function chat(ref: string): Promise<Chat> {
+    const found = await findChats(ref);
+    if (found.length === 0) throw new Error(`no chat matches "${ref}"`);
+    return only(found, ref);
+  }
+
+  async function* messages({ chat: ref, since, until, text, limit = Infinity }: MessageQuery = {}) {
+    if (limit <= 0) return;
+    const target = ref === undefined ? undefined : await chat(ref);
+    const from = target ? [sourceOf(target)!] : sources;
+    const matches = matcher(text);
+    let count = 0;
+    for await (const message of newestFirst(from.map((s) => s.messages({ chat: target?.id, since, until })))) {
+      if (since && message.date < since) return;
+      if (until && message.date >= until) continue;
+      if (target && message.chat.id !== target.id) continue;
+      const kept = screen(message);
+      if (!kept || !matches(kept)) continue;
+      yield kept;
+      if (++count >= limit) return;
+    }
+  }
+
+  async function* watch({ chat: ref, text }: Omit<MessageQuery, "since" | "until" | "limit"> = {}) {
+    const target = ref === undefined ? undefined : await chat(ref);
+    const live = (target ? [sourceOf(target)!] : sources).filter((s) => s.watch);
+    if (live.length === 0) throw new Error("no source can watch for new messages");
+    const matches = matcher(text);
+    for await (const message of arrivals(live.map((s) => s.watch!({ chat: target?.id })))) {
+      if (target && message.chat.id !== target.id) continue;
+      const kept = screen(message);
+      if (kept && matches(kept)) yield kept;
+    }
+  }
+
+  /** Only an id or an exact name: a partial match could text the wrong people. */
+  async function send(ref: string, message: Outgoing): Promise<void> {
+    const found = await lookup(ref, true);
+    const target = found.length > 0 ? only(found, ref) : undefined;
+    const source = target ? sourceOf(target) : isPhone(ref) || ref.includes("@") ? sources.find((s) => s.send) : undefined;
+    if (!source) throw new Error(`no chat matches "${ref}"`);
+    if (!source.send) throw new Error(`${source.label ?? source.id} can't send messages`);
+    await source.send(target?.id ?? ref.trim(), message);
+  }
+
+  return { sources, chats, findChats, chat, messages, watch, send };
+}

package/src/redact.ts

@@ -0,0 +1,80 @@
+import { sameHandle } from "./handles.ts";
+import { dayRange, toDate, type DateInput } from "./time.ts";
+import type { Filter, Message } from "./types.ts";
+
+export const REDACTED = "[redacted]";
+
+type OneOrMany<T> = T | T[];
+
+export interface RedactRule {
+  /**
+   * Chat id. For a 1:1 iMessage chat that's the person's number or email; `pigeon chats` shows group ids.
+   * Names aren't accepted: they change, and a rule that silently stops matching would show what it hid.
+   */
+  chat?: OneOrMany<string>;
+  /** Sender handle, or `"me"`. */
+  from?: OneOrMany<string>;
+  /** A whole day, local time: `"2026-10-06"`. */
+  on?: DateInput;
+  since?: DateInput;
+  until?: DateInput;
+  /** Hide only these strings. Without it, the whole message is hidden. */
+  match?: OneOrMany<string | RegExp>;
+}
+
+function list<T>(value: OneOrMany<T> | undefined): T[] {
+  return value === undefined ? [] : Array.isArray(value) ? value : [value];
+}
+
+function escape(text: string): string {
+  return text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+/** Always a fresh global regex: a caller's sticky flag or leftover lastIndex would skip matches. */
+function toPattern(match: string | RegExp): RegExp {
+  if (typeof match === "string") return new RegExp(escape(match), "gi");
+  return new RegExp(match.source, match.flags.replace(/[gy]/g, "") + "g");
+}
+
+/** Replaces every match of every pattern, merging overlaps so each hidden span reads as one marker. */
+function hide(text: string, patterns: RegExp[]): string {
+  const spans = patterns
+    .flatMap((p) => [...text.matchAll(p)].map((m) => [m.index, m.index + m[0].length] as const))
+    .filter(([start, end]) => end > start)
+    .sort((a, b) => a[0] - b[0]);
+  let out = "";
+  let at = 0;
+  for (const [start, end] of spans) {
+    if (start >= at) out += text.slice(at, start) + REDACTED;
+    at = Math.max(at, end);
+  }
+  return out + text.slice(at);
+}
+
+/**
+ * A filter that hides messages instead of dropping them, so a reader can still
+ * tell something was there. Every field narrows the rule; `redact({})` hides everything.
+ */
+export function redact(rule: RedactRule): Filter {
+  const chats = list(rule.chat);
+  const senders = list(rule.from);
+  const [onStart, onEnd] = rule.on === undefined ? [] : dayRange(rule.on);
+  const since = rule.since === undefined ? onStart : toDate(rule.since);
+  const until = rule.until === undefined ? onEnd : toDate(rule.until);
+  const patterns = list(rule.match).map(toPattern);
+
+  const applies = (m: Message) =>
+    (chats.length === 0 || chats.some((c) => sameHandle(c, m.chat.id))) &&
+    (senders.length === 0 || senders.some((s) => sameHandle(s, m.from.id))) &&
+    (since === undefined || m.date >= since) &&
+    (until === undefined || m.date < until);
+
+  return (m) => {
+    if (!applies(m)) return true;
+    if (patterns.length === 0) return { ...m, text: REDACTED, attachments: [], redacted: true };
+    const text = hide(m.text, patterns);
+    const attachments = m.attachments.map((a) => (hide(a.name, patterns) === a.name ? a : { name: REDACTED }));
+    const changed = text !== m.text || attachments.some((a, i) => a !== m.attachments[i]);
+    return changed ? { ...m, text, attachments, redacted: true } : true;
+  };
+}

package/src/sources/imessage/contacts.ts

@@ -0,0 +1,50 @@
+import { Database } from "bun:sqlite";
+import { Glob } from "bun";
+import { handleKey } from "../../handles.ts";
+
+const NAME = `
+  COALESCE(
+    NULLIF(TRIM(COALESCE(r.ZFIRSTNAME, '') || ' ' || COALESCE(r.ZLASTNAME, '')), ''),
+    r.ZNICKNAME,
+    r.ZORGANIZATION
+  )`;
+
+const HANDLES = `
+  SELECT p.ZFULLNUMBER AS handle, ${NAME} AS name
+  FROM ZABCDPHONENUMBER p JOIN ZABCDRECORD r ON r.Z_PK = p.ZOWNER
+  UNION ALL
+  SELECT e.ZADDRESS AS handle, ${NAME} AS name
+  FROM ZABCDEMAILADDRESS e JOIN ZABCDRECORD r ON r.Z_PK = e.ZOWNER`;
+
+function databases(root: string): string[] {
+  try {
+    return ["AddressBook-v22.abcddb", "Sources/*/AddressBook-v22.abcddb"].flatMap((pattern) => [
+      ...new Glob(pattern).scanSync({ cwd: root, absolute: true }),
+    ]);
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Names from the macOS Contacts database, keyed by `handleKey`. Read directly
+ * so it works over ssh, where the Contacts framework isn't available. Every
+ * account (iCloud, Google, local) keeps its own database under Sources/.
+ */
+export function loadContacts(root: string): Map<string, string> {
+  const names = new Map<string, string>();
+  for (const file of databases(root)) {
+    let db: Database | undefined;
+    try {
+      db = new Database(file, { readonly: true });
+      for (const { handle, name } of db.query<{ handle: string | null; name: string | null }, []>(HANDLES).all()) {
+        if (handle && name && !names.has(handleKey(handle))) names.set(handleKey(handle), name);
+      }
+    } catch {
+      continue;
+    } finally {
+      db?.close();
+    }
+  }
+  return names;
+}