msaas-billing 0.1.0__tar.gz

msaas_billing-0.1.0/.gitignore

@@ -0,0 +1,21 @@
+node_modules/
+dist/
+.next/
+.turbo/
+*.pyc
+__pycache__/
+.venv/
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+.env
+.env.local
+.env.*.local
+.DS_Store
+coverage/
+
+# Runtime artifacts
+logs_llm/
+vectors.db
+vectors.db-shm
+vectors.db-wal

msaas_billing-0.1.0/PKG-INFO

@@ -0,0 +1,14 @@
+Metadata-Version: 2.4
+Name: msaas-billing
+Version: 0.1.0
+Summary: Stripe billing module for SaaS products
+Requires-Python: >=3.12
+Requires-Dist: fastapi>=0.115.0
+Requires-Dist: msaas-api-core
+Requires-Dist: msaas-errors
+Requires-Dist: pydantic>=2.0
+Requires-Dist: stripe>=9.0.0
+Provides-Extra: dev
+Requires-Dist: httpx>=0.27; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'

msaas_billing-0.1.0/pyproject.toml

@@ -0,0 +1,30 @@
+[project]
+name = "msaas-billing"
+version = "0.1.0"
+description = "Stripe billing module for SaaS products"
+requires-python = ">=3.12"
+dependencies = [
+    "msaas-api-core",
+    "msaas-errors",
+    "stripe>=9.0.0",
+    "fastapi>=0.115.0",
+    "pydantic>=2.0",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/billing"]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.24",
+    "httpx>=0.27",
+]
+
+[tool.uv.sources]
+msaas-api-core = { workspace = true }
+msaas-errors = { workspace = true }

msaas_billing-0.1.0/src/billing/__init__.py

@@ -0,0 +1,56 @@
+"""willian-billing: Stripe billing module for SaaS products.
+
+Usage:
+    from billing import init_billing, BillingConfig, BillingRouter
+
+    config = BillingConfig(
+        stripe_secret_key="sk_...",
+        stripe_webhook_secret="whsec_...",
+        success_url="https://app.example.com/billing/success",
+        cancel_url="https://app.example.com/billing/cancel",
+        product_plans={"starter": "price_xxx", "pro": "price_yyy"},
+    )
+    init_billing(config)
+
+    # Mount the router in your FastAPI app
+    app.include_router(BillingRouter)
+"""
+
+from billing.checkout import create_checkout, create_portal_session
+from billing.config import BillingConfig, init_billing
+from billing.invoices import get_invoices
+from billing.models import (
+    CheckoutSession,
+    Invoice,
+    Subscription,
+    UsageRecord,
+    WebhookEvent,
+)
+from billing.router import BillingRouter
+from billing.subscriptions import (
+    cancel_subscription,
+    get_subscription,
+    update_subscription,
+)
+from billing.usage import get_usage, record_usage
+from billing.webhooks import handle_webhook
+
+__all__ = [
+    "BillingConfig",
+    "BillingRouter",
+    "CheckoutSession",
+    "Invoice",
+    "Subscription",
+    "UsageRecord",
+    "WebhookEvent",
+    "cancel_subscription",
+    "create_checkout",
+    "create_portal_session",
+    "get_invoices",
+    "get_subscription",
+    "get_usage",
+    "handle_webhook",
+    "init_billing",
+    "record_usage",
+    "update_subscription",
+]

msaas_billing-0.1.0/src/billing/checkout.py

@@ -0,0 +1,73 @@
+"""Stripe Checkout and Customer Portal session management."""
+
+from __future__ import annotations
+
+import stripe
+
+from billing.config import get_config
+from billing.models import CheckoutSession
+
+
+def create_checkout(
+    user_id: str,
+    plan: str,
+    email: str | None = None,
+) -> CheckoutSession:
+    """Create a Stripe Checkout session for the given plan.
+
+    Args:
+        user_id: Internal user identifier, stored as client_reference_id.
+        plan: Plan name as defined in BillingConfig.product_plans.
+        email: Optional customer email to pre-fill in checkout.
+
+    Returns:
+        CheckoutSession with the redirect URL and session ID.
+
+    Raises:
+        ValueError: If the plan name is not found in configured plans.
+        stripe.StripeError: On Stripe API failures.
+    """
+    config = get_config()
+
+    price_id = config.product_plans.get(plan)
+    if not price_id:
+        available = ", ".join(config.product_plans.keys())
+        raise ValueError(f"Unknown plan '{plan}'. Available plans: {available}")
+
+    params: dict = {
+        "mode": "subscription",
+        "line_items": [{"price": price_id, "quantity": 1}],
+        "success_url": config.success_url,
+        "cancel_url": config.cancel_url,
+        "client_reference_id": user_id,
+        "metadata": {"user_id": user_id, "plan": plan},
+    }
+
+    if email:
+        params["customer_email"] = email
+
+    session = stripe.checkout.Session.create(**params)
+
+    return CheckoutSession(
+        url=session.url,
+        session_id=session.id,
+    )
+
+
+def create_portal_session(customer_id: str) -> str:
+    """Create a Stripe Customer Portal session.
+
+    Args:
+        customer_id: Stripe customer ID.
+
+    Returns:
+        The portal session URL for redirect.
+
+    Raises:
+        stripe.StripeError: On Stripe API failures.
+    """
+    session = stripe.billing_portal.Session.create(
+        customer=customer_id,
+        return_url=get_config().success_url,
+    )
+    return session.url

