Mirror candidates

import os

import requests

BASE = "https://tahoe.workonward.com/api/partner/v1"
session = requests.Session()
session.headers["Authorization"] = f"Bearer {os.environ['TAHOE_API_KEY']}"


def backfill_applicants(store):
    cursor = None
    while True:
        params = {"limit": 100}
        if cursor:
            params["cursor"] = cursor
        response = session.get(f"{BASE}/applicants", params=params, timeout=30)
        response.raise_for_status()
        body = response.json()

        for applicant in body["data"]:
            provenance = applicant["provenance"]
            store.upsert_person(
                tahoe_id=applicant["id"],
                # "applicant" or "ats_import" here; "sourced" on /sourced-profiles.
                origin=provenance["origin"],
                full_name=applicant["full_name"],
                location=applicant["location"],
                linkedin_url=applicant["linkedin_url"],
                # Kept so a compliance question can be answered without
                # another API call.
                consent_basis=provenance["consent"]["basis"],
                unsubscribed=provenance["consent"]["unsubscribed"],
                external_refs=applicant["external_refs"],
                # No contact details here. They are fetched when needed.
                contact_state="unknown",
            )

        cursor = body["next_cursor"]
        if not cursor:
            return

def reconcile(store):
    """Match up to 100 of our own records to Tahoe people in one call."""
    batch = [
        {"kind": "linkedin_url", "value": row.linkedin_url}
        if row.linkedin_url
        else {"kind": "email", "value": row.email}
        for row in store.unmatched(limit=100)
    ]
    response = session.post(f"{BASE}/people/resolve:batch", json={"keys": batch}, timeout=30)
    response.raise_for_status()
    body = response.json()

    # Results come back IN ORDER, unmatched ones included, so pairing them
    # with the input by position is safe and nothing goes missing.
    for sent, result in zip(batch, body["data"]):
        if not result["matched"]:
            store.mark_unresolved(sent, reason=result["reason"])
            continue

        person = result["person"]
        if person["counts"]["exact_matches"] == 0:
            # Matched on email alone: probable, not certain. Ask a human.
            store.queue_for_review(sent, person["canonical_id"])
            continue

        # canonical_id, not id: the same human found by email and by LinkedIn
        # URL has two ids but one canonical_id.
        store.link_person(sent, person["canonical_id"])

def contact_for(store, applicant_id):
    """Fetch contact details at the moment a recruiter opens the record."""
    cached = store.contact(applicant_id)
    if cached and cached.fresh:
        return cached

    response = session.get(f"{BASE}/applicants/{applicant_id}/contact-info", timeout=30)
    response.raise_for_status()
    body = response.json()

    # "restricted" means Tahoe holds the value and this key may not read it.
    # Storing an empty value would record "this person has no phone", and
    # nothing would make you look again once the scope is granted.
    withheld = set(body.get("restricted") or [])

    store.save_contact(
        applicant_id,
        emails=None if "emails" in withheld else body["emails"],
        phones=None if "phones" in withheld else body["phones"],
        withheld=sorted(withheld),
        field_states=body["field_states"],
        # Never gated by scopes. If true, do not contact this person.
        unsubscribed=body["unsubscribed"],
    )
    return store.contact(applicant_id)

HANDLERS = {
    "applicant.created": reread_applicant,
    "applicant.updated": reread_applicant,
    "applicant.deleted": purge_applicant,
    # Wire this one first. It is what stops you emailing someone who asked
    # not to be contacted.
    "applicant.unsubscribed": mark_unsubscribed,

    "sourced_profile.created": reread_sourced,
    "sourced_profile.updated": reread_sourced,
    "sourced_profile.deleted": purge_sourced,
    # Names the fields that were revealed, never the values. Drop your
    # cached contact details and fetch them again when they are needed.
    "sourced_profile.contact_info_revealed": invalidate_contact_cache,

    "resume.access_changed": reread_resume_access,

    # A handle you stored is no longer the canonical one for this person.
    "person.canonical_id_changed": remap_person,

    # An instruction, not information. See the deletion guide.
    "data_subject.suppression_applied": on_data_subject_event,
    "data_subject.erasure_completed": on_data_subject_event,
}