npm package: @happypanda-ai/sdk
Description: HappyPanda SDK - User feedback, onboarding, and analytics for TypeScript projects
Author: HappyPanda
Latest version: 1.2.0

# @happypanda-ai/sdk

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

## Installation

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

## Quick Start

```typescript
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: 'john@example.com',
  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

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

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

### User Identification

```typescript
// 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

```typescript
// 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

```typescript
// 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

```typescript
// 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

```typescript
// 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:

```tsx
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:

```tsx
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:

```typescript
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

```typescript
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