messaging-core 0.1.2

Python gRPC client for Your Service

Messaging Core Python SDK

Python gRPC client for the Messaging Core service, providing easy access to messaging functionality including user management, conversations, and real-time messaging.

Installation

Prerequisites

• Python 3.8 or higher
• gRPC and Protocol Buffers support

Install from PyPI

pip install messaging-core

Quick Start

Basic Usage

from messaging_core import MessagingCoreClient

# Initialize the client with your server address and API key
client = MessagingCoreClient(
    server_address="your-server-address:50051",  # e.g., "localhost:50051"
    api_key="your-api-key-here",
    use_ssl=False  # Set to True in production
)

# Login with user credentials
try:
    auth_response = client.login(
        username="[e-mail]",
        password="your-secure-password"
    )
    print(f"Successfully logged in as {auth_response.user.email}")
    
    # Get user conversations
    conversations = client.list_conversations()
    print(f"Found {len(conversations)} conversations")
    
    # Send a message
    message = client.send_message(
        conversation_id=conversations[0].id,
        content="Hello from Python SDK!"
    )
    print(f"Message sent with ID: {message.id}")
    
except Exception as e:
    print(f"Error: {e}")

Features

• Authentication: Secure login with JWT tokens
• Conversation Management: Create, list, and manage conversations
• Messaging: Send and receive messages in real-time
• User Management: User profiles and presence
• Attachments: Send and receive files and media

API Reference

Initialization

from messaging_core import MessagingCoreClient

# For development (without SSL)
client = MessagingCoreClient(
    server_address="localhost:50051",
    api_key="your-api-key",
    use_ssl=False
)

# For production (with SSL)
client = MessagingCoreClient(
    server_address="api.yourdomain.com:443",
    api_key="your-api-key",
    use_ssl=True
)

Authentication

# Login with username/password
auth_response = client.login(
    username="[e-mail]",
    password="your-password"
)

# The client automatically handles token refresh
# You can also manually refresh the token
new_tokens = client.refresh_token(
    refresh_token=auth_response.refresh_token
)

# Logout
client.logout()

Conversations

# List conversations with pagination
conversations = client.list_conversations(
    page=1,
    page_size=20
)

# Create a new conversation
conversation = client.create_conversation(
    title="Team Chat",
    participant_ids=["user1", "user2"],
    type="GROUP"
)

# Get conversation details
conversation = client.get_conversation(conversation_id="conv123")

# Delete a conversation
client.delete_conversation(conversation_id="conv123")

Messages

# Send a text message
message = client.send_message(
    conversation_id="conv123",
    content="Hello, world!"
)

# Send a message with metadata
message = client.send_message(
    conversation_id="conv123",
    content="Check this out!",
    metadata={"type": "announcement", "priority": "high"}
)

# Get message history
messages = client.get_messages(
    conversation_id="conv123",
    limit=50,
    before=datetime.utcnow()
)

Users

# Get current user profile
profile = client.get_my_profile()

# Update profile
updated = client.update_profile(
    first_name="John",
    last_name="Doe",
    avatar_url="https://example.com/avatar.jpg"
)

# Search users
users = client.search_users(query="john")

Error Handling

All API calls raise grpc.RpcError for gRPC-related errors. The client also provides custom exceptions for business logic errors.

try:
    client.login(username="[e-mail]", password="wrong-password")
except Exception as e:
    if hasattr(e, 'code') and e.code() == grpc.StatusCode.UNAUTHENTICATED:
        print("Authentication failed: Invalid credentials")
    else:
        print(f"Error: {e}")

Development

For development and contributing, you'll need:

Setup

1. Clone the repository:

   git clone https://github.com/alijkdkar/Messaging-Core.git
   cd Messaging-Core/docs/sdk/python
   

2. Install dependencies:

   poetry install
   

Generating gRPC Code

To regenerate the gRPC code from the .proto files:

./scripts/generate_sdk.sh

Running Tests

pytest tests/

Building the Package

python -m build

Publishing to PyPI

1. Build the package:

   python -m build
   

2. Upload to PyPI:

   twine upload dist/*
   

License

This project is licensed under the MIT License - see the LICENSE file for details.