Wonksknow Chat API

✨ Features

🚀 Quick Start

Prerequisites

• Go 1.21 or higher
• MongoDB (local or MongoDB Atlas)
• Environment variables configured (see .env.example)

Installation

1. Clone the repository:

   git clone <repository-url>
   cd wonksknow-chat

2. Install dependencies:

   go mod download

3. Configure environment variables:

   cp env.example .env
   # Edit .env with your configuration

4. Run the application:

   go run main.go

The server will start on http://localhost:8080 (or the port specified in SERVER_PORT).

👥 Tenant Onboarding Guide

This guide will walk you through the process of signing up as a tenant, generating tokens, and using all the APIs.

curl -X POST http://localhost:8080/api/v1/tenants \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Company"
  }'

{
  "id": "tenant-uuid-here",
  "name": "My Company",
  "api_key": "api-key-uuid-here",
  "is_active": true,
  "message": "Tenant created successfully. Please save the API key securely."
}

curl -X POST http://localhost:8080/api/v1/tenant/{tenant_id}/auth/token \
  -H "X-API-Key: your-api-key-here"

{
  "token": "generated-token-here",
  "tenant_id": "tenant-uuid-here",
  "expires_at": "2024-11-20T10:29:07Z",
  "expires_in": 86400
}

curl -X POST http://localhost:8080/api/v1/users \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-token-here" \
  -H "X-Tenant-ID: your-tenant-id-here" \
  -H "X-User-ID: admin-user-id-here" \
  -d '{
    "name": "John Doe",
    "email": "john@example.com",
    "phone": "+1234567890"
  }'

{
  "id": "user-uuid-here",
  "tenant_id": "tenant-uuid-here",
  "name": "John Doe",
  "email": "john@example.com",
  "phone": "+1234567890",
  "is_active": true,
  "created_at": "2024-11-19T10:29:07Z",
  "updated_at": "2024-11-19T10:29:07Z"
}

curl -X POST http://localhost:8080/api/v1/groups \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-token-here" \
  -H "X-Tenant-ID: your-tenant-id-here" \
  -H "X-User-ID: admin-user-id-here" \
  -d '{
    "name": "Team Chat",
    "description": "Team discussion room",
    "user_ids": ["user-id-1", "user-id-2", "user-id-3"]
  }'

curl -X POST http://localhost:8080/api/v1/chats \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-token-here" \
  -H "X-Tenant-ID: your-tenant-id-here" \
  -H "X-User-ID: sender-user-id-here" \
  -d '{
    "receiver_id": "receiver-user-id-here",
    "message_body": "Hello! How are you?",
    "message_type": "text"
  }'

curl -X POST http://localhost:8080/api/v1/chats \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-token-here" \
  -H "X-Tenant-ID: your-tenant-id-here" \
  -H "X-User-ID: sender-user-id-here" \
  -d '{
    "group_id": "group-id-here",
    "message_body": "Hello team!",
    "message_type": "text"
  }'

const token = 'your-token-here';
const ws = new WebSocket(`ws://localhost:8080/api/v1/ws?token=${token}`);

ws.onopen = () => {
  console.log('WebSocket connected');
  
  // Send a message
  ws.send(JSON.stringify({
    type: 'message',
    tenant_id: 'your-tenant-id',
    chat_id: 'message-id-here',
    sender_id: 'sender-user-id',
    data: {
      receiver_id: 'receiver-user-id',
      message_body: 'Hello via WebSocket!'
    },
    timestamp: new Date().toISOString()
  }));
};

ws.onmessage = (event) => {
  const message = JSON.parse(event.data);
  console.log('Received message:', message);
};

ws.onerror = (error) => {
  console.error('WebSocket error:', error);
};

ws.onclose = () => {
  console.log('WebSocket disconnected');
};

📚 API Documentation

Interactive Swagger documentation is available at:

• Swagger UI: http://localhost:8080/swagger/index.html
• Swagger JSON: http://localhost:8080/swagger/doc.json
• Swagger YAML: http://localhost:8080/swagger/doc.yaml

🔐 Authentication

API Key Authentication

Used for generating tenant authentication tokens.

Header:

X-API-Key: your-api-key-here

Used in:

• POST /api/v1/tenant/{tenant_id}/auth/token

Bearer Token Authentication

Used for all authenticated API endpoints.

Headers:

Authorization: Bearer your-token-here
X-Tenant-ID: your-tenant-id-here
X-User-ID: your-user-id-here (optional, for RBAC)

Used in:

• All /api/v1/users, /api/v1/groups, /api/v1/chats, and /api/v1/rbac endpoints

🔗 API Endpoints

Tenants

Authentication

Users

Groups

Chats

RBAC

WebSocket

🔌 WebSocket API

Connection

Connect to ws://localhost:8080/api/v1/ws?token={your-token} or use Bearer token in Authorization header.

Message Types

Send Message

{
  "type": "message",
  "tenant_id": "tenant-id",
  "sender_id": "user-id",
  "data": {
    "receiver_id": "receiver-id",
    "message_body": "Hello!",
    "message_type": "text"
  },
  "timestamp": "2024-11-19T10:29:07Z"
}

Typing Indicator

{
  "type": "typing",
  "tenant_id": "tenant-id",
  "sender_id": "user-id",
  "data": {
    "receiver_id": "receiver-id",
    "is_typing": true
  },
  "timestamp": "2024-11-19T10:29:07Z"
}

Read Receipt

