Why Another Color Library?

With Flutter's recent updates, many existing color manipulation libraries have become outdated, still using deprecated color APIs. Color Palette Plus was built from the ground up to:

• Use Flutter's modern color component accessors (.r, .g, .b, .a)

• Properly handle color components in the 0.0-1.0 range

• Provide efficient color transformations

• Maintain type safety and null safety

Key Features

1. Material Design Swatch Generation

Generate complete Material Design color swatches from any base color:

import 'package:color_palette_plus/color_palette_plus.dart';

final baseColor = Color(0xFF2196F3); // Blue
final materialSwatch = ColorPalette.generateSwatch(baseColor);

// Access shades
final primaryColor = materialSwatch[500];
final lightVariant = materialSwatch[200];
final darkVariant = materialSwatch[700];

2. Color Harmonies

Create harmonious color combinations with built-in generators:

// Monochromatic variations
final monochromaticColors = ColorPalettes.monochromatic(
  baseColor,
  steps: 5,
);

// Analogous colors
final analogousColors = ColorPalettes.analogous(
  baseColor,
  steps: 3,
  angle: 30,
);

// Complementary colors
final complementaryColors = ColorPalettes.complementary(baseColor);

3. Flexible Shade Access

Access color shades in multiple ways:

// Get a specific shade
final shade = ColorPalette.getShade(baseColor, 500);

// Get all shades as a map
final allShades = ColorPalette.getAllShades(baseColor);

Real-World Usage Examples

1. Dynamic Theme Generation

Create dynamic themes based on a brand color:

MaterialApp(
  theme: ThemeData(
    primarySwatch: ColorPalette.generateSwatch(brandColor),
    // Use specific shades for different elements
    scaffoldBackgroundColor: ColorPalette.getShade(brandColor, 50),
    appBarTheme: AppBarTheme(
      backgroundColor: ColorPalette.getShade(brandColor, 500),
    ),
  ),
)

2. Custom Color Schemes

Generate custom color schemes for your UI:

class CustomColorScheme {
  final Color primary;
  final Color secondary;
  final Color accent;

  CustomColorScheme(Color baseColor) {
    final swatch = ColorPalette.generateSwatch(baseColor);
    primary = swatch[500]!;

    // Generate analogous colors for variety
    final analogous = ColorPalettes.analogous(baseColor);
    secondary = analogous[1];
    accent = analogous[2];
  }
}

3. Accessible Color Combinations

Create accessible color pairs:

Widget buildAccessibleText(Color backgroundColor) {
  // Get contrasting text color based on background
  final textColor = backgroundColor.computeLuminance() > 0.5 
    ? ColorPalette.getShade(backgroundColor, 900)
    : ColorPalette.getShade(backgroundColor, 50);

  return Container(
    color: backgroundColor,
    child: Text(
      'Accessible Text',
      style: TextStyle(color: textColor),
    ),
  );
}

Performance Tips

1. Cache Generated Colors

Instead of generating colors in build methods:

class ColorProvider extends ChangeNotifier {
  late final MaterialColor _primarySwatch;
  late final List<Color> _analogousColors;

  ColorProvider(Color baseColor) {
    _primarySwatch = ColorPalette.generateSwatch(baseColor);
    _analogousColors = ColorPalettes.analogous(baseColor);
  }

  MaterialColor get primarySwatch => _primarySwatch;
  List<Color> get analogousColors => _analogousColors;
}

2. Avoid Repeated Generations

Cache commonly used shades:

class ThemeColors {
  static final Map<Color, MaterialColor> _swatchCache = {};

  static MaterialColor getSwatchFor(Color color) {
    return _swatchCache.putIfAbsent(
      color,
      () => ColorPalette.generateSwatch(color),
    );
  }
}

Best Practices

1. Shade Selection

   • Use 500 for the primary color

   • Use 50-200 for backgrounds

   • Use 700-900 for text on light backgrounds

   • Use 50-100 for text on dark backgrounds

2. Color Harmony

   • Use monochromatic palettes for subtle variations

   • Use analogous colors for related UI elements

   • Use complementary colors for contrast and emphasis

3. Accessibility

   • Always test contrast ratios

   • Provide sufficient color contrast for text

   • Don't rely solely on color to convey information

Getting Started

