ffid-python-sdk 0.1.0__py3-none-any.whl

ffid_sdk/client.py

@@ -0,0 +1,394 @@
+"""
+FFID API Client
+
+FFID プラットフォームとの全API通信を担当するクライアント。
+TypeScript SDK の ``createFFIDClient`` に対応するサーバーサイド版。
+
+ブラウザの Cookie 認証ではなく、Bearer Token 認証を使用。
+
+Example:
+    ```python
+    from ffid_sdk import FFIDClient, FFIDConfig
+
+    client = FFIDClient(FFIDConfig(service_code="chatbot"))
+
+    # セッション検証
+    response = await client.get_session(token="eyJ...")
+    if response.is_success:
+        print(response.data.user.email)
+    ```
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from typing import Any, Dict, Optional
+
+import httpx
+
+from ffid_sdk.constants import (
+    AUTHORIZATION_HEADER,
+    BEARER_PREFIX,
+    DEFAULT_API_BASE_URL,
+    DEFAULT_MAX_RETRIES,
+    DEFAULT_RETRY_BACKOFF_FACTOR,
+    DEFAULT_TIMEOUT_SECONDS,
+    NO_CONTENT_STATUS,
+    REFRESH_ENDPOINT,
+    SDK_LOGGER_NAME,
+    SESSION_ENDPOINT,
+    SIGNOUT_ENDPOINT,
+    SUBSCRIPTIONS_CHECK_ENDPOINT,
+)
+from ffid_sdk.errors import FFIDErrorCode, FFIDNetworkError, FFIDSDKError
+from ffid_sdk.types import (
+    FFIDApiResponse,
+    FFIDConfig,
+    FFIDError,
+    FFIDSessionResponse,
+    FFIDSubscription,
+    FFIDTokenResponse,
+)
+
+logger = logging.getLogger(SDK_LOGGER_NAME)
+
+# デバッグログでマスクするセンシティブなキー（snake_case / camelCase）
+_SENSITIVE_KEYS = frozenset({
+    "access_token", "refresh_token", "accessToken", "refreshToken",
+    "authorization",
+})
+
+# ログ用マスクプレースホルダー（センシティブ値を置換する文字列）
+_MASK_PLACEHOLDER = "***"
+
+
+def _sanitize_for_log(data: Dict[str, Any]) -> Dict[str, Any]:
+    """ログ出力用にセンシティブデータをマスクした辞書を返す"""
+    if not isinstance(data, dict):
+        return data
+    result: Dict[str, Any] = {}
+    for key, value in data.items():
+        if key in _SENSITIVE_KEYS:
+            result[key] = _MASK_PLACEHOLDER
+        elif isinstance(value, dict):
+            result[key] = _sanitize_for_log(value)
+        elif isinstance(value, list):
+            result[key] = [
+                _sanitize_for_log(item) if isinstance(item, dict) else item
+                for item in value
+            ]
+        else:
+            result[key] = value
+    return result
+
+
+class FFIDClient:
+    """FFID API クライアント
+
+    FFID プラットフォームのAPIを呼び出すための非同期HTTPクライアント。
+    TypeScript SDK の ``createFFIDClient`` に対応。
+
+    Args:
+        config: SDK設定（``FFIDConfig`` インスタンス）
+
+    Raises:
+        FFIDValidationError: service_code が未設定の場合
+
+    Example:
+        ```python
+        client = FFIDClient(FFIDConfig(service_code="chatbot"))
+        response = await client.get_session(token)
+        ```
+    """
+
+    def __init__(self, config: FFIDConfig) -> None:
+        if not config.service_code or not config.service_code.strip():
+            from ffid_sdk.errors import FFIDValidationError
+
+            raise FFIDValidationError(
+                message="service_code が未設定です",
+                code=FFIDErrorCode.VALIDATION_ERROR,
+            )
+
+        self._config = config
+        self._base_url = config.api_base_url if config.api_base_url is not None else DEFAULT_API_BASE_URL
+        self._timeout = config.timeout_seconds if config.timeout_seconds is not None else DEFAULT_TIMEOUT_SECONDS
+        self._max_retries = config.max_retries if config.max_retries is not None else DEFAULT_MAX_RETRIES
+        self._backoff_factor = DEFAULT_RETRY_BACKOFF_FACTOR
+        self._service_code = config.service_code
+
+        if config.debug:
+            logging.getLogger(SDK_LOGGER_NAME).setLevel(logging.DEBUG)
+
+        logger.debug("FFIDClient initialized: base_url=%s, service_code=%s",
+                      self._base_url, self._service_code)
+
+    @property
+    def base_url(self) -> str:
+        """API ベースURL"""
+        return self._base_url
+
+    @property
+    def service_code(self) -> str:
+        """サービスコード"""
+        return self._service_code
+
+    # ------------------------------------------------------------------
+    # Internal HTTP helpers
+    # ------------------------------------------------------------------
+
+    def _build_headers(self, token: str) -> Dict[str, str]:
+        """認証ヘッダーを構築"""
+        return {
+            AUTHORIZATION_HEADER: f"{BEARER_PREFIX}{token}",
+            "Content-Type": "application/json",
+        }
+
+    async def _request(
+        self,
+        method: str,
+        endpoint: str,
+        token: Optional[str] = None,
+        *,
+        json_body: Optional[Dict[str, Any]] = None,
+        params: Optional[Dict[str, str]] = None,
+        headers_override: Optional[Dict[str, str]] = None,
+    ) -> httpx.Response:
+        """HTTP リクエストを実行（リトライ + 指数バックオフ付き）
+
+        Args:
+            method: HTTPメソッド（GET, POST等）
+            endpoint: APIエンドポイントパス
+            token: アクセストークン（headers_override未指定時に使用）
+            json_body: リクエストボディ（JSON）
+            params: クエリパラメータ
+            headers_override: カスタムヘッダー（認証ヘッダー不要なリクエスト用）
+
+        Raises:
+            FFIDNetworkError: 全リトライ失敗時
+        """
+        url = f"{self._base_url}{endpoint}"
+        headers = headers_override if headers_override is not None else self._build_headers(token or "")
+        last_error: Optional[Exception] = None
+
+        async with httpx.AsyncClient(timeout=self._timeout) as client:
+            for attempt in range(self._max_retries):
+                try:
+                    logger.debug("Request [attempt %d/%d]: %s %s",
+                                 attempt + 1, self._max_retries, method, url)
+
+                    response = await client.request(
+                        method=method,
+                        url=url,
+                        headers=headers,
+                        json=json_body,
+                        params=params,
+                    )
+                    return response
+
+                except httpx.TimeoutException as exc:
+                    last_error = exc
+                    logger.warning("Request timeout [attempt %d/%d]: %s %s",
+                                   attempt + 1, self._max_retries, method, url)
+                except httpx.ConnectError as exc:
+                    last_error = exc
+                    logger.warning("Connection error [attempt %d/%d]: %s %s",
+                                   attempt + 1, self._max_retries, method, url)
+
+                # 指数バックオフ（最後の試行後は待機不要）
+                if attempt < self._max_retries - 1:
+                    backoff_seconds = self._backoff_factor * (2 ** attempt)
+                    logger.debug("Retrying in %.1f seconds...", backoff_seconds)
+                    await asyncio.sleep(backoff_seconds)
+
+        raise FFIDNetworkError(
+            message="ネットワークエラーが発生しました。しばらく経ってから再度お試しください。",
+            details={"url": url, "error": str(last_error)},
+        )
+
+    async def _fetch_json(
+        self,
+        method: str,
+        endpoint: str,
+        token: Optional[str] = None,
+        *,
+        json_body: Optional[Dict[str, Any]] = None,
+        params: Optional[Dict[str, str]] = None,
+        headers_override: Optional[Dict[str, str]] = None,
+    ) -> Dict[str, Any]:
+        """JSON レスポンスを取得してパース
+
+        Returns:
+            パース済みJSONレスポンス
+
+        Raises:
+            FFIDNetworkError: ネットワークエラー
+            FFIDSDKError: パースエラー
+        """
+        response = await self._request(
+            method, endpoint, token,
+            json_body=json_body, params=params,
+            headers_override=headers_override,
+        )
+
+        if response.status_code == NO_CONTENT_STATUS:
+            return {}
+
+        try:
+            data: Dict[str, Any] = response.json()
+        except Exception as exc:
+            logger.error("Parse error: status=%d, error=%s", response.status_code, exc)
+            raise FFIDSDKError(
+                code=FFIDErrorCode.PARSE_ERROR,
+                message=f"サーバーから不正なレスポンスを受信しました (status: {response.status_code})",
+            ) from exc
+
+        logger.debug(
+            "Response: status=%d, data=%s",
+            response.status_code,
+            _sanitize_for_log(data),
+        )
+
+        if response.status_code >= 400:
+            error_data = data.get("error", {})
+            raise FFIDSDKError(
+                code=error_data.get("code", FFIDErrorCode.UNKNOWN_ERROR),
+                message=error_data.get("message", "不明なエラーが発生しました"),
+                details=error_data.get("details"),
+            )
+
+        return data
+
+    # ------------------------------------------------------------------
+    # Public API methods
+    # ------------------------------------------------------------------
+
+    async def get_session(self, token: str) -> FFIDApiResponse[FFIDSessionResponse]:
+        """セッション情報を取得
+
+        FFID API の ``GET /api/v1/auth/session`` を呼び出し、
+        トークンに紐づくユーザー・組織・契約情報を取得する。
+
+        Args:
+            token: アクセストークン（Bearer Token）
+
+        Returns:
+            セッション情報を含むレスポンス
+        """
+        try:
+            raw = await self._fetch_json("GET", SESSION_ENDPOINT, token)
+            session_data = raw.get("data", raw)
+            session = FFIDSessionResponse.model_validate(session_data)
+            return FFIDApiResponse[FFIDSessionResponse](data=session)
+        except FFIDSDKError as exc:
+            return FFIDApiResponse[FFIDSessionResponse](
+                error=FFIDError(code=exc.code, message=exc.message, details=exc.details)
+            )
+        except Exception as exc:
+            logger.error("Unexpected error in get_session: %s", exc)
+            return FFIDApiResponse[FFIDSessionResponse](
+                error=FFIDError(
+                    code=FFIDErrorCode.UNKNOWN_ERROR,
+                    message="セッション情報の取得に失敗しました",
+                )
+            )
+
+    async def refresh_token(self, refresh_token: str) -> FFIDApiResponse[FFIDTokenResponse]:
+        """トークンをリフレッシュ
+
+        リフレッシュトークンはリクエストボディのみに含める（セキュリティ対策）。
+        Authorization ヘッダーには送信しない。
+
+        Args:
+            refresh_token: リフレッシュトークン
+
+        Returns:
+            新しいアクセストークンを含むレスポンス
+        """
+        try:
+            raw = await self._fetch_json(
+                "POST",
+                REFRESH_ENDPOINT,
+                None,
+                json_body={"refresh_token": refresh_token},
+                headers_override={"Content-Type": "application/json"},
+            )
+            data = raw.get("data", raw)
+            token_response = FFIDTokenResponse.model_validate(data)
+            return FFIDApiResponse[FFIDTokenResponse](data=token_response)
+        except FFIDSDKError as exc:
+            return FFIDApiResponse[FFIDTokenResponse](
+                error=FFIDError(code=exc.code, message=exc.message, details=exc.details)
+            )
+        except Exception as exc:
+            logger.error("Unexpected error in refresh_token: %s", exc)
+            return FFIDApiResponse[FFIDTokenResponse](
+                error=FFIDError(
+                    code=FFIDErrorCode.UNKNOWN_ERROR,
+                    message="トークンのリフレッシュに失敗しました",
+                )
+            )
+
+    async def sign_out(self, token: str) -> FFIDApiResponse[None]:
+        """サインアウト
+
+        Args:
+            token: アクセストークン
+
+        Returns:
+            成功時は data=None のレスポンス
+        """
+        try:
+            await self._request("POST", SIGNOUT_ENDPOINT, token)
+            return FFIDApiResponse[None](data=None)
+        except FFIDSDKError as exc:
+            return FFIDApiResponse[None](
+                error=FFIDError(code=exc.code, message=exc.message, details=exc.details)
+            )
+        except Exception as exc:
+            logger.error("Unexpected error in sign_out: %s", exc)
+            return FFIDApiResponse[None](
+                error=FFIDError(
+                    code=FFIDErrorCode.UNKNOWN_ERROR,
+                    message="サインアウトに失敗しました",
+                )
+            )
+
+    async def check_subscription(
+        self,
+        token: str,
+        service_code: Optional[str] = None,
+    ) -> FFIDApiResponse[FFIDSubscription]:
+        """契約状況をチェック
+
+        Args:
+            token: アクセストークン
+            service_code: サービスコード（未指定時はクライアント設定値を使用）
+
+        Returns:
+            契約情報を含むレスポンス
+        """
+        svc = service_code or self._service_code
+        try:
+            raw = await self._fetch_json(
+                "GET",
+                SUBSCRIPTIONS_CHECK_ENDPOINT,
+                token,
+                params={"service_code": svc},
+            )
+            data = raw.get("data", raw)
+            subscription = FFIDSubscription.model_validate(data)
+            return FFIDApiResponse[FFIDSubscription](data=subscription)
+        except FFIDSDKError as exc:
+            return FFIDApiResponse[FFIDSubscription](
+                error=FFIDError(code=exc.code, message=exc.message, details=exc.details)
+            )
+        except Exception as exc:
+            logger.error("Unexpected error in check_subscription: %s", exc)
+            return FFIDApiResponse[FFIDSubscription](
+                error=FFIDError(
+                    code=FFIDErrorCode.UNKNOWN_ERROR,
+                    message="契約情報の取得に失敗しました",
+                )
+            )

ffid_sdk/constants.py

@@ -0,0 +1,75 @@
+"""
+FFID SDK Shared Constants
+
+SDK全体で共有される定数。URL・エンドポイント・デフォルト設定値を一元管理。
+"""
+
+from __future__ import annotations
+
+# ---------------------------------------------------------------------------
+# API Base URL
+# ---------------------------------------------------------------------------
+
+DEFAULT_API_BASE_URL = "https://id.feelflow.co.jp"
+"""FFID API のデフォルトベースURL（本番環境）"""
+
+# ---------------------------------------------------------------------------
+# API Endpoint Paths
+# ---------------------------------------------------------------------------
+
+SESSION_ENDPOINT = "/api/v1/auth/session"
+"""セッション取得エンドポイント"""
+
+REFRESH_ENDPOINT = "/api/v1/auth/refresh"
+"""トークンリフレッシュエンドポイント"""
+
+SIGNOUT_ENDPOINT = "/api/v1/auth/signout"
+"""サインアウトエンドポイント"""
+
+SUBSCRIPTIONS_CHECK_ENDPOINT = "/api/v1/subscriptions/check"
+"""契約チェックエンドポイント"""
+
+LEGAL_EXT_PREFIX = "/api/v1/legal/ext"
+"""Legal 外部 API プレフィックス（Service API Key 認証）"""
+
+# ---------------------------------------------------------------------------
+# HTTP
+# ---------------------------------------------------------------------------
+
+SERVICE_API_KEY_HEADER = "X-Service-Api-Key"
+"""Service API Key ヘッダー名（Legal 等のサーバー間通信）"""
+
+NO_CONTENT_STATUS = 204
+"""HTTP 204 No Content ステータスコード"""
+
+AUTHORIZATION_HEADER = "Authorization"
+"""認証ヘッダー名"""
+
+BEARER_PREFIX = "Bearer "
+"""Bearer トークンプレフィックス"""
+
+SESSION_COOKIE_NAME = "ffid_session"
+"""セッションCookie名"""
+
+REFRESH_COOKIE_NAME = "ffid_refresh"
+"""リフレッシュトークン用Cookie名（auto_refresh 有効時のみ参照）"""
+
+# ---------------------------------------------------------------------------
+# Timeouts & Retries
+# ---------------------------------------------------------------------------
+
+DEFAULT_TIMEOUT_SECONDS = 10.0
+"""デフォルトHTTPタイムアウト（秒）"""
+
+DEFAULT_MAX_RETRIES = 3
+"""デフォルトリトライ回数"""
+
+DEFAULT_RETRY_BACKOFF_FACTOR = 0.5
+"""リトライ時のバックオフ係数"""
+
+# ---------------------------------------------------------------------------
+# Logging
+# ---------------------------------------------------------------------------
+
+SDK_LOGGER_NAME = "ffid_sdk"
+"""SDKロガー名"""

ffid_sdk/context.py

@@ -0,0 +1,75 @@
+"""
+FFID Context Dependencies for FastAPI
+
+FastAPI の ``Depends()`` で利用するコンテキスト取得関数。
+ミドルウェアが設定した ``FFIDContext`` をエンドポイントに注入する。
+
+Example:
+    ```python
+    from fastapi import Depends
+    from ffid_sdk import FFIDContext, get_ffid_context, require_ffid_auth
+
+    @app.get("/profile")
+    async def profile(ctx: FFIDContext = Depends(get_ffid_context)):
+        return {"email": ctx.user.email}
+
+    @app.get("/admin")
+    async def admin(ctx: FFIDContext = Depends(require_ffid_auth)):
+        # 認証必須（未認証時は FFIDAuthenticationError を送出）
+        return {"user": ctx.user.id}
+    ```
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Optional
+
+from fastapi import Request
+
+from ffid_sdk.constants import SDK_LOGGER_NAME
+from ffid_sdk.errors import FFIDAuthenticationError, FFIDErrorCode
+from ffid_sdk.types import FFIDContext
+
+logger = logging.getLogger(SDK_LOGGER_NAME)
+
+
+def get_ffid_context(request: Request) -> Optional[FFIDContext]:
+    """リクエストから FFID コンテキストを取得（認証任意）
+
+    ミドルウェアが設定した ``FFIDContext`` を返す。
+    未認証（除外パス等）の場合は ``None`` を返す。
+
+    Args:
+        request: FastAPI リクエストオブジェクト
+
+    Returns:
+        認証済みの場合は FFIDContext、未認証の場合は None
+    """
+    context: Optional[FFIDContext] = getattr(request.state, "ffid_context", None)
+    return context
+
+
+def require_ffid_auth(request: Request) -> FFIDContext:
+    """リクエストから FFID コンテキストを取得（認証必須）
+
+    ミドルウェアが設定した ``FFIDContext`` を返す。
+    未認証の場合は ``FFIDAuthenticationError`` を発生させる。
+
+    Args:
+        request: FastAPI リクエストオブジェクト
+
+    Returns:
+        認証済みの FFIDContext
+
+    Raises:
+        FFIDAuthenticationError: 未認証の場合
+    """
+    context: Optional[FFIDContext] = getattr(request.state, "ffid_context", None)
+    if context is None:
+        logger.debug("require_ffid_auth: No context found on request.state")
+        raise FFIDAuthenticationError(
+            message="認証が必要です。ログインしてください。",
+            code=FFIDErrorCode.AUTHENTICATION_ERROR,
+        )
+    return context

