wappi-fe

wappi frontend

What is wappi frontend you ask?

What is wappi??

The open-source API framework that's your secret weapon for coding faster and smarter. It's here to turbocharge your development, documentation, testing, and typing. Ready for a game-changer? Check out Wappi and make coding magic happen.
You can find wappi here.

wappi-fe

wappi-fe is so you can get the awesomeness of the wappi api framework on the frontend. Including all the types being automatically there during development.

Quick start guide:

1. Create a wappi server locally. Follow the wappi guides here.
2. Install wappi-fe

npm i -S wappi-fe

3. Update your tsconfig.json file

{
  "compilerOptions": {
    "paths": {
      "@wappiTypes": [
        "./src/wappiTypes.ts"
      ]
    }
  }
}

This is the path that you are importing your wappiTypes to from your local wappi .env file.

FRONTEND_PROJECT_PATHS=["/absolute/path/to/frontend/wappiTypes/file.ts"]    
# Example:
FRONTEND_PROJECT_PATHS=["/Users/Smithy/ProjectAlpha/src/wappiTypes.ts"]

4. Create your first endpoint call

const response = async () => (request({
  apiUrl: 'https://api.domain.com', // your base API domain
  authRedirectPath: '/login', // The path you want the user to be redirected to if they don't have an auth token
}, {
  name: 'Get Some Information', // This will create a url in your network tab of: GetUserInformation
  query: 'NameSpace_FunctionName_1_0_0',
  data: {
    // ... body object
  },
  authRequired: true,
}))

Query Structure

interface request {
  name: string,
  query: string // The endpoint name. 
  data: any // Strict type of endpoint body
  results?: {
    name: string;
    include?: Array<{ name: string; key: string }>
    exclude?: Array<{ key: string }>
  }
  authRequired?: boolean
  resultsOnly?: boolean
  errorCallback?: (x: any) => void
  successCallback?: (x: any) => void
  logResults?: boolean
  logFullResponse?: boolean
}

name: string required

This is the specific name of the information you want returned. As multiple requests can be made, this breaks them up.
tip: Add a dynamic ID into the name for easy observability Get info for ${user.name}

authRequired: boolean optionally required - if necessary

true or false. If true, it will get the auth token that is automatically set.
See the Authentication section.

query: string required

This is the name of the function on the server.
This function will be the one called.

data: inherits endpoints Body types optional

This is an object of the all the data required for the function.
Such as all the user data to add a user.
This data is specific to the function and should be typed in the NameSpace_FunctionName_1_0_0__Body type.
Typescript should show an error of missing or mis-typed types.

results: optional

This determines what results you receive.
If you leave it as a blank obj or don't include it, it will return everything the function returns.
Otherwise you can specify what to include or exclude.

• name : optional The name you want the results to return as. Default = results
• include : optional An array of objects, with
  • name : required This is the name that you want it to be called. So you can rename it to match your frontend app.
  • key : required This is the backend key of the object that you want to include
• exclude : optional An array of objects, with
  • key : required This is the backend key of the object that you want to exclude from the results. This allows the returned object to be clean to what you need, to help with clarity.

Logic for including and excluding is as follows:
If nothing is defined in include, then everything will be included.
If nothing is defined in exclude, then nothing will be excluded.
If Nothing is defined in include, but something is defined in exclude, everything defined in exclude will be removed.
If a key is defined in include and in exclude, then it will be included

Why do this^?
Usually the processing of the endpoint is faster than the Latency of sending and receiving the data. So you might have an endpoint that can return a lot of data, but you only want 1 piece of it. So instead of creating a new backend function, you can just define what you want returned and get the same result.

successCallback: optional

On success this will be called with the body passed through as the param

successCallback: (response) => {
  // Logic to do something with the response.
  console.log('response', response)
}

successCallback: optional

On success this will be called with the body passed through as the param

errorCallback: (errorResponse) => {
  // Logic to do something with the error.
  console.error('errorResponse', errorResponse)
}

logResults: optional

This will console.log out the results or the name of the results you requested.
Handy if you want to inspec the results object.

logFullResponse: optional

This will console.log out the full wappi server response from the endpoint.
Handy if you want to check your wappi server response.

Best practices:

Create a config file:

Create a config file somewhere in your code base so it's reusable.
Like this:

import { WappiConfig } from 'wappi-fe/types';

export const WAPPI_CONFIG: WappiConfig = {
  apiUrl: 'https://api.domain.com', // your base API domain
  authRedirectPath: '/login', // The path you want the user to be redirected to if they don't have an auth token
};

Then you can call your endpoint like this:

const response = async () => (request(WAPPI_CONFIG, {
  name: 'Get Some Information',
  query: 'NameSpace_FunctionName_1_0_0',
  data: {},
}))

Authentication

All taken care of with wappi and wappi-fe!!
To generate authentication with wappi, you need to add code to your wappi server endpoint called Core_Login_1_0_0 or any subsequent versions.
When this endpoint is called, wappi-fe will set a auth token to localStorage of the browser / device called: wappiAuthToken.
This Auth Token will be used as an encrypted authentication between your frontend and backend.
If the token is expired, or incorrect. Then endpoint will return: success: false

Help desk = Ai!

There is a GPT called wappi.
You can access it here -> wappi ai help.
Got any questions, it should be able to help you with it.

Improvements

This is used in a lot of projects and we are always eager to improve wappi!
So if you have any suggestions on how to make it easier, let us know. We want to know!