1. Add to your pubspec.yaml:

dependencies:
  color_palette_plus: ^1.0.0

2. Import the library:

import 'package:color_palette_plus/color_palette_plus.dart';

3. Start using it in your code!

Requirements

• Flutter ≥ 3.27.0

• Dart ≥ 3.6.0

Pub Dev Link: color_palette_plus

Conclusion

Color Palette Plus simplifies color management in Flutter while ensuring you're using modern, efficient practices. Whether you're building a theme system, creating a design system, or just need some color variations, Color Palette Plus has you covered.

Check out the GitHub repository for more examples and documentation. We welcome contributions and feedback from the community!

What's Next?

We're planning to add more features in future releases:

• Color palette export/import

• Additional color harmony algorithms

• Color accessibility scoring

• Color naming suggestions

Stay tuned for updates, and don't forget to star the repository if you find it useful!

Happy coding! 🎨 ✨

The goal of this article is to get a comprehensive understanding of the flutter declarative routing and the scenarios like login state, app initialization on startup, splash, onboarding, etc...

Problems that I'm trying to solve

assume we have a flutter application that we have to handle those situations.

• We need to show the onboarding page when the user opens the app for the first time.
• We need to execute some initialisation functions every time the app opens.
• The application should be capable of kicking out the user anywhere in the application when the login state changes (log out).
• And also app should be capable of handling the deep links regardless of login state.

I know, It looks like a lot. but stay with me I'm going to cover it all in this article

Starting the project

First of all, let's create the application. assuming that you have already installed flutter (I use the currently available latest version v2.8.0) Create a folder and inside it run this command,

flutter create --template app --overwrite.

I'm sure you are using vs-code or android studio for this so you don't have to create an app manually. if you do just ignore the above command and create the app from the IDE.

throughout the project, I'm going to run the application on the web. since all plugging, I'm using here is platform-independent you can use any platform you like it's totally up to you.

Okay, Let's add plugging to the pubspec.yaml under dependencies

• provider: ^6.0.1

  we will be using the provider package to do all the state management in our application.

• go_router: ^2.5.5

  The purpose of the go_router package is to use declarative routes to reduce complexity, regardless of the platform you're targeting (mobile, web, desktop), handle deep and dynamic linking from Android, iOS and the web, along with several other navigation-related scenarios, while still (hopefully) providing an easy-to-use developer experience.

• shared_preferences: ^2.0.11

  will be used to store some persistent data that we have kept in our application.

That's it, that's all the package we are going to use, run flutter pub get to get the packages.

flutter pub get

Let's start the coding

Open the main.dart file and remove everything and create the main function like this.

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();
  final SharedPreferences sharedPreferences = await SharedPreferences.getInstance();
  runApp(MyApp(sharedPreferences: sharedPreferences));
}

then create the MyApp class by extending the StatefulWidget because we need initState inside this widget.

class MyApp extends StatefulWidget {
  final SharedPreferences sharedPreferences;
  const MyApp({
    Key? key,
    required this.sharedPreferences,
  }) : super(key: key);

  @override
  _MyAppState createState() => _MyAppState();
}

class _MyAppState extends State<MyApp> {
  @override
  Widget build(BuildContext context) {
    return Container(

    );
  }
}

Okay, then let's create some files for the classes, take a close look and complete the appropriate files and folders for the next step.

Route Utils

Let's create enum class inside the route_utils.dart file that contain all the pages that our application has.

enum APP_PAGE {
  splash,
  login,
  home,
  error,
  onBoarding
}

Then we will add extension to the APP_PAGE for purpose convinent.

extension AppPageExtension on APP_PAGE {
  String get toPath {
    switch (this) {
      case APP_PAGE.home:
        return "/";
      case APP_PAGE.login:
        return "/login";
      case APP_PAGE.splash:
        return "/splash";
      case APP_PAGE.error:
        return "/error";
      case APP_PAGE.onBoarding:
        return "/start";
      default:
        return "/";
    }
  }

  String get toName {
    switch (this) {
      case APP_PAGE.home:
        return "HOME";
      case APP_PAGE.login:
        return "LOGIN";
      case APP_PAGE.splash:
        return "SPLASH";
      case APP_PAGE.error:
        return "ERROR";
      case APP_PAGE.onBoarding:
        return "START";
      default:
        return "HOME";
    }
  }

