rauth-provider/types/index.d.ts

A lightweight, plug-and-play Node.js library for phone number authentication using the Rauth.io reverse verification flow via WhatsApp or SMS.

/**
 * TypeScript definitions for RauthProvider
 */

import { Request, Response, NextFunction } from 'express';

// Configuration interfaces
export interface RauthProviderConfig {
  rauth_api_key: string;
  app_id: string;
  webhook_secret: string;
  webhook_url?: string;
  default_session_ttl?: number;
  default_revoked_ttl?: number;
}

export interface SessionOptions {
  sessionToken: string;
  phone: string;
  ip: string;
  userAgent: string;
  deviceId: string;
  deviceModel: string;
  timestamp: number;
  expiresAt: number;
}

export interface DeviceInfo {
  ip: string;
  userAgent: string;
  deviceId: string;
  deviceModel: string;
}

export interface SessionData {
  phone: string;
  ttl: number;
  createdAt: number;
}

export interface RevokedData {
  reason: string;
  ttl: number;
  revokedAt: number;
}

export interface ValidationResult {
  success: boolean;
  missing: string[];
}

export interface ErrorResponse {
  success: false;
  error: {
    message: string;
    code: string;
    statusCode: number;
  };
}

export interface SuccessResponse {
  success: true;
  message: string;
  data?: any;
}

export interface SessionStats {
  activeSessions: number;
  revokedSessions: number;
  initialized: boolean;
  config: {
    app_id: string;
    webhook_url?: string;
    default_session_ttl: number;
    default_revoked_ttl: number;
  };
}

export interface ApiSessionInitResponse {
  session_token: string;
  wa_link: string;
  qr_image_link: string;
}

export interface ApiSessionResponse {
  session_token?: string;
  status?: string;
  phone?: string;
  timestamp?: number;
  ttl?: number;
  reason?: string;
}

export interface WebhookPayload {
  event: 'session_created' | 'session_revoked';
  session_token: string;
  phone?: string;
  ttl: number;
  reason?: string;
  timestamp: number;
}

export interface RouteOptions {
  webhookPath?: string;
  healthPath?: string;
  initPath?: string;
  verifyPath?: string;
  statsPath?: string;
}

// Express middleware type
export type ExpressMiddleware = (req: Request, res: Response, next: NextFunction) => void;
export type ExpressHandler = (req: Request, res: Response) => void;

// SessionStore class
export declare class SessionStore {
  constructor();
  createSession(phone: string, sessionToken: string, ttl: number): void;
  getSession(sessionToken: string): SessionData | null;
  verifySession(sessionToken: string, userPhone: string): boolean;
  removeSession(sessionToken: string): void;
  getAllSessions(): Map<string, SessionData>;
  cleanupExpiredSessions(): void;
  clear(): void;
}

// RevokedStore class
export declare class RevokedStore {
  constructor();
  revokeSession(sessionToken: string, ttl: number, reason?: string): void;
  isSessionRevoked(sessionToken: string): boolean;
  getRevokedSession(sessionToken: string): RevokedData | null;
  removeRevokedSession(sessionToken: string): void;
  getAllRevokedSessions(): Map<string, RevokedData>;
  cleanupExpiredRevokedSessions(): void;
  clear(): void;
}

// Utils class
export declare class Utils {
  static prepareSessionInitPayload(
    phone: string,
    ip: string,
    userAgent: string,
    deviceId: string,
    deviceModel: string
  ): any;
  static extractDeviceInfo(req: Request): DeviceInfo;
  static isValidPhoneNumber(phone: string): boolean;
  static validatePayload(payload: any, requiredFields: string[]): ValidationResult;
  static createErrorResponse(message: string, code?: string, statusCode?: number): ErrorResponse;
  static createSuccessResponse(data?: any, message?: string): SuccessResponse;
  static safeJsonParse(jsonString: string): any | null;
  static generateWebhookSignature(payload: string, secret: string): string;
  static verifyWebhookSignature(payload: string, signature: string, secret: string): boolean;
}

// RauthProvider class
export declare class RauthProvider {
  constructor();
  init(options: RauthProviderConfig): void;
  initSession(
    phone: string,
    headers: Record<string, string | string[] | undefined>
  ): Promise<ApiSessionInitResponse>;
  verifySession(sessionToken: string, userPhone: string): Promise<boolean>;
  isSessionRevoked(sessionToken: string): Promise<boolean>;
  createSession(phone: string, sessionToken: string, ttl: number): void;
  revokeSession(sessionToken: string, ttl: number, reason?: string): void;
  webhookHandler(): ExpressMiddleware;
  checkApiHealth(): Promise<boolean>;
  clearAllSessions(): void;
}

// RauthApiClient class
export declare class RauthApiClient {
  constructor(config: RauthProviderConfig);
  initSession(payload: any): Promise<ApiSessionInitResponse>;
  getSessionDetails(sessionToken: string): Promise<ApiSessionResponse | null>;
  verifySession(sessionToken: string): Promise<any>;
  healthCheck(): Promise<boolean>;
}

// RauthServer class
export declare class RauthServer {
  static createBodyParserMiddleware(): ExpressMiddleware;
  static createWebhookValidationMiddleware(): ExpressMiddleware;
  static createWebhookHandler(): ExpressMiddleware[];
  static createHealthCheckHandler(): ExpressHandler;
  static createSessionInitHandler(): ExpressHandler;
  static createSessionVerificationHandler(): ExpressHandler;
  static createRevocationCheckMiddleware(): ExpressMiddleware;
  static createStatsHandler(): ExpressHandler;
  static setupRoutes(app: any, options?: RouteOptions): void;
}

// Main export interface
export interface RauthProviderExports {
  // Main provider instance
  RauthProvider: RauthProvider;
  
  // Server utilities for Express integration
  RauthServer: typeof RauthServer;
  
  // Core components (for advanced usage)
  SessionStore: typeof SessionStore;
  RevokedStore: typeof RevokedStore;
  Utils: typeof Utils;
  RauthApiClient: typeof RauthApiClient;
  
  // Convenience aliases
  init(options: RauthProviderConfig): void;
  initSession(
    phone: string,
    headers: Record<string, string | string[] | undefined>
  ): Promise<ApiSessionInitResponse>;
  verifySession(sessionToken: string, userPhone: string): Promise<boolean>;
  isSessionRevoked(sessionToken: string): Promise<boolean>;
  webhookHandler(): ExpressMiddleware;
  checkApiHealth(): Promise<boolean>;
  clearAllSessions(): void;
  
  // Server utilities
  setupRoutes(app: any, options?: RouteOptions): void;
  createWebhookHandler(): ExpressMiddleware[];
  createHealthCheckHandler(): ExpressHandler;
  createSessionInitHandler(): ExpressHandler;
  createSessionVerificationHandler(): ExpressHandler;
  createRevocationCheckMiddleware(): ExpressMiddleware;
  createStatsHandler(): ExpressHandler;
}

// Default export
declare const rauthProvider: RauthProviderExports;
export default rauthProvider;

// Named exports
export {
  RauthProvider,
  RauthServer,
  SessionStore,
  RevokedStore,
  Utils,
};