airbyte-agent-stripe 0.5.28__py3-none-any.whl → 0.5.37__py3-none-any.whl

airbyte_agent_stripe/connector.py

@@ -4,58 +4,65 @@ stripe 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 StripeConnectorModel
-
+from ._vendored.connector_sdk.introspection import describe_entities, generate_tool_description
 from .types import (
     BalanceGetParams,
     BalanceTransactionsGetParams,
     BalanceTransactionsListParams,
     BalanceTransactionsListParamsCreated,
+    ChargesApiSearchParams,
     ChargesGetParams,
     ChargesListParams,
     ChargesListParamsCreated,
-    ChargesSearchParams,
+    CustomersApiSearchParams,
+    CustomersCreateParams,
+    CustomersDeleteParams,
     CustomersGetParams,
     CustomersListParams,
     CustomersListParamsCreated,
-    CustomersSearchParams,
+    CustomersUpdateParams,
     DisputesGetParams,
     DisputesListParams,
     DisputesListParamsCreated,
+    InvoicesApiSearchParams,
     InvoicesGetParams,
     InvoicesListParams,
     InvoicesListParamsCreated,
-    InvoicesSearchParams,
+    PaymentIntentsApiSearchParams,
     PaymentIntentsGetParams,
     PaymentIntentsListParams,
     PaymentIntentsListParamsCreated,
-    PaymentIntentsSearchParams,
     PayoutsGetParams,
     PayoutsListParams,
     PayoutsListParamsArrivalDate,
     PayoutsListParamsCreated,
+    ProductsApiSearchParams,
+    ProductsCreateParams,
+    ProductsDeleteParams,
     ProductsGetParams,
     ProductsListParams,
     ProductsListParamsCreated,
-    ProductsSearchParams,
+    ProductsUpdateParams,
+    RefundsCreateParams,
     RefundsGetParams,
     RefundsListParams,
     RefundsListParamsCreated,
+    SubscriptionsApiSearchParams,
     SubscriptionsGetParams,
     SubscriptionsListParams,
     SubscriptionsListParamsAutomaticTax,
     SubscriptionsListParamsCreated,
     SubscriptionsListParamsCurrentPeriodEnd,
     SubscriptionsListParamsCurrentPeriodStart,
-    SubscriptionsSearchParams,
 )
-
 if TYPE_CHECKING:
     from .models import StripeAuthConfig
 # Import response models and envelope models at runtime
