@auxiora/contacts 1.0.0

package/src/context.ts

@@ -0,0 +1,64 @@
+import type { Contact } from './types.js';
+import type { ContactGraph } from './graph.js';
+
+export class ContextRecall {
+  private graph: ContactGraph;
+
+  constructor(graph: ContactGraph) {
+    this.graph = graph;
+  }
+
+  getContext(emailOrName: string): { contact: Contact; relationshipSummary: string } | null {
+    let contact = this.graph.findByEmail(emailOrName);
+    if (!contact) {
+      const byName = this.graph.findByName(emailOrName);
+      if (byName.length > 0) {
+        contact = byName[0];
+      }
+    }
+    if (!contact) return null;
+
+    const rel = contact.relationship;
+    const recencyText = isFinite(rel.recency)
+      ? `${Math.round(rel.recency)} days ago`
+      : 'never';
+    const relationshipSummary = `Strong relationship (score ${rel.strength.toFixed(2)}). Context: ${rel.context}. Last interaction: ${recencyText}.`;
+
+    return { contact, relationshipSummary };
+  }
+
+  whoIs(query: string): string {
+    const result = this.getContext(query);
+    if (!result) return `No contact found for "${query}".`;
+
+    const { contact, relationshipSummary } = result;
+    const email = contact.emails[0] ?? 'no email';
+    const company = contact.company ? ` at ${contact.company}` : '';
+    const title = contact.jobTitle ? ` - ${contact.jobTitle}` : '';
+    const notes = contact.notes?.length ? ` Notes: ${contact.notes.join('; ')}` : '';
+
+    return `${contact.displayName} (${email})${company}${title}. ${relationshipSummary}${notes}`;
+  }
+
+  getUpcomingBirthdays(contacts: Contact[], withinDays = 30): Contact[] {
+    const now = new Date();
+    const currentYear = now.getFullYear();
+
+    return contacts.filter(contact => {
+      if (!contact.birthday) return false;
+
+      const bday = new Date(contact.birthday);
+      // Set birthday to current year
+      const thisYearBday = new Date(currentYear, bday.getMonth(), bday.getDate());
+
+      // If birthday already passed this year, check next year
+      if (thisYearBday.getTime() < now.getTime()) {
+        thisYearBday.setFullYear(currentYear + 1);
+      }
+
+      const diffMs = thisYearBday.getTime() - now.getTime();
+      const diffDays = diffMs / (24 * 60 * 60 * 1000);
+      return diffDays >= 0 && diffDays <= withinDays;
+    });
+  }
+}

package/src/dedup.ts

@@ -0,0 +1,61 @@
+import type { Contact } from './types.js';
+
+export class ContactDeduplicator {
+  similarity(a: Contact, b: Contact): number {
+    let score = 0;
+
+    // Email overlap: any shared email → 0.9 minimum
+    const aEmails = new Set(a.emails.map(e => e.toLowerCase()));
+    const hasSharedEmail = b.emails.some(e => aEmails.has(e.toLowerCase()));
+    if (hasSharedEmail) {
+      score = Math.max(score, 0.9);
+    }
+
+    // Name similarity
+    const nameScore = this.nameSimilarity(a.displayName, b.displayName);
+    score = Math.max(score, nameScore);
+
+    // Company match adds 0.1
+    if (a.company && b.company && a.company.toLowerCase() === b.company.toLowerCase()) {
+      score = Math.min(1, score + 0.1);
+    }
+
+    return score;
+  }
+
+  findDuplicates(
+    contacts: Contact[],
+    threshold = 0.7,
+  ): Array<{ contact1: Contact; contact2: Contact; similarity: number }> {
+    const results: Array<{ contact1: Contact; contact2: Contact; similarity: number }> = [];
+
+    for (let i = 0; i < contacts.length; i++) {
+      for (let j = i + 1; j < contacts.length; j++) {
+        const sim = this.similarity(contacts[i], contacts[j]);
+        if (sim >= threshold) {
+          results.push({ contact1: contacts[i], contact2: contacts[j], similarity: sim });
+        }
+      }
+    }
+
+    return results;
+  }
+
+  private nameSimilarity(a: string, b: string): number {
+    const la = a.toLowerCase();
+    const lb = b.toLowerCase();
+
+    if (la === lb) return 1.0;
+    if (la.includes(lb) || lb.includes(la)) return 0.7;
+
+    // Character overlap ratio
+    const setA = new Set(la);
+    const setB = new Set(lb);
+    let overlap = 0;
+    for (const ch of setA) {
+      if (setB.has(ch)) overlap++;
+    }
+    const union = new Set([...setA, ...setB]).size;
+    return union > 0 ? overlap / union : 0;
+  }
+}

