@dmgincs/utils v0.3.12-rc2

DamageInc Utils

Damage Inc frontend Utils

Installation

Install the package in your project directory with:

// with yarn
yarn add @dmgincs/utils

Authentication

In order to setup forum authentication a few things are required.

Please note that you need the following envorionement variables for this to work properly:

NEXT_PUBLIC_AUTH_CLIENT_ID = acp client id
NEXT_PUBLIC_COOKIE_PREFIX  = this will be appended to every cookie
NEXT_PUBLIC_FORUM_URL      = the url of the forums to use

User Provider

The first step to allow the user logic into the app, is surrounding the app with the User Context like

_app.tsx

import { UserProvider } from "@dmgincs/utils";

const Demo: React.FC = () => {
  return (
    <UserProvider>
      // The rest of the page
      <Component ... />
    </UserProvider>
  )
}

The User Provider handles the logic for logging a person back in when they have valid cookies. The logic for logging someone in for the first time is not present and will have to be done manually for now.

Logging in

You can generate a login url by calling the following function:

import { buildLoginURL } from "@dmgincs/utils";
import { useRouter } from "next/router";

const router = useRouter();

const login = () => {
  // Get the actual login url
  const url = buildLoginURL();
  if (url) {
    // Redirect to that url, the router is not mandatory, but it is nicer for the browser since this will append to the history.
    router.push(url);
  }
};

Getting the current user

If you want to get the logged in user at any time, you can run the following code.

import { UserContext, useUserContext } from "@dmgincs/utils";

const Demo: React.FC = () => {
  // The type cast is required for typescript to know what the user object will be.

  // The user will be undefined if not logged in, and be an object of type IUser when logged in.
  const { user } = useUserContext();
};

Api Caller

Next to login logic, this package also contains logic for calling the api.

Please note that you need the following envorionement variables for this to work properly:

NEXT_PUBLIC_API_BASE_URL = the root of the api, this will be appended before every request

Basic requests

import { handleRequest } from "@dmgincs/utils";

// IResponse can be of any interface, and will be used to type the response.
async function fetch(): Promise<IResponse[]> {
    return await handleRequest<IResponse[]>({url: '/demo'});
  }
}

Authorization

When calling the api you have two different options of what authorization you want to use. The first one is using an api key, and the second is using a Synful-Key (User Bearer token).

Making a serverside request

When making request server side, you usually need an api key for the authorization.

In order to make this work you can use the default request handler, but just append headers containing an api key. To generate these headers you can do the following:

import { handleRequest, getApiKeyHeaders } from "@dmgincs/utils";

async function get(): Promise<any> {
  return await handleRequest<any>({
    url: "url",
    customHeaders: getApiKeyHeaders("apikey"),
  });
}

Making a user authenticated request

Sometimes it's not possible to make the request on the server, so we have Synful authentication in place. This basically uses the users' authentication token to request an endpoint. Because we use this quite often, you can use this a bit easier than the api handler.

import { handleAuthenticatedRequest } from "@dmgincs/utils";

async function get(): Promise<any> {
  return await handleAuthenticatedRequest<any>({ url: "url" });
}

This method will automatically send a request with a Synful-Key header. Therefore you don't have to do this yourself anymore. Do note, you cannot use this function on the server, because that will throw an exception, due to cookies not being available on the server.

Api Requests using a hook

Whenever you want to load data on the client's side if the page loads, you might want to use a hook. A hook enabled you declare consts in your code, but those will act as States.

import { useApiRequest } from "@dmgincs/utils";

const [value, setValue] = React.useState("nonono");

const { response, loading, error } = useApiRequest<object>({
  authenticated: true,
  url: "url/to/api/route",
  version: 2,
}, [value]);

The above code is a simple way to use the hook. The arguments passed to the method are the same as the handleRequest methods. The only difference being this method has the option authenticated. The authenticated flag, if enabled, will make an api call using the users' X-Authorization. The second argument allows for a depency array. So in the example, if value were to change by anything else on the page, the loading would be set to true and the response would later be updated after the api has been called again.