airbyte-agent-hubspot 0.15.25__py3-none-any.whl → 0.15.43__py3-none-any.whl

airbyte_agent_hubspot/connector.py

@@ -1,44 +1,44 @@
 """
-hubspot connector.
+Hubspot connector.
 """
 
 from __future__ import annotations
 
-from typing import TYPE_CHECKING, Any, overload
+import logging
+from typing import TYPE_CHECKING, Any, Callable, TypeVar, overload
 try:
     from typing import Literal
 except ImportError:
     from typing_extensions import Literal
 
 from .connector_model import HubspotConnectorModel
-
+from ._vendored.connector_sdk.introspection import describe_entities, generate_tool_description
 from .types import (
+    CompaniesApiSearchParams,
+    CompaniesApiSearchParamsFiltergroupsItem,
+    CompaniesApiSearchParamsSortsItem,
     CompaniesGetParams,
     CompaniesListParams,
-    CompaniesSearchParams,
-    CompaniesSearchParamsFiltergroupsItem,
-    CompaniesSearchParamsSortsItem,
+    ContactsApiSearchParams,
+    ContactsApiSearchParamsFiltergroupsItem,
+    ContactsApiSearchParamsSortsItem,
     ContactsGetParams,
     ContactsListParams,
-    ContactsSearchParams,
-    ContactsSearchParamsFiltergroupsItem,
-    ContactsSearchParamsSortsItem,
+    DealsApiSearchParams,
+    DealsApiSearchParamsFiltergroupsItem,
+    DealsApiSearchParamsSortsItem,
     DealsGetParams,
     DealsListParams,
-    DealsSearchParams,
-    DealsSearchParamsFiltergroupsItem,
-    DealsSearchParamsSortsItem,
     ObjectsGetParams,
     ObjectsListParams,
     SchemasGetParams,
     SchemasListParams,
+    TicketsApiSearchParams,
+    TicketsApiSearchParamsFiltergroupsItem,
+    TicketsApiSearchParamsSortsItem,
     TicketsGetParams,
     TicketsListParams,
-    TicketsSearchParams,
-    TicketsSearchParamsFiltergroupsItem,
-    TicketsSearchParamsSortsItem,
 )
-
 if TYPE_CHECKING:
     from .models import HubspotAuthConfig
 # Import response models and envelope models at runtime
