fourbyfour 0.1.4

Official Fourbyfour SDK for Python

fourbyfour

Official Python SDK for Fourbyfour - Revenue workflows on autopilot.

Installation

pip install fourbyfour

Setup

1. Get your credentials

Get your API key and Project ID from fourbyfour.dev.

2. Configure environment variables

# .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):

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):

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):

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

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:

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

# 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

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:

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

Type Hints

Full type hint support with all events:

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

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 for full documentation.

License

MIT