airwallex-sdk 0.1.0__py3-none-any.whl

airwallex/api/financial_transaction.py

@@ -0,0 +1,123 @@
+"""
+Airwallex Financial Transaction API.
+"""
+from typing import Dict, Any, List, Optional, Type, TypeVar, Union, cast
+from datetime import datetime
+from ..models.financial_transaction import FinancialTransaction
+from .base import AirwallexAPIBase
+
+T = TypeVar("T", bound=FinancialTransaction)
+
+
+class FinancialTransaction(AirwallexAPIBase[FinancialTransaction]):
+    """
+    Operations for Airwallex financial transactions.
+    
+    Financial transactions represent the transactions that contributed to the Airwallex account balance.
+    """
+    endpoint = "financial_transactions"
+    model_class = cast(Type[FinancialTransaction], FinancialTransaction)
+    
+    def list_with_filters(
+        self, 
+        batch_id: Optional[str] = None,
+        currency: Optional[str] = None,
+        from_created_at: Optional[Union[str, datetime]] = None,
+        to_created_at: Optional[Union[str, datetime]] = None,
+        source_id: Optional[str] = None,
+        status: Optional[str] = None,
+        page_num: int = 0,
+        page_size: int = 100
+    ) -> List[FinancialTransaction]:
+        """
+        List financial transactions with filtering options.
+        
+        Args:
+            batch_id: Filter by batch ID
+            currency: Filter by currency (3-letter ISO-4217 code)
+            from_created_at: Filter by creation date (start, inclusive)
+            to_created_at: Filter by creation date (end, inclusive)
+            source_id: Filter by source ID
+            status: Filter by status (PENDING, SETTLED)
+            page_num: Page number (0-indexed) for pagination
+            page_size: Number of transactions per page (max 1000)
+            
+        Returns:
+            List[FinancialTransaction]: List of matching financial transactions
+        """
+        params = {
+            "page_num": page_num,
+            "page_size": page_size
+        }
+        
+        if batch_id:
+            params["batch_id"] = batch_id
+        
+        if currency:
+            params["currency"] = currency
+        
+        if source_id:
+            params["source_id"] = source_id
+        
+        if status:
+            params["status"] = status
+        
+        if from_created_at:
+            params["from_created_at"] = from_created_at
+        
+        if to_created_at:
+            params["to_created_at"] = to_created_at
+        
+        return self.list(**params)
+    
+    async def list_with_filters_async(
+        self, 
+        batch_id: Optional[str] = None,
+        currency: Optional[str] = None,
+        from_created_at: Optional[Union[str, datetime]] = None,
+        to_created_at: Optional[Union[str, datetime]] = None,
+        source_id: Optional[str] = None,
+        status: Optional[str] = None,
+        page_num: int = 0,
+        page_size: int = 100
+    ) -> List[FinancialTransaction]:
+        """
+        List financial transactions with filtering options asynchronously.
+        
+        Args:
+            batch_id: Filter by batch ID
+            currency: Filter by currency (3-letter ISO-4217 code)
+            from_created_at: Filter by creation date (start, inclusive)
+            to_created_at: Filter by creation date (end, inclusive)
+            source_id: Filter by source ID
+            status: Filter by status (PENDING, SETTLED)
+            page_num: Page number (0-indexed) for pagination
+            page_size: Number of transactions per page (max 1000)
+            
+        Returns:
+            List[FinancialTransaction]: List of matching financial transactions
+        """
+        params = {
+            "page_num": page_num,
+            "page_size": page_size
+        }
+        
+        if batch_id:
+            params["batch_id"] = batch_id
+        
+        if currency:
+            params["currency"] = currency
+        
+        if source_id:
+            params["source_id"] = source_id
+        
+        if status:
+            params["status"] = status
+        
+        if from_created_at:
+            params["from_created_at"] = from_created_at
+        
+        if to_created_at:
+            params["to_created_at"] = to_created_at
+        
+        return await self.list_async(**params)

airwallex/api/invoice.py

