tps-cli 0.1.0
CLI tool for testing Third-Party App integrations via TPS service
License: MIT
Requires Python: >=3.10
Keywords: azure-ad, cli, integration, oauth, slack, testing, third-party, tps, workday

# TPS CLI - Third-Party App Integration Service Testing Tool

A comprehensive CLI tool for testing and managing integrations in the TPS (Third-Party App Integration Service). This tool provides a Python-based interface to interact with TPS APIs, manage OAuth flows, and query integration data directly from the database.

## Features

- **OAuth Flow Testing**: Complete OAuth2 authorization flow testing for integrations
- **Token Management**: Generate, refresh, and validate access tokens
- **Database Integration**: Direct access to TPS database for integration and credential queries
- **Multi-Integration Support**: Scalable architecture supporting multiple integrations (Workday, Azure AD, etc.)
- **Rich CLI Output**: Beautiful terminal output with tables, panels, and colored text
- **Multiple Auth Types**: Support for OAuth2, API Key, Basic Auth, and Form-Based OAuth2

## Quick Start

### Installation

**Using uvx (recommended - no installation needed):**
```bash
uvx tps-cli init
uvx tps-cli health
```

**Using pipx (persistent installation):**
```bash
pipx install tps-cli
tps init
tps health
```

**Using pip:**
```bash
pip install tps-cli
tps init
```

### Setup

Initialize the CLI configuration:

```bash
tps init
```

This will interactively prompt you for:
- TPS Service URL (default: http://localhost:8093)
- Database connection details
- Encryption key (optional)

Configuration is saved to `~/.tps-cli/config.yaml`

### Basic Usage

```bash
# Show version
tps version

# Check TPS service health
tps health

# List integrations
tps integration list

# Get integration details with credentials
tps integration get 123 --with-credential

# Install a new integration (end-to-end OAuth flow)
tps integration install 32 --config '{...}'
```

## Documentation

- **GETTING_STARTED.md**: Step-by-step setup and workflows
- **PROJECT_SUMMARY.md**: Architecture overview and implementation details
- **.env.example**: Example configuration

## Architecture

Built with scalable, modular architecture that mirrors TPS Java backend:

```
tps-cli/
├── auth/                # Authentication handlers (OAuth2, API Key, etc.)
├── client/              # HTTP clients (TPS API, base client)
├── database/            # Database repository (integration queries)
├── commands/            # CLI commands (integration testing)
├── models/              # Data models (Pydantic)
├── utils/               # Utilities (Rich output formatting)
└── config.py            # Configuration management
```

## Key Commands

### Integration Management

```bash
# List integrations
tps integration list --tenant-id 1 --status ACTIVE

# Get integration with credentials
tps integration get 123 --with-credential

# Check token expiration
tps integration check-token 123
```

### OAuth Flow Testing

```bash
# 1. Generate authorization URL
tps integration generate-auth-url workday \
    --client-id "..." --client-secret "..." \
    --redirect-url "http://localhost:8093/callback" \
    --tenant-name "my_tenant" \
    --auth-url "https://wd2-impl-services1.workday.com" \
    --api-url "https://wd2-impl-services1.workday.com"

# 2. Exchange code for tokens
tps integration exchange-token workday --code "..." [OPTIONS]

# 3. Refresh tokens
tps integration refresh-token workday --refresh-token "..." [OPTIONS]
```

## Configuration

Edit `~/.tps-cli/config.yaml`:

```yaml
active_profile: local

profiles:
  local:
    tps_service:
      url: http://localhost:8093
    database:
      host: localhost
      port: 5432
      database: tps
      username: postgres
      password: your_password
```

Or use environment variables (`.env` file).

## Statistics

- **~1,940 lines of Python code**
- **20 Python modules**
- **100% compatible with TPS Java backend**
- **Scalable for 25+ integrations**

## Adding New Integrations

```python
# 1. Create handler in auth/handlers/new_app.py
from ..oauth2 import OAuth2Handler

class NewAppOAuthHandler(OAuth2Handler):
    def __init__(self, ...):
        super().__init__(
            authorization_url="...",
            token_url="...",
            scopes=[...],
            verbose=verbose
        )
    
    def is_cache_enabled(self) -> bool:
        return True  # or False if rotation is used

# 2. Add commands in commands/integration.py
# 3. Done!
```

## Dependencies

- **typer**: Modern CLI framework
- **httpx**: Async HTTP client
- **pydantic**: Data validation
- **rich**: Terminal formatting
- **sqlalchemy**: Database ORM
- **psycopg2-binary**: PostgreSQL driver
- **pyjwt**: JWT token parsing
- **pyyaml**: YAML configuration

## Support

For detailed usage, see:
- **GETTING_STARTED.md** for workflows and examples
- **PROJECT_SUMMARY.md** for architecture details

Built for AtomicWork TPS Team