msaas_billing-0.1.0/src/billing/config.py

@@ -0,0 +1,48 @@
+"""Billing configuration and Stripe client initialization."""
+
+from __future__ import annotations
+
+import stripe
+from pydantic import BaseModel, Field
+
+
+class BillingConfig(BaseModel):
+    """Configuration for the billing module."""
+
+    stripe_secret_key: str = Field(description="Stripe secret API key")
+    stripe_webhook_secret: str = Field(description="Stripe webhook signing secret")
+    success_url: str = Field(description="Redirect URL after successful checkout")
+    cancel_url: str = Field(description="Redirect URL after cancelled checkout")
+    product_plans: dict[str, str] = Field(
+        default_factory=dict,
+        description="Mapping of plan_name -> stripe_price_id",
+    )
+
+
+_config: BillingConfig | None = None
+
+
+def init_billing(config: BillingConfig) -> None:
+    """Initialize the billing module with the given configuration.
+
+    Sets the Stripe API key and stores config for later use by all billing functions.
+
+    Args:
+        config: Billing configuration with Stripe credentials and plan mappings.
+    """
+    global _config
+    _config = config
+    stripe.api_key = config.stripe_secret_key
+
+
+def get_config() -> BillingConfig:
+    """Return the current billing configuration.
+
+    Raises:
+        RuntimeError: If init_billing has not been called.
+    """
+    if _config is None:
+        raise RuntimeError(
+            "Billing not initialized. Call init_billing(config) before using billing functions."
+        )
+    return _config

msaas_billing-0.1.0/src/billing/invoices.py

@@ -0,0 +1,47 @@
+"""Invoice retrieval operations."""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime
+
+import stripe
+
+from billing.models import Invoice
+from billing.subscriptions import _get_customer_id
+
+
+def get_invoices(user_id: str, limit: int = 10) -> list[Invoice]:
+    """Fetch recent invoices for a user.
+
+    Args:
+        user_id: Internal user identifier.
+        limit: Maximum number of invoices to return. Defaults to 10.
+
+    Returns:
+        List of Invoice objects, most recent first.
+
+    Raises:
+        ValueError: If no Stripe customer is found for the user.
+        stripe.StripeError: On Stripe API failures.
+    """
+    customer_id = _get_customer_id(user_id)
+
+    stripe_invoices = stripe.Invoice.list(
+        customer=customer_id,
+        limit=limit,
+    )
+
+    invoices: list[Invoice] = []
+    for inv in stripe_invoices.data:
+        invoices.append(
+            Invoice(
+                id=inv.id,
+                amount=inv.amount_paid or inv.amount_due,
+                currency=inv.currency,
+                status=inv.status,
+                created=datetime.fromtimestamp(inv.created, tz=UTC),
+                pdf_url=inv.invoice_pdf,
+            )
+        )
+
+    return invoices

msaas_billing-0.1.0/src/billing/models.py

