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:

Name	Type	Description	Default
iamIdentifier	String	The current user's unique identifier	[required]
sessionClearHandler	Function	A function responsible for clearing the server-only cookie	[required]
sessionPersistHandler	Function	- A function responsible for creating the server-only cookie; it is given the iamIdentifier as parameter - The signature encourages the return of a server timestamp	[required]
lastCodeIdentifier?	String	[retrieved from server-only cookie] the last code's iamIdentifier	undefined
lastCodeSendAt?	String, Number	[retrieved from server-only cookie] when the last code was sent; it will be parsed by the Javascript Date class. If the input is unparsable, the hook will throw InvalidLastCodeSentAtError	undefined
callOnMount?	Boolean	Whether to call the worker on component mount	false
cooldownPeriod?	Number	The cooldown period in seconds	300 (5 minutes)
buttonPropsActiveLabel?	String	The button's label when a new code is available	"Send me a new code"
buttonPropsLoadingPropName?	String	[Custom component support] specify the loading boolean property name on a custom button component	"loading"
debugStatements?	Boolean	Whether to log debug statements (requires development mode)	false

Properties

The hook returns an object with the following properties:

Name	Type	Description
sendCode	Function	The function responsible for calling the worker and updating the internal state
reset	Function	Will reset the hook to a "READY" state; this same function is called once the cooldown has expired
status	String	The current status of the hook; it can be one of the following: "READY", "COOLDOWN", "SENDING", "RESTORING"
buttonProps	Object	The props that should be passed to the button component; affected by buttonPropsActiveLabel, buttonPropsLoadingPropName

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