Metadata-Version: 2.4
Name: ffid-python-sdk
Version: 0.2.0
Summary: FeelFlow ID Platform SDK for Python (FastAPI)
Project-URL: Homepage, https://github.com/feel-flow/feelflow-id-platform/tree/develop/sdk/python
Project-URL: Repository, https://github.com/feel-flow/feelflow-id-platform
Project-URL: Documentation, https://github.com/feel-flow/feelflow-id-platform/tree/develop/sdk/python#readme
Project-URL: Bug Tracker, https://github.com/feel-flow/feelflow-id-platform/issues
Author-email: "FeelFlow Inc." <dev@feelflow.co.jp>
License-Expression: MIT
License-File: LICENSE
Keywords: authentication,fastapi,feelflow,ffid,sdk
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: FastAPI
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: fastapi>=0.100.0
Requires-Dist: httpx>=0.24.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: typing-extensions>=4.0.0
Provides-Extra: dev
Requires-Dist: mypy>=1.0.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Requires-Dist: respx>=0.20.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Description-Content-Type: text/markdown

# ffid-python-sdk

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

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

- Python 3.11+
- FastAPI / Pydantic v2 / httpx

## インストール

```bash
pip install ffid-python-sdk
```

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

```python
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` にコンテキストを格納します。

```python
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

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

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

### FFIDClient

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

```python
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
