@event/fours-sdk が唯一の型付き 4S クライアントである。すべてのモジュール・アプリはこの SDK を通して 4S を読み、直接 fetch を書かない。SDK は4つの面（surface）を提供する。
4つの面
| 面 | 主関数 | 認証 | 用途 |
|---|---|---|---|
| event-read | fetchEvent / listSessionsFromEvent / listSpeakersFromEvent / listPassTiers / get4SHealth | なし（public read） | セッション・登壇者・チケット・会場の読み出し（第6章） |
| profile-read | fetch4SUser / fetchPublicProfile / fetchOrgMembers / extractSlug / normName | なし | ユーザー / 組織プロフィール、名寄せ |
| handoff / identity | verify4SUser / createSessionCodec / createLoginProxyHandler / createCognitoRefreshHandler、client 側 tokenStore（@event/fours-sdk/client） | Bearer idToken | ログインレス handoff・本人確定・cookie セッション（第9章） |
| admin (service) | isServiceConfigured / getServiceIdToken / fetchEntryIndex / fetchDescendantInfos | service アカウント Bearer | entries 索引・リファラルツリー等の管理 API |
接続モード matrix
mode は env の組み合わせから createFoursConfig() が一意に決める。判定優先順は上から。
| mode | 条件 | 挙動 |
|---|---|---|
mock-locked | USE_MOCK_DATA | 4S に一切出ない。foursFetchPublic / fetchEvent は null |
authenticated | FOURS_API_KEY あり | write 系 API 可。Bearer は config.apiKey |
public-read | FOURS_PUBLIC_READ | 認証なし読み取りのみ |
stub | それ以外 | 読み書きとも no-op。render は落とさない |
summarizeFoursConfig(config) は秘匿値を含まない診断サマリ（mode / base / hasApiKey 等）を返し、/api/4s/health 系のデバッグ UI に使う。
エンドポイント一覧（実コード観測ベース）
| 面 | エンドポイント | 認証 | 備考 |
|---|---|---|---|
| event read | GET /slug/{eventSlug} | なし | type 判別レスポンス（event / user / organization）。sessions / speakers / stages / schedules / tickets / location |
| profile read | GET /slug/{userSlug} | なし | organizationMembers / userLinks / socialLinks / tags |
| org members | GET /organizations/{id}/members?page&perPage | なし | ロスター母集団 |
| config | GET /config | なし | COGNITO_USER_POOL_ID / COGNITO_USER_POOL_CLIENT_ID |
| identity | GET /users/me | Bearer idToken | 正典の本人情報。client 申告の name/avatar は破棄 |
| admin | GET /manage/events/{id}/entries?perPage=200 | Bearer (service) | slug/name→entryId 索引 |
| admin | GET /events/{id}/entries/{entryId}/referral-descendants | Bearer (service) | 招待ツリー |
| login | POST /auth/login（body: email または slug + password） | なし | @ の有無で email / slug を選ぶ |
| handoff | POST /auth/session-handoff/consume {code} | なし（Origin 検査） | 400 / 403 / 404 / 410 |
| handoff | POST /auth/session-handoff/mint | Cognito（4s.link のみ） | イベントサイトからは物理的に呼べない |
| Cognito | POST https://cognito-idp.{region}.amazonaws.com/ | — | REFRESH_TOKEN_AUTH。SSRF 正規表現ガード |
| webhook | POST /api/4s/webhook（inbound） | X-4S-Signature: sha256=<HMAC> | raw body の HMAC-SHA256 |
transport と error handling
foursFetch / foursFetchPublic が全通信の関門である。設計方針:
- null-on-failure: 4S の欠落・障害でイベントサイトの render を落とさない。throw が必要な呼び出しは
throwOnError: trueを指定する FoursErrorは型付きコード（network/unauthorized/not_found/invalid_response/handoff_*/unknown）を持ち、UI がステータス別に分岐できる。handoff の4状態はhandoffErrorFromStatus(status)で変換する- タイムアウトは
AbortSignal.timeout（既定 15000ms）で強制 - Next.js の fetch cache 制御（
next.revalidate/tags）はオプションで透過する
route handler factory
サーバ側は factory を1行 mount するだけで済む:
// app/api/4s-session/login/route.ts
import { createFoursConfig, createLoginProxyHandler } from "@event/fours-sdk";
export const POST = createLoginProxyHandler(createFoursConfig());
export const runtime = "nodejs";
export const dynamic = "force-dynamic";createLoginProxyHandler はブラウザ→4S の CORS 問題を server→server 転送で回避し、パスワードは保存せず転送のみ。404 と 401 を 401 に統一してユーザー名列挙オラクルを塞ぐ。createCognitoRefreshHandler は region / clientId をホワイトリスト正規表現で検証し、宛先を常に cognito-idp.<region>.amazonaws.com に限定する（SSRF 防止）。