  String get toTitle {
    switch (this) {
      case APP_PAGE.home:
        return "My App";
      case APP_PAGE.login:
        return "My App Log In";
      case APP_PAGE.splash:
        return "My App Splash";
      case APP_PAGE.error:
        return "My App Error";
      case APP_PAGE.onBoarding:
        return "Welcome to My App";
      default:
        return "My App";
    }
  }
}

Next, we will create StatelessWidget inside every view file except splash_page.dart file, inside that create a StatefulWidget,

then, let's create the AppService class,

// ignore: non_constant_identifier_names
String LOGIN_KEY = "5FD6G46SDF4GD64F1VG9SD68";
// ignore: non_constant_identifier_names
String ONBOARD_KEY = "GD2G82CG9G82VDFGVD22DVG";

class AppService with ChangeNotifier {
  late final SharedPreferences sharedPreferences;
  final StreamController<bool> _loginStateChange = StreamController<bool>.broadcast();
  bool _loginState = false;
  bool _initialized = false;
  bool _onboarding = false;

  AppService(this.sharedPreferences);

  bool get loginState => _loginState;
  bool get initialized => _initialized;
  bool get onboarding => _onboarding;
  Stream<bool> get loginStateChange => _loginStateChange.stream;

  set loginState(bool state) {
    sharedPreferences.setBool(LOGIN_KEY, state);
    _loginState = state;
    _loginStateChange.add(state);
    notifyListeners();
  }

  set initialized(bool value) {
    _initialized = value;
    notifyListeners();
  }

  set onboarding(bool value) {
    sharedPreferences.setBool(ONBOARD_KEY, value);
    _onboarding = value;
    notifyListeners();
  }

  Future<void> onAppStart() async {
    _onboarding = sharedPreferences.getBool(ONBOARD_KEY) ?? false;
    _loginState = sharedPreferences.getBool(LOGIN_KEY) ?? false;

    // This is just to demonstrate the splash screen is working.
    // In real-life applications, it is not recommended to interrupt the user experience by doing such things.
    await Future.delayed(const Duration(seconds: 2));

    _initialized = true;
    notifyListeners();
  }
}

This is our AppService class, we create it with ChangeNotifier so we can listen for the state changes using Provider.

SharedPreferences instance that we created earlier will use in this class. and there are several values to keep track of the different states of the application.

While the initialized value only lives through the app life circle, loginState and onboarding values will be stored in local storage, because those values need to be kept even if the app is entirely closed. the onAppStart method is responsible for reading those values from local storage and finishing the app initialization. we will be showing the Splash screen until the onAppStart future is completed.

Ok, now we can define the routers, I'm going to do it by using Go Router if you're not familiar with its basic concepts first of all you should take a look at its documentation.

Let's start routing