package/src/graph.ts

@@ -0,0 +1,115 @@
+import { nanoid } from 'nanoid';
+import type { Contact, ContactGraphConfig } from './types.js';
+
+export class ContactGraph {
+  private contacts: Map<string, Contact> = new Map();
+  private config: ContactGraphConfig;
+
+  constructor(config?: ContactGraphConfig) {
+    this.config = {
+      mergeThreshold: config?.mergeThreshold ?? 0.8,
+      decayDays: config?.decayDays ?? 90,
+    };
+  }
+
+  addContact(input: Omit<Contact, 'id' | 'relationship'>): Contact {
+    const contact: Contact = {
+      ...input,
+      id: nanoid(),
+      relationship: {
+        strength: 0,
+        frequency: 0,
+        recency: Infinity,
+        context: 'unknown',
+      },
+    };
+    this.contacts.set(contact.id, contact);
+    return contact;
+  }
+
+  getById(id: string): Contact | undefined {
+    return this.contacts.get(id);
+  }
+
+  findByEmail(email: string): Contact | undefined {
+    const lower = email.toLowerCase();
+    for (const contact of this.contacts.values()) {
+      if (contact.emails.some(e => e.toLowerCase() === lower)) {
+        return contact;
+      }
+    }
+    return undefined;
+  }
+
+  findByName(name: string): Contact[] {
+    const lower = name.toLowerCase();
+    const results: Contact[] = [];
+    for (const contact of this.contacts.values()) {
+      if (contact.displayName.toLowerCase().includes(lower)) {
+        results.push(contact);
+      }
+    }
+    return results;
+  }
+
+  search(query: string): Contact[] {
+    const lower = query.toLowerCase();
+    const results: Contact[] = [];
+    for (const contact of this.contacts.values()) {
+      if (
+        contact.displayName.toLowerCase().includes(lower) ||
+        contact.emails.some(e => e.toLowerCase().includes(lower)) ||
+        contact.company?.toLowerCase().includes(lower) ||
+        contact.tags?.some(t => t.toLowerCase().includes(lower))
+      ) {
+        results.push(contact);
+      }
+    }
+    return results;
+  }
+
+  merge(id1: string, id2: string): Contact {
+    const c1 = this.contacts.get(id1);
+    const c2 = this.contacts.get(id2);
+    if (!c1 || !c2) {
+      throw new Error(`Contact not found: ${!c1 ? id1 : id2}`);
+    }
+
+    const mergedEmails = [...new Set([...c1.emails, ...c2.emails])];
+    const mergedSources = [...c1.sources, ...c2.sources];
+    const mergedNotes = [...(c1.notes ?? []), ...(c2.notes ?? [])];
+    const mergedTags = [...new Set([...(c1.tags ?? []), ...(c2.tags ?? [])])];
+
+    const merged: Contact = {
+      ...c1,
+      emails: mergedEmails,
+      sources: mergedSources,
+      notes: mergedNotes.length > 0 ? mergedNotes : undefined,
+      tags: mergedTags.length > 0 ? mergedTags : undefined,
+    };
+
+    this.contacts.set(id1, merged);
+    this.contacts.delete(id2);
+    return merged;
+  }
+
+  update(id: string, updates: Partial<Omit<Contact, 'id'>>): Contact | undefined {
+    const contact = this.contacts.get(id);
+    if (!contact) return undefined;
+    const updated = { ...contact, ...updates, id: contact.id };
+    this.contacts.set(id, updated);
+    return updated;
+  }
+
+  remove(id: string): boolean {
+    return this.contacts.delete(id);
+  }
+
+  getAll(): Contact[] {
+    return [...this.contacts.values()];
+  }
+
+  count(): number {
+    return this.contacts.size;
+  }
+}

