Metadata-Version: 2.4
Name: fourbyfour
Version: 0.1.3
Summary: Official Fourbyfour SDK for Python
Project-URL: Homepage, https://github.com/occupymars/fourbyfour/tree/main/sdks/python#readme
Project-URL: Repository, https://github.com/occupymars/fourbyfour.git
Project-URL: Documentation, https://fourbyfour.dev/docs
Project-URL: Issues, https://github.com/occupymars/fourbyfour/issues
Author: Fourbyfour
License-Expression: MIT
Keywords: fourbyfour,hooks,notifications,sdk,stream
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
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
Classifier: Typing :: Typed
Requires-Python: >=3.9
Requires-Dist: httpx>=0.25.0
Provides-Extra: dev
Requires-Dist: mypy>=1.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff>=0.1; extra == 'dev'
Description-Content-Type: text/markdown

# fourbyfour

Official Python SDK for Fourbyfour - Revenue workflows on autopilot.

## Installation

```bash
pip install fourbyfour
```

## Setup

### 1. Get your credentials

Get your API key and Project ID from [fourbyfour.dev/dashboard](https://fourbyfour.dev/dashboard).

### 2. Configure environment variables

```bash
# .env
FOURBYFOUR_API_KEY=sk_live_...
FOURBYFOUR_PROJECT_ID=proj_...
```

### 3. Initialize the SDK

Add the SDK initialization in your app:

**FastAPI** (`app/lib/fourbyfour.py`):
```python
import os
from fourbyfour import saas

fbf = saas(
    api_key=os.environ["FOURBYFOUR_API_KEY"],
    project_id=os.environ["FOURBYFOUR_PROJECT_ID"]
)
```

**Django** (`myapp/fourbyfour.py`):
```python
import os
from fourbyfour import saas

fbf = saas(
    api_key=os.environ["FOURBYFOUR_API_KEY"],
    project_id=os.environ["FOURBYFOUR_PROJECT_ID"]
)
```

**Flask** (`app/fourbyfour.py`):
```python
import os
from fourbyfour import saas

fbf = saas(
    api_key=os.environ["FOURBYFOUR_API_KEY"],
    project_id=os.environ["FOURBYFOUR_PROJECT_ID"]
)
```

### 4. Track your first event

```python
from app.lib.fourbyfour import fbf

# In your payment handler, API route, or service
fbf.track("payment.failed", {
    "user_id": user.id,
    "amount": invoice.amount,
    "currency": "USD",
    "plan": subscription.plan,
    "subscription_id": subscription.id,
    "billing_cycle": "monthly"
})
```

## Verticals

Choose the client that matches your business:

```python
from fourbyfour import saas, ecommerce, fintech, edtech, games, apps

# SaaS - trials, subscriptions, usage
fbf = saas(api_key="...", project_id="...")

# E-commerce - carts, orders, shipping
fbf = ecommerce(api_key="...", project_id="...")

# Fintech - transactions, payments, KYC
fbf = fintech(api_key="...", project_id="...")

# EdTech - courses, lessons, certificates
fbf = edtech(api_key="...", project_id="...")

# Games - levels, achievements, streaks
fbf = games(api_key="...", project_id="...")

# Apps - trials, subscriptions, milestones
fbf = apps(api_key="...", project_id="...")
```

## Common Events

### SaaS

```python
# Trial lifecycle
fbf.track("trial.started", {"user_id": "u_123", "plan": "Pro", "trial_days": 14})
fbf.track("trial.ending", {"user_id": "u_123", "plan": "Pro", "days_remaining": 3})

# Subscriptions
fbf.track("subscription.canceled", {"user_id": "u_123", "plan": "Pro", "reason": "too_expensive"})
fbf.track("subscription.upgraded", {"user_id": "u_123", "from_plan": "Starter", "to_plan": "Pro"})

# Usage
fbf.track("usage.threshold", {"user_id": "u_123", "metric": "api_calls", "current": 9500, "limit": 10000})

# Payment
fbf.track("payment.failed", {"user_id": "u_123", "amount": 99.0, "currency": "USD", "plan": "Pro"})
```

### E-commerce

```python
fbf.track("cart.abandoned", {
    "user_id": "u_123",
    "cart_id": "cart_456",
    "items": [{"product_id": "prod_1", "name": "Shirt", "quantity": 2, "price": 29.99}],
    "total_value": 59.98
})

fbf.track("order.placed", {"user_id": "u_123", "order_id": "ord_789", "total_value": 150.0})
fbf.track("order.shipped", {"user_id": "u_123", "order_id": "ord_789", "tracking_number": "TRK123"})
```

## User Context

Send user context to help optimize delivery timing and channels:

```python
fbf.notify({
    "user_id": "u_123",
    "timezone": "Asia/Kolkata",
    "tier": "premium",
    "preferred_channel": "email"
})
```

## Type Hints

Full type hint support with all events:

```python
from fourbyfour import saas, SaaSClient, TrackResult

fbf: SaaSClient = saas(api_key="...", project_id="...")

result: TrackResult = fbf.track("trial.started", {
    "user_id": "u_123",
    "plan": "Pro",
    "trial_days": 14
})
```

## Error Handling

```python
from fourbyfour import saas, FourbyfourError, AuthenticationError, RateLimitError

fbf = saas(api_key="...", project_id="...")

try:
    fbf.track("payment.failed", {"user_id": "u_123", "amount": 99.0})
except AuthenticationError:
    print("Invalid API key")
except RateLimitError:
    print("Rate limit exceeded, retry later")
except FourbyfourError as e:
    print(f"API error: {e}")
```

## Documentation

See [fourbyfour.dev/docs](https://fourbyfour.dev/docs) for full documentation.

## License

MIT
