Skip to content

Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS

10.5 KB
Raw Blame
/**
 * Tribe identity matcher — pure, deterministic mapping of a calendar attendee /
 * message counterpart ({ email, name }) back to a tracked Tribe person (#2033).
 *
 * Matching is intentionally deterministic (no LLM, no fuzzy string distance):
 *   1. Email / handle — authoritative. Compared case-insensitively against the
 *      identifiers the user stored on the person record (`person.emails`).
 *   2. Exact name — case-insensitive, and only when EXACTLY ONE tracked person
 *      owns that name (ambiguous names never resolve, so a shared first name can
 *      not mis-log). This is a convenience fallback before the user has recorded
 *      any emails; fuzzy name-matching is a separate consent-gated follow-up.
 */

export function normalizeIdentifier(value) {
  if (value == null) return '';
  return String(value).trim().toLowerCase();
}

/**
 * Normalize a phone handle to a stable E.164-ish key so a person's stored phone
 * matches an iMessage/Signal handle (`chat.db` stores handles as either an email
 * or an E.164 phone like `+15551234567`). Deterministic, no external library:
 *
 *   - strip every character except digits and a leading `+`;
 *   - a value that already carries a `+` country code passes through as `+<digits>`;
 *   - a bare 11-digit US number starting with `1` gets a `+` (`15551234567` → `+15551234567`);
 *   - a bare 10-digit US number is assumed NANP and prefixed `+1` (`5551234567` → `+15551234567`);
 *   - anything else (already-international bare digits, short codes) is returned as
 *     `+<digits>` so two spellings of the same number still collide.
 *
 * Returns `''` when there is no usable digit sequence. An `@`-bearing value is NOT
 * a phone — callers route those through `normalizeIdentifier` (email path) instead.
 */
export function normalizePhone(value) {
  if (value == null) return '';
  const raw = String(value).trim();
  if (!raw || raw.includes('@')) return '';
  const hasPlus = raw.startsWith('+');
  const digits = raw.replace(/\D/g, '');
  if (!digits) return '';
  if (hasPlus) return `+${digits}`;
  if (digits.length === 11 && digits.startsWith('1')) return `+${digits}`;
  if (digits.length === 10) return `+1${digits}`;
  return `+${digits}`;
}

/**
 * Classify a raw handle (from an iMessage/Signal `chat.db` `handle.id`, or a
 * calendar/message counterpart) into `{ email, phone }` — exactly one is set.
 * A value containing `@` is an email; otherwise it's treated as a phone.
 */
export function identityFromHandle(handle) {
  const raw = handle == null ? '' : String(handle).trim();
  if (!raw) return {};
  if (raw.includes('@')) return { email: normalizeIdentifier(raw) };
  const phone = normalizePhone(raw);
  return phone ? { phone } : {};
}

/**
 * Build lookup indexes from a list of tribe people. Returns
 * `{ byIdentifier: Map<email, personId>, byPhone: Map<e164, personId>, byName: Map<name, personId[]> }`.
 * The first person to claim an identifier/phone wins (they're meant to be unique
 * to one person); names collect every owner so ambiguity is detectable.
 */
export function buildPersonMatchIndex(people = []) {
  const byIdentifier = new Map();
  const byPhone = new Map();
  const byName = new Map();
  for (const person of people) {
    if (!person?.id) continue;
    for (const identifier of person.emails || []) {
      const key = normalizeIdentifier(identifier);
      if (key && !byIdentifier.has(key)) byIdentifier.set(key, person.id);
    }
    for (const rawPhone of person.phones || []) {
      const key = normalizePhone(rawPhone);
      if (key && !byPhone.has(key)) byPhone.set(key, person.id);
    }
    const nameKey = normalizeIdentifier(person.name);
    if (nameKey) {
      const owners = byName.get(nameKey) || [];
      owners.push(person.id);
      byName.set(nameKey, owners);
    }
  }
  return { byIdentifier, byPhone, byName };
}

/**
 * Resolve a single `{ email, phone, name }` identity to a personId, or `null`.
 * Email/handle wins, then phone (E.164-normalized), then exact unique name.
 */
export function matchPerson(identity, index) {
  if (!identity || !index) return null;
  const email = normalizeIdentifier(identity.email);
  if (email && index.byIdentifier.has(email)) return index.byIdentifier.get(email);
  const phone = normalizePhone(identity.phone);
  if (phone && index.byPhone?.has(phone)) return index.byPhone.get(phone);
  const name = normalizeIdentifier(identity.name);
  if (name) {
    const owners = index.byName.get(name);
    if (owners && owners.length === 1) return owners[0];
  }
  return null;
}

/**
 * Resolve many identities (mixed `{ email, phone, name }` objects or bare
 * email/handle strings) to a de-duplicated Set of personIds. A single
 * event/message that involves the same tracked person twice (organizer +
 * attendee) yields one id. A bare string is classified as email-or-phone via
 * `identityFromHandle`, so a raw `+15551234567` handle resolves by phone.
 */
export function matchPeople(identities = [], index) {
  const ids = new Set();
  if (!index) return ids;
  for (const raw of identities) {
    if (!raw) continue;
    const identity = typeof raw === 'string' ? identityFromHandle(raw) : raw;
    const id = matchPerson(identity, index);
    if (id) ids.add(id);
  }
  return ids;
}