package/src/index.ts

@@ -0,0 +1,11 @@
+export { ContactGraph } from './graph.js';
+export { RelationshipScorer } from './relationship.js';
+export { ContactDeduplicator } from './dedup.js';
+export { ContextRecall } from './context.js';
+export type {
+  Contact,
+  ContactSource,
+  RelationshipScore,
+  Interaction,
+  ContactGraphConfig,
+} from './types.js';

package/src/relationship.ts

@@ -0,0 +1,59 @@
+import type { Contact, Interaction, RelationshipScore } from './types.js';
+
+export class RelationshipScorer {
+  private decayDays: number;
+
+  constructor(config?: { decayDays?: number }) {
+    this.decayDays = config?.decayDays ?? 90;
+  }
+
+  score(interactions: Interaction[]): RelationshipScore {
+    if (interactions.length === 0) {
+      return { strength: 0, frequency: 0, recency: Infinity, context: 'unknown' };
+    }
+
+    const now = Date.now();
+    const thirtyDaysMs = 30 * 24 * 60 * 60 * 1000;
+
+    // Recency: days since most recent interaction
+    const mostRecent = Math.max(...interactions.map(i => i.timestamp));
+    const recency = (now - mostRecent) / (24 * 60 * 60 * 1000);
+
+    // Frequency: interactions in last 30 days
+    const recentInteractions = interactions.filter(
+      i => now - i.timestamp <= thirtyDaysMs,
+    );
+    const frequency = recentInteractions.length;
+
+    // Strength: weighted formula, clamped to [0, 1]
+    const recencyFactor = Math.max(0, 1 - recency / this.decayDays);
+    const frequencyFactor = Math.min(frequency / 10, 1);
+    const strength = Math.max(0, Math.min(1, 0.4 * recencyFactor + 0.6 * frequencyFactor));
+
+    // Context: infer from interaction types
+    const context = this.inferContext(interactions);
+
+    return { strength, frequency, recency, context };
+  }
+
+  updateRelationship(contact: Contact, interactions: Interaction[]): Contact {
+    return { ...contact, relationship: this.score(interactions) };
+  }
+
+  private inferContext(interactions: Interaction[]): string {
+    const counts: Record<string, number> = {};
+    for (const interaction of interactions) {
+      counts[interaction.type] = (counts[interaction.type] ?? 0) + 1;
+    }
+
+    const total = interactions.length;
+    const emailRatio = (counts['email'] ?? 0) / total;
+    const messageRatio = (counts['message'] ?? 0) / total;
+    const meetingRatio = (counts['meeting'] ?? 0) / total;
+
+    if (emailRatio > 0.5) return 'professional';
+    if (messageRatio > 0.5) return 'personal';
+    if (meetingRatio > 0.5) return 'colleague';
+    return 'mixed';
+  }
+}

package/src/types.ts