ffid_sdk/decorators.py

@@ -0,0 +1,147 @@
+"""
+FFID SDK Decorators
+
+FastAPI エンドポイント向けの契約チェックデコレータ。
+TypeScript SDK の ``withSubscription`` HOC に対応。
+
+Example:
+    ```python
+    from ffid_sdk import require_subscription, FFIDContext, get_ffid_context
+
+    @app.get("/premium")
+    @require_subscription(plans=["pro", "enterprise"])
+    async def premium_feature(ctx: FFIDContext = Depends(get_ffid_context)):
+        return {"plan": ctx.active_subscription.plan_code}
+
+    @app.get("/basic")
+    @require_subscription()  # 任意の有効な契約があればOK
+    async def basic_feature(ctx: FFIDContext = Depends(get_ffid_context)):
+        return {"message": "Welcome!"}
+    ```
+"""
+
+from __future__ import annotations
+
+import functools
+import logging
+from collections.abc import Callable
+from typing import TypeVar
+
+try:
+    from typing import ParamSpec
+except ImportError:
+    from typing_extensions import ParamSpec
+
+from ffid_sdk.constants import SDK_LOGGER_NAME
+from ffid_sdk.errors import (
+    FFIDAuthenticationError,
+    FFIDErrorCode,
+    FFIDSubscriptionError,
+)
+from ffid_sdk.types import FFIDContext, SubscriptionStatus
+
+logger = logging.getLogger(SDK_LOGGER_NAME)
+
+P = ParamSpec("P")
+R = TypeVar("R")
+
+
+def require_subscription(
+    plans: list[str] | None = None,
+    plan: list[str] | None = None,
+    service_code: str | None = None,
+) -> Callable[[Callable[P, R]], Callable[P, R]]:
+    """契約チェックデコレータ
+
+    エンドポイント関数をラップし、有効な契約があるかチェックする。
+    TypeScript SDK の ``withSubscription`` HOC に対応。
+
+    Args:
+        plans: 許可するプランコードのリスト（省略時は任意のアクティブ契約でOK）
+        plan: ``plans`` のエイリアス（Issue #170 の使用例と一致。plans より優先されない）
+        service_code: サービスコード（省略時はコンテキストの全契約を対象）
+
+    Returns:
+        デコレータ関数
+
+    Raises:
+        FFIDAuthenticationError: 未認証の場合
+        FFIDSubscriptionError: 有効な契約がない場合
+
+    Example:
+        ```python
+        @require_subscription(plans=["pro", "enterprise"])
+        async def premium_only(ctx: FFIDContext = Depends(get_ffid_context)):
+            ...
+        ```
+    """
+    # Issue #170: plan は plans のエイリアス（使用例 @require_subscription(plan=[...]) と一致）
+    if plans is None and plan is not None:
+        plans = plan
+
+    def decorator(func: Callable[P, R]) -> Callable[P, R]:
+        @functools.wraps(func)
+        async def wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
+            # コンテキストを取得（args および kwargs から FFIDContext を探す）
+            ctx: FFIDContext | None = next(
+                (a for a in args if isinstance(a, FFIDContext)), None
+            )
+            if ctx is None:
+                ctx = next(
+                    (v for v in kwargs.values() if isinstance(v, FFIDContext)), None
+                )
+
+            if ctx is None:
+                raise FFIDAuthenticationError(
+                    message="認証が必要です。ログインしてください。",
+                    code=FFIDErrorCode.AUTHENTICATION_ERROR,
+                )
+
+            # 契約チェック
+            active_statuses = (SubscriptionStatus.ACTIVE, SubscriptionStatus.TRIALING)
+            matching_subs = [
+                s for s in ctx.subscriptions
+                if s.status in active_statuses
+            ]
+
+            # サービスコードでフィルタ
+            if service_code:
+                matching_subs = [
+                    s for s in matching_subs
+                    if s.service_code == service_code
+                ]
+
+            # プランでフィルタ
+            if plans:
+                matching_subs = [
+                    s for s in matching_subs
+                    if s.plan_code in plans
+                ]
+
+            if not matching_subs:
+                plan_info = ""
+                if plans:
+                    plan_info = f"（必要なプラン: {', '.join(plans)}）"
+                logger.debug(
+                    "Subscription check failed: user=%s, plans=%s, service=%s",
+                    ctx.user.email, plans, service_code,
+                )
+                raise FFIDSubscriptionError(
+                    message=f"この機能を利用するには有効な契約が必要です。{plan_info}",
+                    code=FFIDErrorCode.SUBSCRIPTION_REQUIRED,
+                    details={
+                        "required_plans": plans or [],
+                        "service_code": service_code,
+                    },
+                )
+
+            logger.debug(
+                "Subscription check passed: user=%s, plan=%s",
+                ctx.user.email, matching_subs[0].plan_code,
+            )
+
+            return await func(*args, **kwargs)
+
+        return wrapper  # type: ignore[return-value]
+
+    return decorator