@feelflow/ffid-sdk 5.12.0 → 5.14.0

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { F as FFIDSubscriptionStatus, a as FFIDConfig, b as FFIDApiResponse, c as FFIDSessionResponse, d as FFIDRedirectResult, e as FFIDError, f as FFIDSubscriptionCheckResponse, g as FFIDCheckServiceAccessParams, h as FFIDServiceAccessDecision, i as FFIDProfileCallOptions, j as FFIDUserProfile, k as FFIDUpdateUserProfileRequest, l as FFIDAnalyticsConfig, m as FFIDVerifyAccessTokenOptions, n as FFIDOAuthUserInfo, o as FFIDInquiryCreateParams, p as FFIDInquiryCreateResponse, q as FFIDAuthMode, r as FFIDLogger, s as FFIDCacheAdapter, t as FFIDUser, u as FFIDOrganization, v as FFIDSubscription, w as FFIDSubscriptionContextValue, E as EffectiveSubscriptionStatus, x as FFIDOAuthUserInfoSubscription, y as FFIDAnnouncementsClientConfig, L as ListAnnouncementsOptions, z as FFIDAnnouncementsApiResponse, A as AnnouncementListResponse, B as FFIDAnnouncementsLogger } from './index-DqsWKU16.js';
-export { C as Announcement, D as AnnouncementStatus, G as AnnouncementType, H as EFFECTIVE_SUBSCRIPTION_STATUSES, I as FFIDAnnouncementBadge, J as FFIDAnnouncementList, K as FFIDAnnouncementsError, M as FFIDAnnouncementsErrorCode, N as FFIDAnnouncementsServerResponse, O as FFIDCacheConfig, P as FFIDContextValue, Q as FFIDInquiryCategory, R as FFIDInquiryCategorySite2026, S as FFIDInquiryForm, T as FFIDInquiryFormCategoryItem, U as FFIDInquiryFormClassNames, V as FFIDInquiryFormLegalLayout, W as FFIDInquiryFormOrganization, X as FFIDInquiryFormPlaceholderContext, Y as FFIDInquiryFormPrefill, Z as FFIDInquiryFormProps, _ as FFIDInquiryFormSubmitData, $ as FFIDInquiryFormSubmitResult, a0 as FFIDJwtClaims, a1 as FFIDLoginButton, a2 as FFIDOAuthTokenResponse, a3 as FFIDOAuthUserInfoMemberRole, a4 as FFIDOrganizationSwitcher, a5 as FFIDRedirectErrorCode, a6 as FFIDSeatModel, a7 as FFIDServiceAccessDenialReason, a8 as FFIDServiceAccessFailPolicy, a9 as FFIDSubscriptionBadge, aa as FFIDTokenIntrospectionResponse, ab as FFIDUserMenu, ac as FFID_INQUIRY_CATEGORIES, ad as FFID_INQUIRY_CATEGORIES_SITE_2026, ae as UseFFIDAnnouncementsOptions, af as UseFFIDAnnouncementsReturn, ag as isFFIDInquiryCategorySite2026, ah as useFFIDAnnouncements } from './index-DqsWKU16.js';
+import { F as FFIDSubscriptionStatus, a as FFIDConfig, b as FFIDApiResponse, c as FFIDSessionResponse, d as FFIDRedirectResult, e as FFIDError, f as FFIDSubscriptionCheckResponse, g as FFIDCheckServiceAccessParams, h as FFIDServiceAccessDecision, i as FFIDAnalyticsConfig, j as FFIDVerifyAccessTokenOptions, k as FFIDOAuthUserInfo, l as FFIDInquiryCreateParams, m as FFIDInquiryCreateResponse, n as FFIDAuthMode, o as FFIDLogger, p as FFIDCacheAdapter, q as FFIDUser, r as FFIDOrganization, s as FFIDSubscription, t as FFIDSubscriptionContextValue, E as EffectiveSubscriptionStatus, u as FFIDOAuthUserInfoSubscription, v as FFIDAnnouncementsClientConfig, L as ListAnnouncementsOptions, w as FFIDAnnouncementsApiResponse, A as AnnouncementListResponse, x as FFIDAnnouncementsLogger } from './index-CsVJTuPv.js';
+export { y as Announcement, z as AnnouncementStatus, B as AnnouncementType, C as EFFECTIVE_SUBSCRIPTION_STATUSES, D as FFIDAnnouncementBadge, G as FFIDAnnouncementList, H as FFIDAnnouncementsError, I as FFIDAnnouncementsErrorCode, J as FFIDAnnouncementsServerResponse, K as FFIDCacheConfig, M as FFIDContextValue, N as FFIDInquiryCategory, O as FFIDInquiryCategorySite2026, P as FFIDInquiryForm, Q as FFIDInquiryFormCategoryItem, R as FFIDInquiryFormClassNames, S as FFIDInquiryFormLegalLayout, T as FFIDInquiryFormOrganization, U as FFIDInquiryFormPlaceholderContext, V as FFIDInquiryFormPrefill, W as FFIDInquiryFormProps, X as FFIDInquiryFormSubmitData, Y as FFIDInquiryFormSubmitResult, Z as FFIDJwtClaims, _ as FFIDLoginButton, $ as FFIDOAuthTokenResponse, a0 as FFIDOAuthUserInfoMemberRole, a1 as FFIDOrganizationSwitcher, a2 as FFIDRedirectErrorCode, a3 as FFIDSeatModel, a4 as FFIDServiceAccessDenialReason, a5 as FFIDServiceAccessFailPolicy, a6 as FFIDSubscriptionBadge, a7 as FFIDTokenIntrospectionResponse, a8 as FFIDUserMenu, a9 as FFID_INQUIRY_CATEGORIES, aa as FFID_INQUIRY_CATEGORIES_SITE_2026, ab as UseFFIDAnnouncementsOptions, ac as UseFFIDAnnouncementsReturn, ad as isFFIDInquiryCategorySite2026, ae as useFFIDAnnouncements } from './index-CsVJTuPv.js';
 export { A as ALL_DENIED_EXCEPT_NECESSARY, i as CONSENT_COOKIE_NAME, j as CONSENT_DISMISSAL_TIMESTAMP_KEY, l as COOKIE_VERSION, D as DEFAULT_CONSENT_ERROR_MESSAGES, o as FFIDAnalyticsProvider, p as FFIDAnalyticsProviderProps, c as FFIDConsentCategories, r as FFIDConsentCategoryCode, e as FFIDConsentCategoryMetadata, w as FFIDConsentError, x as FFIDConsentErrorCode, y as FFIDConsentMergeStrategy, B as FFIDConsentMergeWarning, E as FFIDConsentMergeWarningEvent, F as FFIDConsentResult, I as FFIDConsentSource, a as FFIDConsentState, d as FFIDConsentSyncResult, M as FFIDCookieBanner, N as FFIDCookieBannerClassNames, O as FFIDCookieBannerProps, Q as FFIDCookieLink, R as FFIDCookieLinkProps, f as FFIDCookiePolicy, T as FFIDCookieSettings, U as FFIDCookieSettingsClassNames, V as FFIDCookieSettingsProps, _ as FFID_CONSENT_ERROR_CODES, ae as UseFFIDConsentPreferencesReturn, af as UseFFIDConsentReturn, ag as clearConsentDismissalTimestamp, aj as decodeConsentCookie, al as encodeConsentCookie, an as readConsentCookie, ao as readConsentDismissalTimestamp, aq as useFFIDConsent, ar as useFFIDConsentPreferences, as as writeConsentCookie, at as writeConsentDismissalTimestamp } from './FFIDCookieLink-D1WwE_ZO.js';
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import { ReactNode, ComponentType, FC } from 'react';
@@ -122,6 +122,35 @@ declare function storeCodeVerifier(verifier: string, logger?: PKCELogger): boole
  */
 declare function retrieveCodeVerifier(logger?: PKCELogger): string | null;
 
