@feelflow/ffid-sdk 5.13.0 → 5.14.0

package/dist/{ffid-client-BG0Qr86U.d.ts → ffid-client-9-lh0G_h.d.ts}

@@ -799,6 +799,300 @@ 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';
+/**
+ * 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;
+}
+
 /**
  * FFID SDK Type Definitions
  *
@@ -1135,75 +1429,6 @@ type FFIDApiResponse<T> = {
     error: FFIDError;
 };
 
-/**
- * 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;
-}
 /**
  * Response shape from `GET /api/v1/ext/analytics/config?service=<code>`.
  *
@@ -1227,48 +1452,6 @@ interface FFIDAnalyticsConfig {
      */
     isActive: boolean;
 }
-/**
- * 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;
-}
 /**
  * Discriminant for redirect failures that callers need to handle
  * programmatically (vs. logging the human-readable `error` string).
@@ -1364,6 +1547,26 @@ 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;
+}
+
 /**
  * Token Store
  *
@@ -1489,6 +1692,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>>;