@@ -0,0 +1,53 @@
+"""Pydantic models for billing domain objects."""
+
+from __future__ import annotations
+
+from datetime import datetime
+
+from pydantic import BaseModel, Field
+
+
+class Subscription(BaseModel):
+    """Represents an active or past subscription."""
+
+    id: str
+    user_id: str
+    plan_name: str
+    status: str = Field(description="Stripe subscription status (active, canceled, past_due, etc.)")
+    current_period_start: datetime
+    current_period_end: datetime
+    cancel_at_period_end: bool = False
+
+
+class Invoice(BaseModel):
+    """Represents a Stripe invoice."""
+
+    id: str
+    amount: int = Field(description="Amount in smallest currency unit (e.g., cents)")
+    currency: str
+    status: str
+    created: datetime
+    pdf_url: str | None = None
+
+
+class UsageRecord(BaseModel):
+    """Represents a metered usage record."""
+
+    user_id: str
+    metric: str
+    quantity: int
+    timestamp: datetime = Field(default_factory=datetime.now)
+
+
+class CheckoutSession(BaseModel):
+    """Result of creating a Stripe Checkout session."""
+
+    url: str = Field(description="Redirect URL for the checkout page")
+    session_id: str
+
+
+class WebhookEvent(BaseModel):
+    """Parsed and verified Stripe webhook event."""
+
+    type: str = Field(description="Stripe event type (e.g., checkout.session.completed)")
+    data: dict = Field(default_factory=dict, description="Event payload data")

msaas_billing-0.1.0/src/billing/router.py

@@ -0,0 +1,138 @@
+"""FastAPI router exposing billing endpoints."""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+from errors import (
+    NotFoundError,
+    ValidationError,
+)
+from fastapi import APIRouter, Header, Request
+from pydantic import BaseModel
+
+from billing.checkout import create_checkout, create_portal_session
+from billing.invoices import get_invoices
+from billing.models import CheckoutSession, Invoice, Subscription
+from billing.subscriptions import cancel_subscription, get_subscription
+from billing.usage import record_usage
+from billing.webhooks import handle_webhook
+
+
+class CheckoutRequest(BaseModel):
+    """Request body for creating a checkout session."""
+
+    user_id: str
+    plan: str
+    email: str | None = None
+
+
+class PortalRequest(BaseModel):
+    """Request body for creating a customer portal session."""
+
+    customer_id: str
+
+
+class UsageRequest(BaseModel):
+    """Request body for recording usage."""
+
+    user_id: str
+    metric: str
+    quantity: int = 1
+
+
+class CancelRequest(BaseModel):
+    """Request body for cancelling a subscription."""
+
+    user_id: str
+    at_period_end: bool = True
+
+
+class PortalResponse(BaseModel):
+    """Response containing a portal session URL."""
+
+    url: str
+
+
+BillingRouter = APIRouter(prefix="/billing", tags=["billing"])
+
+
+@BillingRouter.post("/checkout", response_model=CheckoutSession)
+async def checkout_endpoint(body: CheckoutRequest) -> CheckoutSession:
+    """Create a Stripe Checkout session for a plan."""
+    try:
+        return create_checkout(
+            user_id=body.user_id,
+            plan=body.plan,
+            email=body.email,
+        )
+    except ValueError as e:
+        raise ValidationError(str(e)) from e
+
+
+@BillingRouter.get("/subscription", response_model=Subscription | None)
+async def subscription_endpoint(user_id: str) -> Subscription | None:
+    """Get the current subscription for a user."""
+    return get_subscription(user_id)
+
+
+@BillingRouter.post("/cancel", response_model=Subscription)
+async def cancel_endpoint(body: CancelRequest) -> Subscription:
+    """Cancel a user's subscription."""
+    try:
+        return cancel_subscription(
+            user_id=body.user_id,
+            at_period_end=body.at_period_end,
+        )
+    except ValueError as e:
+        raise NotFoundError(str(e)) from e
+
+
+@BillingRouter.post("/portal", response_model=PortalResponse)
+async def portal_endpoint(body: PortalRequest) -> PortalResponse:
+    """Create a Stripe Customer Portal session."""
+    url = create_portal_session(customer_id=body.customer_id)
+    return PortalResponse(url=url)
+
+
+@BillingRouter.post("/webhook")
+async def webhook_endpoint(
+    request: Request,
+    stripe_signature: Annotated[str, Header(alias="Stripe-Signature")],
+) -> dict:
+    """Handle Stripe webhook events.
+
+    Reads the raw body and verifies the Stripe signature before processing.
+    """
+    payload = await request.body()
+
+    try:
+        event = handle_webhook(payload=payload, signature=stripe_signature)
+    except ValueError as e:
+        raise ValidationError(str(e)) from e
+
+    return {"type": event.type, "received": True}
+
+
+@BillingRouter.post("/usage")
+async def usage_endpoint(body: UsageRequest) -> dict:
+    """Record metered usage for billing."""
+    try:
+        record_usage(
+            user_id=body.user_id,
+            metric=body.metric,
+            quantity=body.quantity,
+        )
+    except ValueError as e:
+        raise ValidationError(str(e)) from e
+
+    return {"recorded": True}
+
+
+@BillingRouter.get("/invoices", response_model=list[Invoice])
+async def invoices_endpoint(user_id: str, limit: int = 10) -> list[Invoice]:
+    """Fetch recent invoices for a user."""
+    try:
+        return get_invoices(user_id=user_id, limit=limit)
+    except ValueError as e:
+        raise NotFoundError(str(e)) from e

