@feelflow/ffid-sdk 5.18.0 → 5.19.0

package/README.md

@@ -396,6 +396,83 @@ await ffid.updateMemberRole({
 - `role` は `admin` / `member` / `viewer` のみ指定可能です。`owner` は追加・昇格 API では扱いません。
 - agency client と同じ呼び味が必要な場合は `ffid.addMember(organizationId, { email, role })` も使えます。
 
+### Provisioning（users / organizations）
+
+外部サービスからの一括移行向けに、**service-key 認証**でユーザー・組織を冪等にプロビジョニングするメソッド。REST を直叩きせず `createFFIDClient` 経由で呼べる（SDK-first、#3790 / #4127）。
+
+- **`authMode: 'service-key'`（`X-Service-Api-Key`）専用**。`token`（Bearer）/ `cookie` モードで呼ぶとサーバーへ往復せず即座に `VALIDATION_ERROR` を返す（サーバー側エンドポイントが service-key 認証のみを受け付けるため）。
+- 必要 scope: `provisionUser` → `user:provision`、`provisionOrganization` → `organization:write`。
+
+```ts
+import { createFFIDClient } from '@feelflow/ffid-sdk/server'
+
+const ffid = createFFIDClient({
+  serviceCode: 'praxis',
+  scope: '',
+  authMode: 'service-key',
+  serviceApiKey: process.env.FFID_SERVICE_API_KEY!,
+})
+
+// 1. ユーザーを冪等に作成（新規なら created:true / 既存なら created:false）
+const userRes = await ffid.provisionUser({
+  email: 'owner@example.com',
+  profile: { displayName: '山田 太郎', companyName: 'Example Inc.' },
+})
+if (userRes.error) throw new Error(userRes.error.message)
+if (!userRes.data.dryRun) {
+  console.log(userRes.data.created ? '新規作成' : '既存ユーザー', userRes.data.user.id)
+}
+
+// 2. その owner の組織を作成し、メンバーを冪等に追加
+const orgRes = await ffid.provisionOrganization({
+  name: 'Example 組織',
+  ownerEmail: 'owner@example.com',
+  members: [
+    { email: 'member1@example.com', role: 'member' },
+    { email: 'member2@example.com', role: 'viewer' },
+  ],
+})
+if (orgRes.error) {
+  // owner が未登録なら error.code === 'OWNER_NOT_FOUND'（先に provisionUser が必要）
+  throw new Error(orgRes.error.message)
+}
+if (!orgRes.data.dryRun) {
+  for (const m of orgRes.data.members) {
+    console.log(m.email, m.status) // 'added' | 'already_member' | 'user_not_found'
+  }
+}
+```
+
+#### 冪等セマンティクス
+
+- `provisionUser`: **既存メールは `created: false`**（HTTP 200、no-op）、新規メールは `created: true`（HTTP 201、パスワードレス・メール確認済み）。メールはサーバー側で normalize（trim + lowercase）されるため、大文字小文字違いの再送でも同一ユーザーに解決する。新規作成で `profile` を渡した場合のみ `profileWritten` が付き、`false` は「ユーザーは作成されたがプロフィール書き込みに失敗」→ 再送を推奨。
+- `provisionOrganization`: owner が同名の組織を既に持つ場合は `created: false`（HTTP 200）。`members` は冪等に追加され、各要素の `status` が `added` / `already_member` / `user_not_found` を返す。
+
+#### dryRun
+
+`dryRun: true` を渡すと **一切書き込まず**、実行時に何が起きるかだけを返す。レスポンスは `dryRun` 判別のタグ付きユニオン。
+
+```ts
+const preview = await ffid.provisionUser({ email: 'owner@example.com', dryRun: true })
+if (!preview.error && preview.data.dryRun) {
+  console.log(preview.data.wouldCreate) // true = 実行すれば新規作成される
+}
+
+const orgPreview = await ffid.provisionOrganization({
+  name: 'Example 組織',
+  ownerEmail: 'owner@example.com',
+  members: [{ email: 'member1@example.com', role: 'member' }],
+  dryRun: true,
+})
+if (!orgPreview.error && orgPreview.data.dryRun) {
+  console.log(orgPreview.data.wouldCreate) // 組織を新規作成するか
+  // per-member plan status: 'would_add' | 'already_member' | 'user_not_found'
+  orgPreview.data.members.forEach((m) => console.log(m.email, m.status))
+}
+```
+
+`if (res.data.dryRun)` で TypeScript が型を絞り込むため、dry-run 分岐では `wouldCreate`、実行分岐では `created` がそれぞれ型安全に参照できる。
+
 ### getProfile() / updateProfile()
 
 ログイン中ユーザー自身のプロフィールを取得・更新するメソッド（`createFFIDClient` から呼び出し）。

package/dist/{chunk-L2H56C4W.js → chunk-D3PZ6SZB.js}

@@ -873,6 +873,93 @@ function createMembersMethods(deps) {
   return { listMembers, addMember, updateMemberRole, removeMember };
 }
 
+// src/client/provisioning-methods.ts
+var USER_PROVISION_ENDPOINT = "/api/v1/ext/users/provision";
+var ORGANIZATION_PROVISION_ENDPOINT = "/api/v1/ext/organizations/provision";
+var MAX_PROVISION_MEMBERS = 100;
+var ASSIGNABLE_MEMBER_ROLES = {
+  admin: true,
+  member: true,
+  viewer: true
+};
+function isAssignableMemberRole(role) {
+  return Object.hasOwn(ASSIGNABLE_MEMBER_ROLES, role);
+}
+function createProvisioningMethods(deps) {
+  const { fetchWithAuth, createError, authMode } = deps;
+  function serviceKeyModeError() {
+    if (authMode === "service-key") return null;
+    return createError(
+      "VALIDATION_ERROR",
+      "provisionUser / provisionOrganization \u306F service-key \u8A8D\u8A3C\uFF08X-Service-Api-Key\uFF09\u3067\u306E\u307F\u5229\u7528\u3067\u304D\u307E\u3059\u3002Bearer / cookie \u30E2\u30FC\u30C9\u3067\u306F\u547C\u3073\u51FA\u305B\u307E\u305B\u3093"
+    );
+  }
+  async function provisionUser(params) {
+    const modeError = serviceKeyModeError();
+    if (modeError) return { error: modeError };
+    if (!params.email || !params.email.trim()) {
+      return { error: createError("VALIDATION_ERROR", "email \u306F\u5FC5\u9808\u3067\u3059") };
+    }
+    const body = { email: params.email.trim() };
+    if (params.profile !== void 0) body.profile = params.profile;
+    if (params.dryRun !== void 0) body.dryRun = params.dryRun;
+    return fetchWithAuth(USER_PROVISION_ENDPOINT, {
+      method: "POST",
+      body: JSON.stringify(body)
+    });
+  }
+  async function provisionOrganization(params) {
+    const modeError = serviceKeyModeError();
+    if (modeError) return { error: modeError };
+    if (!params.name || !params.name.trim()) {
+      return { error: createError("VALIDATION_ERROR", "name \u306F\u5FC5\u9808\u3067\u3059") };
+    }
+    if (!params.ownerEmail || !params.ownerEmail.trim()) {
+      return { error: createError("VALIDATION_ERROR", "ownerEmail \u306F\u5FC5\u9808\u3067\u3059") };
+    }
+    if (params.members) {
+      if (params.members.length > MAX_PROVISION_MEMBERS) {
+        return {
+          error: createError(
+            "VALIDATION_ERROR",
+            `members \u306F1\u30EA\u30AF\u30A8\u30B9\u30C8\u3042\u305F\u308A\u6700\u5927 ${MAX_PROVISION_MEMBERS} \u4EF6\u307E\u3067\u3067\u3059`
+          )
+        };
+      }
+      for (const member of params.members) {
+        if (!member.email || !member.email.trim()) {
+          return { error: createError("VALIDATION_ERROR", "members[].email \u306F\u5FC5\u9808\u3067\u3059") };
+        }
+        if (!isAssignableMemberRole(member.role)) {
+          return {
+            error: createError(
+              "VALIDATION_ERROR",
+              "members[].role \u306F admin\u3001member\u3001viewer \u306E\u3044\u305A\u308C\u304B\u3092\u6307\u5B9A\u3057\u3066\u304F\u3060\u3055\u3044"
+            )
+          };
+        }
+      }
+    }
+    const body = {
+      name: params.name.trim(),
+      ownerEmail: params.ownerEmail.trim()
+    };
+    if (params.billingEmail !== void 0) body.billingEmail = params.billingEmail.trim();
+    if (params.members !== void 0) {
+      body.members = params.members.map((member) => ({
+        email: member.email.trim(),
+        role: member.role
+      }));
+    }
+    if (params.dryRun !== void 0) body.dryRun = params.dryRun;
+    return fetchWithAuth(ORGANIZATION_PROVISION_ENDPOINT, {
+      method: "POST",
+      body: JSON.stringify(body)
+    });
+  }
+  return { provisionUser, provisionOrganization };
+}
+
 // src/client/seat-methods.ts
 function seatsEndpoint(subscriptionId) {
   return `/api/v1/subscriptions/ext/${encodeURIComponent(subscriptionId)}/seats/assignments`;
@@ -1117,7 +1204,7 @@ function createNonContractMethods(deps) {
 }
 
 // src/client/version-check.ts
-var SDK_VERSION = "5.18.0";
+var SDK_VERSION = "5.19.0";
 var SDK_USER_AGENT = `FFID-SDK/${SDK_VERSION} (TypeScript)`;
 var SDK_VERSION_HEADER = "X-FFID-SDK-Version";
 function sdkHeaders() {
@@ -3128,6 +3215,11 @@ function createFFIDClient(config) {
     createError,
     serviceCode: config.serviceCode
   });
+  const { provisionUser, provisionOrganization } = createProvisioningMethods({
+    fetchWithAuth,
+    createError,
+    authMode
+  });
   const { getProfile, updateProfile } = createProfileMethods({
     fetchWithAuth,
     createError
@@ -3223,6 +3315,8 @@ function createFFIDClient(config) {
     addMember,
     updateMemberRole,
     removeMember,
+    provisionUser,
+    provisionOrganization,
     getProfile,
     updateProfile,
     // Non-contract ext API coverage (#3783)

package/dist/{chunk-55S5VUWR.cjs → chunk-TW2FXASO.cjs}

@@ -875,6 +875,93 @@ function createMembersMethods(deps) {
   return { listMembers, addMember, updateMemberRole, removeMember };
 }
 
+// src/client/provisioning-methods.ts
+var USER_PROVISION_ENDPOINT = "/api/v1/ext/users/provision";
+var ORGANIZATION_PROVISION_ENDPOINT = "/api/v1/ext/organizations/provision";
+var MAX_PROVISION_MEMBERS = 100;
+var ASSIGNABLE_MEMBER_ROLES = {
+  admin: true,
+  member: true,
+  viewer: true
+};
+function isAssignableMemberRole(role) {
+  return Object.hasOwn(ASSIGNABLE_MEMBER_ROLES, role);
+}
+function createProvisioningMethods(deps) {
+  const { fetchWithAuth, createError, authMode } = deps;
+  function serviceKeyModeError() {
+    if (authMode === "service-key") return null;
+    return createError(
+      "VALIDATION_ERROR",
+      "provisionUser / provisionOrganization \u306F service-key \u8A8D\u8A3C\uFF08X-Service-Api-Key\uFF09\u3067\u306E\u307F\u5229\u7528\u3067\u304D\u307E\u3059\u3002Bearer / cookie \u30E2\u30FC\u30C9\u3067\u306F\u547C\u3073\u51FA\u305B\u307E\u305B\u3093"
+    );
+  }
+  async function provisionUser(params) {
+    const modeError = serviceKeyModeError();
+    if (modeError) return { error: modeError };
+    if (!params.email || !params.email.trim()) {
+      return { error: createError("VALIDATION_ERROR", "email \u306F\u5FC5\u9808\u3067\u3059") };
+    }
+    const body = { email: params.email.trim() };
+    if (params.profile !== void 0) body.profile = params.profile;
+    if (params.dryRun !== void 0) body.dryRun = params.dryRun;
+    return fetchWithAuth(USER_PROVISION_ENDPOINT, {
+      method: "POST",
+      body: JSON.stringify(body)
+    });
+  }
+  async function provisionOrganization(params) {
+    const modeError = serviceKeyModeError();
+    if (modeError) return { error: modeError };
+    if (!params.name || !params.name.trim()) {
+      return { error: createError("VALIDATION_ERROR", "name \u306F\u5FC5\u9808\u3067\u3059") };
+    }
+    if (!params.ownerEmail || !params.ownerEmail.trim()) {
+      return { error: createError("VALIDATION_ERROR", "ownerEmail \u306F\u5FC5\u9808\u3067\u3059") };
+    }
+    if (params.members) {
+      if (params.members.length > MAX_PROVISION_MEMBERS) {
+        return {
+          error: createError(
+            "VALIDATION_ERROR",
+            `members \u306F1\u30EA\u30AF\u30A8\u30B9\u30C8\u3042\u305F\u308A\u6700\u5927 ${MAX_PROVISION_MEMBERS} \u4EF6\u307E\u3067\u3067\u3059`
+          )
+        };
+      }
+      for (const member of params.members) {
+        if (!member.email || !member.email.trim()) {
+          return { error: createError("VALIDATION_ERROR", "members[].email \u306F\u5FC5\u9808\u3067\u3059") };
+        }
+        if (!isAssignableMemberRole(member.role)) {
+          return {
+            error: createError(
+              "VALIDATION_ERROR",
+              "members[].role \u306F admin\u3001member\u3001viewer \u306E\u3044\u305A\u308C\u304B\u3092\u6307\u5B9A\u3057\u3066\u304F\u3060\u3055\u3044"
+            )
+          };
+        }
+      }
+    }
+    const body = {
+      name: params.name.trim(),
+      ownerEmail: params.ownerEmail.trim()
+    };
+    if (params.billingEmail !== void 0) body.billingEmail = params.billingEmail.trim();
+    if (params.members !== void 0) {
+      body.members = params.members.map((member) => ({
+        email: member.email.trim(),
+        role: member.role
+      }));
+    }
+    if (params.dryRun !== void 0) body.dryRun = params.dryRun;
+    return fetchWithAuth(ORGANIZATION_PROVISION_ENDPOINT, {
+      method: "POST",
+      body: JSON.stringify(body)
+    });
+  }
+  return { provisionUser, provisionOrganization };
+}
+
 // src/client/seat-methods.ts
 function seatsEndpoint(subscriptionId) {
   return `/api/v1/subscriptions/ext/${encodeURIComponent(subscriptionId)}/seats/assignments`;
@@ -1119,7 +1206,7 @@ function createNonContractMethods(deps) {
 }
 
 // src/client/version-check.ts
-var SDK_VERSION = "5.18.0";
+var SDK_VERSION = "5.19.0";
 var SDK_USER_AGENT = `FFID-SDK/${SDK_VERSION} (TypeScript)`;
 var SDK_VERSION_HEADER = "X-FFID-SDK-Version";
 function sdkHeaders() {
@@ -3130,6 +3217,11 @@ function createFFIDClient(config) {
     createError,
     serviceCode: config.serviceCode
   });
+  const { provisionUser, provisionOrganization } = createProvisioningMethods({
+    fetchWithAuth,
+    createError,
+    authMode
+  });
   const { getProfile, updateProfile } = createProfileMethods({
     fetchWithAuth,
     createError
@@ -3225,6 +3317,8 @@ function createFFIDClient(config) {
     addMember,
     updateMemberRole,
     removeMember,
+    provisionUser,
+    provisionOrganization,
     getProfile,
     updateProfile,
     // Non-contract ext API coverage (#3783)

package/dist/components/index.cjs

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

package/dist/components/index.js

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

package/dist/{ffid-client-Cwk6cG3b.d.cts → ffid-client-BuDM5tmq.d.cts}

@@ -683,6 +683,217 @@ interface FFIDRemoveMemberResponse {
     message: string;
 }
 
+/**
+ * Provisioning types (ext API) — service-key-authenticated, idempotent user /
+ * organization provisioning for external batch migration (#3790 / #4127).
+ *
+ * Mirrors the server contract of `POST /api/v1/ext/users/provision` and
+ * `POST /api/v1/ext/organizations/provision`. Responses are modelled as
+ * discriminated unions on `dryRun` so consumers narrow with `if (res.dryRun)`
+ * and the compiler enforces which fields are present on each branch
+ * (`wouldCreate` on dry-run, `created` on a real call).
+ */
+
+/** Optional business-profile fields applied to a freshly provisioned user. */
+interface FFIDProvisionUserProfileInput {
+    /** Display name (1–255 chars). */
+    displayName?: string;
+    /** Company name (≤255 chars). */
+    companyName?: string;
+    /** Department (≤255 chars). */
+    department?: string;
+    /** Job title (≤255 chars). */
+    jobTitle?: string;
+    /** Phone number (≤30 chars). */
+    phone?: string;
+}
+/** Parameters for `provisionUser`. */
+interface FFIDProvisionUserParams {
+    /**
+     * Email of the user to provision. Normalized (trim + lowercase) server-side
+     * before the idempotency lookup, so re-runs with different casing resolve to
+     * the same user.
+     */
+    email: string;
+    /** Optional business profile applied only when a new user is created. */
+    profile?: FFIDProvisionUserProfileInput;
+    /**
+     * When `true`, the server performs no writes and returns a
+     * {@link FFIDProvisionUserDryRun} describing what a real call would do.
+     * @default false
+     */
+    dryRun?: boolean;
+}
+/** Minimal identity returned for a provisioned / resolved user. */
+interface FFIDProvisionedUser {
+    /** User ID (UUID). */
+    id: string;
+    /** Email address (normalized). */
+    email: string;
+}
+/**
+ * Real (non-dry-run) user provisioning outcome.
+ *
+ * Idempotent: an existing email resolves to `created: false` (HTTP 200) instead
+ * of creating a duplicate; a new email yields `created: true` (HTTP 201) for a
+ * passwordless, email-confirmed user.
+ */
+interface FFIDProvisionUserOutcome {
+    /** Discriminant — absent/`false` for a real call. */
+    dryRun?: false;
+    /**
+     * `true`  → a new passwordless, email-confirmed user was created (HTTP 201).
+     * `false` → a user with this email already existed; idempotent no-op (HTTP 200).
+     */
+    created: boolean;
+    user: FFIDProvisionedUser;
+    /**
+     * Present only when a new user was created **and** a `profile` was supplied.
+     * `false` means the user row was created but the authoritative profile write
+     * did not complete — some profile fields may not be fully applied, so
+     * re-issue the profile to be sure. Absent on the idempotent-existing branch
+     * and when no profile was requested.
+     */
+    profileWritten?: boolean;
+}
+/** Dry-run user provisioning outcome — no writes performed. */
+interface FFIDProvisionUserDryRun {
+    /** Discriminant — always `true` for a dry-run. */
+    dryRun: true;
+    /** Whether a real call would create a new user. */
+    wouldCreate: boolean;
+    /** `id` is present only when the user already exists. */
+    user: {
+        id?: string;
+        email: string;
+    };
+}
+/**
+ * Response from `provisionUser`. Narrow with the truthiness of `dryRun`:
+ *
+ * ```ts
+ * if (res.dryRun) {
+ *   // FFIDProvisionUserDryRun — inspect res.wouldCreate
+ * } else {
+ *   // FFIDProvisionUserOutcome — inspect res.created
+ * }
+ * ```
+ *
+ * A real (non-dry-run) response omits `dryRun` on the wire (it is `undefined`,
+ * not `false`), so narrow with `if (res.dryRun)` — do **not** use
+ * `res.dryRun === false` or `switch (res.dryRun)`, which would miss every real
+ * response. This mirrors how `FFIDApiResponse` is narrowed on `data` / `error`.
+ */
+type FFIDProvisionUserResponse = FFIDProvisionUserOutcome | FFIDProvisionUserDryRun;
+/** A member to add to the provisioned organization. */
+interface FFIDProvisionOrganizationMemberInput {
+    email: string;
+    /** `owner` is intentionally excluded — the owner is set via `ownerEmail`. */
+    role: FFIDAssignableMemberRole;
+}
+/** Parameters for `provisionOrganization`. */
+interface FFIDProvisionOrganizationParams {
+    /** Organization display name (1–255 chars). */
+    name: string;
+    /**
+     * Email of the organization owner. The owner **must** already be an FFID user
+     * — provision them via `provisionUser` first, otherwise the call returns an
+     * `OWNER_NOT_FOUND` error (HTTP 422).
+     */
+    ownerEmail: string;
+    /** Optional billing contact email. */
+    billingEmail?: string;
+    /** Members to add idempotently (≤100 per request; validated client-side). */
+    members?: FFIDProvisionOrganizationMemberInput[];
+    /**
+     * When `true`, the server performs no writes and returns a
+     * {@link FFIDProvisionOrganizationDryRun} describing what a real call would do.
+     * @default false
+     */
+    dryRun?: boolean;
+}
+/** Minimal organization shape returned by the org provisioning helper. */
+interface FFIDProvisionedOrganization {
+    /** Organization ID (UUID). */
+    id: string;
+    /** Organization display name. */
+    name: string;
+    /** URL-safe slug. */
+    slug: string;
+}
+/** Per-member outcome status of a real (non-dry-run) organization provision. */
+type FFIDProvisionMemberStatus = 'added' | 'already_member' | 'user_not_found';
+/** Per-member outcome status of a dry-run organization provision. */
+type FFIDProvisionMemberPlanStatus = 'would_add' | 'already_member' | 'user_not_found';
+/** Per-member outcome of a real (non-dry-run) organization provision. */
+interface FFIDProvisionMemberResult {
+    email: string;
+    role: FFIDAssignableMemberRole;
+    /**
+     * - `added`          — membership was inserted.
+     * - `already_member` — user was already a member (idempotent no-op).
+     * - `user_not_found` — no FFID user exists for this email (skipped).
+     */
+    status: FFIDProvisionMemberStatus;
+}
+/** Per-member plan of a dry-run organization provision. */
+interface FFIDProvisionMemberPlan {
+    email: string;
+    role: FFIDAssignableMemberRole;
+    /**
+     * - `would_add`      — user exists and is not yet a member.
+     * - `already_member` — user is already a member of the existing org.
+     * - `user_not_found` — no FFID user exists for this email.
+     */
+    status: FFIDProvisionMemberPlanStatus;
+}
+/** Real (non-dry-run) organization provisioning outcome. */
+interface FFIDProvisionOrganizationOutcome {
+    /** Discriminant — absent/`false` for a real call. */
+    dryRun?: false;
+    /**
+     * `true`  → a brand-new organization was created (HTTP 201).
+     * `false` → the owner already owned an org with this name; idempotent (HTTP 200).
+     */
+    created: boolean;
+    organization: FFIDProvisionedOrganization;
+    /** Per-member results (added / already_member / user_not_found). */
+    members: FFIDProvisionMemberResult[];
+}
+/** Dry-run organization provisioning outcome — no writes performed. */
+interface FFIDProvisionOrganizationDryRun {
+    /** Discriminant — always `true` for a dry-run. */
+    dryRun: true;
+    /**
+     * Whether a real call would create a new organization. Coupled to
+     * `organization`: `wouldCreate === (organization === null)` — the server
+     * returns `organization: null` exactly when it would create a new org.
+     */
+    wouldCreate: boolean;
+    /** `null` when the org does not exist yet (would be created) — see `wouldCreate`. */
+    organization: FFIDProvisionedOrganization | null;
+    /** Per-member plans (would_add / already_member / user_not_found). */
+    members: FFIDProvisionMemberPlan[];
+}
+/**
+ * Response from `provisionOrganization`. Narrow on `dryRun`:
+ *
+ * ```ts
+ * if (res.dryRun) {
+ *   // FFIDProvisionOrganizationDryRun — inspect res.wouldCreate / res.organization (nullable)
+ * } else {
+ *   // FFIDProvisionOrganizationOutcome — inspect res.created / res.members
+ * }
+ * ```
+ *
+ * As with `FFIDProvisionUserResponse`, a real response omits `dryRun` on the
+ * wire, so narrow with `if (res.dryRun)` — not `res.dryRun === false`.
+ *
+ * When `ownerEmail` has no FFID user, the call resolves to
+ * `{ error: { code: 'OWNER_NOT_FOUND' } }` (HTTP 422) rather than a data branch.
+ */
+type FFIDProvisionOrganizationResponse = FFIDProvisionOrganizationOutcome | FFIDProvisionOrganizationDryRun;
+
 /**
  * Contract resource types (#3787 Phase A)
  *
@@ -1732,6 +1943,8 @@ declare function createFFIDClient(config: FFIDConfig): {
         organizationId: string;
         userId: string;
     }) => Promise<FFIDApiResponse<FFIDRemoveMemberResponse>>;
+    provisionUser: (params: FFIDProvisionUserParams) => Promise<FFIDApiResponse<FFIDProvisionUserResponse>>;
+    provisionOrganization: (params: FFIDProvisionOrganizationParams) => Promise<FFIDApiResponse<FFIDProvisionOrganizationResponse>>;
     getProfile: (options?: FFIDProfileCallOptions) => Promise<FFIDApiResponse<FFIDUserProfile>>;
     updateProfile: (data: FFIDUpdateUserProfileRequest, options?: FFIDProfileCallOptions) => Promise<FFIDApiResponse<FFIDUserProfile>>;
     getLoginHistory: (params?: FFIDGetLoginHistoryParams) => Promise<FFIDApiResponse<FFIDLoginHistoryResponse>>;
@@ -1815,4 +2028,4 @@ declare function createFFIDClient(config: FFIDConfig): {
 /** Type of the FFID client */
 type FFIDClient = ReturnType<typeof createFFIDClient>;
 
-export { type FFIDUpdateUserProfileRequest as A, type FFIDUser as B, type FFIDUserProfile as C, type TokenStore as D, createFFIDClient as E, type FFIDLogger as F, createTokenStore as G, type TokenData as T, type FFIDError as a, type FFIDCacheAdapter as b, type FFIDVerifyAccessTokenOptions as c, type FFIDApiResponse as d, type FFIDOAuthUserInfo as e, type FFIDAddMemberParams as f, type FFIDAddMemberRequest as g, type FFIDAddMemberResponse as h, type FFIDAssignableMemberRole as i, type FFIDCacheConfig as j, type FFIDClient as k, type FFIDConfig as l, type FFIDListMembersResponse as m, type FFIDMemberRole as n, type FFIDOrganization as o, type FFIDOrganizationMember as p, type FFIDOtpSendResponse as q, type FFIDOtpVerifyResponse as r, type FFIDPasswordResetConfirmResponse as s, type FFIDPasswordResetResponse as t, type FFIDPasswordResetVerifyResponse as u, type FFIDProfileCallOptions as v, type FFIDRemoveMemberResponse as w, type FFIDResetSessionResponse as x, type FFIDSubscription as y, type FFIDUpdateMemberRoleResponse as z };
+export { type FFIDProvisionOrganizationDryRun as A, type FFIDProvisionOrganizationMemberInput as B, type FFIDProvisionOrganizationOutcome as C, type FFIDProvisionOrganizationParams as D, type FFIDProvisionOrganizationResponse as E, type FFIDLogger as F, type FFIDProvisionUserDryRun as G, type FFIDProvisionUserOutcome as H, type FFIDProvisionUserParams as I, type FFIDProvisionUserProfileInput as J, type FFIDProvisionUserResponse as K, type FFIDProvisionedOrganization as L, type FFIDProvisionedUser as M, type FFIDRemoveMemberResponse as N, type FFIDResetSessionResponse as O, type FFIDSubscription as P, type FFIDUpdateMemberRoleResponse as Q, type FFIDUpdateUserProfileRequest as R, type FFIDUser as S, type FFIDUserProfile as T, type TokenData as U, type TokenStore as V, createFFIDClient as W, createTokenStore as X, type FFIDError as a, type FFIDCacheAdapter as b, type FFIDVerifyAccessTokenOptions as c, type FFIDApiResponse as d, type FFIDOAuthUserInfo as e, type FFIDAddMemberParams as f, type FFIDAddMemberRequest as g, type FFIDAddMemberResponse as h, type FFIDAssignableMemberRole as i, type FFIDCacheConfig as j, type FFIDClient as k, type FFIDConfig as l, type FFIDListMembersResponse as m, type FFIDMemberRole as n, type FFIDOrganization as o, type FFIDOrganizationMember as p, type FFIDOtpSendResponse as q, type FFIDOtpVerifyResponse as r, type FFIDPasswordResetConfirmResponse as s, type FFIDPasswordResetResponse as t, type FFIDPasswordResetVerifyResponse as u, type FFIDProfileCallOptions as v, type FFIDProvisionMemberPlan as w, type FFIDProvisionMemberPlanStatus as x, type FFIDProvisionMemberResult as y, type FFIDProvisionMemberStatus as z };