@happypanda-ai/sdk

TypeScript SDK for HappyPanda - User feedback, onboarding, and analytics.

Installation

npm install @happypanda-ai/sdk
# or
pnpm add @happypanda-ai/sdk
# or
yarn add @happypanda-ai/sdk

Quick Start

import { HappyPandaAPI } from '@happypanda-ai/sdk';

// Create an API instance
const api = new HappyPandaAPI('your-project-id');

// Identify a user
await api.identify({
  userId: 'user_123',
  email: '[email protected]',
  name: 'John Doe',
  properties: {
    plan: 'pro',
    company: 'Acme Inc',
  },
});

// Track events
await api.track('feature_used', { feature: 'export' });

// Track conversions
await api.trackConversion('trial_to_paid', {
  plan: 'pro',
  mrr: 49,
  currency: 'USD',
}, 'user_123');

// Complete onboarding steps
await api.completeStep('user_123', 'create_first_project');

API Reference

Constructor

const api = new HappyPandaAPI(projectId: string, baseUrl?: string);

• projectId - Your HappyPanda project ID (required)
• baseUrl - Custom API URL (optional, defaults to production)

User Identification

// Identify a user
await api.identify({
  userId: string,           // Required
  email?: string,           // For emails
  name?: string,            // Display name
  avatarUrl?: string,       // Avatar URL
  properties?: object,      // Custom properties
});

// Enroll in welcome emails
await api.enrollWelcomeEmails({
  userId: string,
  email: string,
  firstName?: string,
  lastName?: string,
});

Event Tracking

// Track custom events
await api.track(eventName: string, properties?: object, userId?: string);

// Track conversions
await api.trackConversion(conversionType: string, properties?: object, userId?: string);

Onboarding Checklist

// Get checklist config
const config = await api.getOnboarding(userId: string);

// Complete a step
await api.completeStep(userId: string, stepId: string);

// Skip a step
await api.skipStep(userId: string, stepId: string);

// Dismiss the checklist
await api.dismissOnboarding(userId: string);

Changelog

// Get changelog entries
const { entries, unreadCount } = await api.getChangelog(userId?: string, limit?: number);

// Mark entries as read
await api.markChangelogRead(userId: string, entryIds: string[]);

Feedback

// Submit feedback
await api.submitFeedback({
  message: 'Great product!',
  rating: 5,
  metadata: {
    browser: 'Chrome',
    url: 'https://example.com',
    // ...
  },
});

Widget Components (React/Preact)

Import UI components for embedding in your app:

import { HappyPandaAPI } from '@happypanda-ai/sdk';
import {
  ChecklistWidget,
  ChangelogLauncher,
  useChecklist,
  useChangelog,
} from '@happypanda-ai/sdk/widget';

const api = new HappyPandaAPI('your-project-id');

function App() {
  const userId = 'user_123';

  return (
    <div>
      {/* Onboarding checklist - place anywhere */}
      <Sidebar>
        <ChecklistWidget api={api} userId={userId} />
      </Sidebar>

      {/* Changelog button with dropdown */}
      <Header>
        <ChangelogLauncher api={api} userId={userId} />
      </Header>
    </div>
  );
}

Hooks

Use hooks for custom UI:

import { useChecklist, useChangelog } from '@happypanda-ai/sdk/widget';

function CustomOnboarding({ api, userId }) {
  const {
    config,
    steps,
    progress,
    isLoading,
    completeStep,
    skipStep,
    dismiss,
  } = useChecklist(api, userId);

  if (isLoading) return <div>Loading...</div>;
  if (!config) return null;

  return (
    <div>
      <h2>{config.name}</h2>
      {steps.map((step) => (
        <div key={step.id}>
          <span>{step.title}</span>
          <button onClick={() => completeStep(step.id)}>Complete</button>
        </div>
      ))}
    </div>
  );
}

Available Components

| Component | Description | |-----------|-------------| | ChecklistWidget | Full checklist with launcher and panel | | ChecklistLauncher | Floating button that opens checklist | | ChangelogLauncher | Button with unread badge and dropdown |

Available Hooks

| Hook | Description | |------|-------------| | useChecklist(api, userId) | Manage checklist state and actions | | useChangelog(api, userId?) | Manage changelog state and actions |

TypeScript

All types are exported:

import type {
  // API Response types
  IdentifyResponse,
  EnrollResult,
  FeedbackResponse,

  // Config types
  WidgetConfig,
  OnboardingConfig,
  OnboardingStep,
  OnboardingProgress,

  // Data types
  ChangelogEntry,
  Survey,
  SubmissionData,
} from '@happypanda-ai/sdk';

Error Handling

import { HappyPandaAPI, APIError, isNetworkError, getErrorMessage } from '@happypanda-ai/sdk';

const api = new HappyPandaAPI('project_id');

try {
  await api.identify({ userId: 'user_123' });
} catch (error) {
  if (isNetworkError(error)) {
    console.log('Network error - retry later');
  } else {
    console.log('Error:', getErrorMessage(error));
  }
}

Browser Support

• Chrome 60+
• Firefox 55+
• Safari 11+
• Edge 79+

License

MIT