feat: add billing subscription plan api

api/services/billing_service.py

@@ -1,7 +1,7 @@
 import logging
 import os
 from collections.abc import Sequence
-from typing import Literal
+from typing import Literal, TypedDict
 
 import httpx
 from tenacity import retry, retry_if_exception_type, stop_before_delay, wait_fixed
@@ -16,6 +16,13 @@ from models import Account, TenantAccountJoin, TenantAccountRole
 logger = logging.getLogger(__name__)
 
 
+class SubscriptionPlan(TypedDict):
+    """Tenant subscriptionplan information."""
+
+    plan: str
+    expiration_date: int
+
+
 class BillingService:
     base_url = os.environ.get("BILLING_API_URL", "BILLING_API_URL")
     secret_key = os.environ.get("BILLING_API_SECRET_KEY", "BILLING_API_SECRET_KEY")
@@ -270,3 +277,34 @@ class BillingService:
     def sync_partner_tenants_bindings(cls, account_id: str, partner_key: str, click_id: str):
         payload = {"account_id": account_id, "click_id": click_id}
         return cls._send_request("PUT", f"/partners/{partner_key}/tenants", json=payload)
+
+    @classmethod
+    def get_plan_bulk(cls, tenant_ids: Sequence[str]) -> dict[str, SubscriptionPlan]:
+        """
+        Bulk fetch billing subscription plan via billing API.
+        Payload: {"tenant_ids": ["t1", "t2", ...]} (max 200 per request)
+        Returns:
+            Mapping of tenant_id -> {plan: str, expiration_date: int}
+        """
+        results: dict[str, SubscriptionPlan] = {}
+
+        chunk_size = 200
+        for i in range(0, len(tenant_ids), chunk_size):
+            chunk = tenant_ids[i : i + chunk_size]
+            resp = cls._send_request("POST", "/subscription/plan/batch", json={"tenant_ids": chunk})
+            data = resp.get("data", {})
+            for tenant_id, plan in data.items():
+                if isinstance(plan, dict) and "plan" in plan and "expiration_date" in plan:
+                    subscription_plan: SubscriptionPlan = {
+                        "plan": str(plan["plan"]),
+                        "expiration_date": int(plan["expiration_date"]),
+                    }
+                    results[tenant_id] = subscription_plan
+
+        return results
+    
+    @classmethod
+    def get_expired_subscription_cleanup_whitelist(cls) -> Sequence[str]:
+        resp = cls._send_request("GET", "/subscription/cleanup/whitelist")
+        data = resp.get("data", [])
+        return data