@feelflow/ffid-sdk 5.31.1 → 6.0.0

package/dist/agency/index.cjs

@@ -163,6 +163,14 @@ function createFFIDAgencyClient(config = {}) {
       { method: "DELETE" }
     );
   }
+  async function provisionOrganization(agencyId, data) {
+    const err = validateIds([agencyId, "agencyId"]);
+    if (err) return err;
+    return fetchWithCredentials(`/${encodeURIComponent(agencyId)}/organizations/provision`, {
+      method: "POST",
+      body: JSON.stringify(data)
+    });
+  }
   async function getSubAgencies(agencyId) {
     const err = validateIds([agencyId, "agencyId"]);
     if (err) return err;
@@ -290,6 +298,7 @@ function createFFIDAgencyClient(config = {}) {
     getOrganizations,
     linkOrganization,
     unlinkOrganization,
+    provisionOrganization,
     // Sub-Agencies
     getSubAgencies,
     createSubAgency,
@@ -316,9 +325,112 @@ function createFFIDAgencyClient(config = {}) {
   };
 }
 
+// src/agency/ffid-agency-server-client.ts
+var API_PREFIX2 = "/api/v1/ext/agencies";
+var AGENCY_API_KEY_HEADER = "X-Agency-Api-Key";
+var SDK_LOG_PREFIX2 = "[FFID Agency Server SDK]";
+var noopLogger2 = {
+  debug: () => {
+  },
+  info: () => {
+  },
+  warn: () => {
+  },
+  error: () => {
+  }
+};
+var consoleLogger2 = {
+  debug: (...args) => console.debug(SDK_LOG_PREFIX2, ...args),
+  info: (...args) => console.info(SDK_LOG_PREFIX2, ...args),
+  warn: (...args) => console.warn(SDK_LOG_PREFIX2, ...args),
+  error: (...args) => console.error(SDK_LOG_PREFIX2, ...args)
+};
+var DEFAULT_TIMEOUT_MS = 3e4;
+function createFFIDAgencyServerClient(config) {
+  const apiKey = config.apiKey?.trim() ?? "";
+  if (apiKey === "") {
+    throw new Error(
+      "createFFIDAgencyServerClient: apiKey is required (set it from an environment variable, never in browser code)"
+    );
+  }
+  const baseUrl = config.apiBaseUrl ?? chunkMDHKSVLP_cjs.DEFAULT_API_BASE_URL;
+  const logger = config.logger ?? (config.debug ? consoleLogger2 : noopLogger2);
+  const timeoutMs = config.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  async function request(endpoint, body) {
+    const url = `${baseUrl}${API_PREFIX2}${endpoint}`;
+    let response;
+    try {
+      response = await fetch(url, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          [AGENCY_API_KEY_HEADER]: apiKey
+        },
+        body: JSON.stringify(body),
+        signal: AbortSignal.timeout(timeoutMs)
+      });
+    } catch (error) {
+      logger.error("Network error:", { url, error });
+      return {
+        error: {
+          code: FFID_AGENCY_ERROR_CODES.NETWORK_ERROR,
+          // タイムアウトも組織が作られた後かもしれない。再試行の前に確認を促す。
+          message: `${error instanceof Error ? error.message : "\u30CD\u30C3\u30C8\u30EF\u30FC\u30AF\u30A8\u30E9\u30FC\u304C\u767A\u751F\u3057\u307E\u3057\u305F"}\u3002\u7D44\u7E54\u304C\u4F5C\u6210\u3055\u308C\u305F\u53EF\u80FD\u6027\u304C\u3042\u308B\u305F\u3081\u3001\u518D\u8A66\u884C\u524D\u306B\u7D44\u7E54\u4E00\u89A7\u3092\u78BA\u8A8D\u3057\u3066\u304F\u3060\u3055\u3044`
+        }
+      };
+    }
+    let payload;
+    try {
+      payload = await response.json();
+    } catch (parseError) {
+      logger.error("Parse error:", { url, status: response.status, parseError });
+      return {
+        error: {
+          code: FFID_AGENCY_ERROR_CODES.PARSE_ERROR,
+          message: `\u30B5\u30FC\u30D0\u30FC\u304B\u3089\u4E0D\u6B63\u306A\u30EC\u30B9\u30DD\u30F3\u30B9\u3092\u53D7\u4FE1\u3057\u307E\u3057\u305F (status: ${response.status})\u3002\u7D44\u7E54\u304C\u4F5C\u6210\u3055\u308C\u305F\u53EF\u80FD\u6027\u304C\u3042\u308B\u305F\u3081\u3001\u518D\u8A66\u884C\u524D\u306B\u7D44\u7E54\u4E00\u89A7\u3092\u78BA\u8A8D\u3057\u3066\u304F\u3060\u3055\u3044`
+        }
+      };
+    }
+    if (payload === null || typeof payload !== "object") {
+      logger.error("Malformed response body:", { url, status: response.status });
+      return {
+        error: {
+          code: FFID_AGENCY_ERROR_CODES.PARSE_ERROR,
+          message: `\u30B5\u30FC\u30D0\u30FC\u304B\u3089\u4E0D\u6B63\u306A\u30EC\u30B9\u30DD\u30F3\u30B9\u3092\u53D7\u4FE1\u3057\u307E\u3057\u305F (status: ${response.status})`
+        }
+      };
+    }
+    const parsed = payload;
+    if (!response.ok || parsed.success !== true) {
+      return {
+        error: {
+          code: parsed.error?.code ?? FFID_AGENCY_ERROR_CODES.UNKNOWN_ERROR,
+          message: parsed.error?.message ?? `\u30EA\u30AF\u30A8\u30B9\u30C8\u304C\u5931\u6557\u3057\u307E\u3057\u305F (${response.status})`
+        }
+      };
+    }
+    if (parsed.data === void 0) {
+      logger.error("Missing data in successful response:", { url });
+      return {
+        error: {
+          code: FFID_AGENCY_ERROR_CODES.UNKNOWN_ERROR,
+          message: "\u30B5\u30FC\u30D0\u30FC\u304B\u3089\u30C7\u30FC\u30BF\u304C\u8FD4\u3055\u308C\u307E\u305B\u3093\u3067\u3057\u305F"
+        }
+      };
+    }
+    return { data: parsed.data };
+  }
+  return {
+    async provisionCustomerOrganization(data) {
+      return request("/organizations/provision", data);
+    }
+  };
+}
+
 Object.defineProperty(exports, "DEFAULT_API_BASE_URL", {
   enumerable: true,
   get: function () { return chunkMDHKSVLP_cjs.DEFAULT_API_BASE_URL; }
 });
 exports.FFID_AGENCY_ERROR_CODES = FFID_AGENCY_ERROR_CODES;
 exports.createFFIDAgencyClient = createFFIDAgencyClient;
