svc-infra 0.1.562__py3-none-any.whl → 0.1.654__py3-none-any.whl

svc_infra/billing/async_service.py

@@ -0,0 +1,147 @@
+from __future__ import annotations
+
+import uuid
+from datetime import datetime, timedelta, timezone
+from typing import Optional, Sequence
+
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from .models import Invoice, InvoiceLine, UsageAggregate, UsageEvent
+
+
+class AsyncBillingService:
+    def __init__(self, session: AsyncSession, tenant_id: str):
+        self.session = session
+        self.tenant_id = tenant_id
+
+    async def record_usage(
+        self,
+        *,
+        metric: str,
+        amount: int,
+        at: datetime,
+        idempotency_key: str,
+        metadata: dict | None,
+    ) -> str:
+        if at.tzinfo is None:
+            at = at.replace(tzinfo=timezone.utc)
+        evt = UsageEvent(
+            id=str(uuid.uuid4()),
+            tenant_id=self.tenant_id,
+            metric=metric,
+            amount=amount,
+            at_ts=at,
+            idempotency_key=idempotency_key,
+            metadata_json=metadata or {},
+        )
+        self.session.add(evt)
+        await self.session.flush()
+        return evt.id
+
+    async def aggregate_daily(self, *, metric: str, day_start: datetime) -> int:
+        day_start = day_start.replace(
+            hour=0, minute=0, second=0, microsecond=0, tzinfo=timezone.utc
+        )
+        next_day = day_start + timedelta(days=1)
+        total = 0
+        rows: Sequence[UsageEvent] = (
+            (
+                await self.session.execute(
+                    select(UsageEvent).where(
+                        UsageEvent.tenant_id == self.tenant_id,
+                        UsageEvent.metric == metric,
+                        UsageEvent.at_ts >= day_start,
+                        UsageEvent.at_ts < next_day,
+                    )
+                )
+            )
+            .scalars()
+            .all()
+        )
+        for r in rows:
+            total += int(r.amount)
+
+        agg = (
+            await self.session.execute(
+                select(UsageAggregate).where(
+                    UsageAggregate.tenant_id == self.tenant_id,
+                    UsageAggregate.metric == metric,
+                    UsageAggregate.period_start == day_start,
+                    UsageAggregate.granularity == "day",
+                )
+            )
+        ).scalar_one_or_none()
+        if agg:
+            agg.total = total
+        else:
+            self.session.add(
+                UsageAggregate(
+                    id=str(uuid.uuid4()),
+                    tenant_id=self.tenant_id,
+                    metric=metric,
+                    period_start=day_start,
+                    granularity="day",
+                    total=total,
+                )
+            )
+        return total
+
+    async def list_daily_aggregates(
+        self, *, metric: str, date_from: Optional[datetime], date_to: Optional[datetime]
+    ) -> list[UsageAggregate]:
+        q = select(UsageAggregate).where(
+            UsageAggregate.tenant_id == self.tenant_id,
+            UsageAggregate.metric == metric,
+            UsageAggregate.granularity == "day",
+        )
+        if date_from is not None:
+            q = q.where(UsageAggregate.period_start >= date_from)
+        if date_to is not None:
+            q = q.where(UsageAggregate.period_start < date_to)
+        rows: list[UsageAggregate] = (await self.session.execute(q)).scalars().all()
+        return rows
+
+    async def generate_monthly_invoice(
+        self, *, period_start: datetime, period_end: datetime, currency: str
+    ) -> str:
+        total = 0
+        aggs: Sequence[UsageAggregate] = (
+            (
+                await self.session.execute(
+                    select(UsageAggregate).where(
+                        UsageAggregate.tenant_id == self.tenant_id,
+                        UsageAggregate.period_start >= period_start,
+                        UsageAggregate.period_start < period_end,
+                        UsageAggregate.granularity == "day",
+                    )
+                )
+            )
+            .scalars()
+            .all()
+        )
+        for r in aggs:
+            total += int(r.total)
+
+        inv = Invoice(
+            id=str(uuid.uuid4()),
+            tenant_id=self.tenant_id,
+            period_start=period_start,
+            period_end=period_end,
+            status="created",
+            total_amount=total,
+            currency=currency,
+        )
+        self.session.add(inv)
+        await self.session.flush()
+
+        line = InvoiceLine(
+            id=str(uuid.uuid4()),
+            invoice_id=inv.id,
+            price_id=None,
+            metric=None,
+            quantity=1,
+            amount=total,
+        )
+        self.session.add(line)
+        return inv.id

