@feelflow/ffid-sdk 5.18.0 → 5.21.0

package/dist/{ffid-client-Cwk6cG3b.d.cts → ffid-client-BQPhm-XL.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)
  *
@@ -1438,6 +1649,19 @@ interface FFIDSessionResponse {
     organizations: FFIDOrganization[];
     subscriptions: FFIDSubscription[];
 }
+/**
+ * Optional metadata on successful {@link FFIDApiResponse} values (#4136).
+ *
+ * Present only on the success branch — error responses never carry `meta`.
+ */
+interface FFIDApiResponseMeta {
+    /**
+     * Set when introspect-strategy verification could not use the configured
+     * cache (adapter read/write failure or `crypto.subtle` unavailable).
+     * Visible without a custom logger; absent when cache operated normally.
+     */
+    verificationCacheDegraded?: true;
+}
 /**
  * API response wrapper (discriminated union for type safety)
  *
@@ -1447,10 +1671,33 @@ interface FFIDSessionResponse {
 type FFIDApiResponse<T> = {
     data: T;
     error?: undefined;
+    meta?: FFIDApiResponseMeta;
 } | {
     data?: undefined;
     error: FFIDError;
 };
+/**
+ * Result of `signOut()` (#4119, extended #4136).
+ *
+ * Local credentials (tokens / local state) are always cleared when `signOut()`
+ * resolves without `error`. `revoked` additionally indicates whether the
+ * server-side revocation/sign-out actually succeeded:
+ *
+ * - `revoked: true` — no server-side session/token remains active.
+ * - `revoked: false` — server-side revocation failed (network error or non-2xx
+ *   response). The access token may remain valid server-side until natural
+ *   expiry. Non-fatal: the local sign-out still completed, but callers that
+ *   need guaranteed revocation (e.g. shared-device flows) should surface this.
+ *
+ * Token mode (#4136): `accessTokenRevoked` / `refreshTokenRevoked` report each
+ * RFC 7009 revoke call. `revoked` is `true` only when every applicable token
+ * was revoked successfully. Cookie mode omits the per-token fields.
+ */
+interface FFIDSignOutResult {
+    revoked: boolean;
+    accessTokenRevoked?: boolean;
+    refreshTokenRevoked?: boolean;
+}
 
 /**
  * Response shape from `GET /api/v1/ext/analytics/config?service=<code>`.
@@ -1484,23 +1731,33 @@ interface FFIDAnalyticsConfig {
  *   has been fired **3 times within 60 seconds**. Caller should surface a
  *   manual "再度ログインする" UI rather than retry automatically (#2406 / #2411).
  *
- * SDK 2.18.0 only ships `'redirect_loop_detected'`. Other failure paths
- * (SSR environment, PKCE generation failure, empty organizationId) currently
- * return `error` without a `code`. New codes will be added in future minor
- * versions — treat this union as forward-extensible and do NOT exhaustively
- * `switch` over it without a `default` branch for consumer code that must
- * stay compatible across SDK upgrades.
+ * - `'state_persistence_failed'`: `redirectToAuthorize()` could not persist
+ *   the OAuth CSRF `state` (storage unavailable / quota). Redirect is aborted
+ *   fail-closed (#4136) — callers should surface a manual retry UI.
+ *
+ * Other failure paths (SSR environment, PKCE generation failure, empty
+ * organizationId) currently return `error` without a `code`. Treat this union
+ * as forward-extensible and do NOT exhaustively `switch` over it without a
+ * `default` branch for consumer code that must stay compatible across SDK
+ * upgrades.
  */