@@ -63,16 +70,16 @@ from .models import (
     StripeExecuteResult,
     StripeExecuteResultWithMeta,
     CustomersListResult,
-    CustomersSearchResult,
+    CustomersApiSearchResult,
     InvoicesListResult,
     ChargesListResult,
     SubscriptionsListResult,
     RefundsListResult,
     ProductsListResult,
-    ProductsSearchResult,
+    ProductsApiSearchResult,
     BalanceTransactionsListResult,
     PaymentIntentsListResult,
-    PaymentIntentsSearchResult,
+    PaymentIntentsApiSearchResult,
     DisputesListResult,
     PayoutsListResult,
     Balance,
@@ -80,17 +87,22 @@ from .models import (
     Charge,
     ChargeSearchResult,
     Customer,
+    CustomerDeletedResponse,
     Dispute,
     Invoice,
     InvoiceSearchResult,
     PaymentIntent,
     Payout,
     Product,
+    ProductDeletedResponse,
     Refund,
     Subscription,
     SubscriptionSearchResult,
 )
 
+# TypeVar for decorator type preservation
+_F = TypeVar("_F", bound=Callable[..., Any])
+
 
 class StripeConnector:
     """
@@ -100,34 +112,41 @@ class StripeConnector:
     """
 
     connector_name = "stripe"
-    connector_version = "0.1.3"
+    connector_version = "0.1.4"
     vendored_sdk_version = "0.1.0"  # Version of vendored connector-sdk
 
     # Map of (entity, action) -> has_extractors for envelope wrapping decision
     _EXTRACTOR_MAP = {
         ("customers", "list"): True,
+        ("customers", "create"): False,
         ("customers", "get"): False,
-        ("customers", "search"): True,
+        ("customers", "update"): False,
+        ("customers", "delete"): False,
+        ("customers", "api_search"): True,
         ("invoices", "list"): True,
         ("invoices", "get"): False,
-        ("invoices", "search"): False,
+        ("invoices", "api_search"): False,
         ("charges", "list"): True,
         ("charges", "get"): False,
-        ("charges", "search"): False,
+        ("charges", "api_search"): False,
         ("subscriptions", "list"): True,
         ("subscriptions", "get"): False,
-        ("subscriptions", "search"): False,
+        ("subscriptions", "api_search"): False,
         ("refunds", "list"): True,
+        ("refunds", "create"): False,
         ("refunds", "get"): False,
         ("products", "list"): True,
+        ("products", "create"): False,
         ("products", "get"): False,
-        ("products", "search"): True,
+        ("products", "update"): False,
+        ("products", "delete"): False,
+        ("products", "api_search"): True,
         ("balance", "get"): False,
         ("balance_transactions", "list"): True,
         ("balance_transactions", "get"): False,
         ("payment_intents", "list"): True,
         ("payment_intents", "get"): False,
-        ("payment_intents", "search"): True,
+        ("payment_intents", "api_search"): True,
         ("disputes", "list"): True,
         ("disputes", "get"): False,
         ("payouts", "list"): True,
@@ -139,26 +158,30 @@ class StripeConnector:
     _PARAM_MAP = {
         ('customers', 'list'): {'limit': 'limit', 'starting_after': 'starting_after', 'ending_before': 'ending_before', 'email': 'email', 'created': 'created'},
         ('customers', 'get'): {'id': 'id'},
-        ('customers', 'search'): {'query': 'query', 'limit': 'limit', 'page': 'page'},
+        ('customers', 'update'): {'id': 'id'},
+        ('customers', 'delete'): {'id': 'id'},
+        ('customers', 'api_search'): {'query': 'query', 'limit': 'limit', 'page': 'page'},
         ('invoices', 'list'): {'collection_method': 'collection_method', 'created': 'created', 'customer': 'customer', 'customer_account': 'customer_account', 'ending_before': 'ending_before', 'limit': 'limit', 'starting_after': 'starting_after', 'status': 'status', 'subscription': 'subscription'},
         ('invoices', 'get'): {'id': 'id'},
-        ('invoices', 'search'): {'query': 'query', 'limit': 'limit', 'page': 'page'},
+        ('invoices', 'api_search'): {'query': 'query', 'limit': 'limit', 'page': 'page'},
         ('charges', 'list'): {'created': 'created', 'customer': 'customer', 'ending_before': 'ending_before', 'limit': 'limit', 'payment_intent': 'payment_intent', 'starting_after': 'starting_after'},
         ('charges', 'get'): {'id': 'id'},
-        ('charges', 'search'): {'query': 'query', 'limit': 'limit', 'page': 'page'},
+        ('charges', 'api_search'): {'query': 'query', 'limit': 'limit', 'page': 'page'},
         ('subscriptions', 'list'): {'automatic_tax': 'automatic_tax', 'collection_method': 'collection_method', 'created': 'created', 'current_period_end': 'current_period_end', 'current_period_start': 'current_period_start', 'customer': 'customer', 'customer_account': 'customer_account', 'ending_before': 'ending_before', 'limit': 'limit', 'price': 'price', 'starting_after': 'starting_after', 'status': 'status'},
         ('subscriptions', 'get'): {'id': 'id'},
-        ('subscriptions', 'search'): {'query': 'query', 'limit': 'limit', 'page': 'page'},
+        ('subscriptions', 'api_search'): {'query': 'query', 'limit': 'limit', 'page': 'page'},
         ('refunds', 'list'): {'charge': 'charge', 'created': 'created', 'ending_before': 'ending_before', 'limit': 'limit', 'payment_intent': 'payment_intent', 'starting_after': 'starting_after'},
         ('refunds', 'get'): {'id': 'id'},
         ('products', 'list'): {'active': 'active', 'created': 'created', 'ending_before': 'ending_before', 'ids': 'ids', 'limit': 'limit', 'shippable': 'shippable', 'starting_after': 'starting_after', 'url': 'url'},
         ('products', 'get'): {'id': 'id'},
-        ('products', 'search'): {'query': 'query', 'limit': 'limit', 'page': 'page'},
+        ('products', 'update'): {'id': 'id'},
+        ('products', 'delete'): {'id': 'id'},
+        ('products', 'api_search'): {'query': 'query', 'limit': 'limit', 'page': 'page'},
         ('balance_transactions', 'list'): {'created': 'created', 'currency': 'currency', 'ending_before': 'ending_before', 'limit': 'limit', 'payout': 'payout', 'source': 'source', 'starting_after': 'starting_after', 'type': 'type'},
         ('balance_transactions', 'get'): {'id': 'id'},
         ('payment_intents', 'list'): {'created': 'created', 'customer': 'customer', 'customer_account': 'customer_account', 'ending_before': 'ending_before', 'limit': 'limit', 'starting_after': 'starting_after'},
         ('payment_intents', 'get'): {'id': 'id'},
-        ('payment_intents', 'search'): {'query': 'query', 'limit': 'limit', 'page': 'page'},
+        ('payment_intents', 'api_search'): {'query': 'query', 'limit': 'limit', 'page': 'page'},
         ('disputes', 'list'): {'charge': 'charge', 'created': 'created', 'ending_before': 'ending_before', 'limit': 'limit', 'payment_intent': 'payment_intent', 'starting_after': 'starting_after'},
         ('disputes', 'get'): {'id': 'id'},
         ('payouts', 'list'): {'arrival_date': 'arrival_date', 'created': 'created', 'destination': 'destination', 'ending_before': 'ending_before', 'limit': 'limit', 'starting_after': 'starting_after', 'status': 'status'},
@@ -262,6 +285,14 @@ class StripeConnector:
         params: "CustomersListParams"
     ) -> "CustomersListResult": ...
 
+    @overload
+    async def execute(
+        self,
+        entity: Literal["customers"],
+        action: Literal["create"],
+        params: "CustomersCreateParams"
+    ) -> "Customer": ...
+
     @overload
     async def execute(
         self,
@@ -274,9 +305,25 @@ class StripeConnector:
     async def execute(
         self,
         entity: Literal["customers"],
-        action: Literal["search"],
-        params: "CustomersSearchParams"
-    ) -> "CustomersSearchResult": ...
+        action: Literal["update"],
+        params: "CustomersUpdateParams"
+    ) -> "Customer": ...
+
+    @overload
+    async def execute(
+        self,
+        entity: Literal["customers"],
+        action: Literal["delete"],
+        params: "CustomersDeleteParams"
+    ) -> "CustomerDeletedResponse": ...
+
+    @overload
+    async def execute(
+        self,
+        entity: Literal["customers"],
+        action: Literal["api_search"],
+        params: "CustomersApiSearchParams"
+    ) -> "CustomersApiSearchResult": ...
 
     @overload
     async def execute(
@@ -298,8 +345,8 @@ class StripeConnector:
     async def execute(
         self,
         entity: Literal["invoices"],
-        action: Literal["search"],
-        params: "InvoicesSearchParams"
+        action: Literal["api_search"],
+        params: "InvoicesApiSearchParams"
     ) -> "InvoiceSearchResult": ...
 
     @overload
@@ -322,8 +369,8 @@ class StripeConnector:
     async def execute(
         self,
         entity: Literal["charges"],
-        action: Literal["search"],
-        params: "ChargesSearchParams"
+        action: Literal["api_search"],
+        params: "ChargesApiSearchParams"
     ) -> "ChargeSearchResult": ...
 
     @overload
@@ -346,8 +393,8 @@ class StripeConnector:
     async def execute(
         self,
         entity: Literal["subscriptions"],
-        action: Literal["search"],
-        params: "SubscriptionsSearchParams"
+        action: Literal["api_search"],
+        params: "SubscriptionsApiSearchParams"
     ) -> "SubscriptionSearchResult": ...
 
     @overload
@@ -358,6 +405,14 @@ class StripeConnector:
         params: "RefundsListParams"
     ) -> "RefundsListResult": ...
 
+    @overload
+    async def execute(
+        self,
+        entity: Literal["refunds"],
+        action: Literal["create"],
+        params: "RefundsCreateParams"
+    ) -> "Refund": ...
+
     @overload
     async def execute(
         self,
@@ -374,6 +429,14 @@ class StripeConnector:
         params: "ProductsListParams"
     ) -> "ProductsListResult": ...
 
+    @overload
+    async def execute(
+        self,
+        entity: Literal["products"],
+        action: Literal["create"],
+        params: "ProductsCreateParams"
+    ) -> "Product": ...
+
     @overload
     async def execute(
         self,
@@ -386,9 +449,25 @@ class StripeConnector:
     async def execute(
         self,
         entity: Literal["products"],
-        action: Literal["search"],
-        params: "ProductsSearchParams"
-    ) -> "ProductsSearchResult": ...
+        action: Literal["update"],
+        params: "ProductsUpdateParams"
+    ) -> "Product": ...
+
+    @overload
+    async def execute(
+        self,
+        entity: Literal["products"],
+        action: Literal["delete"],
+        params: "ProductsDeleteParams"
+    ) -> "ProductDeletedResponse": ...
+
+    @overload
+    async def execute(
+        self,
+        entity: Literal["products"],
+        action: Literal["api_search"],
+        params: "ProductsApiSearchParams"
+    ) -> "ProductsApiSearchResult": ...
 
     @overload
     async def execute(
@@ -434,9 +513,9 @@ class StripeConnector:
     async def execute(
         self,
         entity: Literal["payment_intents"],
-        action: Literal["search"],
-        params: "PaymentIntentsSearchParams"
-    ) -> "PaymentIntentsSearchResult": ...
+        action: Literal["api_search"],
+        params: "PaymentIntentsApiSearchParams"
+    ) -> "PaymentIntentsApiSearchResult": ...
 
     @overload
     async def execute(
@@ -544,6 +623,88 @@ class StripeConnector:
             # 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()
+            @StripeConnector.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(StripeConnectorModel)
+
+        original_doc = func.__doc__ or ""
+        if original_doc.strip():
+            func.__doc__ = f"{original_doc.strip()}\n\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(StripeConnectorModel)
+
+    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 StripeConnectorModel.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 StripeConnectorModel.entities]}"
+            )
+        return entity_def.entity_schema if entity_def else None
+
 
 
 class CustomersQuery:
@@ -595,6 +756,25 @@ class CustomersQuery:
 
 
 
+    async def create(
+        self,
+        **kwargs
+    ) -> Customer:
+        """
+        Creates a new customer object.
+
+        Returns:
+            Customer
+        """
+        params = {k: v for k, v in {
+            **kwargs
+        }.items() if v is not None}
+
+        result = await self._connector.execute("customers", "create", params)
+        return result
+
+
+
     async def get(
         self,
         id: str | None = None,
@@ -620,13 +800,63 @@ class CustomersQuery:
 
 
 
-    async def search(
+    async def update(
+        self,
+        id: str | None = None,
+        **kwargs
+    ) -> Customer:
+        """
+        Updates the specified customer by setting the values of the parameters passed.
+
+        Args:
+            id: The customer ID
+            **kwargs: Additional parameters
+
+        Returns:
+            Customer
+        """
+        params = {k: v for k, v in {
+            "id": id,
+            **kwargs
+        }.items() if v is not None}
+
+        result = await self._connector.execute("customers", "update", params)
+        return result
+
+
+
+    async def delete(
+        self,
+        id: str | None = None,
+        **kwargs
+    ) -> CustomerDeletedResponse:
+        """
+        Permanently deletes a customer. It cannot be undone.
+
+        Args:
+            id: The customer ID
+            **kwargs: Additional parameters
+
+        Returns:
+            CustomerDeletedResponse
+        """
+        params = {k: v for k, v in {
+            "id": id,
+            **kwargs
+        }.items() if v is not None}
+
+        result = await self._connector.execute("customers", "delete", params)
+        return result
+
+
+
+    async def api_search(
         self,
         query: str,
         limit: int | None = None,
         page: str | None = None,
         **kwargs
-    ) -> CustomersSearchResult:
+    ) -> CustomersApiSearchResult:
         """
         Search for customers using Stripe's Search Query Language.
 
@@ -637,7 +867,7 @@ class CustomersQuery:
             **kwargs: Additional parameters
 
         Returns:
-            CustomersSearchResult
+            CustomersApiSearchResult
         """
         params = {k: v for k, v in {
             "query": query,
@@ -646,9 +876,9 @@ class CustomersQuery:
             **kwargs
         }.items() if v is not None}
 
-        result = await self._connector.execute("customers", "search", params)
+        result = await self._connector.execute("customers", "api_search", params)
         # Cast generic envelope to concrete typed result
-        return CustomersSearchResult(
+        return CustomersApiSearchResult(
             data=result.data,
             meta=result.meta        )
 
@@ -740,7 +970,7 @@ class InvoicesQuery:
 
 
 
-    async def search(
+    async def api_search(
         self,
         query: str,
         limit: int | None = None,
@@ -766,7 +996,7 @@ class InvoicesQuery:
             **kwargs
         }.items() if v is not None}
 
-        result = await self._connector.execute("invoices", "search", params)
+        result = await self._connector.execute("invoices", "api_search", params)
         return result
 
 
@@ -848,7 +1078,7 @@ class ChargesQuery:
 
 
 
-    async def search(
+    async def api_search(
         self,
         query: str,
         limit: int | None = None,
@@ -874,7 +1104,7 @@ class ChargesQuery:
             **kwargs
         }.items() if v is not None}
 
-        result = await self._connector.execute("charges", "search", params)
+        result = await self._connector.execute("charges", "api_search", params)
         return result
 
 
@@ -974,7 +1204,7 @@ class SubscriptionsQuery:
 
 
 
-    async def search(
+    async def api_search(
         self,
         query: str,
         limit: int | None = None,
@@ -1000,7 +1230,7 @@ class SubscriptionsQuery:
             **kwargs
         }.items() if v is not None}
 
-        result = await self._connector.execute("subscriptions", "search", params)
+        result = await self._connector.execute("subscriptions", "api_search", params)
         return result
 
 
@@ -1057,6 +1287,25 @@ class RefundsQuery:
 
 
 
+    async def create(
+        self,
+        **kwargs
+    ) -> Refund:
+        """
+        When you create a new refund, you must specify a Charge or a PaymentIntent object on which to create it. Creating a new refund will refund a charge that has previously been created but not yet refunded.
+
+        Returns:
+            Refund
+        """
+        params = {k: v for k, v in {
+            **kwargs
+        }.items() if v is not None}
+
+        result = await self._connector.execute("refunds", "create", params)
+        return result
+
+
+
     async def get(
         self,
         id: str | None = None,
@@ -1140,6 +1389,25 @@ class ProductsQuery:
 
 
 
+    async def create(
+        self,
+        **kwargs
+    ) -> Product:
+        """
+        Creates a new product object. Your product's name, description, and other information will be displayed in all product and invoice displays.
+
+        Returns:
+            Product
+        """
+        params = {k: v for k, v in {
+            **kwargs
+        }.items() if v is not None}
+
+        result = await self._connector.execute("products", "create", params)
+        return result
+
+
+
     async def get(
         self,
         id: str | None = None,
@@ -1165,13 +1433,63 @@ class ProductsQuery:
 
 
 
-    async def search(
+    async def update(
+        self,
+        id: str | None = None,
+        **kwargs
+    ) -> Product:
+        """
+        Updates the specific product by setting the values of the parameters passed. Any parameters not provided will be left unchanged.
+
+        Args:
+            id: The product ID
+            **kwargs: Additional parameters
+
+        Returns:
+            Product
+        """
+        params = {k: v for k, v in {
+            "id": id,
+            **kwargs
+        }.items() if v is not None}
+
+        result = await self._connector.execute("products", "update", params)
+        return result
+
+
+
+    async def delete(
+        self,
+        id: str | None = None,
+        **kwargs
+    ) -> ProductDeletedResponse:
+        """
+        Deletes a product. Deleting a product is only possible if it has no prices associated with it.
+
+        Args:
+            id: The product ID
+            **kwargs: Additional parameters
+
+        Returns:
+            ProductDeletedResponse
+        """
+        params = {k: v for k, v in {
+            "id": id,
+            **kwargs
+        }.items() if v is not None}
+
+        result = await self._connector.execute("products", "delete", params)
+        return result
+
+
+
+    async def api_search(
         self,
         query: str,
         limit: int | None = None,
         page: str | None = None,
         **kwargs
-    ) -> ProductsSearchResult:
+    ) -> ProductsApiSearchResult:
         """
         Search for products using Stripe's Search Query Language.
 
@@ -1182,7 +1500,7 @@ class ProductsQuery:
             **kwargs: Additional parameters
 
         Returns:
-            ProductsSearchResult
+            ProductsApiSearchResult
         """
         params = {k: v for k, v in {
             "query": query,
@@ -1191,9 +1509,9 @@ class ProductsQuery:
             **kwargs
         }.items() if v is not None}
 
-        result = await self._connector.execute("products", "search", params)
+        result = await self._connector.execute("products", "api_search", params)
         # Cast generic envelope to concrete typed result
-        return ProductsSearchResult(
+        return ProductsApiSearchResult(
             data=result.data,
             meta=result.meta        )
 
@@ -1387,13 +1705,13 @@ class PaymentIntentsQuery:
 
 
 
-    async def search(
+    async def api_search(
         self,
         query: str,
         limit: int | None = None,
         page: str | None = None,
         **kwargs
-    ) -> PaymentIntentsSearchResult:
+    ) -> PaymentIntentsApiSearchResult:
         """
         Search for payment intents using Stripe's Search Query Language.
 
@@ -1404,7 +1722,7 @@ class PaymentIntentsQuery:
             **kwargs: Additional parameters
 
         Returns:
-            PaymentIntentsSearchResult
+            PaymentIntentsApiSearchResult
         """
         params = {k: v for k, v in {
             "query": query,
@@ -1413,9 +1731,9 @@ class PaymentIntentsQuery:
             **kwargs
         }.items() if v is not None}
 
-        result = await self._connector.execute("payment_intents", "search", params)
+        result = await self._connector.execute("payment_intents", "api_search", params)
         # Cast generic envelope to concrete typed result
-        return PaymentIntentsSearchResult(
+        return PaymentIntentsApiSearchResult(
             data=result.data,
             meta=result.meta        )