we need to create the AppRouter class which contains all the routing information in our application.

 class AppRouter {
  late final AppService appService;
  GoRouter get router => _goRouter;

  AppRouter(this.appService);

  late final GoRouter _goRouter = GoRouter(
    refreshListenable: appService,
    initialLocation: APP_PAGE.home.toPath,
    routes: <GoRoute>[
      GoRoute(
        path: APP_PAGE.home.toPath,
        name: APP_PAGE.home.toName,
        builder: (context, state) => const HomePage(),
      ),
      GoRoute(
        path: APP_PAGE.splash.toPath,
        name: APP_PAGE.splash.toName,
        builder: (context, state) => const SplashPage(),
      ),
      GoRoute(
        path: APP_PAGE.login.toPath,
        name: APP_PAGE.login.toName,
        builder: (context, state) => const LogInPage(),
      ),
      GoRoute(
        path: APP_PAGE.onBoarding.toPath,
        name: APP_PAGE.onBoarding.toName,
        builder: (context, state) => const OnBoardingPage(),
      ),
      GoRoute(
        path: APP_PAGE.error.toPath,
        name: APP_PAGE.error.toName,
        builder: (context, state) => ErrorPage(error: state.extra.toString()),
      ),
    ],
    errorBuilder: (context, state) => ErrorPage(error: state.error.toString()),
    redirect: (state) {
      final loginLocation = state.namedLocation(APP_PAGE.login.toPath);
      final homeLocation = state.namedLocation(APP_PAGE.home.toPath);
      final splashLocation = state.namedLocation(APP_PAGE.splash.toPath);
      final onboardLocation = state.namedLocation(APP_PAGE.onBoarding.toPath);

      final isLogedIn = appService.loginState;
      final isInitialized = appService.initialized;
      final isOnboarded = appService.onboarding;

      final isGoingToLogin = state.subloc == loginLocation;
      final isGoingToInit = state.subloc == splashLocation;
      final isGoingToOnboard = state.subloc == onboardLocation;

      // If not Initialized and not going to Initialized redirect to Splash
      if (!isInitialized && !isGoingToInit) {
        return splashLocation;
      // If not onboard and not going to onboard redirect to OnBoarding
      } else if (isInitialized && !isOnboarded && !isGoingToOnboard) {
        return onboardLocation;
      // If not logedin and not going to login redirect to Login
      } else if (isInitialized && isOnboarded && !isLogedIn && !isGoingToLogin) {
        return loginLocation;
      // If all the scenarios are cleared but still going to any of that screen redirect to Home
      } else if ((isLogedIn && isGoingToLogin) || (isInitialized && isGoingToInit) || (isOnboarded && isGoingToOnboard)) {
        return homeLocation;
      } else {
      // Else Don't do anything
        return null;
      }
    },
  );

Whoa, whoa what the fudge is going on here?

It looks like too much information to take but don't worry I'm going to break down it for you.

late final AppService appService;
GoRouter get router => _goRouter;

Here we define the AppService object and the GoRouter object, Since the AppService is listenable we can listen for the state changes and rebuild the router delegate according to the app states.

refreshListenable: appService,
initialLocation: APP_PAGE.home.toPath,

refreshListenable is that we define a listenable class to go router to react to changes. and the initialLocation is the default location that the app will redirect when there is no other path when the app starts (like deep links and dynamic links).

GoRoute(
  path: APP_PAGE.home.toPath,
  name: APP_PAGE.home.toName,
  builder: (context, state) => const HomePage(),
),

Here are all the predefined locations in our application. you can see that earlier we create APP_PAGE enum class and an extension for it. it is super convenient to define the path, and name when we have such a class that's why we created it.

If you take a closer look you will see we use ErrorPage on two different locations routers and errorBuilder. one inside the routers, we will use for manually navigate to the error page when there is a critical error in our application. the errorBuilder will use by Go Router to throw exceptions when there is something like an undefined navigation path.

one thing that I forgot to mention, there is a String argument on the error page called error which we will use to show an error to the user. when errorBuilder is triggered, always exception will be stored in the state.error object, when we navigate to the error page manually we will carry the error string inside the state.extra object. more information about it here.

Redirects

This method is the most important part of our application. it will handle all the core routing logic of the application, let's break down the block by block for better understanding.

final loginLocation = state.namedLocation(APP_PAGE.login.toName);
final homeLocation = state.namedLocation(APP_PAGE.home.toName);
final splashLocation = state.namedLocation(APP_PAGE.splash.toName);
final onboardLocation = state.namedLocation(APP_PAGE.onBoarding.toName);

Here we get all the locations from the router so we know where to redirect in different scenarios.

final isLogedIn = appService.loginState;
final isInitialized = appService.initialized;
final isOnboarded = appService.onboarding;

Then we get all the current states in our application from appService so we know what to do next when we redirect.

final isGoingToLogin = state.subloc == loginLocation;
final isGoingToInit = state.subloc == splashLocation;
final isGoingToOnboard = state.subloc == onboardLocation;

Finally we get where we actually go so we know when to redirect or not.

See it's not that complicated

Ok, ok, the next part is quite complicated, let's break it down,

We know that there are two cases where the redirect method called

• When we navigate to another location.
• When appService object changes.

  because the router is always listing for its changes when it happens router will be rebuilt.

assume the app is starting for the first time, the sub-location of the router will be initialLocation which is home /, so this is the first case that I mentioned above the redirect method will be called, after collecting all the information we are in the if statement. so it will check app is initialized or not, obviously it is false. because we are stating the app and also we are not going to splash screen. so the statement will be valid we will return Splash Screen Location /splash. when we do that unintentionally also triggered the first case because the navigator location has changed. so the redirect method will be called again but this time isInitialized is still false but isGoingToInit is true because we are going to splash the screen. so along with the if statement all other conditions will be false. we just let go of the navigator to do its thing without changing anything. so at this point,

there is a three-state value of this application, and any of that is not changed yet.

app is just going to the splash screen

and already redirect method is called 3 times

those are the main three-point I need you to understand here. if you didn't please repeat the above paragraph again until you do.

before we start the splash screen we have to do one thing,

Adding Provider and Router to the App

class _MyAppState extends State<MyApp> {
  late AppService appService;

  @override
  void initState() {
    appService = AppService(widget.sharedPreferences);
    super.initState();
  }

  @override
  Widget build(BuildContext context) {
    return MultiProvider(
      providers: [
        ChangeNotifierProvider<AppService>(create: (_) => appService),
        Provider<AppRouter>(create: (_) => AppRouter(appService)),
      ],
      child: Builder(
        builder: (context) {
          final GoRouter goRouter = Provider.of<AppRouter>(context, listen: false).router;
          return MaterialApp.router(
            title: "Router App",
            routeInformationParser: goRouter.routeInformationParser,
            routerDelegate: goRouter.routerDelegate,
          );
        },
      ),
    );
  }
}

You can see in the above code we have created appService object and initialized it inside initState function with sharedPreferences instance. After that we have to wrap MaterialApp with MultiProvider and then add appService as ChangeNotifierProvider also we will declare AppRouter with appService as a provider too. finally we can add routeInformationParser and routerDelegate to the MaterialApp.router by getting it from context. We have not created AuthService yet, it will be added later.

Okay, back to the splash screen

Splash Screen

There is one thing we have to do in the splash screen which is we need to call the onAppStart function.

class SplashPage extends StatefulWidget {
  const SplashPage({ Key? key }) : super(key: key);

  @override
  _SplashPageState createState() => _SplashPageState();
}

class _SplashPageState extends State<SplashPage> {
  late AppService _appService;

  @override
  void initState() {
    _appService = Provider.of<AppService>(context, listen: false);
    onStartUp();
    super.initState();
  }

  void onStartUp() async {
    await _appService.onAppStart();
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: Text(APP_PAGE.splash.toTitle),
      ),
      body: const Center(
        child: CircularProgressIndicator(),
      ),
    );
  }
}

