subscribeflow 1.8.0__tar.gz → 1.8.2__tar.gz

{subscribeflow-1.8.0 → subscribeflow-1.8.2}/.gitignore

@@ -1,5 +1,4 @@
 # Dependencies
-uv.lock
 
 # Python
 __pycache__/

{subscribeflow-1.8.0 → subscribeflow-1.8.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: subscribeflow
-Version: 1.8.0
+Version: 1.8.2
 Summary: Python SDK for SubscribeFlow API - Email subscription management
 Project-URL: Homepage, https://subscribeflow.net
 Project-URL: Documentation, https://docs.subscribeflow.net/guides/sdk-setup
@@ -30,7 +30,7 @@ Requires-Dist: pytest-httpx>=0.30.0; extra == 'dev'
 Requires-Dist: pytest>=8.0.0; extra == 'dev'
 Requires-Dist: ruff>=0.6.0; extra == 'dev'
 Provides-Extra: mcp
-Requires-Dist: mcp>=1.0.0; extra == 'mcp'
+Requires-Dist: mcp>=2.2.0; extra == 'mcp'
 Description-Content-Type: text/markdown
 
 # subscribeflow
@@ -116,6 +116,7 @@ The client uses an async context manager to manage the HTTP connection. This ens
 import asyncio
 from subscribeflow import SubscribeFlowClient
 
+
 async def main():
     async with SubscribeFlowClient(api_key="sf_live_xxx") as client:
         # Create a subscriber with tags and metadata
@@ -126,6 +127,7 @@ async def main():
         )
         print(f"Created subscriber: {subscriber.id}")
 
+
 asyncio.run(main())
 ```
 
@@ -410,11 +412,9 @@ The client accepts configuration options when initialized. Only the `api_key` is
 client = SubscribeFlowClient(
     # Required: Your API key (starts with sf_live_ or sf_test_)
     api_key="sf_live_xxx",
-
     # Optional: API base URL (default: https://api.subscribeflow.net)
     # The SDK appends /api/v1/... automatically
     base_url="https://api.subscribeflow.net",
-
     # Optional: Request timeout in seconds (default: 30)
     timeout=30.0,
 )
@@ -483,6 +483,7 @@ This SDK is fully typed and works with mypy, pyright, and other type checkers ou
 ```python
 from subscribeflow import SubscribeFlowClient, Subscriber, Tag
 
+
 async def get_active_subscribers(client: SubscribeFlowClient) -> list[Subscriber]:
     result = await client.subscribers.list(status="active")
     return result.items

{subscribeflow-1.8.0 → subscribeflow-1.8.2}/README.md

@@ -81,6 +81,7 @@ The client uses an async context manager to manage the HTTP connection. This ens
 import asyncio
 from subscribeflow import SubscribeFlowClient
 
+
 async def main():
     async with SubscribeFlowClient(api_key="sf_live_xxx") as client:
         # Create a subscriber with tags and metadata
@@ -91,6 +92,7 @@ async def main():
         )
         print(f"Created subscriber: {subscriber.id}")
 
+
 asyncio.run(main())
 ```
 
@@ -375,11 +377,9 @@ The client accepts configuration options when initialized. Only the `api_key` is
 client = SubscribeFlowClient(
     # Required: Your API key (starts with sf_live_ or sf_test_)
     api_key="sf_live_xxx",
-
     # Optional: API base URL (default: https://api.subscribeflow.net)
     # The SDK appends /api/v1/... automatically
     base_url="https://api.subscribeflow.net",
-
     # Optional: Request timeout in seconds (default: 30)
     timeout=30.0,
 )
@@ -448,6 +448,7 @@ This SDK is fully typed and works with mypy, pyright, and other type checkers ou
 ```python
 from subscribeflow import SubscribeFlowClient, Subscriber, Tag
 
+
 async def get_active_subscribers(client: SubscribeFlowClient) -> list[Subscriber]:
     result = await client.subscribers.list(status="active")
     return result.items

