dhisana 0.0.1.dev85__py3-none-any.whl → 0.0.1.dev236__py3-none-any.whl

dhisana/utils/hubspot_crm_tools.py

@@ -1,16 +1,25 @@
+from __future__ import annotations
+
+# ─── Standard library ──────────────────────────────────────────────────────────
+import html
 import json
 import os
-import aiohttp
-from typing import Optional, List, Dict, Any
-from pydantic import BaseModel
+import time
+from typing import Any, Dict, List, Optional, Union
 from urllib.parse import urlparse
+
+# ─── Third-party packages ──────────────────────────────────────────────────────
+import aiohttp
+from bs4 import BeautifulSoup
 from fastapi import Query
+from markdown import markdown
+from pydantic import BaseModel
 
+# ─── Internal / application imports ────────────────────────────────────────────
 from dhisana.schemas.sales import HUBSPOT_TO_LEAD_MAPPING, HubSpotLeadInformation
 from dhisana.utils.assistant_tool_tag import assistant_tool
 from dhisana.utils.clean_properties import cleanup_properties
-from typing import Union
-
+import logging
 
 # --------------------------------------------------------------------
 # 1. Retrieve HubSpot Access Token
@@ -18,6 +27,9 @@ from typing import Union
 def get_hubspot_access_token(tool_config: Optional[List[Dict]] = None) -> str:
     """
     Retrieves the HubSpot access token from the provided tool configuration.
+
+    Raises:
+        ValueError: If the HubSpot integration has not been configured.
     """
     if tool_config:
         hubspot_config = next(
@@ -29,7 +41,12 @@ def get_hubspot_access_token(tool_config: Optional[List[Dict]] = None) -> str:
                 for item in hubspot_config.get("configuration", [])
                 if item
             }
-            HUBSPOT_ACCESS_TOKEN = config_map.get("apiKey")
+            # Check for OAuth access token in nested oauth_tokens structure first, then fall back to API key
+            oauth_tokens = config_map.get("oauth_tokens")
+            if oauth_tokens and isinstance(oauth_tokens, dict):
+                HUBSPOT_ACCESS_TOKEN = oauth_tokens.get("access_token")
+            else:
+                HUBSPOT_ACCESS_TOKEN = config_map.get("access_token") or config_map.get("apiKey")
         else:
             HUBSPOT_ACCESS_TOKEN = None
     else:
@@ -37,7 +54,9 @@ def get_hubspot_access_token(tool_config: Optional[List[Dict]] = None) -> str:
 
     HUBSPOT_ACCESS_TOKEN = HUBSPOT_ACCESS_TOKEN or os.getenv("HUBSPOT_API_KEY")
     if not HUBSPOT_ACCESS_TOKEN:
-        raise ValueError("HubSpot access token not found in tool_config or environment variable")
+        raise ValueError(
+            "HubSpot integration is not configured. Please configure the connection to HubSpot in Integrations."
+        )
     return HUBSPOT_ACCESS_TOKEN
 
 
