@payez/next-mvp 4.8.0 → 4.8.2

package/src/types/api.ts

@@ -1,13 +1,13 @@
-export interface ApiResponse<T = any> { success: boolean; data?: T; error?: ApiError; meta?: ApiMeta; timestamp: string; requestId: string; }
-export interface ApiError { code: string; message: string; details?: Record<string, any>; field?: string; resolution?: string; supportContact?: string; remainingAttempts?: number; }
-export interface ApiMeta { version: string; responseTime: number; operation?: string; rateLimit?: { limit: number; remaining: number; resetAt: string; }; pagination?: { page: number; pageSize: number; total: number; totalPages: number; }; cached?: boolean; filters?: Record<string, any>; aggregation?: Record<string, any>; resourceId?: string | number; }
-export interface ApiRequestContext { requestId: string; startTime: number; userAgent?: string; ipAddress?: string; userId?: string; sessionId?: string; endpoint: string; method: string; params?: Record<string, string>; headers?: Record<string, string>; }
-export interface ApiValidationError { field: string; message: string; code: string; value?: any; }
-export interface ApiAuthContext { accessToken: string | null; tokenType: string; refreshToken: string | null; userId?: string; roles?: string[]; sessionId?: string; expiresAt?: number; }
-export interface ApiHandlerConfig { requireAuth?: boolean; requiredRoles?: readonly string[]; rateLimit?: { windowMs: number; maxRequests: number; }; validation?: { body?: any; query?: any; params?: any; }; timeout?: number; retries?: number; cacheTtl?: number; tokenRefreshBuffer?: number; }
-export interface ApiMiddleware { name: string; execute: (context: ApiRequestContext, config: ApiHandlerConfig) => Promise<void>; }
-export enum ApiErrorCode { UNAUTHORIZED='UNAUTHORIZED', FORBIDDEN='FORBIDDEN', TOKEN_EXPIRED='TOKEN_EXPIRED', INVALID_TOKEN='INVALID_TOKEN', INVALID_SESSION='INVALID_SESSION', INVALID_2FA_TOKEN='INVALID_2FA_TOKEN', INSUFFICIENT_PERMISSIONS='INSUFFICIENT_PERMISSIONS', RATE_LIMIT_EXCEEDED='RATE_LIMIT_EXCEEDED', TOO_MANY_REQUESTS='TOO_MANY_REQUESTS', VALIDATION_ERROR='VALIDATION_ERROR', INVALID_REQUEST='INVALID_REQUEST', MISSING_REQUIRED_FIELD='MISSING_REQUIRED_FIELD', INVALID_FORMAT='INVALID_FORMAT', RESOURCE_NOT_FOUND='RESOURCE_NOT_FOUND', NOT_FOUND='NOT_FOUND', RESOURCE_CONFLICT='RESOURCE_CONFLICT', CONFLICT='CONFLICT', BUSINESS_RULE_VIOLATION='BUSINESS_RULE_VIOLATION', NOT_IMPLEMENTED='NOT_IMPLEMENTED', INTERNAL_ERROR='INTERNAL_ERROR', INTERNAL_SERVER_ERROR='INTERNAL_SERVER_ERROR', SERVICE_UNAVAILABLE='SERVICE_UNAVAILABLE', TIMEOUT='TIMEOUT', CIRCUIT_BREAKER_OPEN='CIRCUIT_BREAKER_OPEN', UPSTREAM_SERVICE_ERROR='UPSTREAM_SERVICE_ERROR', NETWORK_ERROR='NETWORK_ERROR', CONNECTION_ERROR='CONNECTION_ERROR', UNKNOWN_ERROR='UNKNOWN_ERROR' }
-export const ApiErrorMessages: Record<ApiErrorCode, string> = { [ApiErrorCode.UNAUTHORIZED]:'Authentication required',[ApiErrorCode.FORBIDDEN]:'Access denied',[ApiErrorCode.TOKEN_EXPIRED]:'Authentication token has expired',[ApiErrorCode.INVALID_TOKEN]:'Invalid authentication token',[ApiErrorCode.INVALID_SESSION]:'Invalid session - please log in again',[ApiErrorCode.INVALID_2FA_TOKEN]:'Invalid or expired 2FA verification token',[ApiErrorCode.INSUFFICIENT_PERMISSIONS]:'Insufficient permissions for this resource',[ApiErrorCode.RATE_LIMIT_EXCEEDED]:'Rate limit exceeded',[ApiErrorCode.TOO_MANY_REQUESTS]:'Too many requests',[ApiErrorCode.VALIDATION_ERROR]:'Request validation failed',[ApiErrorCode.INVALID_REQUEST]:'Invalid request format',[ApiErrorCode.MISSING_REQUIRED_FIELD]:'Required field is missing',[ApiErrorCode.INVALID_FORMAT]:'Invalid data format',[ApiErrorCode.RESOURCE_NOT_FOUND]:'Resource not found',[ApiErrorCode.NOT_FOUND]:'Not found',[ApiErrorCode.RESOURCE_CONFLICT]:'Resource conflict',[ApiErrorCode.CONFLICT]:'Conflict',[ApiErrorCode.BUSINESS_RULE_VIOLATION]:'Business rule violation',[ApiErrorCode.NOT_IMPLEMENTED]:'Feature not yet implemented',[ApiErrorCode.INTERNAL_ERROR]:'Internal error occurred',[ApiErrorCode.INTERNAL_SERVER_ERROR]:'Internal server error',[ApiErrorCode.SERVICE_UNAVAILABLE]:'Service temporarily unavailable',[ApiErrorCode.TIMEOUT]:'Request timeout',[ApiErrorCode.CIRCUIT_BREAKER_OPEN]:'Service circuit breaker is open',[ApiErrorCode.UPSTREAM_SERVICE_ERROR]:'Upstream service error',[ApiErrorCode.NETWORK_ERROR]:'Network error',[ApiErrorCode.CONNECTION_ERROR]:'Connection error',[ApiErrorCode.UNKNOWN_ERROR]:'An unknown error occurred' };
-export type ApiSuccessResponse<T> = ApiResponse<T> & { success: true; data: T; message: string; operation_code: string; };
-export type ApiErrorResponse = ApiResponse<never> & { success: false; error: ApiError };
+export interface ApiResponse<T = any> { success: boolean; data?: T; error?: ApiError; meta?: ApiMeta; timestamp: string; requestId: string; }
+export interface ApiError { code: string; message: string; details?: Record<string, any>; field?: string; resolution?: string; supportContact?: string; remainingAttempts?: number; }
+export interface ApiMeta { version: string; responseTime: number; operation?: string; rateLimit?: { limit: number; remaining: number; resetAt: string; }; pagination?: { page: number; pageSize: number; total: number; totalPages: number; }; cached?: boolean; filters?: Record<string, any>; aggregation?: Record<string, any>; resourceId?: string | number; }
+export interface ApiRequestContext { requestId: string; startTime: number; userAgent?: string; ipAddress?: string; userId?: string; sessionId?: string; endpoint: string; method: string; params?: Record<string, string>; headers?: Record<string, string>; }
+export interface ApiValidationError { field: string; message: string; code: string; value?: any; }
+export interface ApiAuthContext { accessToken: string | null; tokenType: string; refreshToken: string | null; userId?: string; roles?: string[]; sessionId?: string; expiresAt?: number; }
+export interface ApiHandlerConfig { requireAuth?: boolean; requiredRoles?: readonly string[]; rateLimit?: { windowMs: number; maxRequests: number; }; validation?: { body?: any; query?: any; params?: any; }; timeout?: number; retries?: number; cacheTtl?: number; tokenRefreshBuffer?: number; }
+export interface ApiMiddleware { name: string; execute: (context: ApiRequestContext, config: ApiHandlerConfig) => Promise<void>; }
+export enum ApiErrorCode { UNAUTHORIZED='UNAUTHORIZED', FORBIDDEN='FORBIDDEN', TOKEN_EXPIRED='TOKEN_EXPIRED', INVALID_TOKEN='INVALID_TOKEN', INVALID_SESSION='INVALID_SESSION', INVALID_2FA_TOKEN='INVALID_2FA_TOKEN', INSUFFICIENT_PERMISSIONS='INSUFFICIENT_PERMISSIONS', RATE_LIMIT_EXCEEDED='RATE_LIMIT_EXCEEDED', TOO_MANY_REQUESTS='TOO_MANY_REQUESTS', VALIDATION_ERROR='VALIDATION_ERROR', INVALID_REQUEST='INVALID_REQUEST', MISSING_REQUIRED_FIELD='MISSING_REQUIRED_FIELD', INVALID_FORMAT='INVALID_FORMAT', RESOURCE_NOT_FOUND='RESOURCE_NOT_FOUND', NOT_FOUND='NOT_FOUND', RESOURCE_CONFLICT='RESOURCE_CONFLICT', CONFLICT='CONFLICT', BUSINESS_RULE_VIOLATION='BUSINESS_RULE_VIOLATION', NOT_IMPLEMENTED='NOT_IMPLEMENTED', INTERNAL_ERROR='INTERNAL_ERROR', INTERNAL_SERVER_ERROR='INTERNAL_SERVER_ERROR', SERVICE_UNAVAILABLE='SERVICE_UNAVAILABLE', TIMEOUT='TIMEOUT', CIRCUIT_BREAKER_OPEN='CIRCUIT_BREAKER_OPEN', UPSTREAM_SERVICE_ERROR='UPSTREAM_SERVICE_ERROR', NETWORK_ERROR='NETWORK_ERROR', CONNECTION_ERROR='CONNECTION_ERROR', UNKNOWN_ERROR='UNKNOWN_ERROR' }
+export const ApiErrorMessages: Record<ApiErrorCode, string> = { [ApiErrorCode.UNAUTHORIZED]:'Authentication required',[ApiErrorCode.FORBIDDEN]:'Access denied',[ApiErrorCode.TOKEN_EXPIRED]:'Authentication token has expired',[ApiErrorCode.INVALID_TOKEN]:'Invalid authentication token',[ApiErrorCode.INVALID_SESSION]:'Invalid session - please log in again',[ApiErrorCode.INVALID_2FA_TOKEN]:'Invalid or expired 2FA verification token',[ApiErrorCode.INSUFFICIENT_PERMISSIONS]:'Insufficient permissions for this resource',[ApiErrorCode.RATE_LIMIT_EXCEEDED]:'Rate limit exceeded',[ApiErrorCode.TOO_MANY_REQUESTS]:'Too many requests',[ApiErrorCode.VALIDATION_ERROR]:'Request validation failed',[ApiErrorCode.INVALID_REQUEST]:'Invalid request format',[ApiErrorCode.MISSING_REQUIRED_FIELD]:'Required field is missing',[ApiErrorCode.INVALID_FORMAT]:'Invalid data format',[ApiErrorCode.RESOURCE_NOT_FOUND]:'Resource not found',[ApiErrorCode.NOT_FOUND]:'Not found',[ApiErrorCode.RESOURCE_CONFLICT]:'Resource conflict',[ApiErrorCode.CONFLICT]:'Conflict',[ApiErrorCode.BUSINESS_RULE_VIOLATION]:'Business rule violation',[ApiErrorCode.NOT_IMPLEMENTED]:'Feature not yet implemented',[ApiErrorCode.INTERNAL_ERROR]:'Internal error occurred',[ApiErrorCode.INTERNAL_SERVER_ERROR]:'Internal server error',[ApiErrorCode.SERVICE_UNAVAILABLE]:'Service temporarily unavailable',[ApiErrorCode.TIMEOUT]:'Request timeout',[ApiErrorCode.CIRCUIT_BREAKER_OPEN]:'Service circuit breaker is open',[ApiErrorCode.UPSTREAM_SERVICE_ERROR]:'Upstream service error',[ApiErrorCode.NETWORK_ERROR]:'Network error',[ApiErrorCode.CONNECTION_ERROR]:'Connection error',[ApiErrorCode.UNKNOWN_ERROR]:'An unknown error occurred' };
+export type ApiSuccessResponse<T> = ApiResponse<T> & { success: true; data: T; message: string; operation_code: string; };
+export type ApiErrorResponse = ApiResponse<never> & { success: false; error: ApiError };
 export class ApiResponseBuilder { private context: ApiRequestContext; private config: ApiHandlerConfig; constructor(context: ApiRequestContext, config: ApiHandlerConfig = {}) { this.context = context; this.config = config; } success<T>(data: T, meta?: Partial<ApiMeta>): ApiSuccessResponse<T> { return { success: true, data, message: meta?.operation ? `${meta.operation.replace(/-/g, ' ')} completed successfully` : 'Operation completed successfully', operation_code: meta?.operation || 'unknown-operation', meta: { version:'1.0', responseTime: Date.now() - this.context.startTime, ...meta }, timestamp: new Date().toISOString(), requestId: this.context.requestId }; } error(code: ApiErrorCode, message?: string, details?: Record<string, any>, field?: string): ApiErrorResponse { const errorMessage = message || ApiErrorMessages[code]; const enhancedDetails = { ...details, ...(this.context.endpoint && { endpoint: this.context.endpoint }), ...(this.context.method && { method: this.context.method }), timestamp: new Date().toISOString() }; return { success: false, error: { code, message: errorMessage, details: enhancedDetails, field, resolution: this.getResolution(code), supportContact: process.env.SUPPORT_CONTACT }, meta: { version: '1.0', responseTime: Date.now() - this.context.startTime }, timestamp: new Date().toISOString(), requestId: this.context.requestId }; } private getResolution(code: ApiErrorCode): string | undefined { const resolutions: Partial<Record<ApiErrorCode, string>> = { [ApiErrorCode.RATE_LIMIT_EXCEEDED]:'Please try again later',[ApiErrorCode.TOKEN_EXPIRED]:'Please refresh your session',[ApiErrorCode.UNAUTHORIZED]:'Please log in again',[ApiErrorCode.SERVICE_UNAVAILABLE]:'Please try again in a few minutes',[ApiErrorCode.CIRCUIT_BREAKER_OPEN]:'Service is temporarily unavailable. Please try again later.' }; return resolutions[code]; }}

