@feelflow/ffid-sdk 12.2.2 → 13.0.1

package/README.md

@@ -20,6 +20,28 @@ yarn add @feelflow/ffid-sdk
 pnpm add @feelflow/ffid-sdk
 ```
 
+### 必要な Node.js のバージョン（13.0.0〜）
+
+13.0.0 以降は **Node.js 26.12.1 以上**が必要です（`engines.node: ">=26.12.1"`）。Node 18 / 20 はサポート終了済みで、22 / 24 も外して FeelFlow の全サービスを Node 26 に統一しています。下限の 26.12.1 は 2026 年 10 月の Node セキュリティリリースです。
+
+利用側は次の順で移行してください。
+
+1. サービスの実行環境（ローカル・CI・Vercel 等の配備先）を Node 26.12.1 以上へ移す
+2. その後に `@feelflow/ffid-sdk` を `^13.0.1` へ上げる（13.0.1 は API キーを載せた要求が 3xx を追従しないようにした修正を含みます。詳細は [CHANGELOG](./CHANGELOG.md) の 13.0.1）
+
+Node 26.12.1 未満の環境（26.0〜26.12.0 を含む）で 13 を入れると npm は `EBADENGINE` の警告を出し（`engine-strict=true` ならインストールを拒否します）、動作は保証しません。Node を上げられないサービスは 12.x に留めてください。
+
+13.0.0 では、ほかに代理店 API（`@feelflow/ffid-sdk/agency`）から次を外しています。どれも 12.x の時点で非推奨・保存されない・呼ぶと失敗する、のいずれかだったものです。
+
+- 非推奨の markup 課金方式: `FFIDAgencyBillingType` の `'markup'` と、`defaultMarkupRate` / `defaultMarkupFixed` / `markupRate` / `markupFixed`（型からは外しましたが、FFID 側で markup の代理店が残っている間は応答に `'markup'` が届きえます。網羅的な `switch` には `default` を残してください）
+- `updateBranding()` の引数の `logoUrl` / `faviconUrl`（引数の型は `FFIDUpdateAgencyBrandingRequest`。ロゴとファビコンは `uploadAsset()` で変える）
+- 代理店クライアントの `getMembers()` / `addMember()` / `updateMember()` / `removeMember()`（FFID 側の route が無く失敗していた）。代理店のロールは代理店の実体である組織でのロールから導出されるので、メンバーは下の「Organization member management」の組織メンバー API に、`getAgency()` の応答の `organizationId`（13.0.0 で型に追加）を渡して管理する。`linkOrganization()` で紐付けた顧客組織の ID ではありません。⚠️ FFID は代理店そのものを応答の `data` に入れて返すので、値は `result.data.organizationId` にあります（SDK の型は `{ agency }` と包んだ形で、実際と食い違っています。#7177 で直します）
+- 代理店クライアントの `createSubAgency()`（FFID が常に `SUB_AGENCY_CREATION_REMOVED` を返し、必ず失敗していた。サブ代理店の新規作成は廃止）
+
+また、`FFIDAgencyErrorCode` に FFID の代理店のエラーコード表の全値（`UNKNOWN_SETTINGS_KEY` / `INVALID_FIELD_TYPE` / `MISSING_REQUIRED_FIELD` など 88 個）を加えました。閉じた union への追加なので、網羅的な `switch` や `Record<FFIDAgencyErrorCode, …>` には分岐・キーの追加が要ります。表の外のコード（共通層の `METHOD_NOT_ALLOWED` など）も届きうるので、`default` は残してください。
+
+移行手順は [CHANGELOG](./CHANGELOG.md) の 13.0.0 を参照してください。
+
 ## 統合ガイド
 
 ### ニュースレター登録・目的別停止（12.2.0）
@@ -509,7 +531,7 @@ await ffid.updateMemberRole({
 
 - `addMember` は既存 FFID ユーザーを active member として追加します。招待メール送信や token 発行は行いません。
 - `role` は `admin` / `member` / `viewer` のみ指定可能です。`owner` は追加・昇格 API では扱いません。
-- agency client と同じ呼び味が必要な場合は `ffid.addMember(organizationId, { email, role })` も使えます。
+- 位置引数の形 `ffid.addMember(organizationId, { email, role })` も使えます。12.x までの代理店クライアントの `addMember(agencyId, …)` と形は同じですが、第 1 引数は組織の ID（代理店なら `getAgency()` の応答の `data.organizationId`）で、`role` は上の 3 つだけです（旧代理店ロールの `sales` / `support` はありません）。
 - 未登録の人を招待する（招待メールと受諾リンクを FFID が送る）ときは `inviteMember({ organizationId, email, role, inviterUserId })` を使います。`inviterUserId` は、サービスで招待を操作した人の FFID ユーザー ID です。FFID の「保留中の招待」と招待メールに、その人が招待者として出ます。
   - service-key モードでは `inviterUserId` を渡してください。その人が対象の組織の owner / admin でなければ 403 `FORBIDDEN`（`details.reason: 'inviter_not_organization_admin'`）で、招待は作られません。省略すると従来どおり組織の owner が招待者になり、メールの招待者名は `service:<serviceCode>` です。
   - token モードでは省略します（ログイン中の利用者が招待者になります）。別の人の ID を渡すと 400 `VALIDATION_ERROR` です。

package/dist/agency/index.cjs

@@ -1,5 +1,6 @@
 'use strict';
 
+var chunkD6CCHTHL_cjs = require('../chunk-D6CCHTHL.cjs');
 var chunkMDHKSVLP_cjs = require('../chunk-MDHKSVLP.cjs');
 
 // src/agency/ffid-agency-client.ts
@@ -113,35 +114,6 @@ function createFFIDAgencyClient(config = {}) {
       body: JSON.stringify(data)
     });
   }
-  async function getMembers(agencyId) {
-    const err = validateIds([agencyId, "agencyId"]);
-    if (err) return err;
-    return fetchWithCredentials(`/${encodeURIComponent(agencyId)}/members`);
-  }
-  async function addMember(agencyId, data) {
-    const err = validateIds([agencyId, "agencyId"]);
-    if (err) return err;
-    return fetchWithCredentials(`/${encodeURIComponent(agencyId)}/members`, {
-      method: "POST",
-      body: JSON.stringify(data)
-    });
-  }
-  async function updateMember(agencyId, userId, data) {
-    const err = validateIds([agencyId, "agencyId"], [userId, "userId"]);
-    if (err) return err;
-    return fetchWithCredentials(
-      `/${encodeURIComponent(agencyId)}/members/${encodeURIComponent(userId)}`,
-      { method: "PUT", body: JSON.stringify(data) }
-    );
-  }
-  async function removeMember(agencyId, userId) {
-    const err = validateIds([agencyId, "agencyId"], [userId, "userId"]);
-    if (err) return err;
-    return fetchWithCredentials(
-      `/${encodeURIComponent(agencyId)}/members/${encodeURIComponent(userId)}`,
-      { method: "DELETE" }
-    );
-  }
   async function getOrganizations(agencyId) {
     const err = validateIds([agencyId, "agencyId"]);
     if (err) return err;
@@ -176,14 +148,6 @@ function createFFIDAgencyClient(config = {}) {
     if (err) return err;
     return fetchWithCredentials(`/${encodeURIComponent(agencyId)}/sub-agencies`);
   }
-  async function createSubAgency(agencyId, data) {
-    const err = validateIds([agencyId, "agencyId"]);
-    if (err) return err;
-    return fetchWithCredentials(`/${encodeURIComponent(agencyId)}/sub-agencies`, {
-      method: "POST",
-      body: JSON.stringify(data)
-    });
-  }
   async function getHierarchy(agencyId) {
     const err = validateIds([agencyId, "agencyId"]);
     if (err) return err;
@@ -289,11 +253,6 @@ function createFFIDAgencyClient(config = {}) {
     getAgencies,
     getAgency,
     updateAgency,
-    // Members
-    getMembers,
-    addMember,
-    updateMember,
-    removeMember,
     // Organizations
     getOrganizations,
     linkOrganization,
@@ -301,7 +260,6 @@ function createFFIDAgencyClient(config = {}) {
     provisionOrganization,
     // Sub-Agencies
     getSubAgencies,
-    createSubAgency,
     // Hierarchy
     getHierarchy,
     // Branding
@@ -362,6 +320,7 @@ function createFFIDAgencyServerClient(config) {
     try {
       response = await fetch(url, {
         method: "POST",
+        ...chunkD6CCHTHL_cjs.CREDENTIAL_REDIRECT_INIT,
         headers: {
           "Content-Type": "application/json",
           [AGENCY_API_KEY_HEADER]: apiKey
@@ -379,6 +338,11 @@ function createFFIDAgencyServerClient(config) {
         }
       };
     }
+    if (chunkD6CCHTHL_cjs.isRedirectResponse(response)) {
+      return {
+        error: { code: FFID_AGENCY_ERROR_CODES.NETWORK_ERROR, message: chunkD6CCHTHL_cjs.credentialRedirectMessage(response) }
+      };
+    }
     let payload;
     try {
       payload = await response.json();

package/dist/agency/index.d.cts

@@ -1,12 +1,26 @@
 export { D as DEFAULT_API_BASE_URL } from '../constants-Ce2eXQtB.cjs';
 
+/**
+ * FFID の代理店 API が返すエラーコード（13.0.0〜）。
+ *
+ * FFID 本体の `src/lib/agencies/errors.ts` の `AGENCY_ERROR_CODES` の値を、定義順のまま写したもの。
+ * 食い違いは root の `npm run sdk:verify-sync`（`scripts/verify-sdk-constants-sync.ts`）が落とす。
+ * サーバーにコードを足したら、同じ PR でここにも足す（足さないと上の同期検査が落ちる）。閉じた union への
+ * 追加は網羅的な `switch` / `Record` を書く利用者には破壊的になるので、SDK の版の上げ方は FFID の
+ * GIT_WORKFLOW §8.2 に従って判断する。
+ *
+ * 型（`FFIDAgencyServerErrorCode`）を導くためだけに使い、公開 export にはしない。
+ */
+declare const FFID_AGENCY_SERVER_ERROR_CODES: readonly ["UNAUTHORIZED", "FORBIDDEN", "NOT_AGENCY_MEMBER", "NOT_AGENCY_ADMIN", "NOT_AGENCY_OWNER", "NOT_PLATFORM_OWNER", "SUB_AGENCY_CREATION_REMOVED", "MISSING_REQUIRED_FIELD", "INVALID_AGENCY_NAME", "INVALID_EMAIL", "INVALID_ROLE", "INVALID_AGENCY_ID", "INVALID_MEMBER_ID", "INVALID_ORGANIZATION_ID", "INVALID_COMMISSION_RATE", "INVALID_BILLING_OVERRIDE", "INVALID_STATUS", "INVALID_JSON", "AGENCY_NOT_FOUND", "MEMBER_NOT_FOUND", "USER_NOT_FOUND", "ORGANIZATION_NOT_FOUND", "MAX_HIERARCHY_DEPTH_EXCEEDED", "PARENT_AGENCY_NOT_FOUND", "SUB_AGENCY_NOT_FOUND", "INACTIVE_PARENT_AGENCY", "CIRCULAR_HIERARCHY_DETECTED", "MEMBER_ALREADY_EXISTS", "ORGANIZATION_ALREADY_LINKED", "ORGANIZATION_IS_AGENCY", "ORGANIZATION_LINKED_TO_OTHER_AGENCY", "CANNOT_REMOVE_OWNER", "CANNOT_CHANGE_OWNER_ROLE", "AGENCY_SLUG_EXISTS", "INVALID_BILLING_TYPE", "INVALID_FIELD_TYPE", "INVALID_INVITE_LINK_LABEL", "INVALID_SEARCH_QUERY", "UNKNOWN_SETTINGS_KEY", "BILLING_TYPE_CHANGE_NOT_ALLOWED", "STRIPE_CUSTOMER_REQUIRED", "INVOICE_NOT_FOUND", "INVALID_PAYMENT_TERMS", "INVALID_WHOLESALE_DISCOUNT_RATE", "NO_BILLABLE_ORGANIZATIONS", "INVOICE_FINALIZED_NOT_RECORDED", "INVOICE_SEND_FAILED", "INVALID_PERIOD", "INVALID_INVITE_LINK_LIMIT", "INVITE_LINK_EXPIRED", "INVITE_LINK_NOT_FOUND", "INVITE_LINK_REVOKED", "INVITE_LINK_EXHAUSTED", "ORGANIZATION_SLUG_CONFLICT", "INVALID_ORGANIZATION_SLUG", "INVALID_ORGANIZATION_NAME", "INVALID_BILLING_EMAIL", "INVALID_IDEMPOTENCY_KEY", "IDEMPOTENCY_KEY_REUSED", "ORGANIZATION_SLUG_RESERVED", "OWNER_ACCOUNT_UNAVAILABLE", "OWNER_ALREADY_SIGNED_IN", "OWNER_EMAIL_UNDELIVERABLE", "WELCOME_EMAIL_RECIPIENT_AMBIGUOUS", "WELCOME_EMAIL_COOLDOWN", "WELCOME_EMAIL_SEND_FAILED", "MISSING_API_KEY", "INVALID_API_KEY_FORMAT", "INVALID_API_KEY", "REVOKED_API_KEY", "EXPIRED_API_KEY", "SERVICE_UNAVAILABLE", "API_KEY_NOT_FOUND", "INVALID_API_KEY_ID", "INVALID_API_KEY_NAME", "INVALID_API_KEY_SCOPE", "INVALID_API_KEY_EXPIRY", "INVALID_WEBHOOK_URL", "INVALID_COLOR", "INVALID_DOMAIN", "DOMAIN_ALREADY_IN_USE", "DOMAIN_VERIFICATION_FAILED", "DOMAIN_NOT_CONFIGURED", "INVALID_COMPANY_NAME", "INVALID_FROM_EMAIL", "FILE_TOO_LARGE", "INVALID_FILE_TYPE", "FILE_UPLOAD_FAILED", "VERCEL_API_ERROR", "INTERNAL_ERROR", "SLUG_GENERATION_EXHAUSTED"];
+
 /**
  * FFID Agency SDK Type Definitions
  *
  * Types for the FeelFlow ID Agency Management SDK.
- * Used for managing agencies, members, organizations, branding,
+ * Used for managing agencies, organizations, branding,
  * domain, email settings, billing, and hierarchy.
  */
+
 /**
  * Configuration for the FFID Agency Client
  */
@@ -31,19 +45,28 @@ type FFIDAgencyStatus = 'active' | 'suspended' | 'inactive';
 /**
  * 代理店の課金方式。
  *
- * `'markup'` は非推奨（FFID #6507）。既存データの値として残している。`updateBilling()` は
- * 互換のため今も `'markup'` を受け付けるが、新しく設定しないこと。受け取った値を網羅的に
- * 扱う箇所では引き続き `'markup'` を扱うこと。
+ * 13.0.0 で非推奨の `'markup'` を外した（FFID #6507 / #6714）。ただし FFID 側の値と列の削除は #6714 で
+ * 別に行うので、それまでは markup の代理店の応答に `'markup'` が届きうる（SDK は応答を実行時に検証しない）。
+ * 受け取った値を網羅的に扱う箇所（`switch` / `Record<FFIDAgencyBillingType, …>` の参照）では、想定外の
+ * 値の分岐（`default`）を残すこと。
  */
-type FFIDAgencyBillingType = 'direct' | 'consolidated' | 'markup';
-type FFIDAgencyMemberRole = 'owner' | 'admin' | 'sales' | 'support';
-type FFIDAgencyMemberStatus = 'active' | 'invited' | 'suspended';
+type FFIDAgencyBillingType = 'direct' | 'consolidated';
 type FFIDAgencyBillingOverride = 'default' | 'direct' | 'exempt';
 type FFIDSslStatus = 'pending' | 'active' | 'failed';
 interface FFIDAgency {
     id: string;
     name: string;
     slug: string;
+    /**
+     * この代理店の実体である組織の ID（FFID #5817。13.0.0 で型に追加。FFID は以前から返している）。
+     * 代理店のロールはこの組織での利用者のロールから導出されるので、代理店のメンバーは
+     * `createFFIDClient()` の組織メンバー API（`listMembers` など）にこの ID を渡して管理する。
+     *
+     * ⚠️ `getAgency()` の応答では、FFID は代理店そのものを `data` に入れて返す（値は
+     * `result.data.organizationId`）。`FFIDAgencyClient.getAgency` の型が宣言する `{ agency }` の形とは
+     * 食い違っている（FFID #7177 で直す）。
+     */
+    organizationId: string;
     isPlatformOwner: boolean;
     parentAgencyId: string | null;
     status: FFIDAgencyStatus;
@@ -65,6 +88,13 @@ interface FFIDAgencyBrandingSettings {
     secondaryColor?: string;
     companyName?: string;
 }
+/**
+ * {@link FFIDAgencyClient.updateBranding} の引数。
+ *
+ * 13.0.0 で `logoUrl` / `faviconUrl` を外した（FFID #6972 / #6714）。FFID は 2 つを保存しないので、
+ * ロゴとファビコンは {@link FFIDAgencyClient.uploadAsset} で変える。
+ */
+type FFIDUpdateAgencyBrandingRequest = Omit<FFIDAgencyBrandingSettings, 'logoUrl' | 'faviconUrl'>;
 interface FFIDAgencyDnsRecord {
     type: string;
     name: string;
@@ -81,23 +111,6 @@ interface FFIDAgencyEmailSettings {
     fromEmail?: string;
     replyTo?: string;
 }
-interface FFIDAgencyMember {
-    userId: string;
-    email: string;
-    displayName: string | null;
-    avatarUrl: string | null;
-    role: FFIDAgencyMemberRole;
-    status: FFIDAgencyMemberStatus;
-    joinedAt: string | null;
-    invitedAt: string | null;
-}
-interface FFIDAddAgencyMemberRequest {
-    email: string;
-    role?: FFIDAgencyMemberRole;
-}
-interface FFIDUpdateAgencyMemberRequest {
-    role: FFIDAgencyMemberRole;
-}
 interface FFIDAgencyOrganization {
     id: string;
     agencyId: string;
@@ -106,10 +119,6 @@ interface FFIDAgencyOrganization {
     organizationSlug: string;
     billingOverride: FFIDAgencyBillingOverride;
     commissionRate: number | null;
-    /** @deprecated markup 課金方式は非推奨（FFID #6507）。帳票用の既存値を読むだけで、更新する API は無い。 */
-    markupRate: number | null;
-    /** @deprecated markup 課金方式は非推奨（FFID #6507）。帳票用の既存値を読むだけで、更新する API は無い。 */
-    markupFixed: number | null;
     /** 組織単位の卸割引率 override（%、0〜100）。null = 代理店デフォルトに従う。 */
     wholesaleDiscountRate: number | null;
     notes: string | null;
@@ -180,11 +189,6 @@ interface FFIDLinkOrganizationRequest {
     wholesaleDiscountRate?: number | null;
     notes?: string;
 }
-interface FFIDCreateSubAgencyRequest {
-    name: string;
-    contactEmail?: string;
-    settings?: FFIDAgencySettings;
-}
 interface FFIDAgencyHierarchyNode {
     agency: FFIDAgency;
     children: FFIDAgencyHierarchyNode[];
@@ -201,10 +205,6 @@ interface FFIDAgencyBillingConfig {
     stripeCustomerId: string | null;
     invoiceEmail: string | null;
     paymentTerms: number | null;
-    /** @deprecated markup 課金方式は非推奨（FFID #6507）。帳票用の既存値を読むだけで、更新する API は無い。 */
-    defaultMarkupRate: number | null;
-    /** @deprecated markup 課金方式は非推奨（FFID #6507）。帳票用の既存値を読むだけで、更新する API は無い。 */
-    defaultMarkupFixed: number | null;
     /** 代理店デフォルト卸割引率（%、0〜100）。null = 未設定（定価請求）。 */
     wholesaleDiscountRate: number | null;
 }
@@ -212,16 +212,6 @@ interface FFIDUpdateAgencyBillingRequest {
     billingType?: FFIDAgencyBillingType;
     invoiceEmail?: string;
     paymentTerms?: number;
-    /**
-     * @deprecated FFID はこの項目を受け付けず、送っても黙って捨てる（FFID #6507）。
-     * markup 課金方式は非推奨で、値を更新する手段は無い。
-     */
-    defaultMarkupRate?: number;
-    /**
-     * @deprecated FFID はこの項目を受け付けず、送っても黙って捨てる（FFID #6507）。
-     * markup 課金方式は非推奨で、値を更新する手段は無い。
-     */
-    defaultMarkupFixed?: number;
     /** 代理店デフォルト卸割引率（%、0〜100）。null で未設定に戻す。 */
     wholesaleDiscountRate?: number | null;
 }
@@ -269,6 +259,10 @@ interface FFIDAgencyClient {
         agencies: FFIDAgency[];
         count: number;
     }>>;
+    /**
+     * ⚠️ FFID は代理店そのものを `data` に入れて返す（`data.agency` ではない）。この型の `{ agency }` は
+     * 実際の応答と食い違っている。代理店クライアントの応答型の総点検は FFID #7177 で 13.x として行う。
+     */
     getAgency(agencyId: string): Promise<FFIDAgencyApiResponse<{
         agency: FFIDAgency;
     }>>;
@@ -281,19 +275,6 @@ interface FFIDAgencyClient {
     updateAgency(agencyId: string, data: FFIDUpdateAgencyRequest): Promise<FFIDAgencyApiResponse<{
         agency: FFIDAgency;
     }>>;
-    getMembers(agencyId: string): Promise<FFIDAgencyApiResponse<{
-        members: FFIDAgencyMember[];
-        count: number;
-    }>>;
-    addMember(agencyId: string, data: FFIDAddAgencyMemberRequest): Promise<FFIDAgencyApiResponse<{
-        member: FFIDAgencyMember;
-    }>>;
-    updateMember(agencyId: string, userId: string, data: FFIDUpdateAgencyMemberRequest): Promise<FFIDAgencyApiResponse<{
-        member: FFIDAgencyMember;
-    }>>;
-    removeMember(agencyId: string, userId: string): Promise<FFIDAgencyApiResponse<{
-        message: string;
-    }>>;
     getOrganizations(agencyId: string): Promise<FFIDAgencyApiResponse<{
         organizations: FFIDAgencyOrganization[];
         count: number;
@@ -318,9 +299,6 @@ interface FFIDAgencyClient {
         agencies: FFIDAgency[];
         count: number;
     }>>;
-    createSubAgency(agencyId: string, data: FFIDCreateSubAgencyRequest): Promise<FFIDAgencyApiResponse<{
-        agency: FFIDAgency;
-    }>>;
     getHierarchy(agencyId: string): Promise<FFIDAgencyApiResponse<FFIDAgencyHierarchyResponse>>;
     getBranding(agencyId: string): Promise<FFIDAgencyApiResponse<{
         branding: FFIDAgencyBrandingSettings;
@@ -329,15 +307,13 @@ interface FFIDAgencyClient {
      * ブランディング（色 2 種・会社名）を更新する。
      *
      * FFID は型にないキーを 400 `UNKNOWN_SETTINGS_KEY` で拒否する（FFID #6972。`error.details.fields`
-     * にキー名）。`logoUrl` / `faviconUrl` は型が許すので受け付けるが、**保存しない** —
-     * ロゴとファビコンは {@link FFIDAgencyClient.uploadAsset} で変える。2 つはこのメソッドの
-     * 引数の型から次の major 版で外す。
+     * にキー名）。`logoUrl` / `faviconUrl` は 13.0.0 で引数の型から外した。FFID は既知のキーとして
+     * 受け付けるが**保存しない** — ロゴとファビコンは {@link FFIDAgencyClient.uploadAsset} で変える。
      *
-     * ⚠️ `error.code` の型（{@link FFIDAgencyErrorCode}）は `UNKNOWN_SETTINGS_KEY` を含まない
-     * （閉じた union にコードを足すのは破壊的変更なので次の major 版で扱う）。実行時には届くので、
-     * 比べるときは `(error.code as string) === 'UNKNOWN_SETTINGS_KEY'` とする。
+     * `UNKNOWN_SETTINGS_KEY` は 13.0.0 で {@link FFIDAgencyErrorCode} に入ったので、
+     * `error.code === 'UNKNOWN_SETTINGS_KEY'` とキャストなしで比べられる。
      */
-    updateBranding(agencyId: string, data: FFIDAgencyBrandingSettings): Promise<FFIDAgencyApiResponse<{
+    updateBranding(agencyId: string, data: FFIDUpdateAgencyBrandingRequest): Promise<FFIDAgencyApiResponse<{
         branding: FFIDAgencyBrandingSettings;
     }>>;
     uploadAsset(agencyId: string, file: File, type: FFIDAgencyAssetType): Promise<FFIDAgencyApiResponse<{
@@ -377,7 +353,21 @@ interface FFIDAgencyClient {
     getRevenue(agencyId: string): Promise<FFIDAgencyApiResponse<FFIDAgencyRevenue>>;
 }
 type FFIDAgencySdkErrorCode = 'NETWORK_ERROR' | 'PARSE_ERROR' | 'UNKNOWN_ERROR' | 'VALIDATION_ERROR';
-type FFIDAgencyServerErrorCode = 'UNAUTHORIZED' | 'FORBIDDEN' | 'NOT_FOUND' | 'VALIDATION_ERROR' | 'INTERNAL_ERROR' | 'CONFLICT';
+/**
+ * FFID の代理店 API が返すエラーコード。
+ *
+ * 13.0.0 から FFID の代理店のエラーコード表 `AGENCY_ERROR_CODES` の全値（`./server-error-codes`）を含む。
+ * 12.x までは 6 個だけで、`UNKNOWN_SETTINGS_KEY`（FFID #6972）や `INVALID_FIELD_TYPE` /
+ * `MISSING_REQUIRED_FIELD` など、FFID が実際に返すコードが入っていなかった。
+ *
+ * ⚠️ 代理店 API の応答に載るのはこの表のコードだけではない。共通層の 405 `METHOD_NOT_ALLOWED` や、
+ * 請求書の 500 `invalid_db_timestamp` などは表の外で、SDK はそのまま `error.code` に通す。
+ * `error.code` を網羅的に扱う箇所では、想定外の値の分岐（`default`）を残すこと。
+ *
+ * `NOT_FOUND` / `VALIDATION_ERROR` / `CONFLICT` は 12.x から型にあるが、`AGENCY_ERROR_CODES` に無い
+ * （`VALIDATION_ERROR` は SDK 自身の入力検査のコードとしても使う）。互換のため残している。
+ */
+type FFIDAgencyServerErrorCode = (typeof FFID_AGENCY_SERVER_ERROR_CODES)[number] | 'NOT_FOUND' | 'VALIDATION_ERROR' | 'CONFLICT';
 type FFIDAgencyErrorCode = FFIDAgencySdkErrorCode | FFIDAgencyServerErrorCode;
 interface FFIDAgencyServerError {
     code: FFIDAgencyErrorCode;
@@ -435,10 +425,11 @@ type FFIDAgencyApiResponse<T> = {
 /**
  * このクライアントが返しうるエラーコード。
  *
- * `FFIDAgencyErrorCode`（SDK 内部で定義した閉じた集合）には、サーバーが実際に
- * 返す `ORGANIZATION_SLUG_CONFLICT` / `INVALID_ORGANIZATION_SLUG` /
- * `REVOKED_API_KEY` などが含まれていない。閉じた union のふりをすると、
- * 利用者が書いた exhaustive な `switch` が実行時に全部 `default` に落ちる。
+ * `FFIDAgencyErrorCode`（SDK 内部で定義した閉じた集合）は 13.0.0 から FFID の
+ * `AGENCY_ERROR_CODES` の全値を含む（12.x までは `ORGANIZATION_SLUG_CONFLICT` /
+ * `INVALID_ORGANIZATION_SLUG` / `REVOKED_API_KEY` なども欠けていた）。それでも、
+ * SDK より新しい FFID が足したコードは SDK を上げるまで届きうる。閉じた union のふりを
+ * すると、利用者が書いた exhaustive な `switch` が実行時に `default` に落ちる。
  * **開いた集合であることを型で正直に表す。**
  *
  * ⚠️ `types.ts` の `FFIDAgencyServerErrorCode` とは**別物**。あちらは
@@ -455,9 +446,10 @@ interface FFIDAgencyServerClientError {
 /**
  * サーバークライアントの応答。
  *
- * Cookie クライアントの `FFIDAgencyApiResponse` は `code` が閉じた union だが、
- * それは SDK 内部で作るコードしか載らないため。こちらは**サーバーのコードを
- * そのまま通す**ので、型も開いておく必要がある。
+ * Cookie クライアントの `FFIDAgencyApiResponse` は `code` が閉じた union
+ * （`FFIDAgencyErrorCode`）だが、実際にはサーバーのコードを素通しするので、表の外の
+ * コードも届きうる（`FFIDAgencyServerErrorCode` の注記）。こちらは**サーバーのコードを
+ * そのまま通す**ことを型でも表すため、開いておく。
  */
 type FFIDAgencyServerClientResponse<T> = {
     data: T;
@@ -555,4 +547,4 @@ declare const FFID_AGENCY_ERROR_CODES: {
 declare function createFFIDAgencyClient(config?: FFIDAgencyClientConfig): FFIDAgencyClient;
 
 export { FFID_AGENCY_ERROR_CODES, createFFIDAgencyClient, createFFIDAgencyServerClient };
-export type { FFIDAddAgencyMemberRequest, FFIDAgency, FFIDAgencyApiResponse, FFIDAgencyAssetType, FFIDAgencyBillingConfig, FFIDAgencyBillingOverride, FFIDAgencyBillingSummary, FFIDAgencyBillingType, FFIDAgencyBrandingSettings, FFIDAgencyClient, FFIDAgencyClientConfig, FFIDAgencyDnsRecord, FFIDAgencyDomainSettings, FFIDAgencyEmailSettings, FFIDAgencyError, FFIDAgencyErrorCode, FFIDAgencyHierarchyNode, FFIDAgencyHierarchyResponse, FFIDAgencyInvoice, FFIDAgencyInvoiceStatus, FFIDAgencyLogger, FFIDAgencyMember, FFIDAgencyMemberRole, FFIDAgencyMemberStatus, FFIDAgencyOrganization, FFIDAgencyRevenue, FFIDAgencySdkErrorCode, FFIDAgencyServerClient, FFIDAgencyServerClientConfig, FFIDAgencyServerClientError, FFIDAgencyServerClientErrorCode, FFIDAgencyServerClientResponse, FFIDAgencyServerError, FFIDAgencyServerErrorCode, FFIDAgencyServerResponse, FFIDAgencySettings, FFIDAgencyStatus, FFIDCreateSubAgencyRequest, FFIDLinkOrganizationRequest, FFIDProvisionOrganizationRequest, FFIDProvisionedOrganization, FFIDSetupDomainRequest, FFIDSslStatus, FFIDUpdateAgencyBillingRequest, FFIDUpdateAgencyMemberRequest, FFIDUpdateAgencyRequest, FFIDUpdateEmailSettingsRequest, FFIDWelcomeEmailOutcome };
+export type { FFIDAgency, FFIDAgencyApiResponse, FFIDAgencyAssetType, FFIDAgencyBillingConfig, FFIDAgencyBillingOverride, FFIDAgencyBillingSummary, FFIDAgencyBillingType, FFIDAgencyBrandingSettings, FFIDAgencyClient, FFIDAgencyClientConfig, FFIDAgencyDnsRecord, FFIDAgencyDomainSettings, FFIDAgencyEmailSettings, FFIDAgencyError, FFIDAgencyErrorCode, FFIDAgencyHierarchyNode, FFIDAgencyHierarchyResponse, FFIDAgencyInvoice, FFIDAgencyInvoiceStatus, FFIDAgencyLogger, FFIDAgencyOrganization, FFIDAgencyRevenue, FFIDAgencySdkErrorCode, FFIDAgencyServerClient, FFIDAgencyServerClientConfig, FFIDAgencyServerClientError, FFIDAgencyServerClientErrorCode, FFIDAgencyServerClientResponse, FFIDAgencyServerError, FFIDAgencyServerErrorCode, FFIDAgencyServerResponse, FFIDAgencySettings, FFIDAgencyStatus, FFIDLinkOrganizationRequest, FFIDProvisionOrganizationRequest, FFIDProvisionedOrganization, FFIDSetupDomainRequest, FFIDSslStatus, FFIDUpdateAgencyBillingRequest, FFIDUpdateAgencyBrandingRequest, FFIDUpdateAgencyRequest, FFIDUpdateEmailSettingsRequest, FFIDWelcomeEmailOutcome };