bosa-server-plugins-binary 0.14.9
BOSA Server Plugins
Requires Python: <3.14,>=3.11

# BOSA Server Plugins

A comprehensive collection of Plugin Routes for interacting with GitHub, Google services, Twitter, and other third-party APIs. Built on the BOSA Core plugin architecture.

## Features

- **Multi-Platform Integration**: GitHub, Google Drive, Google Mail, Google Docs, Twitter
- **OAuth Authentication**: Secure authentication flows for all platforms
- **Plugin Architecture**: Modular design for easy extension
- **Caching & Background Processing**: Redis-based caching and async task processing

## Installation

### Prerequisites

- Python 3.11+ - [Install here](https://www.python.org/downloads/)
- Pip (if using Pip) - [Install here](https://pip.pypa.io/en/stable/installation/)
- Poetry 2.1.3+ (if using Poetry) - [Install here](https://python-poetry.org/docs/#installation)
- Access to the [GDP Labs SDK repository](https://github.com/GDP-ADMIN/bosa-sdk)

### Install from PyPI

```bash
# Using pip
pip install bosa-server-plugins-binary

# Using Poetry
poetry add bosa-server-plugins-binary
```

### Development Installation

```bash
poetry add "git+ssh://git@github.com/GDP-ADMIN/bosa-sdk.git#subdirectory=python/bosa-server-plugins"
```

## Configuration

Set the following environment variables:

```bash
# GitHub
GITHUB_CLIENT_ID=your-github-client-id
GITHUB_CLIENT_SECRET=your-github-client-secret
GITHUB_API_KEY=your-github-api-key

# Google Services
GOOGLE_CLIENT_ID=your-google-client-id
GOOGLE_CLIENT_SECRET=your-google-client-secret

# Twitter
TWITTER_BEARER_TOKEN=your-twitter-bearer-token
TWITTER_API_KEY=your-twitter-api-key
TWITTER_API_SECRET=your-twitter-api-secret

# BOSA Core
BOSA_API_URL=https://your-bosa-api-url
REDIS_URL=redis://localhost:6379
DATABASE_URL=postgresql://username:password@localhost:5432/dbname
```

## Available Plugins

### GitHub Plugin

**Metrics**: `get_all_contributor_commit_activity`, `get_the_last_year_of_commit_activity`, `get_weekly_commit_count`, `get_user_contribution_statistics`

**Repositories**: `list_commits`, `search_commits`, `list_collaborators`, `list_releases`, `list_contributors`, `list_languages`, `search_contributions`

**Pull Requests**: `list_pull_requests`, `search_pull_requests`, `get_pull`

**Issues**: `create_issue`, `get_issue`, `list_issues`, `list_issues_comments`, `search_issues`

**Projects**: `list_project_items`, `list_projects`

### Google Drive Plugin

**Files**: `search_files`, `get_file`, `create_file`, `create_folder`, `update_file`, `update_folder`, `copy_file`, `delete_file`, `summarize_folder_files_by_type`, `summarize_total_files_by_type`, `list_recent_files_from_yesterday`

**Permissions**: `create_permission`, `list_permissions`, `get_permission`, `update_permission`, `delete_permission`

**Download**: `download_file`

### Google Mail Plugin

**Emails**: `send_email`, `list_emails`, `get_email_details`, `modify_email`, `delete_email`, `trash_email`, `untrash_email`

**Drafts**: `create_draft`, `list_drafts`, `send_draft`, `get_draft`, `modify_draft`

**Threads**: `list_threads`, `thread_details`, `modify_thread`

**Labels**: `list_labels`, `total_email_perlabel`, `get_label_details`, `create_labels`, `modify_labels`, `delete_labels`

**Attachments**: `get_attachment`

**Auto Reply**: `get_auto_reply`, `set_auto_reply`

### Google Docs Plugin

**Documents**: `get_document`, `list_documents`, `create_document`, `update_document`, `copy_content`, `update_document_markdown`

**Comments**: `list_comments`, `summarize_comments`

### Twitter Plugin

**Tweets**: `tweet_search`, `get_tweets`, `get_thread`

**Users**: `get-users`

### Google Plugin (General)

**User**: `userinfo`

## API Usage

All endpoints use POST requests with JSON payloads and require authentication:

```bash
curl -X POST http://localhost:8000/endpoint_name \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: your-api-key" \
  -H "Authorization: Bearer your-token" \
  -d '{"param1": "value1", "param2": "value2"}'
```

### Example: GitHub - List Commits

```bash
curl -X POST http://localhost:8000/list_commits \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: your-api-key" \
  -H "Authorization: Bearer your-token" \
  -d '{
    "owner": "GDP-ADMIN",
    "repo": "bosa-sdk",
    "per_page": 10
  }'
```

### Example: Google Drive - Search Files

```bash
curl -X POST http://localhost:8000/search_files \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: your-api-key" \
  -H "Authorization: Bearer your-token" \
  -d '{
    "query": "name contains \"project\"",
    "page_size": 10
  }'
```

## OAuth Integration

The plugins support OAuth authentication:

1. Call `initialize_authorization` method
2. Redirect users to authorization URL
3. Handle OAuth callback to store tokens
4. Use stored tokens for API calls

## Development

### Adding New Plugins

1. Create plugin directory under `bosa_server_plugins/`
2. Implement plugin class extending `ThirdPartyIntegrationPlugin`
3. Define routes and authentication schemes
4. Add API endpoint implementations

### Testing & Code Quality

```bash
# Run tests
pytest tests/

# Format and check code
black bosa_server_plugins/
ruff check bosa_server_plugins/
mypy bosa_server_plugins/
```

## Support

- **Email**: bosa-eng@gdplabs.id
- **Issues**: Create issues in the GDP Labs SDK repository

## References

### Product Requirements Documents (PRD)

- [BOSA Connector - Product Document](https://docs.google.com/document/d/1R6JIGWnKzNg2kRMRSiZ-wwPGe9pOR9rkkEI0Uz-Wtdw/edit?tab=t.y617gs6jfk15#heading=h.uss0d453lcbs)

### Architecture Documents

- [BOSA Connector - Architecture Document](https://docs.google.com/document/d/1HHUBAkbFAM8sM_Dtx6tmoatR1HeuM6VBfsWEjpgVCtg/edit?tab=t.0#heading=h.bj79ljx9eqg8)

### Design Documents

- [BOSA Connector - Design Document](https://docs.google.com/document/d/1PghW7uOJcEbT3WNSlZ0FI99o4y24ys0LCyAG8hg3T9o/edit?tab=t.0#heading=h.bj79ljx9eqg8)

### Implementation Documents

- [BOSA Connector - Implementation Document](https://docs.google.com/document/d/1a8BvggPu5a6PBStgUu2ILse075FjAAgoehUuvxxAajM/edit?tab=t.0#heading=h.bj79ljx9eqg8)

## License

This project is licensed under the terms specified by GDP Labs.