@@ -0,0 +1,257 @@
+"""
+Airwallex Invoice API.
+"""
+from typing import Dict, Any, List, Optional, Type, TypeVar, Union, cast
+from datetime import datetime
+from ..models.invoice import Invoice, InvoiceItem, InvoicePreviewRequest, InvoicePreviewResponse
+from .base import AirwallexAPIBase
+
+T = TypeVar("T", bound=Invoice)
+
+
+class Invoice(AirwallexAPIBase[Invoice]):
+    """
+    Operations for Airwallex invoices.
+    
+    Invoices record one-off sales transactions between you and your customers.
+    """
+    endpoint = "invoices"
+    model_class = cast(Type[Invoice], Invoice)
+    
+    def preview(self, preview_request: InvoicePreviewRequest) -> InvoicePreviewResponse:
+        """
+        Preview an upcoming invoice.
+        
+        This method allows you to preview the upcoming invoice of an existing subscription
+        or the first invoice before creating a new subscription.
+        
+        Args:
+            preview_request: InvoicePreviewRequest model with preview details
+            
+        Returns:
+            InvoicePreviewResponse: The preview of the upcoming invoice
+        """
+        url = self._build_url(suffix="preview")
+        
+        if not self.client.__class__.__name__.startswith('Async'):
+            response = self.client._request("POST", url, json=preview_request.to_api_dict())
+            return InvoicePreviewResponse.from_api_response(response.json())
+        else:
+            raise ValueError("Use preview_async for async clients")
+    
+    async def preview_async(self, preview_request: InvoicePreviewRequest) -> InvoicePreviewResponse:
+        """
+        Preview an upcoming invoice asynchronously.
+        
+        This method allows you to preview the upcoming invoice of an existing subscription
+        or the first invoice before creating a new subscription.
+        
+        Args:
+            preview_request: InvoicePreviewRequest model with preview details
+            
+        Returns:
+            InvoicePreviewResponse: The preview of the upcoming invoice
+        """
+        url = self._build_url(suffix="preview")
+        
+        if self.client.__class__.__name__.startswith('Async'):
+            response = await self.client._request("POST", url, json=preview_request.to_api_dict())
+            return InvoicePreviewResponse.from_api_response(response.json())
+        else:
+            raise ValueError("Use preview for sync clients")
+    
+    def list_items(self, invoice_id: str, page_num: int = 0, page_size: int = 20) -> List[InvoiceItem]:
+        """
+        List all items for a specific invoice.
+        
+        Args:
+            invoice_id: The ID of the invoice to fetch items for
+            page_num: Page number (0-indexed) for pagination
+            page_size: Number of items per page
+            
+        Returns:
+            List[InvoiceItem]: List of invoice items
+        """
+        url = f"{self._build_url(invoice_id)}/items"
+        params = {
+            "page_num": page_num,
+            "page_size": page_size
+        }
+        
+        if not self.client.__class__.__name__.startswith('Async'):
+            response = self.client._request("GET", url, params=params)
+            data = response.json()
+            
+            if "items" in data:
+                return [InvoiceItem.from_api_response(item) for item in data["items"]]
+            return []
+        else:
+            raise ValueError("Use list_items_async for async clients")
+    
+    async def list_items_async(self, invoice_id: str, page_num: int = 0, page_size: int = 20) -> List[InvoiceItem]:
+        """
+        List all items for a specific invoice asynchronously.
+        
+        Args:
+            invoice_id: The ID of the invoice to fetch items for
+            page_num: Page number (0-indexed) for pagination
+            page_size: Number of items per page
+            
+        Returns:
+            List[InvoiceItem]: List of invoice items
+        """
+        url = f"{self._build_url(invoice_id)}/items"
+        params = {
+            "page_num": page_num,
+            "page_size": page_size
+        }
+        
+        if self.client.__class__.__name__.startswith('Async'):
+            response = await self.client._request("GET", url, params=params)
+            data = response.json()
+            
+            if "items" in data:
+                return [InvoiceItem.from_api_response(item) for item in data["items"]]
+            return []
+        else:
+            raise ValueError("Use list_items for sync clients")
+    
+    def get_item(self, invoice_id: str, item_id: str) -> InvoiceItem:
+        """
+        Retrieve a specific invoice item.
+        
+        Args:
+            invoice_id: The ID of the invoice that contains the item
+            item_id: The ID of the invoice item to retrieve
+            
+        Returns:
+            InvoiceItem: The requested invoice item
+        """
+        url = f"{self._build_url(invoice_id)}/items/{item_id}"
+        
+        if not self.client.__class__.__name__.startswith('Async'):
+            response = self.client._request("GET", url)
+            return InvoiceItem.from_api_response(response.json())
+        else:
+            raise ValueError("Use get_item_async for async clients")
+    
+    async def get_item_async(self, invoice_id: str, item_id: str) -> InvoiceItem:
+        """
+        Retrieve a specific invoice item asynchronously.
+        
+        Args:
+            invoice_id: The ID of the invoice that contains the item
+            item_id: The ID of the invoice item to retrieve
+            
+        Returns:
+            InvoiceItem: The requested invoice item
+        """
+        url = f"{self._build_url(invoice_id)}/items/{item_id}"
+        
+        if self.client.__class__.__name__.startswith('Async'):
+            response = await self.client._request("GET", url)
+            return InvoiceItem.from_api_response(response.json())
+        else:
+            raise ValueError("Use get_item for sync clients")
+    
+    def list_with_filters(
+        self, 
+        customer_id: Optional[str] = None,
+        subscription_id: Optional[str] = None,
+        status: Optional[str] = None,
+        from_created_at: Optional[Union[str, datetime]] = None,
+        to_created_at: Optional[Union[str, datetime]] = None,
+        page_num: int = 0,
+        page_size: int = 20
+    ) -> List[Invoice]:
+        """
+        List invoices with filtering options.
+        
+        Args:
+            customer_id: Filter by customer ID
+            subscription_id: Filter by subscription ID
+            status: Filter by status (SENT, PAID, PAYMENT_FAILED)
+            from_created_at: Filter by creation date (start, inclusive)
+            to_created_at: Filter by creation date (end, exclusive)
+            page_num: Page number (0-indexed) for pagination
+            page_size: Number of invoices per page
+            
+        Returns:
+            List[Invoice]: List of matching invoices
+        """
+        params = {
+            "page_num": page_num,
+            "page_size": page_size
+        }
+        
+        if customer_id:
+            params["customer_id"] = customer_id
+        
+        if subscription_id:
+            params["subscription_id"] = subscription_id
+        
+        if status:
+            params["status"] = status
+        
+        if from_created_at:
+            if isinstance(from_created_at, datetime):
+                from_created_at = from_created_at.isoformat()
+            params["from_created_at"] = from_created_at
+        
+        if to_created_at:
+            if isinstance(to_created_at, datetime):
+                to_created_at = to_created_at.isoformat()
+            params["to_created_at"] = to_created_at
+        
+        return self.list(**params)
+    
+    async def list_with_filters_async(
+        self, 
+        customer_id: Optional[str] = None,
+        subscription_id: Optional[str] = None,
+        status: Optional[str] = None,
+        from_created_at: Optional[Union[str, datetime]] = None,
+        to_created_at: Optional[Union[str, datetime]] = None,
+        page_num: int = 0,
+        page_size: int = 20
+    ) -> List[Invoice]:
+        """
+        List invoices with filtering options asynchronously.
+        
+        Args:
+            customer_id: Filter by customer ID
+            subscription_id: Filter by subscription ID
+            status: Filter by status (SENT, PAID, PAYMENT_FAILED)
+            from_created_at: Filter by creation date (start, inclusive)
+            to_created_at: Filter by creation date (end, exclusive)
+            page_num: Page number (0-indexed) for pagination
+            page_size: Number of invoices per page
+            
+        Returns:
+            List[Invoice]: List of matching invoices
+        """
+        params = {
+            "page_num": page_num,
+            "page_size": page_size
+        }
+        
+        if customer_id:
+            params["customer_id"] = customer_id
+        
+        if subscription_id:
+            params["subscription_id"] = subscription_id
+        
+        if status:
+            params["status"] = status
+        
+        if from_created_at:
+            if isinstance(from_created_at, datetime):
+                from_created_at = from_created_at.isoformat()
+            params["from_created_at"] = from_created_at
+        
+        if to_created_at:
+            if isinstance(to_created_at, datetime):
+                to_created_at = to_created_at.isoformat()
+            params["to_created_at"] = to_created_at
+        
+        return await self.list_async(**params)

