@feedhog/js

JavaScript SDK for Feedhog - collect user feedback from any website or application.

Installation

npm install @feedhog/js
# or
pnpm add @feedhog/js
# or
yarn add @feedhog/js

CDN Usage

<script src="https://feedhog.com/sdk.js"></script>
<script>
  const feedhog = new Feedhog({ apiKey: 'fhpk_xxx' });
</script>

Quick Start

import Feedhog from '@feedhog/js';

// Initialize with your public API key
const feedhog = new Feedhog({
  apiKey: 'fhpk_xxx',
  baseUrl: 'https://feedhog.com' // Optional, defaults to production
});

// Identify the current user (optional but recommended)
await feedhog.identify({
  externalId: 'user-123',
  email: '[email protected]',
  name: 'John Doe',
  metadata: { plan: 'pro' }
});

// Submit feedback
const feedback = await feedhog.submit({
  title: 'Add dark mode',
  description: 'Would love a dark theme option',
  type: 'idea' // 'bug' | 'idea' | 'question' | 'other'
});

API Reference

new Feedhog(config)

Create a new Feedhog instance.

const feedhog = new Feedhog({
  apiKey: 'fhpk_xxx',     // Required: Your public API key
  baseUrl: 'https://...'  // Optional: Custom API URL
});

feedhog.identify(user)

Identify the current user. This associates all subsequent feedback and votes with this user.

await feedhog.identify({
  externalId: 'user-123',      // Required: Your system's user ID
  email: '[email protected]',   // Optional
  name: 'John Doe',            // Optional
  avatarUrl: 'https://...',    // Optional
  metadata: { plan: 'pro' }    // Optional: Custom data
});

User identity is persisted in localStorage, so returning users are automatically recognized.

feedhog.submit(input)

Submit new feedback.

const feedback = await feedhog.submit({
  title: 'Feature request',           // Required
  description: 'Detailed description', // Optional
  type: 'idea',                        // Optional: 'bug' | 'idea' | 'question' | 'other'
  metadata: { page: '/settings' }      // Optional: Custom data
});

feedhog.list(options)

List feedback items with optional filters.

const { items, total, page, totalPages } = await feedhog.list({
  status: ['new', 'planned'],  // Filter by status(es)
  type: 'idea',                // Filter by type
  search: 'dark mode',         // Search query
  sortBy: 'votes',             // 'newest' | 'oldest' | 'votes' | 'comments'
  page: 1,                     // Page number
  limit: 20                    // Items per page (max 100)
});

feedhog.get(feedbackId)

Get a single feedback item with full details including comments.

const feedback = await feedhog.get('abc123');
console.log(feedback.comments);
console.log(feedback.userHasVoted);

feedhog.vote(feedbackId)

Toggle vote on a feedback item.

const { voted, voteCount } = await feedhog.vote('abc123');
// voted: true if vote was added, false if removed

feedhog.hasVoted(feedbackId)

Check if the current user has voted on a feedback item.

const { voted, voteCount } = await feedhog.hasVoted('abc123');

feedhog.reset()

Clear the current user and stored data. Use when a user logs out.

feedhog.reset();

feedhog.user

Get the currently identified user.

if (feedhog.user) {
  console.log('Logged in as:', feedhog.user.name);
}

Events

Subscribe to SDK events:

// User identified
feedhog.on('identify', (user) => {
  console.log('User identified:', user);
});

// Feedback submitted
feedhog.on('submit', (feedback) => {
  console.log('Feedback submitted:', feedback.id);
});

// Vote toggled
feedhog.on('vote', ({ feedbackId, result }) => {
  console.log('Vote toggled:', result.voted);
});

// Error occurred
feedhog.on('error', (error) => {
  console.error('SDK error:', error);
});

// User reset
feedhog.on('reset', () => {
  console.log('User logged out');
});

TypeScript

The SDK is fully typed. Import types as needed:

import Feedhog, {
  type FeedbackType,
  type FeedbackStatus,
  type FeedbackListItem,
  type UserIdentity
} from '@feedhog/js';

Error Handling

import Feedhog, { FeedhogApiError } from '@feedhog/js';

try {
  await feedhog.submit({ title: '' });
} catch (error) {
  if (error instanceof FeedhogApiError) {
    console.log('Status:', error.status);
    console.log('Message:', error.message);
    console.log('Field errors:', error.details?.fieldErrors);
  }
}

License

MIT