msaas_billing-0.1.0/src/billing/subscriptions.py

@@ -0,0 +1,168 @@
+"""Subscription lifecycle management via Stripe."""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime
+
+import stripe
+
+from billing.config import get_config
+from billing.models import Subscription
+
+
+def _get_customer_id(user_id: str) -> str:
+    """Look up the Stripe customer ID by user_id stored in metadata.
+
+    Args:
+        user_id: Internal user identifier.
+
+    Returns:
+        Stripe customer ID.
+
+    Raises:
+        ValueError: If no customer is found for the given user_id.
+    """
+    customers = stripe.Customer.search(
+        query=f'metadata["user_id"]:"{user_id}"',
+        limit=1,
+    )
+
+    if not customers.data:
+        raise ValueError(f"No Stripe customer found for user_id '{user_id}'")
+
+    return customers.data[0].id
+
+
+def _resolve_plan_name(price_id: str) -> str:
+    """Resolve a Stripe price_id back to a plan name from config.
+
+    Returns the price_id itself if no matching plan is found.
+    """
+    config = get_config()
+    for plan_name, configured_price_id in config.product_plans.items():
+        if configured_price_id == price_id:
+            return plan_name
+    return price_id
+
+
+def _stripe_sub_to_model(sub: stripe.Subscription, user_id: str) -> Subscription:
+    """Convert a Stripe Subscription object to our domain model."""
+    price_id = sub["items"]["data"][0]["price"]["id"]
+    return Subscription(
+        id=sub.id,
+        user_id=user_id,
+        plan_name=_resolve_plan_name(price_id),
+        status=sub.status,
+        current_period_start=datetime.fromtimestamp(sub.current_period_start, tz=UTC),
+        current_period_end=datetime.fromtimestamp(sub.current_period_end, tz=UTC),
+        cancel_at_period_end=sub.cancel_at_period_end,
+    )
+
+
+def get_subscription(user_id: str) -> Subscription | None:
+    """Fetch the current active subscription for a user.
+
+    Args:
+        user_id: Internal user identifier.
+
+    Returns:
+        Subscription if found, None if the user has no active subscription.
+
+    Raises:
+        stripe.StripeError: On Stripe API failures.
+    """
+    try:
+        customer_id = _get_customer_id(user_id)
+    except ValueError:
+        return None
+
+    subscriptions = stripe.Subscription.list(
+        customer=customer_id,
+        status="active",
+        limit=1,
+        expand=["data.items.data.price"],
+    )
+
+    if not subscriptions.data:
+        # Also check for past_due or trialing
+        subscriptions = stripe.Subscription.list(
+            customer=customer_id,
+            limit=1,
+            expand=["data.items.data.price"],
+        )
+        if not subscriptions.data:
+            return None
+
+    return _stripe_sub_to_model(subscriptions.data[0], user_id)
+
+
+def cancel_subscription(user_id: str, at_period_end: bool = True) -> Subscription:
+    """Cancel a user's subscription.
+
+    Args:
+        user_id: Internal user identifier.
+        at_period_end: If True, cancel at the end of the current billing period.
+            If False, cancel immediately.
+
+    Returns:
+        Updated Subscription after cancellation.
+
+    Raises:
+        ValueError: If no active subscription is found.
+        stripe.StripeError: On Stripe API failures.
+    """
+    sub = get_subscription(user_id)
+    if sub is None:
+        raise ValueError(f"No active subscription found for user_id '{user_id}'")
+
+    if at_period_end:
+        updated = stripe.Subscription.modify(
+            sub.id,
+            cancel_at_period_end=True,
+        )
+    else:
+        updated = stripe.Subscription.cancel(sub.id)
+
+    return _stripe_sub_to_model(updated, user_id)
+
+
+def update_subscription(user_id: str, new_plan: str) -> Subscription:
+    """Change a user's subscription to a different plan (proration applied).
+
+    Args:
+        user_id: Internal user identifier.
+        new_plan: New plan name as defined in BillingConfig.product_plans.
+
+    Returns:
+        Updated Subscription with the new plan.
+
+    Raises:
+        ValueError: If no active subscription or unknown plan.
+        stripe.StripeError: On Stripe API failures.
+    """
+    config = get_config()
+    new_price_id = config.product_plans.get(new_plan)
+    if not new_price_id:
+        available = ", ".join(config.product_plans.keys())
+        raise ValueError(f"Unknown plan '{new_plan}'. Available plans: {available}")
+
+    sub = get_subscription(user_id)
+    if sub is None:
+        raise ValueError(f"No active subscription found for user_id '{user_id}'")
+
+    # Get the current subscription item to replace
+    stripe_sub = stripe.Subscription.retrieve(sub.id, expand=["items.data.price"])
+    current_item_id = stripe_sub["items"]["data"][0].id
+
+    updated = stripe.Subscription.modify(
+        sub.id,
+        items=[
+            {
+                "id": current_item_id,
+                "price": new_price_id,
+            }
+        ],
+        proration_behavior="create_prorations",
+    )
+
+    return _stripe_sub_to_model(updated, user_id)

