nat-engine 1__py3-none-any.whl

mannf/product/billing/metering.py

@@ -0,0 +1,179 @@
+# Copyright (C) 2026 Brad Guider
+# This file is part of NAT (Neural Agent Testing Framework).
+# Licensed under the AGPL-3.0. See LICENSE for details.
+
+"""Metered usage reporting for NAT SaaS module add-ons.
+
+For plans with metered billing, ``report_module_usage`` creates a usage record
+on the appropriate Stripe subscription item.  For flat-rate plans the function
+is a no-op but still logs usage internally for tracking purposes.
+"""
+
+from __future__ import annotations
+
+import logging
+
+logger = logging.getLogger(__name__)
+
+
+def report_module_usage(tenant_id: str, module_name: str, quantity: int = 1) -> None:
+    """Report metered usage for a module add-on to Stripe.
+
+    For plans with metered billing, this creates a usage record on the
+    appropriate subscription item.  For flat-rate plans, this is a no-op
+    but still logs for internal tracking.
+
+    Args:
+        tenant_id: The NAT tenant UUID string.
+        module_name: The scan module being used (e.g. ``"visual"``,
+                     ``"performance"``).
+        quantity: Number of usage units to report.  Defaults to ``1``.
+    """
+    logger.debug(
+        "report_module_usage: tenant=%s module=%s quantity=%d",
+        tenant_id,
+        module_name,
+        quantity,
+    )
+
+    try:
+        _report_to_stripe(tenant_id, module_name, quantity)
+    except Exception as exc:  # noqa: BLE001
+        # Non-fatal: log and continue.  Stripe usage reporting should never
+        # block the scan from proceeding.
+        logger.warning(
+            "Failed to report module usage to Stripe (tenant=%s, module=%s): %s",
+            tenant_id,
+            module_name,
+            exc,
+        )
+
+
+def _report_to_stripe(tenant_id: str, module_name: str, quantity: int) -> None:
+    """Internal: attempt to create a Stripe usage record for the module.
+
+    Looks up the tenant's subscription item ID for the given module product,
+    then creates a usage record via the Stripe API.  Silently skips if:
+    - Stripe is not configured (``STRIPE_SECRET_KEY`` absent)
+    - No module product ID is configured for *module_name*
+    - The tenant has no subscription item matching the module product
+    - The database is unavailable
+    """
+    import os  # noqa: PLC0415
+
+    stripe_key = os.environ.get("STRIPE_SECRET_KEY", "")
+    if not stripe_key:
+        logger.debug("STRIPE_SECRET_KEY not set — skipping Stripe usage report")
+        return
+
+    from mannf.product.billing.plans import MODULE_PRODUCTS  # noqa: PLC0415
+
+    module_product_id = MODULE_PRODUCTS.get(module_name)
+    if not module_product_id:
+        logger.debug(
+            "No Stripe product configured for module '%s' — skipping usage report",
+            module_name,
+        )
+        return
+
+    # Attempt to resolve the subscription item ID from the tenant record.
+    subscription_item_id = _resolve_subscription_item_id(tenant_id, module_product_id)
+    if not subscription_item_id:
+        logger.debug(
+            "No subscription item found for tenant=%s module=%s — skipping usage report",
+            tenant_id,
+            module_name,
+        )
+        return
+
+    import stripe  # noqa: PLC0415
+
+    stripe.api_key = stripe_key
+    stripe.SubscriptionItem.create_usage_record(
+        subscription_item_id,
+        quantity=quantity,
+        action="increment",
+    )
+    logger.info(
+        "Reported %d usage unit(s) for tenant=%s module=%s (item=%s)",
+        quantity,
+        tenant_id,
+        module_name,
+        subscription_item_id,
+    )
+
+
+def _resolve_subscription_item_id(tenant_id: str, product_id: str) -> str | None:
+    """Return the Stripe subscription item ID for *product_id* on *tenant_id*.
+
+    Queries the Stripe API for the tenant's subscription items and returns the
+    ID of the item whose price is for the given product.  Returns ``None`` if
+    not found or if the database / Stripe is unavailable.
+    """
+    import os  # noqa: PLC0415
+
+    stripe_key = os.environ.get("STRIPE_SECRET_KEY", "")
+    if not stripe_key:
+        return None
+
+    subscription_id = _get_tenant_subscription_id(tenant_id)
+    if not subscription_id:
+        return None
+
+    try:
+        import stripe  # noqa: PLC0415
+
+        stripe.api_key = stripe_key
+        subscription = stripe.Subscription.retrieve(subscription_id, expand=["items.data.price.product"])
+        for item in subscription.get("items", {}).get("data", []):
+            item_product = item.get("price", {}).get("product")
+            item_product_id = (
+                item_product.get("id") if isinstance(item_product, dict) else item_product
+            )
+            if item_product_id == product_id:
+                return item["id"]
+    except Exception as exc:  # noqa: BLE001
+        logger.debug("_resolve_subscription_item_id failed: %s", exc)
+
+    return None
+
+
+def _get_tenant_subscription_id(tenant_id: str) -> str | None:
+    """Return the Stripe subscription ID for *tenant_id* from the database."""
+    try:
+        import asyncio  # noqa: PLC0415
+        from mannf.product.database import _async_session_factory, _build_engine  # noqa: PLC0415
+
+        if _build_engine() is None or _async_session_factory is None:
+            return None
+
+        import uuid as _uuid  # noqa: PLC0415
+
+        async def _fetch() -> str | None:
+            from sqlalchemy import select  # noqa: PLC0415
+            from mannf.product.models import Tenant  # noqa: PLC0415
+
+            try:
+                tenant_uuid = _uuid.UUID(tenant_id)
+            except ValueError:
+                return None
+
+            async with _async_session_factory() as session:
+                result = await session.execute(
+                    select(Tenant.stripe_subscription_id).where(Tenant.id == tenant_uuid)
+                )
+                return result.scalar_one_or_none()
+
+        try:
+            loop = asyncio.get_running_loop()
+            # Inside an async context — use a future
+            import concurrent.futures  # noqa: PLC0415
+
+            with concurrent.futures.ThreadPoolExecutor(max_workers=1) as pool:
+                future = pool.submit(asyncio.run, _fetch())
+                return future.result(timeout=5)
+        except RuntimeError:
+            return asyncio.run(_fetch())
+    except Exception as exc:  # noqa: BLE001
+        logger.debug("_get_tenant_subscription_id failed: %s", exc)
+        return None

