@cyguin/survey

Post-action micro-surveys. Trigger a 1-3 question modal on specific app events — cancel flow, post-upgrade, onboarding complete — and aggregate responses server-side.

The Deal

Three question types (NPS, multiple choice, short text), a drop-in React modal, a server-side adapter for persistence. That's it.

Install

npm install @cyguin/survey

Requires Next.js App Router and React 18+.

Usage

Client: Trigger a survey

import { showSurvey } from '@cyguin/survey';

const result = await showSurvey('churn-survey', userId);
// result: { surveyId: string, questions: Question[] }

const closeModal = result.modal?.(); // opens the modal
// call closeModal() to dismiss programmatically

Client: useSurveyModal hook

import { useSurveyModal } from '@cyguin/survey';

function MyPage() {
  const { isOpen, open, close, modal } = useSurveyModal(
    'survey-123',
    [
      { id: 'q1', surveyId: 'survey-123', questionText: 'How likely?', questionType: 'nps', questionOrder: 1 },
    ],
    userId,
    { onComplete: (answers) => console.log(answers) }
  );

  return (
    <>
      <button onClick={open}>Take Survey</button>
      {modal}
    </>
  );
}

Server: API routes

Place these in your Next.js app router:

• POST /api/survey/trigger — look up active survey by trigger slug
• GET /api/survey/[surveyId] — fetch survey questions
• POST /api/survey/[surveyId]/responses — submit answers

Adapter: wire up persistence

import { getSurveyAdapter, setSurveyAdapter } from '@cyguin/survey/adapter';

const myAdapter = {
  async findByTrigger(trigger) { /* ... */ },
  async getQuestions(surveyId) { /* ... */ },
  async saveResponses(responses) { /* ... */ },
  async getAggregate(surveyId) { /* ... */ },
};

setSurveyAdapter(myAdapter);

Exports

Export	Type	Description
SurveyModal	Component	Modal UI with all three question types
showSurvey	Function	Client-side trigger + modal opener
useSurveyModal	Hook	Controlled modal state hook
SurveyModalProps	Type	Props for <SurveyModal />
Question	Type	Question shape
Answer	Type	Answer shape
QuestionType	Type	'nps' | 'multiple_choice' | 'short_text'
TriggerResponse	Type	Response from trigger API
SubmitResponse	Type	Response from submit API
SurveyConfig	Type	Client-side config
getSurveyAdapter	Function	Get the current adapter
setSurveyAdapter	Function	Set the adapter

Configuration

interface SurveyConfig {
  autoDismissMs?: number;  // auto-dismiss after N ms (0 = disabled)
  minAnswers?: number;     // min answers to count as completed
  apiBase?: string;        // custom API base URL (defaults to relative)
}

Requirements

• Next.js App Router (>=14)
• React (>=18)

Status

Experimental. API surface may change.

License

MIT