apsimo 1.3.0__py3-none-any.whl

apsimo/contacts/identity_links.py

@@ -0,0 +1,251 @@
+"""Candidate links and exact owner corrections in the existing contact store.
+
+These functions establish attribution, never tool grants. The authenticated
+host owns caller authorization and the source-ledger correction transaction.
+"""
+import hashlib
+import json
+
+
+def _json(value):
+    return json.dumps(value, sort_keys=True, separators=(',', ':'), allow_nan=False)
+
+
+def _refs(values):
+    if not isinstance(values, (list, tuple)) or len(values) > 100:
+        raise ValueError('invalid_identity_evidence')
+    if any(not isinstance(v, str) or not v.strip() or len(v) > 256 for v in values):
+        raise ValueError('invalid_identity_evidence')
+    return sorted(set(values))
+
+
+def usable_handle(handle):
+    """Legacy name guesses are hypotheses, even before an operator migrates them."""
+    return bool(getattr(handle, 'verified', False)) or getattr(handle, 'source', '') != 'auto:scoped-name'
+
+
+def normalized_handle(gateway, address):
+    from .store import _normalize_email, _normalize_phone
+    if not isinstance(gateway, str) or not isinstance(address, str):
+        raise ValueError('invalid_identity_handle')
+    gateway, address = gateway.strip().lower(), address.strip()
+    if not gateway or len(gateway) > 64 or not address or len(address) > 512:
+        raise ValueError('invalid_identity_handle')
+    if gateway == 'rcs':
+        gateway = 'sms'
+    if gateway == 'email':
+        address = _normalize_email(address)
+    elif gateway in ('sms', 'imessage', 'signal'):
+        address = _normalize_phone(address)
+    return gateway, address
+
+
+async def propose(store, *, contact_id, gateway, address, evidence_refs=(), source='auto:scoped-name'):
+    from .store import _now_iso
+    gateway, address = normalized_handle(gateway, address)
+    refs = _refs(evidence_refs)
+    if await store.get(contact_id) is None:
+        raise ValueError('identity_contact_not_found')
+    if not isinstance(source, str) or not source or len(source) > 128:
+        raise ValueError('invalid_identity_source')
+    candidate_id = 'identity-candidate:' + hashlib.sha256(_json([contact_id, gateway, address]).encode()).hexdigest()
+    db = store._require_db()
+    await db.execute('''INSERT OR IGNORE INTO contact_identity_candidates
+        (candidate_id,contact_id,gateway,address,source,evidence_refs_json,created_at)
+        VALUES (?,?,?,?,?,?,?)''', (candidate_id, contact_id, gateway, address, source, _json(refs), _now_iso()))
+    await db.commit()
+    async with db.execute('SELECT * FROM contact_identity_candidates WHERE contact_id=? AND gateway=? AND address=?',
+                          (contact_id, gateway, address)) as cursor:
+        result = dict(await cursor.fetchone())
+    result['evidence_refs'] = json.loads(result.pop('evidence_refs_json'))
+    result['authority_granted'] = False
+    return result
+
+
+async def correct(store, *, operation_id, performed_by, gateway, address,
+                  expected_contact_id, contact_id, evidence_refs, affected_source_ids=()):
+    """Move/remove one exact handle, preserving old attribution in a durable receipt.
+
+    expected_contact_id=None means no current handle is expected. contact_id=None
+    rejects candidate links and removes the explicitly expected handle, if any.
+    The host supplies and subsequently reconciles the exact affected source IDs.
+    A lost response may repeat the operation; changed input under its ID fails.
+    """
+    from .store import _gen_id, _now_iso
+    gateway, address = normalized_handle(gateway, address)
+    refs, sources = _refs(evidence_refs), _refs(affected_source_ids)
+    if not refs:
+        raise ValueError('identity_correction_requires_evidence')
+    for value in (operation_id, performed_by):
+        if not isinstance(value, str) or not value.strip() or len(value) > 256:
+            raise ValueError('invalid_identity_correction')
+    for value in (expected_contact_id, contact_id):
+        if value is not None and (not isinstance(value, str) or not value.startswith('cid-') or len(value) > 256):
+            raise ValueError('invalid_identity_contact')
+    request_hash = hashlib.sha256(_json([operation_id, performed_by, gateway, address,
+        expected_contact_id, contact_id, refs, sources]).encode()).hexdigest()
+    db = await store._open_provision_connection()
+    try:
+        await db.execute('BEGIN IMMEDIATE')
+        async with db.execute('SELECT * FROM contact_identity_operations WHERE operation_id=?', (operation_id,)) as cur:
+            prior = await cur.fetchone()
+        if prior:
+            if prior['request_sha256'] != request_hash:
+                raise ValueError('identity_operation_conflict')
+            await db.rollback()
+            return json.loads(prior['result_json'])
+        async with db.execute('SELECT * FROM contact_handles WHERE gateway=? AND address=?', (gateway, address)) as cur:
+            handle = await cur.fetchone()
+        old_id = handle['contact_id'] if handle else None
+        if old_id != expected_contact_id:
+            raise ValueError('identity_preimage_changed')
+        if contact_id is not None:
+            async with db.execute('SELECT contact_id FROM contacts WHERE contact_id=? AND deleted_at IS NULL', (contact_id,)) as cur:
+                if await cur.fetchone() is None:
+                    raise ValueError('identity_contact_not_found')
+        now = _now_iso()
+        handle_id = handle['handle_id'] if handle else None
+        if contact_id is None:
+            if handle:
+                await db.execute('DELETE FROM contact_handles WHERE handle_id=?', (handle_id,))
+        elif handle:
+            await db.execute('''UPDATE contact_handles SET contact_id=?, verified=1,
+                confidence=1,source='owner_operator',is_primary=CASE WHEN contact_id=? THEN is_primary ELSE 0 END
+                WHERE handle_id=?''', (contact_id, contact_id, handle_id))
+        else:
+            handle_id = _gen_id('hdl')
+            await db.execute('''INSERT INTO contact_handles
+                (handle_id,contact_id,gateway,address,is_primary,verified,confidence,source,created_at)
+                VALUES (?,?,?,?,0,1,1,'owner_operator',?)''', (handle_id, contact_id, gateway, address, now))
+        await db.execute('''UPDATE contact_identity_candidates SET status=CASE WHEN contact_id=?
+            THEN 'confirmed' ELSE 'rejected' END,resolved_at=? WHERE gateway=? AND address=? AND status='pending' ''',
+            (contact_id, now, gateway, address))
+        result = {'schema': 'IdentityCorrectionV1', 'operation_id': operation_id,
+            'old_contact_id': old_id, 'contact_id': contact_id, 'handle_id': handle_id,
+            'gateway': gateway, 'address_sha256': hashlib.sha256(address.encode()).hexdigest(),
+            'evidence_refs': refs, 'affected_source_ids': sources, 'recorded_at': now,
+            'performed_by': performed_by, 'authority_granted': False,
+            'source_reconciliation_required': bool(sources)}
+        for cid in sorted({cid for cid in (old_id, contact_id) if cid}):
+            await db.execute('''INSERT INTO contact_audit
+                (id,contact_id,action,detail,performed_by,created_at) VALUES (?,?,?,?,?,?)''',
+                (_gen_id('aud'), cid, 'identity_corrected', _json(result), performed_by, now))
+        await db.execute('INSERT INTO contact_identity_operations VALUES (?,?,?,?)',
+            (operation_id, request_hash, _json(result), now))
+        await db.commit()
+    except Exception:
+        await db.rollback()
+        raise
+    finally:
+        await db.close()
+    from apsimo.identity.resolver import reset_identity_resolver
+    reset_identity_resolver()
+    return result
+
+
+async def evidence(store, contact_id):
+    if await store.get(contact_id) is None:
+        raise ValueError('identity_contact_not_found')
+    handles = await store.get_handles(contact_id)
+    db = store._require_db()
+    async with db.execute('SELECT * FROM contact_identity_candidates WHERE contact_id=? ORDER BY created_at DESC LIMIT 100', (contact_id,)) as cur:
+        candidates = [dict(row) for row in await cur.fetchall()]
+    for row in candidates:
+        row['evidence_refs'] = json.loads(row.pop('evidence_refs_json'))
+    async with db.execute('''SELECT result_json FROM contact_identity_operations
+        WHERE json_extract(result_json,'$.old_contact_id')=? OR json_extract(result_json,'$.contact_id')=?
+        ORDER BY created_at DESC,operation_id LIMIT 20''', (contact_id, contact_id)) as cur:
+        operations = [json.loads(row['result_json']) for row in await cur.fetchall()]
+    summaries = [{key: op[key] for key in ('operation_id', 'old_contact_id', 'contact_id', 'recorded_at',
+        'source_reconciliation_required')} | {
+            'source_reconciliation_status': op.get('source_reconciliation_status',
+                'pending' if op['source_reconciliation_required'] else 'complete'),
+            'source_count': len(op['affected_source_ids']), 'source_ids': op['affected_source_ids'][:10],
+            'sources_truncated': len(op['affected_source_ids']) > 10,
+            'conflict': op.get('source_reconciliation_conflict')}
+        for op in operations]
+    return {'contact_id': contact_id, 'handles': [h.to_dict() | {
+        'identity_status': 'confirmed' if h.verified else 'observed' if usable_handle(h) else 'tentative',
+        'usable_for_attribution': usable_handle(h)} for h in handles], 'candidates': candidates,
+        'operations': summaries, 'authority_granted': False}
+
+
+async def pending_reconciliations(store, *, limit=100):
+    """Recover unfinished cross-store corrections from their existing receipts."""
+    db = store._require_db()
+    async with db.execute('''SELECT result_json FROM contact_identity_operations
+        WHERE json_extract(result_json,'$.source_reconciliation_required')=1
+        AND coalesce(json_extract(result_json,'$.source_reconciliation_status'),'pending')!='conflicted'
+        ORDER BY created_at,operation_id LIMIT ?''', (max(1, min(int(limit), 500)),)) as cur:
+        return [json.loads(row['result_json']) for row in await cur.fetchall()]
+
+
+async def mark_sources_reconciled(store, *, operation_id, source_result):
+    """Finish an exact source correction without introducing a second queue."""
+    db = await store._open_provision_connection()
+    try:
+        await db.execute('BEGIN IMMEDIATE')
+        async with db.execute('SELECT result_json FROM contact_identity_operations WHERE operation_id=?', (operation_id,)) as cur:
+            row = await cur.fetchone()
+        if row is None:
+            raise ValueError('identity_operation_not_found')
+        result = json.loads(row['result_json'])
+        if (source_result.get('schema') != 'SourceAttributionCorrectionV1'
+                or source_result.get('operation_id') != operation_id
+                or source_result.get('old_contact_id') != result['old_contact_id']
+                or source_result.get('contact_id') != result['contact_id']
+                or sorted(source_result.get('source_ids', [])) != sorted(result['affected_source_ids'])):
+            raise ValueError('identity_reconciliation_mismatch')
+        summary = {key: source_result[key] for key in ('operation_id', 'source_ids',
+            'affected_source_ids', 'invalidated_source_ids', 'recorded_at')}
+        if not result['source_reconciliation_required']:
+            if result.get('source_reconciliation') != summary:
+                raise ValueError('identity_reconciliation_conflict')
+            await db.rollback()
+            return result
+        result['source_reconciliation_required'] = False
+        result['source_reconciliation_status'] = 'complete'
+        result.pop('source_reconciliation_conflict', None)
+        result['source_reconciliation'] = summary
+        await db.execute('UPDATE contact_identity_operations SET result_json=? WHERE operation_id=?',
+                         (_json(result), operation_id))
+        await db.commit()
+        return result
+    except Exception:
+        await db.rollback()
+        raise
+    finally:
+        await db.close()
+
+
+async def mark_sources_conflicted(store, *, operation_id, code):
+    """Retain a permanent conflict for inspection without retrying it forever."""
+    from .store import _now_iso
+    if code not in {'source_erased', 'source_attribution_preimage_changed'}:
+        raise ValueError('invalid_identity_reconciliation_conflict')
+    db = await store._open_provision_connection()
+    try:
+        await db.execute('BEGIN IMMEDIATE')
+        async with db.execute('SELECT result_json FROM contact_identity_operations WHERE operation_id=?', (operation_id,)) as cur:
+            row = await cur.fetchone()
+        if row is None:
+            raise ValueError('identity_operation_not_found')
+        result = json.loads(row['result_json'])
+        if not result['source_reconciliation_required']:
+            raise ValueError('identity_reconciliation_already_complete')
+        if result.get('source_reconciliation_status') == 'conflicted':
+            if result['source_reconciliation_conflict']['code'] != code:
+                raise ValueError('identity_reconciliation_conflict_changed')
+            await db.rollback()
+            return result
+        result['source_reconciliation_status'] = 'conflicted'
+        result['source_reconciliation_conflict'] = {'code': code, 'recorded_at': _now_iso()}
+        await db.execute('UPDATE contact_identity_operations SET result_json=? WHERE operation_id=?',
+                         (_json(result), operation_id))
+        await db.commit()
+        return result
+    except Exception:
+        await db.rollback()
+        raise
+    finally:
+        await db.close()