+/** Logger interface matching FFIDLogger for optional warning output */
+interface StateLogger {
+    warn: (...args: unknown[]) => void;
+}
+/**
+ * Store the OAuth `state` for later retrieval.
+ *
+ * Writes to both sessionStorage (primary) and localStorage (fallback for iOS
+ * WebKit sessionStorage eviction during external OAuth bounces). Returns true
+ * if at least one write succeeded.
+ *
+ * @param state - The OAuth state value to store
+ * @param logger - Optional logger for warning on storage failure
+ * @returns true if stored in at least one storage, false otherwise
+ */
+declare function storeState(state: string, logger?: StateLogger): boolean;
+/**
+ * Retrieve and remove the OAuth `state`.
+ *
+ * Reads from sessionStorage first, falls back to localStorage (with 5-minute TTL).
+ * Removes from all storages after retrieval (one-time use). Returns null if no
+ * state is stored, the fallback is stale (>5 min), or storage is unavailable.
+ *
+ * @param logger - Optional logger for warning on storage failure
+ */
+declare function retrieveState(logger?: StateLogger): string | null;
+
+declare function cleanupStateStorage(logger?: StateLogger): void;
+
 /**
  * Billing checkout / portal session types.
  *
@@ -651,6 +680,307 @@ interface FFIDRetryPaymentSummary {
     failures: FFIDRetryPaymentFailure[];
 }
 
+/**
+ * Login history types (ext API).
+ *
+ * Mirrors the data shape returned by `GET /api/v1/users/ext/me/login-history`
+ * (and its cookie counterpart `/api/v1/users/me/login-history`), which is
+ * derived from `audit_logs` rows. Field names are `camelCase` to match the
+ * route's `data` payload.
+ */
+/**
+ * A single login-history entry.
+ *
+ * Each entry corresponds to one auth audit event (sign-in / sign-out /
+ * password-reset). Failed attempts are flagged via {@link isSuspicious}.
+ */
+interface FFIDLoginHistoryEntry {
+    /** Audit log entry id (UUID). */
+    id: string;
+    /** ISO 8601 timestamp of the event. */
+    timestamp: string;
+    /** Source IP address, or `null` when not recorded. */
+    ipAddress: string | null;
+    /** User agent string, or `null` when not recorded. */
+    userAgent: string | null;
+    /** Audit action (e.g. `auth.signin`, `auth.signout`, `auth.password_reset`). */
+    action: string;
+    /** Whether the auth event succeeded or failed. */
+    result: 'success' | 'failure';
+    /** `true` for failed attempts (currently equivalent to `result === 'failure'`). */
+    isSuspicious: boolean;
+}
+/**
+ * Response payload from `getLoginHistory`.
+ *
+ * `total` is the number of entries returned (not a global count) — it equals
+ * `history.length`, matching the route's `{ history, total }` envelope.
+ */
+interface FFIDLoginHistoryResponse {
+    /** Recent login-history entries, newest first. */
+    history: FFIDLoginHistoryEntry[];
+    /** Number of entries returned (equal to `history.length`). */
+    total: number;
+}
+
+/**
+ * Types for the organization verified-domains ext API.
+ *
+ * Mirrors the `VerifiedDomain` row shape returned by the FFID server route
+ * `GET /api/v1/organizations/ext/domains` (data field of the response).
+ *
+ * @see Issue #3783 (non-contract SDK coverage)
+ * @see Issue #3757 (verified-domain claims)
+ */
+/** A single organization verified-domain claim. */
+interface FFIDOrganizationDomain {
+    /** Domain claim ID (UUID) */
+    id: string;
+    /** Owning organization ID (UUID) */
+    organizationId: string;
+    /** Claimed domain (normalized, e.g. `example.com`) */
+    domain: string;
+    /** Token to publish as a DNS TXT record to prove ownership */
+    verificationToken: string;
+    /** When ownership was verified, or `null` while the claim is still pending */
+    verifiedAt: string | null;
+    /** User ID (UUID) that verified the claim, or `null` while pending */
+    verifiedBy: string | null;
+    /** Whether same-domain users can discover & request to join (only meaningful once verified) */
+    discoverable: boolean;
+    /** When the claim was created */
+    createdAt: string;
+    /** When the claim was last updated */
+    updatedAt: string;
+}
+/** Response from getOrganizationDomains (ext). */
+interface FFIDOrganizationDomainsResponse {
+    domains: FFIDOrganizationDomain[];
+}
+
+/**
+ * Organization billing notification preference types (ext API).
+ *
+ * Mirrors the FFID backend `billing_notification_preferences` shape exposed via
+ * `GET /api/v1/organizations/ext/notification-preferences` and the matching
+ * `PATCH`. Keys use the backend's snake_case casing because they map directly to
+ * the stored JSONB column.
+ */
+/**
+ * An organization's billing notification preferences.
+ *
+ * `payment_failed` is a legal obligation and is always `true` — the server
+ * forces it on read and write regardless of the requested value.
+ */
+interface FFIDOrganizationNotificationPreferences {
+    /** Whether renewal reminder notifications are enabled */
+    renewal_reminders: boolean;
+    /** Whether monthly usage/summary notifications are enabled */
+    monthly_summary: boolean;
+    /** Always true — payment failure notifications cannot be disabled (legal obligation) */
+    payment_failed: boolean;
+}
+/** Response from getNotificationPreferences / updateNotificationPreferences (ext) */
+interface FFIDOrganizationNotificationPreferencesResponse {
+    preferences: FFIDOrganizationNotificationPreferences;
+}
+/**
+ * Request payload for updateNotificationPreferences (ext).
+ *
+ * Partial of the writable keys — only the supplied keys are updated. Omitted
+ * keys are reset to their default (`true`) on the server. `payment_failed` is
+ * not writable: it is always forced to `true`.
+ */
+type FFIDUpdateNotificationPreferencesRequest = Partial<Pick<FFIDOrganizationNotificationPreferences, 'renewal_reminders' | 'monthly_summary'>>;
+
+/**
+ * Invitation status returned by the ext invite endpoint.
+ *
+ * A freshly created invitation is always `pending`; the broader union is
+ * included to match the route's `status` field (sourced from the invitations
+ * table) so consumers can narrow safely.
+ */
+type FFIDInvitationStatus = 'pending' | 'accepted' | 'expired' | 'cancelled';
+/** Request body for inviteMember (ext) */
+interface FFIDInviteMemberRequest {
+    /** Email address to invite */
+    email: string;
+    /** Role to assign on acceptance (defaults to `member` server-side) */
+    role?: FFIDAssignableMemberRole;
+}
+/**
+ * Response from inviteMember (ext).
+ *
+ * Matches the `/api/v1/organizations/ext/invite` route data exactly:
+ * `{ id, email, role, status, expiresAt }`.
+ */
+interface FFIDInviteMemberResponse {
+    /** Invitation ID (UUID) */
+    id: string;
+    /** Invited email address (normalized server-side) */
+    email: string;
+    /** Role assigned to the invitation */
+    role: FFIDMemberRole;
+    /** Invitation lifecycle status (always `pending` on creation) */
+    status: FFIDInvitationStatus;
+    /** ISO 8601 timestamp when the invitation expires */
+    expiresAt: string;
+}
+
+/**
+ * Types for the user-scoped organization membership methods (ext API).
+ *
+ * Backs `leaveOrganization` — a DESTRUCTIVE self-leave operation against
+ * `DELETE /api/v1/users/ext/me/organizations/:organizationId`.
+ */
+/**
+ * Parameters for `leaveOrganization`.
+ *
+ * `userId` is REQUIRED in `service-key` auth mode (there is no ambient user on
+ * a service credential, so the leaving user must be named explicitly). In
+ * `token` / `cookie` modes it is derived server-side from the credential and
+ * may be omitted; if provided in those modes it is ignored by the server.
+ */
+interface FFIDLeaveOrganizationParams {
+    /** The organization the user is leaving (UUID). */
+    organizationId: string;
+    /**
+     * The leaving user's id (UUID). Required for `service-key` mode; optional
+     * (and server-ignored) for `token` / `cookie` modes.
+     */
+    userId?: string;
+}
+/**
+ * Response from `leaveOrganization` (ext).
+ *
+ * Matches the route's success `data` shape `{ message }`.
+ */
+interface FFIDLeaveOrganizationResponse {
+    /** Human-readable confirmation message (Japanese). */
+    message: string;
+}
+
+/**
+ * User profile types (ext API: `GET` / `PUT /api/v1/users/ext/me`).
+ *
+ * Extracted from `./index.ts` to keep the types barrel under the file-size
+ * limit, consistent with the per-domain extraction already used for
+ * `service-access`, `organization-members`, `contract-resources`, etc. The
+ * barrel re-exports these so the public import path (`@feelflow/ffid-sdk`)
+ * is unchanged.
+ */
+/**
+ * User profile for the authenticated user (returned by `getProfile` / `updateProfile`).
+ *
+ * Mirrors the FFID backend `UserProfile` shape exposed via
+ * `GET /api/v1/users/ext/me` and `PUT /api/v1/users/ext/me`.
+ */
+interface FFIDUserProfile {
+    /** User ID (UUID) */
+    id: string;
+    /** Email address */
+    email: string;
+    /** Display name (nullable when not set) */
+    displayName: string | null;
+    /** Avatar URL (nullable when not set) */
+    avatarUrl: string | null;
+    /** Phone number (nullable when not set) */
+    phone: string | null;
+    /** Company name (nullable when not set) */
+    companyName: string | null;
+    /** Department (nullable when not set) */
+    department: string | null;
+    /** Job title (nullable when not set) */
+    jobTitle: string | null;
+    /** IANA timezone (e.g. 'Asia/Tokyo') */
+    timezone: string;
+    /** Locale (e.g. 'ja', 'en') */
+    locale: string;
+    /** Arbitrary user preferences bag */
+    preferences: Record<string, unknown>;
+    /** Account creation timestamp (ISO 8601) */
+    createdAt: string;
+    /** Profile last-updated timestamp (ISO 8601) */
+    updatedAt: string;
+}
+/**
+ * Per-call options for profile methods (`getProfile` / `updateProfile`).
+ *
+ * Supply `accessToken` to forward an end-user Bearer token for the single call
+ * without mutating client-level auth state. Designed for server runtimes (Cloudflare
+ * Workers, Edge, Node) that receive a user-scoped Bearer per request and want to
+ * act as that user against `/api/v1/users/ext/me`.
+ *
+ * When `accessToken` is supplied with a non-empty value, it overrides the client's
+ * configured auth mode: authentication for that request uses only
+ * `Authorization: Bearer <accessToken>` (no service key, no cookie, no token-store
+ * lookup, no auto-refresh on 401). Non-auth headers such as `Content-Type` are
+ * still attached. SDK metadata headers (`User-Agent` / `X-FFID-SDK-Version`) are
+ * attached on non-browser runtimes only (Node.js / Cloudflare Workers / Edge /
+ * Deno); browsers receive an empty object to avoid iOS WebKit `fetch()` breakage
+ * (see #2417).
+ *
+ * Runtime semantics:
+ * - `accessToken` omitted (or `undefined`) → no override, configured `authMode` is used
+ * - `accessToken` is empty string / whitespace-only → rejected as `VALIDATION_ERROR`
+ *   before any network call (prevents silent impersonation fallback when a caller
+ *   extracts a missing/blank `Authorization` header into this field)
+ * - `accessToken` is a non-empty string → override activated
+ */
+interface FFIDProfileCallOptions {
+    /**
+     * End-user Bearer token forwarded for this single request.
+     *
+     * Must be a non-empty string when supplied. Passing `''` or a whitespace-only
+     * string is treated as a caller error and surfaces as `VALIDATION_ERROR` —
+     * this guards against the common footgun where a server runtime extracts the
+     * Bearer from an incoming request without checking the header is present.
+     */
+    accessToken?: string;
+}
+/**
+ * Request payload for `updateProfile`.
+ *
+ * Mirrors the FFID backend `UpdateUserProfileRequest` shape. All fields are
+ * optional — only the supplied keys will be updated (partial update semantics).
+ *
+ * Per-field value semantics:
+ * - `undefined` / key omitted → field is untouched (partial update)
+ * - `null` → clears the field (stores SQL NULL in the DB)
+ * - `""` (empty string) → stored as a literal empty string, **not** treated as
+ *   a clear. Use `null` when you want the DB value to become NULL
+ *
+ * `timezone` and `locale` are intentionally modeled as non-null in this
+ * request type (application-level invariant — the DB columns have DEFAULT
+ * values but no NOT NULL constraint, yet the server-side normalization
+ * pipeline assumes a string is always present). Pass a string to update the
+ * value, or omit the key to leave the current value in place. Do not pass
+ * `null` to clear — there is no meaningful "no timezone" state for a user.
+ *
+ * `preferences: null` is accepted and clears the column. Subsequent reads
+ * return `{}` because the FFID backend normalizes a null `preferences` column
+ * to an empty object (`toUserProfile` helper) before serializing the response —
+ * the SDK itself does not transform the payload.
+ */
+interface FFIDUpdateUserProfileRequest {
+    /** Display name (null clears the field) */
+    displayName?: string | null;
+    /** Phone number (null clears the field) */
+    phone?: string | null;
+    /** Company name (null clears the field) */
+    companyName?: string | null;
+    /** Department (null clears the field) */
+    department?: string | null;
+    /** Job title (null clears the field) */
+    jobTitle?: string | null;
+    /** IANA timezone (non-null; omit the key to leave unchanged) */
+    timezone?: string;
+    /** Locale (non-null; omit the key to leave unchanged) */
+    locale?: string;
+    /** Arbitrary user preferences bag (null clears the column; reads return {}) */
+    preferences?: Record<string, unknown> | null;
+}
+
 /** OTP / magic link methods - sendOtp / verifyOtp */
 
 /** Response from sendOtp */
