Metadata-Version: 2.4
Name: trackvault-shared
Version: 1.5.1
Summary: Shared utilities, services, and RBAC system for TrackVault microservices
Author-email: TrackVault Team <team@trackvault.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/trackvault/shared-lib
Project-URL: Documentation, https://github.com/trackvault/shared-lib#readme
Project-URL: Repository, https://github.com/trackvault/shared-lib
Keywords: trackvault,microservices,utilities,event-bus
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: redis>=5.0.0
Requires-Dist: pydantic>=2.0.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: isort>=5.12.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Dynamic: license-file

# TrackVault Shared Library

Shared utilities and services for TrackVault microservices.

## ⚠️ **IMPORTANT: Maintaining GitHub-PyPI Integrity**

When adding new features, fixing bugs, or making any changes to the shared library, **you MUST follow this workflow** to keep GitHub and PyPI in sync:

### **Workflow for Changes:**

1. **Make Your Changes**
   - Edit code in the `trackvault_shared/` directory
   - Update tests if needed
   - Test locally: `pip install -e .`

2. **Update Version in `pyproject.toml`**
   - Increment version number following [Semantic Versioning](https://semver.org/):
     - **PATCH** (`1.5.0` → `1.5.1`): Bug fixes, minor updates
     - **MINOR** (`1.5.0` → `1.6.0`): New features, backward compatible
     - **MAJOR** (`1.5.0` → `2.0.0`): Breaking changes
   ```toml
   [project]
   version = "1.5.1"  # Update this!
   ```

3. **Commit and Push to GitHub**
   ```bash
   git add .
   git commit -m "Add new feature: [description]"
   git push origin main
   ```

4. **Create GitHub Release (Triggers PyPI Publish)**
   - Go to: https://github.com/muhsinbinirshad/trackvault-shared-lib/releases/new
   - **Tag version**: `v1.5.1` (must match `pyproject.toml` version, must start with `v`)
   - **Release title**: `TrackVault Shared Library v1.5.1`
   - **Description**: Brief changelog of what changed
   - Click **"Publish release"**

5. **GitHub Actions Automatically:**
   - Builds the package from `pyproject.toml`
   - Publishes to PyPI with version from `pyproject.toml`
   - Creates a tagged release on GitHub

6. **Verify Publication**
   - Check PyPI: https://pypi.org/project/trackvault-shared/
   - Verify version appears: `pip search trackvault-shared` (or check PyPI web)
   - Test installation: `pip install trackvault-shared==1.5.1`

### **Critical Rules:**

- ✅ **ALWAYS update `pyproject.toml` version** before creating a release
- ✅ **Tag version MUST match `pyproject.toml` version** (with `v` prefix)
- ✅ **Tag format**: `v1.5.1` (not `1.5.1` or `v1.5.0` if version is `1.5.1`)
- ✅ **Test locally first**: `pip install -e .` in `trackvault-shared-lib/`
- ✅ **Don't publish without version bump** (PyPI rejects duplicate versions)
- ❌ **Never push to PyPI manually** (use GitHub Actions workflow only)
- ❌ **Never skip version bump** (causes version conflicts)

### **After Publishing:**

- **Update Microservices** (if needed):
  - Update `requirements.txt` in microservices: `trackvault-shared>=1.5.1`
  - Or let them auto-update: `trackvault-shared>=1.5.0` (will get `1.5.1`)

### **Quick Checklist:**

```
[ ] Made code changes
[ ] Updated version in pyproject.toml
[ ] Tested locally: pip install -e .
[ ] Committed and pushed to GitHub
[ ] Created GitHub release with matching tag (v1.x.x)
[ ] Verified GitHub Actions workflow succeeded
[ ] Verified package on PyPI
[ ] Updated microservices if needed
```

---

## 🚀 Quick Installation

### Option 1: Install from PyPI (Recommended for Production)

```bash
# Install from PyPI
pip install trackvault-shared>=1.5.0
```

**Benefits:**
- ✅ Standard Python package installation
- ✅ Versioned releases
- ✅ Works in any environment
- ✅ CI/CD friendly
- ✅ No authentication required (public package)

### Option 2: Install Locally (Development Only)

For local development, install in editable mode:

```bash
# From backend/ directory
cd backend
pip install -e ../trackvault-shared-lib
```

**Benefits:**
- ✅ Changes are immediately available (no reinstall needed)
- ✅ Perfect for active development

**Note:** For production/CI/CD, use PyPI (Option 1).

## Features

- **Event Bus**: Redis Streams-based event publishing and subscription
- **Plans Registry**: Multi-tenancy plan definitions and validation
- **Health Checks**: Comprehensive health monitoring utilities
- **Circuit Breaker**: Prevent cascade failures
- **Retry Pattern**: Exponential backoff for resilient operations
- **Event Schemas**: Standardized event types for microservice communication
- **Soft Delete**: Soft delete mixins for Beanie models

## Quick Start

```python
from trackvault_shared import get_project_event_bus, PLANS

# Event Bus
bus = get_project_event_bus("redis://localhost:6379/0")
await bus.publish("project.created", {"project_id": "123"})

# Plans Registry
plan = get_plan_by_name("team")
print(plan["workspace_limits"])
```

## 📚 Publishing

To publish a new version:

1. Update version in `pyproject.toml`
2. Create a GitHub release (tag: `v1.5.0`)
3. GitHub Actions automatically publishes to PyPI

**PyPI API Token Setup:**
1. Go to https://pypi.org/manage/account/token/
2. Create API token with "Upload packages" scope
3. Add as secret `PYPI_API_TOKEN` in GitHub repository settings

## License

MIT License - see LICENSE file for details.