package/src/types/auth.d.ts

@@ -1,23 +1,23 @@
-export interface Session {
-  user?: { name?: string | null; email?: string | null; image?: string | null; id?: string };
-  expires: string;
-}
-export interface JWT {
-  [key: string]: unknown;
-  name?: string | null;
-  email?: string | null;
-  sub?: string;
-}
-export type TwoFactorMethod = 'none' | 'sms' | 'authenticator' | 'passkey';
-
-export interface User {
-  id: string; email: string; name?: string | null; roles: string[]; twoFactorMethod?: TwoFactorMethod; requiresTwoFactor: boolean; accessToken?: string; refreshToken?: string; tokenType?: string;
-  authenticationMethods?: string[]; authenticationLevel?: string;
-}
-
-export interface JwtPayload { [key: string]: unknown; sub: string; email: string; name?: string; roles?: string[]; exp: number; iat: number; aud: string; iss: string; requiresTwoFactor?: boolean; twoFactorMethod?: TwoFactorMethod; amr?: string[]; acr?: string; }
-export interface JwtPayloadWithRoles extends JwtPayload { roles: string[]; requiresTwoFactor: boolean; twoFactorMethod?: TwoFactorMethod; amr?: string[]; acr?: string; }
-
-export interface AuthorizeCredentials { email?: string; password?: string; token?: string; twoFactorCode?: string; twoFactorMethod?: TwoFactorMethod; }
-
-export interface ApiResponse { access_token?: string; refresh_token?: string; requiresTwoFactor?: boolean; twoFactorMethod?: TwoFactorMethod; user_id?: string; email?: string; name?: string; roles?: string[]; error?: string; message?: string; result?: { access_token?: string; refresh_token?: string; name?: string; error?: string; id?: string; email?: string; roles?: string[]; user?: { email?: string; name?: string; roles?: string[]; id?: string; twoFactorMethod?: TwoFactorMethod | null; requiresTwoFactor?: boolean; accessToken?: string; refreshToken?: string; tokenType?: string; }; }; }
+export interface Session {
+  user?: { name?: string | null; email?: string | null; image?: string | null; id?: string };
+  expires: string;
+}
+export interface JWT {
+  [key: string]: unknown;
+  name?: string | null;
+  email?: string | null;
+  sub?: string;
+}
+export type TwoFactorMethod = 'none' | 'sms' | 'authenticator' | 'passkey';
+
+export interface User {
+  id: string; email: string; name?: string | null; roles: string[]; twoFactorMethod?: TwoFactorMethod; requiresTwoFactor: boolean; accessToken?: string; refreshToken?: string; tokenType?: string;
+  authenticationMethods?: string[]; authenticationLevel?: string;
+}
+
+export interface JwtPayload { [key: string]: unknown; sub: string; email: string; name?: string; roles?: string[]; exp: number; iat: number; aud: string; iss: string; requiresTwoFactor?: boolean; twoFactorMethod?: TwoFactorMethod; amr?: string[]; acr?: string; }
+export interface JwtPayloadWithRoles extends JwtPayload { roles: string[]; requiresTwoFactor: boolean; twoFactorMethod?: TwoFactorMethod; amr?: string[]; acr?: string; }
+
+export interface AuthorizeCredentials { email?: string; password?: string; token?: string; twoFactorCode?: string; twoFactorMethod?: TwoFactorMethod; }
+
+export interface ApiResponse { access_token?: string; refresh_token?: string; requiresTwoFactor?: boolean; twoFactorMethod?: TwoFactorMethod; user_id?: string; email?: string; name?: string; roles?: string[]; error?: string; message?: string; result?: { access_token?: string; refresh_token?: string; name?: string; error?: string; id?: string; email?: string; roles?: string[]; user?: { email?: string; name?: string; roles?: string[]; id?: string; twoFactorMethod?: TwoFactorMethod | null; requiresTwoFactor?: boolean; accessToken?: string; refreshToken?: string; tokenType?: string; }; }; }