msaas_billing-0.1.0/src/billing/usage.py

@@ -0,0 +1,108 @@
+"""Metered usage billing operations."""
+
+from __future__ import annotations
+
+import time
+
+import stripe
+
+from billing.subscriptions import _get_customer_id
+
+
+def _get_subscription_item_id(user_id: str, metric: str) -> str:
+    """Find the subscription item for a given metered metric.
+
+    Looks up the user's active subscription and finds the line item
+    whose price has a lookup_key matching the metric name.
+
+    Args:
+        user_id: Internal user identifier.
+        metric: The usage metric name (should match a Stripe price lookup_key).
+
+    Returns:
+        Stripe subscription item ID.
+
+    Raises:
+        ValueError: If no matching subscription item is found.
+    """
+    customer_id = _get_customer_id(user_id)
+
+    subscriptions = stripe.Subscription.list(
+        customer=customer_id,
+        status="active",
+        limit=1,
+        expand=["data.items.data.price"],
+    )
+
+    if not subscriptions.data:
+        raise ValueError(f"No active subscription for user_id '{user_id}'")
+
+    for item in subscriptions.data[0]["items"]["data"]:
+        price = item["price"]
+        if price.get("lookup_key") == metric or price.get("id") == metric:
+            return item.id
+
+    raise ValueError(
+        f"No subscription item found for metric '{metric}' on user '{user_id}'. "
+        "Ensure the Stripe price has a lookup_key matching the metric name."
+    )
+
+
+def record_usage(user_id: str, metric: str, quantity: int = 1) -> None:
+    """Record metered usage for a subscription item.
+
+    Args:
+        user_id: Internal user identifier.
+        metric: The usage metric name (matches Stripe price lookup_key).
+        quantity: Number of units to record. Defaults to 1.
+
+    Raises:
+        ValueError: If no matching subscription item is found.
+        stripe.StripeError: On Stripe API failures.
+    """
+    subscription_item_id = _get_subscription_item_id(user_id, metric)
+
+    stripe.SubscriptionItem.create_usage_record(
+        subscription_item_id,
+        quantity=quantity,
+        timestamp=int(time.time()),
+        action="increment",
+    )
+
+
+def get_usage(
+    user_id: str,
+    metric: str,
+    period_start: int | None = None,
+) -> int:
+    """Get total metered usage for a subscription item in the current period.
+
+    Args:
+        user_id: Internal user identifier.
+        metric: The usage metric name.
+        period_start: Unix timestamp for the start of the period to query.
+            Defaults to the current subscription period start.
+
+    Returns:
+        Total quantity used in the period.
+
+    Raises:
+        ValueError: If no matching subscription item is found.
+        stripe.StripeError: On Stripe API failures.
+    """
+    subscription_item_id = _get_subscription_item_id(user_id, metric)
+
+    # Fetch usage record summaries for the period
+    summaries = stripe.SubscriptionItem.list_usage_record_summaries(
+        subscription_item_id,
+        limit=100,
+    )
+
+    total = 0
+    for summary in summaries.auto_paging_iter():
+        # Filter by period_start if provided
+        if period_start is not None and summary.period.start < period_start:
+            continue
+        total += summary.total_usage
+
+    return total

msaas_billing-0.1.0/src/billing/webhooks.py