once we are on the splash screen onAppStart function will be triggered, so it will read _onboarding and _loginState values from the locale storage and will change _initialized to true then will call notifyListeners as soon as that happens, the router will be rebuilt and will recall the redirect function.

oh god, that's too much "re" 😂

Okay, back to the redirect function

At this point isInitialized is true and other values will be false so obviously, it will redirect to the onboardLocation and inside the OnBoardingPage user will press the Done button and we will change _onboarding to true, it pretty much the same thing I think you can now understand the redirect function logics. Let's move on to the AuthService

Authentication Service

The reason why we are creating a separate AuthService class while tricking the login state inside the AppService, it will be so clean and understandable to implement authentication logic in a separate class and just expose the login state by an event stream. if you have experience with FirebaseAuth you will easily understand what I'm doing here,

class AuthService {
  final StreamController<bool> _onAuthStateChange = StreamController.broadcast();

  Stream<bool> get onAuthStateChange => _onAuthStateChange.stream;

  Future<bool> login() async {

    // This is just to demonstrate the login process time.
    // In real-life applications, it is not recommended to interrupt the user experience by doing such things.
    await Future.delayed(const Duration(seconds: 1));

    _onAuthStateChange.add(true);
    return true;
  }

  void logOut() {
    _onAuthStateChange.add(false);
  }
}

ok, now it's time to update the main.dart with AuthService we will declare it in the initState and add a listener to change the loginState.

class _MyAppState extends State<MyApp> {
  late AppService appService;
  late AuthService authService;
  late StreamSubscription<bool> authSubscription;

  @override
  void initState() {
    appService = AppService(widget.sharedPreferences);
    authService = AuthService();
    authSubscription = authService.onAuthStateChange.listen(onAuthStateChange);
    super.initState();
  }

  void onAuthStateChange(bool login) {
    appService.loginState = login;
  }

