@goldenhippo/gh-surveys

Golden Hippo Surveys

Table of Contents

• Golden Hippo Surveys
  • Table of Contents
  • Installation
  • Usage
    • SurveyAPI
      • SurveyAPI Methods
      • SurveyAPI Usage
    • SurveyResponse
      • Question Types
      • Answers

Installation

npm i @goldenhippo/gh-surveys

This package requires that you have an instance of the GH Survey API deployed with a publicly accessible URL.

Usage

SurveyAPI

Import the SurveyAPI class from the package and instantiate it with a connection string to a deployed API. The connection string should be in the format of https://surveyapi.herokuapp.com (or whatever the deployed API URL is).

Note: There should be no slash at the end of the URL.

import { SurveyAPI } from "@goldenhippo/gh-surveys";

const surveyAPI = new SurveyAPI(
  "https://surveyapi.herokuapp.com"
);

SurveyAPI Methods

The SurveyAPI class has the following methods:

• retrieve(sessionId: string) - Retrieves all responses for a given session ID. Returns a Promise that resolves to an array of SurveyRetrievalResponse objects.
• ensureTableExists(create: boolean = false) - Confirms that the survey_responses table exists in the database. If it does not exist, the create parameter can be passed to create the table. Returns a Promise that resolves to a boolean indicating whether the table exists. This process should only be run on application startup because it is an expensive operation.
• submitToDB(surveyResponse: SurveyResponse) - Submits a SurveyResponse object to the database. Returns a Promise that resolves to a SurveySubmitResponse object.

SurveyAPI Usage

import { SurveyAPI } from "@goldenhippo/gh-surveys";

const surveyAPI = new SurveyConnection(
  "https://surveyapi.herokuapp.com"
);

const responses = surveyAPI.retrieve("1234")
  .then((sessionResponses) => {
      console.log(sessionResponses);
      //Find the age response
      const ageResponse = sessionResponses.find(response => response instanceof SurveyResponse.Age)
      if(ageResponse) {
      const ageSelection = ageResponse.answer
      //Do something based on the answer which will be one of the enum options
    }
  })

const tableExists = await surveyAPI.ensureTableExists(); // Validate that table exists, but do not create it if it does not.
console.log(tableExists);

const tableExistsWithCreate = await surveyAPI.ensureTableExists(true); // Validate that table exists, and create it if it does not.
console.log(tableExistsWithCreate);

SurveyResponse

The SurveyResponse class is an abstract class that should be extended to create a response for a specific survey question type. The created object can then be submitted to the database using the SurveyAPI.submitToDB method and returns a promise that resolves to a SurveySubmitResponse object.

The response object has the following structure:

{
  success: boolean,
  response: {
    answer: string,
    sessionId: string,
    questionType: string
  } | null
}

import { SurveyAPI, SurveyResponse } from "@goldenhippo/gh-surveys";

const surveyAPI = new SurveyAPI(
  "https://surveyapi.herokuapp.com"
);

const ageResponse = new SurveyResponse.Age({
  question: "How old are you?",
  rawAnswer: "21",
  answer: "AGE_18_24",
  sessionId: "1234",
});
const ageSubmission = apiConnection.submitToDB(ageResponse)
.then((response) => {
  console.log(response);
  /*
   {
      success: true,
      response: {
        answer: "AGE_18_24",
        sessionId: "1234",
        questionType: "AGE"
      }
   }
   */
}

Question Types

The SurveyResponse class allows you to create responses for the following question types:

• Age
• Gender
• DigestiveIssue
• IssueAge
• BowelMovementWeekly
• SolutionDifficulty

Note: To view the available questions and answers, you can access the configuration file from your API URL at /config. For example, https://yourapi.herokuapp.com/config.

Answers

Each of the question types has a set of possible answers. The answers are defined as static properties on the class. For example, the SurveyResponse.Gender class has the following possible answers:

• MALE
• FEMALE
• NON_BINARY
• DECLINE_TO_ANSWER

Note: To view the available questions and answers, you can access the configuration file from your API URL at /config. For example, https://yourapi.herokuapp.com/config.