Metadata-Version: 2.4
Name: softreck-shared
Version: 0.1.1
Summary: Shared components for Softreck ecosystem
Author-email: Tom Sapletta <tom@sapletta.com>
License-Expression: Apache-2.0
Keywords: integrations,ticketing,project-management
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: pydantic>=2.0
Requires-Dist: httpx>=0.27
Requires-Dist: pydantic-settings>=2.0
Provides-Extra: jira
Requires-Dist: jira>=3.0; extra == "jira"
Provides-Extra: github
Requires-Dist: PyGithub>=2.0; extra == "github"
Provides-Extra: gitlab
Requires-Dist: python-gitlab>=4.0; extra == "gitlab"
Provides-Extra: all
Requires-Dist: jira>=3.0; extra == "all"
Requires-Dist: PyGithub>=2.0; extra == "all"
Requires-Dist: python-gitlab>=4.0; extra == "all"

# Softreck Shared Integrations

Common integration components for the Softreck ecosystem.

## Overview

This package provides shared interfaces and implementations for:
- Ticket management systems (Jira, GitHub, GitLab)
- Project management backends
- Issue tracking platforms

## Installation

```bash
pip install softreck-shared
```

## Usage

### Base Interfaces

```python
from softreck_shared.integrations import PMBackend, TicketRef, TicketStatus

# Implement a custom backend
class MyBackend(PMBackend):
    def create_ticket(self, title: str, body: str, **kwargs) -> TicketRef:
        # Implementation
        pass
    
    def update_ticket(self, ticket_id: str, **kwargs) -> None:
        # Implementation
        pass
```

### Generic Backend

```python
from softreck_shared.integrations import GenericBackend

# Use with any REST API
backend = GenericBackend(
    base_url="https://api.example.com",
    api_key="your-api-key"
)

# Create a ticket
ticket = backend.create_ticket(
    title="Bug fix",
    body="Fix the login issue",
    labels=["bug", "urgent"],
    priority="high"
)
```

### Platform-Specific Backends

Install with optional dependencies:

```bash
# For Jira
pip install softreck-shared[jira]

# For GitHub
pip install softreck-shared[github]

# For GitLab
pip install softreck-shared[gitlab]

# Or all at once
pip install softreck-shared[all]
```

```python
from softreck_shared.integrations import JiraBackend, GitHubBackend, GitLabBackend

# Jira
jira = JiraBackend(
    server="https://company.atlassian.net",
    username="user@example.com",
    api_key="your-api-key"
)

# GitHub
github = GitHubBackend(
    token="github-token",
    repo="owner/repo"
)

# GitLab
gitlab = GitLabBackend(
    url="https://gitlab.com",
    token="gitlab-token"
)
```

## Architecture

The shared integrations follow a protocol-based design:

- `PMBackend` - Protocol defining the interface
- `TicketRef` - Reference to a created/updated ticket
- `TicketStatus` - Status information for a ticket
- `GenericBackend` - HTTP-based implementation for REST APIs

## Contributing

When adding new platform integrations:

1. Implement the `PMBackend` protocol
2. Add platform-specific optional dependencies
3. Include comprehensive error handling
4. Add type hints for all public methods
5. Write tests for the implementation

## License

Apache License 2.0