  @override
  void dispose() {
    authSubscription.cancel();
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    return MultiProvider(
      providers: [
        ChangeNotifierProvider<AppService>(create: (_) => appService),
        Provider<AppRouter>(create: (_) => AppRouter(appService)),
        Provider<AuthService>(create: (_) => authService),
      ],
      child: Builder(
        builder: (context) {
          final GoRouter goRouter = Provider.of<AppRouter>(context, listen: false).router;
          return MaterialApp.router(
            title: "Router App",
            routeInformationParser: goRouter.routeInformationParser,
            routerDelegate: goRouter.routerDelegate,
          );
        },
      ),
    );
  }
}

Finally, we have finished almost all the coding now,

we just need to add some buttons and run the application. I'll just add the home page code here the full source code will be available on GitHub.

class HomePage extends StatelessWidget {
  const HomePage({ Key? key }) : super(key: key);

  @override
  Widget build(BuildContext context) {
    final authService = Provider.of<AuthService>(context);
    return Scaffold(
      appBar: AppBar(
        title: Text(APP_PAGE.home.toTitle),
      ),
      body: Center(
        child: Column(
          children: [
            TextButton(
              onPressed: () {
                authService.logOut();
              },
              child: const Text(
                "Log out"
              ),
            ),
            TextButton(
              onPressed: () {
                GoRouter.of(context).goNamed(APP_PAGE.error.toName, extra: "Erro from Home");
              },
              child: const Text(
                "Show Error"
              ),
            ),
          ],
        ),
      ),
    );
  }
}

Okay, let's run the application,

You will clearly see everything is working as expected.

Okay, I'm going to wrap up the article here. since it is already too long, Handling Deep Link will be discussed in a separate article later. The link will be updated.

I know this is not the most advanced way to do it. But I think it is good, at what it is capable of. Feel free to share your thoughts in the comment section. Don't hesitate to ask questions I will help you. Don't forget to like, and share the article with your Flutter friends.

Github Repository

Happy coding.

Yes, you can and here is how we are going to do it.

So then I decide to do it by myself creating a separate API for the Mobile verification.

Creating the project

First of all, let's create a FastAPI project. I use vs-code for the development. create a folder for the project and inside it create the main python file main.py.

then let's create a virtual environment for the project. I will use venv, you should have to have python installed in your system I use python 3.10 the latest version currently available.

Open a new terminal inside project-root and run this command.

python -m venv venv

It will create a folder venv in the project root. after that, we can activate the virtual environment using the below command accordingly to your system.

# bash (Unix or MacOS)
source venv/bin/activate

# PowerShell (Windows)
venv\Scripts\Activate.ps1

If you use vs-code with python extension installed, as soon as you create the environment you will be asked to activate it automatically. Just press the YES and then kill and recreate the terminal.

To continue we need an SMS gateway, after trying several locally provided services I decided to go with send.lk they give you free 30 credits on sign up. (Not sponsored) I'm not going to explain it you can register from their website and get an API key.

Moving on, let's install the necessary packages to start coding.

pip install fastapi python-dotenv sendlk uvicorn

to keep a track of necessary packages let's create a requirements.txt file too.

pip freeze > requirements.txt

Start the project coding

Inside the main.py file let's import the FastAPI and create the app.

from fastapi import FastAPI

# Create the app
app: FastAPI = FastAPI(
    title="FastAPI Mobile Verification",
    version="0.1.0",
)

# App Root
@app.get("/", name="root")
def root():
    return {"message": f"Welcome to Mobile Verification API {app.version}"}

Done, Now we can start the debug server for the real-time preview of the API. Run the below command inside the venv activated terminal in the project root.

uvicorn --port 8000 --reload main:app

you will see that debug server started in port 8000, we use --reload flag to reload the server on file changes.

once again if you are using vs-code you can create the debug configuration by creating a launch.json file inside the project-root/.vscode folder with the following content.

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Python: FastAPI",
            "type": "python",
            "request": "launch",
            "module": "uvicorn",
            "args": [
                "--port",
                "8000",
                "--reload",
                "main:app"
            ],
            "jinja": true
        }
    ]
}

After stating the debug server if you go to http://localhost:8000 you will see that the API is working and we are getting the content of the root path.

localhost:8000

hope you are not getting any errors or problems running the API 🤞

Add Environment variables

