Metadata-Version: 2.4
Name: fourbyfour
Version: 0.1.2
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://docs.fourbyfour.dev
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
```

## Quick Start

```python
from fourbyfour import saas

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

# Track events → triggers workflows
fbf.track("payment.failed", {
    "user_id": "u_123",
    "amount": 99.0,
    "currency": "USD",
    "plan": "Pro",
    "subscription_id": "sub_456",
    "billing_cycle": "monthly"
})

# Send context → helps optimize
fbf.notify({
    "user_id": "u_123",
    "timezone": "Asia/Kolkata",
    "tier": "premium"
})
```

## Verticals

Choose the client that matches your business:

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

# SaaS
saas_client = saas(api_key="sk_...", project_id="proj_...")

# E-commerce
ecom_client = ecommerce(api_key="sk_...", project_id="proj_...")

# Fintech
fin_client = fintech(api_key="sk_...", project_id="proj_...")

# EdTech
edu_client = edtech(api_key="sk_...", project_id="proj_...")

# Games
game_client = games(api_key="sk_...", project_id="proj_...")

# Apps
app_client = apps(api_key="sk_...", project_id="proj_...")
```

## SaaS Events

```python
fbf = saas(api_key="sk_...", project_id="proj_...")

# 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})

# Subscription events
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"})
fbf.track("subscription.downgraded", {"user_id": "u_123", "from_plan": "Pro", "to_plan": "Starter"})

# Usage & engagement
fbf.track("usage.threshold", {"user_id": "u_123", "metric": "api_calls", "current": 9500, "limit": 10000})
fbf.track("feature.adopted", {"user_id": "u_123", "feature": "analytics"})
fbf.track("nps.submitted", {"user_id": "u_123", "score": 9, "feedback": "Great product!"})

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

## E-commerce Events

```python
fbf = ecommerce(api_key="sk_...", project_id="proj_...")

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"})
```

## Type Hints

Full type hint support with all events:

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

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

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="sk_...", project_id="proj_...")

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 [docs.fourbyfour.dev](https://docs.fourbyfour.dev) for full documentation.

## License

MIT
