feat: move endpoints services to openapi gateway

Author: fatemefallah

docs/en/services/chat.md

@@ -11,12 +11,12 @@ different message types, manage chat participants, and track chat history and up
 
 ## Chat Methods
 
-| Method                                | Description       | Parameters                    |
-|---------------------------------------|-------------------|-------------------------------|
-| [`create_message()`](#create-message) | Create a message  | `request: MessageRequest`     |
-| [`create_chat()`](#create-chat)       | Create a chat     | `request: CreateChatRequest`  |
-| [`get_messages()`](#get-messages)     | Get chat messages | `request: GetMessagesRequest` |
-| [`get_chats()`](#get-chats)           | Get chats list    | `request: GetChatsRequest`    |
+| Method                                | Description       | Parameters                                                     |
+|---------------------------------------|-------------------|----------------------------------------------------------------|
+| [`create_message()`](#create-message) | Create a message  | `chat_id: int, request: MessageRequest`                        |
+| [`create_chat()`](#create-chat)       | Create a chat     | `request: CreateChatRequest`                                   |
+| [`get_messages()`](#get-messages)     | Get chat messages | `chat_id: int, request: Optional[GetMessagesRequest] = None`   |
+| [`get_chats()`](#get-chats)           | Get chats list    | `request: GetChatsRequest`                                     |
 
 ## Examples
 
@@ -46,7 +46,7 @@ async def create_message_example():
             text="Hello, how can I help you?"
         )
     )
-    message = await client.create_message(request=request)
+    message = await client.chat.create_message(chat_id=123, request=request)
     return message
 ```
 
@@ -60,7 +60,7 @@ async def create_chat_example():
     request = CreateChatRequest(
         user_id=123
     )
-    new_chat = await client.create_chat(request=request)
+    new_chat = await client.chat.create_chat(request=request)
     return new_chat
 ```
 
@@ -72,12 +72,21 @@ from basalam_sdk.chat.models import GetMessagesRequest
 
 async def get_messages_example():
     request = GetMessagesRequest(
-        chat_id=123,
         message_id=456,
         limit=20,
         order="desc",
     )
-    messages = await client.get_messages(request=request)
+    messages = await client.chat.get_messages(chat_id=123, request=request)
+
+    # Option 2: With default parameters (request is optional)
+    messages = await client.chat.get_messages(chat_id=123)
+
+    # Option 3: With only some custom parameters
+    messages = await client.chat.get_messages(
+        chat_id=123,
+        request=GetMessagesRequest(limit=50)
+    )
+
     return messages
 ```
 
@@ -93,7 +102,7 @@ async def get_chats_example():
         order_by=MessageOrderByEnum.UPDATED_AT,
         filters=MessageFiltersEnum.UNSEEN
     )
-    chats = await client.get_chats(request=request)
+    chats = await client.chat.get_chats(request=request)
     return chats
 ```
 

docs/en/services/core.md

@@ -48,7 +48,7 @@ information, handle bank account operations, and manage categories and attribute
 | [`verify_user_bank_account_otp()`](#verify-user-bank-account-otp)                                     | Verify bank account OTP                        | `user_id`, `request: UserCardsOtpSchema`                                   |
 | [`verify_user_bank_account()`](#verify-user-bank-account)                                             | Verify bank accounts                           | `user_id`, `request: UserVerifyBankInformationSchema`                      |
 | [`delete_user_bank_account()`](#delete-user-bank-account)                                             | Delete bank account                            | `user_id`, `bank_account_id`                                               |
-| [`update_user_bank_account()`](#update-user-bank-account)                                             | Update bank account                            | `bank_account_id`, `request: UpdateUserBankInformationSchema`              |
+| [`update_user_bank_account()`](#update-user-bank-account)                                             | Update bank account                            | `user_id`, `bank_account_id`, `request: UpdateUserBankInformationSchema`   |
 | [`update_user_verification()`](#update-user-verification)                                             | Update user verification                       | `user_id`, `request: UserVerificationSchema`                               |
 | [`get_category_attributes()`](#get-category-attributes)                                               | Get category attributes                        | `category_id`, `product_id`, `vendor_id`, `exclude_multi_selects`          |
 | [`get_categories()`](#get-categories)                                                                 | Get all categories                             | `None`                                                                     |

docs/en/services/wallet.md

@@ -24,8 +24,8 @@ refunds, and handle credit-specific operations.
 | [`get_expense_by_ref()`](#get-expense-by-ref-example)                 | Get expense by reference            | `user_id`, `reason_id`, `reference_id`, `x_operator_id`                       |
 | [`delete_expense_by_ref()`](#delete-expense-by-ref-example)           | Delete expense by reference         | `user_id`, `reason_id`, `reference_id`, `rollback_reason_id`, `x_operator_id` |
 | [`create_refund()`](#create-refund-example)                           | Process a refund                    | `request`, `x_operator_id`                                                    |
-| [`can_rollback_refund()`](#can-rollback-refund-example)               | Check if refund can be rolled back  | `refund_reason`, `refund_reference_id`, `x_operator_id`                       |
-| [`rollback_refund()`](#rollback-refund-example)                       | Rollback a refund                   | `request`, `x_operator_id`                                                    |
+| [`can_rollback_refund()`](#can-rollback-refund-example)               | Check if refund can be rolled back  | `refund_id`, `refund_reason`, `refund_reference_id`, `x_operator_id`|                                                |
+| [`rollback_refund()`](#rollback-refund-example)                       | Rollback a refund                   | `refund_id`, `request`, `x_operator_id`                                       |
 
 ## Examples
 
@@ -49,7 +49,7 @@ client = BasalamClient(auth=auth)
 
 ```python
 async def get_balance_example():
-    balance = await client.get_balance(
+    balance = await client.wallet.get_balance(
         user_id=123,
         filters=[
             BalanceFilter(
@@ -61,7 +61,7 @@ async def get_balance_example():
         ],
         x_operator_id=456
     )
-    
+
     print(f"User balance: {balance}")
     return balance
 ```
@@ -70,7 +70,7 @@ async def get_balance_example():
 
 ```python
 async def get_transactions_example():
-    transactions = await client.get_transactions(
+    transactions = await client.wallet.get_transactions(
         user_id=123,
         page=1,
         per_page=20,
@@ -87,7 +87,7 @@ async def get_transactions_example():
 
 ```python
 async def create_expense_example():
-    expense = await client.create_expense(
+    expense = await client.wallet.create_expense(
         user_id=123,
         request=SpendCreditRequest(
             reason_id=1,
@@ -112,7 +112,7 @@ async def create_expense_example():
 
 ```python
 async def create_expense_from_credit_example():
-    expense = await client.create_expense_from_credit(
+    expense = await client.wallet.create_expense_from_credit(
         user_id=123,
         credit_id=789,
         request=SpendSpecificCreditRequest(
@@ -137,7 +137,7 @@ async def create_expense_from_credit_example():
 
 ```python
 async def get_expense_example():
-    expense = await client.get_expense(
+    expense = await client.wallet.get_expense(
         user_id=123,
         expense_id=456,
         x_operator_id=456
@@ -153,7 +153,7 @@ async def get_expense_example():
 
 ```python
 async def delete_expense_example():
-    result = await client.delete_expense(
+    result = await client.wallet.delete_expense(
         user_id=123,
         expense_id=456,
         rollback_reason_id=2,
@@ -168,7 +168,7 @@ async def delete_expense_example():
 
 ```python
 async def get_expense_by_ref_example():
-    expense = await client.get_expense_by_ref(
+    expense = await client.wallet.get_expense_by_ref(
         user_id=123,
         reason_id=1,
         reference_id=456,
@@ -184,7 +184,7 @@ async def get_expense_by_ref_example():
 
 ```python
 async def delete_expense_by_ref_example():
-    result = await client.delete_expense_by_ref(
+    result = await client.wallet.delete_expense_by_ref(
         user_id=123,
         reason_id=1,
         reference_id=456,
@@ -200,7 +200,7 @@ async def delete_expense_by_ref_example():
 
 ```python
 async def create_refund_example():
-    refund = await client.create_refund(
+    refund = await client.wallet.create_refund(
         request=RefundRequest(
             original_reason=1,
             original_reference_id=456,
@@ -226,23 +226,25 @@ async def create_refund_example():
 
 ```python
 async def can_rollback_refund_example():
-    can_rollback = await client.can_rollback_refund(
-        refund_reason=2,
-        refund_reference_id=789,
+    # Assuming refund_id is 999
+    can_rollback = await client.wallet.can_rollback_refund(
+        refund_id=999,
         x_operator_id=456
     )
-    
+
     print(f"Can rollback refund: {can_rollback.status}")
     print(f"Message: {can_rollback.message}")
-    
+
     return can_rollback
 ```
 
 ### Rollback Refund Example
 
 ```python
 async def rollback_refund_example():
-    result = await client.rollback_refund(
+    # Assuming refund_id is 999
+    result = await client.wallet.rollback_refund(
+        refund_id=999,
         request=RollbackRefundRequest(
             refund_reason=2,
             rollback_refund_reason=3,
@@ -258,7 +260,7 @@ async def rollback_refund_example():
         ),
         x_operator_id=456
     )
-    
+
     print(f"Refund rolled back: {result.id}")
     return result
 ```

src/basalam_sdk/auth.py

@@ -385,7 +385,6 @@ async def refresh_token(self) -> TokenInfo:
         Note: Personal Token flow doesn't support automatic token refresh.
         You need to provide a new token manually.
         """
-        print("Token refresh not supported for PersonalToken authentication. Please provide a new token manually.")
         return self._token_info
 
     def refresh_token_sync(self) -> TokenInfo:
@@ -395,7 +394,6 @@ def refresh_token_sync(self) -> TokenInfo:
         Note: Personal Token flow doesn't support automatic token refresh.
         You need to provide a new token manually.
         """
-        print("Token refresh not supported for PersonalToken authentication. Please provide a new token manually.")
         return self._token_info
 
 
@@ -545,7 +543,6 @@ async def refresh_token(self) -> TokenInfo:
         """
         Refresh token functionality is not available in this implementation.
         """
-        print("Refresh token functionality is not available for this authorization code implementation.")
         if not self._token_info:
             raise BasalamAuthError("No token available. You must first exchange an authorization code.")
         return self._token_info
@@ -554,7 +551,6 @@ def refresh_token_sync(self) -> TokenInfo:
         """
         Refresh token functionality is not available in this implementation.
         """
-        print("Refresh token functionality is not available for this authorization code implementation.")
         if not self._token_info:
             raise BasalamAuthError("No token available. You must first exchange an authorization code.")
         return self._token_info

src/basalam_sdk/basalam_client.pyi

@@ -111,8 +111,8 @@ class BasalamClient:
     def create_message_sync( self, request: MessageRequest, user_agent: Optional[str] = None ) -> MessageResponse: ...
     async def get_chats( self, request: GetChatsRequest ) -> ChatListResponse: ...
     def get_chats_sync( self, request: GetChatsRequest ) -> ChatListResponse: ...
-    async def get_messages( self, request: GetMessagesRequest ) -> GetMessagesResponse: ...
-    def get_messages_sync( self, request: GetMessagesRequest ) -> GetMessagesResponse: ...
+    async def get_messages( self, request: Optional[GetMessagesRequest] = None ) -> GetMessagesResponse: ...
+    def get_messages_sync( self, request: Optional[GetMessagesRequest] = None ) -> GetMessagesResponse: ...
     async def create_invoice_payment( self, invoice_id: int, request: CreatePaymentRequestModel ) -> Dict[str, Any]: ...
     def create_invoice_payment_sync( self, invoice_id: int, request: CreatePaymentRequestModel ) -> Dict[str, Any]: ...
     async def create_payment_callback( self, payment_id: int, request: PaymentVerifyRequestModel ) -> Dict[str, Any]: ...
@@ -147,14 +147,8 @@ class BasalamClient:
     def search_products_sync(self, request: ProductSearchModel) -> Dict[str, Any]: ...
     async def upload_file( self, file: BinaryIO, file_type: UserUploadFileTypeEnum, custom_unique_name: Optional[str] = None, expire_minutes: Optional[int] = None ) -> FileResponse: ...
     def upload_file_sync( self, file: BinaryIO, file_type: UserUploadFileTypeEnum, custom_unique_name: Optional[str] = None, expire_minutes: Optional[int] = None ) -> FileResponse: ...
-    async def can_rollback_refund( self, refund_reason: int, refund_reference_id: int, x_operator_id: Optional[int] = None ) -> CanRollbackRefundResponse: ...
-    def can_rollback_refund_sync( self, refund_reason: int, refund_reference_id: int, x_operator_id: Optional[int] = None ) -> CanRollbackRefundResponse: ...
     async def create_expense( self, user_id: int, request: SpendCreditRequest, x_operator_id: Optional[int] = None ) -> SpendResponse: ...
-    async def create_expense_from_credit( self, user_id: int, credit_id: int, request: SpendSpecificCreditRequest, x_operator_id: Optional[int] = None ) -> SpendResponse: ...
-    def create_expense_from_credit_sync( self, user_id: int, credit_id: int, request: SpendSpecificCreditRequest, x_operator_id: Optional[int] = None ) -> SpendResponse: ...
     def create_expense_sync( self, user_id: int, request: SpendCreditRequest, x_operator_id: Optional[int] = None ) -> SpendResponse: ...
-    async def create_refund( self, request: RefundRequest, x_operator_id: Optional[int] = None ) -> Union[CreditCreationResponse, SpendResponse]: ...
-    def create_refund_sync( self, request: RefundRequest, x_operator_id: Optional[int] = None ) -> Union[CreditCreationResponse, SpendResponse]: ...
     async def delete_expense( self, user_id: int, expense_id: int, rollback_reason_id: int, x_operator_id: Optional[int] = None ) -> SpendResponse: ...
     async def delete_expense_by_ref( self, user_id: int, reason_id: int, reference_id: int, rollback_reason_id: int, x_operator_id: Optional[int] = None ) -> SpendResponse: ...
     def delete_expense_by_ref_sync( self, user_id: int, reason_id: int, reference_id: int, rollback_reason_id: int, x_operator_id: Optional[int] = None ) -> SpendResponse: ...
@@ -167,8 +161,6 @@ class BasalamClient:
     def get_expense_sync( self, user_id: int, expense_id: int, x_operator_id: Optional[int] = None ) -> SpendResponse: ...
     async def get_transactions( self, user_id: int, page: int = 1, per_page: int = 50, x_operator_id: Optional[int] = None ) -> HistoryPaginationResponse: ...
     def get_transactions_sync( self, user_id: int, page: int = 1, per_page: int = 50, x_operator_id: Optional[int] = None ) -> HistoryPaginationResponse: ...
-    async def rollback_refund( self, request: RollbackRefundRequest, x_operator_id: Optional[int] = None ) -> SpendResponse: ...
-    def rollback_refund_sync( self, request: RollbackRefundRequest, x_operator_id: Optional[int] = None ) -> SpendResponse: ...
     async def create_webhook(self, request: CreateWebhookRequest) -> WebhookResource: ...
     async def create_webhook_service(self, request: CreateServiceRequest) -> ServiceResource: ...
     def create_webhook_service_sync(self, request: CreateServiceRequest) -> ServiceResource: ...

src/basalam_sdk/base_client.py

@@ -72,6 +72,32 @@ def _handle_http_error(e: httpx.HTTPStatusError) -> None:
             response=e.response,
         )
 
+    @staticmethod
+    def _unwrap_response(data: Union[Dict, List]) -> Union[Dict, List]:
+        """
+        Unwrap response data if it's wrapped in a single-key dictionary.
+
+        This handles cases where the API returns data wrapped in a single key,
+        like {"openapi_raw_data": [...]} or any future wrapper format.
+
+        Args:
+            data: The response data to unwrap
+
+        Returns:
+            The unwrapped data if it was wrapped, otherwise the original data
+        """
+        # If it's a dict with exactإإly one key and the value is a list,
+        # return the list value (unwrap it)
+        if isinstance(data, dict) and len(data) == 1:
+            key = next(iter(data))
+            value = data[key]
+            # Only unwrap if the single value is a list (common for wrapped list responses)
+            # This preserves single-key dict responses that are meant to be dicts
+            if isinstance(value, list):
+                return value
+
+        return data
+
     @staticmethod
     def _parse_response_data(
             response: httpx.Response,