SDK Documentation

Complete guide to using the Fayda Authentication JavaScript/TypeScript SDK.

Installation

Install the Fayda Authentication SDK using your favorite package manager.

bash

# Using npm
npm i fayda-auth

# Using yarn
yarn add fayda-auth

# Using pnpm
pnpm add fayda-auth

Quick Start

Get started with the SDK in just a few lines of code.

javascript

import { FaydaAuth } from 'fayda-auth';

// Initialize the SDK with your API key
const fayda = new FaydaAuth({
  apiKey: 'your-api-key-here'
});

// Complete authentication flow
async function authenticateUser(fcn) {
  try {
    // Step 1: Initiate OTP
    const otpResult = await fayda.initiateOTP(fcn);
    console.log('OTP sent to:', otpResult.maskedMobile);
    
    // Step 2: Get OTP from user (implementation depends on your UI)
    const otp = await getUserOTPInput();
    
    // Step 3: Verify OTP
    const verifyResult = await fayda.verifyOTP(otpResult.transactionId, otp, fcn);
    console.log('User authenticated:', verifyResult.user.fullName[0].value);
    
    return verifyResult.user;
  } catch (error) {
    console.error('Authentication failed:', error.message);
    throw error;
  }
}

Configuration

The FaydaAuth constructor accepts a configuration object with the following options.

Option	Type	Required	Default	Description
apiKey	String	Yes	-	Your API key from the developer dashboard.
baseURL	String	No	https://fayda-auth.vercel.app	Base URL for the our API.
timeout	Number	No	30000	Request timeout in milliseconds.
retries	Number	No	3	Number of retry attempts for failed requests.
debug	Boolean	No	false	Enable debug logging.

API Methods

Core methods available in the SDK for authentication.

`initiateOTP(fcn)`

Initiates OTP verification with a Fayda Card Number.

javascript

const result = await fayda.initiateOTP('1234567890123456');
console.log('Transaction ID:', result.transactionId);
console.log('OTP sent to:', result.maskedMobile);

`verifyOTP(transactionId, otp, fcn)`

Verifies an OTP code and returns user data if successful.

javascript

const result = await fayda.verifyOTP(transactionId, '123456', '1234567890123456');
console.log('User:', result.user.fullName[0].value);
console.log('UIN:', result.user.uin);

// Access photo and QR code
const photoBase64 = result.photo.data;
const qrCodeBase64 = result.qrCode.data;

Error Handling

The SDK throws standardized error objects for different failure scenarios.

javascript

try {
  const result = await fayda.initiateOTP('invalid-fcn');
} catch (error) {
  console.log('Error type:', error.error);
  console.log('Message:', error.message);
  console.log('Status code:', error.statusCode);
  
  // Handle specific error types
  switch (error.error) {
    case 'INVALID_FCN':
      // Handle invalid FCN format
      break;
    case 'FCN_NOT_FOUND':
      // Handle FCN not found
      break;
    case 'RATE_LIMITED':
      // Handle rate limiting
      break;
    case 'NETWORK_ERROR':
      // Handle network issues
      break;
    default:
      // Handle other errors
      break;
  }
}

View complete error reference →

TypeScript Support

The SDK includes full TypeScript definitions. Here are the main types.

typescript

import { 
  FaydaAuth, 
  FaydaConfig, 
  OTPInitiateResponse, 
  OTPVerifyResponse,
  FaydaUser,
  FaydaError 
} from '@fayda/auth';

// Configuration type
interface FaydaConfig {
  apiKey: string;
  timeout?: number;
  retries?: number;
  debug?: boolean;
}

// User data type
interface FaydaUser {
  uin: string;
  fullName: Array<{ language: string; value: string }> ;
  dateOfBirth: string;
  gender: Array<{ language: string; value: string }> ;
  phone: string;
  region: Array<{ language: string; value: string }> ;
  zone: Array<{ language: string; value: string }> ;
  woreda: Array<{ language: string; value: string }> ;
}

// Error type
interface FaydaError extends Error {
  error: string;
  statusCode: number;
  details?: any;
  timestamp: string;
}

Best Practices

Recommendations for security, performance, and user experience.

Security

Never expose your API key in client-side code.
Use environment variables to store your API key.
Implement proper error handling to avoid exposing sensitive information.
Clear sensitive data from memory after use.

Performance

Reuse FaydaAuth instances instead of creating new ones for each request.
Implement proper timeout handling for better user experience.
Use appropriate retry logic for network failures.
Cache configuration settings when possible.

User Experience

Provide clear feedback during the OTP process.
Implement proper loading states and error messages.
Handle rate limiting gracefully with appropriate user messaging.
Validate FCN format on the client side before API calls.

More Examples

For more comprehensive examples and use cases, visit our examples section.

Browse Code Examples