@@ -0,0 +1,120 @@
+"""Stripe webhook handling with signature verification."""
+
+from __future__ import annotations
+
+import logging
+
+import stripe
+from stripe import SignatureVerificationError
+
+from billing.config import get_config
+from billing.models import WebhookEvent
+
+logger = logging.getLogger("billing.webhooks")
+
+# Events this module understands and returns structured data for.
+HANDLED_EVENTS = frozenset(
+    {
+        "checkout.session.completed",
+        "customer.subscription.updated",
+        "customer.subscription.deleted",
+        "invoice.payment_succeeded",
+        "invoice.payment_failed",
+    }
+)
+
+
+def handle_webhook(payload: bytes, signature: str) -> WebhookEvent:
+    """Verify and parse a Stripe webhook event.
+
+    Verifies the webhook signature using the configured webhook secret,
+    then extracts structured data for known event types.
+
+    Args:
+        payload: Raw request body bytes from the webhook POST.
+        signature: Value of the Stripe-Signature header.
+
+    Returns:
+        WebhookEvent with the event type and extracted data.
+
+    Raises:
+        ValueError: If signature verification fails.
+    """
+    config = get_config()
+
+    try:
+        event = stripe.Webhook.construct_event(
+            payload,
+            signature,
+            config.stripe_webhook_secret,
+        )
+    except SignatureVerificationError as e:
+        logger.warning("Webhook signature verification failed: %s", e)
+        raise ValueError("Invalid webhook signature") from e
+
+    event_type = event.type
+    event_data: dict = {}
+
+    if event_type not in HANDLED_EVENTS:
+        logger.debug("Unhandled webhook event type: %s", event_type)
+        return WebhookEvent(type=event_type, data=event.data.object)
+
+    obj = event.data.object
+
+    if event_type == "checkout.session.completed":
+        event_data = {
+            "session_id": obj.id,
+            "customer_id": obj.customer,
+            "user_id": obj.client_reference_id,
+            "subscription_id": obj.subscription,
+            "email": obj.customer_email or obj.customer_details.get("email")
+            if obj.customer_details
+            else obj.customer_email,
+            "metadata": dict(obj.metadata) if obj.metadata else {},
+        }
+
+    elif event_type == "customer.subscription.updated":
+        event_data = {
+            "subscription_id": obj.id,
+            "customer_id": obj.customer,
+            "status": obj.status,
+            "cancel_at_period_end": obj.cancel_at_period_end,
+            "current_period_end": obj.current_period_end,
+            "items": [
+                {"price_id": item.price.id, "quantity": item.quantity}
+                for item in obj["items"]["data"]
+            ],
+        }
+
+    elif event_type == "customer.subscription.deleted":
+        event_data = {
+            "subscription_id": obj.id,
+            "customer_id": obj.customer,
+            "status": obj.status,
+            "ended_at": obj.ended_at,
+        }
+
+    elif event_type == "invoice.payment_succeeded":
+        event_data = {
+            "invoice_id": obj.id,
+            "customer_id": obj.customer,
+            "subscription_id": obj.subscription,
+            "amount_paid": obj.amount_paid,
+            "currency": obj.currency,
+            "hosted_invoice_url": obj.hosted_invoice_url,
+            "pdf_url": obj.invoice_pdf,
+        }
+
+    elif event_type == "invoice.payment_failed":
+        event_data = {
+            "invoice_id": obj.id,
+            "customer_id": obj.customer,
+            "subscription_id": obj.subscription,
+            "amount_due": obj.amount_due,
+            "currency": obj.currency,
+            "attempt_count": obj.attempt_count,
+            "next_payment_attempt": obj.next_payment_attempt,
+        }
+
+    logger.info("Processed webhook event: %s", event_type)
+    return WebhookEvent(type=event_type, data=event_data)

msaas_billing-0.1.0/tests/conftest.py

@@ -0,0 +1,24 @@
+"""Shared test fixtures for billing tests."""
+
+from __future__ import annotations
+
+import pytest
+from billing.config import BillingConfig, init_billing
+
+
+@pytest.fixture(autouse=True)
+def billing_config():
+    """Initialize billing with test configuration before each test."""
+    config = BillingConfig(
+        stripe_secret_key="sk_test_fake_key_for_testing",
+        stripe_webhook_secret="whsec_test_fake_secret",
+        success_url="https://example.com/success",
+        cancel_url="https://example.com/cancel",
+        product_plans={
+            "starter": "price_starter_test",
+            "pro": "price_pro_test",
+            "enterprise": "price_enterprise_test",
+        },
+    )
+    init_billing(config)
+    return config

msaas_billing-0.1.0/tests/test_checkout.py

