foldset 0.1.0__tar.gz

foldset-0.1.0/.gitignore

@@ -0,0 +1,40 @@
+# Dependencies
+node_modules
+.pnpm-store
+
+# Build outputs
+dist
+# TODO: Remove these exceptions once packages are published to npm.
+# Currently committing dist/ because Vercel doesn't run prepare scripts
+# for git dependencies properly.
+!packages/typescript/nextjs/dist
+!packages/typescript/core/dist
+build
+.next
+out
+
+# Environment files
+.env
+.env.local
+.env.*.local
+
+# IDE
+.idea
+.vscode
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Debug logs
+npm-debug.log*
+pnpm-debug.log*
+
+# TypeScript
+*.tsbuildinfo
+
+# Misc
+*.log
+.cache

foldset-0.1.0/PKG-INFO

@@ -0,0 +1,21 @@
+Metadata-Version: 2.4
+Name: foldset
+Version: 0.1.0
+Summary: Core types and utilities for Foldset payment protection
+Project-URL: Homepage, https://foldset.com
+Project-URL: Documentation, https://docs.foldset.com
+Project-URL: Repository, https://github.com/foldset/sdks
+Author-email: Foldset <team@foldset.com>
+License-Expression: MIT
+Keywords: agents,ai,foldset,micropayments,stablecoin
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.28.0
+Requires-Dist: upstash-redis>=1.0.0
+Requires-Dist: x402[mechanisms]>=2.0.0

foldset-0.1.0/foldset/__init__.py

@@ -0,0 +1,172 @@
+from __future__ import annotations
+
+from .config import (
+    BotsManager,
+    CachedConfigManager,
+    FacilitatorManager,
+    HostConfigManager,
+    PaymentMethodsManager,
+    RestrictionsManager,
+    build_request_metadata,
+)
+from .handler import handle_request, handle_settlement
+from .health import HEALTH_PATH, build_health_response
+from .mcp import handle_mcp_request
+from .server import HttpServerManager
+from .store import create_redis_store, fetch_redis_credentials
+from .types import (
+    ConfigStore,
+    FoldsetOptions,
+    ProcessRequestResult,
+    RedisCredentials,
+    RequestAdapter,
+)
+
+_cached_core: WorkerCore | None = None
+
+
+class WorkerCore:
+    def __init__(
+        self,
+        store: ConfigStore,
+        api_key: str,
+        platform: str,
+        sdk_version: str,
+    ) -> None:
+        self.host_config = HostConfigManager(store)
+        self.restrictions = RestrictionsManager(store)
+        self.payment_methods = PaymentMethodsManager(store)
+        self.bots = BotsManager(store)
+        self.api_key = api_key
+        self.http_server = HttpServerManager(store)
+        self.platform = platform
+        self.sdk_version = sdk_version
+
+    @classmethod
+    async def from_options(cls, options: FoldsetOptions) -> WorkerCore:
+        global _cached_core
+        if _cached_core:
+            return _cached_core
+
+        credentials = options.redis_credentials or await fetch_redis_credentials(
+            options.api_key
+        )
+        store = create_redis_store(credentials)
+        _cached_core = cls(
+            store,
+            options.api_key,
+            options.platform or "unknown",
+            options.sdk_version or "unknown",
+        )
+        return _cached_core
+
+    async def process_request(self, adapter: RequestAdapter) -> ProcessRequestResult:
+        metadata = build_request_metadata()
+
+        if adapter.get_path() == HEALTH_PATH:
+            return ProcessRequestResult(
+                type="health-check",
+                metadata=metadata,
+                response=type(
+                    "HealthResponse",
+                    (),
+                    {
+                        "status": 200,
+                        "body": build_health_response(self.platform, self.sdk_version),
+                        "headers": {"Content-Type": "application/json"},
+                    },
+                )(),
+            )
+
+        host_config = await self.host_config.get()
+        mcp_endpoint = host_config.mcp_endpoint if host_config else None
+
+        if mcp_endpoint and adapter.get_path() == mcp_endpoint:
+            return await handle_mcp_request(self, adapter, mcp_endpoint, metadata)
+
+        return await handle_request(self, adapter, metadata)
+
+    async def process_settlement(
+        self,
+        adapter: RequestAdapter,
+        payment_payload,
+        payment_requirements,
+        upstream_status_code: int,
+        request_id: str,
+    ):
+        return await handle_settlement(
+            self,
+            adapter,
+            payment_payload,
+            payment_requirements,
+            upstream_status_code,
+            request_id,
+        )
+
+
+# Re-exports
+__all__ = [
+    "WorkerCore",
+    # Types
+    "ConfigStore",
+    "FoldsetOptions",
+    "ProcessRequestResult",
+    "RedisCredentials",
+    "RequestAdapter",
+    # Store
+    "create_redis_store",
+    "fetch_redis_credentials",
+    # Paywall
+    "generate_paywall_html",
+    # Routes
+    "build_routes_config",
+    "price_to_amount",
+    # Config managers
+    "BotsManager",
+    "CachedConfigManager",
+    "FacilitatorManager",
+    "HostConfigManager",
+    "PaymentMethodsManager",
+    "RestrictionsManager",
+    # Server
+    "HttpServerManager",
+    # MCP
+    "build_json_rpc_error",
+    "build_mcp_route_key",
+    "build_mcp_routes_config",
+    "get_mcp_list_payment_requirements",
+    "get_mcp_route_key",
+    "handle_mcp_request",
+    "is_mcp_list_method",
+    "parse_mcp_request",
+    # Telemetry
+    "build_event_payload",
+    "log_event",
+    "report_error",
+    "send_event",
+    # Handlers
+    "handle_request",
+    "handle_settlement",
+    "format_api_payment_error",
+    "format_web_payment_error",
+    # Health
+    "HEALTH_PATH",
+    "build_health_response",
+]
+
+# Lazy imports for __all__ items
+from .paywall import generate_paywall_html  # noqa: E402
+from .routes import build_routes_config, price_to_amount  # noqa: E402
+from .mcp import (  # noqa: E402
+    build_json_rpc_error,
+    build_mcp_route_key,
+    build_mcp_routes_config,
+    get_mcp_list_payment_requirements,
+    get_mcp_route_key,
+    is_mcp_list_method,
+    parse_mcp_request,
+)
+from .telemetry import build_event_payload, log_event, report_error, send_event  # noqa: E402
+from .handler import handle_payment_request  # noqa: E402
+from .api import format_api_payment_error  # noqa: E402
+from .web import format_web_payment_error  # noqa: E402

