UCR Client

UCR is an NPM module that decorates specific HTML forms with tokens from an external API for CSRF requests and handles success and error messages from our User Contacts Form.

Installation and Use

npm i --save @rsc/ucr-client

To call this, simply require the module, and initialize it:

import tokenate from "@rsc/ucr-client";

document.addEventListener("DOMContentLoaded", () => {
  tokenate(
    "https://form-action-that-requires-tokens",
    "https://uri-to-request-a-token"
  );
});

Tokenator expects to be able to retieve a token via a simple GET request to an endpoint. If successful, return a 200 status with the following response:

{
  "token": "Some unique token that will be checked by the form processor"
}

Tokenator receives that token and inserts it into the form via a hidden input element, e.g.,:

<form action="https://form-action-that-requires-tokens" method="post">
  <input type="text" name="name" placeholder="Your Name" />
  <input type="text" name="email" placeholder="Email" />
  <textarea name="question" placeholder="Your question..."></textarea>

  <button type="submit">Contact Us</button>

  <!-- This is inserted by tokenator! -->
  <input
    type="hidden"
    name="token"
    value="Some unique token that will be checked by the form processor"
  />
</form>

Messages

The UCR client automatically inserts error and success messages to your forms provided an appropriate URL Query parameter was provided by the redirect.

URL: /?success=Thank%20you%20for%20submitting.

<form action="https://form-action-that-requires-tokens" method="post">
  <!-- Inserted by the UCR client -->
  <div
    style="padding: 1rem;
  background: green;
  color: white;
  border-radius: 3px;"
  >
    Thank you for submitting.
  </div>

  <input type="text" name="name" placeholder="Your Name" />
  <input type="text" name="email" placeholder="Email" />
  <textarea name="question" placeholder="Your question..."></textarea>

  <button type="submit">Contact Us</button>

  <!-- This is inserted by the UCR client -->
  <input
    type="hidden"
    name="token"
    value="Some unique token that will be checked by the form processor"
  />
</form>

The same is true for error messages. Formulate the URL like:

?success      -> Default success message: Thank you. We have received your submission.
?success=<custom>
?error        -> Default error message: Unknown error.
?error=<custom>

Options

You can pass in an optional argument to control the display of messages:

tokenate(
  "https://form-action-that-requires-tokens",
  "https://uri-to-request-a-token",
  {
    successMessage: "custom-success-message-class",
    errorMessage: "custom-error-message-class"
  }
);

Note: if you supply these options, we will not insert inline styles with the error and success messages.

Testing

Testing is accomplished with Jest and jsdom

cd npm-tokenator
npm install
npm run test