@@ -0,0 +1,78 @@
+"""Tests for checkout session creation."""
+
+from __future__ import annotations
+
+from unittest.mock import MagicMock, patch
+
+import pytest
+from billing.checkout import create_checkout, create_portal_session
+from billing.models import CheckoutSession
+
+
+class TestCreateCheckout:
+    """Tests for create_checkout function."""
+
+    @patch("billing.checkout.stripe.checkout.Session.create")
+    def test_creates_session_with_correct_params(self, mock_create: MagicMock) -> None:
+        mock_create.return_value = MagicMock(
+            url="https://checkout.stripe.com/c/pay_test123",
+            id="cs_test_session123",
+        )
+
+        result = create_checkout(user_id="user_abc", plan="pro", email="user@example.com")
+
+        assert isinstance(result, CheckoutSession)
+        assert result.url == "https://checkout.stripe.com/c/pay_test123"
+        assert result.session_id == "cs_test_session123"
+
+        call_kwargs = mock_create.call_args[1]
+        assert call_kwargs["mode"] == "subscription"
+        assert call_kwargs["line_items"] == [{"price": "price_pro_test", "quantity": 1}]
+        assert call_kwargs["client_reference_id"] == "user_abc"
+        assert call_kwargs["customer_email"] == "user@example.com"
+        assert call_kwargs["success_url"] == "https://example.com/success"
+        assert call_kwargs["cancel_url"] == "https://example.com/cancel"
+        assert call_kwargs["metadata"]["user_id"] == "user_abc"
+        assert call_kwargs["metadata"]["plan"] == "pro"
+
+    @patch("billing.checkout.stripe.checkout.Session.create")
+    def test_creates_session_without_email(self, mock_create: MagicMock) -> None:
+        mock_create.return_value = MagicMock(
+            url="https://checkout.stripe.com/c/pay_test456",
+            id="cs_test_session456",
+        )
+
+        result = create_checkout(user_id="user_xyz", plan="starter")
+
+        assert result.session_id == "cs_test_session456"
+
+        call_kwargs = mock_create.call_args[1]
+        assert "customer_email" not in call_kwargs
+
+    def test_raises_value_error_for_unknown_plan(self) -> None:
+        with pytest.raises(ValueError, match="Unknown plan 'nonexistent'"):
+            create_checkout(user_id="user_abc", plan="nonexistent")
+
+    def test_error_message_lists_available_plans(self) -> None:
+        with pytest.raises(ValueError, match="starter") as exc_info:
+            create_checkout(user_id="user_abc", plan="bad_plan")
+        assert "pro" in str(exc_info.value)
+        assert "enterprise" in str(exc_info.value)
+
+
+class TestCreatePortalSession:
+    """Tests for create_portal_session function."""
+
+    @patch("billing.checkout.stripe.billing_portal.Session.create")
+    def test_returns_portal_url(self, mock_create: MagicMock) -> None:
+        mock_create.return_value = MagicMock(
+            url="https://billing.stripe.com/p/session/test_portal",
+        )
+
+        url = create_portal_session(customer_id="cus_test123")
+
+        assert url == "https://billing.stripe.com/p/session/test_portal"
+        mock_create.assert_called_once_with(
+            customer="cus_test123",
+            return_url="https://example.com/success",
+        )

msaas_billing-0.1.0/tests/test_webhooks.py

