ffid-python-sdk 0.1.0__tar.gz

ffid_python_sdk-0.1.0/.gitignore

@@ -0,0 +1,98 @@
+# FeelFlow ID Platform - Git Ignore
+
+# Dependencies
+node_modules/
+.pnp/
+.pnp.js
+.yarn/
+
+# Build outputs
+.next/
+out/
+dist/
+build/
+
+# Environment variables
+.env
+.env.local
+.env.*.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+# Debug logs
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+.pnpm-debug.log*
+
+# Testing
+coverage/
+*.lcov
+.nyc_output/
+
+# TypeScript
+*.tsbuildinfo
+next-env.d.ts
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+.project
+.classpath
+.settings/
+
+# OS
+.DS_Store
+.DS_Store?
+._*
+.Spotlight-V100
+.Trashes
+ehthumbs.db
+Thumbs.db
+
+# Logs
+logs/
+*.log
+
+# Temporary files
+tmp/
+temp/
+*.tmp
+*.temp
+
+# Vercel
+.vercel/
+
+# Turbopack
+.turbo/
+
+# Claude Code local settings
+.claude/settings.local.json
+# Cursor / Claude Code plan files
+.claude/plans/
+# Cursor: ignore .cursor except skills (project-specific, shared with team)
+.cursor/*
+!.cursor/skills/
+
+# SDK build outputs (for sdk/ directory)
+sdk/python/dist/
+sdk/python/*.egg-info/
+sdk/typescript/dist/
+sdk/typescript/node_modules/
+
+# Python cache
+__pycache__/
+*.py[cod]
+*$py.class
+.pytest_cache/
+
+# Distribution packages
+*.zip
+
+# Test data (local only, not committed)
+supabase/tests/*.local.md
+supabase/tests/test-data.local.json

ffid_python_sdk-0.1.0/.gitkeep

@@ -0,0 +1,2 @@
+# ffid-python-sdk
+# Python SDK for connecting services to FeelFlow ID Platform

ffid_python_sdk-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 FeelFlow Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ffid_python_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,135 @@
+Metadata-Version: 2.4
+Name: ffid-python-sdk
+Version: 0.1.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

ffid_python_sdk-0.1.0/README.md

@@ -0,0 +1,100 @@
+# 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

ffid_python_sdk-0.1.0/ffid_sdk/__init__.py

@@ -0,0 +1,176 @@
+"""
+FFID SDK - FeelFlow ID Platform SDK for Python (FastAPI)
+
+FastAPI アプリケーション向けの認証・認可・契約管理 SDK。
+
+Quick Start:
+    ```python
+    from fastapi import FastAPI, Depends
+    from ffid_sdk import FFIDMiddleware, FFIDContext, get_ffid_context, require_subscription
+
+    app = FastAPI()
+    app.add_middleware(FFIDMiddleware, service_code="chatbot")
+
+    @app.get("/dashboard")
+    async def dashboard(ctx: FFIDContext = Depends(get_ffid_context)):
+        return {"user": ctx.user.email}
+
+    @app.get("/premium")
+    @require_subscription(plans=["pro", "enterprise"])
+    async def premium(ctx: FFIDContext = Depends(get_ffid_context)):
+        return {"plan": ctx.active_subscription.plan_code}
+    ```
+"""
+
+from __future__ import annotations
+
+# Client
+from ffid_sdk.client import FFIDClient
+
+# Constants
+from ffid_sdk.constants import DEFAULT_API_BASE_URL
+
+# Context & Dependencies
+from ffid_sdk.context import get_ffid_context, require_ffid_auth
+
+# Decorators
+from ffid_sdk.decorators import require_subscription
+
+# Errors
+from ffid_sdk.errors import (
+    FFIDAuthenticationError,
+    FFIDAuthorizationError,
+    FFIDErrorCode,
+    FFIDNetworkError,
+    FFIDSDKError,
+    FFIDSubscriptionError,
+    FFIDValidationError,
+)
+
+# Middleware
+from ffid_sdk.middleware import FFIDMiddleware
+
+# Types
+from ffid_sdk.types import (
+    FFIDApiResponse,
+    FFIDConfig,
+    FFIDContext,
+    FFIDError,
+    FFIDOrganization,
+    FFIDSessionResponse,
+    FFIDSubscription,
+    FFIDTokenResponse,
+    FFIDUser,
+    MembershipStatus,
+    OrganizationRole,
+    SubscriptionStatus,
+)
+
+# Webhook - Constants
+from ffid_sdk.webhook_constants import (
+    DEFAULT_TOLERANCE_SECONDS,
+    FFID_WEBHOOK_EVENT_ID_HEADER,
+    FFID_WEBHOOK_SIGNATURE_HEADER,
+    FFID_WEBHOOK_TIMESTAMP_HEADER,
+)
+
+# Webhook - Errors
+from ffid_sdk.webhook_errors import (
+    FFIDWebhookError,
+    FFIDWebhookPayloadError,
+    FFIDWebhookSignatureError,
+    FFIDWebhookTimestampError,
+)
+
+# Webhook - Handler
+from ffid_sdk.webhook_handler import WebhookHandler
+
+# Webhook - Types
+from ffid_sdk.webhook_types import (
+    EVENT_TYPE_PAYLOAD_MAP,
+    FFIDLegalDocumentPayload,
+    FFIDMaintenancePayload,
+    FFIDOrganizationMemberPayload,
+    FFIDOrganizationPayload,
+    FFIDSubscriptionPayload,
+    FFIDTestPingPayload,
+    FFIDUserPayload,
+    FFIDWebhookEvent,
+    WebhookEventType,
+)
+
+# Webhook - Verify
+from ffid_sdk.webhook_verify import verify_webhook_signature
+
+# Legal (Phase 2: 利用規約チェック・リダイレクト)
+from ffid_sdk.legal import (
+    FFIDLegalClient,
+    FFIDLegalClientConfig,
+    check_pending_agreements_and_redirect_url,
+)
+
+__all__ = [
+    # Client
+    "FFIDClient",
+    # Config & Constants
+    "FFIDConfig",
+    "DEFAULT_API_BASE_URL",
+    # Context & Dependencies
+    "FFIDContext",
+    "get_ffid_context",
+    "require_ffid_auth",
+    # Decorators
+    "require_subscription",
+    # Errors
+    "FFIDSDKError",
+    "FFIDAuthenticationError",
+    "FFIDAuthorizationError",
+    "FFIDSubscriptionError",
+    "FFIDNetworkError",
+    "FFIDValidationError",
+    "FFIDErrorCode",
+    # Middleware
+    "FFIDMiddleware",
+    # Types
+    "FFIDUser",
+    "FFIDOrganization",
+    "FFIDSubscription",
+    "FFIDSessionResponse",
+    "FFIDTokenResponse",
+    "FFIDError",
+    "FFIDApiResponse",
+    "OrganizationRole",
+    "MembershipStatus",
+    "SubscriptionStatus",
+    # Webhook - Constants
+    "FFID_WEBHOOK_SIGNATURE_HEADER",
+    "FFID_WEBHOOK_TIMESTAMP_HEADER",
+    "FFID_WEBHOOK_EVENT_ID_HEADER",
+    "DEFAULT_TOLERANCE_SECONDS",
+    # Webhook - Errors
+    "FFIDWebhookError",
+    "FFIDWebhookSignatureError",
+    "FFIDWebhookTimestampError",
+    "FFIDWebhookPayloadError",
+    # Webhook - Handler
+    "WebhookHandler",
+    # Webhook - Types
+    "FFIDWebhookEvent",
+    "WebhookEventType",
+    "FFIDSubscriptionPayload",
+    "FFIDUserPayload",
+    "FFIDOrganizationPayload",
+    "FFIDOrganizationMemberPayload",
+    "FFIDLegalDocumentPayload",
+    "FFIDMaintenancePayload",
+    "FFIDTestPingPayload",
+    "EVENT_TYPE_PAYLOAD_MAP",
+    # Webhook - Verify
+    "verify_webhook_signature",
+    # Legal
+    "FFIDLegalClient",
+    "FFIDLegalClientConfig",
+    "check_pending_agreements_and_redirect_url",
+]
+
+__version__ = "0.1.0"