+exports.createFFIDAgencyServerClient = createFFIDAgencyServerClient;

package/dist/agency/index.d.cts

@@ -1,4 +1,4 @@
-export { D as DEFAULT_API_BASE_URL } from '../constants-D61jqRIO.cjs';
+export { D as DEFAULT_API_BASE_URL } from '../constants-Ce2eXQtB.cjs';
 
 /**
  * FFID Agency SDK Type Definitions
@@ -101,13 +101,60 @@ interface FFIDAgencyOrganization {
     commissionRate: number | null;
     markupRate: number | null;
     markupFixed: number | null;
+    /** 組織単位の卸割引率 override（%、0〜100）。null = 代理店デフォルトに従う。 */
+    wholesaleDiscountRate: number | null;
     notes: string | null;
     createdAt: string;
 }
+/**
+ * 顧客組織の代行作成リクエスト（#5143）。
+ */
+interface FFIDProvisionOrganizationRequest {
+    /** 組織名 */
+    name: string;
+    /** 顧客担当者のメールアドレス。この人が組織の owner になる */
+    ownerEmail: string;
+    /**
+     * 組織 ID（slug）。半角英小文字・数字・ハイフンのみ。
+     *
+     * 省略すると組織名から自動生成される。**指定した場合、既存組織と衝突すると
+     * 409 が返り、組織は作成されない**（自動で `acme-2` のような別名に
+     * すり替えたりはしない。代理店が顧客に伝えた URL と食い違うため）。
+     */
+    slug?: string;
+    /** 請求先メールアドレス */
+    billingEmail?: string;
+}
+/** 案内メールの送信結果。組織作成の成否とは独立している。 */
+type FFIDWelcomeEmailOutcome = 'sent' | 'failed';
+/**
+ * 代行作成の結果（#5143）。
+ */
+interface FFIDProvisionedOrganization {
+    id: string;
+    name: string;
+    slug: string;
+    billingEmail: string | null;
+    createdAt: string;
+    /** owner になった顧客担当者 */
+    ownerUserId: string;
+    ownerEmail: string;
+    /** 顧客が既に FeelFlow ID のアカウントを持っていたか */
+    ownerExisted: boolean;
+    /**
+     * パスワード設定の案内メールの結果。
+     *
+     * `'failed'` でも**組織と紐付けは作成済み**（メール失敗で巻き戻さない）。
+     * この場合は顧客がログインできないので、代理店から再送を促すこと。
+     */
+    welcomeEmail: FFIDWelcomeEmailOutcome;
+}
 interface FFIDLinkOrganizationRequest {
     organizationId: string;
     billingOverride?: FFIDAgencyBillingOverride;
     commissionRate?: number;
+    /** 組織単位の卸割引率 override（%、0〜100）。省略時 / null は代理店デフォルトに従う。 */
+    wholesaleDiscountRate?: number | null;
     notes?: string;
 }
 interface FFIDCreateSubAgencyRequest {
@@ -133,6 +180,8 @@ interface FFIDAgencyBillingConfig {
     paymentTerms: number | null;
     defaultMarkupRate: number | null;
     defaultMarkupFixed: number | null;
+    /** 代理店デフォルト卸割引率（%、0〜100）。null = 未設定（定価請求）。 */
+    wholesaleDiscountRate: number | null;
 }
 interface FFIDUpdateAgencyBillingRequest {
     billingType?: FFIDAgencyBillingType;
@@ -140,6 +189,8 @@ interface FFIDUpdateAgencyBillingRequest {
     paymentTerms?: number;
     defaultMarkupRate?: number;
     defaultMarkupFixed?: number;
+    /** 代理店デフォルト卸割引率（%、0〜100）。null で未設定に戻す。 */
+    wholesaleDiscountRate?: number | null;
 }
 interface FFIDAgencyBillingSummary {
     agencyId: string;
@@ -214,6 +265,16 @@ interface FFIDAgencyClient {
     unlinkOrganization(agencyId: string, orgId: string): Promise<FFIDAgencyApiResponse<{
         message: string;
     }>>;
+    /**
+     * 顧客組織を代行作成する（#5143）。
+     *
+     * `linkOrganization` が**既存**組織を紐付けるのに対し、こちらは組織そのものを
+     * 作る。顧客担当者が最初から owner になり、代理店スタッフは組織のメンバーに
+     * ならない。作成後、顧客担当者へパスワード設定の案内メールが送られる。
+     *
+     * 実行できるのは owner / admin / **sales**（support は 403）。
+     */
+    provisionOrganization(agencyId: string, data: FFIDProvisionOrganizationRequest): Promise<FFIDAgencyApiResponse<FFIDProvisionedOrganization>>;
     getSubAgencies(agencyId: string): Promise<FFIDAgencyApiResponse<{
         agencies: FFIDAgency[];
         count: number;
@@ -292,6 +353,120 @@ type FFIDAgencyApiResponse<T> = {
     error: FFIDAgencyError;
 };
 
+/**
+ * 代理店のサーバー間クライアント（API キー認証）
+ *
+ * ⚠️ **サーバーサイド専用。ブラウザで使ってはいけない。**
+ *
+ * このクライアントが使う API キーは、
+ * - 任意のメールアドレスに対して FFID アカウントを作れる
+ * - 顧客組織を代理店に紐付ける = **売上の計上先を決める**
+ *
+ * ため、ブラウザに出た時点で第三者が代理店になりすませる。
+ *
+ * ## なぜ `createFFIDAgencyClient` と別なのか
+ *
+ * あちらは Cookie 認証（`credentials: 'include'`）でブラウザから使える。
+ * 同じファクトリに「キーを渡すとキー認証になる」モードを足すと、ブラウザ用の
+ * コードにキーを渡す事故が型で防げない。**別の関数にしておけば、
+ * キーを渡せる場所がサーバー専用のモジュールに限定される。**
+ *
+ * ## agencyId を引数に取らない
+ *
+ * 代理店はキーそのものから確定する。呼び出し側が渡さないので、他社の代理店 ID
+ * を指定するという操作自体が存在しない。
+ *
+ * @see Issue #5144 (Epic #5137)
+ */
+
+/**
+ * このクライアントが返しうるエラーコード。
+ *
+ * `FFIDAgencyErrorCode`（SDK 内部で定義した閉じた集合）には、サーバーが実際に
+ * 返す `ORGANIZATION_SLUG_CONFLICT` / `INVALID_ORGANIZATION_SLUG` /
+ * `REVOKED_API_KEY` などが含まれていない。閉じた union のふりをすると、
+ * 利用者が書いた exhaustive な `switch` が実行時に全部 `default` に落ちる。
+ * **開いた集合であることを型で正直に表す。**
+ *
+ * ⚠️ `types.ts` の `FFIDAgencyServerErrorCode` とは**別物**。あちらは
+ * 「サーバー由来コードの閉じた union」で `FFIDAgencyErrorCode` の構成要素。
+ * こちらは「このクライアントの `error.code` に載りうる値」。
+ */
+type FFIDAgencyServerClientErrorCode = FFIDAgencyErrorCode | (string & {});
+/** サーバークライアントのエラー。`code` が開いた集合である点だけが違う。 */
+interface FFIDAgencyServerClientError {
+    code: FFIDAgencyServerClientErrorCode;
+    message: string;
+    details?: Record<string, unknown>;
+}
+/**
+ * サーバークライアントの応答。
+ *
+ * Cookie クライアントの `FFIDAgencyApiResponse` は `code` が閉じた union だが、
+ * それは SDK 内部で作るコードしか載らないため。こちらは**サーバーのコードを
+ * そのまま通す**ので、型も開いておく必要がある。
+ */
+type FFIDAgencyServerClientResponse<T> = {
+    data: T;
+    error?: undefined;
+} | {
+    data?: undefined;
+    error: FFIDAgencyServerClientError;
+};
+interface FFIDAgencyServerClientConfig {
+    /**
+     * 代理店の API キー。**環境変数から読むこと。**
+     * ソースに直書きしたりブラウザへ渡したりしてはいけない。
+     */
+    apiKey: string;
+    apiBaseUrl?: string;
+    logger?: FFIDAgencyLogger;
+    /** `true` でコンソールに診断ログを出す（`createFFIDAgencyClient` と同じ）。 */
+    debug?: boolean;
+    /**
+     * リクエストのタイムアウト（ミリ秒）。既定 30 秒。
+     *
+     * 無いと FFID 側がハングしたときに呼び出し側のハンドラも道連れになる。
+     */
+    timeoutMs?: number;
+}
+interface FFIDAgencyServerClient {
+    /**
+     * 顧客組織を代行作成する。
+     *
+     * 組織の作成・owner membership・代理店への紐付けはサーバー側で 1 つの
+     * トランザクションにまとまっており、途中で失敗しても部分的な状態は残らない。
+     *
+     * 作成後、顧客担当者にパスワード設定の案内メールが送られる。
+     * **`welcomeEmail: 'failed'` でも組織と紐付けは作成済み**（メールの失敗で
+     * 作成は巻き戻さない）。その場合は顧客がログインできないので、
+     * 別途フォローが要る。
+     *
+     * @returns 成功時は作成された組織。失敗時は `error`（このクライアントは
+     *   throw しない — 他の agency メソッドと同じ契約）。
+     *   すべて 401 だが**コードは原因ごとに違う**（打ち手が違うため）:
+     *   - `MISSING_API_KEY` — ヘッダーが無い
+     *   - `INVALID_API_KEY_FORMAT` — 値が途中で切れている等
+     *   - `INVALID_API_KEY` — 該当するキーが無い
+     *   - `REVOKED_API_KEY` / `EXPIRED_API_KEY` — 再発行が必要
+     *
+     *   そのほか:
+     *   - スコープ不足 / 代理店が停止中 → `FORBIDDEN`（403）
+     *   - slug が既存組織と衝突 → `ORGANIZATION_SLUG_CONFLICT`（409、組織は作成されない）
+     *   - 認証段階の一時障害 → `SERVICE_UNAVAILABLE`（503、**安全に再試行できる**）
+     *   - `PARSE_ERROR` / `NETWORK_ERROR` — **組織が作成された可能性がある**。
+     *     再試行の前に組織一覧を確認すること（#5165 で冪等キーを導入予定）
+     */
+    provisionCustomerOrganization(data: FFIDProvisionOrganizationRequest): Promise<FFIDAgencyServerClientResponse<FFIDProvisionedOrganization>>;
+}
+/**
+ * サーバー間クライアントを作る。
+ *
+ * @throws {Error} `apiKey` が空のとき。認証されないリクエストを送って 401 で
+ *   気づくより、初期化時点で止めたほうが原因が明確になる。
+ */
+declare function createFFIDAgencyServerClient(config: FFIDAgencyServerClientConfig): FFIDAgencyServerClient;
+
 /**
  * FFID Agency API Client
  *
@@ -318,4 +493,4 @@ declare const FFID_AGENCY_ERROR_CODES: {
 };
 declare function createFFIDAgencyClient(config?: FFIDAgencyClientConfig): FFIDAgencyClient;
 
-export { type FFIDAddAgencyMemberRequest, type FFIDAgency, type FFIDAgencyApiResponse, type FFIDAgencyAssetType, type FFIDAgencyBillingConfig, type FFIDAgencyBillingOverride, type FFIDAgencyBillingSummary, type FFIDAgencyBillingType, type FFIDAgencyBrandingSettings, type FFIDAgencyClient, type FFIDAgencyClientConfig, type FFIDAgencyDnsRecord, type FFIDAgencyDomainSettings, type FFIDAgencyEmailSettings, type FFIDAgencyError, type FFIDAgencyErrorCode, type FFIDAgencyHierarchyNode, type FFIDAgencyHierarchyResponse, type FFIDAgencyInvoice, type FFIDAgencyInvoiceStatus, type FFIDAgencyLogger, type FFIDAgencyMember, type FFIDAgencyMemberRole, type FFIDAgencyMemberStatus, type FFIDAgencyOrganization, type FFIDAgencyRevenue, type FFIDAgencySdkErrorCode, type FFIDAgencyServerError, type FFIDAgencyServerErrorCode, type FFIDAgencyServerResponse, type FFIDAgencySettings, type FFIDAgencyStatus, type FFIDCreateSubAgencyRequest, type FFIDLinkOrganizationRequest, type FFIDSetupDomainRequest, type FFIDSslStatus, type FFIDUpdateAgencyBillingRequest, type FFIDUpdateAgencyMemberRequest, type FFIDUpdateAgencyRequest, type FFIDUpdateEmailSettingsRequest, FFID_AGENCY_ERROR_CODES, createFFIDAgencyClient };
+export { type FFIDAddAgencyMemberRequest, type FFIDAgency, type FFIDAgencyApiResponse, type FFIDAgencyAssetType, type FFIDAgencyBillingConfig, type FFIDAgencyBillingOverride, type FFIDAgencyBillingSummary, type FFIDAgencyBillingType, type FFIDAgencyBrandingSettings, type FFIDAgencyClient, type FFIDAgencyClientConfig, type FFIDAgencyDnsRecord, type FFIDAgencyDomainSettings, type FFIDAgencyEmailSettings, type FFIDAgencyError, type FFIDAgencyErrorCode, type FFIDAgencyHierarchyNode, type FFIDAgencyHierarchyResponse, type FFIDAgencyInvoice, type FFIDAgencyInvoiceStatus, type FFIDAgencyLogger, type FFIDAgencyMember, type FFIDAgencyMemberRole, type FFIDAgencyMemberStatus, type FFIDAgencyOrganization, type FFIDAgencyRevenue, type FFIDAgencySdkErrorCode, type FFIDAgencyServerClient, type FFIDAgencyServerClientConfig, type FFIDAgencyServerClientError, type FFIDAgencyServerClientErrorCode, type FFIDAgencyServerClientResponse, type FFIDAgencyServerError, type FFIDAgencyServerErrorCode, type FFIDAgencyServerResponse, type FFIDAgencySettings, type FFIDAgencyStatus, type FFIDCreateSubAgencyRequest, type FFIDLinkOrganizationRequest, type FFIDProvisionOrganizationRequest, type FFIDProvisionedOrganization, type FFIDSetupDomainRequest, type FFIDSslStatus, type FFIDUpdateAgencyBillingRequest, type FFIDUpdateAgencyMemberRequest, type FFIDUpdateAgencyRequest, type FFIDUpdateEmailSettingsRequest, type FFIDWelcomeEmailOutcome, FFID_AGENCY_ERROR_CODES, createFFIDAgencyClient, createFFIDAgencyServerClient };

package/dist/agency/index.d.ts

@@ -1,4 +1,4 @@
-export { D as DEFAULT_API_BASE_URL } from '../constants-D61jqRIO.js';
+export { D as DEFAULT_API_BASE_URL } from '../constants-Ce2eXQtB.js';
 
 /**
  * FFID Agency SDK Type Definitions
@@ -101,13 +101,60 @@ interface FFIDAgencyOrganization {
     commissionRate: number | null;
     markupRate: number | null;
     markupFixed: number | null;
+    /** 組織単位の卸割引率 override（%、0〜100）。null = 代理店デフォルトに従う。 */
+    wholesaleDiscountRate: number | null;
     notes: string | null;
     createdAt: string;
 }
+/**
+ * 顧客組織の代行作成リクエスト（#5143）。
+ */
+interface FFIDProvisionOrganizationRequest {
+    /** 組織名 */
+    name: string;
+    /** 顧客担当者のメールアドレス。この人が組織の owner になる */
+    ownerEmail: string;
+    /**
+     * 組織 ID（slug）。半角英小文字・数字・ハイフンのみ。
+     *
+     * 省略すると組織名から自動生成される。**指定した場合、既存組織と衝突すると
+     * 409 が返り、組織は作成されない**（自動で `acme-2` のような別名に
+     * すり替えたりはしない。代理店が顧客に伝えた URL と食い違うため）。
+     */
+    slug?: string;
+    /** 請求先メールアドレス */
+    billingEmail?: string;
+}
+/** 案内メールの送信結果。組織作成の成否とは独立している。 */
+type FFIDWelcomeEmailOutcome = 'sent' | 'failed';
+/**
+ * 代行作成の結果（#5143）。
+ */
+interface FFIDProvisionedOrganization {
+    id: string;
+    name: string;
+    slug: string;
+    billingEmail: string | null;
+    createdAt: string;
+    /** owner になった顧客担当者 */
+    ownerUserId: string;
+    ownerEmail: string;
+    /** 顧客が既に FeelFlow ID のアカウントを持っていたか */
+    ownerExisted: boolean;
+    /**
+     * パスワード設定の案内メールの結果。
+     *
+     * `'failed'` でも**組織と紐付けは作成済み**（メール失敗で巻き戻さない）。
+     * この場合は顧客がログインできないので、代理店から再送を促すこと。
+     */
+    welcomeEmail: FFIDWelcomeEmailOutcome;
+}
 interface FFIDLinkOrganizationRequest {
     organizationId: string;
     billingOverride?: FFIDAgencyBillingOverride;
     commissionRate?: number;
+    /** 組織単位の卸割引率 override（%、0〜100）。省略時 / null は代理店デフォルトに従う。 */
+    wholesaleDiscountRate?: number | null;
     notes?: string;
 }
 interface FFIDCreateSubAgencyRequest {
@@ -133,6 +180,8 @@ interface FFIDAgencyBillingConfig {
     paymentTerms: number | null;
     defaultMarkupRate: number | null;
     defaultMarkupFixed: number | null;
+    /** 代理店デフォルト卸割引率（%、0〜100）。null = 未設定（定価請求）。 */
+    wholesaleDiscountRate: number | null;
 }
 interface FFIDUpdateAgencyBillingRequest {
     billingType?: FFIDAgencyBillingType;
@@ -140,6 +189,8 @@ interface FFIDUpdateAgencyBillingRequest {
     paymentTerms?: number;
     defaultMarkupRate?: number;
     defaultMarkupFixed?: number;
+    /** 代理店デフォルト卸割引率（%、0〜100）。null で未設定に戻す。 */
+    wholesaleDiscountRate?: number | null;
 }
 interface FFIDAgencyBillingSummary {
     agencyId: string;
@@ -214,6 +265,16 @@ interface FFIDAgencyClient {
     unlinkOrganization(agencyId: string, orgId: string): Promise<FFIDAgencyApiResponse<{
         message: string;
     }>>;
+    /**
+     * 顧客組織を代行作成する（#5143）。
+     *
+     * `linkOrganization` が**既存**組織を紐付けるのに対し、こちらは組織そのものを
+     * 作る。顧客担当者が最初から owner になり、代理店スタッフは組織のメンバーに
+     * ならない。作成後、顧客担当者へパスワード設定の案内メールが送られる。
+     *
+     * 実行できるのは owner / admin / **sales**（support は 403）。
+     */
+    provisionOrganization(agencyId: string, data: FFIDProvisionOrganizationRequest): Promise<FFIDAgencyApiResponse<FFIDProvisionedOrganization>>;
     getSubAgencies(agencyId: string): Promise<FFIDAgencyApiResponse<{
         agencies: FFIDAgency[];
         count: number;
@@ -292,6 +353,120 @@ type FFIDAgencyApiResponse<T> = {
     error: FFIDAgencyError;
 };
 
+/**
+ * 代理店のサーバー間クライアント（API キー認証）
+ *
+ * ⚠️ **サーバーサイド専用。ブラウザで使ってはいけない。**
+ *
+ * このクライアントが使う API キーは、
+ * - 任意のメールアドレスに対して FFID アカウントを作れる
+ * - 顧客組織を代理店に紐付ける = **売上の計上先を決める**
+ *
+ * ため、ブラウザに出た時点で第三者が代理店になりすませる。
+ *
+ * ## なぜ `createFFIDAgencyClient` と別なのか
+ *
+ * あちらは Cookie 認証（`credentials: 'include'`）でブラウザから使える。
+ * 同じファクトリに「キーを渡すとキー認証になる」モードを足すと、ブラウザ用の
+ * コードにキーを渡す事故が型で防げない。**別の関数にしておけば、
+ * キーを渡せる場所がサーバー専用のモジュールに限定される。**
+ *
+ * ## agencyId を引数に取らない
+ *
+ * 代理店はキーそのものから確定する。呼び出し側が渡さないので、他社の代理店 ID
+ * を指定するという操作自体が存在しない。
+ *
+ * @see Issue #5144 (Epic #5137)
+ */
+
+/**
+ * このクライアントが返しうるエラーコード。
+ *
+ * `FFIDAgencyErrorCode`（SDK 内部で定義した閉じた集合）には、サーバーが実際に
+ * 返す `ORGANIZATION_SLUG_CONFLICT` / `INVALID_ORGANIZATION_SLUG` /
+ * `REVOKED_API_KEY` などが含まれていない。閉じた union のふりをすると、
+ * 利用者が書いた exhaustive な `switch` が実行時に全部 `default` に落ちる。
+ * **開いた集合であることを型で正直に表す。**
+ *
+ * ⚠️ `types.ts` の `FFIDAgencyServerErrorCode` とは**別物**。あちらは
+ * 「サーバー由来コードの閉じた union」で `FFIDAgencyErrorCode` の構成要素。
+ * こちらは「このクライアントの `error.code` に載りうる値」。
+ */
+type FFIDAgencyServerClientErrorCode = FFIDAgencyErrorCode | (string & {});
+/** サーバークライアントのエラー。`code` が開いた集合である点だけが違う。 */
+interface FFIDAgencyServerClientError {
+    code: FFIDAgencyServerClientErrorCode;
+    message: string;
+    details?: Record<string, unknown>;
+}
+/**
+ * サーバークライアントの応答。
+ *
+ * Cookie クライアントの `FFIDAgencyApiResponse` は `code` が閉じた union だが、
+ * それは SDK 内部で作るコードしか載らないため。こちらは**サーバーのコードを
+ * そのまま通す**ので、型も開いておく必要がある。
+ */
+type FFIDAgencyServerClientResponse<T> = {
+    data: T;
+    error?: undefined;
+} | {
+    data?: undefined;
+    error: FFIDAgencyServerClientError;
+};
+interface FFIDAgencyServerClientConfig {
+    /**
+     * 代理店の API キー。**環境変数から読むこと。**
+     * ソースに直書きしたりブラウザへ渡したりしてはいけない。
+     */
+    apiKey: string;
+    apiBaseUrl?: string;
+    logger?: FFIDAgencyLogger;
+    /** `true` でコンソールに診断ログを出す（`createFFIDAgencyClient` と同じ）。 */
+    debug?: boolean;
+    /**
+     * リクエストのタイムアウト（ミリ秒）。既定 30 秒。
+     *
+     * 無いと FFID 側がハングしたときに呼び出し側のハンドラも道連れになる。
+     */
+    timeoutMs?: number;
+}
+interface FFIDAgencyServerClient {
+    /**
+     * 顧客組織を代行作成する。
+     *
+     * 組織の作成・owner membership・代理店への紐付けはサーバー側で 1 つの
+     * トランザクションにまとまっており、途中で失敗しても部分的な状態は残らない。
+     *
+     * 作成後、顧客担当者にパスワード設定の案内メールが送られる。
+     * **`welcomeEmail: 'failed'` でも組織と紐付けは作成済み**（メールの失敗で
+     * 作成は巻き戻さない）。その場合は顧客がログインできないので、
+     * 別途フォローが要る。
+     *
+     * @returns 成功時は作成された組織。失敗時は `error`（このクライアントは
+     *   throw しない — 他の agency メソッドと同じ契約）。
+     *   すべて 401 だが**コードは原因ごとに違う**（打ち手が違うため）:
+     *   - `MISSING_API_KEY` — ヘッダーが無い
+     *   - `INVALID_API_KEY_FORMAT` — 値が途中で切れている等
+     *   - `INVALID_API_KEY` — 該当するキーが無い
+     *   - `REVOKED_API_KEY` / `EXPIRED_API_KEY` — 再発行が必要
+     *
+     *   そのほか:
+     *   - スコープ不足 / 代理店が停止中 → `FORBIDDEN`（403）
+     *   - slug が既存組織と衝突 → `ORGANIZATION_SLUG_CONFLICT`（409、組織は作成されない）
+     *   - 認証段階の一時障害 → `SERVICE_UNAVAILABLE`（503、**安全に再試行できる**）
+     *   - `PARSE_ERROR` / `NETWORK_ERROR` — **組織が作成された可能性がある**。
+     *     再試行の前に組織一覧を確認すること（#5165 で冪等キーを導入予定）
+     */
+    provisionCustomerOrganization(data: FFIDProvisionOrganizationRequest): Promise<FFIDAgencyServerClientResponse<FFIDProvisionedOrganization>>;
+}
+/**
+ * サーバー間クライアントを作る。
+ *
+ * @throws {Error} `apiKey` が空のとき。認証されないリクエストを送って 401 で
+ *   気づくより、初期化時点で止めたほうが原因が明確になる。
+ */
+declare function createFFIDAgencyServerClient(config: FFIDAgencyServerClientConfig): FFIDAgencyServerClient;
+
 /**
  * FFID Agency API Client
  *
@@ -318,4 +493,4 @@ declare const FFID_AGENCY_ERROR_CODES: {
 };
 declare function createFFIDAgencyClient(config?: FFIDAgencyClientConfig): FFIDAgencyClient;
 
-export { type FFIDAddAgencyMemberRequest, type FFIDAgency, type FFIDAgencyApiResponse, type FFIDAgencyAssetType, type FFIDAgencyBillingConfig, type FFIDAgencyBillingOverride, type FFIDAgencyBillingSummary, type FFIDAgencyBillingType, type FFIDAgencyBrandingSettings, type FFIDAgencyClient, type FFIDAgencyClientConfig, type FFIDAgencyDnsRecord, type FFIDAgencyDomainSettings, type FFIDAgencyEmailSettings, type FFIDAgencyError, type FFIDAgencyErrorCode, type FFIDAgencyHierarchyNode, type FFIDAgencyHierarchyResponse, type FFIDAgencyInvoice, type FFIDAgencyInvoiceStatus, type FFIDAgencyLogger, type FFIDAgencyMember, type FFIDAgencyMemberRole, type FFIDAgencyMemberStatus, type FFIDAgencyOrganization, type FFIDAgencyRevenue, type FFIDAgencySdkErrorCode, type FFIDAgencyServerError, type FFIDAgencyServerErrorCode, type FFIDAgencyServerResponse, type FFIDAgencySettings, type FFIDAgencyStatus, type FFIDCreateSubAgencyRequest, type FFIDLinkOrganizationRequest, type FFIDSetupDomainRequest, type FFIDSslStatus, type FFIDUpdateAgencyBillingRequest, type FFIDUpdateAgencyMemberRequest, type FFIDUpdateAgencyRequest, type FFIDUpdateEmailSettingsRequest, FFID_AGENCY_ERROR_CODES, createFFIDAgencyClient };
+export { type FFIDAddAgencyMemberRequest, type FFIDAgency, type FFIDAgencyApiResponse, type FFIDAgencyAssetType, type FFIDAgencyBillingConfig, type FFIDAgencyBillingOverride, type FFIDAgencyBillingSummary, type FFIDAgencyBillingType, type FFIDAgencyBrandingSettings, type FFIDAgencyClient, type FFIDAgencyClientConfig, type FFIDAgencyDnsRecord, type FFIDAgencyDomainSettings, type FFIDAgencyEmailSettings, type FFIDAgencyError, type FFIDAgencyErrorCode, type FFIDAgencyHierarchyNode, type FFIDAgencyHierarchyResponse, type FFIDAgencyInvoice, type FFIDAgencyInvoiceStatus, type FFIDAgencyLogger, type FFIDAgencyMember, type FFIDAgencyMemberRole, type FFIDAgencyMemberStatus, type FFIDAgencyOrganization, type FFIDAgencyRevenue, type FFIDAgencySdkErrorCode, type FFIDAgencyServerClient, type FFIDAgencyServerClientConfig, type FFIDAgencyServerClientError, type FFIDAgencyServerClientErrorCode, type FFIDAgencyServerClientResponse, type FFIDAgencyServerError, type FFIDAgencyServerErrorCode, type FFIDAgencyServerResponse, type FFIDAgencySettings, type FFIDAgencyStatus, type FFIDCreateSubAgencyRequest, type FFIDLinkOrganizationRequest, type FFIDProvisionOrganizationRequest, type FFIDProvisionedOrganization, type FFIDSetupDomainRequest, type FFIDSslStatus, type FFIDUpdateAgencyBillingRequest, type FFIDUpdateAgencyMemberRequest, type FFIDUpdateAgencyRequest, type FFIDUpdateEmailSettingsRequest, type FFIDWelcomeEmailOutcome, FFID_AGENCY_ERROR_CODES, createFFIDAgencyClient, createFFIDAgencyServerClient };