svc_infra/billing/jobs.py

@@ -0,0 +1,230 @@
+from __future__ import annotations
+
+import inspect
+from datetime import datetime, timezone
+from typing import Any, Awaitable, Callable, Dict, Optional
+
+from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker
+
+from svc_infra.jobs.queue import Job, JobQueue
+from svc_infra.jobs.scheduler import InMemoryScheduler
+from svc_infra.webhooks.service import WebhookService
+
+from .async_service import AsyncBillingService
+
+
+async def job_aggregate_daily(
+    session: AsyncSession, *, tenant_id: str, metric: str, day_start: datetime
+) -> None:
+    """
+    Aggregate usage for a tenant/metric for the given day_start (UTC).
+
+    Intended to be called from a scheduler/worker with an AsyncSession created by the host app.
+    """
+    svc = AsyncBillingService(session=session, tenant_id=tenant_id)
+    if day_start.tzinfo is None:
+        day_start = day_start.replace(tzinfo=timezone.utc)
+    await svc.aggregate_daily(metric=metric, day_start=day_start)
+
+
+async def job_generate_monthly_invoice(
+    session: AsyncSession,
+    *,
+    tenant_id: str,
+    period_start: datetime,
+    period_end: datetime,
+    currency: str,
+) -> str:
+    """
+    Generate a monthly invoice for a tenant between [period_start, period_end).
+    Returns the internal invoice id.
+    """
+    svc = AsyncBillingService(session=session, tenant_id=tenant_id)
+    if period_start.tzinfo is None:
+        period_start = period_start.replace(tzinfo=timezone.utc)
+    if period_end.tzinfo is None:
+        period_end = period_end.replace(tzinfo=timezone.utc)
+    return await svc.generate_monthly_invoice(
+        period_start=period_start, period_end=period_end, currency=currency
+    )
+
+
+# -------- Job helpers and handlers (scheduler/worker wiring) ---------
+
+BILLING_AGGREGATE_JOB = "billing.aggregate_daily"
+BILLING_INVOICE_JOB = "billing.generate_monthly_invoice"
+
+
+def enqueue_aggregate_daily(
+    queue: JobQueue,
+    *,
+    tenant_id: str,
+    metric: str,
+    day_start: datetime,
+    delay_seconds: int = 0,
+) -> None:
+    payload = {
+        "tenant_id": tenant_id,
+        "metric": metric,
+        "day_start": day_start.astimezone(timezone.utc).isoformat(),
+    }
+    queue.enqueue(BILLING_AGGREGATE_JOB, payload, delay_seconds=delay_seconds)
+
+
+def enqueue_generate_monthly_invoice(
+    queue: JobQueue,
+    *,
+    tenant_id: str,
+    period_start: datetime,
+    period_end: datetime,
+    currency: str,
+    delay_seconds: int = 0,
+) -> None:
+    payload = {
+        "tenant_id": tenant_id,
+        "period_start": period_start.astimezone(timezone.utc).isoformat(),
+        "period_end": period_end.astimezone(timezone.utc).isoformat(),
+        "currency": currency,
+    }
+    queue.enqueue(BILLING_INVOICE_JOB, payload, delay_seconds=delay_seconds)
+
+
+def make_daily_aggregate_tick(
+    queue: JobQueue,
+    *,
+    tenant_id: str,
+    metric: str,
+    when: Optional[datetime] = None,
+):
+    """Return an async function that enqueues a daily aggregate job.
+
+    This is a simple helper for local/dev schedulers; it schedules an aggregate
+    for the UTC day of ``when`` (or now). Call repeatedly via a scheduler.
+    """
+
+    async def _tick():
+        ts = (when or datetime.now(timezone.utc)).astimezone(timezone.utc)
+        day_start = ts.replace(hour=0, minute=0, second=0, microsecond=0)
+        enqueue_aggregate_daily(queue, tenant_id=tenant_id, metric=metric, day_start=day_start)
+
+    return _tick
+
+
+def make_billing_job_handler(
+    *,
+    session_factory: "async_sessionmaker[AsyncSession]",
+    webhooks: WebhookService,
+) -> Callable[[Job], Awaitable[None]]:
+    """Create a worker handler that processes billing jobs and emits webhooks.
+
+    Supported jobs and their expected payloads:
+    - billing.aggregate_daily {tenant_id, metric, day_start: ISO8601}
+      → emits topic 'billing.usage_aggregated'
+    - billing.generate_monthly_invoice {tenant_id, period_start: ISO8601, period_end: ISO8601, currency}
+      → emits topic 'billing.invoice.created'
+    """
+
+    async def _maybe_commit(session: Any) -> None:
+        """Commit if the session exposes a commit method (await if coroutine).
+
+        This makes the handler resilient in tests/dev where a dummy session is used.
+        """
+        commit = getattr(session, "commit", None)
+        if callable(commit):
+            result = commit()
+            if inspect.isawaitable(result):
+                await result
+
+    async def _handler(job: Job) -> None:
+        name = job.name
+        data: Dict[str, Any] = job.payload or {}
+        if name == BILLING_AGGREGATE_JOB:
+            tenant_id = str(data.get("tenant_id"))
+            metric = str(data.get("metric"))
+            day_raw = data.get("day_start")
+            if not tenant_id or not metric or not day_raw:
+                return
+            day_start = datetime.fromisoformat(str(day_raw))
+            async with session_factory() as session:
+                svc = AsyncBillingService(session=session, tenant_id=tenant_id)
+                total = await svc.aggregate_daily(metric=metric, day_start=day_start)
+                await _maybe_commit(session)
+            webhooks.publish(
+                "billing.usage_aggregated",
+                {
+                    "tenant_id": tenant_id,
+                    "metric": metric,
+                    "day_start": day_start.astimezone(timezone.utc).isoformat(),
+                    "total": int(total),
+                },
+            )
+            return
+        if name == BILLING_INVOICE_JOB:
+            tenant_id = str(data.get("tenant_id"))
+            period_start_raw = data.get("period_start")
+            period_end_raw = data.get("period_end")
+            currency = str(data.get("currency"))
+            if not tenant_id or not period_start_raw or not period_end_raw or not currency:
+                return
+            period_start = datetime.fromisoformat(str(period_start_raw))
+            period_end = datetime.fromisoformat(str(period_end_raw))
+            async with session_factory() as session:
+                svc = AsyncBillingService(session=session, tenant_id=tenant_id)
+                invoice_id = await svc.generate_monthly_invoice(
+                    period_start=period_start, period_end=period_end, currency=currency
+                )
+                await _maybe_commit(session)
+            webhooks.publish(
+                "billing.invoice.created",
+                {
+                    "tenant_id": tenant_id,
+                    "invoice_id": invoice_id,
+                    "period_start": period_start.astimezone(timezone.utc).isoformat(),
+                    "period_end": period_end.astimezone(timezone.utc).isoformat(),
+                    "currency": currency,
+                },
+            )
+            return
+        # Ignore unrelated jobs
+
+    return _handler
+
+
+def add_billing_jobs(
+    *,
+    scheduler: InMemoryScheduler,
+    queue: JobQueue,
+    jobs: list[dict],
+) -> None:
+    """Register simple interval-based billing job enqueuers.
+
+    jobs: list of dicts with shape {"name": "aggregate", "tenant_id": ..., "metric": ..., "interval_seconds": 86400}
+          or {"name": "invoice", "tenant_id": ..., "period_start": ISO, "period_end": ISO, "currency": ..., "interval_seconds": 2592000}
+    """
+
+    for j in jobs:
+        name = j.get("name")
+        interval = int(j.get("interval_seconds", 86400))
+        if name == "aggregate":
+            tenant_id = j["tenant_id"]
+            metric = j["metric"]
+
+            async def _tick_fn(tid=tenant_id, m=metric):
+                # Enqueue for the current UTC day
+                now = datetime.now(timezone.utc)
+                day_start = now.replace(hour=0, minute=0, second=0, microsecond=0)
+                enqueue_aggregate_daily(queue, tenant_id=tid, metric=m, day_start=day_start)
+
+            scheduler.add_task(f"billing.aggregate.{tenant_id}.{metric}", interval, _tick_fn)
+        elif name == "invoice":
+            tenant_id = j["tenant_id"]
+            currency = j["currency"]
+            pstart = datetime.fromisoformat(j["period_start"]).astimezone(timezone.utc)
+            pend = datetime.fromisoformat(j["period_end"]).astimezone(timezone.utc)
+
+            async def _tick_inv(tid=tenant_id, cs=currency, ps=pstart, pe=pend):
+                enqueue_generate_monthly_invoice(
+                    queue, tenant_id=tid, period_start=ps, period_end=pe, currency=cs
+                )
+
+            scheduler.add_task(f"billing.invoice.{tenant_id}", interval, _tick_inv)