Ok, let's add the Sendlk token and sender id to the .env file so that we can keep it private if we ever push this to a public repository. also, we will add a secret string to encrypt the OTP token.

# Send lk token
SENDLK_TOKEN="sendlk-token"
SENDER_ID="sender-id"
SECRET="my-super-secret"

and add these two lines to the top of the main.py

from dotenv import load_dotenv
# Load the .env file
load_dotenv(".env")

also, add the .gitignore file to the project root with the following content

### dotenv ###
.env
venv
.idea

### Python ###
# Byte-compiled / optimized / DLL files
__pycache__/
*.py[cod]
*$py.class

restart the server

I know the article is getting long but I'm going to finish this with one article. stay with me,

to implement the feature first we will create folder src, inside that create three files controller.py, schema.py and route.py. like this

before using the sendlk package we need to initialize it first after doing it main.py file will look like this

from fastapi import FastAPI
from dotenv import load_dotenv
import sendlk
import os

# Load the .env file
load_dotenv(".env")

SENDLK_TOKEN = os.environ.get("SENDLK_TOKEN")
SECRET = os.environ.get("SECRET")

sendlk.initialize(SENDLK_TOKEN, SECRET)

# Create the app
app: FastAPI = FastAPI(
    title="FastAPI Mobile Verification",
    version="0.1.0",
)

# App Root
@app.get("/", name="root")
def root():
    return {"message": f"Welcome to Mobile Verification API {app.version}"}

restart the server

Creating Controllers

inside the controller file, we are going to create some functions. first import those modules.

from sendlk.engine import SMS
from sendlk.responses import SmsResponse
from sendlk.exceptions import SendLKException
from sendlk.options import SendLKVerifyOption, SendLKCodeTemplet
from fastapi.exceptions import HTTPException
from starlette.responses import JSONResponse
import os

Ok, let's create send_verify_code function, it will accept the user phone number as an argument and will return the token.

def send_verify_code(phone_number: str) -> str:
    pass

Almost forgot, add this line before the function and after the import lines

SENDER_ID = os.environ.get("SENDER_ID")

then we will create SendLKVerifyOption object to call the actual function

def send_verify_code(phone_number: str) -> str:

    # Create the SMS option object
    options: SendLKVerifyOption = SendLKVerifyOption(
        code_length=4,
        expires_in=3,
        sender_id=SENDER_ID,
        code_templet=CustomCodeTemplet()
    )

code_length is the OTP code length

expires_in means how much time that users have to submit the code, the token will be expired after this time. here I use 3 minutes.

sender_id is the sender id that wants to use with the text message.

but... wait...

what the fudge nugget is the CustomCodeTemplet()

here is the deal, in the sendlk package it has a default text body to send code to the phone number which is something like 0000 is your verification code. ugly right? so we can override that and provide our own text body. like adding our company name to it like this -> *0000 is the verification code for foo service.* Nice.

So let's do it. if you want you can create a separate file but I'm going to use the same file here. before the send function add this class.

class CustomCodeTemplet(SendLKCodeTemplet):
    def __init__(self):
        super().__init__()

    def text(self, code: str) -> str:
        return f"{code} is the varification code for foo serveice."

I don't think I have to explain the above code it's quite self explainable, right? Ok moving on, we are going to use try except for the sendlk call. add this to the function.

def send_verify_code(phone_number: str) -> str:

    try:
        # Create the SMS option object
        options: SendLKVerifyOption = SendLKVerifyOption(
            code_length=4,
            expires_in=3,
            sender_id=SENDER_ID,
            code_templet=CustomCodeTemplet()
        )

        response = SMS.send_verify_code(number=phone_number, verify_option=options)
        token = response.data.get("token", None)
        return token
    except SendLKException as e:
        raise HTTPException(status_code=400, detail=e.message)

response = SMS.send_verify_code(number=phone_number, verify_option=options) this is the line we acthuly send the code it will return the SmsResponse object with the token inside it.

ok, what the fudge is this token? let me explain it to you.

Assume we providing phone number verification on our own mobile application. after we get the phone number from the user we make a request to the API with the number. then API will generate a code and send it to the user's phone number and API will send a response back to our app with the token which indicates the code. we don't even know what code the client received (obviously you can view it from the gateway dashboard). with the token app will wait for the client code submit. after that app will make another request to the API with code and token. API will verify the code and finish the process. Here is how it's work...