mannf/product/billing/notifications.py

@@ -0,0 +1,181 @@
+# Copyright (C) 2026 Brad Guider
+# This file is part of NAT (Neural Agent Testing Framework).
+# Licensed under the AGPL-3.0. See LICENSE for details.
+
+"""Billing event notification dispatcher.
+
+Fires on key billing lifecycle events and delivers notifications via:
+- **Webhook**: HTTP POST to a tenant-configured URL (Team/Enterprise plans).
+- **Email** (log-based placeholder): structured log entry for future
+  email-service integration.
+
+Usage::
+
+    from mannf.product.billing.notifications import dispatch_billing_notification
+
+    await dispatch_billing_notification(
+        event_type="payment.failed",
+        tenant_id="<uuid>",
+        tenant_email="user@example.com",
+        details={"stripe_invoice_id": "in_…"},
+    )
+
+All errors are caught and logged — notifications must never block billing flows.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+import os
+from typing import Any, Optional
+
+logger = logging.getLogger(__name__)
+
+# ---------------------------------------------------------------------------
+# Public dispatcher
+# ---------------------------------------------------------------------------
+
+
+async def dispatch_billing_notification(
+    event_type: str,
+    *,
+    tenant_id: Optional[str] = None,
+    tenant_email: Optional[str] = None,
+    webhook_url: Optional[str] = None,
+    details: Optional[dict[str, Any]] = None,
+) -> None:
+    """Dispatch a billing notification for the given event type.
+
+    Delivers the notification to all configured channels (webhook, email)
+    concurrently.  All failures are swallowed and logged.
+
+    Args:
+        event_type: Billing event identifier, e.g. ``"payment.failed"``.
+        tenant_id: UUID string of the affected tenant.
+        tenant_email: Tenant's email address (used for email notifications).
+        webhook_url: Tenant-configured webhook URL (Team/Enterprise plans).
+            If ``None``, the global ``NAT_BILLING_WEBHOOK_URL`` env var is
+            checked as a fallback.
+        details: Additional event context to include in the notification.
+    """
+    payload: dict[str, Any] = {
+        "event_type": event_type,
+        "tenant_id": tenant_id,
+        "details": details or {},
+    }
+
+    tasks = []
+
+    # Resolve webhook URL: per-tenant override → global env fallback
+    effective_webhook_url = webhook_url or os.environ.get(
+        "NAT_BILLING_WEBHOOK_URL", ""
+    )
+    if effective_webhook_url:
+        tasks.append(_deliver_webhook(effective_webhook_url, payload))
+
+    # Email notification (log-based placeholder)
+    if tenant_email:
+        tasks.append(_deliver_email(event_type, tenant_email, payload))
+
+    if tasks:
+        results = await asyncio.gather(*tasks, return_exceptions=True)
+        for i, result in enumerate(results):
+            if isinstance(result, Exception):
+                logger.warning(
+                    "Billing notification delivery failed (task %d) for event %s: %s",
+                    i,
+                    event_type,
+                    result,
+                )
+    else:
+        logger.debug(
+            "No notification channels configured for billing event: %s", event_type
+        )
+
+
+# ---------------------------------------------------------------------------
+# Delivery backends
+# ---------------------------------------------------------------------------
+
+
+async def _deliver_webhook(
+    url: str, payload: dict[str, Any], *, timeout: float = 10.0
+) -> None:
+    """POST the billing event payload to the configured webhook URL.
+
+    Args:
+        url: Target webhook endpoint.
+        payload: JSON-serialisable event payload.
+        timeout: Request timeout in seconds.
+    """
+    try:
+        import aiohttp  # noqa: PLC0415
+    except ImportError:
+        logger.warning(
+            "_deliver_webhook: aiohttp not installed — webhook delivery skipped"
+        )
+        return
+
+    try:
+        body = json.dumps(payload, default=str)
+        headers = {
+            "Content-Type": "application/json",
+            "User-Agent": "NAT-Billing/1.0",
+        }
+
+        # Include optional signing secret
+        signing_secret = os.environ.get("NAT_BILLING_WEBHOOK_SECRET", "")
+        if signing_secret:
+            import hashlib  # noqa: PLC0415
+            import hmac  # noqa: PLC0415
+
+            sig = hmac.new(
+                signing_secret.encode(), body.encode(), hashlib.sha256
+            ).hexdigest()
+            headers["X-NAT-Signature"] = f"sha256={sig}"
+
+        async with aiohttp.ClientSession() as session:
+            async with session.post(
+                url, data=body, headers=headers, timeout=aiohttp.ClientTimeout(total=timeout)
+            ) as resp:
+                if resp.status >= 400:
+                    logger.warning(
+                        "_deliver_webhook: server returned %d for event %s",
+                        resp.status,
+                        payload.get("event_type"),
+                    )
+                else:
+                    logger.debug(
+                        "_deliver_webhook: delivered %s to %s (status=%d)",
+                        payload.get("event_type"),
+                        url,
+                        resp.status,
+                    )
+    except Exception as exc:  # noqa: BLE001
+        raise RuntimeError(
+            f"Webhook delivery to {url!r} failed: {exc}"
+        ) from exc
+
+
+async def _deliver_email(
+    event_type: str, recipient: str, payload: dict[str, Any]
+) -> None:
+    """Log a structured email notification placeholder.
+
+    In future this will call an email service (SendGrid, SES, etc.).  For now
+    it emits a structured INFO log entry that can be forwarded by any log
+    aggregator.
+
+    Args:
+        event_type: Billing event type.
+        recipient: Destination email address.
+        payload: Full event payload for context.
+    """
+    logger.info(
+        "BILLING_EMAIL_NOTIFICATION event_type=%s recipient=%s payload=%s",
+        event_type,
+        recipient,
+        json.dumps(payload, default=str),
+    )

mannf/product/billing/plans.py

@@ -0,0 +1,133 @@
+# Copyright (C) 2026 Brad Guider
+# This file is part of NAT (Neural Agent Testing Framework).
+# Licensed under the AGPL-3.0. See LICENSE for details.
+
+"""NAT SaaS plan tier definitions."""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class PlanTier:
+    name: str
+    display_name: str
+    monthly_scan_quota: int          # functional scans per month
+    monthly_security_scan_quota: int  # security scans per month
+    price_monthly_cents: int         # price in cents (0 = free)
+    stripe_price_id: str | None      # recurring price ID; populated from env vars
+    stripe_product_id: str | None    # product ID; populated from env vars
+    rate_limit_per_minute: int       # API requests per minute for this plan
+    max_concurrent_scans: int        # maximum simultaneous scans for this plan
+    included_modules: tuple[str, ...] = ()  # modules included in base subscription
+    max_scheduled_scans: int = 0     # max recurring scan schedules (0 = not available)
+    max_seats: int = 0               # max user seats (0 = unlimited)
+
+
+PLAN_TIERS: dict[str, PlanTier] = {
+    "free": PlanTier(
+        name="free",
+        display_name="Free",
+        monthly_scan_quota=50,
+        monthly_security_scan_quota=10,
+        price_monthly_cents=0,
+        stripe_price_id=os.environ.get("STRIPE_PRICE_ID_FREE") or None,
+        stripe_product_id=os.environ.get("STRIPE_PRODUCT_ID_FREE") or None,
+        rate_limit_per_minute=10,
+        max_concurrent_scans=1,
+        included_modules=("functional",),
+        max_scheduled_scans=0,
+        max_seats=1,
+    ),
+    "pro": PlanTier(
+        name="pro",
+        display_name="Pro",
+        monthly_scan_quota=500,
+        monthly_security_scan_quota=100,
+        price_monthly_cents=4900,  # $49/month
+        stripe_price_id=os.environ.get("STRIPE_PRICE_ID_PRO") or None,
+        stripe_product_id=os.environ.get("STRIPE_PRODUCT_ID_PRO") or None,
+        rate_limit_per_minute=60,
+        max_concurrent_scans=3,
+        included_modules=("functional", "visual", "accessibility"),
+        max_scheduled_scans=3,
+        max_seats=5,
+    ),
+    "team": PlanTier(
+        name="team",
+        display_name="Team",
+        monthly_scan_quota=2000,
+        monthly_security_scan_quota=500,
+        price_monthly_cents=14900,  # $149/month
+        stripe_price_id=os.environ.get("STRIPE_PRICE_ID_TEAM") or None,
+        stripe_product_id=os.environ.get("STRIPE_PRODUCT_ID_TEAM") or None,
+        rate_limit_per_minute=200,
+        max_concurrent_scans=10,
+        included_modules=("functional", "visual", "accessibility", "performance"),
+        max_scheduled_scans=10,
+        max_seats=25,
+    ),
+    "enterprise": PlanTier(
+        name="enterprise",
+        display_name="Enterprise",
+        monthly_scan_quota=999999,  # effectively unlimited
+        monthly_security_scan_quota=999999,
+        price_monthly_cents=0,  # custom pricing
+        stripe_price_id=os.environ.get("STRIPE_PRICE_ID_ENTERPRISE") or None,
+        stripe_product_id=os.environ.get("STRIPE_PRODUCT_ID_ENTERPRISE") or None,
+        rate_limit_per_minute=1000,
+        max_concurrent_scans=999999,  # effectively unlimited
+        included_modules=("functional", "visual", "accessibility", "performance"),
+        max_scheduled_scans=999_999,
+        max_seats=0,
+    ),
+}
+
+# Per-module Stripe product IDs for modular add-on pricing.
+# Each key maps to the env var that holds the Stripe product ID for that module.
+MODULE_PRODUCTS: dict[str, str | None] = {
+    "functional": os.environ.get("STRIPE_PRODUCT_ID_FUNCTIONAL") or None,
+    "visual": os.environ.get("STRIPE_PRODUCT_ID_VISUAL") or None,
+    "accessibility": os.environ.get("STRIPE_PRODUCT_ID_ACCESSIBILITY") or None,
+    "performance": os.environ.get("STRIPE_PRODUCT_ID_PERFORMANCE") or None,
+    "ai_intelligence": os.environ.get("STRIPE_PRODUCT_ID_AI_INTELLIGENCE") or None,
+}
+
+# Per-module Stripe price IDs for add-on billing.
+MODULE_PRICES: dict[str, str | None] = {
+    "functional": os.environ.get("STRIPE_PRICE_ID_FUNCTIONAL") or None,
+    "visual": os.environ.get("STRIPE_PRICE_ID_VISUAL") or None,
+    "accessibility": os.environ.get("STRIPE_PRICE_ID_ACCESSIBILITY") or None,
+    "performance": os.environ.get("STRIPE_PRICE_ID_PERFORMANCE") or None,
+}
+
+
+def get_module_price_id(module_name: str) -> str | None:
+    """Return the Stripe price ID for a scan module add-on, or None."""
+    return MODULE_PRICES.get(module_name)
+
+
+def get_plan(tier_name: str) -> PlanTier:
+    """Return the plan tier config, defaulting to 'free' for unknown tiers."""
+    return PLAN_TIERS.get(tier_name, PLAN_TIERS["free"])
+
+
+def get_plan_by_stripe_price_id(price_id: str) -> PlanTier | None:
+    """Reverse-look up a plan by its Stripe price ID.
+
+    Useful in webhook handlers where only the price ID is known (e.g. from a
+    ``checkout.session.completed`` event).
+
+    Args:
+        price_id: The Stripe price ID to look up (e.g. ``"price_abc123"``).
+
+    Returns:
+        The matching :class:`PlanTier`, or ``None`` if no plan is configured
+        with that price ID.
+    """
+    for plan in PLAN_TIERS.values():
+        if plan.stripe_price_id and plan.stripe_price_id == price_id:
+            return plan
+    return None

mannf/product/billing/rate_limits.py

@@ -0,0 +1,35 @@
+# Copyright (C) 2026 Brad Guider
+# This file is part of NAT (Neural Agent Testing Framework).
+# Licensed under the AGPL-3.0. See LICENSE for details.
+
+"""Per-plan rate limit configuration for the NAT SaaS API.
+
+Each plan tier has its own request-per-minute and concurrent-scan limits
+that override the global ``NAT_RATE_LIMIT`` environment variable when a
+tenant is authenticated.
+"""
+
+from __future__ import annotations
+
+from typing import TypedDict
+
+
+class RateLimitConfig(TypedDict):
+    requests_per_minute: int
+    concurrent_scans: int
+
+
+PLAN_RATE_LIMITS: dict[str, RateLimitConfig] = {
+    "free": {"requests_per_minute": 30, "concurrent_scans": 1},
+    "pro": {"requests_per_minute": 120, "concurrent_scans": 3},
+    "team": {"requests_per_minute": 300, "concurrent_scans": 10},
+    "enterprise": {"requests_per_minute": 1000, "concurrent_scans": 50},
+}
+
+# Default to the free plan limits for unknown/unrecognised tiers.
+_DEFAULT_PLAN = "free"
+
+
+def get_rate_limit_config(plan_tier: str) -> RateLimitConfig:
+    """Return the rate-limit config for *plan_tier*, defaulting to free."""
+    return PLAN_RATE_LIMITS.get(plan_tier, PLAN_RATE_LIMITS[_DEFAULT_PLAN])