trackvault-shared 1.5.5
Shared utilities, services, and RBAC system for TrackVault microservices
Requires Python: >=3.9
Keywords: trackvault, microservices, utilities, event-bus

# TrackVault Shared Library

Shared utilities and services for TrackVault microservices.

## ⚠️ **SIMPLE STEP-BY-STEP GUIDE: Editing Shared Library**

**After you edit code in the shared library, follow these steps EXACTLY:**

### **Step 1: Edit Your Code**
```bash
# Make changes in trackvault_shared/ directory
# Test locally (optional but recommended)
cd trackvault-shared-lib
pip install -e .
```

### **Step 2: Update Version in `pyproject.toml`** ⚠️ **CRITICAL!**
**⚠️ YOU MUST UPDATE VERSION EVEN IF YOU ONLY CHANGED README!**

Open `pyproject.toml` and change the version:
```toml
[project]
version = "1.5.2"  # Change this number! (e.g., 1.5.1 → 1.5.2)
```

**Why?** PyPI rejects duplicate versions. If version `1.5.1` already exists, you cannot publish it again, even if only README changed.

**Version Rules:**
- `1.5.1` → `1.5.2` (bug fix, README update, docs only)
- `1.5.1` → `1.6.0` (new feature, backward compatible)
- `1.5.1` → `2.0.0` (breaking change)

### **Step 3: Commit and Push**
```bash
git add .
git commit -m "Your commit message"
git push origin main
```

### **Step 4: Publish to PyPI (Choose ONE method):**

#### **Option A: Manually Trigger Workflow (EASIER!)** ⭐ Recommended
1. Go to: https://github.com/muhsinbinirshad/trackvault-shared-lib/actions/workflows/publish.yml
2. Click **"Run workflow"** button (top right)
3. Select branch: `main`
4. Click **"Run workflow"** ✅

**What happens:**
- ✅ Reads version from `pyproject.toml` automatically (e.g., `1.5.1`)
- ✅ Builds package with that version
- ✅ Publishes to PyPI automatically
- ✅ Creates tag `v1.5.1` automatically (if it doesn't exist)
- ✅ Takes 1-2 minutes

**No need to create a release!** Just click "Run workflow" and it publishes to PyPI.

#### **Option B: Create GitHub Release** (If you want a visible release)
1. Go to: https://github.com/muhsinbinirshad/trackvault-shared-lib/releases/new
2. Click **"Choose a tag"** → Type: `v1.5.1` (must match `pyproject.toml` version with `v` prefix!)
3. **Release title**: `TrackVault Shared Library v1.5.1`
4. **Description**: What you changed
5. Click **"Publish release"** ✅

**What happens:**
- ✅ Same as Option A (publishes to PyPI)
- ✅ PLUS creates a visible release on GitHub

### **Step 5: Wait 1-2 Minutes**
The workflow automatically:
- ✅ Builds package from `pyproject.toml`
- ✅ Reads version from `pyproject.toml` (e.g., `1.5.1`)
- ✅ Publishes to PyPI with that version

**You don't need to do anything else!**

### **Step 6: Verify (Optional)**
- Check workflow: https://github.com/muhsinbinirshad/trackvault-shared-lib/actions
- Check PyPI: https://pypi.org/project/trackvault-shared/
- New version should appear automatically (1-2 minutes after workflow completes)

### **What About Microservices?**
**✅ Nothing to update!** Microservices use `trackvault-shared>=1.5.0`, so they automatically get the new version (`1.5.1`) when you:
- Reinstall: `pip install -r requirements.txt`
- Or rebuild Docker images

### **Critical Rules:**

- ✅ **ALWAYS update `pyproject.toml` version FIRST** (before running workflow)
- ✅ **Even if you only changed README, you MUST bump version** (PyPI rejects duplicates)
- ✅ **Workflow reads version from `pyproject.toml` automatically** (no need to specify tag manually)
- ✅ **Workflow checks if version exists on PyPI and fails early** (prevents upload errors)
- ✅ **Test locally first**: `pip install -e .` in `trackvault-shared-lib/`
- ❌ **Never push to PyPI manually** (use GitHub Actions workflow only)
- ❌ **Never skip version bump** (workflow will fail with clear error message)

### **What If You Forget to Update Version?**

**Don't worry!** The workflow checks if the version already exists on PyPI and **fails early** with a clear error message:

```
⚠️ WARNING: Version 1.5.1 already exists on PyPI!
You must update version in pyproject.toml before publishing.
Current version in pyproject.toml: 1.5.1
```

**To fix:**
1. Update version in `pyproject.toml` (e.g., `1.5.1` → `1.5.2`)
2. Commit and push: `git add pyproject.toml && git commit -m 'Bump version' && git push`
3. Run workflow again ✅

**If using Option B (GitHub 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`)

### **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.