apsimo/contacts/importer.py

@@ -0,0 +1,280 @@
+"""Colony Contacts — import pipeline."""
+
+from __future__ import annotations
+
+import csv
+import hashlib
+import io
+import logging
+import re
+from abc import ABC, abstractmethod
+from typing import List, Optional
+
+from .config import ContactsConfig
+from .importers.batch import BatchImportResult, ImportOutcome, ImportRecord
+from .importers.macos_contacts import RawContactRecord
+from .store import SQLiteContactStore, _normalize_phone, _normalize_email, _gen_id
+
+logger = logging.getLogger("colony.contacts.importer")
+
+
+def _pii_hash(value: Optional[str]) -> str:
+    """Short hash for PII-safe log correlation (never log raw contact data)."""
+    if not value:
+        return "∅"
+    return hashlib.sha256(value.encode("utf-8")).hexdigest()[:8]
+
+# vCard property pattern
+_VCARD_PROP = re.compile(r'^([A-Z\-]+)(?:;[^:]*)?:(.*)$')
+
+
+def _parse_vcard(vcard_data: str) -> List[RawContactRecord]:
+    """Parse one or more vCard 4.0 entries into RawContactRecord objects."""
+    records: List[RawContactRecord] = []
+    current: Optional[dict] = None
+    for line in vcard_data.splitlines():
+        line = line.strip()
+        if line.upper() == "BEGIN:VCARD":
+            current = {"phones": [], "emails": [], "given": None, "family": None, "org": None, "fn": None}
+        elif line.upper() == "END:VCARD" and current is not None:
+            given = current["given"]
+            family = current["family"]
+            display = current["fn"] or (" ".join(p for p in [given, family] if p) or None)
+            if not given and display:
+                parts = display.split(None, 1)
+                given = parts[0] if parts else None
+                family = parts[1] if len(parts) > 1 else None
+            records.append(RawContactRecord(
+                given_name=given,
+                family_name=family,
+                organization=current["org"],
+                phone_numbers=current["phones"],
+                email_addresses=current["emails"],
+                source="vcard",
+            ))
+            current = None
+        elif current is not None:
+            m = _VCARD_PROP.match(line)
+            if not m:
+                continue
+            prop, val = m.group(1).upper(), m.group(2).strip()
+            if prop == "FN":
+                current["fn"] = val
+            elif prop == "N":
+                parts = val.split(";")
+                current["family"] = parts[0] if parts else None
+                current["given"] = parts[1] if len(parts) > 1 else None
+            elif prop in ("TEL", "X-TEL") or prop.startswith("TEL"):
+                if val:
+                    current["phones"].append(val)
+            elif prop == "EMAIL":
+                if val:
+                    current["emails"].append(val.lower())
+            elif prop == "ORG":
+                current["org"] = val
+    return records
+
+
+def _parse_csv(csv_data: str, source: str) -> List[RawContactRecord]:
+    """Parse a CSV string into RawContactRecord objects."""
+    records: List[RawContactRecord] = []
+    reader = csv.DictReader(io.StringIO(csv_data))
+    for row in reader:
+        # Support common column names
+        given = row.get("given_name") or row.get("First Name") or row.get("first_name") or None
+        family = row.get("family_name") or row.get("Last Name") or row.get("last_name") or None
+        org = row.get("organization") or row.get("Organization") or row.get("Company") or None
+        phone_raw = row.get("phone") or row.get("Phone") or row.get("primary_phone") or ""
+        email_raw = row.get("email") or row.get("Email") or row.get("primary_email") or ""
+        phones = [p.strip() for p in phone_raw.split("|") if p.strip()] if phone_raw else []
+        emails = [e.strip().lower() for e in email_raw.split("|") if e.strip()] if email_raw else []
+        if not given and not family and not phones and not emails:
+            continue
+        records.append(RawContactRecord(
+            given_name=given or None,
+            family_name=family or None,
+            organization=org or None,
+            phone_numbers=phones,
+            email_addresses=emails,
+            source=source,
+        ))
+    return records
+
+
+# ── Abstract interface ────────────────────────────────────────────────────────
+
+class ContactImporter(ABC):
+    """Orchestrates contact import from any source through deduplication."""
+
+    @abstractmethod
+    async def import_raw(self, records: List[RawContactRecord], source: str) -> BatchImportResult:
+        """Import a list of RawContactRecord objects through dedup pipeline."""
+
+    @abstractmethod
+    async def import_from_macos_contacts(self) -> BatchImportResult:
+        """Import all contacts from the macOS Contacts framework."""
+
+    @abstractmethod
+    async def import_from_vcard(self, vcard_data: str) -> BatchImportResult:
+        """Import contacts from a vCard 4.0 string."""
+
+    @abstractmethod
+    async def import_from_csv(self, csv_data: str, source: str = "csv") -> BatchImportResult:
+        """Import contacts from a UTF-8 CSV string."""
+
+
+# ── SQLite-backed implementation ──────────────────────────────────────────────
+
+class SQLiteContactImporter(ContactImporter):
+    """ContactImporter backed by SQLiteContactStore."""
+
+    def __init__(
+        self,
+        store: SQLiteContactStore,
+        config: Optional[ContactsConfig] = None,
+        bridge = None,  # Optional[WorldModelContactBridge]
+    ) -> None:
+        self._store = store
+        self._config = config or ContactsConfig()
+        self._bridge = bridge
+
+    async def import_raw(self, records: List[RawContactRecord], source: str) -> BatchImportResult:
+        result = BatchImportResult(source=source, total=len(records))
+        for raw in records:
+            display_name = raw.display_name
+            try:
+                # Normalize addresses
+                norm_phones = [_normalize_phone(p) for p in raw.phone_numbers if p]
+                norm_emails = [_normalize_email(e) for e in raw.email_addresses if e]
+
+                # Run dedup check
+                candidates = await self._store.find_dedup_candidates(
+                    raw.given_name, raw.family_name, norm_phones, norm_emails
+                )
+
+                auto_threshold = self._config.auto_merge_confidence_threshold
+                proposal_threshold = self._config.merge_proposal_threshold
+
+                async def _attach(contact_id: str, kind: str, value: str, confidence: Optional[float]) -> None:
+                    try:
+                        kwargs = {"source": raw.source}
+                        if confidence is not None:
+                            kwargs["confidence"] = confidence
+                        await self._store.add_handle(contact_id, kind, value, **kwargs)
+                    except ValueError:
+                        # Handle already owned by a different contact; store
+                        # resolves ownership separately. Count the conflict
+                        # so callers see lossy merges, and log a redacted
+                        # correlation hash only — never raw PII.
+                        result.handle_conflicts += 1
+                        logger.debug(
+                            "contact handle conflict: kind=%s value_hash=%s name_hash=%s",
+                            kind, _pii_hash(value), _pii_hash(display_name),
+                        )
+
+                if candidates and candidates[0][0] >= auto_threshold:
+                    # High-confidence match — merge handles into existing contact
+                    conf, existing_id, reason = candidates[0]
+                    for phone in norm_phones:
+                        await _attach(existing_id, "imessage", phone, conf)
+                    for email in norm_emails:
+                        await _attach(existing_id, "email", email, conf)
+                    result.merged += 1
+                    result.records.append(ImportRecord(
+                        raw_display_name=display_name,
+                        outcome=ImportOutcome.MERGED,
+                        contact_id=existing_id,
+                        merged_into_id=existing_id,
+                    ))
+                    # Absorb any discovered contacts with overlapping handles
+                    if self._bridge:
+                        await self._absorb_discovered_for(existing_id, norm_phones, norm_emails)
+                elif candidates and candidates[0][0] >= proposal_threshold:
+                    # Below auto-merge but above proposal threshold — create and propose
+                    contact = await self._store.create(
+                        display_name=display_name,
+                        given_name=raw.given_name,
+                        family_name=raw.family_name,
+                        organization=raw.organization,
+                        import_source=raw.source,
+                    )
+                    for phone in norm_phones:
+                        await _attach(contact.contact_id, "imessage", phone, None)
+                    for email in norm_emails:
+                        await _attach(contact.contact_id, "email", email, None)
+                    # Queue merge proposal (handled by merger)
+                    result.created += 1
+                    result.records.append(ImportRecord(
+                        raw_display_name=display_name,
+                        outcome=ImportOutcome.CREATED,
+                        contact_id=contact.contact_id,
+                    ))
+                    if self._bridge:
+                        await self._absorb_discovered_for(contact.contact_id, norm_phones, norm_emails)
+                else:
+                    # No match — create new contact
+                    contact = await self._store.create(
+                        display_name=display_name,
+                        given_name=raw.given_name,
+                        family_name=raw.family_name,
+                        organization=raw.organization,
+                        import_source=raw.source,
+                    )
+                    for phone in norm_phones:
+                        await _attach(contact.contact_id, "imessage", phone, None)
+                    for email in norm_emails:
+                        await _attach(contact.contact_id, "email", email, None)
+                    result.created += 1
+                    result.records.append(ImportRecord(
+                        raw_display_name=display_name,
+                        outcome=ImportOutcome.CREATED,
+                        contact_id=contact.contact_id,
+                    ))
+                    if self._bridge:
+                        await self._absorb_discovered_for(contact.contact_id, norm_phones, norm_emails)
+            except Exception as exc:
+                logger.warning(
+                    "Failed to import record (name_hash=%s): %s",
+                    _pii_hash(display_name), type(exc).__name__,
+                )
+                result.failed += 1
+                result.records.append(ImportRecord(
+                    raw_display_name=display_name,
+                    outcome=ImportOutcome.FAILED,
+                    error=type(exc).__name__,
+                ))
+        return result
+
+    async def _absorb_discovered_for(
+        self,
+        curated_contact_id: str,
+        norm_phones: List[str],
+        norm_emails: List[str],
+    ) -> None:
+        """Find discovered contacts with overlapping handles and absorb them."""
+        if not self._bridge:
+            return
+        for phone in norm_phones:
+            discovered = await self._store.find_discovered_by_handle("imessage", phone)
+            if discovered:
+                await self._bridge.absorb_discovered_contact(curated_contact_id, discovered)
+                return
+        for email in norm_emails:
+            discovered = await self._store.find_discovered_by_handle("email", email)
+            if discovered:
+                await self._bridge.absorb_discovered_contact(curated_contact_id, discovered)
+                return
+
+    async def import_from_macos_contacts(self) -> BatchImportResult:
+        from .importers.macos_contacts import MacOSContactsImporter
+        importer = MacOSContactsImporter(normalize_phones=self._config.import_cfg.normalize_phones)
+        raw_records = importer.fetch_all()
+        return await self.import_raw(raw_records, "ios_contacts")
+
+    async def import_from_vcard(self, vcard_data: str) -> BatchImportResult:
+        records = _parse_vcard(vcard_data)
+        return await self.import_raw(records, "vcard")
+
+    async def import_from_csv(self, csv_data: str, source: str = "csv") -> BatchImportResult:
+        records = _parse_csv(csv_data, source)
+        return await self.import_raw(records, source)