@@ -0,0 +1,39 @@
+export interface Contact {
+  id: string;
+  displayName: string;
+  emails: string[];
+  phones?: string[];
+  company?: string;
+  jobTitle?: string;
+  birthday?: string; // ISO date
+  sources: ContactSource[];
+  relationship: RelationshipScore;
+  lastInteraction?: number; // timestamp
+  notes?: string[];
+  tags?: string[];
+}
+
+export interface ContactSource {
+  type: 'email' | 'calendar' | 'social' | 'channel' | 'manual';
+  sourceId: string;
+  importedAt: number;
+}
+
+export interface RelationshipScore {
+  strength: number;    // 0-1
+  frequency: number;   // interactions per 30 days
+  recency: number;     // days since last interaction
+  context: string;     // e.g. "colleague", "client", "friend"
+}
+
+export interface Interaction {
+  contactId: string;
+  type: 'email' | 'meeting' | 'message' | 'social';
+  timestamp: number;
+  summary?: string;
+}
+
+export interface ContactGraphConfig {
+  mergeThreshold?: number; // similarity threshold for auto-merge, default 0.8
+  decayDays?: number;      // relationship decay period, default 90
+}

package/tests/context.test.ts

@@ -0,0 +1,78 @@
+import { describe, it, expect } from 'vitest';
+import { ContactGraph } from '../src/graph.js';
+import { ContextRecall } from '../src/context.js';
+import type { Contact } from '../src/types.js';
+
+function setupGraph() {
+  const graph = new ContactGraph();
+  const contact = graph.addContact({
+    displayName: 'Alice Smith',
+    emails: ['alice@example.com'],
+    sources: [{ type: 'manual', sourceId: 'test', importedAt: Date.now() }],
+    company: 'Acme Corp',
+    jobTitle: 'Engineer',
+    notes: ['Met at conference'],
+    birthday: getBirthdaySoon(),
+  });
+  // Manually update relationship for testing
+  graph.update(contact.id, {
+    relationship: { strength: 0.85, frequency: 5, recency: 3, context: 'colleague' },
+  });
+  return { graph, contact: graph.getById(contact.id)! };
+}
+
+function getBirthdaySoon(): string {
+  const d = new Date();
+  d.setDate(d.getDate() + 5);
+  return `${d.getFullYear() - 30}-${String(d.getMonth() + 1).padStart(2, '0')}-${String(d.getDate()).padStart(2, '0')}`;
+}
+
+describe('ContextRecall', () => {
+  it('getContext finds by email', () => {
+    const { graph } = setupGraph();
+    const recall = new ContextRecall(graph);
+    const result = recall.getContext('alice@example.com');
+    expect(result).not.toBeNull();
+    expect(result!.contact.displayName).toBe('Alice Smith');
+    expect(result!.relationshipSummary).toContain('0.85');
+  });
+
+  it('getContext finds by name', () => {
+    const { graph } = setupGraph();
+    const recall = new ContextRecall(graph);
+    const result = recall.getContext('Alice');
+    expect(result).not.toBeNull();
+    expect(result!.contact.emails).toContain('alice@example.com');
+  });
+
+  it('getContext returns null for unknown', () => {
+    const { graph } = setupGraph();
+    const recall = new ContextRecall(graph);
+    expect(recall.getContext('nobody@nowhere.com')).toBeNull();
+  });
+
+  it('whoIs returns formatted string', () => {
+    const { graph } = setupGraph();
+    const recall = new ContextRecall(graph);
+    const result = recall.whoIs('Alice');
+    expect(result).toContain('Alice Smith');
+    expect(result).toContain('alice@example.com');
+    expect(result).toContain('Acme Corp');
+    expect(result).toContain('Engineer');
+    expect(result).toContain('Met at conference');
+  });
+
+  it('getUpcomingBirthdays filters correctly', () => {
+    const { graph, contact } = setupGraph();
+    const recall = new ContextRecall(graph);
+    const allContacts = graph.getAll();
+
+    const upcoming = recall.getUpcomingBirthdays(allContacts, 10);
+    expect(upcoming).toHaveLength(1);
+    expect(upcoming[0].id).toBe(contact.id);
+
+    // Birthday 5 days away should not appear in 2-day window
+    const none = recall.getUpcomingBirthdays(allContacts, 2);
+    expect(none).toHaveLength(0);
+  });
+});