foldset-0.1.0/foldset/api.py

@@ -0,0 +1,36 @@
+from __future__ import annotations
+
+import json
+
+from .types import ApiRestriction, PaymentMethod, ProcessRequestResult
+
+
+def format_api_payment_error(
+    result: ProcessRequestResult,
+    restriction: ApiRestriction,
+    payment_methods: list[PaymentMethod],
+    terms_of_service_url: str | None = None,
+) -> None:
+    body: dict = {
+        "error": "payment_required",
+        "version": result.metadata.version,
+        "request_id": result.metadata.request_id,
+        "timestamp": result.metadata.timestamp,
+        "message": restriction.description,
+        "price": restriction.price,
+    }
+    if terms_of_service_url:
+        body["terms_of_service_url"] = terms_of_service_url
+    body["payment_methods"] = [
+        {
+            "network": pm.caip2_id,
+            "asset": pm.contract_address,
+            "decimals": pm.decimals,
+            "pay_to": pm.circle_wallet_address,
+            "chain": pm.chain_display_name,
+            "asset_name": pm.asset_display_name,
+        }
+        for pm in payment_methods
+    ]
+    result.response.body = json.dumps(body)
+    result.response.headers["Content-Type"] = "application/json"

foldset-0.1.0/foldset/config.py

@@ -0,0 +1,183 @@
+from __future__ import annotations
+
+import json
+import time
+import uuid
+from datetime import datetime, timezone
+from typing import Any
+
+from x402.http import FacilitatorConfig as X402FacilitatorConfig
+from x402.http import HTTPFacilitatorClient
+
+from .types import (
+    Bot,
+    ConfigStore,
+    FacilitatorConfig,
+    HostConfig,
+    PaymentMethod,
+    ProcessRequestResult,
+    RequestMetadata,
+    Restriction,
+    ApiRestriction,
+    McpRestriction,
+    WebRestriction,
+)
+
+from importlib.metadata import version as _pkg_version
+
+PACKAGE_VERSION = _pkg_version("foldset")
+CACHE_TTL_MS = 30_000
+API_BASE_URL = "https://api.foldset.com"
+
+
+def build_request_metadata() -> RequestMetadata:
+    return RequestMetadata(
+        version=PACKAGE_VERSION,
+        request_id=str(uuid.uuid4()),
+        timestamp=datetime.now(timezone.utc).isoformat(),
+    )
+
+
+def no_payment_required(metadata: RequestMetadata) -> ProcessRequestResult:
+    return ProcessRequestResult(type="no-payment-required", metadata=metadata)
+
+
+class CachedConfigManager[T]:
+    def __init__(self, config_store: ConfigStore, key: str, fallback: T) -> None:
+        self._config_store = config_store
+        self._key = key
+        self._fallback = fallback
+        self._cached: T = fallback
+        self._cache_timestamp: float = 0
+
+    def _is_cache_valid(self) -> bool:
+        return self._cache_timestamp > 0 and (time.time() * 1000 - self._cache_timestamp) < CACHE_TTL_MS
+
+    def _deserialize(self, raw: str) -> T:
+        return json.loads(raw)
+
+    async def get(self) -> T:
+        if self._is_cache_valid():
+            return self._cached
+        raw = await self._config_store.get(self._key)
+        self._cached = self._deserialize(raw) if raw else self._fallback
+        self._cache_timestamp = time.time() * 1000
+        return self._cached
+
+
+def _parse_restriction(data: dict[str, Any]) -> Restriction:
+    rtype = data.get("type")
+    if rtype == "web":
+        return WebRestriction(
+            description=data["description"],
+            price=data["price"],
+            scheme=data["scheme"],
+            path=data.get("path", ""),
+        )
+    elif rtype == "api":
+        return ApiRestriction(
+            description=data["description"],
+            price=data["price"],
+            scheme=data["scheme"],
+            path=data.get("path", ""),
+            http_method=data.get("httpMethod"),
+        )
+    elif rtype == "mcp":
+        return McpRestriction(
+            description=data["description"],
+            price=data["price"],
+            scheme=data["scheme"],
+            method=data.get("method", ""),
+            name=data.get("name", ""),
+        )
+    raise ValueError(f"Unknown restriction type: {rtype}")
+
+
+class HostConfigManager(CachedConfigManager[HostConfig | None]):
+    def __init__(self, store: ConfigStore) -> None:
+        super().__init__(store, "host-config", None)
+
+    def _deserialize(self, raw: str) -> HostConfig | None:
+        data = json.loads(raw)
+        return HostConfig(
+            host=data["host"],
+            api_protection_mode=data.get("apiProtectionMode", "bots"),
+            mcp_endpoint=data.get("mcpEndpoint"),
+            terms_of_service_url=data.get("termsOfServiceUrl"),
+        )
+
+
+class RestrictionsManager(CachedConfigManager[list[Restriction]]):
+    def __init__(self, store: ConfigStore) -> None:
+        super().__init__(store, "restrictions", [])
+
+    def _deserialize(self, raw: str) -> list[Restriction]:
+        data = json.loads(raw)
+        return [_parse_restriction(r) for r in data]
+
+
+class PaymentMethodsManager(CachedConfigManager[list[PaymentMethod]]):
+    def __init__(self, store: ConfigStore) -> None:
+        super().__init__(store, "payment-methods", [])
+
+    def _deserialize(self, raw: str) -> list[PaymentMethod]:
+        data = json.loads(raw)
+        return [
+            PaymentMethod(
+                caip2_id=pm["caip2_id"],
+                decimals=pm["decimals"],
+                contract_address=pm["contract_address"],
+                circle_wallet_address=pm["circle_wallet_address"],
+                chain_display_name=pm["chain_display_name"],
+                asset_display_name=pm["asset_display_name"],
+                extra=pm.get("extra"),
+            )
+            for pm in data
+        ]
+
+
+class BotsManager(CachedConfigManager[list[Bot]]):
+    def __init__(self, store: ConfigStore) -> None:
+        super().__init__(store, "bots", [])
+
+    def _deserialize(self, raw: str) -> list[Bot]:
+        data = json.loads(raw)
+        return [
+            Bot(
+                user_agent=b["user_agent"].lower(),
+                force_200=b.get("force_200", False),
+            )
+            for b in data
+        ]
+
+    async def match_bot(self, user_agent: str) -> Bot | None:
+        bots = await self.get()
+        ua = user_agent.lower()
+        for bot in bots:
+            if bot.user_agent in ua:
+                return bot
+        return None
+
+
+class FacilitatorManager(CachedConfigManager[HTTPFacilitatorClient | None]):
+    def __init__(self, store: ConfigStore) -> None:
+        super().__init__(store, "facilitator", None)
+
+    def _deserialize(self, raw: str) -> HTTPFacilitatorClient:
+        config = json.loads(raw)
+
+        has_auth_headers = (
+            config.get("verifyHeaders")
+            or config.get("settleHeaders")
+            or config.get("supportedHeaders")
+        )
+
+        facilitator_config: dict[str, Any] = {"url": config["url"]}
+        if has_auth_headers:
+            facilitator_config["create_headers"] = lambda: {
+                "verify": config.get("verifyHeaders") or {},
+                "settle": config.get("settleHeaders") or {},
+                "supported": config.get("supportedHeaders") or {},
+            }
+
+        return HTTPFacilitatorClient(facilitator_config)