@@ -46,13 +46,13 @@ from .models import (
     HubspotExecuteResult,
     HubspotExecuteResultWithMeta,
     ContactsListResult,
-    ContactsSearchResult,
+    ContactsApiSearchResult,
     CompaniesListResult,
-    CompaniesSearchResult,
+    CompaniesApiSearchResult,
     DealsListResult,
-    DealsSearchResult,
+    DealsApiSearchResult,
     TicketsListResult,
-    TicketsSearchResult,
+    TicketsApiSearchResult,
     SchemasListResult,
     ObjectsListResult,
     CRMObject,
@@ -63,6 +63,9 @@ from .models import (
     Ticket,
 )
 
+# TypeVar for decorator type preservation
+_F = TypeVar("_F", bound=Callable[..., Any])
+
 
 class HubspotConnector:
     """
@@ -75,24 +78,24 @@ class HubspotConnector:
     connector_version = "0.1.3"
     vendored_sdk_version = "0.1.0"  # Version of vendored connector-sdk
 
-    # Map of (entity, action) -> has_extractors for envelope wrapping decision
-    _EXTRACTOR_MAP = {
+    # Map of (entity, action) -> needs_envelope for envelope wrapping decision
+    _ENVELOPE_MAP = {
         ("contacts", "list"): True,
-        ("contacts", "get"): False,
-        ("contacts", "search"): True,
+        ("contacts", "get"): None,
+        ("contacts", "api_search"): True,
         ("companies", "list"): True,
-        ("companies", "get"): False,
-        ("companies", "search"): True,
+        ("companies", "get"): None,
+        ("companies", "api_search"): True,
         ("deals", "list"): True,
-        ("deals", "get"): False,
-        ("deals", "search"): True,
+        ("deals", "get"): None,
+        ("deals", "api_search"): True,
         ("tickets", "list"): True,
-        ("tickets", "get"): False,
-        ("tickets", "search"): True,
+        ("tickets", "get"): None,
+        ("tickets", "api_search"): True,
         ("schemas", "list"): True,
-        ("schemas", "get"): False,
+        ("schemas", "get"): None,
         ("objects", "list"): True,
-        ("objects", "get"): False,
+        ("objects", "get"): None,
     }
 
     # Map of (entity, action) -> {python_param_name: api_param_name}
@@ -100,16 +103,16 @@ class HubspotConnector:
     _PARAM_MAP = {
         ('contacts', 'list'): {'limit': 'limit', 'after': 'after', 'associations': 'associations', 'properties': 'properties', 'properties_with_history': 'propertiesWithHistory', 'archived': 'archived'},
         ('contacts', 'get'): {'contact_id': 'contactId', 'properties': 'properties', 'properties_with_history': 'propertiesWithHistory', 'associations': 'associations', 'id_property': 'idProperty', 'archived': 'archived'},
-        ('contacts', 'search'): {'filter_groups': 'filterGroups', 'properties': 'properties', 'limit': 'limit', 'after': 'after', 'sorts': 'sorts', 'query': 'query'},
+        ('contacts', 'api_search'): {'filter_groups': 'filterGroups', 'properties': 'properties', 'limit': 'limit', 'after': 'after', 'sorts': 'sorts', 'query': 'query'},
         ('companies', 'list'): {'limit': 'limit', 'after': 'after', 'associations': 'associations', 'properties': 'properties', 'properties_with_history': 'propertiesWithHistory', 'archived': 'archived'},
         ('companies', 'get'): {'company_id': 'companyId', 'properties': 'properties', 'properties_with_history': 'propertiesWithHistory', 'associations': 'associations', 'id_property': 'idProperty', 'archived': 'archived'},
-        ('companies', 'search'): {'filter_groups': 'filterGroups', 'properties': 'properties', 'limit': 'limit', 'after': 'after', 'sorts': 'sorts', 'query': 'query'},
+        ('companies', 'api_search'): {'filter_groups': 'filterGroups', 'properties': 'properties', 'limit': 'limit', 'after': 'after', 'sorts': 'sorts', 'query': 'query'},
         ('deals', 'list'): {'limit': 'limit', 'after': 'after', 'associations': 'associations', 'properties': 'properties', 'properties_with_history': 'propertiesWithHistory', 'archived': 'archived'},
         ('deals', 'get'): {'deal_id': 'dealId', 'properties': 'properties', 'properties_with_history': 'propertiesWithHistory', 'associations': 'associations', 'id_property': 'idProperty', 'archived': 'archived'},
-        ('deals', 'search'): {'filter_groups': 'filterGroups', 'properties': 'properties', 'limit': 'limit', 'after': 'after', 'sorts': 'sorts', 'query': 'query'},
+        ('deals', 'api_search'): {'filter_groups': 'filterGroups', 'properties': 'properties', 'limit': 'limit', 'after': 'after', 'sorts': 'sorts', 'query': 'query'},
         ('tickets', 'list'): {'limit': 'limit', 'after': 'after', 'associations': 'associations', 'properties': 'properties', 'properties_with_history': 'propertiesWithHistory', 'archived': 'archived'},
         ('tickets', 'get'): {'ticket_id': 'ticketId', 'properties': 'properties', 'properties_with_history': 'propertiesWithHistory', 'associations': 'associations', 'id_property': 'idProperty', 'archived': 'archived'},
-        ('tickets', 'search'): {'filter_groups': 'filterGroups', 'properties': 'properties', 'limit': 'limit', 'after': 'after', 'sorts': 'sorts', 'query': 'query'},
+        ('tickets', 'api_search'): {'filter_groups': 'filterGroups', 'properties': 'properties', 'limit': 'limit', 'after': 'after', 'sorts': 'sorts', 'query': 'query'},
         ('schemas', 'list'): {'archived': 'archived'},
         ('schemas', 'get'): {'object_type': 'objectType'},
         ('objects', 'list'): {'object_type': 'objectType', 'limit': 'limit', 'after': 'after', 'properties': 'properties', 'archived': 'archived', 'associations': 'associations', 'properties_with_history': 'propertiesWithHistory'},
@@ -220,9 +223,9 @@ class HubspotConnector:
     async def execute(
         self,
         entity: Literal["contacts"],
-        action: Literal["search"],
-        params: "ContactsSearchParams"
-    ) -> "ContactsSearchResult": ...
+        action: Literal["api_search"],
+        params: "ContactsApiSearchParams"
+    ) -> "ContactsApiSearchResult": ...
 
     @overload
     async def execute(
@@ -244,9 +247,9 @@ class HubspotConnector:
     async def execute(
         self,
         entity: Literal["companies"],
-        action: Literal["search"],
-        params: "CompaniesSearchParams"
-    ) -> "CompaniesSearchResult": ...
+        action: Literal["api_search"],
+        params: "CompaniesApiSearchParams"
+    ) -> "CompaniesApiSearchResult": ...
 
     @overload
     async def execute(
@@ -268,9 +271,9 @@ class HubspotConnector:
     async def execute(
         self,
         entity: Literal["deals"],
-        action: Literal["search"],
-        params: "DealsSearchParams"
-    ) -> "DealsSearchResult": ...
+        action: Literal["api_search"],
+        params: "DealsApiSearchParams"
+    ) -> "DealsApiSearchResult": ...
 
     @overload
     async def execute(
@@ -292,9 +295,9 @@ class HubspotConnector:
     async def execute(
         self,
         entity: Literal["tickets"],
-        action: Literal["search"],
-        params: "TicketsSearchParams"
-    ) -> "TicketsSearchResult": ...
+        action: Literal["api_search"],
+        params: "TicketsApiSearchParams"
+    ) -> "TicketsApiSearchResult": ...
 
     @overload
     async def execute(
@@ -387,7 +390,7 @@ class HubspotConnector:
             raise RuntimeError(f"Execution failed: {result.error}")
 
         # Check if this operation has extractors configured
-        has_extractors = self._EXTRACTOR_MAP.get((entity, action), False)
+        has_extractors = self._ENVELOPE_MAP.get((entity, action), False)
 
         if has_extractors:
             # With extractors - return Pydantic envelope with data and meta
@@ -402,6 +405,88 @@ class HubspotConnector:
             # No extractors - return raw response data
             return result.data
 
+    # ===== INTROSPECTION METHODS =====
+
+    @classmethod
+    def describe(cls, func: _F) -> _F:
+        """
+        Decorator that populates a function's docstring with connector capabilities.
+
+        This class method can be used as a decorator to automatically generate
+        comprehensive documentation for AI tool functions.
+
+        Usage:
+            @mcp.tool()
+            @HubspotConnector.describe
+            async def execute(entity: str, action: str, params: dict):
+                '''Execute operations.'''
+                ...
+
+        The decorated function's __doc__ will be updated with:
+        - Available entities and their actions
+        - Parameter signatures with required (*) and optional (?) markers
+        - Response structure documentation
+        - Example questions (if available in OpenAPI spec)
+
+        Args:
+            func: The function to decorate
+
+        Returns:
+            The same function with updated __doc__
+        """
+        description = generate_tool_description(HubspotConnectorModel)
+
+        original_doc = func.__doc__ or ""
+        if original_doc.strip():
+            func.__doc__ = f"{original_doc.strip()}\n{description}"
+        else:
+            func.__doc__ = description
+
+        return func
+
+    def list_entities(self) -> list[dict[str, Any]]:
+        """
+        Get structured data about available entities, actions, and parameters.
+
+        Returns a list of entity descriptions with:
+        - entity_name: Name of the entity (e.g., "contacts", "deals")
+        - description: Entity description from the first endpoint
+        - available_actions: List of actions (e.g., ["list", "get", "create"])
+        - parameters: Dict mapping action -> list of parameter dicts
+
+        Example:
+            entities = connector.list_entities()
+            for entity in entities:
+                print(f"{entity['entity_name']}: {entity['available_actions']}")
+        """
+        return describe_entities(HubspotConnectorModel)
+
+    def entity_schema(self, entity: str) -> dict[str, Any] | None:
+        """
+        Get the JSON schema for an entity.
+
+        Args:
+            entity: Entity name (e.g., "contacts", "companies")
+
+        Returns:
+            JSON schema dict describing the entity structure, or None if not found.
+
+        Example:
+            schema = connector.entity_schema("contacts")
+            if schema:
+                print(f"Contact properties: {list(schema.get('properties', {}).keys())}")
+        """
+        entity_def = next(
+            (e for e in HubspotConnectorModel.entities if e.name == entity),
+            None
+        )
+        if entity_def is None:
+            logging.getLogger(__name__).warning(
+                f"Entity '{entity}' not found. Available entities: "
+                f"{[e.name for e in HubspotConnectorModel.entities]}"
+            )
+        return entity_def.entity_schema if entity_def else None
+
 
 
 class ContactsQuery:
@@ -452,7 +537,8 @@ class ContactsQuery:
         # Cast generic envelope to concrete typed result
         return ContactsListResult(
             data=result.data,
-            meta=result.meta        )
+            meta=result.meta
+        )
 
 
 
@@ -496,16 +582,16 @@ class ContactsQuery:
 
 
 
-    async def search(
+    async def api_search(
         self,
-        filter_groups: list[ContactsSearchParamsFiltergroupsItem] | None = None,
+        filter_groups: list[ContactsApiSearchParamsFiltergroupsItem] | None = None,
         properties: list[str] | None = None,
         limit: int | None = None,
         after: str | None = None,
-        sorts: list[ContactsSearchParamsSortsItem] | None = None,
+        sorts: list[ContactsApiSearchParamsSortsItem] | None = None,
         query: str | None = None,
         **kwargs
-    ) -> ContactsSearchResult:
+    ) -> ContactsApiSearchResult:
         """
         Search for contacts by filtering on properties, searching through associations, and sorting results.
 
@@ -519,7 +605,7 @@ class ContactsQuery:
             **kwargs: Additional parameters
 
         Returns:
-            ContactsSearchResult
+            ContactsApiSearchResult
         """
         params = {k: v for k, v in {
             "filterGroups": filter_groups,
@@ -531,11 +617,12 @@ class ContactsQuery:
             **kwargs
         }.items() if v is not None}
 
-        result = await self._connector.execute("contacts", "search", params)
+        result = await self._connector.execute("contacts", "api_search", params)
         # Cast generic envelope to concrete typed result
-        return ContactsSearchResult(
+        return ContactsApiSearchResult(
             data=result.data,
-            meta=result.meta        )
+            meta=result.meta
+        )
 
 
 
@@ -587,7 +674,8 @@ class CompaniesQuery:
         # Cast generic envelope to concrete typed result
         return CompaniesListResult(
             data=result.data,
-            meta=result.meta        )
+            meta=result.meta
+        )
 
 
 
@@ -631,16 +719,16 @@ class CompaniesQuery:
 
 
 
-    async def search(
+    async def api_search(
         self,
-        filter_groups: list[CompaniesSearchParamsFiltergroupsItem] | None = None,
+        filter_groups: list[CompaniesApiSearchParamsFiltergroupsItem] | None = None,
         properties: list[str] | None = None,
         limit: int | None = None,
         after: str | None = None,
-        sorts: list[CompaniesSearchParamsSortsItem] | None = None,
+        sorts: list[CompaniesApiSearchParamsSortsItem] | None = None,
         query: str | None = None,
         **kwargs
-    ) -> CompaniesSearchResult:
+    ) -> CompaniesApiSearchResult:
         """
         Search for companies by filtering on properties, searching through associations, and sorting results.
 
@@ -654,7 +742,7 @@ class CompaniesQuery:
             **kwargs: Additional parameters
 
         Returns:
-            CompaniesSearchResult
+            CompaniesApiSearchResult
         """
         params = {k: v for k, v in {
             "filterGroups": filter_groups,
@@ -666,11 +754,12 @@ class CompaniesQuery:
             **kwargs
         }.items() if v is not None}
 
-        result = await self._connector.execute("companies", "search", params)
+        result = await self._connector.execute("companies", "api_search", params)
         # Cast generic envelope to concrete typed result
-        return CompaniesSearchResult(
+        return CompaniesApiSearchResult(
             data=result.data,
-            meta=result.meta        )
+            meta=result.meta
+        )
 
 
 
@@ -722,7 +811,8 @@ class DealsQuery:
         # Cast generic envelope to concrete typed result
         return DealsListResult(
             data=result.data,
-            meta=result.meta        )
+            meta=result.meta
+        )
 
 
 
@@ -766,16 +856,16 @@ class DealsQuery:
 
 
 
-    async def search(
+    async def api_search(
         self,
-        filter_groups: list[DealsSearchParamsFiltergroupsItem] | None = None,
+        filter_groups: list[DealsApiSearchParamsFiltergroupsItem] | None = None,
         properties: list[str] | None = None,
         limit: int | None = None,
         after: str | None = None,
-        sorts: list[DealsSearchParamsSortsItem] | None = None,
+        sorts: list[DealsApiSearchParamsSortsItem] | None = None,
         query: str | None = None,
         **kwargs
-    ) -> DealsSearchResult:
+    ) -> DealsApiSearchResult:
         """
         Search deals with filters and sorting
 
@@ -789,7 +879,7 @@ class DealsQuery:
             **kwargs: Additional parameters
 
         Returns:
-            DealsSearchResult
+            DealsApiSearchResult
         """
         params = {k: v for k, v in {
             "filterGroups": filter_groups,
@@ -801,11 +891,12 @@ class DealsQuery:
             **kwargs
         }.items() if v is not None}
 
-        result = await self._connector.execute("deals", "search", params)
+        result = await self._connector.execute("deals", "api_search", params)
         # Cast generic envelope to concrete typed result
-        return DealsSearchResult(
+        return DealsApiSearchResult(
             data=result.data,
-            meta=result.meta        )
+            meta=result.meta
+        )
 
 
 
@@ -857,7 +948,8 @@ class TicketsQuery:
         # Cast generic envelope to concrete typed result
         return TicketsListResult(
             data=result.data,
-            meta=result.meta        )
+            meta=result.meta
+        )
 
 
 
@@ -901,16 +993,16 @@ class TicketsQuery:
 
 
 
-    async def search(
+    async def api_search(
         self,
-        filter_groups: list[TicketsSearchParamsFiltergroupsItem] | None = None,
+        filter_groups: list[TicketsApiSearchParamsFiltergroupsItem] | None = None,
         properties: list[str] | None = None,
         limit: int | None = None,
         after: str | None = None,
-        sorts: list[TicketsSearchParamsSortsItem] | None = None,
+        sorts: list[TicketsApiSearchParamsSortsItem] | None = None,
         query: str | None = None,
         **kwargs
-    ) -> TicketsSearchResult:
+    ) -> TicketsApiSearchResult:
         """
         Search for tickets by filtering on properties, searching through associations, and sorting results.
 
@@ -924,7 +1016,7 @@ class TicketsQuery:
             **kwargs: Additional parameters
 
         Returns:
-            TicketsSearchResult
+            TicketsApiSearchResult
         """
         params = {k: v for k, v in {
             "filterGroups": filter_groups,
@@ -936,11 +1028,12 @@ class TicketsQuery:
             **kwargs
         }.items() if v is not None}
 
-        result = await self._connector.execute("tickets", "search", params)
+        result = await self._connector.execute("tickets", "api_search", params)
         # Cast generic envelope to concrete typed result
-        return TicketsSearchResult(
+        return TicketsApiSearchResult(
             data=result.data,
-            meta=result.meta        )
+            meta=result.meta
+        )
 
 
 
@@ -976,7 +1069,8 @@ class SchemasQuery:
         result = await self._connector.execute("schemas", "list", params)
         # Cast generic envelope to concrete typed result
         return SchemasListResult(
-            data=result.data        )
+            data=result.data
+        )
 
 
 
@@ -1056,7 +1150,8 @@ class ObjectsQuery:
         # Cast generic envelope to concrete typed result
         return ObjectsListResult(
             data=result.data,
-            meta=result.meta        )
+            meta=result.meta
+        )
 
 
 

airbyte_agent_hubspot/connector_model.py

@@ -71,12 +71,17 @@ HubspotConnectorModel: ConnectorModel = ConnectorModel(
                 'refresh_token': '${refresh_token}',
                 'access_token': '${access_token}',
             },
+            replication_auth_key_mapping={
+                'client_id': 'client_id',
+                'client_secret': 'client_secret',
+                'refresh_token': 'refresh_token',
+            },
         ),
     ),
     entities=[
         EntityDefinition(
             name='contacts',
-            actions=[Action.LIST, Action.GET, Action.SEARCH],
+            actions=[Action.LIST, Action.GET, Action.API_SEARCH],
             endpoints={
                 Action.LIST: EndpointDefinition(
                     method='GET',
@@ -287,10 +292,10 @@ HubspotConnectorModel: ConnectorModel = ConnectorModel(
                         'x-airbyte-entity-name': 'contacts',
                     },
                 ),
-                Action.SEARCH: EndpointDefinition(
+                Action.API_SEARCH: EndpointDefinition(
                     method='POST',
                     path='/crm/v3/objects/contacts/search',
-                    action=Action.SEARCH,
+                    action=Action.API_SEARCH,
                     description='Search for contacts by filtering on properties, searching through associations, and sorting results.',
                     body_fields=[
                         'filterGroups',
@@ -553,7 +558,7 @@ HubspotConnectorModel: ConnectorModel = ConnectorModel(
         ),
         EntityDefinition(
             name='companies',
-            actions=[Action.LIST, Action.GET, Action.SEARCH],
+            actions=[Action.LIST, Action.GET, Action.API_SEARCH],
             endpoints={
                 Action.LIST: EndpointDefinition(
                     method='GET',
@@ -758,10 +763,10 @@ HubspotConnectorModel: ConnectorModel = ConnectorModel(
                         'x-airbyte-entity-name': 'companies',
                     },
                 ),
-                Action.SEARCH: EndpointDefinition(
+                Action.API_SEARCH: EndpointDefinition(
                     method='POST',
                     path='/crm/v3/objects/companies/search',
-                    action=Action.SEARCH,
+                    action=Action.API_SEARCH,
                     description='Search for companies by filtering on properties, searching through associations, and sorting results.',
                     body_fields=[
                         'filterGroups',
@@ -1018,7 +1023,7 @@ HubspotConnectorModel: ConnectorModel = ConnectorModel(
         ),
         EntityDefinition(
             name='deals',
-            actions=[Action.LIST, Action.GET, Action.SEARCH],
+            actions=[Action.LIST, Action.GET, Action.API_SEARCH],
             endpoints={
                 Action.LIST: EndpointDefinition(
                     method='GET',
@@ -1241,10 +1246,10 @@ HubspotConnectorModel: ConnectorModel = ConnectorModel(
                         'x-airbyte-entity-name': 'deals',
                     },
                 ),
-                Action.SEARCH: EndpointDefinition(
+                Action.API_SEARCH: EndpointDefinition(
                     method='POST',
                     path='/crm/v3/objects/deals/search',
-                    action=Action.SEARCH,
+                    action=Action.API_SEARCH,
                     description='Search deals with filters and sorting',
                     body_fields=[
                         'filterGroups',
@@ -1519,7 +1524,7 @@ HubspotConnectorModel: ConnectorModel = ConnectorModel(
         ),
         EntityDefinition(
             name='tickets',
-            actions=[Action.LIST, Action.GET, Action.SEARCH],
+            actions=[Action.LIST, Action.GET, Action.API_SEARCH],
             endpoints={
                 Action.LIST: EndpointDefinition(
                     method='GET',
@@ -1748,10 +1753,10 @@ HubspotConnectorModel: ConnectorModel = ConnectorModel(
                         'x-airbyte-entity-name': 'tickets',
                     },
                 ),
-                Action.SEARCH: EndpointDefinition(
+                Action.API_SEARCH: EndpointDefinition(
                     method='POST',
                     path='/crm/v3/objects/tickets/search',
-                    action=Action.SEARCH,
+                    action=Action.API_SEARCH,
                     description='Search for tickets by filtering on properties, searching through associations, and sorting results.',
                     body_fields=[
                         'filterGroups',