airwallex/api/issuing_authorization.py

@@ -0,0 +1,313 @@
+"""
+Airwallex Issuing Authorization API.
+"""
+from typing import Dict, Any, List, Optional, Type, TypeVar, Union, cast
+from datetime import datetime
+from ..models.issuing_authorization import Authorization, AuthorizationListResponse
+from .base import AirwallexAPIBase
+
+T = TypeVar("T", bound=Authorization)
+
+
+class IssuingAuthorization(AirwallexAPIBase[Authorization]):
+    """
+    Operations for Airwallex issuing authorizations.
+    
+    Authorizations represent pre-auth and capture processed against individual cards.
+    """
+    endpoint = "issuing/authorizations"
+    model_class = cast(Type[Authorization], Authorization)
+    
+    def list_with_filters(
+        self,
+        billing_currency: Optional[str] = None,
+        card_id: Optional[str] = None,
+        digital_wallet_token_id: Optional[str] = None,
+        from_created_at: Optional[Union[str, datetime]] = None,
+        lifecycle_id: Optional[str] = None,
+        page_num: int = 0,
+        page_size: int = 10,
+        retrieval_ref: Optional[str] = None,
+        status: Optional[str] = None,
+        to_created_at: Optional[Union[str, datetime]] = None,
+    ) -> List[Authorization]:
+        """
+        List authorizations with filtering options.
+        
+        Args:
+            billing_currency: Currency in which transition was billed (3-letter ISO-4217 code)
+            card_id: Unique Identifier for card
+            digital_wallet_token_id: Unique Identifier for digital token
+            from_created_at: Start of Transaction Date in ISO8601 format (inclusive)
+            lifecycle_id: Unique Identifier for lifecycle
+            page_num: Page number, starts from 0
+            page_size: Number of results per page
+            retrieval_ref: Retrieval reference number
+            status: Authorization status (CLEARED, EXPIRED, FAILED, PENDING, REVERSED)
+            to_created_at: End of Transaction Date in ISO8601 format (exclusive)
+            
+        Returns:
+            List[Authorization]: List of matching authorizations
+        """
+        params = {
+            "page_num": page_num,
+            "page_size": page_size
+        }
+        
+        if billing_currency:
+            params["billing_currency"] = billing_currency
+        
+        if card_id:
+            params["card_id"] = card_id
+            
+        if digital_wallet_token_id:
+            params["digital_wallet_token_id"] = digital_wallet_token_id
+            
+        if from_created_at:
+            if isinstance(from_created_at, datetime):
+                from_created_at = from_created_at.isoformat()
+            params["from_created_at"] = from_created_at
+            
+        if lifecycle_id:
+            params["lifecycle_id"] = lifecycle_id
+            
+        if retrieval_ref:
+            params["retrieval_ref"] = retrieval_ref
+            
+        if status:
+            params["status"] = status
+            
+        if to_created_at:
+            if isinstance(to_created_at, datetime):
+                to_created_at = to_created_at.isoformat()
+            params["to_created_at"] = to_created_at
+        
+        if not self.client.__class__.__name__.startswith('Async'):
+            response = self.client._request("GET", self._build_url(), params=params)
+            data = response.json()
+            return [self.model_class.from_api_response(item) for item in data.get("items", [])]
+        else:
+            raise ValueError("Use list_with_filters_async for async clients")
+    
+    async def list_with_filters_async(
+        self,
+        billing_currency: Optional[str] = None,
+        card_id: Optional[str] = None,
+        digital_wallet_token_id: Optional[str] = None,
+        from_created_at: Optional[Union[str, datetime]] = None,
+        lifecycle_id: Optional[str] = None,
+        page_num: int = 0,
+        page_size: int = 10,
+        retrieval_ref: Optional[str] = None,
+        status: Optional[str] = None,
+        to_created_at: Optional[Union[str, datetime]] = None,
+    ) -> List[Authorization]:
+        """
+        List authorizations with filtering options asynchronously.
+        
+        Args:
+            billing_currency: Currency in which transition was billed (3-letter ISO-4217 code)
+            card_id: Unique Identifier for card
+            digital_wallet_token_id: Unique Identifier for digital token
+            from_created_at: Start of Transaction Date in ISO8601 format (inclusive)
+            lifecycle_id: Unique Identifier for lifecycle
+            page_num: Page number, starts from 0
+            page_size: Number of results per page
+            retrieval_ref: Retrieval reference number
+            status: Authorization status (CLEARED, EXPIRED, FAILED, PENDING, REVERSED)
+            to_created_at: End of Transaction Date in ISO8601 format (exclusive)
+            
+        Returns:
+            List[Authorization]: List of matching authorizations
+        """
+        params = {
+            "page_num": page_num,
+            "page_size": page_size
+        }
+        
+        if billing_currency:
+            params["billing_currency"] = billing_currency
+        
+        if card_id:
+            params["card_id"] = card_id
+            
+        if digital_wallet_token_id:
+            params["digital_wallet_token_id"] = digital_wallet_token_id
+            
+        if from_created_at:
+            if isinstance(from_created_at, datetime):
+                from_created_at = from_created_at.isoformat()
+            params["from_created_at"] = from_created_at
+            
+        if lifecycle_id:
+            params["lifecycle_id"] = lifecycle_id
+            
+        if retrieval_ref:
+            params["retrieval_ref"] = retrieval_ref
+            
+        if status:
+            params["status"] = status
+            
+        if to_created_at:
+            if isinstance(to_created_at, datetime):
+                to_created_at = to_created_at.isoformat()
+            params["to_created_at"] = to_created_at
+        
+        if self.client.__class__.__name__.startswith('Async'):
+            response = await self.client._request("GET", self._build_url(), params=params)
+            data = response.json()
+            return [self.model_class.from_api_response(item) for item in data.get("items", [])]
+        else:
+            raise ValueError("Use list_with_filters for sync clients")
+    
+    def paginate(self, **params: Any) -> List[Authorization]:
+        """
+        Fetch all pages of authorizations.
+        
+        Args:
+            **params: Filter parameters to pass to the API
+            
+        Returns:
+            List[Authorization]: All authorizations matching the filters
+        """
+        if str(self.client.__class__.__name__).startswith('Async'):
+            raise ValueError("This method requires a sync client.")
+            
+        all_items: List[Dict[str, Any]] = []
+        page_num = params.get("page_num", 0)
+        page_size = params.get("page_size", 10)
+        
+        while True:
+            params["page_num"] = page_num
+            params["page_size"] = page_size
+            
+            response = self.client._request("GET", self._build_url(), params=params)
+            data = response.json()
+            
+            items = data.get("items", [])
+            has_more = data.get("has_more", False)
+            
+            if not items:
+                break
+                
+            all_items.extend(items)
+            
+            if not has_more:
+                break
+                
+            page_num += 1
+                
+        return [self.model_class.from_api_response(item) for item in all_items]
+    
+    async def paginate_async(self, **params: Any) -> List[Authorization]:
+        """
+        Fetch all pages of authorizations asynchronously.
+        
+        Args:
+            **params: Filter parameters to pass to the API
+            
+        Returns:
+            List[Authorization]: All authorizations matching the filters
+        """
+        if not self.client.__class__.__name__.startswith('Async'):
+            raise ValueError("This method requires an async client.")
+            
+        all_items: List[Dict[str, Any]] = []
+        page_num = params.get("page_num", 0)
+        page_size = params.get("page_size", 10)
+        
+        while True:
+            params["page_num"] = page_num
+            params["page_size"] = page_size
+            
+            response = await self.client._request("GET", self._build_url(), params=params)
+            data = response.json()
+            
+            items = data.get("items", [])
+            has_more = data.get("has_more", False)
+            
+            if not items:
+                break
+                
+            all_items.extend(items)
+            
+            if not has_more:
+                break
+                
+            page_num += 1
+                
+        return [self.model_class.from_api_response(item) for item in all_items]
+    
+    def paginate_generator(self, **params: Any):
+        """
+        Generate items one by one from paginated results.
+        
+        Args:
+            **params: Filter parameters to pass to the API
+            
+        Yields:
+            Authorization: Authorization objects one by one
+        """
+        if self.client.__class__.__name__.startswith('Async'):
+            raise ValueError("This method requires a sync client.")
+            
+        page_num = params.get("page_num", 0)
+        page_size = params.get("page_size", 10)
+        
+        while True:
+            params["page_num"] = page_num
+            params["page_size"] = page_size
+            
+            response = self.client._request("GET", self._build_url(), params=params)
+            data = response.json()
+            
+            items = data.get("items", [])
+            has_more = data.get("has_more", False)
+            
+            if not items:
+                break
+                
+            for item in items:
+                yield self.model_class.from_api_response(item)
+            
+            if not has_more:
+                break
+                
+            page_num += 1
+    
+    async def paginate_async_generator(self, **params: Any):
+        """
+        Generate items one by one from paginated results asynchronously.
+        
+        Args:
+            **params: Filter parameters to pass to the API
+            
+        Yields:
+            Authorization: Authorization objects one by one
+        """
+        if not self.client.__class__.__name__.startswith('Async'):
+            raise ValueError("This method requires an async client.")
+            
+        page_num = params.get("page_num", 0)
+        page_size = params.get("page_size", 10)
+        
+        while True:
+            params["page_num"] = page_num
+            params["page_size"] = page_size
+            
+            response = await self.client._request("GET", self._build_url(), params=params)
+            data = response.json()
+            
+            items = data.get("items", [])
+            has_more = data.get("has_more", False)
+            
+            if not items:
+                break
+                
+            for item in items:
+                yield self.model_class.from_api_response(item)
+            
+            if not has_more:
+                break
+                
+            page_num += 1