foldset-0.1.0/foldset/handler.py

@@ -0,0 +1,125 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from x402.http import HTTPRequestContext, ProcessSettleResult
+
+from .api import format_api_payment_error
+from .config import no_payment_required
+from .telemetry import log_event
+from .types import ProcessRequestResult, RequestAdapter, RequestMetadata
+from .web import format_web_payment_error
+
+if TYPE_CHECKING:
+    from . import WorkerCore
+
+
+def _settlement_failure(reason: str, network: str) -> ProcessSettleResult:
+    return ProcessSettleResult(success=False, error_reason=reason)
+
+
+async def handle_payment_request(
+    core: WorkerCore,
+    adapter: RequestAdapter,
+    metadata: RequestMetadata,
+    path_override: str | None = None,
+) -> ProcessRequestResult:
+    http_server = await core.http_server.get()
+    if not http_server:
+        return no_payment_required(metadata)
+
+    path = path_override or adapter.get_path()
+
+    context = HTTPRequestContext(
+        adapter=adapter,
+        path=path,
+        method=adapter.get_method(),
+        payment_header=(
+            adapter.get_header("PAYMENT-SIGNATURE")
+            or adapter.get_header("X-PAYMENT")
+        ),
+    )
+
+    if not http_server.requires_payment(context):
+        return no_payment_required(metadata)
+
+    result = await http_server.process_http_request_with_restriction(context)
+    result.metadata = metadata
+
+    if result.type == "payment-error":
+        if result.restriction and result.restriction.price == 0:
+            await log_event(core, adapter, 200, metadata.request_id)
+            return no_payment_required(metadata)
+        await log_event(core, adapter, result.response.status if result.response else 402, metadata.request_id)
+
+    return result
+
+
+async def handle_request(
+    core: WorkerCore,
+    adapter: RequestAdapter,
+    metadata: RequestMetadata,
+) -> ProcessRequestResult:
+    user_agent = adapter.get_user_agent()
+    bot = await core.bots.match_bot(user_agent) if user_agent else None
+    host_config = await core.host_config.get()
+
+    should_check = bot or (host_config and host_config.api_protection_mode == "all")
+    if not should_check:
+        return no_payment_required(metadata)
+
+    result = await handle_payment_request(core, adapter, metadata)
+
+    if result.type != "payment-error":
+        return result
+
+    # Web restrictions are always bot-only
+    if result.restriction and result.restriction.type == "web" and not bot:
+        return no_payment_required(metadata)
+
+    payment_methods = await core.payment_methods.get()
+
+    if payment_methods and result.restriction:
+        if result.restriction.type == "api":
+            format_api_payment_error(
+                result, result.restriction, payment_methods, host_config.terms_of_service_url if host_config else None
+            )
+        elif result.restriction.type == "web":
+            format_web_payment_error(
+                result, result.restriction, payment_methods, adapter, host_config.terms_of_service_url if host_config else None
+            )
+
+    if bot and bot.force_200 and result.response:
+        result.response.status = 200
+
+    return result
+
+
+async def handle_settlement(
+    core: WorkerCore,
+    adapter: RequestAdapter,
+    payment_payload: Any,
+    payment_requirements: Any,
+    upstream_status_code: int,
+    request_id: str,
+) -> ProcessSettleResult:
+    http_server = await core.http_server.get()
+    if not http_server:
+        return _settlement_failure("Server not initialized", "")
+
+    if upstream_status_code >= 400:
+        await log_event(core, adapter, upstream_status_code, request_id)
+        return _settlement_failure("Upstream error", "")
+
+    result = await http_server.process_settlement(
+        payment_payload,
+        payment_requirements,
+    )
+
+    if result.success:
+        payment_response = result.headers.get("PAYMENT-RESPONSE")
+        await log_event(core, adapter, upstream_status_code, request_id, payment_response)
+    else:
+        await log_event(core, adapter, 402, request_id)
+
+    return result

foldset-0.1.0/foldset/health.py

@@ -0,0 +1,18 @@
+from __future__ import annotations
+
+import json
+from datetime import datetime, timezone
+
+from .config import PACKAGE_VERSION
+
+HEALTH_PATH = "/.well-known/foldset"
+
+
+def build_health_response(platform: str, sdk_version: str) -> str:
+    return json.dumps({
+        "status": "ok",
+        "core_version": PACKAGE_VERSION,
+        "sdk_version": sdk_version,
+        "platform": platform,
+        "timestamp": datetime.now(timezone.utc).isoformat(),
+    })