-type FFIDRedirectErrorCode = 'redirect_loop_detected';
+type FFIDRedirectErrorCode = 'redirect_loop_detected' | 'state_persistence_failed';
 /**
  * Result of a redirect operation (redirectToLogin / redirectToAuthorize / redirectToLogout)
  *
  * Structured return type so callers can inspect failure reasons
  * instead of receiving a bare `false`. When `code` is set, branch on it
  * for programmatic handling; otherwise log `error` for humans.
+ *
+ * `loopDetectionDisabled` (#4119): set to `true` when sessionStorage is
+ * unavailable (iOS WebKit private mode / eviction) so redirect-loop detection
+ * ran **fail-open** — the redirect fired, but repeated-redirect protection is
+ * disabled for this browser session. Callers that need loop protection on
+ * such browsers should add their own max-retry guard.
  */
 type FFIDRedirectResult = {
     success: true;
+    loopDetectionDisabled?: boolean;
 } | {
     success: false;
     error: string;
@@ -1695,7 +1952,7 @@ interface RedirectToAuthorizeOptions {
 /** Creates an FFID API client instance */
 declare function createFFIDClient(config: FFIDConfig): {
     getSession: () => Promise<FFIDApiResponse<FFIDSessionResponse>>;
-    signOut: () => Promise<FFIDApiResponse<void>>;
+    signOut: () => Promise<FFIDApiResponse<FFIDSignOutResult>>;
     redirectToLogin: (options?: RedirectToAuthorizeOptions) => Promise<FFIDRedirectResult>;
     redirectToAuthorize: (options?: RedirectToAuthorizeOptions) => Promise<FFIDRedirectResult>;
     redirectToLogout: (postLogoutRedirectUri?: string) => FFIDRedirectResult;
@@ -1732,6 +1989,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 +2074,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 };

package/dist/{ffid-client-w8Twi5lD.d.ts → ffid-client-Bx8y4SwC.d.ts}

@@ -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)
  *
@@ -1438,6 +1649,19 @@ interface FFIDSessionResponse {
     organizations: FFIDOrganization[];
     subscriptions: FFIDSubscription[];
 }
+/**
+ * Optional metadata on successful {@link FFIDApiResponse} values (#4136).
+ *
+ * Present only on the success branch — error responses never carry `meta`.
+ */
+interface FFIDApiResponseMeta {
+    /**
+     * Set when introspect-strategy verification could not use the configured
+     * cache (adapter read/write failure or `crypto.subtle` unavailable).
+     * Visible without a custom logger; absent when cache operated normally.
+     */
+    verificationCacheDegraded?: true;
+}
 /**
  * API response wrapper (discriminated union for type safety)
  *
@@ -1447,10 +1671,33 @@ interface FFIDSessionResponse {
 type FFIDApiResponse<T> = {
     data: T;
     error?: undefined;
+    meta?: FFIDApiResponseMeta;
 } | {
     data?: undefined;
     error: FFIDError;
 };
+/**
+ * Result of `signOut()` (#4119, extended #4136).
+ *
+ * Local credentials (tokens / local state) are always cleared when `signOut()`
+ * resolves without `error`. `revoked` additionally indicates whether the
+ * server-side revocation/sign-out actually succeeded:
+ *
+ * - `revoked: true` — no server-side session/token remains active.
+ * - `revoked: false` — server-side revocation failed (network error or non-2xx
+ *   response). The access token may remain valid server-side until natural
+ *   expiry. Non-fatal: the local sign-out still completed, but callers that
+ *   need guaranteed revocation (e.g. shared-device flows) should surface this.
+ *
+ * Token mode (#4136): `accessTokenRevoked` / `refreshTokenRevoked` report each
+ * RFC 7009 revoke call. `revoked` is `true` only when every applicable token
+ * was revoked successfully. Cookie mode omits the per-token fields.
+ */
+interface FFIDSignOutResult {
+    revoked: boolean;
+    accessTokenRevoked?: boolean;
+    refreshTokenRevoked?: boolean;
+}
 
 /**
  * Response shape from `GET /api/v1/ext/analytics/config?service=<code>`.
@@ -1484,23 +1731,33 @@ interface FFIDAnalyticsConfig {
  *   has been fired **3 times within 60 seconds**. Caller should surface a
  *   manual "再度ログインする" UI rather than retry automatically (#2406 / #2411).
  *
- * SDK 2.18.0 only ships `'redirect_loop_detected'`. Other failure paths
- * (SSR environment, PKCE generation failure, empty organizationId) currently
- * return `error` without a `code`. New codes will be added in future minor
- * versions — treat this union as forward-extensible and do NOT exhaustively
- * `switch` over it without a `default` branch for consumer code that must
- * stay compatible across SDK upgrades.
+ * - `'state_persistence_failed'`: `redirectToAuthorize()` could not persist
+ *   the OAuth CSRF `state` (storage unavailable / quota). Redirect is aborted
+ *   fail-closed (#4136) — callers should surface a manual retry UI.
+ *
+ * Other failure paths (SSR environment, PKCE generation failure, empty
+ * organizationId) currently return `error` without a `code`. Treat this union
+ * as forward-extensible and do NOT exhaustively `switch` over it without a
+ * `default` branch for consumer code that must stay compatible across SDK
+ * upgrades.
  */
-type FFIDRedirectErrorCode = 'redirect_loop_detected';
+type FFIDRedirectErrorCode = 'redirect_loop_detected' | 'state_persistence_failed';
 /**
  * Result of a redirect operation (redirectToLogin / redirectToAuthorize / redirectToLogout)
  *
  * Structured return type so callers can inspect failure reasons
  * instead of receiving a bare `false`. When `code` is set, branch on it
  * for programmatic handling; otherwise log `error` for humans.
+ *
+ * `loopDetectionDisabled` (#4119): set to `true` when sessionStorage is
+ * unavailable (iOS WebKit private mode / eviction) so redirect-loop detection
+ * ran **fail-open** — the redirect fired, but repeated-redirect protection is
+ * disabled for this browser session. Callers that need loop protection on
+ * such browsers should add their own max-retry guard.
  */
 type FFIDRedirectResult = {
     success: true;
+    loopDetectionDisabled?: boolean;
 } | {
     success: false;
     error: string;
@@ -1695,7 +1952,7 @@ interface RedirectToAuthorizeOptions {
 /** Creates an FFID API client instance */
 declare function createFFIDClient(config: FFIDConfig): {
     getSession: () => Promise<FFIDApiResponse<FFIDSessionResponse>>;
-    signOut: () => Promise<FFIDApiResponse<void>>;
+    signOut: () => Promise<FFIDApiResponse<FFIDSignOutResult>>;
     redirectToLogin: (options?: RedirectToAuthorizeOptions) => Promise<FFIDRedirectResult>;
     redirectToAuthorize: (options?: RedirectToAuthorizeOptions) => Promise<FFIDRedirectResult>;
     redirectToLogout: (postLogoutRedirectUri?: string) => FFIDRedirectResult;
@@ -1732,6 +1989,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 +2074,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 };