// ---------------------------------------------------------------------------
// Network-scoped identity axis (#34, decided on #10) — the `tribe_identities`
// table's (kind, network, handle) key. This is a THIRD axis, deliberately
// separate from identityFromHandle above: identityFromHandle classifies a bare
// string of unknown provenance (an iMessage/Signal `chat.db` handle) by
// testing for `@`, which is exactly what makes it misclassify a Matrix-style
// id like `@discord_123:beeper.com` as an email (#15 — closed as
// "not reachable from any live iMessage/Signal caller", but explicitly
// deferred to this identity work rather than fixed in place).
//
// The functions below never see a raw source_user_id / Matrix id — callers
// pass an already-scoped Beeper `handle` value (`User.phoneNumber` or
// `User.username`, never `User.id`), so the `@`-vs-Matrix collision does not
// apply here. What DOES apply, and what these functions guard against, is
// #15's other finding: a digit-bearing (but non-phone) handle must never
// collapse into a fabricated E.164 key. `classifyNetworkHandle` only takes the
// phone branch when the value contains NO letters at all — a plausible
// phone-shaped string — never merely "has enough digits".
// ---------------------------------------------------------------------------

// Lowercase, trim, strip a leading '@' — the normalization #10 specifies for
// a network handle before it reaches tribe_identities.
export function normalizeNetworkHandle(value) {
  if (value == null) return '';
  return String(value).trim().toLowerCase().replace(/^@+/, '');
}

// A string is phone-SHAPED only when, after stripping spaces/hyphens/
// parens/dots and an optional leading '+', every remaining character is a
// digit. Any letter (a Discord/Slack/X username, "user5550100199") takes the
// 'handle' branch instead — the #15 hazard, guarded here rather than reusing
// normalizePhone's bare "strip everything but digits" behavior blind to
// letters.
const PHONE_SHAPE_RE = /^\+?[0-9]+$/;
// Real-world E.164 numbers run roughly 7-15 digits (a handful of short-country
// numbers, e.g. some Pacific island plans, are as short as 7). A shorter
// all-digit token (a PIN-like username) is refused as a phone rather than
// fabricating an implausible key — residual ambiguity for a genuinely long
// all-digit non-phone id (a full Discord snowflake) is an accepted,
// documented limit: nothing upstream is expected to feed one through `handle`
// (source_user_id carries those, and is never routed through this function).
const MIN_PHONE_DIGITS = 7;
const MAX_PHONE_DIGITS = 15;

/**
 * Classify an already network-scoped Beeper handle (`User.phoneNumber` or
 * `User.username` — never a bare `User.id` / Matrix id) into the
 * `tribe_identities` `{ kind, handle }` shape, or `null` for a blank value.
 * `kind` is `'phone'` (handle normalized E.164 via normalizePhone) or
 * `'handle'` (lowercased/trimmed/`@`-stripped username).
 */
export function classifyNetworkHandle(value) {
  const raw = value == null ? '' : String(value).trim();
  if (!raw) return null;
  const stripped = raw.replace(/[\s().-]/g, '');
  if (PHONE_SHAPE_RE.test(stripped)) {
    const digits = stripped.replace(/^\+/, '');
    if (digits.length >= MIN_PHONE_DIGITS && digits.length <= MAX_PHONE_DIGITS) {
      const phone = normalizePhone(stripped);
      if (phone) return { kind: 'phone', handle: phone };
    }
  }
  const handle = normalizeNetworkHandle(raw);
  return handle ? { kind: 'handle', handle } : null;
}

// ---------------------------------------------------------------------------
// Soft-delete parity — a `tribe_person_id` cache column reads as "linked"
// consistently everywhere a beeper_participants row is shaped.
// ---------------------------------------------------------------------------

/**
 * A `beeper_participants.tribe_person_id` cache column, plus the joined
 * `tribe_people.deleted` flag it was read alongside, collapsed to ONE answer.
 * `tribe.deletePerson` is a SOFT delete — it never fires the FK's ON DELETE
 * CASCADE — so the raw column can go on pointing at a person who no longer
 * counts as one. Every reader of a participant row (the conversation/list
 * shaper in `services/beeperConversations.js`, and `services/beeperTribe.js`'s
 * own row shaper) calls this SAME function so a soft-deleted link reads as
 * unlinked everywhere at once: `null`, never a dead id with no re-link
 * affordance in the UI. Extracted here rather than duplicated in both
 * services precisely because two independent copies had already drifted —
 * one nulled the id, the other did not.
 */
export function resolveLinkedPersonId(tribePersonId, tribePersonDeleted) {
  return tribePersonId && !tribePersonDeleted ? tribePersonId : null;
}

/**
 * The idempotency key a calendar event carries on `tribe_touchpoints.dedupe_key`.
 * ONE builder for both producers — the sync auto-logger (`calendarSync.js`) and
 * the manual "log this event" route (`tribe.createCalendarTouchpoint`) — so a
 * hand-logged event and a synced one collide on the unique index instead of
 * both inserting. Keyed on the provider id when present, matching the cache's
 * `externalId || id` convention. Returns null when the event has no usable id.
 */
export function calendarTouchpointDedupeKey(accountId, event) {
  const eventKey = event?.externalId || event?.id;
  return eventKey ? `cal:${accountId}:${eventKey}` : null;
}