@@ -928,96 +947,6 @@ async def update_hubspot_company_info(
         return updated_data
 
 
-# --------------------------------------------------------------------
-# 4) Create a HubSpot Note for a Customer (via V3)
-#    - If customer_id is None but email is provided, search for contact ID by email.
-#    - Then create a "note" object and associate it with the contact.
-# --------------------------------------------------------------------
-@assistant_tool
-async def create_hubspot_note_for_customer(
-    customer_id: str = None,
-    email: str = None,
-    note: str = None,
-    tool_config: Optional[List[Dict]] = None
-):
-    """
-    Create and attach a note (v3) to a customer (contact) in HubSpot using the customer's ID or email.
-    """
-    HUBSPOT_API_KEY = get_hubspot_access_token(tool_config)
-    if not (customer_id or email):
-        raise ValueError("Either 'customer_id' or 'email' must be provided.")
-    if not note:
-        raise ValueError("Note content must be provided.")
-
-    headers = {
-        "Authorization": f"Bearer {HUBSPOT_API_KEY}",
-        "Content-Type": "application/json"
-    }
-
-    async with aiohttp.ClientSession() as session:
-        # ---------------------------------------------------------
-        # 1) If no contact ID, lookup by email
-        # ---------------------------------------------------------
-        if not customer_id:
-            search_url = "https://api.hubapi.com/crm/v3/objects/contacts/search"
-            search_payload = {
-                "filterGroups": [
-                    {
-                        "filters": [
-                            {"propertyName": "email", "operator": "EQ", "value": email}
-                        ]
-                    }
-                ],
-                "limit": 1
-            }
-            async with session.post(search_url, headers=headers, json=search_payload) as resp:
-                data = await resp.json()
-                if resp.status != 200:
-                    raise Exception(f"Error searching contact by email: {resp.status} => {data}")
-
-                results = data.get("results", [])
-                if not results:
-                    raise Exception(f"No contact found with email '{email}'.")
-                customer_id = results[0]["id"]
-
-        # ---------------------------------------------------------
-        # 2) Create a note object with association to the contact
-        #    In V3, "notes" is a standard object type. 
-        #    We specify "hs_note_body" in properties, plus associations.
-        #
-        #    The correct associationTypeId for "note -> contact" can vary,
-        #    but typically "180" or "280." This can be verified via 
-        #    GET /crm/v3/associations/Note/Contact (or see docs).
-        #    We'll assume "280" here as an example.
-        # ---------------------------------------------------------
-        create_note_url = "https://api.hubapi.com/crm/v3/objects/notes"
-        note_payload = {
-            "properties": {
-                "hs_note_body": note
-            },
-            "associations": [
-                {
-                    "to": {
-                        "id": customer_id,
-                        "type": "contact"
-                    },
-                    "types": [
-                        {
-                            "associationCategory": "HUBSPOT_DEFINED",
-                            "associationTypeId": 280
-                        }
-                    ]
-                }
-            ]
-        }
-        async with session.post(create_note_url, headers=headers, json=note_payload) as resp:
-            created_note = await resp.json()
-            if resp.status != 201:
-                raise Exception(f"Error creating note: {resp.status} => {created_note}")
-
-        return created_note
-
-
 # --------------------------------------------------------------------
 # 5) Get Last N Notes for a Customer (via V3)
 #    - If customer_id is None but email is provided, find contact ID
@@ -1130,6 +1059,154 @@ async def get_last_n_notes_for_customer(
         return full_notes[:n]
 
 
+# --------------------------------------------------------------------
+# 5b) Get Last N Call Logs for a Lead (via V3)
+#     - Use lead information to look up the contact by email or by
+#       firstname/lastname and company name
+#     - Then list associated calls from /contacts/{id}/associations/calls
+#     - Sort by created date descending and return the top n
+# --------------------------------------------------------------------
+@assistant_tool
+async def get_last_n_calls_for_lead(
+    lead_info: HubSpotLeadInformation,
+    n: int = 5,
+    tool_config: Optional[List[Dict]] = None,
+):
+    """
+    Retrieve the last ``n`` call log records for a contact in HubSpot
+    based on provided ``lead_info`` (email or name & company).
+    """
+
+    HUBSPOT_API_KEY = get_hubspot_access_token(tool_config)
+    if not lead_info:
+        raise ValueError("lead_info must be provided")
+
+    headers = {
+        "Authorization": f"Bearer {HUBSPOT_API_KEY}",
+        "Content-Type": "application/json",
+    }
+
+    async with aiohttp.ClientSession() as session:
+        # -------------------------------------------------------------
+        # 1) Find contact ID via email or name/company
+        # -------------------------------------------------------------
+        search_url = "https://api.hubapi.com/crm/v3/objects/contacts/search"
+        if lead_info.email:
+            search_payload = {
+                "filterGroups": [
+                    {
+                        "filters": [
+                            {
+                                "propertyName": "email",
+                                "operator": "EQ",
+                                "value": lead_info.email,
+                            }
+                        ]
+                    }
+                ],
+                "limit": 1,
+            }
+        else:
+            filters = []
+            if lead_info.first_name:
+                filters.append(
+                    {
+                        "propertyName": "firstname",
+                        "operator": "EQ",
+                        "value": lead_info.first_name,
+                    }
+                )
+            if lead_info.last_name:
+                filters.append(
+                    {
+                        "propertyName": "lastname",
+                        "operator": "EQ",
+                        "value": lead_info.last_name,
+                    }
+                )
+            if lead_info.organization_name:
+                filters.append(
+                    {
+                        "propertyName": "company",
+                        "operator": "EQ",
+                        "value": lead_info.organization_name,
+                    }
+                )
+            if not filters:
+                raise ValueError(
+                    "lead_info must include email or name and company information"
+                )
+            search_payload = {"filterGroups": [{"filters": filters}], "limit": 1}
+
+        async with session.post(
+            search_url, headers=headers, json=search_payload
+        ) as resp:
+            data = await resp.json()
+            if resp.status != 200:
+                raise Exception(
+                    f"Error searching contact by lead info: {resp.status} => {data}"
+                )
+
+            results = data.get("results", [])
+            if not results:
+                raise Exception("No contact found with the provided lead information")
+            contact_id = results[0]["id"]
+
+        # -------------------------------------------------------------
+        # 2) Fetch associated calls
+        # -------------------------------------------------------------
+        assoc_url = (
+            f"https://api.hubapi.com/crm/v3/objects/contacts/{contact_id}/associations/calls"
+        )
+        calls = []
+        after = None
+        while True:
+            params = {"limit": 100}
+            if after:
+                params["after"] = after
+
+            async with session.get(assoc_url, headers=headers, params=params) as resp:
+                assoc_data = await resp.json()
+                if resp.status != 200:
+                    raise Exception(
+                        f"Error fetching contact->calls associations: {resp.status} => {assoc_data}"
+                    )
+
+                calls.extend(assoc_data.get("results", []))
+                after = assoc_data.get("paging", {}).get("next", {}).get("after")
+
+            if not after:
+                break
+
+        if not calls:
+            return []
+
+        call_ids = [c["id"] for c in calls]
+        batch_url = "https://api.hubapi.com/crm/v3/objects/calls/batch/read"
+        payload = {
+            "properties": [
+                "hs_call_title",
+                "hs_call_body",
+                "hs_createdate",
+                "hs_call_duration",
+            ],
+            "inputs": [{"id": cid} for cid in call_ids],
+        }
+        async with session.post(batch_url, headers=headers, json=payload) as resp:
+            batch_data = await resp.json()
+            if resp.status != 200:
+                raise Exception(
+                    f"Error batch-reading calls: {resp.status} => {batch_data}"
+                )
+
+        full_calls = batch_data.get("results", [])
+        full_calls.sort(
+            key=lambda x: x.get("properties", {}).get("hs_createdate", ""),
+            reverse=True,
+        )
+        return full_calls[:n]
+
+
 # --------------------------------------------------------------------
 # 6) Fetch HubSpot Contact Associations (via V3)
 #    - e.g., fetch a contact's associated companies, deals, tickets, etc.
@@ -1237,7 +1314,7 @@ async def fetch_hubspot_lead_info(
                 })
             if linkedin_url:
                 filters.append({
-                    "propertyName": "linkedin_url", "operator": "EQ", "value": linkedin_url
+                    "propertyName": "hs_linkedin_url", "operator": "EQ", "value": linkedin_url
                 })
             if phone_number:
                 filters.append({
@@ -1254,7 +1331,7 @@ async def fetch_hubspot_lead_info(
                         "filters": filters
                     }
                 ],
-                "properties": ["firstname","lastname","email","phone","linkedin_url"],
+                "properties": ["firstname","lastname","email","phone","hs_linkedin_url"],
                 "limit": 1
             }
 
@@ -1306,16 +1383,17 @@ async def fetch_hubspot_lead_info(
 
 
 # --------------------------------------------------------------------
-# 2) Fetch HubSpot Contact Info (V3)
+# 2) Fetch HubSpot Contact Info (V3) with optional custom tags
 # --------------------------------------------------------------------
 @assistant_tool
 async def fetch_hubspot_contact_info(
     hubspot_id: str = None,
     email: str = None,
-    tool_config: Optional[List[Dict]] = None
+    tool_config: Optional[List[Dict]] = None,
+    custom_tag_property_name: str = None
 ):
     """
-    Fetch contact information from HubSpot, including associated companies, notes, tasks, calls, meetings, etc. (v3).
+    Fetch contact information from HubSpot, including associated companies, notes, tasks, calls, meetings, and optionally custom tags.
     """
     HUBSPOT_API_KEY = get_hubspot_access_token(tool_config)
     if not hubspot_id and not email:
@@ -1326,6 +1404,11 @@ async def fetch_hubspot_contact_info(
         "Content-Type": "application/json"
     }
 
+    # Prepare base properties list
+    base_properties = ["email", "firstname", "lastname", "phone", "hs_linkedin_url"]
+    if custom_tag_property_name:
+        base_properties.append(custom_tag_property_name)
+
     contact_info = None
 
     async with aiohttp.ClientSession() as session:
@@ -1334,11 +1417,11 @@ async def fetch_hubspot_contact_info(
         # ---------------------------------------------------------
         if hubspot_id:
             url = f"https://api.hubapi.com/crm/v3/objects/contacts/{hubspot_id}"
-            params = {"properties": "email,firstname,lastname,phone"}
+            params = {"properties": ",".join(base_properties)}
             async with session.get(url, headers=headers, params=params) as resp:
-                data = await resp.json()
                 if resp.status != 200:
-                    raise Exception(f"Error fetching contact by ID: {resp.status} => {data}")
+                    return None
+                data = await resp.json()
                 contact_info = data
         else:
             # -----------------------------------------------------
@@ -1353,7 +1436,7 @@ async def fetch_hubspot_contact_info(
                         ]
                     }
                 ],
-                "properties": ["email", "firstname", "lastname", "phone"],
+                "properties": base_properties,
                 "limit": 1
             }
             async with session.post(search_url, headers=headers, json=payload) as resp:
