@feelflow/ffid-sdk 2.19.0 → 2.21.0

package/README.md

@@ -351,6 +351,43 @@ await client.updateProfile({
 
 対応フィールド: `displayName` / `phone` / `companyName` / `department` / `jobTitle` / `preferences`。`timezone` / `locale` は application-level invariant（サーバー側 normalization が string 前提）のため null 非許容。クリアは不可 — キー未指定で現状維持、もしくは新しい有効な値を渡す。
 
+### getAnalyticsConfig() (#2347)
+
+外部サービスが自身に割り当てられた GA4 Measurement ID を取得するメソッド。
+
+- エンドポイント: `GET /api/v1/ext/analytics/config?service=<code>`
+- 必要 scope: `analytics:read`（Bearer / API Key 両方で enforce）
+- レスポンス: `FFIDAnalyticsConfig` (`{ code, measurementId, displayName, isActive }`)
+- **archived service** (`isActive: false`) でも 200 を返す — caller が次回 deploy で tracking 停止判断する間、in-flight events が 5xx を起こさないように measurementId は引き続き返す
+
+```ts
+import { createFFIDClient } from '@feelflow/ffid-sdk/server'
+
+const client = createFFIDClient({
+  serviceCode: 'flow-board-ai',
+  authMode: 'service-key',
+  serviceApiKey: process.env.FFID_SERVICE_API_KEY!,
+})
+
+const result = await client.getAnalyticsConfig('feel-agent-ai')
+if (result.error) {
+  if (result.error.code === 'SERVICE_NOT_FOUND') {
+    // 該当 GA4 stream がまだ sync されていない / typo
+  } else {
+    console.error(`[FFID] analytics config fetch failed: ${result.error.code}`)
+  }
+} else if (result.data.isActive) {
+  // GA4 タグを描画して events を送信
+  loadGA4Script(result.data.measurementId)
+}
+```
+
+エラーコード:
+- `VALIDATION_ERROR` — `serviceCode` が空 / kebab-case 形式違反（SDK 側 pre-validate）
+- `INSUFFICIENT_SCOPE` (403) — `analytics:read` scope なし
+- `SERVICE_NOT_FOUND` (404) — DB に未登録の service code
+- `INVALID_PARAM` (400) — server 側で形式違反を検出（pre-validate 通過後の boundary）
+
 ## 型定義
 
 ```typescript
@@ -487,6 +524,88 @@ SDK の `package.json` で `react` / `react-dom` は `optional: true` に設定
 }
 ```
 
+## E2E テストモード（`@feelflow/ffid-sdk/server/test`）
+
+> **⚠️ SECURITY NOTICE** — テストモードは Bearer トークン検証を **意図的にバイパス** する仕組みです。本番環境で誤って有効化すると、登録されたバイパストークンを持つ任意のリクエストが認証通過します。
+
+各サービスで E2E テストを書く際、`verifyAccessToken` の introspect 呼び出しをモックする実装を独自に持つ必要がなくなります。SDK 側で **多重 production guard 付き** の bypass クライアントを提供します。
+
+```ts
+import { createFFIDClient } from '@feelflow/ffid-sdk/server'
+import { createTestFFIDClient } from '@feelflow/ffid-sdk/server/test'
+
+const isE2E =
+  process.env.NODE_ENV !== 'production' &&
+  process.env.FFID_TEST_MODE === 'true'
+
+const client = isE2E
+  ? createTestFFIDClient({
+      users: [
+        {
+          bypassToken: process.env.E2E_TEST_BYPASS_SECRET!,
+          userInfo: {
+            sub: 'e2e-test-sub',
+            email: 'e2e@example.com',
+            name: 'E2E Test User',
+            picture: null,
+          },
+        },
+      ],
+    })
+  : createFFIDClient({ /* normal production options */ })
+
+const result = await client.verifyAccessToken(bearerToken)
+```
+
+### Built-in production guards (defense-in-depth)
+
+- `NODE_ENV` を **trim + lowercase** 後に比較。`"production "`（改行混入）や `"Production"` も production として扱う（Vercel 環境変数の copy/paste 事故対策）
+- `process.env` を露出しない runtime（Edge / Cloudflare Workers / browser）では **fail-close** で構築拒否
+- `bypassToken` の重複検知 / 空チェック / `userInfo.sub` 必須チェック（構築時 throw）
+- 未登録 token は **fail-close**（実 introspect への暗黙 fallthrough は行わない）
+- 構築時点で `users` のスナップショットを取り、入力配列の post-construction mutation は無視
+- 各 `verifyAccessToken` 呼び出しは新しいオブジェクトを返却（caller mutation が後続呼び出しを汚染しない）
+
+### `allowInProduction` escape hatch
+
+staging が `NODE_ENV=production` をミラーするケース等のみ、明示的な ack 文字列で有効化できます：
+
+```ts
+import {
+  createTestFFIDClient,
+  TEST_CLIENT_ALLOW_IN_PRODUCTION_ACK,
+} from '@feelflow/ffid-sdk/server/test'
+
+createTestFFIDClient({
+  users: [...],
+  allowInProduction: TEST_CLIENT_ALLOW_IN_PRODUCTION_ACK,
+})
+// → process.emitWarning(..., 'FFIDTestModeInProduction') を毎構築時に発火
+```
+
+`boolean` ではなく **literal string ack** を要求する型なので、`allowInProduction: someBooleanFlag` のような誤代入はコンパイルエラーになります。ack 文字列は grep 可能で監査も容易です。
+
+### サブパス分離
+
+`createTestFFIDClient` は **`@feelflow/ffid-sdk/server/test` からのみ** import 可能です（`@feelflow/ffid-sdk/server` にも main entry にも含まれない）。本番コードからの誤 import は ESLint の `no-restricted-imports` 等で検知することを推奨します：
+
+```js
+// eslint.config.mjs (flat config)
+import { defineConfig } from 'eslint/config'
+
+export default defineConfig([
+  {
+    files: ['src/**/*.{ts,tsx}'],          // production code only
+    ignores: ['**/__tests__/**', 'tests/e2e/**'],
+    rules: {
+      'no-restricted-imports': ['error', {
+        patterns: ['@feelflow/ffid-sdk/server/test'],
+      }],
+    },
+  },
+])
+```
+
 ## 環境変数
 
 オプションで環境変数を使用してデフォルト設定を上書きできます：

package/dist/{chunk-BBXUZS4U.cjs → chunk-HUU4Q5VH.cjs}

@@ -807,7 +807,7 @@ function createProfileMethods(deps) {
 }
 
 // src/client/version-check.ts
-var SDK_VERSION = "2.19.0";
+var SDK_VERSION = "2.21.0";
 var SDK_USER_AGENT = `FFID-SDK/${SDK_VERSION} (TypeScript)`;
 var SDK_VERSION_HEADER = "X-FFID-SDK-Version";
 function sdkHeaders() {
@@ -1840,6 +1840,63 @@ function createOtpMethods(deps) {
   };
 }
 
+// src/client/analytics-methods.ts
+var EXT_ANALYTICS_CONFIG_ENDPOINT = "/api/v1/ext/analytics/config";
+function resolveAuthOverride2(options, createError) {
+  if (!options || options.accessToken === void 0) {
+    return {};
+  }
+  const token = options.accessToken;
+  if (typeof token !== "string" || token.trim() === "") {
+    return {
+      error: createError(
+        "VALIDATION_ERROR",
+        "accessToken \u3092\u6307\u5B9A\u3059\u308B\u5834\u5408\u3001\u7A7A\u6587\u5B57\u5217\u3084\u7A7A\u767D\u306E\u307F\u306E\u5024\u306F\u4F7F\u7528\u3067\u304D\u307E\u305B\u3093"
+      )
+    };
+  }
+  return { override: { accessToken: token } };
+}
+var ANALYTICS_SERVICE_CODE_PATTERN = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+function validateServiceCode(serviceCode, createError) {
+  if (typeof serviceCode !== "string" || serviceCode.trim() === "") {
+    return createError(
+      "VALIDATION_ERROR",
+      "serviceCode \u306F\u5FC5\u9808\u306E kebab-case \u6587\u5B57\u5217\u3067\u3059"
+    );
+  }
+  if (!ANALYTICS_SERVICE_CODE_PATTERN.test(serviceCode)) {
+    return createError(
+      "VALIDATION_ERROR",
+      "serviceCode \u306F kebab-case \u5F62\u5F0F (\u82F1\u5C0F\u6587\u5B57\u30FB\u6570\u5B57\u30FB\u30CF\u30A4\u30D5\u30F3) \u3067\u6307\u5B9A\u3057\u3066\u304F\u3060\u3055\u3044"
+    );
+  }
+  return null;
+}
+function createAnalyticsMethods(deps) {
+  const { fetchWithAuth, createError } = deps;
+  async function getAnalyticsConfig(serviceCode, options) {
+    const validationError = validateServiceCode(serviceCode, createError);
+    if (validationError) {
+      return { error: validationError };
+    }
+    const { override, error: overrideError } = resolveAuthOverride2(
+      options,
+      createError
+    );
+    if (overrideError) {
+      return { error: overrideError };
+    }
+    const endpoint = `${EXT_ANALYTICS_CONFIG_ENDPOINT}?service=${encodeURIComponent(serviceCode)}`;
+    return fetchWithAuth(
+      endpoint,
+      { method: "GET" },
+      override
+    );
+  }
+  return { getAnalyticsConfig };
+}
+
 // src/client/contract-wizard-methods.ts
 var CONTRACT_WIZARD_PATH = "/contract-wizard";
 function buildWizardUrl(baseUrl, flow, params) {
@@ -2362,6 +2419,10 @@ function createFFIDClient(config) {
     fetchWithAuth,
     createError
   });
+  const { getAnalyticsConfig } = createAnalyticsMethods({
+    fetchWithAuth,
+    createError
+  });
   const {
     requestPasswordReset,
     verifyPasswordResetToken,
@@ -2435,6 +2496,7 @@ function createFFIDClient(config) {
     removeMember,
     getProfile,
     updateProfile,
+    getAnalyticsConfig,
     createCheckoutSession,
     createPortalSession,
     listPlans,

package/dist/{chunk-SXYB5QM3.js → chunk-I7NEMG52.js}

@@ -805,7 +805,7 @@ function createProfileMethods(deps) {
 }
 
 // src/client/version-check.ts
-var SDK_VERSION = "2.19.0";
+var SDK_VERSION = "2.21.0";
 var SDK_USER_AGENT = `FFID-SDK/${SDK_VERSION} (TypeScript)`;
 var SDK_VERSION_HEADER = "X-FFID-SDK-Version";
 function sdkHeaders() {
@@ -1838,6 +1838,63 @@ function createOtpMethods(deps) {
   };
 }
 
+// src/client/analytics-methods.ts
+var EXT_ANALYTICS_CONFIG_ENDPOINT = "/api/v1/ext/analytics/config";
+function resolveAuthOverride2(options, createError) {
+  if (!options || options.accessToken === void 0) {
+    return {};
+  }
+  const token = options.accessToken;
+  if (typeof token !== "string" || token.trim() === "") {
+    return {
+      error: createError(
+        "VALIDATION_ERROR",
+        "accessToken \u3092\u6307\u5B9A\u3059\u308B\u5834\u5408\u3001\u7A7A\u6587\u5B57\u5217\u3084\u7A7A\u767D\u306E\u307F\u306E\u5024\u306F\u4F7F\u7528\u3067\u304D\u307E\u305B\u3093"
+      )
+    };
+  }
+  return { override: { accessToken: token } };
+}
+var ANALYTICS_SERVICE_CODE_PATTERN = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+function validateServiceCode(serviceCode, createError) {
+  if (typeof serviceCode !== "string" || serviceCode.trim() === "") {
+    return createError(
+      "VALIDATION_ERROR",
+      "serviceCode \u306F\u5FC5\u9808\u306E kebab-case \u6587\u5B57\u5217\u3067\u3059"
+    );
+  }
+  if (!ANALYTICS_SERVICE_CODE_PATTERN.test(serviceCode)) {
+    return createError(
+      "VALIDATION_ERROR",
+      "serviceCode \u306F kebab-case \u5F62\u5F0F (\u82F1\u5C0F\u6587\u5B57\u30FB\u6570\u5B57\u30FB\u30CF\u30A4\u30D5\u30F3) \u3067\u6307\u5B9A\u3057\u3066\u304F\u3060\u3055\u3044"
+    );
+  }
+  return null;
+}
+function createAnalyticsMethods(deps) {
+  const { fetchWithAuth, createError } = deps;
+  async function getAnalyticsConfig(serviceCode, options) {
+    const validationError = validateServiceCode(serviceCode, createError);
+    if (validationError) {
+      return { error: validationError };
+    }
+    const { override, error: overrideError } = resolveAuthOverride2(
+      options,
+      createError
+    );
+    if (overrideError) {
+      return { error: overrideError };
+    }
+    const endpoint = `${EXT_ANALYTICS_CONFIG_ENDPOINT}?service=${encodeURIComponent(serviceCode)}`;
+    return fetchWithAuth(
+      endpoint,
+      { method: "GET" },
+      override
+    );
+  }
+  return { getAnalyticsConfig };
+}
+
 // src/client/contract-wizard-methods.ts
 var CONTRACT_WIZARD_PATH = "/contract-wizard";
 function buildWizardUrl(baseUrl, flow, params) {
@@ -2360,6 +2417,10 @@ function createFFIDClient(config) {
     fetchWithAuth,
     createError
   });
+  const { getAnalyticsConfig } = createAnalyticsMethods({
+    fetchWithAuth,
+    createError
+  });
   const {
     requestPasswordReset,
     verifyPasswordResetToken,
@@ -2433,6 +2494,7 @@ function createFFIDClient(config) {
     removeMember,
     getProfile,
     updateProfile,
+    getAnalyticsConfig,
     createCheckoutSession,
     createPortalSession,
     listPlans,

package/dist/components/index.cjs

@@ -1,34 +1,34 @@
 'use strict';
 
-var chunkBBXUZS4U_cjs = require('../chunk-BBXUZS4U.cjs');
+var chunkHUU4Q5VH_cjs = require('../chunk-HUU4Q5VH.cjs');
 
 
 
 Object.defineProperty(exports, "FFIDAnnouncementBadge", {
   enumerable: true,
-  get: function () { return chunkBBXUZS4U_cjs.FFIDAnnouncementBadge; }
+  get: function () { return chunkHUU4Q5VH_cjs.FFIDAnnouncementBadge; }
 });
 Object.defineProperty(exports, "FFIDAnnouncementList", {
   enumerable: true,
-  get: function () { return chunkBBXUZS4U_cjs.FFIDAnnouncementList; }
+  get: function () { return chunkHUU4Q5VH_cjs.FFIDAnnouncementList; }
 });
 Object.defineProperty(exports, "FFIDInquiryForm", {
   enumerable: true,
-  get: function () { return chunkBBXUZS4U_cjs.FFIDInquiryForm; }
+  get: function () { return chunkHUU4Q5VH_cjs.FFIDInquiryForm; }
 });
 Object.defineProperty(exports, "FFIDLoginButton", {
   enumerable: true,
-  get: function () { return chunkBBXUZS4U_cjs.FFIDLoginButton; }
+  get: function () { return chunkHUU4Q5VH_cjs.FFIDLoginButton; }
 });
 Object.defineProperty(exports, "FFIDOrganizationSwitcher", {
   enumerable: true,
-  get: function () { return chunkBBXUZS4U_cjs.FFIDOrganizationSwitcher; }
+  get: function () { return chunkHUU4Q5VH_cjs.FFIDOrganizationSwitcher; }
 });
 Object.defineProperty(exports, "FFIDSubscriptionBadge", {
   enumerable: true,
-  get: function () { return chunkBBXUZS4U_cjs.FFIDSubscriptionBadge; }
+  get: function () { return chunkHUU4Q5VH_cjs.FFIDSubscriptionBadge; }
 });
 Object.defineProperty(exports, "FFIDUserMenu", {
   enumerable: true,
-  get: function () { return chunkBBXUZS4U_cjs.FFIDUserMenu; }
+  get: function () { return chunkHUU4Q5VH_cjs.FFIDUserMenu; }
 });

package/dist/components/index.d.cts

@@ -1,3 +1,3 @@
-export { M as FFIDAnnouncementBadge, al as FFIDAnnouncementBadgeClassNames, am as FFIDAnnouncementBadgeProps, N as FFIDAnnouncementList, an as FFIDAnnouncementListClassNames, ao as FFIDAnnouncementListProps, V as FFIDInquiryForm, W as FFIDInquiryFormCategoryItem, X as FFIDInquiryFormClassNames, Y as FFIDInquiryFormOrganization, Z as FFIDInquiryFormPlaceholderContext, _ as FFIDInquiryFormPrefill, $ as FFIDInquiryFormProps, a0 as FFIDInquiryFormSubmitData, a1 as FFIDInquiryFormSubmitResult, a3 as FFIDLoginButton, ap as FFIDLoginButtonProps, a9 as FFIDOrganizationSwitcher, aq as FFIDOrganizationSwitcherClassNames, ar as FFIDOrganizationSwitcherProps, ac as FFIDSubscriptionBadge, as as FFIDSubscriptionBadgeClassNames, at as FFIDSubscriptionBadgeProps, ae as FFIDUserMenu, au as FFIDUserMenuClassNames, av as FFIDUserMenuProps } from '../index-0D2vYSLq.cjs';
+export { N as FFIDAnnouncementBadge, am as FFIDAnnouncementBadgeClassNames, an as FFIDAnnouncementBadgeProps, O as FFIDAnnouncementList, ao as FFIDAnnouncementListClassNames, ap as FFIDAnnouncementListProps, W as FFIDInquiryForm, X as FFIDInquiryFormCategoryItem, Y as FFIDInquiryFormClassNames, Z as FFIDInquiryFormOrganization, _ as FFIDInquiryFormPlaceholderContext, $ as FFIDInquiryFormPrefill, a0 as FFIDInquiryFormProps, a1 as FFIDInquiryFormSubmitData, a2 as FFIDInquiryFormSubmitResult, a4 as FFIDLoginButton, aq as FFIDLoginButtonProps, aa as FFIDOrganizationSwitcher, ar as FFIDOrganizationSwitcherClassNames, as as FFIDOrganizationSwitcherProps, ad as FFIDSubscriptionBadge, at as FFIDSubscriptionBadgeClassNames, au as FFIDSubscriptionBadgeProps, af as FFIDUserMenu, av as FFIDUserMenuClassNames, aw as FFIDUserMenuProps } from '../index-Dr5G9HQ4.cjs';
 import 'react/jsx-runtime';
 import 'react';

package/dist/components/index.d.ts

@@ -1,3 +1,3 @@
-export { M as FFIDAnnouncementBadge, al as FFIDAnnouncementBadgeClassNames, am as FFIDAnnouncementBadgeProps, N as FFIDAnnouncementList, an as FFIDAnnouncementListClassNames, ao as FFIDAnnouncementListProps, V as FFIDInquiryForm, W as FFIDInquiryFormCategoryItem, X as FFIDInquiryFormClassNames, Y as FFIDInquiryFormOrganization, Z as FFIDInquiryFormPlaceholderContext, _ as FFIDInquiryFormPrefill, $ as FFIDInquiryFormProps, a0 as FFIDInquiryFormSubmitData, a1 as FFIDInquiryFormSubmitResult, a3 as FFIDLoginButton, ap as FFIDLoginButtonProps, a9 as FFIDOrganizationSwitcher, aq as FFIDOrganizationSwitcherClassNames, ar as FFIDOrganizationSwitcherProps, ac as FFIDSubscriptionBadge, as as FFIDSubscriptionBadgeClassNames, at as FFIDSubscriptionBadgeProps, ae as FFIDUserMenu, au as FFIDUserMenuClassNames, av as FFIDUserMenuProps } from '../index-0D2vYSLq.js';
+export { N as FFIDAnnouncementBadge, am as FFIDAnnouncementBadgeClassNames, an as FFIDAnnouncementBadgeProps, O as FFIDAnnouncementList, ao as FFIDAnnouncementListClassNames, ap as FFIDAnnouncementListProps, W as FFIDInquiryForm, X as FFIDInquiryFormCategoryItem, Y as FFIDInquiryFormClassNames, Z as FFIDInquiryFormOrganization, _ as FFIDInquiryFormPlaceholderContext, $ as FFIDInquiryFormPrefill, a0 as FFIDInquiryFormProps, a1 as FFIDInquiryFormSubmitData, a2 as FFIDInquiryFormSubmitResult, a4 as FFIDLoginButton, aq as FFIDLoginButtonProps, aa as FFIDOrganizationSwitcher, ar as FFIDOrganizationSwitcherClassNames, as as FFIDOrganizationSwitcherProps, ad as FFIDSubscriptionBadge, at as FFIDSubscriptionBadgeClassNames, au as FFIDSubscriptionBadgeProps, af as FFIDUserMenu, av as FFIDUserMenuClassNames, aw as FFIDUserMenuProps } from '../index-Dr5G9HQ4.js';
 import 'react/jsx-runtime';
 import 'react';

package/dist/components/index.js

@@ -1 +1 @@
-export { FFIDAnnouncementBadge, FFIDAnnouncementList, FFIDInquiryForm, FFIDLoginButton, FFIDOrganizationSwitcher, FFIDSubscriptionBadge, FFIDUserMenu } from '../chunk-SXYB5QM3.js';
+export { FFIDAnnouncementBadge, FFIDAnnouncementList, FFIDInquiryForm, FFIDLoginButton, FFIDOrganizationSwitcher, FFIDSubscriptionBadge, FFIDUserMenu } from '../chunk-I7NEMG52.js';