package/tests/dedup.test.ts

@@ -0,0 +1,75 @@
+import { describe, it, expect } from 'vitest';
+import { ContactDeduplicator } from '../src/dedup.js';
+import type { Contact } from '../src/types.js';
+
+function makeContact(overrides: Partial<Contact> = {}): Contact {
+  return {
+    id: 'test-id',
+    displayName: 'Test User',
+    emails: ['test@example.com'],
+    sources: [{ type: 'manual', sourceId: 'test', importedAt: Date.now() }],
+    relationship: { strength: 0, frequency: 0, recency: Infinity, context: 'unknown' },
+    ...overrides,
+  };
+}
+
+describe('ContactDeduplicator', () => {
+  const dedup = new ContactDeduplicator();
+
+  it('same email produces similarity >= 0.9', () => {
+    const a = makeContact({ id: 'a', displayName: 'Alice', emails: ['shared@example.com'] });
+    const b = makeContact({ id: 'b', displayName: 'Bob', emails: ['shared@example.com'] });
+    expect(dedup.similarity(a, b)).toBeGreaterThanOrEqual(0.9);
+  });
+
+  it('same name produces high similarity', () => {
+    const a = makeContact({ id: 'a', displayName: 'Alice Smith', emails: ['a@test.com'] });
+    const b = makeContact({ id: 'b', displayName: 'Alice Smith', emails: ['b@test.com'] });
+    expect(dedup.similarity(a, b)).toBe(1.0);
+  });
+
+  it('no overlap produces low similarity', () => {
+    const a = makeContact({ id: 'a', displayName: 'Alice', emails: ['alice@test.com'] });
+    const b = makeContact({ id: 'b', displayName: 'Zyx', emails: ['zyx@other.com'] });
+    expect(dedup.similarity(a, b)).toBeLessThan(0.5);
+  });
+
+  it('findDuplicates returns pairs above threshold', () => {
+    const contacts = [
+      makeContact({ id: 'a', displayName: 'Alice', emails: ['alice@test.com'] }),
+      makeContact({ id: 'b', displayName: 'Alice', emails: ['alice@test.com'] }),
+    ];
+    const pairs = dedup.findDuplicates(contacts, 0.7);
+    expect(pairs.length).toBeGreaterThanOrEqual(1);
+    expect(pairs[0].similarity).toBeGreaterThanOrEqual(0.7);
+  });
+
+  it('findDuplicates ignores below threshold', () => {
+    const contacts = [
+      makeContact({ id: 'a', displayName: 'Alice', emails: ['alice@test.com'] }),
+      makeContact({ id: 'b', displayName: 'Zyx', emails: ['zyx@other.com'] }),
+    ];
+    const pairs = dedup.findDuplicates(contacts, 0.9);
+    expect(pairs).toHaveLength(0);
+  });
+
+  it('company match adds to score', () => {
+    const a = makeContact({
+      id: 'a', displayName: 'Alice Smith', emails: ['a@test.com'], company: 'Acme',
+    });
+    const b = makeContact({
+      id: 'b', displayName: 'Al Smith', emails: ['b@test.com'], company: 'Acme',
+    });
+    const withCompany = dedup.similarity(a, b);
+
+    const c = makeContact({
+      id: 'c', displayName: 'Alice Smith', emails: ['a@test.com'],
+    });
+    const d = makeContact({
+      id: 'd', displayName: 'Al Smith', emails: ['b@test.com'],
+    });
+    const withoutCompany = dedup.similarity(c, d);
+
+    expect(withCompany).toBeGreaterThan(withoutCompany);
+  });
+});

package/tests/graph.test.ts