back to the code.

if everything goes right we return the token otherwise will raise an exception with status code 400.

let's move on to the next function which is validate_code.

def validate_code(token: str, code: str) -> str:
    try:
        # Validate the code
        response = SMS.validate_verify_code(code=code, token=token)
        return response.message
    except SendLKException as e:
        raise HTTPException(status_code=400, detail=e.message)

I'm sure the code is pretty self explainable right. anyway here we take token and code as arguments we will give it to the validate function on SMS class if we received success response we just return the message otherwise again we raise an exception.

ok, end of the file here is the full code

from sendlk.engine import SMS
from sendlk.responses import SmsResponse
from sendlk.exceptions import SendLKException
from sendlk.options import SendLKVerifyOption, SendLKCodeTemplet
from fastapi.exceptions import HTTPException
from starlette.responses import JSONResponse
import os

SENDER_ID = os.environ.get("SENDER_ID")

class CustomCodeTemplet(SendLKCodeTemplet):
    def __init__(self):
        super().__init__()

    def text(self, code: str) -> str:
        return f"{code} is the varification code for foo serveice."

def send_verify_code(phone_number: str) -> str:

    try:
        # Create the SMS option object
        options: SendLKVerifyOption = SendLKVerifyOption(
            code_length=4,
            expires_in=3,
            sender_id=SENDER_ID,
            code_templet=CustomCodeTemplet()
        )

        response = SMS.send_verify_code(number=phone_number, verify_option=options)
        token = response.data.get("token", None)
        return token
    except SendLKException as e:
        raise HTTPException(status_code=400, detail=e.message)

def validate_code(token: str, code: str) -> str:
    try:
        # Validate the code
        response = SMS.validate_verify_code(code=code, token=token)
        return response.message
    except SendLKException as e:
        raise HTTPException(status_code=400, detail=e.message)

Creating Schemas

moving on to the schema.py let's create some schemas.

from pydantic import BaseModel

class Token(BaseModel):
    token: str

class PhoneNumber(BaseModel):
    phone_number: str

class ValidateCode(Token):
    code: str

class Message(BaseModel):
    message: str

Alright, I know this is not necessary to do. but come on let's do it right.

if you don't know what is schemas it is like blueprints for the API, we predefined the request and response models so there will be no mistakes when calling the API.

Creating Routes

okay, finally we are going to create the routes

from fastapi import APIRouter
from src.controller import send_verify_code, validate_code
from src.schema import PhoneNumber, ValidateCode, Token, Message

router = APIRouter(prefix="/code")

@router.post("/send", response_model=Token)
def send_verify_code_handler(phone_number: PhoneNumber):
    token = send_verify_code(phone_number.phone_number)
    return Token(token=token)

@router.post("/validate", response_model=Message)
def validate_code_handler(validate: ValidateCode):
    message = validate_code(validate.token, validate.code)
    return Message(message=message)

you can clearly see what is going on, again I'm not going to explain line by line this is not entirely a FastAPI tutorial after all. anyway, we create sub route /code and add two post requests to it. send_verify_code_handler and validate_code_handler which will accept requests according to the schemas and return the response appropriately.

Finishing the Project

as the final step back to the main.py,

import the router after the sendlk initialize line then add the route to the main app, that's it we done.

from fastapi import FastAPI
from dotenv import load_dotenv
import sendlk
import os

# Load the .env file
load_dotenv(".env")

SENDLK_TOKEN = os.environ.get("SENDLK_TOKEN")
SECRET = os.environ.get("SECRET")

sendlk.initialize(SENDLK_TOKEN, SECRET)

# Imports routes
from src.route import router

# Create the app
app: FastAPI = FastAPI(
    title="FastAPI Mobile Verification",
    version="0.1.0",
)

# App Root
@app.get("/", name="root")
def root():
    return {"message": f"Welcome to Mobile Verification API {app.version}"}

app.include_router(router, prefix="/api")

Okay, It's QA time. Run the server, reload if it's already running.

and go to this URL

localhost:8000/docs

you got your own auto-generated Swagger UI that's the beauty of FastAPI and that's why we create all the schemas too. Cool right?

try it, play it, do whatever you want with it. and here is the repo if you want to take a look at the code.

Peace out!