@@ -716,6 +1046,45 @@ interface ContractWizardSubscriptionOptions {
     organizationId?: string;
 }
 
+/** Login history methods - getLoginHistory (ext API) */
+
+/** Parameters accepted by `getLoginHistory`. */
+interface FFIDGetLoginHistoryParams {
+    /**
+     * Target user id (UUID).
+     *
+     * **Required in `service-key` auth mode** — an `X-Service-Api-Key` request
+     * has no ambient user, so the server requires `?userId=` to know whose
+     * history to return. In `token` / `cookie` auth modes the user is derived
+     * server-side from the credential, so `userId` is ignored if supplied.
+     */
+    userId?: string;
+    /**
+     * Maximum number of entries to return. Clamped server-side to the route's
+     * ceiling (20); omit to use the default.
+     */
+    limit?: number;
+}
+
+/** OAuth token operations - exchangeCodeForTokens / refreshAccessToken / signOutToken */
+
+/**
+ * Optional OAuth `state` validation for {@link exchangeCodeForTokens}.
+ *
+ * If a `state` is supplied on EITHER side — `expectedState` (the value persisted
+ * at `redirectToAuthorize`) or `actualState` (the value returned on the callback
+ * URL) — both must be present and equal before any token exchange. A mismatch
+ * OR an omitted counterpart fails closed (no exchange) to defend against CSRF
+ * (RFC 6749 §10.12 / #3841). Validation is skipped only when BOTH are omitted
+ * (backward compatible — callers that don't opt in are unaffected).
+ */
+interface ExchangeCodeForTokensOptions {
+    /** Stored state from `redirectToAuthorize` (e.g. `retrieveState()`) */
+    expectedState?: string;
+    /** State returned on the OAuth callback URL */
+    actualState?: string;
+}
+
 /** Redirect and URL generation - redirectToLogin / redirectToAuthorize / redirectToLogout / getLoginUrl / getSignupUrl / getLogoutUrl */
 
 /**
@@ -755,7 +1124,7 @@ declare function createFFIDClient(config: FFIDConfig): {
     getLogoutUrl: (postLogoutRedirectUri?: string) => string;
     getSignupUrl: (redirectUrl?: string) => string;
     createError: (code: string, message: string) => FFIDError;
-    exchangeCodeForTokens: (code: string, codeVerifier?: string) => Promise<FFIDApiResponse<void>>;
+    exchangeCodeForTokens: (code: string, codeVerifier?: string, opts?: ExchangeCodeForTokensOptions) => Promise<FFIDApiResponse<void>>;
     refreshAccessToken: () => Promise<FFIDApiResponse<void>>;
     checkSubscription: (params: {
         userId?: string;
@@ -781,6 +1150,23 @@ declare function createFFIDClient(config: FFIDConfig): {
     }) => Promise<FFIDApiResponse<FFIDRemoveMemberResponse>>;
     getProfile: (options?: FFIDProfileCallOptions) => Promise<FFIDApiResponse<FFIDUserProfile>>;
     updateProfile: (data: FFIDUpdateUserProfileRequest, options?: FFIDProfileCallOptions) => Promise<FFIDApiResponse<FFIDUserProfile>>;
+    getLoginHistory: (params?: FFIDGetLoginHistoryParams) => Promise<FFIDApiResponse<FFIDLoginHistoryResponse>>;
+    getOrganizationDomains: (params: {
+        organizationId: string;
+    }) => Promise<FFIDApiResponse<FFIDOrganizationDomainsResponse>>;
+    getNotificationPreferences: (params: {
+        organizationId: string;
+    }) => Promise<FFIDApiResponse<FFIDOrganizationNotificationPreferencesResponse>>;
+    updateNotificationPreferences: (params: {
+        organizationId: string;
+        preferences: FFIDUpdateNotificationPreferencesRequest;
+    }) => Promise<FFIDApiResponse<FFIDOrganizationNotificationPreferencesResponse>>;
+    inviteMember: (params: {
+        organizationId: string;
+        email: string;
+        role?: FFIDAssignableMemberRole;
+    }) => Promise<FFIDApiResponse<FFIDInviteMemberResponse>>;
+    leaveOrganization: (params: FFIDLeaveOrganizationParams) => Promise<FFIDApiResponse<FFIDLeaveOrganizationResponse>>;
     getAnalyticsConfig: (serviceCode: string, options?: FFIDProfileCallOptions) => Promise<FFIDApiResponse<FFIDAnalyticsConfig>>;
     createCheckoutSession: (params: FFIDCreateCheckoutParams) => Promise<FFIDApiResponse<FFIDCheckoutSessionResponse>>;
     createPortalSession: (params: FFIDCreatePortalParams) => Promise<FFIDApiResponse<FFIDPortalSessionResponse>>;
@@ -857,6 +1243,52 @@ declare class FFIDSDKError extends Error {
     constructor(code: string, message: string);
 }
 
+/**
+ * OAuth redirect callback handler
+ *
+ * `handleRedirectCallback` is the convenience counterpart to
+ * `redirectToAuthorize`: it reads `code` + `state` from the callback URL,
+ * validates the OAuth `state` against the value persisted at authorize time
+ * (CSRF protection, RFC 6749 §10.12), retrieves the PKCE verifier, exchanges
+ * the code for tokens, and cleans the params out of the URL on success.
+ */
+
+/**
+ * Minimal client surface required by {@link handleRedirectCallback}.
+ * A full {@link FFIDClient} satisfies this structurally.
+ */
+type HandleRedirectCallbackClient = Pick<FFIDClient, 'exchangeCodeForTokens' | 'createError' | 'logger'>;
+/** Options for {@link handleRedirectCallback} */
+interface HandleRedirectCallbackOptions {
+    /**
+     * Callback URL (or query string) to read `code` / `state` from. Accepts an
+     * absolute URL, a relative URL, or a bare query string. Defaults to
+     * `window.location.search` in the browser.
+     */
+    url?: string;
+}
+/**
+ * Complete an OAuth authorization-code redirect.
+ *
+ * Behavior:
+ * 1. Reads `code` + `state` from `options.url ?? window.location.search`.
+ * 2. CSRF guard: if a `state` exists on EITHER side (a stored state from
+ *    authorize OR a `state` on the callback URL), the two MUST match — mismatch,
+ *    a missing stored state, or an **omitted** callback `state` all **fail closed**
+ *    (returns an error, performs no exchange). Validation is skipped ONLY when
+ *    neither side has any state (a genuine no-state flow). Omitting the callback
+ *    `state` does NOT bypass the check (#3841).
+ * 3. Retrieves the PKCE verifier and exchanges the code for tokens.
+ * 4. On success, removes `code` + `state` from the browser URL.
+ *
+ * SSR-safe: when there is no `window` and no `options.url`, no exchange is
+ * attempted and an error result is returned.
+ *
+ * @param client - FFID client (or any object exposing exchangeCodeForTokens / createError / logger)
+ * @param options - Optional callback URL override
+ */
+declare function handleRedirectCallback(client: HandleRedirectCallbackClient, options?: HandleRedirectCallbackOptions): Promise<FFIDApiResponse<void>>;
+
 /**
  * Redirect URI normalization (SDK copy)
  *
@@ -1565,4 +1997,4 @@ declare function createInquiryMethods(deps: InquiryMethodsDeps): {
 };
 type FFIDInquiryClient = ReturnType<typeof createInquiryMethods>;
 
-export { ACCESS_GRANTING_EFFECTIVE_STATUSES, AnnouncementListResponse, BLOCKING_EFFECTIVE_STATUSES, type ComputeEffectiveStatusInput, type ContractWizardFlowType, type ContractWizardResubscribeOptions, type ContractWizardSubscribeOptions, type ContractWizardSubscriptionOptions, DEFAULT_API_BASE_URL, DEFAULT_OAUTH_SCOPES, EffectiveSubscriptionStatus, type FFIDAddMemberParams, type FFIDAddMemberRequest, type FFIDAddMemberResponse, FFIDAnnouncementsApiResponse, type FFIDAnnouncementsClient, FFIDAnnouncementsClientConfig, FFIDAnnouncementsLogger, FFIDApiResponse, type FFIDAssignableMemberRole, type FFIDBillingInterval, FFIDCacheAdapter, type FFIDCancelPendingDowngradeResponse, type FFIDCancelSubscriptionParams, type FFIDCancelSubscriptionResponse, type FFIDChangePlanParams, type FFIDChangePlanResponse, FFIDCheckServiceAccessParams, type FFIDCheckoutSessionResponse, type FFIDClient, FFIDConfig, type FFIDCreateCheckoutParams, type FFIDCreatePortalParams, FFIDError, type FFIDInquiryClient, FFIDInquiryCreateParams, FFIDInquiryCreateResponse, type FFIDListMembersResponse, type FFIDListPlansResponse, FFIDLogger, type FFIDMemberRole, type FFIDMemberStatus, type FFIDNewsletterBodySource, type FFIDNewsletterCampaignStatus, type FFIDNewsletterClient, type FFIDNewsletterConfirmParams, type FFIDNewsletterConfirmResponse, type FFIDNewsletterDispatchParams, type FFIDNewsletterDispatchResponse, type FFIDNewsletterSegment, type FFIDNewsletterSubscribeParams, type FFIDNewsletterSubscribeResponse, type FFIDNewsletterType, type FFIDNewsletterUnsubscribeParams, type FFIDNewsletterUnsubscribeResponse, FFIDOAuthUserInfo, FFIDOAuthUserInfoSubscription, FFIDOrganization, type FFIDOrganizationMember, type FFIDOtpSendResponse, type FFIDOtpVerifyResponse, type FFIDPasswordResetConfirmResponse, type FFIDPasswordResetResponse, type FFIDPasswordResetVerifyResponse, type FFIDPlanChangeLineItem, type FFIDPlanChangePreview, type FFIDPlanChangePreviewResponse, type FFIDPlanInfo, type FFIDPortalSessionResponse, type FFIDPreviewPlanChangeParams, type FFIDPreviewSeatChangeParams, FFIDProfileCallOptions, FFIDProvider, type FFIDProviderProps, FFIDRedirectResult, type FFIDRemoveMemberResponse, type FFIDResetSessionResponse, FFIDSDKError, type FFIDSeatChangeLineItem, type FFIDSeatChangePreview, type FFIDSeatChangePreviewResponse, FFIDServiceAccessDecision, type FFIDServiceInfo, FFIDSessionResponse, type FFIDSubscribeParams, type FFIDSubscribeResponse, FFIDSubscription, FFIDSubscriptionCheckResponse, FFIDSubscriptionContextValue, type FFIDSubscriptionDetail, FFIDSubscriptionStatus, type FFIDSubscriptionSummary, type FFIDSupportedCurrency, type FFIDUpdateMemberRoleResponse, FFIDUpdateUserProfileRequest, FFIDUser, FFIDUserProfile, FFIDVerifyAccessTokenOptions, FFID_ANNOUNCEMENTS_ERROR_CODES, FFID_NEWSLETTER_DISPATCH_MAX_RECIPIENTS, FFID_NEWSLETTER_TYPES, type KVNamespaceLike, ListAnnouncementsOptions, type NormalizeRedirectUriResult, type RedirectToAuthorizeOptions, type TokenData, type TokenStore, type UseFFIDReturn, type UseRequireActiveSubscriptionOptions, type UseRequireActiveSubscriptionReturn, type WithFFIDAuthOptions, type WithSubscriptionOptions, computeEffectiveStatusFromSession, createFFIDAnnouncementsClient, createFFIDClient, createKVCacheAdapter, createMemoryCacheAdapter, createTokenStore, generateCodeChallenge, generateCodeVerifier, hasAccessFromUserinfo, isBlockedFromUserinfo, normalizeRedirectUri, retrieveCodeVerifier, storeCodeVerifier, useFFID, useRequireActiveSubscription, useSubscription, withFFIDAuth, withSubscription };
+export { ACCESS_GRANTING_EFFECTIVE_STATUSES, AnnouncementListResponse, BLOCKING_EFFECTIVE_STATUSES, type ComputeEffectiveStatusInput, type ContractWizardFlowType, type ContractWizardResubscribeOptions, type ContractWizardSubscribeOptions, type ContractWizardSubscriptionOptions, DEFAULT_API_BASE_URL, DEFAULT_OAUTH_SCOPES, EffectiveSubscriptionStatus, type ExchangeCodeForTokensOptions, type FFIDAddMemberParams, type FFIDAddMemberRequest, type FFIDAddMemberResponse, FFIDAnnouncementsApiResponse, type FFIDAnnouncementsClient, FFIDAnnouncementsClientConfig, FFIDAnnouncementsLogger, FFIDApiResponse, type FFIDAssignableMemberRole, type FFIDBillingInterval, FFIDCacheAdapter, type FFIDCancelPendingDowngradeResponse, type FFIDCancelSubscriptionParams, type FFIDCancelSubscriptionResponse, type FFIDChangePlanParams, type FFIDChangePlanResponse, FFIDCheckServiceAccessParams, type FFIDCheckoutSessionResponse, type FFIDClient, FFIDConfig, type FFIDCreateCheckoutParams, type FFIDCreatePortalParams, FFIDError, type FFIDInquiryClient, FFIDInquiryCreateParams, FFIDInquiryCreateResponse, type FFIDInvitationStatus, type FFIDInviteMemberRequest, type FFIDInviteMemberResponse, type FFIDLeaveOrganizationParams, type FFIDLeaveOrganizationResponse, type FFIDListMembersResponse, type FFIDListPlansResponse, FFIDLogger, type FFIDLoginHistoryEntry, type FFIDLoginHistoryResponse, type FFIDMemberRole, type FFIDMemberStatus, type FFIDNewsletterBodySource, type FFIDNewsletterCampaignStatus, type FFIDNewsletterClient, type FFIDNewsletterConfirmParams, type FFIDNewsletterConfirmResponse, type FFIDNewsletterDispatchParams, type FFIDNewsletterDispatchResponse, type FFIDNewsletterSegment, type FFIDNewsletterSubscribeParams, type FFIDNewsletterSubscribeResponse, type FFIDNewsletterType, type FFIDNewsletterUnsubscribeParams, type FFIDNewsletterUnsubscribeResponse, FFIDOAuthUserInfo, FFIDOAuthUserInfoSubscription, FFIDOrganization, type FFIDOrganizationDomain, type FFIDOrganizationDomainsResponse, type FFIDOrganizationMember, type FFIDOrganizationNotificationPreferences, type FFIDOrganizationNotificationPreferencesResponse, type FFIDOtpSendResponse, type FFIDOtpVerifyResponse, type FFIDPasswordResetConfirmResponse, type FFIDPasswordResetResponse, type FFIDPasswordResetVerifyResponse, type FFIDPlanChangeLineItem, type FFIDPlanChangePreview, type FFIDPlanChangePreviewResponse, type FFIDPlanInfo, type FFIDPortalSessionResponse, type FFIDPreviewPlanChangeParams, type FFIDPreviewSeatChangeParams, type FFIDProfileCallOptions, FFIDProvider, type FFIDProviderProps, FFIDRedirectResult, type FFIDRemoveMemberResponse, type FFIDResetSessionResponse, FFIDSDKError, type FFIDSeatChangeLineItem, type FFIDSeatChangePreview, type FFIDSeatChangePreviewResponse, FFIDServiceAccessDecision, type FFIDServiceInfo, FFIDSessionResponse, type FFIDSubscribeParams, type FFIDSubscribeResponse, FFIDSubscription, FFIDSubscriptionCheckResponse, FFIDSubscriptionContextValue, type FFIDSubscriptionDetail, FFIDSubscriptionStatus, type FFIDSubscriptionSummary, type FFIDSupportedCurrency, type FFIDUpdateMemberRoleResponse, type FFIDUpdateNotificationPreferencesRequest, type FFIDUpdateUserProfileRequest, FFIDUser, type FFIDUserProfile, FFIDVerifyAccessTokenOptions, FFID_ANNOUNCEMENTS_ERROR_CODES, FFID_NEWSLETTER_DISPATCH_MAX_RECIPIENTS, FFID_NEWSLETTER_TYPES, type HandleRedirectCallbackClient, type HandleRedirectCallbackOptions, type KVNamespaceLike, ListAnnouncementsOptions, type NormalizeRedirectUriResult, type RedirectToAuthorizeOptions, type TokenData, type TokenStore, type UseFFIDReturn, type UseRequireActiveSubscriptionOptions, type UseRequireActiveSubscriptionReturn, type WithFFIDAuthOptions, type WithSubscriptionOptions, cleanupStateStorage as clearState, computeEffectiveStatusFromSession, createFFIDAnnouncementsClient, createFFIDClient, createKVCacheAdapter, createMemoryCacheAdapter, createTokenStore, generateCodeChallenge, generateCodeVerifier, handleRedirectCallback, hasAccessFromUserinfo, isBlockedFromUserinfo, normalizeRedirectUri, retrieveCodeVerifier, retrieveState, storeCodeVerifier, storeState, useFFID, useRequireActiveSubscription, useSubscription, withFFIDAuth, withSubscription };

package/dist/index.js

@@ -1,5 +1,5 @@
-import { useFFIDContext, useSubscription } from './chunk-KB2JG64Z.js';
-export { ACCESS_GRANTING_EFFECTIVE_STATUSES, BLOCKING_EFFECTIVE_STATUSES, DEFAULT_API_BASE_URL, DEFAULT_OAUTH_SCOPES, EFFECTIVE_SUBSCRIPTION_STATUSES, FFIDAnnouncementBadge, FFIDAnnouncementList, FFIDInquiryForm, FFIDLoginButton, FFIDOrganizationSwitcher, FFIDProvider, FFIDSDKError, FFIDSubscriptionBadge, FFIDUserMenu, FFID_ANNOUNCEMENTS_ERROR_CODES, FFID_INQUIRY_CATEGORIES, FFID_INQUIRY_CATEGORIES_SITE_2026, computeEffectiveStatusFromSession, createFFIDAnnouncementsClient, createFFIDClient, createTokenStore, generateCodeChallenge, generateCodeVerifier, hasAccessFromUserinfo, isBlockedFromUserinfo, isFFIDInquiryCategorySite2026, normalizeRedirectUri, retrieveCodeVerifier, storeCodeVerifier, useFFID, useFFIDAnnouncements, useSubscription, withSubscription } from './chunk-KB2JG64Z.js';
+import { useFFIDContext, useSubscription } from './chunk-4II4R7NR.js';
+export { ACCESS_GRANTING_EFFECTIVE_STATUSES, BLOCKING_EFFECTIVE_STATUSES, DEFAULT_API_BASE_URL, DEFAULT_OAUTH_SCOPES, EFFECTIVE_SUBSCRIPTION_STATUSES, FFIDAnnouncementBadge, FFIDAnnouncementList, FFIDInquiryForm, FFIDLoginButton, FFIDOrganizationSwitcher, FFIDProvider, FFIDSDKError, FFIDSubscriptionBadge, FFIDUserMenu, FFID_ANNOUNCEMENTS_ERROR_CODES, FFID_INQUIRY_CATEGORIES, FFID_INQUIRY_CATEGORIES_SITE_2026, cleanupStateStorage as clearState, computeEffectiveStatusFromSession, createFFIDAnnouncementsClient, createFFIDClient, createTokenStore, generateCodeChallenge, generateCodeVerifier, handleRedirectCallback, hasAccessFromUserinfo, isBlockedFromUserinfo, isFFIDInquiryCategorySite2026, normalizeRedirectUri, retrieveCodeVerifier, retrieveState, storeCodeVerifier, storeState, useFFID, useFFIDAnnouncements, useSubscription, withSubscription } from './chunk-4II4R7NR.js';
 export { ALL_DENIED_EXCEPT_NECESSARY, CONSENT_COOKIE_NAME, CONSENT_DISMISSAL_TIMESTAMP_KEY, COOKIE_VERSION, DEFAULT_CONSENT_ERROR_MESSAGES, FFIDAnalyticsProvider, FFIDConsentError, FFIDCookieBanner, FFIDCookieLink, FFIDCookieSettings, FFID_CONSENT_ERROR_CODES, clearConsentDismissalTimestamp, decodeConsentCookie, encodeConsentCookie, readConsentCookie, readConsentDismissalTimestamp, useFFIDConsent, useFFIDConsentPreferences, writeConsentCookie, writeConsentDismissalTimestamp } from './chunk-M4N2PUX6.js';
 import { useEffect, useRef } from 'react';
 import { jsx, Fragment } from 'react/jsx-runtime';

package/dist/legal/index.cjs

@@ -156,6 +156,18 @@ function createFFIDLegalClient(config) {
     const params = new URLSearchParams({ externalUserId });
     return fetchWithApiKey(`/agreements/pending?${params.toString()}`);
   }
+  async function getAgreementHistory(externalUserId) {
+    if (!externalUserId) {
+      return {
+        error: {
+          code: FFID_LEGAL_ERROR_CODES.VALIDATION_ERROR,
+          message: "externalUserId is required"
+        }
+      };
+    }
+    const params = new URLSearchParams({ externalUserId });
+    return fetchWithApiKey(`/agreements/history?${params.toString()}`);
+  }
   return {
     /** Get all legal documents available to this service */
     getDocuments,