svc_infra/billing/models.py

@@ -0,0 +1,131 @@
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Optional
+
+from sqlalchemy import JSON, DateTime, Index, Numeric, String, UniqueConstraint, text
+from sqlalchemy.orm import Mapped, mapped_column
+
+from svc_infra.db.sql.base import ModelBase
+
+TENANT_ID_LEN = 64
+
+
+class UsageEvent(ModelBase):
+    __tablename__ = "billing_usage_events"
+
+    id: Mapped[str] = mapped_column(String(64), primary_key=True)
+    tenant_id: Mapped[str] = mapped_column(String(TENANT_ID_LEN), index=True, nullable=False)
+    metric: Mapped[str] = mapped_column(String(64), index=True, nullable=False)
+    amount: Mapped[int] = mapped_column(Numeric(18, 0), nullable=False)
+    at_ts: Mapped[datetime] = mapped_column(DateTime(timezone=True), nullable=False)
+    idempotency_key: Mapped[str] = mapped_column(String(128), nullable=False)
+    metadata_json: Mapped[dict] = mapped_column(JSON, default=dict)
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), server_default=text("CURRENT_TIMESTAMP"), nullable=False
+    )
+
+    __table_args__ = (
+        UniqueConstraint("tenant_id", "metric", "idempotency_key", name="uq_usage_idem"),
+        Index("ix_usage_tenant_metric_ts", "tenant_id", "metric", "at_ts"),
+    )
+
+
+class UsageAggregate(ModelBase):
+    __tablename__ = "billing_usage_aggregates"
+
+    id: Mapped[str] = mapped_column(String(64), primary_key=True)
+    tenant_id: Mapped[str] = mapped_column(String(TENANT_ID_LEN), index=True, nullable=False)
+    metric: Mapped[str] = mapped_column(String(64), index=True, nullable=False)
+    period_start: Mapped[datetime] = mapped_column(DateTime(timezone=True), nullable=False)
+    granularity: Mapped[str] = mapped_column(String(8), nullable=False)  # hour|day|month
+    total: Mapped[int] = mapped_column(Numeric(18, 0), nullable=False)
+    updated_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), server_default=text("CURRENT_TIMESTAMP"), nullable=False
+    )
+
+    __table_args__ = (
+        UniqueConstraint("tenant_id", "metric", "period_start", "granularity", name="uq_usage_agg"),
+    )
+
+
+class Plan(ModelBase):
+    __tablename__ = "billing_plans"
+
+    id: Mapped[str] = mapped_column(String(64), primary_key=True)
+    key: Mapped[str] = mapped_column(String(64), unique=True, index=True, nullable=False)
+    name: Mapped[str] = mapped_column(String(128), nullable=False)
+    description: Mapped[Optional[str]] = mapped_column(String(255))
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), server_default=text("CURRENT_TIMESTAMP"), nullable=False
+    )
+
+
+class PlanEntitlement(ModelBase):
+    __tablename__ = "billing_plan_entitlements"
+
+    id: Mapped[str] = mapped_column(String(64), primary_key=True)
+    plan_id: Mapped[str] = mapped_column(String(64), index=True, nullable=False)
+    key: Mapped[str] = mapped_column(String(64), nullable=False)
+    limit_per_window: Mapped[int] = mapped_column(Numeric(18, 0), nullable=False)
+    window: Mapped[str] = mapped_column(String(8), nullable=False)  # day|month
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), server_default=text("CURRENT_TIMESTAMP"), nullable=False
+    )
+
+
+class Subscription(ModelBase):
+    __tablename__ = "billing_subscriptions"
+
+    id: Mapped[str] = mapped_column(String(64), primary_key=True)
+    tenant_id: Mapped[str] = mapped_column(String(TENANT_ID_LEN), index=True, nullable=False)
+    plan_id: Mapped[str] = mapped_column(String(64), index=True, nullable=False)
+    effective_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), nullable=False)
+    ended_at: Mapped[Optional[datetime]] = mapped_column(DateTime(timezone=True))
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), server_default=text("CURRENT_TIMESTAMP"), nullable=False
+    )
+
+
+class Price(ModelBase):
+    __tablename__ = "billing_prices"
+
+    id: Mapped[str] = mapped_column(String(64), primary_key=True)
+    key: Mapped[str] = mapped_column(String(64), unique=True, index=True, nullable=False)
+    currency: Mapped[str] = mapped_column(String(8), nullable=False)
+    unit_amount: Mapped[int] = mapped_column(Numeric(18, 0), nullable=False)  # minor units
+    metric: Mapped[Optional[str]] = mapped_column(String(64))  # null for fixed recurring
+    recurring_interval: Mapped[Optional[str]] = mapped_column(String(8))  # month|year
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), server_default=text("CURRENT_TIMESTAMP"), nullable=False
+    )
+
+
+class Invoice(ModelBase):
+    __tablename__ = "billing_invoices"
+
+    id: Mapped[str] = mapped_column(String(64), primary_key=True)
+    tenant_id: Mapped[str] = mapped_column(String(TENANT_ID_LEN), index=True, nullable=False)
+    period_start: Mapped[datetime] = mapped_column(DateTime(timezone=True), nullable=False)
+    period_end: Mapped[datetime] = mapped_column(DateTime(timezone=True), nullable=False)
+    status: Mapped[str] = mapped_column(String(16), index=True, nullable=False)
+    total_amount: Mapped[int] = mapped_column(Numeric(18, 0), nullable=False)
+    currency: Mapped[str] = mapped_column(String(8), nullable=False)
+    provider_invoice_id: Mapped[Optional[str]] = mapped_column(String(128), index=True)
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), server_default=text("CURRENT_TIMESTAMP"), nullable=False
+    )
+
+
+class InvoiceLine(ModelBase):
+    __tablename__ = "billing_invoice_lines"
+
+    id: Mapped[str] = mapped_column(String(64), primary_key=True)
+    invoice_id: Mapped[str] = mapped_column(String(64), index=True, nullable=False)
+    price_id: Mapped[Optional[str]] = mapped_column(String(64), index=True)
+    metric: Mapped[Optional[str]] = mapped_column(String(64))
+    quantity: Mapped[int] = mapped_column(Numeric(18, 0), nullable=False)
+    amount: Mapped[int] = mapped_column(Numeric(18, 0), nullable=False)
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), server_default=text("CURRENT_TIMESTAMP"), nullable=False
+    )

