@feelflow/ffid-sdk 1.10.0 → 1.13.0

package/dist/server/index.d.cts

@@ -27,6 +27,8 @@ interface FFIDCacheConfig {
  * Core types for the FeelFlow ID SDK
  */
 
+/** Authentication mode for FFID client */
+type FFIDAuthMode = 'cookie' | 'token' | 'service-key';
 /**
  * User information from FFID
  */
@@ -129,6 +131,17 @@ interface FFIDOAuthUserInfo {
     organizationId?: string | null | undefined;
     subscription?: FFIDOAuthUserInfoSubscription | undefined;
 }
+/** Options for verifyAccessToken */
+interface FFIDVerifyAccessTokenOptions {
+    /**
+     * When true, fetches profile info (email, name, picture) via introspect API
+     * after local JWT verification. No effect when verifyStrategy is 'introspect'
+     * (profile is always included).
+     * Requires {@link FFIDConfig.serviceApiKey} to be configured when using jwt strategy.
+     * @default false
+     */
+    includeProfile?: boolean;
+}
 /**
  * SDK configuration options
  */
@@ -156,7 +169,7 @@ interface FFIDConfig {
     /** Callback on authentication error */
     onError?: ((error: FFIDError) => void) | undefined;
     /** Authentication mode: 'cookie' (default), 'token' (OAuth Bearer), or 'service-key' (server-to-server) */
-    authMode?: 'cookie' | 'token' | 'service-key' | undefined;
+    authMode?: FFIDAuthMode | undefined;
     /** Client ID for token mode (defaults to serviceCode if not set) */
     clientId?: string | undefined;
     /** Custom redirect URI for OAuth flow (defaults to window.location.origin + window.location.pathname) */
@@ -168,14 +181,16 @@ interface FFIDConfig {
      * - 'jwt': Local JWT verification via JWKS (default, lower latency)
      * - 'introspect': Remote introspection via /api/v1/oauth/introspect
      *
-     * JWT verification returns limited claims (no email/name/picture/subscription).
-     * Use 'introspect' if you need full user profile data.
+     * JWT verification returns limited claims (no email/name/picture/subscription) by default.
+     * Use 'introspect' if you always need full user profile data, or pass
+     * { includeProfile: true } to verifyAccessToken() for on-demand profile fetching.
      */
     verifyStrategy?: 'jwt' | 'introspect' | undefined;
     /**
      * Cache configuration for token verification results.
      * When set, introspect/userinfo responses are cached to reduce API calls.
-     * Only effective in service-key mode with verifyStrategy: 'introspect'.
+     * Effective in service-key mode with verifyStrategy: 'introspect',
+     * or with verifyStrategy: 'jwt' when includeProfile: true is used.
      */
     cache?: FFIDCacheConfig | undefined;
     /**
@@ -286,6 +301,55 @@ interface FFIDCreatePortalParams {
     /** URL to redirect when user exits the portal */
     returnUrl: string;
 }
+/**
+ * Result of a redirect operation (redirectToLogin / redirectToAuthorize)
+ *
+ * Structured return type so callers can inspect failure reasons
+ * instead of receiving a bare `false`.
+ */
+type FFIDRedirectResult = {
+    success: true;
+} | {
+    success: false;
+    error: string;
+};
+
+/** OTP / magic link methods - sendOtp / verifyOtp */
+
+/** Response from sendOtp */
+interface FFIDOtpSendResponse {
+    message: string;
+}
+/** Response from verifyOtp */
+interface FFIDOtpVerifyResponse {
+    user: {
+        id: string;
+        email: string;
+        displayName: string | null;
+        avatarUrl: string | null;
+    };
+    session: {
+        accessToken: string;
+        refreshToken: string;
+        expiresAt: number;
+        expiresIn: number;
+    };
+}
+
+/** Password reset methods - requestPasswordReset / verifyPasswordResetToken / establishResetSession / confirmPasswordReset */
+
+/** Response from requestPasswordReset */
+interface FFIDPasswordResetResponse {
+    message: string;
+}
+/** Response from verifyPasswordResetToken */
+interface FFIDPasswordResetVerifyResponse {
+    valid: boolean;
+}
+/** Response from establishResetSession */
+type FFIDResetSessionResponse = FFIDPasswordResetResponse;
+/** Response from confirmPasswordReset */
+type FFIDPasswordResetConfirmResponse = FFIDPasswordResetResponse;
 
 /**
  * Token Store
@@ -332,7 +396,7 @@ declare function createTokenStore(storageType?: 'localStorage' | 'memory'): Toke
 declare function createFFIDClient(config: FFIDConfig): {
     getSession: () => Promise<FFIDApiResponse<FFIDSessionResponse>>;
     signOut: () => Promise<FFIDApiResponse<void>>;
-    redirectToLogin: () => boolean;
+    redirectToLogin: () => Promise<FFIDRedirectResult>;
     getLoginUrl: (redirectUrl?: string) => string;
     getSignupUrl: (redirectUrl?: string) => string;
     createError: (code: string, message: string) => FFIDError;
@@ -344,11 +408,22 @@ declare function createFFIDClient(config: FFIDConfig): {
     }) => Promise<FFIDApiResponse<FFIDSubscriptionCheckResponse>>;
     createCheckoutSession: (params: FFIDCreateCheckoutParams) => Promise<FFIDApiResponse<FFIDCheckoutSessionResponse>>;
     createPortalSession: (params: FFIDCreatePortalParams) => Promise<FFIDApiResponse<FFIDPortalSessionResponse>>;
-    verifyAccessToken: (accessToken: string) => Promise<FFIDApiResponse<FFIDOAuthUserInfo>>;
+    verifyAccessToken: (accessToken: string, options?: FFIDVerifyAccessTokenOptions) => Promise<FFIDApiResponse<FFIDOAuthUserInfo>>;
+    requestPasswordReset: (email: string) => Promise<FFIDApiResponse<FFIDPasswordResetResponse>>;
+    verifyPasswordResetToken: (accessToken: string) => Promise<FFIDApiResponse<FFIDPasswordResetVerifyResponse>>;
+    establishResetSession: (accessToken: string, refreshToken: string) => Promise<FFIDApiResponse<FFIDResetSessionResponse>>;
+    confirmPasswordReset: (password: string) => Promise<FFIDApiResponse<FFIDPasswordResetConfirmResponse>>;
+    sendOtp: (email: string, options?: {
+        redirectUrl?: string;
+    }) => Promise<FFIDApiResponse<FFIDOtpSendResponse>>;
+    verifyOtp: (params: {
+        accessToken: string;
+        refreshToken: string;
+    }) => Promise<FFIDApiResponse<FFIDOtpVerifyResponse>>;
     /** Token store (token mode only) */
     tokenStore: TokenStore;
     /** Resolved auth mode */
-    authMode: "cookie" | "token" | "service-key";
+    authMode: FFIDAuthMode;
     /** Resolved logger instance */
     logger: FFIDLogger;
     baseUrl: string;
@@ -388,7 +463,7 @@ interface VerifyAccessTokenDeps {
  * - 'jwt': Local JWT verification via JWKS (default, lower latency)
  * - 'introspect': Remote token introspection (full user profile data)
  */
-declare function createVerifyAccessToken(deps: VerifyAccessTokenDeps): (accessToken: string) => Promise<FFIDApiResponse<FFIDOAuthUserInfo>>;
+declare function createVerifyAccessToken(deps: VerifyAccessTokenDeps): (accessToken: string, options?: FFIDVerifyAccessTokenOptions) => Promise<FFIDApiResponse<FFIDOAuthUserInfo>>;
 
 /**
  * Create an in-memory cache adapter using a Map.
@@ -413,4 +488,4 @@ interface KVNamespaceLike {
  */
 declare function createKVCacheAdapter(kv: KVNamespaceLike): FFIDCacheAdapter;
 
-export { type FFIDCacheAdapter, type FFIDCacheConfig, type FFIDClient, type FFIDConfig, type FFIDOAuthUserInfo, type FFIDOrganization, type FFIDSubscription, type FFIDUser, type KVNamespaceLike, type TokenData, type TokenStore, createFFIDClient, createKVCacheAdapter, createMemoryCacheAdapter, createTokenStore, createVerifyAccessToken };
+export { type FFIDCacheAdapter, type FFIDCacheConfig, type FFIDClient, type FFIDConfig, type FFIDOAuthUserInfo, type FFIDOrganization, type FFIDOtpSendResponse, type FFIDOtpVerifyResponse, type FFIDPasswordResetConfirmResponse, type FFIDPasswordResetResponse, type FFIDPasswordResetVerifyResponse, type FFIDResetSessionResponse, type FFIDSubscription, type FFIDUser, type FFIDVerifyAccessTokenOptions, type KVNamespaceLike, type TokenData, type TokenStore, createFFIDClient, createKVCacheAdapter, createMemoryCacheAdapter, createTokenStore, createVerifyAccessToken };

package/dist/server/index.d.ts

@@ -27,6 +27,8 @@ interface FFIDCacheConfig {
  * Core types for the FeelFlow ID SDK
  */
 
+/** Authentication mode for FFID client */
+type FFIDAuthMode = 'cookie' | 'token' | 'service-key';
 /**
  * User information from FFID
  */
@@ -129,6 +131,17 @@ interface FFIDOAuthUserInfo {
     organizationId?: string | null | undefined;
     subscription?: FFIDOAuthUserInfoSubscription | undefined;
 }
+/** Options for verifyAccessToken */
+interface FFIDVerifyAccessTokenOptions {
+    /**
+     * When true, fetches profile info (email, name, picture) via introspect API
+     * after local JWT verification. No effect when verifyStrategy is 'introspect'
+     * (profile is always included).
+     * Requires {@link FFIDConfig.serviceApiKey} to be configured when using jwt strategy.
+     * @default false
+     */
+    includeProfile?: boolean;
+}
 /**
  * SDK configuration options
  */
@@ -156,7 +169,7 @@ interface FFIDConfig {
     /** Callback on authentication error */
     onError?: ((error: FFIDError) => void) | undefined;
     /** Authentication mode: 'cookie' (default), 'token' (OAuth Bearer), or 'service-key' (server-to-server) */
-    authMode?: 'cookie' | 'token' | 'service-key' | undefined;
+    authMode?: FFIDAuthMode | undefined;
     /** Client ID for token mode (defaults to serviceCode if not set) */
     clientId?: string | undefined;
     /** Custom redirect URI for OAuth flow (defaults to window.location.origin + window.location.pathname) */
@@ -168,14 +181,16 @@ interface FFIDConfig {
      * - 'jwt': Local JWT verification via JWKS (default, lower latency)
      * - 'introspect': Remote introspection via /api/v1/oauth/introspect
      *
-     * JWT verification returns limited claims (no email/name/picture/subscription).
-     * Use 'introspect' if you need full user profile data.
+     * JWT verification returns limited claims (no email/name/picture/subscription) by default.
+     * Use 'introspect' if you always need full user profile data, or pass
+     * { includeProfile: true } to verifyAccessToken() for on-demand profile fetching.
      */
     verifyStrategy?: 'jwt' | 'introspect' | undefined;
     /**
      * Cache configuration for token verification results.
      * When set, introspect/userinfo responses are cached to reduce API calls.
-     * Only effective in service-key mode with verifyStrategy: 'introspect'.
+     * Effective in service-key mode with verifyStrategy: 'introspect',
+     * or with verifyStrategy: 'jwt' when includeProfile: true is used.
      */
     cache?: FFIDCacheConfig | undefined;
     /**
@@ -286,6 +301,55 @@ interface FFIDCreatePortalParams {
     /** URL to redirect when user exits the portal */
     returnUrl: string;
 }
+/**
+ * Result of a redirect operation (redirectToLogin / redirectToAuthorize)
+ *
+ * Structured return type so callers can inspect failure reasons
+ * instead of receiving a bare `false`.
+ */
+type FFIDRedirectResult = {
+    success: true;
+} | {
+    success: false;
+    error: string;
+};
+
+/** OTP / magic link methods - sendOtp / verifyOtp */
+
+/** Response from sendOtp */
+interface FFIDOtpSendResponse {
+    message: string;
+}
+/** Response from verifyOtp */
+interface FFIDOtpVerifyResponse {
+    user: {
+        id: string;
+        email: string;
+        displayName: string | null;
+        avatarUrl: string | null;
+    };
+    session: {
+        accessToken: string;
+        refreshToken: string;
+        expiresAt: number;
+        expiresIn: number;
+    };
+}
+
+/** Password reset methods - requestPasswordReset / verifyPasswordResetToken / establishResetSession / confirmPasswordReset */
+
+/** Response from requestPasswordReset */
+interface FFIDPasswordResetResponse {
+    message: string;
+}
+/** Response from verifyPasswordResetToken */
+interface FFIDPasswordResetVerifyResponse {
+    valid: boolean;
+}
+/** Response from establishResetSession */
+type FFIDResetSessionResponse = FFIDPasswordResetResponse;
+/** Response from confirmPasswordReset */
+type FFIDPasswordResetConfirmResponse = FFIDPasswordResetResponse;
 
 /**
  * Token Store
@@ -332,7 +396,7 @@ declare function createTokenStore(storageType?: 'localStorage' | 'memory'): Toke
 declare function createFFIDClient(config: FFIDConfig): {
     getSession: () => Promise<FFIDApiResponse<FFIDSessionResponse>>;
     signOut: () => Promise<FFIDApiResponse<void>>;
-    redirectToLogin: () => boolean;
+    redirectToLogin: () => Promise<FFIDRedirectResult>;
     getLoginUrl: (redirectUrl?: string) => string;
     getSignupUrl: (redirectUrl?: string) => string;
     createError: (code: string, message: string) => FFIDError;
@@ -344,11 +408,22 @@ declare function createFFIDClient(config: FFIDConfig): {
     }) => Promise<FFIDApiResponse<FFIDSubscriptionCheckResponse>>;
     createCheckoutSession: (params: FFIDCreateCheckoutParams) => Promise<FFIDApiResponse<FFIDCheckoutSessionResponse>>;
     createPortalSession: (params: FFIDCreatePortalParams) => Promise<FFIDApiResponse<FFIDPortalSessionResponse>>;
-    verifyAccessToken: (accessToken: string) => Promise<FFIDApiResponse<FFIDOAuthUserInfo>>;
+    verifyAccessToken: (accessToken: string, options?: FFIDVerifyAccessTokenOptions) => Promise<FFIDApiResponse<FFIDOAuthUserInfo>>;
+    requestPasswordReset: (email: string) => Promise<FFIDApiResponse<FFIDPasswordResetResponse>>;
+    verifyPasswordResetToken: (accessToken: string) => Promise<FFIDApiResponse<FFIDPasswordResetVerifyResponse>>;
+    establishResetSession: (accessToken: string, refreshToken: string) => Promise<FFIDApiResponse<FFIDResetSessionResponse>>;
+    confirmPasswordReset: (password: string) => Promise<FFIDApiResponse<FFIDPasswordResetConfirmResponse>>;
+    sendOtp: (email: string, options?: {
+        redirectUrl?: string;
+    }) => Promise<FFIDApiResponse<FFIDOtpSendResponse>>;
+    verifyOtp: (params: {
+        accessToken: string;
+        refreshToken: string;
+    }) => Promise<FFIDApiResponse<FFIDOtpVerifyResponse>>;
     /** Token store (token mode only) */
     tokenStore: TokenStore;
     /** Resolved auth mode */
-    authMode: "cookie" | "token" | "service-key";
+    authMode: FFIDAuthMode;
     /** Resolved logger instance */
     logger: FFIDLogger;
     baseUrl: string;
@@ -388,7 +463,7 @@ interface VerifyAccessTokenDeps {
  * - 'jwt': Local JWT verification via JWKS (default, lower latency)
  * - 'introspect': Remote token introspection (full user profile data)
  */
-declare function createVerifyAccessToken(deps: VerifyAccessTokenDeps): (accessToken: string) => Promise<FFIDApiResponse<FFIDOAuthUserInfo>>;
+declare function createVerifyAccessToken(deps: VerifyAccessTokenDeps): (accessToken: string, options?: FFIDVerifyAccessTokenOptions) => Promise<FFIDApiResponse<FFIDOAuthUserInfo>>;
 
 /**
  * Create an in-memory cache adapter using a Map.
@@ -413,4 +488,4 @@ interface KVNamespaceLike {
  */
 declare function createKVCacheAdapter(kv: KVNamespaceLike): FFIDCacheAdapter;
 
-export { type FFIDCacheAdapter, type FFIDCacheConfig, type FFIDClient, type FFIDConfig, type FFIDOAuthUserInfo, type FFIDOrganization, type FFIDSubscription, type FFIDUser, type KVNamespaceLike, type TokenData, type TokenStore, createFFIDClient, createKVCacheAdapter, createMemoryCacheAdapter, createTokenStore, createVerifyAccessToken };
+export { type FFIDCacheAdapter, type FFIDCacheConfig, type FFIDClient, type FFIDConfig, type FFIDOAuthUserInfo, type FFIDOrganization, type FFIDOtpSendResponse, type FFIDOtpVerifyResponse, type FFIDPasswordResetConfirmResponse, type FFIDPasswordResetResponse, type FFIDPasswordResetVerifyResponse, type FFIDResetSessionResponse, type FFIDSubscription, type FFIDUser, type FFIDVerifyAccessTokenOptions, type KVNamespaceLike, type TokenData, type TokenStore, createFFIDClient, createKVCacheAdapter, createMemoryCacheAdapter, createTokenStore, createVerifyAccessToken };