{
  "type": "read_receipt",
  "tenant_id": "tenant-id",
  "sender_id": "user-id",
  "data": {
    "chat_ids": ["msg-id-1", "msg-id-2"]
  },
  "timestamp": "2024-11-19T10:29:07Z"
}

🛡️ Permissions and RBAC

Default Permissions

Permissions follow the format: {resource}:{action}

Resources:

• users - User management
• groups - Group management
• chats - Chat/message operations
• rbac - Role and permission management

Actions:

• create - Create new resources
• read - Read/list resources
• update - Update existing resources
• delete - Delete resources

Wildcard:

• * - All actions (e.g., users:* = all user permissions)

Creating Roles

Example: Admin Role

curl -X POST http://localhost:8080/api/v1/rbac/roles \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-token-here" \
  -H "X-Tenant-ID: your-tenant-id-here" \
  -H "X-User-ID: admin-user-id-here" \
  -d '{
    "name": "Admin",
    "description": "Full access to all resources",
    "permissions": [
      "users:*",
      "groups:*",
      "chats:*",
      "rbac:*"
    ]
  }'

🎨 UI Components

Ready-to-use UI components for easy integration into your application. All components support WebSocket for real-time messaging and customizable theming.

1. Chat Window Component

A complete chat window with WebSocket integration, message history, typing indicators, and connection status.

Endpoint: GET /ui/chat-window

Parameters:

*Either receiver_id or group_id must be provided.

Example - Direct Message:

<iframe 
  src="http://localhost:8080/ui/chat-window?tenant_id=xxx&user_id=yyy&token=zzz&receiver_id=aaa&primary_color=%234F46E5&secondary_color=%237C3AED" 
  width="100%" 
  height="700px" 
  style="border: none;">
</iframe>

Example - Group Chat:

<iframe 
  src="http://localhost:8080/ui/chat-window?tenant_id=xxx&user_id=yyy&token=zzz&group_id=ggg" 
  width="100%" 
  height="700px" 
  style="border: none;">
</iframe>

2. Roster Component

A contact and group list component with search functionality. Click on contacts or groups to open the chat window.

Endpoint: GET /ui/roster

Parameters:

Example:

<iframe 
  src="http://localhost:8080/ui/roster?tenant_id=xxx&user_id=yyy&token=zzz&primary_color=%23FF5733&secondary_color=%23FFC300" 
  width="400" 
  height="600" 
  style="border: 1px solid #ddd; border-radius: 8px;">
</iframe>

3. Participant List Component

Display all participants in a group with their names and emails.

Endpoint: GET /ui/participants

Parameters:

Example:

<iframe 
  src="http://localhost:8080/ui/participants?tenant_id=xxx&group_id=ggg&token=zzz" 
  width="100%" 
  height="500px" 
  style="border: none;">
</iframe>

Demo Page

Test all UI components interactively:

http://localhost:8080/demo?api_key=YOUR_API_KEY

Or with custom colors:

http://localhost:8080/demo?api_key=YOUR_API_KEY&primary_color=%234F46E5&secondary_color=%237C3AED

💡 Examples

Complete Flow Example

# 1. Create tenant
TENANT_RESPONSE=$(curl -X POST http://localhost:8080/api/v1/tenants \
  -H "Content-Type: application/json" \
  -d '{"name": "My Company"}')
TENANT_ID=$(echo $TENANT_RESPONSE | jq -r '.id')
API_KEY=$(echo $TENANT_RESPONSE | jq -r '.api_key')

# 2. Generate token
TOKEN_RESPONSE=$(curl -X POST http://localhost:8080/api/v1/tenant/$TENANT_ID/auth/token \
  -H "X-API-Key: $API_KEY")
TOKEN=$(echo $TOKEN_RESPONSE | jq -r '.token')

# 3. Create user
USER_RESPONSE=$(curl -X POST http://localhost:8080/api/v1/users \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Tenant-ID: $TENANT_ID" \
  -H "X-User-ID: admin-user-id" \
  -d '{"name": "John Doe", "email": "john@example.com", "phone": "+1234567890"}')
USER_ID=$(echo $USER_RESPONSE | jq -r '.id')

# 4. Send message
curl -X POST http://localhost:8080/api/v1/chats \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Tenant-ID: $TENANT_ID" \
  -H "X-User-ID: $USER_ID" \
  -d '{
    "receiver_id": "another-user-id",
    "message_body": "Hello!",
    "message_type": "text"
  }'

⚙️ Configuration

Environment variables (see .env.example):

• SERVER_PORT - Server port (default: 8080)
• MONGO_URI - MongoDB connection string
• JWT_SECRET - Secret key for JWT tokens
• JWT_EXPIRY_HOURS - Token expiry in hours (default: 24)
• ENVIRONMENT - Environment (development/production)
• GOOGLE_CLIENT_ID - Google OAuth client ID (optional)
• GOOGLE_CLIENT_SECRET - Google OAuth client secret (optional)
• GITHUB_CLIENT_ID - GitHub OAuth client ID (optional)
• GITHUB_CLIENT_SECRET - GitHub OAuth client secret (optional)

⚠️ Error Handling

The API returns standard HTTP status codes:

• 200 - Success
• 201 - Created
• 400 - Bad Request
• 401 - Unauthorized
• 403 - Forbidden (Insufficient permissions)
• 404 - Not Found
• 500 - Internal Server Error

Error Response Format:

{
  "error": "Error message description"
}