svc_infra/billing/quotas.py

@@ -0,0 +1,101 @@
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from typing import Annotated, Optional
+
+from fastapi import Depends, HTTPException, status
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from svc_infra.api.fastapi.db.sql.session import SqlSessionDep
+from svc_infra.api.fastapi.tenancy.context import TenantId
+
+from .models import PlanEntitlement, Subscription, UsageAggregate
+
+
+async def _current_subscription(session: AsyncSession, tenant_id: str) -> Optional[Subscription]:
+    now = datetime.now(tz=timezone.utc)
+    row = (
+        (
+            await session.execute(
+                select(Subscription)
+                .where(Subscription.tenant_id == tenant_id)
+                .order_by(Subscription.effective_at.desc())
+            )
+        )
+        .scalars()
+        .first()
+    )
+    if row is None:
+        return None
+    # basic check: if ended_at is set and in the past, treat as inactive
+    if row.ended_at is not None and row.ended_at <= now:
+        return None
+    return row
+
+
+def require_quota(metric: str, *, window: str = "day", soft: bool = True):
+    async def _dep(tenant_id: TenantId, session: SqlSessionDep) -> None:
+        sub = await _current_subscription(session, tenant_id)
+        if sub is None:
+            # no subscription → allow (unlimited) by default
+            return
+        ent = (
+            (
+                await session.execute(
+                    select(PlanEntitlement).where(
+                        PlanEntitlement.plan_id == sub.plan_id,
+                        PlanEntitlement.key == metric,
+                        PlanEntitlement.window == window,
+                    )
+                )
+            )
+            .scalars()
+            .first()
+        )
+        if ent is None:
+            # no entitlement → unlimited
+            return
+        # compute current window start
+        now = datetime.now(tz=timezone.utc)
+        if window == "day":
+            period_start = now.replace(hour=0, minute=0, second=0, microsecond=0)
+            granularity = "day"
+        elif window == "month":
+            period_start = now.replace(day=1, hour=0, minute=0, second=0, microsecond=0)
+            granularity = "month"  # we only aggregate per day, but future-proof
+        else:
+            period_start = now.replace(hour=0, minute=0, second=0, microsecond=0)
+            granularity = "day"
+
+        used_row = (
+            (
+                await session.execute(
+                    select(UsageAggregate).where(
+                        UsageAggregate.tenant_id == tenant_id,
+                        UsageAggregate.metric == metric,
+                        UsageAggregate.granularity == granularity,  # v1 daily baseline
+                        UsageAggregate.period_start == period_start,
+                    )
+                )
+            )
+            .scalars()
+            .first()
+        )
+        used = int(used_row.total) if used_row else 0
+        limit_ = int(ent.limit_per_window)
+        if used >= limit_:
+            if soft:
+                # allow but signal overage via header later (TODO: add header hook)
+                return
+            raise HTTPException(
+                status_code=status.HTTP_429_TOO_MANY_REQUESTS,
+                detail=f"Quota exceeded for {metric} in {window} window",
+            )
+
+    return _dep
+
+
+QuotaDep = Annotated[None, Depends(require_quota)]
+
+__all__ = ["require_quota"]

svc_infra/billing/schemas.py

@@ -0,0 +1,33 @@
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Optional
+
+from pydantic import BaseModel, Field, conint
+
+
+class UsageIn(BaseModel):
+    metric: str = Field(..., min_length=1, max_length=64)
+    amount: conint(ge=0) = Field(..., description="Non-negative amount for the metric")
+    at: Optional[datetime] = Field(
+        default=None, description="Event timestamp (UTC). Defaults to server time if omitted."
+    )
+    idempotency_key: str = Field(..., min_length=1, max_length=128)
+    metadata: dict = Field(default_factory=dict)
+
+
+class UsageAckOut(BaseModel):
+    id: str
+    accepted: bool = True
+
+
+class UsageAggregateRow(BaseModel):
+    period_start: datetime
+    granularity: str
+    metric: str
+    total: int
+
+
+class UsageAggregatesOut(BaseModel):
+    items: list[UsageAggregateRow] = Field(default_factory=list)
+    next_cursor: Optional[str] = None