@@ -0,0 +1,104 @@
+import { describe, it, expect } from 'vitest';
+import { ContactGraph } from '../src/graph.js';
+
+function makeInput(overrides: Partial<Parameters<ContactGraph['addContact']>[0]> = {}) {
+  return {
+    displayName: 'Alice Smith',
+    emails: ['alice@example.com'],
+    sources: [{ type: 'manual' as const, sourceId: 'test', importedAt: Date.now() }],
+    ...overrides,
+  };
+}
+
+describe('ContactGraph', () => {
+  it('addContact generates ID', () => {
+    const graph = new ContactGraph();
+    const contact = graph.addContact(makeInput());
+    expect(contact.id).toBeDefined();
+    expect(typeof contact.id).toBe('string');
+    expect(contact.id.length).toBeGreaterThan(0);
+  });
+
+  it('addContact sets default relationship', () => {
+    const graph = new ContactGraph();
+    const contact = graph.addContact(makeInput());
+    expect(contact.relationship).toEqual({
+      strength: 0,
+      frequency: 0,
+      recency: Infinity,
+      context: 'unknown',
+    });
+  });
+
+  it('findByEmail finds correct contact', () => {
+    const graph = new ContactGraph();
+    graph.addContact(makeInput());
+    const found = graph.findByEmail('alice@example.com');
+    expect(found).toBeDefined();
+    expect(found!.displayName).toBe('Alice Smith');
+  });
+
+  it('findByEmail returns undefined for unknown', () => {
+    const graph = new ContactGraph();
+    graph.addContact(makeInput());
+    expect(graph.findByEmail('unknown@example.com')).toBeUndefined();
+  });
+
+  it('findByName case-insensitive match', () => {
+    const graph = new ContactGraph();
+    graph.addContact(makeInput());
+    const results = graph.findByName('alice');
+    expect(results).toHaveLength(1);
+    expect(results[0].displayName).toBe('Alice Smith');
+  });
+
+  it('search matches across fields', () => {
+    const graph = new ContactGraph();
+    graph.addContact(makeInput({ company: 'Acme Corp', tags: ['vip'] }));
+    expect(graph.search('acme')).toHaveLength(1);
+    expect(graph.search('vip')).toHaveLength(1);
+    expect(graph.search('alice')).toHaveLength(1);
+    expect(graph.search('example.com')).toHaveLength(1);
+  });
+
+  it('merge combines emails', () => {
+    const graph = new ContactGraph();
+    const c1 = graph.addContact(makeInput());
+    const c2 = graph.addContact(makeInput({
+      displayName: 'Alice S.',
+      emails: ['alice2@example.com'],
+    }));
+    const merged = graph.merge(c1.id, c2.id);
+    expect(merged.emails).toContain('alice@example.com');
+    expect(merged.emails).toContain('alice2@example.com');
+    expect(merged.displayName).toBe('Alice Smith');
+  });
+
+  it('merge removes second contact', () => {
+    const graph = new ContactGraph();
+    const c1 = graph.addContact(makeInput());
+    const c2 = graph.addContact(makeInput({
+      displayName: 'Alice S.',
+      emails: ['alice2@example.com'],
+    }));
+    graph.merge(c1.id, c2.id);
+    expect(graph.getById(c2.id)).toBeUndefined();
+    expect(graph.count()).toBe(1);
+  });
+
+  it('remove deletes contact', () => {
+    const graph = new ContactGraph();
+    const c = graph.addContact(makeInput());
+    expect(graph.remove(c.id)).toBe(true);
+    expect(graph.getById(c.id)).toBeUndefined();
+  });
+
+  it('count returns correct number', () => {
+    const graph = new ContactGraph();
+    expect(graph.count()).toBe(0);
+    graph.addContact(makeInput());
+    expect(graph.count()).toBe(1);
+    graph.addContact(makeInput({ displayName: 'Bob', emails: ['bob@example.com'] }));
+    expect(graph.count()).toBe(2);
+  });
+});