@@ -1368,72 +1451,25 @@ async def fetch_hubspot_contact_info(
 
         contact_id = contact_info["id"]
 
-        # ---------------------------------------------------------
-        # 3) Fetch associated companies
-        # ---------------------------------------------------------
-        assoc_comp_url = f"https://api.hubapi.com/crm/v3/objects/contacts/{contact_id}/associations/companies"
-        async with session.get(assoc_comp_url, headers=headers) as resp:
-            companies_data = await resp.json()
-            if resp.status == 200:
-                contact_info["companies"] = companies_data.get("results", [])
-            else:
-                contact_info["companies"] = []
-
-        # ---------------------------------------------------------
-        # 4) Fetch associated notes
-        # ---------------------------------------------------------
-        assoc_notes_url = f"https://api.hubapi.com/crm/v3/objects/contacts/{contact_id}/associations/notes"
-        async with session.get(assoc_notes_url, headers=headers) as resp:
-            notes_data = await resp.json()
-            if resp.status == 200:
-                contact_info["notes"] = notes_data.get("results", [])
-            else:
-                contact_info["notes"] = []
-
-        # ---------------------------------------------------------
-        # 5) Fetch associated tasks
-        # ---------------------------------------------------------
-        assoc_tasks_url = f"https://api.hubapi.com/crm/v3/objects/contacts/{contact_id}/associations/tasks"
-        async with session.get(assoc_tasks_url, headers=headers) as resp:
-            tasks_data = await resp.json()
-            if resp.status == 200:
-                contact_info["tasks"] = tasks_data.get("results", [])
-            else:
-                contact_info["tasks"] = []
-
-        # ---------------------------------------------------------
-        # 6) Fetch associated calls
-        # ---------------------------------------------------------
-        assoc_calls_url = f"https://api.hubapi.com/crm/v3/objects/contacts/{contact_id}/associations/calls"
-        async with session.get(assoc_calls_url, headers=headers) as resp:
-            calls_data = await resp.json()
-            if resp.status == 200:
-                contact_info["calls"] = calls_data.get("results", [])
-            else:
-                contact_info["calls"] = []
-
-        # ---------------------------------------------------------
-        # 7) Fetch associated meetings
-        # ---------------------------------------------------------
-        assoc_meetings_url = f"https://api.hubapi.com/crm/v3/objects/contacts/{contact_id}/associations/meetings"
-        async with session.get(assoc_meetings_url, headers=headers) as resp:
-            meetings_data = await resp.json()
-            if resp.status == 200:
-                contact_info["meetings"] = meetings_data.get("results", [])
-            else:
-                contact_info["meetings"] = []
+        # Utility to fetch associated object
+        async def fetch_associated_objects(object_type: str):
+            url = f"https://api.hubapi.com/crm/v3/objects/contacts/{contact_id}/associations/{object_type}"
+            async with session.get(url, headers=headers) as resp:
+                data = await resp.json()
+                if resp.status == 200:
+                    return data.get("results", [])
+                return []
 
-        # ---------------------------------------------------------
-        # (Optional) for "emails" object or email engagement
-        # The v1 email events endpoint was historically used. 
-        # If you have the new "emails" object, you can do:
-        # assoc_emails_url = f"https://api.hubapi.com/crm/v3/objects/contacts/{contact_id}/associations/emails"
-        # ... similar approach ...
-        # ---------------------------------------------------------
+        contact_info["companies"] = await fetch_associated_objects("companies")
+        contact_info["notes"] = await fetch_associated_objects("notes")
+        contact_info["tasks"] = await fetch_associated_objects("tasks")
+        contact_info["calls"] = await fetch_associated_objects("calls")
+        contact_info["meetings"] = await fetch_associated_objects("meetings")
 
         return contact_info
 
 
+
 # --------------------------------------------------------------------
 # 3) Fetch Last N Activities for a Contact (V3 version)
 #    "Activities" typically means calls, tasks, notes, meetings, emails, ...
@@ -1834,3 +1870,571 @@ async def lookup_contact_by_email(
     contact_properties = contact_record.get("properties", {})
     transformed = transform_hubspot_contact_to_lead_info(contact_properties)
     return transformed
+
+
+
+
+
+
+# ──────────────────────────────────────────────────────────────────────────────
+# Utility helpers
+# ──────────────────────────────────────────────────────────────────────────────
+def md_to_html(md: str) -> str:
+    """Render Markdown to HTML that HubSpot notes can display."""
+    return markdown(md, extensions=["extra", "sane_lists"])
+
+
+def html_to_text(html_str: str) -> str:
+    """Strip tags so the value is safe for a plain-text HS property."""
+    return BeautifulSoup(html_str, "html.parser").get_text("\n")
+
+
+def build_note_html(cv: Dict[str, Any]) -> str:
+    """Create a neat, labelled HTML block for the HubSpot note body."""
+    parts: List[str] = []
+    parts.append("<p><strong>Dhisana AI Lead Research & Engagement Summary</strong></p>")
+
+    def para(label: str, val: Optional[str]):
+        if val:
+            parts.append(
+                f"<p><strong>{html.escape(label)}:</strong> "
+                f"{html.escape(val)}</p>"
+            )
+
+    para("Name", f"{cv.get('first_name', '')} {cv.get('last_name', '')}".strip())
+    para("Email", cv.get("email"))
+    para("LinkedIn", cv.get("user_linkedin_url"))
+    para("Phone", cv.get("phone"))
+    para("Job Title", cv.get("job_title"))
+    para("Organization", cv.get("organization_name"))
+    para("Domain", cv.get("organization_domain"))
+
+    md_summary = cv.get("research_summary")
+    if md_summary:
+        parts.append("<p><strong>Research Summary:</strong></p>")
+        parts.append(md_to_html(md_summary))
+
+    return "".join(parts)
+
+
+# ──────────────────────────────────────────────────────────────────────────────
+# Mapping between internal names and HubSpot property names
+# ──────────────────────────────────────────────────────────────────────────────
+PROPERTY_MAPPING: Dict[str, str] = {
+    "first_name": "firstname",
+    "last_name": "lastname",
+    "email": "email",
+    "phone": "phone",
+    "job_title": "jobtitle",
+    "primary_domain_of_organization": "domain",
+    "user_linkedin_url": "hs_linkedin_url",
+    "research_summary": "dhisana_research_summary",
+    "organization_name": "company",
+    # add "website": "website" if present in your schema
+}
+
+# Properties that we conditionally fill-in (only if empty in HS)
+CONDITIONAL_UPDATE_PROPS = {
+    "jobtitle",
+    "company",
+    "phone",
+    "domain",
+    "hs_linkedin_url",
+    "website",
+}
+
+# Properties we *never* modify once the record exists
+IMMUTABLE_ON_UPDATE = {"firstname", "lastname", "email"}
+
+
+def _is_empty(val: Optional[str]) -> bool:
+    return val is None or (isinstance(val, str) and not val.strip())
+
+
+# ──────────────────────────────────────────────────────────────────────────────
+# Main upsert entry-point (updated for flexible tag field)
+# ──────────────────────────────────────────────────────────────────────────────
+async def update_crm_contact_record_function(
+    contact_values: Dict[str, Any],
+    is_update: bool,
+    hubspot_contact_id: Optional[str] = None,
+    email: Optional[str] = None,
+    first_name: Optional[str] = None,
+    last_name: Optional[str] = None,
+    company_domain: Optional[str] = None,
+    user_linkedin_url: Optional[str] = None,
+    tags: Optional[List[str]] = None,
+    tag_property: Optional[str] = None,          # ← NEW
+    tool_config: Optional[List[Dict]] = None,
+) -> Dict[str, Any]:
+    """
+    Create or update a HubSpot contact.
+
+    Args
+    ----
+    tag_property:
+        The HS property that stores your semicolon-delimited tag list
+        (e.g. ``"dhisana_contact_tags"``).  
+        • If supplied *and* present in the portal, it will be used.  
+        • If absent, we silently fall back to ``"my_tags"`` if available.  
+        • If neither exists, tags are skipped without error.
+    """
+
+    HUBSPOT_API_KEY = get_hubspot_access_token(tool_config)
+    headers = {
+        "Authorization": f"Bearer {HUBSPOT_API_KEY}",
+        "Content-Type": "application/json",
+    }
+
+    valid_props = await _fetch_all_contact_properties(headers)
+
+    # ─── 0) Build note HTML + plain-text summary ─────────────────────────────
+    note_html: str = build_note_html(contact_values)
+    note_plain: str = html_to_text(note_html)
+
+    # ─── 1) Map contact_values → HS property dict ────────────────────────────
+    incoming_props: Dict[str, Any] = {}
+    for k, v in contact_values.items():
+        if v is None:
+            continue
+        mapped = PROPERTY_MAPPING.get(k)
+        if mapped and mapped in valid_props:
+            incoming_props[mapped] = v
+
+    # ─── 1-b) Handle tags ----------------------------------------------------
+    if tags:
+        # pick the first tag field that actually exists
+        prop_name: Optional[str] = None
+        if tag_property and tag_property in valid_props:
+            prop_name = tag_property
+        elif "my_tags" in valid_props:
+            prop_name = "my_tags"
+
+        if prop_name:
+            incoming_props[prop_name] = ";".join(tags)
+
+    # ─── 2) Upsert logic ─────────────────────────────────────────────────────
+    found_contact_id: Optional[str] = None
+    if is_update:
+        found_contact_id = hubspot_contact_id or await _find_existing_contact(
+            email,
+            user_linkedin_url,
+            first_name,
+            last_name,
+            company_domain,
+            valid_props,
+            tool_config,
+        )
+
+    if found_contact_id:
+        # ─── Existing contact -------------------------------------------------
+        contact_data = await _get_contact_by_id(found_contact_id, headers)
+        current = contact_data.get("properties", {})
+
+        hubspot_props: Dict[str, Any] = {}
+        for prop, val in incoming_props.items():
+            if prop in IMMUTABLE_ON_UPDATE:
+                continue
+            if prop in CONDITIONAL_UPDATE_PROPS:
+                # only fill if currently blank
+                if _is_empty(current.get(prop)):
+                    hubspot_props[prop] = val
+            else:
+                hubspot_props[prop] = val
+
+        # merge/update dhisana_lead_information
+        if "dhisana_lead_information" in valid_props:
+            if note_plain:
+                merged = (current.get("dhisana_lead_information") or "").strip()
+                merged = f"{merged}\n\n{note_plain}" if merged else note_plain
+                hubspot_props["dhisana_lead_information"] = merged
+        elif note_html:
+            await create_hubspot_note_for_customer(
+                customer_id=found_contact_id,
+                note=note_html,
+                tool_config=tool_config,
+            )
+
+        if hubspot_props:
+            update_url = f"https://api.hubapi.com/crm/v3/objects/contacts/{found_contact_id}"
+            async with aiohttp.ClientSession() as s:
+                async with s.patch(
+                    update_url, headers=headers, json={"properties": hubspot_props}
+                ) as r:
+                    res = await r.json()
+                    if r.status != 200:
+                        raise RuntimeError(f"Update failed {r.status}: {res}")
+                    return res
+        return contact_data
+
+    # ─── Create new contact ──────────────────────────────────────────────────
+    return await _create_new_contact_with_note_or_property(
+        incoming_props,
+        note_html,
+        note_plain,
+        valid_props,
+        headers,
+        tool_config,
+    )
+
+
+# ──────────────────────────────────────────────────────────────────────────────
+# Contact creation helper
+# ──────────────────────────────────────────────────────────────────────────────
+async def _create_new_contact_with_note_or_property(
+    properties: Dict[str, Any],
+    note_html: str,
+    note_plain: str,
+    valid_props: List[str],
+    headers: Dict[str, str],
+    tool_config: Optional[List[Dict]],
+) -> Dict[str, Any]:
+    """Create contact, store lead info either in property or as a note."""
+    if "dhisana_lead_information" in valid_props and note_plain:
+        properties["dhisana_lead_information"] = note_plain
+
+    create_result = await _create_new_hubspot_contact(properties, headers)
+
+    if note_html and "dhisana_lead_information" not in valid_props:
+        new_id = create_result.get("id")
+        if new_id:
+            await create_hubspot_note_for_customer(
+                customer_id=new_id, note=note_html, tool_config=tool_config
+            )
+    return create_result
+
+
+# ──────────────────────────────────────────────────────────────────────────────
+# Misc. helpers
+# ──────────────────────────────────────────────────────────────────────────────
+async def _find_existing_contact(
+    email: Optional[str],
+    linkedin_url: Optional[str],
+    first: Optional[str],
+    last: Optional[str],
+    domain: Optional[str],
+    valid_props: List[str],
+    tool_cfg: Optional[List[Dict]],
+) -> Optional[str]:
+    """Return contact ID if a matching record exists, else None."""
+    filters = []
+    if email:
+        filters.append({"propertyName": "email", "operator": "EQ", "value": email})
+    elif linkedin_url and "hs_linkedin_url" in valid_props:
+        filters.append(
+            {"propertyName": "hs_linkedin_url", "operator": "EQ", "value": linkedin_url}
+        )
+    elif first and last and domain:
+        filters.extend(
+            [
+                {"propertyName": "firstname", "operator": "EQ", "value": first},
+                {"propertyName": "lastname", "operator": "EQ", "value": last},
+                {"propertyName": "domain", "operator": "EQ", "value": domain},
+            ]
+        )
+
+    if not filters:
+        return None
+
+    res = await search_hubspot_objects(
+        object_type="contacts",
+        filters=filters,
+        limit=1,
+        tool_config=tool_cfg,
+        properties=[
+            "email",
+            "firstname",
+            "lastname",
+            "domain",
+            "dhisana_lead_information",
+            "company",
+            "jobtitle",
+            "phone",
+            "hs_linkedin_url",
+        ],
+    )
+    hits = res.get("results", [])
+    return hits[0]["id"] if hits else None
+
+
+async def _create_new_hubspot_contact(
+    properties: Dict[str, Any], headers: Dict[str, str]
+) -> Dict[str, Any]:
+    url = "https://api.hubapi.com/crm/v3/objects/contacts"
+    async with aiohttp.ClientSession() as s:
+        async with s.post(url, headers=headers, json={"properties": properties}) as r:
+            data = await r.json()
+            if r.status not in (200, 201):
+                raise RuntimeError(f"Create contact failed {r.status}: {data}")
+            return data
+
+
+async def _fetch_all_contact_properties(headers: Dict[str, str]) -> List[str]:
+    url = "https://api.hubapi.com/crm/v3/properties/contacts"
+    async with aiohttp.ClientSession() as s:
+        async with s.get(url, headers=headers) as r:
+            if r.status != 200:
+                raise RuntimeError(f"Prop fetch failed {r.status}: {await r.text()}")
+            data = await r.json()
+            return [p["name"] for p in data.get("results", [])]
+
+
+async def _get_contact_by_id(contact_id: str, headers: Dict[str, str]) -> Dict[str, Any]:
+    url = f"https://api.hubapi.com/crm/v3/objects/contacts/{contact_id}"
+    async with aiohttp.ClientSession() as s:
+        async with s.get(url, headers=headers) as r:
+            data = await r.json()
+            if r.status != 200:
+                raise RuntimeError(f"Fetch contact {contact_id} failed: {r.status} {data}")
+            return data
+
+
+# ──────────────────────────────────────────────────────────────────────────────
+# Note creation
+# ──────────────────────────────────────────────────────────────────────────────
+async def create_hubspot_note_for_customer(
+    customer_id: str | None = None,
+    email: str | None = None,
+    note: str | None = None,
+    tool_config: Optional[List[Dict]] = None,
+):
+    """
+    Create a rich-text note and attach it to a contact (associationTypeId 202).
+    `note` must be **HTML**.
+    """
+    HUBSPOT_API_KEY = get_hubspot_access_token(tool_config)
+    if not (customer_id or email):
+        raise ValueError("Either customer_id or email is required.")
+    if not note:
+        raise ValueError("Note content must be provided.")
+
+    headers = {
+        "Authorization": f"Bearer {HUBSPOT_API_KEY}",
+        "Content-Type": "application/json",
+    }
+
+    async with aiohttp.ClientSession() as s:
+        if not customer_id:
+            search_url = "https://api.hubapi.com/crm/v3/objects/contacts/search"
+            payload = {
+                "filterGroups": [
+                    {
+                        "filters": [
+                            {"propertyName": "email", "operator": "EQ", "value": email}
+                        ]
+                    }
+                ],
+                "limit": 1,
+            }
+            async with s.post(search_url, headers=headers, json=payload) as r:
+                js = await r.json()
+                if r.status != 200 or not js.get("results"):
+                    raise RuntimeError(f"Contact lookup failed {r.status}: {js}")
+                customer_id = js["results"][0]["id"]
+
+        create_url = "https://api.hubapi.com/crm/v3/objects/notes"
+        payload = {
+            "properties": {
+                "hs_note_body": note,
+                "hs_timestamp": int(time.time() * 1000),
+            },
+            "associations": [
+                {
+                    "to": {"id": customer_id, "type": "contact"},
+                    "types": [
+                        {
+                            "associationCategory": "HUBSPOT_DEFINED",
+                            "associationTypeId": 202,
+                        }
+                    ],
+                }
+            ],
+        }
+        async with s.post(create_url, headers=headers, json=payload) as r:
+            res = await r.json()
+            if r.status != 201:
+                raise RuntimeError(f"Create note failed {r.status}: {res}")
+            return res
+
+
+
+# ──────────────────────────────────────────────────────────────────────────────
+# Mapping between internal names ⇢ HubSpot company property names
+# ──────────────────────────────────────────────────────────────────────────────
+COMPANY_PROPERTY_MAPPING: Dict[str, str] = {
+    "organization_name": "name",
+    "primary_domain_of_organization": "domain",
+    "organization_website": "website",
+}
+
+# Only fill these if currently blank in HS
+CONDITIONAL_UPDATE_PROPS = {"domain", "website"}
+
+
+# ──────────────────────────────────────────────────────────────────────────────
+# Main upsert entry-point
+# ──────────────────────────────────────────────────────────────────────────────
+async def update_crm_company_record_function(
+    company_values: Dict[str, Any],
+    is_update: bool,
+    hubspot_company_id: Optional[str] = None,
+    organization_name: Optional[str] = None,
+    domain: Optional[str] = None,
+    organization_website: Optional[str] = None,
+    tool_config: Optional[List[Dict]] = None,
+) -> Dict[str, Any]:
+    """
+    Create **or** update a HubSpot *company*.
+
+    Parameters
+    ----------
+    company_values:
+        Arbitrary key/value dict using **internal** names  
+        (``organization_name``, ``primary_domain_of_organization``, etc.)
+    is_update:
+        • ``True``  → do a best-effort lookup + patch if found  
+        • ``False`` → always create a fresh company
+    hubspot_company_id:
+        Pass a known HS ID to force an update to that record.
+    """
+    HUBSPOT_API_KEY = get_hubspot_access_token(tool_config)
+    headers = {
+        "Authorization": f"Bearer {HUBSPOT_API_KEY}",
+        "Content-Type": "application/json",
+    }
+
+    # ─── 1) Resolve allowed property names ───────────────────────────────────
+    valid_props = await _fetch_all_company_properties(headers)
+
+    incoming_props: Dict[str, Any] = {}
+    # a) from dict …
+    for k, v in company_values.items():
+        if v is None:
+            continue
+        mapped = COMPANY_PROPERTY_MAPPING.get(k)
+        if mapped and mapped in valid_props:
+            incoming_props[mapped] = v
+
+    # b) from explicit kwargs (fallbacks)
+    if organization_name and "name" in valid_props:
+        incoming_props.setdefault("name", organization_name)
+    if domain and "domain" in valid_props:
+        incoming_props.setdefault("domain", domain)
+    if organization_website and "website" in valid_props:
+        incoming_props.setdefault("website", organization_website)
+
+    # ─── 2) Upsert logic ─────────────────────────────────────────────────────
+    found_company_id: Optional[str] = None
+    if is_update:
+        found_company_id = hubspot_company_id or await _find_existing_company(
+            domain=domain,
+            name=organization_name,
+            valid_props=valid_props,
+            tool_cfg=tool_config,
+        )
+
+    if found_company_id:
+        logging.info("↻ Updating existing company %s", found_company_id)
+        return await _patch_company(
+            company_id=found_company_id,
+            incoming_props=incoming_props,
+            headers=headers,
+        )
+
+    logging.info("⊕ Creating new company with props: %s", incoming_props)
+    return await _create_new_hubspot_company(incoming_props, headers)
+
+
+# ──────────────────────────────────────────────────────────────────────────────
+# Internal helpers
+# ──────────────────────────────────────────────────────────────────────────────
+async def _patch_company(
+    company_id: str,
+    incoming_props: Dict[str, Any],
+    headers: Dict[str, str],
+) -> Dict[str, Any]:
+    """Patch only the changed / conditionally-empty properties."""
+    current = await _get_company_by_id(company_id, headers)
+    if not current:
+        raise RuntimeError(f"Company {company_id} vanished during update step.")
+
+    current_props = current.get("properties", {})
+    hubspot_props: Dict[str, Any] = {}
+
+    for prop, val in incoming_props.items():
+        if prop in CONDITIONAL_UPDATE_PROPS:
+            if _is_empty(current_props.get(prop)):
+                hubspot_props[prop] = val
+        else:
+            hubspot_props[prop] = val
+
+    if not hubspot_props:
+        logging.info("No new data to patch for company %s; skipping.", company_id)
+        return current
+
+    url = f"https://api.hubapi.com/crm/v3/objects/companies/{company_id}"
+    async with aiohttp.ClientSession() as s:
+        async with s.patch(url, headers=headers, json={"properties": hubspot_props}) as r:
+            res = await r.json()
+            if r.status != 200:
+                raise RuntimeError(f"Company update failed {r.status}: {res}")
+            return res
+
+
+async def _create_new_hubspot_company(
+    properties: Dict[str, Any], headers: Dict[str, str]
+) -> Dict[str, Any]:
+    url = "https://api.hubapi.com/crm/v3/objects/companies"
+    async with aiohttp.ClientSession() as s:
+        async with s.post(url, headers=headers, json={"properties": properties}) as r:
+            data = await r.json()
+            if r.status not in (200, 201):
+                raise RuntimeError(f"Create company failed {r.status}: {data}")
+            return data
+
+
+async def _find_existing_company(
+    domain: Optional[str],
+    name: Optional[str],
+    valid_props: List[str],
+    tool_cfg: Optional[List[Dict]],
+) -> Optional[str]:
+    """Return company ID if a matching record exists, else None."""
+    filters = []
+    if domain:
+        filters.append({"propertyName": "domain", "operator": "EQ", "value": domain})
+    if not filters and name:
+        filters.append({"propertyName": "name", "operator": "EQ", "value": name})
+
+    if not filters:
+        return None
+
+    res = await search_hubspot_objects(
+        object_type="companies",
+        filters=filters,
+        limit=1,
+        tool_config=tool_cfg,
+        properties=["name", "domain", "website"],
+    )
+    hits = res.get("results", [])
+    return hits[0]["id"] if hits else None
+
+
+async def _fetch_all_company_properties(headers: Dict[str, str]) -> List[str]:
+    url = "https://api.hubapi.com/crm/v3/properties/companies"
+    async with aiohttp.ClientSession() as s:
+        async with s.get(url, headers=headers) as r:
+            if r.status != 200:
+                raise RuntimeError(f"Company prop fetch failed {r.status}: {await r.text()}")
+            data = await r.json()
+            return [p["name"] for p in data.get("results", [])]
+
+
+async def _get_company_by_id(company_id: str, headers: Dict[str, str]) -> Dict[str, Any]:
+    url = f"https://api.hubapi.com/crm/v3/objects/companies/{company_id}"
+    async with aiohttp.ClientSession() as s:
+        async with s.get(url, headers=headers) as r:
+            data = await r.json()
+            if r.status != 200:
+                raise RuntimeError(f"Fetch company {company_id} failed: {r.status} {data}")
+            return data