package/src/types/auth.ts

@@ -1,48 +1,48 @@
-import { JwtPayload } from 'jwt-decode';
-
-export type AuthMode = 'traditional' | 'federated';
-export type FederatedProvider = 'google' | 'microsoft' | 'facebook' | 'github' | 'apple';
-
-export interface AuthConfig {
-  /**
-   * @deprecated Superseded by allowFederatedLogin / allowTraditionalLogin.
-   * A single mode made the two mutually exclusive, so a site could only ever show ONE of
-   * OAuth or username/password - and because sites set it themselves, a client's sign-in
-   * screen could contradict what its own IDP offered. Kept so existing callers compile.
-   */
-  mode: AuthMode;
-
-  /**
-   * Whether federated (OAuth) sign-in is offered. Defaults to what the IDP reports at
-   * /api/auth/settings; a site may override. Both this and allowTraditionalLogin can be
-   * true at once - that is the normal case.
-   */
-  allowFederatedLogin?: boolean;
-
-  /**
-   * Whether username/password sign-in is offered. DEFAULTS ON. The IDP does not carry an
-   * explicit flag for it yet; until it does, it is available unless a site opts out.
-   * An OAuth-only client is a deliberate choice, never the default.
-   */
-  allowTraditionalLogin?: boolean;
-  /**
-   * PAY-2334: where /api/auth/settings stands. 'loading' = not answered yet, 'ready' = answered (or nothing to ask:
-   * useDynamicProviders off), 'failed' = non-2xx, thrown, or timed out. Absent means 'ready'. A page must not tell the user
-   * "sign-in is not available" while this is 'loading', and must say a failed read is a failed read, not an empty answer.
-   */
-  settingsStatus?: 'loading' | 'ready' | 'failed';
-  providers: FederatedProvider[];
-  enableRecovery: boolean;
-  enableEmailSignup: boolean;
-  allowPasswordReset: boolean;
-}
-
-export interface JwtPayloadWithRoles extends JwtPayload {
-    role?: string | string[];
-    roles?: string[];
-    amr?: string[];
-    acr?: string;
-    mfa_time?: number;
-    mfa_expires?: number;
-    mfa_validity_hours?: number;
-}
+import { JwtPayload } from 'jwt-decode';
+
+export type AuthMode = 'traditional' | 'federated';
+export type FederatedProvider = 'google' | 'microsoft' | 'facebook' | 'github' | 'apple';
+
+export interface AuthConfig {
+  /**
+   * @deprecated Superseded by allowFederatedLogin / allowTraditionalLogin.
+   * A single mode made the two mutually exclusive, so a site could only ever show ONE of
+   * OAuth or username/password - and because sites set it themselves, a client's sign-in
+   * screen could contradict what its own IDP offered. Kept so existing callers compile.
+   */
+  mode: AuthMode;
+
+  /**
+   * Whether federated (OAuth) sign-in is offered. Defaults to what the IDP reports at
+   * /api/auth/settings; a site may override. Both this and allowTraditionalLogin can be
+   * true at once - that is the normal case.
+   */
+  allowFederatedLogin?: boolean;
+
+  /**
+   * Whether username/password sign-in is offered. DEFAULTS ON. The IDP does not carry an
+   * explicit flag for it yet; until it does, it is available unless a site opts out.
+   * An OAuth-only client is a deliberate choice, never the default.
+   */
+  allowTraditionalLogin?: boolean;
+  /**
+   * PAY-2334: where /api/auth/settings stands. 'loading' = not answered yet, 'ready' = answered (or nothing to ask:
+   * useDynamicProviders off), 'failed' = non-2xx, thrown, or timed out. Absent means 'ready'. A page must not tell the user
+   * "sign-in is not available" while this is 'loading', and must say a failed read is a failed read, not an empty answer.
+   */
+  settingsStatus?: 'loading' | 'ready' | 'failed';
+  providers: FederatedProvider[];
+  enableRecovery: boolean;
+  enableEmailSignup: boolean;
+  allowPasswordReset: boolean;
+}
+
+export interface JwtPayloadWithRoles extends JwtPayload {
+    role?: string | string[];
+    roles?: string[];
+    amr?: string[];
+    acr?: string;
+    mfa_time?: number;
+    mfa_expires?: number;
+    mfa_validity_hours?: number;
+}