{subscribeflow-1.8.0 → subscribeflow-1.8.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "subscribeflow"
-version = "1.8.0"
+version = "1.8.2"
 description = "Python SDK for SubscribeFlow API - Email subscription management"
 readme = "README.md"
 license = { text = "MIT" }
@@ -34,11 +34,16 @@ dev = [
     "ruff>=0.6.0",
 ]
 mcp = [
-    "mcp>=1.0.0",
+    # 2.2.0 is the floor, not 1.x: the server uses the constructor-based
+    # `Server(name, on_list_tools=..., on_call_tool=...)` API introduced in
+    # mcp 2.x, which does not exist in 1.x — an install resolving below this
+    # crashes at import.
+    "mcp>=2.2.0",
 ]
 
 [project.scripts]
 subscribeflow-mcp = "subscribeflow.mcp.server:main"
+subscribeflow-mcp-http = "subscribeflow.mcp.server:main_http"
 
 [project.urls]
 Homepage = "https://subscribeflow.net"

{subscribeflow-1.8.0 → subscribeflow-1.8.2}/src/subscribeflow/__init__.py

@@ -47,7 +47,7 @@ from subscribeflow.models import (
     WebhookEndpoint,
 )
 
-__version__ = "1.7.0"
+__version__ = "1.8.1"
 
 __all__ = [
     # Client

{subscribeflow-1.8.0 → subscribeflow-1.8.2}/src/subscribeflow/client.py

@@ -1881,6 +1881,11 @@ class SubscribeFlowClient:
         Raises:
             SubscribeFlowError: On API errors
         """
+        # The `json` parameter above shadows the module-level `import json` for the
+        # rest of this method's scope, same as in `_do_request`. This method never
+        # references `json.<anything>` directly, so it's safe today — but keep it
+        # that way: don't add error handling here that touches `json.JSONDecodeError`
+        # without renaming the parameter first (see TF-774).
         if self._client is None:
             # Create a one-off client if not using context manager
             async with httpx.AsyncClient(
@@ -1918,7 +1923,10 @@ class SubscribeFlowClient:
         # Handle errors
         try:
             error_data = response.json()
-        except (json.JSONDecodeError, ValueError):
+        except ValueError:
+            # json.JSONDecodeError is a ValueError subclass; catching it by name here
+            # would resolve to the `json` parameter (a dict|None) shadowing the module
+            # import, not the module itself. See TF-774.
             error_data = {"detail": response.text or "Unknown error"}
 
         raise SubscribeFlowError.from_response(error_data, response.status_code)

{subscribeflow-1.8.0 → subscribeflow-1.8.2}/src/subscribeflow/mcp/server.py

@@ -13,11 +13,25 @@ from __future__ import annotations
 import asyncio
 import logging
 import os
+from contextvars import ContextVar
 from typing import Any
 
+import uvicorn
 from mcp.server import Server
+from mcp.server.context import ServerRequestContext
 from mcp.server.stdio import stdio_server
-from mcp.types import TextContent, Tool
+from mcp.server.transport_security import TransportSecuritySettings
+from mcp.shared.exceptions import MCPError
+from mcp.types import (
+    INVALID_REQUEST,
+    CallToolRequestParams,
+    CallToolResult,
+    ListToolsResult,
+    PaginatedRequestParams,
+    TextContent,
+)
+from starlette.responses import JSONResponse
+from starlette.types import Receive, Scope, Send
 
 from subscribeflow import SubscribeFlowClient
 from subscribeflow.exceptions import (
@@ -34,8 +48,9 @@ from subscribeflow.mcp.tools import get_all_tools
 
 logger = logging.getLogger(__name__)
 
-# Server instance
-server = Server("subscribeflow")
+# Server instance is constructed after _handle_list_tools/_handle_call_tool
+# are defined (mcp 2.x registers handlers via constructor kwargs, not
+# decorators). See the bottom of this section.
 
 # Lazy-initialized client
 _client: SubscribeFlowClient | None = None
@@ -44,6 +59,13 @@ _client: SubscribeFlowClient | None = None
 _tier_verified: bool | None = None
 _tier_lock: asyncio.Lock | None = None
 
+# Per-request API key for the Streamable HTTP transport (see create_http_app()
+# in this module). Unset (None) when running as the stdio entry point, where
+# SUBSCRIBEFLOW_API_KEY is used instead. A ContextVar rather than a function
+# parameter because _handle_call_tool's signature is dictated by mcp.server.Server
+# (on_call_tool's fixed (ctx, params) shape) and cannot carry transport-level data.
+_request_api_key: ContextVar[str | None] = ContextVar("request_api_key", default=None)
+
 # Paid tiers that are allowed to use MCP
 _PAID_TIERS = {"starter", "professional", "pro"}
 
@@ -62,13 +84,25 @@ _TIER_CHECK_FAILED_MESSAGE = (
 def _get_client() -> SubscribeFlowClient:
     """Get or create the SubscribeFlow client.
 
+    In HTTP mode (``_request_api_key`` set), builds a fresh client scoped to
+    the current request's API key on every call — concurrent requests from
+    different users must never share a client. In stdio mode, falls back to
+    the existing process-wide singleton built from SUBSCRIBEFLOW_API_KEY,
+    where one process always serves exactly one user.
+
     Returns:
         Configured SubscribeFlowClient instance.
 
     Raises:
-        ValueError: If SUBSCRIBEFLOW_API_KEY is not set.
+        ValueError: If SUBSCRIBEFLOW_API_KEY is required but not set (stdio mode only).
     """
     global _client
+
+    request_key = _request_api_key.get()
+    if request_key is not None:
+        base_url = os.environ.get("SUBSCRIBEFLOW_BASE_URL", "https://api.subscribeflow.net")
+        return SubscribeFlowClient(api_key=request_key, base_url=base_url)
+
     if _client is None:
         api_key = os.environ.get("SUBSCRIBEFLOW_API_KEY")
         if not api_key:
@@ -176,20 +210,47 @@ def _format_delivery_stats(stats: Any) -> str:
     )
 
 
-@server.list_tools()
-async def list_tools() -> list[Tool]:
-    """Return all available MCP tools."""
-    return get_all_tools()
+async def _handle_list_tools(
+    ctx: ServerRequestContext[None], params: PaginatedRequestParams | None
+) -> ListToolsResult:
+    """Return all available MCP tools.
+
+    In HTTP mode (``_request_api_key`` set), the key is validated here before
+    the catalog is returned. Unlike ``_handle_call_tool``, this handler never
+    calls ``_get_client()``'s underlying API otherwise — so, without this
+    check, ``_AuthenticatedMCPApp``'s fail-fast (rejecting only a *missing*
+    header, not an invalid one) would be the only gate, and anyone with a
+    non-empty but bogus Authorization header could enumerate every tool's
+    name, description and input schema for free. Deliberately not routed
+    through ``_check_tier``: tier gating blocks *calling* tools, but browsing
+    the catalog with a real key has always been available regardless of tier
+    (stdio mode included) and should stay that way.
+    """
+    if _request_api_key.get() is not None:
+        try:
+            await _get_client().billing.get_subscription()
+        except AuthenticationError as e:
+            raise MCPError(code=INVALID_REQUEST, message="Authentication failed") from e
+    return ListToolsResult(tools=get_all_tools())
 
 
 async def _check_tier(client: SubscribeFlowClient) -> str | None:
     """Check if the organization's tier allows MCP access.
 
+    In HTTP mode (``_request_api_key`` set), the result is never cached
+    across requests — a cache keyed by nothing would leak one organization's
+    tier status into the next request that happens to run on this process.
+    Stdio mode keeps its existing process-lifetime cache, safe because one
+    process always serves exactly one organization.
+
     Returns:
         Error message string if blocked, None if allowed.
     """
     global _tier_verified, _tier_lock
 
+    if _request_api_key.get() is not None:
+        return await _check_tier_uncached(client)
+
     # Fast path: already verified
     if _tier_verified is True:
         return None
@@ -205,67 +266,84 @@ async def _check_tier(client: SubscribeFlowClient) -> str | None:
         if _tier_verified is not None:
             return _TIER_ERROR_MESSAGE if _tier_verified is False else None
 
-        try:
-            sub = await client.billing.get_subscription()
-            tier = (sub.tier or "").lower()
-            _tier_verified = tier in _PAID_TIERS
-            if not _tier_verified:
-                logger.info(
-                    "MCP access blocked for tier '%s'",
-                    tier,
-                )
-                return _TIER_ERROR_MESSAGE
-            return None
-        except Exception:
-            logger.warning(
-                "Tier verification failed — blocking MCP access",
-                exc_info=True,
-            )
-            # Fail closed: don't cache, so next call retries
-            return _TIER_CHECK_FAILED_MESSAGE
+        result = await _check_tier_uncached(client)
+        # Only cache successful checks or tier-blocked checks, not transient failures
+        if result is None or result == _TIER_ERROR_MESSAGE:
+            _tier_verified = result is None
+        return result
+
 
+async def _check_tier_uncached(client: SubscribeFlowClient) -> str | None:
+    """Run the tier check against the API with no caching.
 
-@server.call_tool()
-async def call_tool(name: str, arguments: dict[str, Any]) -> list[TextContent]:
+    Returns:
+        Error message string if blocked, None if allowed.
+    """
+    try:
+        sub = await client.billing.get_subscription()
+        tier = (sub.tier or "").lower()
+        if tier not in _PAID_TIERS:
+            logger.info("MCP access blocked for tier '%s'", tier)
+            return _TIER_ERROR_MESSAGE
+        return None
+    except Exception:
+        logger.warning(
+            "Tier verification failed — blocking MCP access",
+            exc_info=True,
+        )
+        # Fail closed: don't cache, so next call retries
+        return _TIER_CHECK_FAILED_MESSAGE
+
+
+async def _handle_call_tool(
+    ctx: ServerRequestContext[None], params: CallToolRequestParams
+) -> CallToolResult:
     """Handle tool calls from the LLM.
 
     Args:
-        name: Tool name to execute.
-        arguments: Tool arguments.
+        ctx: Server request context (unused).
+        params: Tool call parameters (name and arguments).
 
     Returns:
-        List of TextContent with the result.
+        CallToolResult wrapping the TextContent result.
 
     Raises:
         ValueError: If tool name is unknown.
     """
+    name = params.name
+    arguments = params.arguments or {}
     client = _get_client()
 
     # Lazy tier check with async lock to prevent race conditions
     tier_result = await _check_tier(client)
     if tier_result is not None:
-        return [TextContent(type="text", text=tier_result)]
+        return CallToolResult(content=[TextContent(type="text", text=tier_result)])
 
     try:
         result = await _execute_tool(client, name, arguments)
-        return [TextContent(type="text", text=result)]
+        return CallToolResult(content=[TextContent(type="text", text=result)])
     except AuthenticationError:
-        return [
-            TextContent(
-                type="text",
-                text="Authentication failed: the configured API key is invalid "
-                "or expired. Update SUBSCRIBEFLOW_API_KEY and restart.",
-            )
-        ]
+        return CallToolResult(
+            content=[
+                TextContent(
+                    type="text",
+                    text="Authentication failed: the configured API key is invalid "
+                    "or expired. Update SUBSCRIBEFLOW_API_KEY and restart.",
+                )
+            ]
+        )
     except AuthorizationError as e:
-        return [
-            TextContent(
-                type="text",
-                text=f"Permission denied: {e}. Check that your API key has the required scopes.",
-            )
-        ]
+        return CallToolResult(
+            content=[
+                TextContent(
+                    type="text",
+                    text=f"Permission denied: {e}. Check that your API key has the required "
+                    "scopes.",
+                )
+            ]
+        )
     except NotFoundError as e:
-        return [TextContent(type="text", text=f"Not found: {e}")]
+        return CallToolResult(content=[TextContent(type="text", text=f"Not found: {e}")])
     except ValidationError as e:
         detail = f"Validation error: {e}"
         if e.errors:
@@ -273,27 +351,33 @@ async def call_tool(name: str, arguments: dict[str, Any]) -> list[TextContent]:
                 f"{err.get('field', 'unknown')}: {err.get('message', str(err))}" for err in e.errors
             )
             detail += f"\nDetails: {fields}"
-        return [TextContent(type="text", text=detail)]
+        return CallToolResult(content=[TextContent(type="text", text=detail)])
     except ConflictError as e:
-        return [TextContent(type="text", text=f"Conflict: {e}")]
+        return CallToolResult(content=[TextContent(type="text", text=f"Conflict: {e}")])
     except LimitExceededError as e:
-        return [
-            TextContent(
-                type="text",
-                text=(
-                    f"Plan limit exceeded: {e.detail}\n"
-                    f"Limit: {e.limit} ({e.current}/{e.max_value})\n"
-                    f"Upgrade at: {e.upgrade_url}"
-                ),
-            )
-        ]
+        return CallToolResult(
+            content=[
+                TextContent(
+                    type="text",
+                    text=(
+                        f"Plan limit exceeded: {e.detail}\n"
+                        f"Limit: {e.limit} ({e.current}/{e.max_value})\n"
+                        f"Upgrade at: {e.upgrade_url}"
+                    ),
+                )
+            ]
+        )
     except RateLimitError as e:
-        return [TextContent(type="text", text=f"Rate limit exceeded: {e}")]
+        return CallToolResult(content=[TextContent(type="text", text=f"Rate limit exceeded: {e}")])
     except SubscribeFlowError as e:
-        return [TextContent(type="text", text=f"API error ({e.status}): {e}")]
+        return CallToolResult(
+            content=[TextContent(type="text", text=f"API error ({e.status}): {e}")]
+        )
     except Exception as e:
         logger.error("Unexpected error in MCP tool %s", name, exc_info=True)
-        return [TextContent(type="text", text=f"Unexpected error: {type(e).__name__}: {e}")]
+        return CallToolResult(
+            content=[TextContent(type="text", text=f"Unexpected error: {type(e).__name__}: {e}")]
+        )
 
 
 async def _execute_tool(client: SubscribeFlowClient, name: str, args: dict[str, Any]) -> str:
@@ -1021,6 +1105,9 @@ async def _execute_tool(client: SubscribeFlowClient, name: str, args: dict[str,
     raise ValueError(f"Unknown tool: {name}")
 
 
+server = Server("subscribeflow", on_list_tools=_handle_list_tools, on_call_tool=_handle_call_tool)
+
+
 def main() -> None:
     """Run the MCP server."""
 
@@ -1037,3 +1124,108 @@ def main() -> None:
 
 if __name__ == "__main__":
     main()
+
+
+def _extract_api_key(headers: list[tuple[bytes, bytes]]) -> str | None:
+    """Read an API key from the Authorization or X-API-Key header.
+
+    Args:
+        headers: Raw ASGI header pairs from the request scope.
+
+    Returns:
+        The extracted key, or None if neither header is present/valid.
+    """
+    decoded = {name.decode("latin-1").lower(): value.decode("latin-1") for name, value in headers}
+    x_api_key = decoded.get("x-api-key")
+    if x_api_key:
+        return x_api_key
+    authorization = decoded.get("authorization")
+    if authorization and authorization.startswith("Bearer "):
+        return authorization[len("Bearer ") :]
+    return None
+
+
+class _AuthenticatedMCPApp:
+    """Wraps the Streamable HTTP app (from Server.streamable_http_app()) with
+    API-key extraction.
+
+    Sets `_request_api_key` before delegating, so `_get_client()` builds a
+    client scoped to this request. Performs no validation of the key itself
+    — that happens naturally the first time the request-scoped client calls
+    the real API. A completely missing header is the one case rejected here,
+    to avoid starting an MCP request for a call that can never succeed.
+    """
+
+    def __init__(self, app: Any) -> None:
+        self._app = app
+
+    async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
+        if scope["type"] != "http":
+            # Non-HTTP scopes (in particular "lifespan") must reach the inner
+            # app unchanged — Server.streamable_http_app()'s own lifespan is
+            # what starts/stops its StreamableHTTPSessionManager.
+            await self._app(scope, receive, send)
+            return
+
+        api_key = _extract_api_key(scope["headers"])
+        if api_key is None:
+            response = JSONResponse(
+                {"error": "API key required. Use X-API-Key or Authorization: Bearer <api_key>"},
+                status_code=401,
+            )
+            await response(scope, receive, send)
+            return
+
+        token = _request_api_key.set(api_key)
+        try:
+            await self._app(scope, receive, send)
+        finally:
+            _request_api_key.reset(token)
+
+
+def create_http_app() -> _AuthenticatedMCPApp:
+    """Build the Streamable HTTP ASGI app for the `mcp` Fly process group.
+
+    Stateless: subscribeflow-api's reverse proxy may reach this process
+    group across restarts/deploys with no client-visible session to lose,
+    and no in-memory state needs to survive a request (see the spec's
+    "Transport" section).
+
+    DNS-rebinding protection is explicitly disabled: this server is never
+    reachable except via subscribeflow-api's reverse proxy over Fly's
+    internal 6PN network (never publicly routable — see fly.toml). The
+    default protection defends browsers against a locally-bound dev server
+    being reached through a rebound DNS name; that threat model doesn't
+    apply to a private, internal server-to-server hop, and the default
+    allowed_hosts (127.0.0.1/localhost only) would reject every real
+    request's Host header, which is set by the reverse proxy's upstream
+    URL, not localhost.
+    """
+    mcp_app = server.streamable_http_app(
+        stateless_http=True,
+        streamable_http_path="/",
+        transport_security=TransportSecuritySettings(enable_dns_rebinding_protection=False),
+    )
+    return _AuthenticatedMCPApp(mcp_app)
+
+
+def main_http() -> None:
+    """Run the MCP server over Streamable HTTP (the `mcp` Fly process group).
+
+    Binds `::` rather than `0.0.0.0`. Fly's private 6PN network is IPv6-only
+    and `<group>.process.<app>.internal` resolves to AAAA records exclusively,
+    so the only caller this server has — subscribeflow-api's /mcp reverse proxy
+    — reaches it over IPv6. A `0.0.0.0` listener refuses that connection
+    outright.
+
+    The resulting socket is IPv6-*only*, not dual-stack: this is uvicorn's
+    single-process path, which hands host/port to `loop.create_server()`, and
+    asyncio explicitly sets IPV6_V6ONLY=1 there regardless of the kernel's
+    dual-stack default. That is correct for this process — it has no IPv4
+    caller — but it is why `HOST` stays overridable: anything that does need to
+    reach this server over IPv4 (a local run, a future sidecar) must set
+    `HOST=0.0.0.0` rather than rely on `::` covering both.
+    """
+    port = int(os.environ.get("PORT", "8001"))
+    host = os.environ.get("HOST", "::")
+    uvicorn.run(create_http_app(), host=host, port=port)

{subscribeflow-1.8.0 → subscribeflow-1.8.2}/src/subscribeflow/models.py

@@ -53,6 +53,13 @@ class Tag(BaseModel):
     category: str | None = Field(default=None, description="Category for grouping tags")
     external_topic_id: str | None = Field(default=None, description="External provider topic ID")
     is_public: bool = Field(default=True, description="Whether visible in Preference Center")
+    approval_status: str = Field(
+        default="approved",
+        description="Moderation status: 'approved' or 'pending' (subscriber-proposed)",
+    )
+    created_by_subscriber_id: str | None = Field(
+        default=None, description="Set when the tag was proposed by a subscriber"
+    )
     subscriber_count: int = Field(default=0, description="Number of active subscribers")
     created_at: datetime = Field(description="Creation timestamp")
     updated_at: datetime = Field(description="Last update timestamp")