@@ -167,6 +179,8 @@ function createFFIDLegalClient(config) {
     checkAgreement,
     /** Get all documents that a user has not yet agreed to */
     getPendingAgreements,
+    /** Get the full agreement history for a user */
+    getAgreementHistory,
     /** Resolved logger instance */
     logger,
     /** API base URL */

package/dist/legal/index.d.cts

@@ -175,6 +175,19 @@ interface FFIDPendingAgreementsResponse {
     /** Whether there are any pending documents */
     hasPending: boolean;
 }
+/**
+ * Response from get agreement history
+ *
+ * Returns every recorded agreement for a (service, external user) pair,
+ * ordered from most recently agreed to oldest. This is the service-scoped
+ * analog of the cookie route GET /api/v1/legal/agreements/me.
+ */
+interface FFIDAgreementHistoryResponse {
+    /** List of recorded agreements (most recent first) */
+    agreements: FFIDServiceUserAgreement[];
+    /** Number of recorded agreements */
+    count: number;
+}
 /**
  * Known SDK error codes (generated client-side)
  */
@@ -314,6 +327,8 @@ declare function createFFIDLegalClient(config: FFIDLegalClientConfig): {
     checkAgreement: (externalUserId: string, documentId: string) => Promise<FFIDLegalApiResponse<FFIDAgreementCheckResult>>;
     /** Get all documents that a user has not yet agreed to */
     getPendingAgreements: (externalUserId: string) => Promise<FFIDLegalApiResponse<FFIDPendingAgreementsResponse>>;
+    /** Get the full agreement history for a user */
+    getAgreementHistory: (externalUserId: string) => Promise<FFIDLegalApiResponse<FFIDAgreementHistoryResponse>>;
     /** Resolved logger instance */
     logger: FFIDLegalLogger;
     /** API base URL */
@@ -322,4 +337,4 @@ declare function createFFIDLegalClient(config: FFIDLegalClientConfig): {
 /** Type of the FFID Legal client */
 type FFIDLegalClient = ReturnType<typeof createFFIDLegalClient>;
 
-export { type FFIDAgreementCheckResult, type FFIDAgreementMethod, type FFIDLegalApiResponse, type FFIDLegalClient, type FFIDLegalClientConfig, type FFIDLegalDocument, type FFIDLegalDocumentType, type FFIDLegalError, type FFIDLegalErrorCode, type FFIDLegalLogger, type FFIDLegalSdkErrorCode, type FFIDLegalServerError, type FFIDLegalServerErrorCode, type FFIDLegalServerResponse, type FFIDPendingAgreement, type FFIDPendingAgreementsResponse, type FFIDRecordAgreementRequest, type FFIDRecordAgreementResponse, type FFIDServiceUserAgreement, FFID_LEGAL_ERROR_CODES, createFFIDLegalClient };
+export { type FFIDAgreementCheckResult, type FFIDAgreementHistoryResponse, type FFIDAgreementMethod, type FFIDLegalApiResponse, type FFIDLegalClient, type FFIDLegalClientConfig, type FFIDLegalDocument, type FFIDLegalDocumentType, type FFIDLegalError, type FFIDLegalErrorCode, type FFIDLegalLogger, type FFIDLegalSdkErrorCode, type FFIDLegalServerError, type FFIDLegalServerErrorCode, type FFIDLegalServerResponse, type FFIDPendingAgreement, type FFIDPendingAgreementsResponse, type FFIDRecordAgreementRequest, type FFIDRecordAgreementResponse, type FFIDServiceUserAgreement, FFID_LEGAL_ERROR_CODES, createFFIDLegalClient };

package/dist/legal/index.d.ts

@@ -175,6 +175,19 @@ interface FFIDPendingAgreementsResponse {
     /** Whether there are any pending documents */
     hasPending: boolean;
 }
+/**
+ * Response from get agreement history
+ *
+ * Returns every recorded agreement for a (service, external user) pair,
+ * ordered from most recently agreed to oldest. This is the service-scoped
+ * analog of the cookie route GET /api/v1/legal/agreements/me.
+ */
+interface FFIDAgreementHistoryResponse {
+    /** List of recorded agreements (most recent first) */
+    agreements: FFIDServiceUserAgreement[];
+    /** Number of recorded agreements */
+    count: number;
+}
 /**
  * Known SDK error codes (generated client-side)
  */
@@ -314,6 +327,8 @@ declare function createFFIDLegalClient(config: FFIDLegalClientConfig): {
     checkAgreement: (externalUserId: string, documentId: string) => Promise<FFIDLegalApiResponse<FFIDAgreementCheckResult>>;
     /** Get all documents that a user has not yet agreed to */
     getPendingAgreements: (externalUserId: string) => Promise<FFIDLegalApiResponse<FFIDPendingAgreementsResponse>>;
+    /** Get the full agreement history for a user */
+    getAgreementHistory: (externalUserId: string) => Promise<FFIDLegalApiResponse<FFIDAgreementHistoryResponse>>;
     /** Resolved logger instance */
     logger: FFIDLegalLogger;
     /** API base URL */
@@ -322,4 +337,4 @@ declare function createFFIDLegalClient(config: FFIDLegalClientConfig): {
 /** Type of the FFID Legal client */
 type FFIDLegalClient = ReturnType<typeof createFFIDLegalClient>;
 
-export { type FFIDAgreementCheckResult, type FFIDAgreementMethod, type FFIDLegalApiResponse, type FFIDLegalClient, type FFIDLegalClientConfig, type FFIDLegalDocument, type FFIDLegalDocumentType, type FFIDLegalError, type FFIDLegalErrorCode, type FFIDLegalLogger, type FFIDLegalSdkErrorCode, type FFIDLegalServerError, type FFIDLegalServerErrorCode, type FFIDLegalServerResponse, type FFIDPendingAgreement, type FFIDPendingAgreementsResponse, type FFIDRecordAgreementRequest, type FFIDRecordAgreementResponse, type FFIDServiceUserAgreement, FFID_LEGAL_ERROR_CODES, createFFIDLegalClient };
+export { type FFIDAgreementCheckResult, type FFIDAgreementHistoryResponse, type FFIDAgreementMethod, type FFIDLegalApiResponse, type FFIDLegalClient, type FFIDLegalClientConfig, type FFIDLegalDocument, type FFIDLegalDocumentType, type FFIDLegalError, type FFIDLegalErrorCode, type FFIDLegalLogger, type FFIDLegalSdkErrorCode, type FFIDLegalServerError, type FFIDLegalServerErrorCode, type FFIDLegalServerResponse, type FFIDPendingAgreement, type FFIDPendingAgreementsResponse, type FFIDRecordAgreementRequest, type FFIDRecordAgreementResponse, type FFIDServiceUserAgreement, FFID_LEGAL_ERROR_CODES, createFFIDLegalClient };

package/dist/legal/index.js

@@ -155,6 +155,18 @@ function createFFIDLegalClient(config) {
     const params = new URLSearchParams({ externalUserId });
     return fetchWithApiKey(`/agreements/pending?${params.toString()}`);
   }
+  async function getAgreementHistory(externalUserId) {
+    if (!externalUserId) {
+      return {
+        error: {
+          code: FFID_LEGAL_ERROR_CODES.VALIDATION_ERROR,
+          message: "externalUserId is required"
+        }
+      };
+    }
+    const params = new URLSearchParams({ externalUserId });
+    return fetchWithApiKey(`/agreements/history?${params.toString()}`);
+  }
   return {
     /** Get all legal documents available to this service */
     getDocuments,
@@ -166,6 +178,8 @@ function createFFIDLegalClient(config) {
     checkAgreement,
     /** Get all documents that a user has not yet agreed to */
     getPendingAgreements,
+    /** Get the full agreement history for a user */
+    getAgreementHistory,
     /** Resolved logger instance */
     logger,
     /** API base URL */