package/src/types/logging.ts

@@ -1,11 +1,11 @@
-export interface LoggingConfig {
-  logLevel: LogLevel;
-  console: { enabled: boolean; colors: boolean; };
-  graylog: { enabled: boolean; host: string; port: number; facility: string; staticMeta: { service: string; application: string; version: string; [key: string]: any; }; };
-  components: { [key: string]: { enabled: boolean; prefix: string; }; };
-  levels: { [key: string]: number; };
-}
-export type LogLevel = 'error' | 'warn' | 'info' | 'http' | 'debug';
-export interface ComponentLoggerConfig { enabled: boolean; prefix: string; }
-export interface Logger { error: (message: string, meta?: any) => void; warn: (message: string, meta?: any) => void; info: (message: string, meta?: any) => void; http: (message: string, meta?: any) => void; debug: (message: string, meta?: any) => void; }
-export interface ComponentLogger extends Logger {}
+export interface LoggingConfig {
+  logLevel: LogLevel;
+  console: { enabled: boolean; colors: boolean; };
+  graylog: { enabled: boolean; host: string; port: number; facility: string; staticMeta: { service: string; application: string; version: string; [key: string]: any; }; };
+  components: { [key: string]: { enabled: boolean; prefix: string; }; };
+  levels: { [key: string]: number; };
+}
+export type LogLevel = 'error' | 'warn' | 'info' | 'http' | 'debug';
+export interface ComponentLoggerConfig { enabled: boolean; prefix: string; }
+export interface Logger { error: (message: string, meta?: any) => void; warn: (message: string, meta?: any) => void; info: (message: string, meta?: any) => void; http: (message: string, meta?: any) => void; debug: (message: string, meta?: any) => void; }
+export interface ComponentLogger extends Logger {}