@@ -0,0 +1,148 @@
+"""Tests for webhook handling and signature verification."""
+
+from __future__ import annotations
+
+from unittest.mock import MagicMock, patch
+
+import pytest
+from billing.webhooks import handle_webhook
+from stripe import SignatureVerificationError
+
+
+class TestHandleWebhook:
+    """Tests for handle_webhook function."""
+
+    def _make_stripe_event(self, event_type: str, obj_data: dict) -> MagicMock:
+        """Helper to create a mock Stripe event."""
+        event = MagicMock()
+        event.type = event_type
+        event.data.object = MagicMock(**obj_data)
+        # Ensure dict-style access works for nested items
+        if "items" in obj_data:
+            event.data.object.__getitem__ = lambda self, key: obj_data[key]
+        return event
+
+    @patch("billing.webhooks.stripe.Webhook.construct_event")
+    def test_checkout_completed_event(self, mock_construct: MagicMock) -> None:
+        mock_event = self._make_stripe_event(
+            "checkout.session.completed",
+            {
+                "id": "cs_test_123",
+                "customer": "cus_test_456",
+                "client_reference_id": "user_abc",
+                "subscription": "sub_test_789",
+                "customer_email": "user@example.com",
+                "customer_details": None,
+                "metadata": {"user_id": "user_abc", "plan": "pro"},
+            },
+        )
+        mock_construct.return_value = mock_event
+
+        result = handle_webhook(b"payload", "sig_header")
+
+        assert result.type == "checkout.session.completed"
+        assert result.data["session_id"] == "cs_test_123"
+        assert result.data["customer_id"] == "cus_test_456"
+        assert result.data["user_id"] == "user_abc"
+        assert result.data["subscription_id"] == "sub_test_789"
+
+    @patch("billing.webhooks.stripe.Webhook.construct_event")
+    def test_subscription_deleted_event(self, mock_construct: MagicMock) -> None:
+        mock_event = self._make_stripe_event(
+            "customer.subscription.deleted",
+            {
+                "id": "sub_test_789",
+                "customer": "cus_test_456",
+                "status": "canceled",
+                "ended_at": 1700000000,
+            },
+        )
+        mock_construct.return_value = mock_event
+
+        result = handle_webhook(b"payload", "sig_header")
+
+        assert result.type == "customer.subscription.deleted"
+        assert result.data["subscription_id"] == "sub_test_789"
+        assert result.data["status"] == "canceled"
+        assert result.data["ended_at"] == 1700000000
+
+    @patch("billing.webhooks.stripe.Webhook.construct_event")
+    def test_invoice_payment_succeeded(self, mock_construct: MagicMock) -> None:
+        mock_event = self._make_stripe_event(
+            "invoice.payment_succeeded",
+            {
+                "id": "in_test_001",
+                "customer": "cus_test_456",
+                "subscription": "sub_test_789",
+                "amount_paid": 2999,
+                "currency": "usd",
+                "hosted_invoice_url": "https://invoice.stripe.com/i/test",
+                "invoice_pdf": "https://invoice.stripe.com/i/test/pdf",
+            },
+        )
+        mock_construct.return_value = mock_event
+
+        result = handle_webhook(b"payload", "sig_header")
+
+        assert result.type == "invoice.payment_succeeded"
+        assert result.data["amount_paid"] == 2999
+        assert result.data["currency"] == "usd"
+        assert result.data["pdf_url"] == "https://invoice.stripe.com/i/test/pdf"
+
+    @patch("billing.webhooks.stripe.Webhook.construct_event")
+    def test_invoice_payment_failed(self, mock_construct: MagicMock) -> None:
+        mock_event = self._make_stripe_event(
+            "invoice.payment_failed",
+            {
+                "id": "in_test_002",
+                "customer": "cus_test_456",
+                "subscription": "sub_test_789",
+                "amount_due": 2999,
+                "currency": "usd",
+                "attempt_count": 2,
+                "next_payment_attempt": 1700100000,
+            },
+        )
+        mock_construct.return_value = mock_event
+
+        result = handle_webhook(b"payload", "sig_header")
+
+        assert result.type == "invoice.payment_failed"
+        assert result.data["attempt_count"] == 2
+        assert result.data["next_payment_attempt"] == 1700100000
+
+    @patch("billing.webhooks.stripe.Webhook.construct_event")
+    def test_unhandled_event_type_returns_raw_data(self, mock_construct: MagicMock) -> None:
+        mock_event = MagicMock()
+        mock_event.type = "charge.refunded"
+        mock_event.data.object = {"id": "ch_test", "amount": 1000}
+        mock_construct.return_value = mock_event
+
+        result = handle_webhook(b"payload", "sig_header")
+
+        assert result.type == "charge.refunded"
+
+    @patch("billing.webhooks.stripe.Webhook.construct_event")
+    def test_invalid_signature_raises_value_error(self, mock_construct: MagicMock) -> None:
+        mock_construct.side_effect = SignatureVerificationError(
+            "No signatures found matching the expected signature for payload",
+            sig_header="bad_sig",
+        )
+
+        with pytest.raises(ValueError, match="Invalid webhook signature"):
+            handle_webhook(b"payload", "bad_sig")
+
+    @patch("billing.webhooks.stripe.Webhook.construct_event")
+    def test_construct_event_called_with_correct_args(self, mock_construct: MagicMock) -> None:
+        mock_event = MagicMock()
+        mock_event.type = "charge.refunded"
+        mock_event.data.object = {}
+        mock_construct.return_value = mock_event
+
+        handle_webhook(b"raw_body_data", "whsec_sig_value")
+
+        mock_construct.assert_called_once_with(
+            b"raw_body_data",
+            "whsec_sig_value",
+            "whsec_test_fake_secret",
+        )