ffid-python-sdk 0.2.0

FeelFlow ID Platform SDK for Python (FastAPI)

ffid-python-sdk

FeelFlow ID Platform SDK for Python (FastAPI).
FastAPI アプリケーション向けの認証・認可・契約管理 SDK です。

5行のコードでFFID認証を導入可能（最小ボイラープレート）。

• Python 3.11+
• FastAPI / Pydantic v2 / httpx

インストール

pip install ffid-python-sdk

クイックスタート（最小例）

from fastapi import FastAPI, Depends
from ffid_sdk import FFIDMiddleware, require_subscription, FFIDContext, get_ffid_context

app = FastAPI()
app.add_middleware(FFIDMiddleware, service_code="chatbot")

@app.get("/api/chat")
@require_subscription(plan=["basic", "pro", "enterprise"])
async def chat(ffid: FFIDContext = Depends(get_ffid_context)):
    return {"message": f"Hello, {ffid.user.email}"}

認証はミドルウェアが行い、get_ffid_context でコンテキストをエンドポイントに注入します。
plan= は plans= のエイリアスです（どちらも利用可能）。

主要コンポーネント

FFIDMiddleware

リクエストからアクセストークン（Authorization: Bearer または Cookie ffid_session）を取得し、FFID API でセッション検証後に request.state.ffid_context にコンテキストを格納します。

app.add_middleware(
    FFIDMiddleware,
    service_code="chatbot",
    exclude_paths=["/health", "/docs", "/openapi.json"],
)

FFIDContext

ユーザー・組織・契約情報を保持するリクエストスコープのコンテキスト。
Depends(get_ffid_context) で取得（認証任意）、Depends(require_ffid_auth) で認証必須にできます。

• ctx.user … 認証ユーザー
• ctx.organizations … 所属組織一覧
• ctx.subscriptions … 契約一覧
• ctx.active_subscription … 有効な契約（1件）

@require_subscription

契約チェック用デコレータ。指定プランまたは任意の有効契約が必要なエンドポイントに付けます。

@require_subscription(plan=["basic", "pro", "enterprise"])  # または plans=
async def premium(ctx: FFIDContext = Depends(get_ffid_context)):
    ...

FFIDClient

FFID API を直接呼ぶクライアント（セッション取得・トークンリフレッシュ・サインアウト・契約確認など）。
ミドルウェアを使わないバックグラウンド処理やテストで利用します。

from ffid_sdk import FFIDClient, FFIDConfig

client = FFIDClient(FFIDConfig(service_code="chatbot"))
response = await client.get_session(token="...")

環境変数

変数	説明
FFID_SERVICE_CODE	サービス識別コード（例: chatbot）。ミドルウェアの service_code に渡すか、クライアント設定で指定。
FFID_API_BASE_URL	FFID API のベースURL（省略時は本番 https://id.feelflow.co.jp 相当）。

利用規約チェック・リダイレクト

法的文書の同意確認と未同意時のリダイレクトは、Legal クライアント（Service API Key 認証）で実装済みです。
check_pending_agreements_and_redirect_url で未同意一覧を取得し、未同意時は返却される redirect_url へリダイレクトできます。戻り値の第4要素に API エラーが入るため、呼び出し元でエラーハンドリング可能です。

トークン自動リフレッシュ（オプション）

JWT 期限切れ時に refresh トークンで自動再取得する機能をミドルウェアで利用できます。
FFIDMiddleware(..., auto_refresh=True) にし、Cookie ffid_refresh にリフレッシュトークンが含まれる構成で有効化します。

ライセンス

MIT