package/src/types/recovery.ts

@@ -1,54 +1,54 @@
-export type RecoveryStep = 'initiate' | 'select-method' | 'verify-code' | 'set-password' | 'requested' | 'complete';
-
-export interface RecoverySession {
-  recoveryToken: string;
-  email: string;
-  maskedEmail?: string;
-  maskedPhone?: string;
-  hasAuthenticator?: boolean;
-  availableMethods: Array<'email' | 'sms' | 'authenticator'>;
-  expiresAt: string;
-}
-
-export interface PasswordResetToken {
-  token: string;
-  expiresAt: string;
-}
-
-export interface RecoveryError {
-  code: string;
-  message: string;
-  attemptsRemaining?: number;
-}
-
-export interface RecoveryInitiateResponse {
-  success: boolean;
-  data: {
-    recovery_session_token?: string;
-    masked_email?: string;
-    masked_phone?: string;
-    has_authenticator?: boolean;
-    available_methods?: Array<'email' | 'sms' | 'authenticator'>;
-    expires_at?: string;
-    message?: string;
-  };
-}
-
-export interface SendCodeResponse {
-  success: boolean;
-  data: {
-    method: string;
-    masked_destination: string;
-    code_length: number;
-    expires_in: number;
-  };
-}
-
-export interface VerifyCodeResponse {
-  success: boolean;
-  data?: {
-    password_reset_token: string;
-    expires_at: string;
-  };
-  error?: RecoveryError;
-}
+export type RecoveryStep = 'initiate' | 'select-method' | 'verify-code' | 'set-password' | 'requested' | 'complete';
+
+export interface RecoverySession {
+  recoveryToken: string;
+  email: string;
+  maskedEmail?: string;
+  maskedPhone?: string;
+  hasAuthenticator?: boolean;
+  availableMethods: Array<'email' | 'sms' | 'authenticator'>;
+  expiresAt: string;
+}
+
+export interface PasswordResetToken {
+  token: string;
+  expiresAt: string;
+}
+
+export interface RecoveryError {
+  code: string;
+  message: string;
+  attemptsRemaining?: number;
+}
+
+export interface RecoveryInitiateResponse {
+  success: boolean;
+  data: {
+    recovery_session_token?: string;
+    masked_email?: string;
+    masked_phone?: string;
+    has_authenticator?: boolean;
+    available_methods?: Array<'email' | 'sms' | 'authenticator'>;
+    expires_at?: string;
+    message?: string;
+  };
+}
+
+export interface SendCodeResponse {
+  success: boolean;
+  data: {
+    method: string;
+    masked_destination: string;
+    code_length: number;
+    expires_in: number;
+  };
+}
+
+export interface VerifyCodeResponse {
+  success: boolean;
+  data?: {
+    password_reset_token: string;
+    expires_at: string;
+  };
+  error?: RecoveryError;
+}