@supertokens-plugins/progressive-profiling-nodejs

SuperTokens Plugin Progressive Profiling

Add progressive profiling functionality to your SuperTokens Node.js backend. This plugin provides APIs and session management for step-by-step user profile collection, allowing you to gather user information gradually through customizable forms and field types.

Installation

npm install @supertokens-plugins/progressive-profiling-nodejs

Quick Start

Backend Configuration

Initialize the plugin in your SuperTokens backend configuration:

import SuperTokens from "supertokens-node";
import ProgressiveProfilingPlugin from "@supertokens-plugins/progressive-profiling-nodejs";

SuperTokens.init({
  appInfo: {
    // your app info
  },
  recipeList: [
    // your recipes (Session recipe is required)
  ],
  experimental: {
    plugins: [
      ProgressiveProfilingPlugin.init({
        sections: [
          {
            id: "basic-info",
            label: "Basic Information",
            description: "Tell us about yourself",
            fields: [
              {
                id: "firstName",
                label: "First Name",
                type: "string",
                required: true,
                placeholder: "Enter your first name",
              },
              {
                id: "lastName",
                label: "Last Name",
                type: "string",
                required: true,
                placeholder: "Enter your last name",
              },
              {
                id: "company",
                label: "Company",
                type: "string",
                required: false,
                placeholder: "Enter your company name",
              },
            ],
          },
          {
            id: "preferences",
            label: "Preferences",
            description: "Customize your experience",
            fields: [
              {
                id: "notifications",
                label: "Email Notifications",
                type: "boolean",
                required: false,
                defaultValue: true,
              },
              {
                id: "theme",
                label: "Preferred Theme",
                type: "select",
                required: false,
                options: [
                  { value: "light", label: "Light" },
                  { value: "dark", label: "Dark" },
                  { value: "auto", label: "Auto" },
                ],
                defaultValue: "auto",
              },
            ],
          },
        ],
      }),
    ],
  },
});

[!IMPORTANT]
You also have to install and configure the frontend plugin for the complete progressive profiling experience.

API Endpoints

The plugin automatically exposes these protected endpoints:

Get Profile Sections

• GET /plugin/supertokens-plugin-progressive-profiling/sections
• Authentication: Session required
• Response:

  {
    "status": "OK",
    "sections": [
      {
        "id": "basic-info",
        "label": "Basic Information",
        "description": "Tell us about yourself",
        "completed": false,
        "fields": [
          {
            "id": "firstName",
            "label": "First Name",
            "type": "string",
            "required": true,
            "placeholder": "Enter your first name"
          }
        ]
      }
    ]
  }
  

Get Profile Data

• GET /plugin/supertokens-plugin-progressive-profiling/profile
• Authentication: Session required
• Response:

  {
    "status": "OK",
    "data": [
      {
        "sectionId": "basic-info",
        "fieldId": "firstName",
        "value": "John"
      },
      {
        "sectionId": "basic-info",
        "fieldId": "lastName",
        "value": "Doe"
      }
    ]
  }
  

Update Profile Data

• POST /plugin/supertokens-plugin-progressive-profiling/profile
• Authentication: Session required
• Body:

  {
    "data": [
      {
        "sectionId": "basic-info",
        "fieldId": "firstName",
        "value": "John"
      },
      {
        "sectionId": "basic-info",
        "fieldId": "lastName",
        "value": "Doe"
      }
    ]
  }
  

• Success Response:

  {
    "status": "OK"
  }
  

• Validation Error Response:

  {
    "status": "INVALID_FIELDS",
    "errors": [
      {
        "id": "firstName",
        "error": "The \"First Name\" field is required"
      }
    ]
  }
  

Configuration Options

Option	Type	Default	Description
sections	FormSection[]	[]	Array of form sections with fields to collect

Form Section Structure

type FormSection = {
  id: string; // Unique identifier for the section
  label: string; // Display label for the section
  description?: string; // Optional description text
  fields: FormField[]; // Array of fields in this section
};

Form Field Structure

type FormField = {
  id: string; // Unique identifier for the field
  label: string; // Display label for the field
  type: FormFieldType; // Field input type (see supported types below)
  required?: boolean; // Whether the field is required (default: false)
  defaultValue?: FormFieldValue; // Default value for the field
  placeholder?: string; // Placeholder text for input
  description?: string; // Optional description text
  options?: SelectOption[]; // Options for select/multiselect fields
};

Supported Field Types

The plugin supports various field types for flexible form creation:

Field Type	Description	Value Type
string	Single-line text input	string
text	Multi-line text area	string
number	Numeric input	number
boolean	Checkbox input	boolean
toggle	Toggle switch	boolean
email	Email input with validation	string
phone	Phone number input	string
date	Date picker	string (ISO date format)
select	Dropdown selection	string
multiselect	Multiple selection dropdown	string[]
password	Password input	string
url	URL input with validation	string
image-url	Image URL input with preview	string

