useSendCode

A React (NextJS-oriented) hook that facilitates operations such as sending one-time codes.

Table of Contents

• useSendCode
  • Table of Contents
  • Features
  • Motivation
    • Caveat
  • Installation
  • Usage
    • Configuration
    • Properties
  • Understanding the hook's behaviour
    • When a user clicks on the CTA
    • When the cooldown is active, but the user refreshes the page
    • When the cooldown period is over
  • TypeScript Support
  • License

Features

• Handle spam-sensitive operations such as one-time codes
• Session tracking through server-only cookie
• Session recovery on reload
• Component (button) props that handle every aspect of the user-facing CTA (label, disabled, loading, etc)

Motivation

Low-cost solution to spam-sensitive operations. This solution omits the use of a cache which might not always be available in early-stage applications.

Caveat

This solution was designed around the ability to retrieve server-only cookies with relative ease, e.g. NextJS' getServerSideProps. A vanilla React application would not be suitable for this solution.

Installation

Install through your package manager of choice (npm, yarn, etc)

npm -i @mzaleski/use-send-code

yarn add @mzaleski/use-send-code

Usage

Example usage with NextJS' getServerSideProps:

import { useSendCode } from '@mzaleski/use-send-code';
import { Button } from 'src/components';

async function worker(iamIdentifier: string): Promise<void> { ... }

function AccountRecoveryPage({ cookiePayload }) {
  const { sendCode, status, buttonProps } = useSendCode(worker, {
    iamIdentifier: 'some-id',
    lastCodeIdentifier: cookiePayload?.iamIdentifier,
    lastCodeSendAt: cookiePayload?.sentAt,
    callOnMount: true,
    cooldownPeriod: 2 * 60,
    buttonPropsActiveLabel: 'Recover my account',
    buttonPropsLoadingPropName: 'isLoading',
    debugStatements: process.env.NODE_ENV === 'development',
    sessionClearHandler: async () => { ... },
    sessionPersistHandler: async (iamIdentifier) => { ... },
  });

  const sendRecoveryCode = async () => {
    const err = await sendCode();
    if (err) {
      // handle error
    }
  };

  return (
    <Button {...buttonProps} onClick={sendRecoveryCode} />
  );
}

export async function getServerSideProps(context) {
  /** retrieve server-only cookie and deserialise it */
  const cookiePayload = {...};

  return {
    props: {
      cookiePayload,
    },
  };
}

Configuration

The hook's configuration is done through the opts object which has the following properties:

Properties

The hook returns an object with the following properties:

Understanding the hook's behaviour

When a user clicks on the CTA

The hook will...

1. Call your worker and perform the operation
2. Call sessionPersistHandler with the given iamIdentifier to create a server-only cookie
3. Update its internal state as well the button's props in order to reflect the change

When the cooldown is active, but the user refreshes the page

The hook will restore the previous state by looking at lastCodeIdentifier and lastCodeSendAt from the server-only cookie.

When the cooldown period is over

The hook will...

1. Call sessionClearHandler to clear the server-only cookie
2. Update its internal state as well the button's props in order to reflect the change

TypeScript Support

You will find a collection of typings bundled with the package.

License

MIT License (c) 2022 Maximilien Zaleski