@feelflow/ffid-sdk 9.0.0 → 10.1.0

package/README.md

@@ -1,5 +1,8 @@
 # @feelflow/ffid-sdk
 
+<!-- markdownlint の既定からの差分（理由）: MD013 = 日本語本文・表・コードを含む公開文書で、折り返せる語境界がなく、表と URL は折り返せない -->
+<!-- markdownlint-configure-file {"MD013": false} -->
+
 [![npm version](https://img.shields.io/npm/v/@feelflow/ffid-sdk.svg)](https://www.npmjs.com/package/@feelflow/ffid-sdk)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
@@ -331,6 +334,38 @@ export default function Layout({ children }: { children: React.ReactNode }) {
 
 **詳細な実装レシピ**（middleware、Express、UI 分岐、Webhook 受信、fixture API を使ったテスト、`EffectiveSubscriptionStatus` 別の UI 推奨動作まで） → [docs/03-implementation/EXPIRED_CONTRACT_HANDLING.md](https://github.com/feel-flow/feelflow-id-platform/blob/develop/docs/03-implementation/EXPIRED_CONTRACT_HANDLING.md)
 
+### ログインを拒否されたとき（`?error=access_denied` と `denial_reason`、v10.1.0）
+
+組織に席が無い・人数枠が満員などで FFID がログインを拒否すると、通常はまず FFID の案内ページ（席が無いときは `/subscriptions/seat-required`）が表示されます。そこから「サービスへ戻る」を押したとき、または `prompt=none` で authorize したときに、サービスの `redirect_uri` へ `code` の代わりに `?error=access_denied&denial_reason=<理由>&state=...` が返ります（FFID [oauth.md「契約・席が無いとき」](https://github.com/feel-flow/feelflow-id-platform/blob/develop/docs/04-api/oauth.md)）。
+
+- token モードの `FFIDProvider` は、これを `useFFID().error` と `onError` に出します（`state` を照合した後。一致しなければ `STATE_MISMATCH_ERROR`）
+- 理由は `getFFIDAuthorizationError(error)` で読みます。`denialReason` は `no_membership` / `no_active_subscription` / `no_seat_assignment` / `subscription_expired` / `member_limit_reached`（`FFIDOAuthDenialReason`）か、理由が無い・未知のときは `null`
+- SDK が URL から外すのは使用済みの `state` だけです。`error` / `denial_reason` は残るので、URL を自分で読んでいる実装もそのまま動きます
+- **このエラーで `login()` を自動で呼び直さないでください。** FFID は同じ理由で拒否します。案内を出し、利用者の操作で再試行させます
+
+```tsx
+'use client'
+import { useFFID, getFFIDAuthorizationError } from '@feelflow/ffid-sdk'
+
+export function LoginDeniedNotice() {
+  const { error } = useFFID()
+  const denial = getFFIDAuthorizationError(error)
+  if (!denial) return null
+  switch (denial.denialReason) {
+    case 'no_seat_assignment':
+    case 'member_limit_reached':
+      return <p>このサービスの利用者に追加されていません。組織のオーナー / 管理者に追加を依頼してください。</p>
+    case 'subscription_expired':
+    case 'no_active_subscription':
+      return <p>組織の契約が有効ではありません。</p>
+    default:
+      return <p>ログインできませんでした。</p>
+  }
+}
+```
+
+サーバー（BFF）の `createServerAuthClient().handleCallback()` も、拒否のときは `error.code` に OAuth の `error`（`access_denied` など）を入れ、同じ `getFFIDAuthorizationError(result.error)` で理由を読めます（`@feelflow/ffid-sdk/server` から import）。
+
 ### Server-side service access decision
 
 API route / middleware では `checkServiceAccess()` を使う。FFID の `/api/v1/subscriptions/ext/check` が返す canonical decision をそのまま受け取り、外部サービス側で `past_due_since + 7d`、`current_period_end + 7d`、`payment_failed_at + 7d` のような lifecycle date math を再実装しない。
@@ -361,6 +396,56 @@ if (error || !access?.hasAccess) {
 - `effectiveStatus`: `active` / `past_due_grace` / `blocked` / `canceled` / `trial_expired` / `expired`。
 - `gracePeriodEndsAt`: `past_due_grace` が `blocked` に変わる時刻。表示・警告用であり、アクセス判定の source of truth にしない。
 - `failPolicy`: 現在は `failClosed` 固定。FFID に到達できない、または canonical decision を取得できない場合は `result.error` ではなく `data.hasAccess=false` / `denialReason='ffid_unreachable'` / `data.error` を返す。呼び出し側は `result.error` だけで通過判定しない。
+- `denialReason` には `member_limit_reached`（10.0.0）も含まれる。flat プランの人数枠が満員で席を付けられない利用者は、ログイン時に OAuth の `denial_reason: 'member_limit_reached'` で止まる。`checkServiceAccess()` 自体はこの値を返さず、人数枠・クレジット残高は `hasAccess` に影響しない。`memberLimitReached` / `credits` / `pricingModel` は情報として decision に載る（古い FFID は返さない）。
+
+### Credits（flat プラン、v10.0.0）
+
+`pricingModel: 'flat'`（固定料金 + 人数枠 + 月次 AI クレジット）の契約では、AI を実行するたびに FFID のクレジット台帳へ消費を報告する。契約の正本は FFID の [CREDITS_API.md](https://github.com/feel-flow/feelflow-id-platform/blob/develop/docs/04-api/CREDITS_API.md)、手順は [docs/INTEGRATION_GUIDE.md の Credits 節](./docs/INTEGRATION_GUIDE.md#credits-flat-plans)。
+
+```ts
+import { createFFIDClient, FFID_CREDITS_ERROR_CODES, type FFIDCreditsInsufficientDetails } from '@feelflow/ffid-sdk'
+
+// サービスのバックエンド（consume は service-key モード専用）
+const ffid = createFFIDClient({
+  serviceCode: 'chatbot-v2',
+  scope: '',
+  authMode: 'service-key',
+  serviceApiKey: process.env.FFID_SERVICE_API_KEY!,
+})
+
+const { data, error } = await ffid.credits.consume({
+  subscriptionId,
+  amount: 50,
+  idempotencyKey: `chat.reply:${requestId}`, // AI 実行 1 回につき 1 つ。再試行でも同じキー
+  feature: 'chat.reply',
+  metadata: { model: 'example', tokens: 1200 }, // 個人情報は入れない
+})
+
+if (error?.code === FFID_CREDITS_ERROR_CODES.CREDITS_INSUFFICIENT) {
+  const details = error.details as unknown as FFIDCreditsInsufficientDetails
+  // 自動で再試行しない。購入導線（owner / admin）か管理者への依頼を出す
+  return { blocked: true, available: details.available }
+}
+if (error) {
+  // 5xx / NETWORK_ERROR は同じキー・同じ amount で再試行してよい（duplicate が返る）
+  throw new Error(error.message)
+}
+// data.status は 'consumed' | 'duplicate'
+```
+
+| メソッド | 認証モード | 用途 |
+| --- | --- | --- |
+| `credits.consume(params)` | service-key のみ | AI 実行 1 回ぶんの消費を報告 |
+| `credits.getBalance(subscriptionId)` | token / service-key | 残高・当期・内訳・`isLow` / `isExhausted` |
+| `credits.listHistory(subscriptionId, { cursor?, limit?, type? })` | token / service-key | 履歴（新しい順） |
+| `credits.listPacks(serviceCode?)` | token / service-key | 購入できるパック |
+| `credits.createPackCheckout(params)` | token のみ（owner / admin） | パック購入の Stripe Checkout URL |
+| `credits.getBuyCreditsUrl({ subscriptionId, orgId? })` / `redirectToBuyCredits` | どれでも | FFID の契約詳細で購入ダイアログを開く URL（UUID か `ffid:<uuid>`。`sub_...` は不可） |
+| `getSeats(subscriptionId)` | token / service-key | 人数枠（`maxMembers` / `assignedMembers` / `availableMembers`、`null` = 無制限） |
+
+- AI 機能のゲートは **残高**（`consume` の結果・`getBalance()`・`checkServiceAccess()` の `credits`）で行い、`hasAccess` では行わない。クレジットが 0 でも `hasAccess` は `true` のまま。
+- `consume` を service-key 以外で、`createPackCheckout` を token 以外で呼ぶと、ネットワークに出る前に `FORBIDDEN`（`details.reason: 'api_key_required'` / `'bearer_required'`）が返る。
+- 残高の変化は webhook `credits.granted` / `credits.low` / `credits.exhausted` / `credits.pack_purchased` でも届く（`@feelflow/ffid-sdk/webhooks`）。
 
 ### Organization member management
 
@@ -614,6 +699,7 @@ if (result.error) {
 ```
 
 エラーコード:
+
 - `VALIDATION_ERROR` — `serviceCode` が空 / kebab-case 形式違反（SDK 側 pre-validate）
 - `INSUFFICIENT_SCOPE` (403) — `analytics:read` scope なし
 - `SERVICE_NOT_FOUND` (404) — DB に未登録の service code
@@ -655,7 +741,7 @@ if (persisted === false) {
 
 実際の導線は次の形です。
 
-```
+```text
 /?invite=abc に着地 → 料金ページを見る → /pricing で「登録」を押す
 ```
 
@@ -685,7 +771,7 @@ v7.3.x までは token モードでトークンが FFID に 1 度も届かず、
 ### cookie の仕様
 
 | 項目 | 値 |
-|---|---|
+| --- | --- |
 | 名前 | `ffid_invite`（first-party・consumer 自身のホスト） |
 | 有効期限 | 30 日 |
 | `Path` | `/` |