Plugin Functions

registerSections

Register additional form sections programmatically:

import { registerSections } from "@supertokens-plugins/progressive-profiling-nodejs";

registerSections({
  storageHandlerId: "custom-storage",
  sections: [
    {
      id: "advanced-settings",
      label: "Advanced Settings",
      fields: [
        {
          id: "apiKey",
          label: "API Key",
          type: "password",
          required: true,
        },
      ],
    },
  ],
  set: async (data, session, userContext) => {
    // Custom storage logic for saving profile data
    const userId = session.getUserId(userContext);
    await customDatabase.saveUserProfile(userId, data);
  },
  get: async (session, userContext) => {
    // Custom storage logic for retrieving profile data
    const userId = session.getUserId(userContext);
    return await customDatabase.getUserProfile(userId);
  },
});

getSectionValues

Get profile data for a the session user:

import { getSectionValues } from "@supertokens-plugins/progressive-profiling-nodejs";

// In your API handler
const profileData = await getSectionValues({
  session,
  userContext,
});

console.log("User profile:", profileData);

setSectionValues

Update profile data for a specific user:

import { setSectionValues } from "@supertokens-plugins/progressive-profiling-nodejs";

// In your API handler
const result = await setSectionValues({
  session,
  data: [
    {
      sectionId: "basic-info",
      fieldId: "firstName",
      value: "John",
    },
  ],
  userContext,
});

if (result.status === "INVALID_FIELDS") {
  console.error("Validation errors:", result.errors);
}

getAllSections

Get all registered sections:

import { getAllSections } from "@supertokens-plugins/progressive-profiling-nodejs";

const sections = await ProgressiveProfilingPlugin.getAllSections({
  session,
  userContext,
});

console.log("Available sections:", sections);

registerGlobalClaimValidatorOverride

Register function to filter global claim validators in all endpoints

import { registerGlobalClaimValidatorOverride } from "@supertokens-plugins/progressive-profiling-nodejs";
import { SessionClaimValidator } from "supertokens-node/recipe/session";

registerGlobalClaimValidatorOverride((globalValidators: SessionClaimValidators[]) => {
  // Filter the validators.
  return globalValidators;
});

getFilterGlobalClaimValidatorsFn

Get the registered function to filter global claim validators in all endpoints

import { getFilterGlobalClaimValidatorsFn } from "@supertokens-plugins/progressive-profiling-nodejs";

const filterFn = getFilterGlobalClaimValidatorsFn();
if (filterFn !== undefined) {
  // Do something with the function.
}

Custom Storage Handlers

By default, the user profile data is handled by the user metadata through the defaultStorageHandlerSetFields and defaultStorageHandlerGetFields methods. These are used whenever sections are added through the plugin config. These methods can also be overriden in order to make use of your own storage system (database, files, third-parties, etc).

You can also implement custom storage logic for different sections:

import { registerSections } from "@supertokens-plugins/progressive-profiling-nodejs";

// Example: Store user preferences in a separate database
registerSections({
  storageHandlerId: "preferences-db",
  sections: [
    {
      id: "user-preferences",
      label: "User Preferences",
      fields: [
        { id: "theme", label: "Theme", type: "select", options: [...] },
        { id: "language", label: "Language", type: "select", options: [...] },
      ],
    },
  ],
  set: async (data, session, userContext) => {
    const userId = session.getUserId(userContext);
    const preferences = {};

    for (const item of data) {
      preferences[item.fieldId] = item.value;
    }

    await preferencesDatabase.updateUserPreferences(userId, preferences);
  },
  get: async (session, userContext) => {
    const userId = session.getUserId(userContext);
    const preferences = await preferencesDatabase.getUserPreferences(userId);

    return Object.entries(preferences).map(([fieldId, value]) => ({
      sectionId: "user-preferences",
      fieldId,
      value,
    }));
  },
});

Validation

The plugin provides built-in validation for form fields:

Built-in Validation Rules

• Required Fields: Automatically validates that required fields are not empty
• Field Type Validation: Ensures values match the expected field type

Custom Validation

You can extend and customise validation by overriding the registerSections implementation method.

Error Handling

By default, the plugin returns the following standardized error responses:

// Missing required field
{
  "status": "INVALID_FIELDS",
  "errors": [
    {
      "id": "firstName",
      "error": "The \"First Name\" field is required" // "First Name" is the label of the field that encountered the error
    }
  ]
}

// Field not found
{
  "status": "INVALID_FIELDS",
  "errors": [
    {
      "id": "unknownField",
      "error": "Field with id \"unknownField\" not found"
    }
  ]
}

// Server errors
{
  "status": "ERROR",
  "message": "Internal server error"
}