apsimo/contacts/importers/__init__.py

@@ -0,0 +1 @@
+"""Colony Contacts importers."""

apsimo/contacts/importers/batch.py

@@ -0,0 +1,43 @@
+"""Batch import result types."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import List, Optional
+
+
+class ImportOutcome(str, Enum):
+    CREATED = "created"
+    MERGED = "merged"
+    SKIPPED = "skipped"
+    FAILED = "failed"
+
+
+@dataclass
+class ImportRecord:
+    """Result for a single record in a batch import."""
+    raw_display_name: Optional[str]
+    outcome: ImportOutcome
+    contact_id: Optional[str] = None       # set on CREATED or MERGED
+    merged_into_id: Optional[str] = None   # set on MERGED
+    error: Optional[str] = None            # set on FAILED
+
+
+@dataclass
+class BatchImportResult:
+    """Summary of a completed batch import operation."""
+    source: str
+    total: int
+    created: int = 0
+    merged: int = 0
+    skipped: int = 0
+    failed: int = 0
+    handle_conflicts: int = 0
+    records: List[ImportRecord] = field(default_factory=list)
+
+    @property
+    def success_rate(self) -> float:
+        if self.total == 0:
+            return 1.0
+        return (self.created + self.merged + self.skipped) / self.total

apsimo/contacts/importers/macos_contacts.py

@@ -0,0 +1,101 @@
+"""macOS Contacts framework importer."""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass, field
+from typing import List, Optional
+
+logger = logging.getLogger("colony.contacts.importers.macos_contacts")
+
+
+@dataclass
+class RawContactRecord:
+    """A contact record extracted from the macOS Contacts framework.
+
+    Intermediate representation before deduplication and persistence.
+    """
+    given_name: Optional[str]
+    family_name: Optional[str]
+    organization: Optional[str]
+    phone_numbers: List[str] = field(default_factory=list)   # E.164-normalized where possible
+    email_addresses: List[str] = field(default_factory=list)
+    source: str = "ios_contacts"
+
+    @property
+    def display_name(self) -> Optional[str]:
+        parts = [self.given_name, self.family_name]
+        name = " ".join(p for p in parts if p)
+        return name or self.organization or None
+
+
+class MacOSContactsImporter:
+    """Imports contacts from the macOS Contacts framework.
+
+    Requires pyobjc-framework-Contacts and macOS Contacts permission.
+    If permission is denied or the framework is unavailable, raises ImportError
+    with a descriptive message rather than silently returning an empty list.
+
+    Args:
+        normalize_phones: If True, attempt E.164 normalization of phone numbers.
+    """
+
+    def __init__(self, normalize_phones: bool = True) -> None:
+        self._normalize = normalize_phones
+        self._cn = self._load_framework()
+
+    def _load_framework(self):
+        try:
+            import Contacts  # type: ignore  # pyobjc
+            return Contacts
+        except ImportError as exc:
+            raise ImportError(
+                "pyobjc-framework-Contacts is required for macOS Contacts import. "
+                "Install it with: pip install pyobjc-framework-Contacts"
+            ) from exc
+
+    def fetch_all(self) -> List[RawContactRecord]:
+        """Fetch all contacts from the macOS Contacts store.
+
+        Returns:
+            List of RawContactRecord objects.
+
+        Raises:
+            PermissionError: If Contacts access has not been granted.
+            ImportError:     If the Contacts framework is unavailable.
+        """
+        CN = self._cn
+        store = CN.CNContactStore.alloc().init()
+        keys = [
+            CN.CNContactGivenNameKey,
+            CN.CNContactFamilyNameKey,
+            CN.CNContactOrganizationNameKey,
+            CN.CNContactPhoneNumbersKey,
+            CN.CNContactEmailAddressesKey,
+        ]
+        fetch_request = CN.CNContactFetchRequest.alloc().initWithKeysToFetch_(keys)
+        records: List[RawContactRecord] = []
+
+        def handler(contact, _stop):
+            phones = [
+                v.value().stringValue()
+                for v in (contact.phoneNumbers() or [])
+            ]
+            emails = [
+                str(v.value())
+                for v in (contact.emailAddresses() or [])
+            ]
+            records.append(RawContactRecord(
+                given_name=str(contact.givenName()) or None,
+                family_name=str(contact.familyName()) or None,
+                organization=str(contact.organizationName()) or None,
+                phone_numbers=phones,
+                email_addresses=emails,
+            ))
+
+        error = None
+        store.enumerateContactsWithFetchRequest_error_usingBlock_(
+            fetch_request, error, handler
+        )
+        logger.info("Fetched %d contacts from macOS Contacts", len(records))
+        return records